diff --git a/crates/squabble-core/data/first-line-rules.tsv b/crates/squabble-core/data/first-line-rules.tsv index 1507778..d7876c2 100644 --- a/crates/squabble-core/data/first-line-rules.tsv +++ b/crates/squabble-core/data/first-line-rules.tsv @@ -38,6 +38,7 @@ SQ-RUN-02 ACT a PR is blocked with required checks green under a strict ruleset SQ-RUN-03 ACT a step fails on a transient host or API error: gh: HTTP 5xx, gh: Server Error (HTTP 5xx), a git remote returning 5xx, or Could not resolve host or Failed to connect to a host name that contains a dot Re-run the failed job once, only if that commit is still the head The re-run passes It fails twice on the same commit, the status is 401 or 403 (a token problem: SQ-OWN-09, or a rate limit: SQ-RUN-01), or the host name has no dot (a service container or localhost is a configuration error a re-run cannot fix) SQ-RUN-04 ACT gitleaks fails with fatal: ambiguous argument ^..: unknown revision or path not in the working tree, because a shallow checkout lacks the range base commit; trufflehog reports commits: 0 for the same range Re-run the failed job once, only if that commit is still the head The re-run passes and the scan covers more than 0 commits It fails twice on the same commit: refer with the suggestion fetch-depth: 0 on the scan checkout SQ-RUN-05 REFER a step fails with Could not resolve host or Failed to connect to a host name that has no dot (a service container, localhost) or no name at all Refer to Hypatia with the log line and the step: this is a configuration error (the service is not running or is named wrongly), so a re-run cannot fix it (owner) Always a referral: the name that does resolve in the workflow is Hypatia's to confirm +SQ-RUN-06 ACT a gate fails closed because it could not read GitHub state: could not read branch rulesets (nothing inspected), could not read the workflow catalogue (enablement is UNKNOWN, not off), or the called workflow could not be read at a SHA (offline with no cache entry, or the API refused) Re-run the failed job once after the Actions token budget resets, only if that commit is still the head; never edit the gate, its baseline or its allowlist to pass The re-run reads the state and the gate passes or fails on its real findings It fails twice on the same commit with the same unread state (a missing permission, not a budget: owner), or the log has a DROPPED CLOSURE line with no could-not-be-read line (a real drop) SQ-CODE-01 FIX a Rust readiness or integration test cannot find its binary under target/debug/build Use PathBuf::from(env!("CARGO_BIN_EXE_")); a code fix, first-line only when the code-fix guard passes cargo test --test readiness passes The fix would hit the code-fix unsafe list, the code is vendored or third-party, or the check does not pass on the PR head SQ-CODE-02 FIX Validate Hypatia Baseline fails on new code_safety findings Fix the code behind the finding; never touch .hypatia-baseline.json The baseline job passes with the baseline file unchanged The fix would hit the code-fix unsafe list, the code is vendored or third-party, or the check does not pass on the PR head SQ-CODE-03 FIX Sonar S7688, S7679 or S131 in shell scripts Make the mechanical edit: for S7688 rewrite [ ] to [[ ]] only in files with a bash shebang (never /bin/sh or POSIX scripts); for S131 add a no-op default case *) ;;; decline S1192 in test files, where repetition is a convention bash -n, shellcheck and the repository's shell tests pass An S7688 test uses -a or -o or relies on word splitting, the fix would hit the code-fix unsafe list, the code is vendored or third-party, or the check does not pass on the PR head diff --git a/crates/squabble-core/src/rules.rs b/crates/squabble-core/src/rules.rs index bd52e81..5b809fa 100644 --- a/crates/squabble-core/src/rules.rs +++ b/crates/squabble-core/src/rules.rs @@ -51,7 +51,7 @@ use RuleClass::{Act, Fix, Noise, Owner, Refer}; /// here. const CATALOGUE_TSV: &str = include_str!("../data/first-line-rules.tsv"); -/// The 46 catalogue rows, in ADR 0004 order. +/// The 47 catalogue rows, in ADR 0004 order. /// /// The data file ships inside the crate, so a malformed row is a defect in /// this crate that a caller cannot repair. The catalogue never loads short: @@ -267,6 +267,17 @@ static LOG_MATCHERS: &[LogMatcher] = &[ ("SQ-OWN-15", |c| { c.has("Not authorized or organization not found") }), + // Last of the actionable rules, after every owner-only one: a re-run never + // outranks an owner condition in the same log (a bad token, SQ-OWN-09, + // that also leaves the gate unable to read). The gate failed closed because + // it could not read GitHub state. Only the unread lines match: a DROPPED + // CLOSURE line alone is a real drop, and the ones that follow an unread + // callee are a consequence of it. + ("SQ-RUN-06", |c| { + c.has("could not read branch rulesets") + || c.has("could not read the workflow catalogue") + || c.has("(offline with no cache entry, or the API refused)") + }), ("SQ-NOI-01", |c| c.has("deed=cancelled")), ("SQ-NOI-02", |c| { c.has("couldn't find remote ref refs/pull/") @@ -566,6 +577,11 @@ pub fn is_code_fix(rule: &Rule) -> bool { rule.class == RuleClass::Fix && rule.id.starts_with("SQ-CODE-") } +/// Act rules whose catalogue row sends a second failure to the owner, not to +/// Hypatia: the same unread state twice is a missing permission, which only the +/// owner can grant (SQ-RUN-06). +const OWNER_AFTER_RERUN: &[&str] = &["SQ-RUN-06"]; + /// Apply the ADR 0004 guards to a rule. pub fn decide(rule: &Rule, g: &GuardInput) -> Decision { match rule.class { @@ -588,6 +604,9 @@ pub fn decide(rule: &Rule, g: &GuardInput) -> Decision { reason: "attempt limit reached: 2 fix attempts on this head".to_string(), }; } + if OWNER_AFTER_RERUN.contains(&rule.id) && g.reruns_of_job >= 1 { + return Decision::OwnerReport; + } if rule.class == RuleClass::Act && g.reruns_of_job >= 1 { return Decision::Refer { reason: "re-run limit reached: the job was already re-run once".to_string(), @@ -938,17 +957,17 @@ mod tests { #[test] fn shipped_catalogue_file_parses() { let parsed = parse_catalogue(CATALOGUE_TSV).expect("the shipped data file is well formed"); - assert_eq!(parsed.len(), 46); + assert_eq!(parsed.len(), 47); } #[test] fn catalogue_shape() { - assert_eq!(CATALOGUE.len(), 46); + assert_eq!(CATALOGUE.len(), 47); let uniq: HashSet<_> = CATALOGUE.iter().map(|r| r.id).collect(); - assert_eq!(uniq.len(), 46); + assert_eq!(uniq.len(), 47); let n = |c| CATALOGUE.iter().filter(|r| r.class == c).count(); assert_eq!(n(Fix), 20); - assert_eq!(n(Act), 4); + assert_eq!(n(Act), 5); assert_eq!(n(Refer), 3); assert_eq!(n(Owner), 16); assert_eq!(n(Noise), 3); @@ -1005,6 +1024,20 @@ mod tests { ("SQ-RUN-03", "fatal: unable to access 'https://git.sr.ht/x': The requested URL returned error: 503"), ("SQ-RUN-03", "fatal: unable to access 'https://git.sr.ht/x': Could not resolve host: git.sr.ht"), ("SQ-RUN-03", "curl: (7) Failed to connect to github.com port 443 after 21 ms"), + // standards runs 43458638630, 43458639621 and 43459052870 (the + // Actions token budget was spent), read from the job logs. + ( + "SQ-RUN-06", + "##[notice]could not read branch rulesets for metadatastician/standards (API error, rate limit, or missing permission) \u{2014} nothing inspected", + ), + ( + "SQ-RUN-06", + "##[error]could not read the workflow catalogue \u{2014} enablement is UNKNOWN, not off", + ), + ( + "SQ-RUN-06", + "##[error]metadatastician/standards@d55304a01b5260b0511aae0d14ed8b8770b00293: the called workflow .github/workflows/rust-ci-reusable.yml could not be read at d55304a01b5260b0511aae0d14ed8b8770b00293 (offline with no cache entry, or the API refused). An unread callee is NOT a closed closure", + ), ( "SQ-RUN-04", "ERR [git] fatal: ambiguous argument '4190136^..bf33aeb': unknown revision or path not in the working tree.", @@ -1098,6 +1131,30 @@ mod tests { assert_eq!(rule("SQ-RUN-05").unwrap().class, Refer); } + #[test] + fn unreadable_github_state_is_a_rerun_but_a_real_drop_is_not() { + let consequence = "DROPPED CLOSURE \u{2014} the reviewed baseline has a -> b, and this source no longer reaches it."; + // A real drop, with nothing unread, is the gate's own finding. + assert!(ids(consequence, None).is_empty()); + // Unread callee plus the drops that follow it: one re-run, then the owner. + let both = format!( + "the called workflow x.yml could not be read at abc (offline with no cache entry, or the API refused).\n{consequence}" + ); + assert_eq!(ids(&both, None), vec!["SQ-RUN-06"]); + // A git credential prompt is not an unread gate (SQ-REF-06). + let git = "fatal: could not read Username for 'https://github.com'"; + assert!(!ids(git, None).contains(&"SQ-RUN-06")); + assert_eq!(rule("SQ-RUN-06").unwrap().class, Act); + } + + #[test] + fn an_owner_condition_outranks_a_rerun_in_the_same_log() { + let log = "gh: Bad credentials (HTTP 401)\n##[error]could not read the workflow catalogue \u{2014} enablement is UNKNOWN, not off"; + assert_eq!(ids(log, None), vec!["SQ-OWN-09", "SQ-RUN-06"]); + // The caller acts on the first: the owner report, never a re-run. + assert_eq!(rule(ids(log, None)[0]).unwrap().class, Owner); + } + #[test] fn push_refusals_are_told_apart() { // The git form is SQ-OWN-04, the gh API form is SQ-OWN-13; neither claims the other. @@ -1207,6 +1264,35 @@ mod tests { } } + #[test] + fn a_second_unread_state_failure_goes_to_the_owner_not_hypatia() { + let first = GuardInput { + reruns_of_job: 0, + ..on() + }; + let second = GuardInput { + reruns_of_job: 1, + ..on() + }; + let unread = rule("SQ-RUN-06").unwrap(); + assert_eq!(decide(unread, &first), Decision::Apply); + assert_eq!(decide(unread, &second), Decision::OwnerReport); + // Every other Act rule still refers after its one re-run. + let other = rule("SQ-RUN-01").unwrap(); + assert!(matches!(decide(other, &second), Decision::Refer { .. })); + // The kill switch still comes first. + assert!(matches!( + decide( + unread, + &GuardInput { + reruns_of_job: 1, + ..GuardInput::default() + } + ), + Decision::ReportOnly { .. } + )); + } + #[test] fn every_decision_branch() { let g = |a, rr, pr, c| GuardInput { diff --git a/docs/decisions/0004-first-line-rule-catalogue.adoc b/docs/decisions/0004-first-line-rule-catalogue.adoc index c674477..a28853e 100644 --- a/docs/decisions/0004-first-line-rule-catalogue.adoc +++ b/docs/decisions/0004-first-line-rule-catalogue.adoc @@ -190,6 +190,12 @@ holds, or when its check does not pass on the PR head. | (owner) | Always a referral: the name that does resolve in the workflow is Hypatia's to confirm. +| SQ-RUN-06 | ACT +| A gate fails closed because it could not read GitHub state: `could not read branch rulesets for (API error, rate limit, or missing permission) - nothing inspected` (standards run 43458638630), `could not read the workflow catalogue - enablement is UNKNOWN, not off` (standards run 43458639621), or `the called workflow could not be read at (offline with no cache entry, or the API refused)` (standards run 43459052870). All three ran while the Actions token budget was spent. +| Re-run the failed job once after the Actions token budget resets, only if that commit is still the head. Never edit the gate, its baseline or its allowlist to make it pass. +| The re-run reads the state, and the gate then passes or fails on its real findings. +| It fails twice on the same commit with the same unread state (a missing permission, not a budget: report to the owner), or the log has a `DROPPED CLOSURE` line with no could-not-be-read line (a real drop). `DROPPED CLOSURE` lines that follow an unread callee are a consequence of it, not findings. + | SQ-CODE-01 | FIX | A Rust readiness or integration test cannot find its binary (`failed to run …/target/debug/build/…: No such file`). | Use `PathBuf::from(env!("CARGO_BIN_EXE_"))`. @@ -351,6 +357,13 @@ is not `setup-bun`, only SQ-RUN-01 matches. Agreed with the rule reconciliation thread; Hypatia's `api_rate_limit` is advice that defers to SQ-PIN-03, then SQ-RUN-01. +SQ-RUN-06 is last in the table, after every owner-only rule: a re-run never +outranks an owner condition in the same log. A bad token (SQ-OWN-09) that +leaves the gate unable to read gives `SQ-OWN-09, SQ-RUN-06`, and the caller +reports to the owner. A second failure of SQ-RUN-06 on the same commit is an +owner report as well, not a Hypatia referral (`OWNER_AFTER_RERUN` in +`rules.rs`); every other `ACT` rule refers to Hypatia after its one re-run. + === Mapping to Hypatia's `ci_failure_triage` ids (hypatia#1064) Under ADR 0003 Hypatia's triage names the cause and the route; every re-run @@ -392,8 +405,8 @@ base). == Consequences -* 24 rules are first-line (20 `FIX`, 4 `ACT`), 3 are referrals, 16 are - owner-only and 3 are noise; 46 in all. Every rule names its check and its +* 25 rules are first-line (20 `FIX`, 5 `ACT`), 3 are referrals, 16 are + owner-only and 3 are noise; 47 in all. Every rule names its check and its referral condition. * A fix that changes code (`SQ-CODE-nn`) is first-line only when the code-fix guard passes on its diff, so a fix that could weaken a check never runs at