From 12f7fa3a48294b1013052186da7801d1ae43c94c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 09:11:22 +0000 Subject: [PATCH] Add the SQ-LOCK-01 executor: squabble relock Repairs actions.lock records whose ref: repeats their own SHA, in the row's order (highest full-semver tag, else highest semver, else first tag, else the default or only branch that holds the commit); ties and no ref are referrals. Pure core in squabble-core (lockfix), thin CLI in squabble-cli (relock). Changes only the flagged ref: lines and re-checks its own result; a dry run unless --write and the guards say Apply (ESTATE_AUTOFIX); reusable callers are read from the repo's workflows and never rewritten; never claims the rule's check passed (the repo's lock gate on the PR is the check). First proof: its output for ZeroInflatedCounts.jl cicd-suite@0da816c0 is byte-identical to the hand repair in ZeroInflatedCounts.jl#22. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_0136P7Zmiut2nCcbtEx25HAU --- crates/squabble-cli/src/main.rs | 6 +- crates/squabble-cli/src/relock.rs | 224 +++++++++ crates/squabble-core/src/lib.rs | 1 + crates/squabble-core/src/lockfix.rs | 453 ++++++++++++++++++ crates/squabble-core/src/rules.rs | 8 +- .../0004-first-line-rule-catalogue.adoc | 34 ++ 6 files changed, 721 insertions(+), 5 deletions(-) create mode 100644 crates/squabble-cli/src/relock.rs create mode 100644 crates/squabble-core/src/lockfix.rs diff --git a/crates/squabble-cli/src/main.rs b/crates/squabble-cli/src/main.rs index 776ad6e..336dbd7 100644 --- a/crates/squabble-cli/src/main.rs +++ b/crates/squabble-cli/src/main.rs @@ -50,6 +50,7 @@ mod fight; mod inbox; mod lock_verifier; mod phase; +mod relock; mod triage; mod verify; mod zero_job; @@ -83,6 +84,7 @@ fn main() -> ExitCode { Some("verify-satisfied") => verify::run(&args[2..]), Some("board") => board::run(&args[2..]), Some("triage") => triage::run(&args[2..]), + Some("relock") => relock::run(&args[2..]), Some("inbox-sweep") => inbox::run(&args[2..]), Some("--version") | Some("-V") => { println!("squabble {}", env!("CARGO_PKG_VERSION")); @@ -104,6 +106,7 @@ fn main() -> ExitCode { squabble {}\n \ squabble {}\n \ squabble {}\n \ + squabble {}\n \ squabble --version\n\n\ EXIT CODES:\n \ 0 ok · 2 failure · 3 no `required_status_checks` rule on the base branch · 4 chains/zero-job: blocking finding · 5 verify-satisfied: agent items remain · 6 board or inbox-sweep: incomplete\n", @@ -115,7 +118,8 @@ fn main() -> ExitCode { board::USAGE.trim_start_matches("usage: squabble "), inbox::USAGE.trim_start_matches("usage: squabble "), verify::USAGE.trim_start_matches("usage: squabble "), - triage::USAGE.trim_start_matches("usage: squabble ") + triage::USAGE.trim_start_matches("usage: squabble "), + relock::USAGE.trim_start_matches("usage: squabble ") ); ExitCode::from(2) } diff --git a/crates/squabble-cli/src/relock.rs b/crates/squabble-cli/src/relock.rs new file mode 100644 index 0000000..5a155f7 --- /dev/null +++ b/crates/squabble-cli/src/relock.rs @@ -0,0 +1,224 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +//! `squabble relock` — the SQ-LOCK-01 executor (ADR 0004). +//! +//! Repairs the `actions.lock` records whose `ref:` repeats their own SHA. It +//! never touches the network: the evidence (the tags at each SHA, the branches +//! that contain it) comes from a TSV file the caller gathered. It changes +//! nothing unless `--write` is given AND the guards say Apply (the +//! `ESTATE_AUTOFIX` kill switch, the attempt and open-PR limits). It never +//! opens a PR and never claims the rule's check passed: that check is the +//! repository's lock gate, run on the PR. + +use squabble_core::lockfix::{plan_lock_fix, reusable_callers, LockFixPlan, RefEvidence}; +use squabble_core::rules::{decide, rule, Decision, GuardInput}; +use std::collections::BTreeMap; +use std::process::ExitCode; + +pub const USAGE: &str = "usage: squabble relock --lock --evidence (--workflows | --callers ) [--attempts ] [--open-fix-pr] [--write]"; + +#[derive(Default)] +struct Args { + lock: Option, + evidence: Option, + callers: Option, + workflows: Option, + attempts: u32, + open_fix_pr: bool, + write: bool, +} + +fn parse_args(args: &[String]) -> Result { + let mut a = Args::default(); + let mut it = args.iter(); + while let Some(flag) = it.next() { + let mut value = |name: &str| { + it.next() + .cloned() + .ok_or_else(|| format!("{name} needs a value")) + }; + match flag.as_str() { + "--lock" => a.lock = Some(value("--lock")?), + "--evidence" => a.evidence = Some(value("--evidence")?), + "--callers" => a.callers = Some(value("--callers")?), + "--workflows" => a.workflows = Some(value("--workflows")?), + "--attempts" => { + a.attempts = value("--attempts")? + .parse() + .map_err(|_| "--attempts needs a whole number".to_string())? + } + "--open-fix-pr" => a.open_fix_pr = true, + "--write" => a.write = true, + other => return Err(format!("unknown argument `{other}`")), + } + } + Ok(a) +} + +/// Parse the evidence file: `keytag|branch|defaultname` per line, `#` +/// comments and blank lines ignored. A malformed line is an error: evidence +/// that was misread must not become a repair. +pub fn parse_evidence(text: &str) -> Result, String> { + let mut out: BTreeMap = BTreeMap::new(); + for (n, line) in text.lines().enumerate() { + if line.trim().is_empty() || line.trim_start().starts_with('#') { + continue; + } + let f: Vec<&str> = line.split('\t').collect(); + let [key, kind, name] = f[..] else { + return Err(format!( + "evidence line {}: want keykindname", + n + 1 + )); + }; + let e = out.entry(key.trim().to_ascii_lowercase()).or_default(); + match kind { + "tag" => e.tags.push(name.to_string()), + "branch" => e.branches.push(name.to_string()), + "default" => e.default_branch = Some(name.to_string()), + other => return Err(format!("evidence line {}: unknown kind `{other}`", n + 1)), + } + } + Ok(out) +} + +fn read(path: &str) -> Result { + std::fs::read_to_string(path).map_err(|e| format!("cannot read `{path}`: {e}")) +} + +/// Write `text` to `path` through a sibling temp file, so a failed write +/// leaves the original lock intact. +fn write_atomic(path: &str, text: &str) -> Result<(), String> { + let tmp = format!("{path}.squabble-tmp"); + std::fs::write(&tmp, text).map_err(|e| format!("cannot write `{tmp}`: {e}"))?; + std::fs::rename(&tmp, path).map_err(|e| { + let _ = std::fs::remove_file(&tmp); + format!("cannot replace `{path}`: {e}") + }) +} + +fn print_plan(plan: &LockFixPlan) { + for (key, new) in &plan.edits { + println!("repair\t{key}\tref -> {new}"); + } + for (key, why) in &plan.refused { + println!("refer\t{key}\t{why}"); + } +} + +/// The job-level reusable callers, from the workflow directory and/or a list +/// file. One of the two is required: a missing list would leave a caller +/// record flagged as if it were a defect, and a rewrite of it breaks the lock. +fn collect_callers(a: &Args) -> Result, String> { + if a.workflows.is_none() && a.callers.is_none() { + return Err("--workflows or --callers is required (callers are never guessed)".into()); + } + let mut callers: Vec = Vec::new(); + if let Some(dir) = &a.workflows { + let entries = std::fs::read_dir(dir).map_err(|e| format!("cannot read `{dir}`: {e}"))?; + let mut paths: Vec<_> = entries.filter_map(Result::ok).map(|e| e.path()).collect(); + paths.sort(); + for p in paths + .iter() + .filter(|p| p.extension().is_some_and(|x| x == "yml" || x == "yaml")) + { + callers.extend(reusable_callers(&read(&p.to_string_lossy())?)); + } + } + if let Some(p) = &a.callers { + callers.extend(read(p)?.lines().map(|l| l.trim().to_ascii_lowercase())); + } + callers.sort(); + callers.dedup(); + Ok(callers) +} + +pub fn run(args: &[String]) -> ExitCode { + match run_inner(args) { + Ok(code) => code, + Err(e) => { + eprintln!("squabble relock: {e}\n{USAGE}"); + ExitCode::from(2) + } + } +} + +fn run_inner(args: &[String]) -> Result { + let a = parse_args(args)?; + let lock_path = a.lock.as_deref().ok_or("--lock is required")?; + let ev_path = a.evidence.as_deref().ok_or("--evidence is required")?; + let lock = read(lock_path)?; + let evidence = parse_evidence(&read(ev_path)?)?; + let callers = collect_callers(&a)?; + let plan = plan_lock_fix(&lock, &callers, &evidence)?; + print_plan(&plan); + let guards = GuardInput { + autofix: std::env::var("ESTATE_AUTOFIX").ok(), + attempts_on_head: a.attempts, + open_fix_pr: a.open_fix_pr, + ..GuardInput::default() + }; + let rule = rule("SQ-LOCK-01").ok_or("SQ-LOCK-01 is not in the catalogue")?; + let decision = decide(rule, &guards); + println!("decision\tSQ-LOCK-01\t{decision:?}"); + let Some(new_lock) = plan.new_lock.as_deref() else { + println!("nothing to write"); + return Ok(exit_for(&plan)); + }; + if a.write && decision == Decision::Apply { + write_atomic(lock_path, new_lock)?; + println!("wrote\t{lock_path}\tcheck: not run here; the lock gate on the PR is the check"); + } else if a.write { + println!("not written: the guards say {decision:?}"); + return Ok(ExitCode::from(4)); + } else { + println!("dry run: pass --write to apply"); + } + Ok(exit_for(&plan)) +} + +/// 0 when every flagged record was repaired, 4 when some are referrals. +fn exit_for(plan: &LockFixPlan) -> ExitCode { + if plan.refused.is_empty() { + ExitCode::SUCCESS + } else { + ExitCode::from(4) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn evidence_parses_by_kind_and_refuses_junk() { + let e = + parse_evidence("# note\n\nA/B@x\ttag\tv1\nA/B@x\tbranch\tmain\nA/B@x\tdefault\tmain\n") + .unwrap(); + let r = &e["a/b@x"]; + assert_eq!((r.tags.len(), r.branches.len()), (1, 1)); + assert_eq!(r.default_branch.as_deref(), Some("main")); + for bad in ["k\ttag", "k\tweird\tx", "k tag v1", "k\ttag\tv1\textra"] { + assert!(parse_evidence(bad).is_err(), "{bad:?}"); + } + } + + #[test] + fn arguments_need_values_and_reject_unknown_flags() { + let s = |v: &[&str]| v.iter().map(|x| x.to_string()).collect::>(); + assert!(parse_args(&s(&["--lock"])).is_err()); + assert!(parse_args(&s(&["--attempts", "x"])).is_err()); + assert!(parse_args(&s(&["--wat"])).is_err()); + let ok = parse_args(&s(&[ + "--lock", + "l", + "--evidence", + "e", + "--write", + "--attempts", + "2", + ])) + .unwrap(); + assert!(ok.write && ok.attempts == 2); + } +} diff --git a/crates/squabble-core/src/lib.rs b/crates/squabble-core/src/lib.rs index f5abd2c..a27f0fe 100644 --- a/crates/squabble-core/src/lib.rs +++ b/crates/squabble-core/src/lib.rs @@ -21,6 +21,7 @@ pub mod done; pub mod execution; pub mod gate; pub mod inbox; +pub mod lockfix; pub mod moves; pub mod outcome; pub mod polarity; diff --git a/crates/squabble-core/src/lockfix.rs b/crates/squabble-core/src/lockfix.rs new file mode 100644 index 0000000..40ab9ab --- /dev/null +++ b/crates/squabble-core/src/lockfix.rs @@ -0,0 +1,453 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +//! The SQ-LOCK-01 executor core (ADR 0004): repair an `actions.lock` record +//! keyed `owner/repo@<40-hex>` whose `ref:` repeats that SHA. +//! +//! Pure: no network, no filesystem. The caller gathers the evidence (the tags +//! that point at the SHA, the branches that contain it) and writes the result; +//! this module chooses the ref, rewrites only the flagged `ref:` lines, and +//! checks its own work before it returns text. A repair it cannot make is a +//! [`Refusal`], never a guess. +//! +//! The order is the catalogue row's: the highest full-semver tag at the SHA, +//! else the highest semver tag, else the first tag, else a branch that +//! contains the commit. Tags that tie, or no tag and no branch, are refusals. + +use crate::rules::{indent_of, is_sha40, self_sha_lock_records, self_sha_record_key, unquote}; +use std::collections::BTreeMap; + +/// What the caller found out about one record's SHA in its repository. +#[derive(Debug, Default, Clone, PartialEq, Eq)] +pub struct RefEvidence { + /// Tags whose commit is the SHA. + pub tags: Vec, + /// Branches that contain the SHA. + pub branches: Vec, + /// The repository's default branch, when known. + pub default_branch: Option, +} + +/// Why a record is not repaired. Each is a referral, not a failure. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Refusal { + /// No evidence was gathered for the key. + NoEvidence, + /// No tag points at the SHA and no branch contains it. + NoRef, + /// Several refs rank equal; the candidates are named. + Tie(Vec), +} + +impl std::fmt::Display for Refusal { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Refusal::NoEvidence => write!(f, "no evidence was gathered for this record"), + Refusal::NoRef => write!(f, "no tag or branch holds the commit"), + Refusal::Tie(c) => write!(f, "refs tie: {}", c.join(", ")), + } + } +} + +/// A tag's numeric parts, `v1.2.3` -> [1, 2, 3], or None when it is not a +/// plain `MAJOR[.MINOR[.PATCH]]` (a pre-release or any other suffix). +fn semver_parts(tag: &str) -> Option> { + let body = tag.strip_prefix('v').unwrap_or(tag); + let parts: Vec = body + .split('.') + .map(|p| { + let plain = !p.is_empty() && p.len() <= 9 && p.bytes().all(|b| b.is_ascii_digit()); + plain.then(|| p.parse().ok()).flatten() + }) + .collect::>()?; + (1..=3).contains(&parts.len()).then_some(parts) +} + +/// The highest of `candidates` by their parts, or a tie naming the top ones. +fn highest(candidates: &[(&String, Vec)]) -> Result { + let key = |p: &[u64]| [p.first(), p.get(1), p.get(2)].map(|v| v.copied().unwrap_or(0)); + let top = candidates.iter().map(|(_, p)| key(p)).max(); + let mut best: Vec<&String> = candidates + .iter() + .filter(|(_, p)| Some(key(p)) == top) + .map(|(t, _)| *t) + .collect(); + best.sort(); + best.dedup(); + match best.as_slice() { + [one] => Ok((*one).clone()), + _ => Err(Refusal::Tie(best.into_iter().cloned().collect())), + } +} + +/// Choose the symbolic ref that replaces a SHA-as-ref. +pub fn choose_ref(e: &RefEvidence) -> Result { + let parsed: Vec<(&String, Vec)> = e + .tags + .iter() + .filter_map(|t| semver_parts(t).map(|p| (t, p))) + .collect(); + let full: Vec<_> = parsed + .iter() + .filter(|(_, p)| p.len() == 3) + .cloned() + .collect(); + if !full.is_empty() { + return highest(&full); + } + if !parsed.is_empty() { + return highest(&parsed); + } + if let Some(first) = e.tags.iter().min() { + return Ok(first.clone()); + } + choose_branch(e) +} + +fn choose_branch(e: &RefEvidence) -> Result { + let mut branches: Vec<&String> = e.branches.iter().collect(); + branches.sort(); + branches.dedup(); + match (branches.as_slice(), &e.default_branch) { + ([], _) => Err(Refusal::NoRef), + (_, Some(d)) if branches.contains(&d) => Ok(d.clone()), + ([one], _) => Ok((*one).clone()), + _ => Err(Refusal::Tie(branches.into_iter().cloned().collect())), + } +} + +/// A ref name safe to write between single quotes: no quote, space, colon or +/// control character, not empty, and not itself a 40-hex SHA. +fn ref_is_writable(r: &str) -> bool { + !r.is_empty() + && !is_sha40(r) + && r.bytes() + .all(|b| b.is_ascii_alphanumeric() || b"._/-+".contains(&b)) +} + +/// Rewrite the direct `ref:` line of each record in `edits` (lowercased +/// `owner/repo@sha` -> new ref). Every other byte is kept, line endings +/// included. Errors when a ref is not writable or a record has no `ref:` line. +pub fn rewrite_refs(lock: &str, edits: &BTreeMap) -> Result { + if let Some((k, r)) = edits.iter().find(|(_, r)| !ref_is_writable(r)) { + return Err(format!("`{r}` is not a writable ref for {k}")); + } + let mut out = String::with_capacity(lock.len()); + let mut current: Option<(String, usize)> = None; + let mut done: Vec<&String> = Vec::new(); + for raw in lock.split_inclusive('\n') { + let line = raw.trim_end_matches(['\n', '\r']); + let eol = &raw[line.len()..]; + let trimmed = line.trim(); + if trimmed.is_empty() || trimmed.starts_with('#') { + out.push_str(raw); + continue; + } + let ind = indent_of(line); + if current.as_ref().is_some_and(|(_, k)| ind <= *k) { + current = None; + } + let Some((key, key_ind)) = current.clone() else { + current = self_sha_record_key(trimmed).map(|k| (k, ind)); + out.push_str(raw); + continue; + }; + match edits.get_key_value(&key) { + Some((k, new)) if ind > key_ind && trimmed.starts_with("ref:") => { + out.push_str(&format!("{}ref: '{new}'{eol}", &line[..ind])); + done.push(k); + } + _ => out.push_str(raw), + } + } + match edits.keys().find(|k| !done.contains(k)) { + Some(k) => Err(format!("record {k} has no direct `ref:` line to rewrite")), + None => Ok(out), + } +} + +/// The lowercased `owner/repo@<40-hex>` keys of the reusable workflows a +/// workflow file calls at job level (`uses: o/r/.github/workflows/x.yml@sha`). +/// A step's action can never name a `.github/workflows/` path, so that path is +/// the test. A caller's lock record legitimately repeats its SHA as its ref, +/// so it must never be rewritten. +pub fn reusable_callers(workflow_yaml: &str) -> Vec { + let mut out: Vec = Vec::new(); + for line in workflow_yaml.lines() { + let t = line.trim().trim_start_matches('-').trim(); + let Some(value) = t.strip_prefix("uses:") else { + continue; + }; + let spec = unquote(value); + let spec = spec.split_whitespace().next().unwrap_or(""); + let Some((path, sha)) = spec.rsplit_once('@') else { + continue; + }; + let mut parts = path.splitn(3, '/'); + let (owner, repo, rest) = (parts.next(), parts.next(), parts.next()); + if let (Some(o), Some(r), Some(rest)) = (owner, repo, rest) { + let key = format!("{o}/{r}@{sha}").to_ascii_lowercase(); + if rest.starts_with(".github/workflows/") && is_sha40(sha) && !out.contains(&key) { + out.push(key); + } + } + } + out +} + +/// What [`plan_lock_fix`] decided. +#[derive(Debug, Default, Clone, PartialEq, Eq)] +pub struct LockFixPlan { + /// Records to rewrite: key -> the ref they will name. + pub edits: BTreeMap, + /// Records left as they are, and why. + pub refused: Vec<(String, Refusal)>, + /// The repaired lock text, when there is at least one edit. + pub new_lock: Option, +} + +/// Plan the repair of every self-SHA record in `lock`. `callers` are the +/// job-level reusable callers (a record they name is valid as it is). +/// +/// Errors only when its own check fails: the result must still parse, differ +/// from the input in exactly the edited `ref:` lines, and no longer flag any +/// edited record. A failed check returns no text. +pub fn plan_lock_fix( + lock: &str, + callers: &[String], + evidence: &BTreeMap, +) -> Result { + let mut plan = LockFixPlan::default(); + for key in self_sha_lock_records(lock, callers) { + let chosen = evidence + .get(&key) + .ok_or(Refusal::NoEvidence) + .and_then(choose_ref); + match chosen { + Ok(r) => { + plan.edits.insert(key, r); + } + Err(why) => plan.refused.push((key, why)), + } + } + if plan.edits.is_empty() { + return Ok(plan); + } + let new = rewrite_refs(lock, &plan.edits)?; + check_rewrite(lock, &new, callers, &plan)?; + plan.new_lock = Some(new); + Ok(plan) +} + +/// The repair's own check (fail closed): same line count, only the edited +/// `ref:` lines differ, and the edited records are no longer flagged while the +/// refused ones still are. +fn check_rewrite( + old: &str, + new: &str, + callers: &[String], + plan: &LockFixPlan, +) -> Result<(), String> { + let (a, b): (Vec<&str>, Vec<&str>) = (old.lines().collect(), new.lines().collect()); + if a.len() != b.len() { + return Err("repair changed the number of lines".into()); + } + let changed: Vec<(&&str, &&str)> = a.iter().zip(&b).filter(|(x, y)| x != y).collect(); + let only_refs = changed.iter().all(|(x, y)| { + unquote(x.trim().trim_start_matches("ref:")).len() == 40 && y.trim().starts_with("ref: '") + }); + if changed.len() != plan.edits.len() || !only_refs { + return Err("repair changed lines other than the flagged `ref:` lines".into()); + } + let after = self_sha_lock_records(new, callers); + let refused: Vec<&String> = plan.refused.iter().map(|(k, _)| k).collect(); + let expected_left = after.iter().all(|k| refused.contains(&k)); + if !expected_left || refused.iter().any(|k| !after.contains(k)) { + return Err("repair left a different set of flagged records than it planned".into()); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + const SHA: &str = "0da816c05ae7486671d863e07935f93981c0c2d5"; + const SHA2: &str = "55556cf5ba71ba744695861503c13148d3915a5d"; + + fn ev(tags: &[&str], branches: &[&str], default: Option<&str>) -> RefEvidence { + RefEvidence { + tags: tags.iter().map(|s| s.to_string()).collect(), + branches: branches.iter().map(|s| s.to_string()).collect(), + default_branch: default.map(String::from), + } + } + + fn lock() -> String { + format!( + "version: 'v0.0.3'\ndependencies:\n 'a/leaf@{SHA}':\n ref: '{SHA}'\n commit: 'sha1-{SHA}'\n owner_id: 1\n 'a/caller@{SHA2}':\n ref: '{SHA2}'\n commit: 'sha1-{SHA2}'\n uses:\n - 'a/leaf@{SHA}'\n 'a/ok@v1':\n ref: 'v1'\n" + ) + } + + #[test] + fn the_catalogue_order_of_refs() { + // Highest full-semver tag wins over a higher short tag and any branch. + assert_eq!( + choose_ref(&ev(&["v1.2.3", "v1.10.0", "v9"], &["main"], None)).unwrap(), + "v1.10.0" + ); + // No full-semver tag: the highest semver tag. + assert_eq!( + choose_ref(&ev(&["v1", "v2.1", "nightly"], &["main"], None)).unwrap(), + "v2.1" + ); + // No semver tag: the first tag. + assert_eq!( + choose_ref(&ev(&["rc", "beta"], &["main"], None)).unwrap(), + "beta" + ); + // A pre-release is not semver. + assert_eq!( + choose_ref(&ev(&["v1.2.3-rc1", "v0.9.0"], &[], None)).unwrap(), + "v0.9.0" + ); + // No tag: the default branch when it contains the commit, else the only one. + assert_eq!( + choose_ref(&ev(&[], &["dev", "main"], Some("main"))).unwrap(), + "main" + ); + assert_eq!(choose_ref(&ev(&[], &["only"], None)).unwrap(), "only"); + } + + #[test] + fn ties_and_nothing_are_refusals_not_guesses() { + assert_eq!( + choose_ref(&ev(&["v1.2.3", "1.2.3"], &[], None)), + Err(Refusal::Tie(vec!["1.2.3".into(), "v1.2.3".into()])) + ); + assert_eq!( + choose_ref(&ev(&[], &["a", "b"], Some("main"))), + Err(Refusal::Tie(vec!["a".into(), "b".into()])) + ); + assert_eq!(choose_ref(&ev(&[], &[], Some("main"))), Err(Refusal::NoRef)); + // 0.9.0 is lower than 0.10.0, not higher as a string compare says. + assert_eq!( + choose_ref(&ev(&["v0.9.0", "v0.10.0"], &[], None)).unwrap(), + "v0.10.0" + ); + // An oversized component is not semver (no overflow). + assert_eq!( + choose_ref(&ev(&["v99999999999999999999.0.0", "v1.0.0"], &[], None)).unwrap(), + "v1.0.0" + ); + } + + #[test] + fn rewrite_touches_only_the_named_ref_line() { + let l = lock(); + let mut edits = BTreeMap::new(); + edits.insert(format!("a/leaf@{SHA}"), "main".to_string()); + let new = rewrite_refs(&l, &edits).unwrap(); + assert_eq!(new.lines().count(), l.lines().count()); + assert!(new.contains(&format!( + "'a/leaf@{SHA}':\n ref: 'main'\n commit: 'sha1-{SHA}'" + ))); + // The caller record with the same ref shape is untouched. + assert!(new.contains(&format!("'a/caller@{SHA2}':\n ref: '{SHA2}'"))); + assert!(new.contains("'a/ok@v1':\n ref: 'v1'\n")); + } + + #[test] + fn rewrite_keeps_line_endings_and_refuses_bad_refs() { + let l = lock().replace('\n', "\r\n"); + let mut edits = BTreeMap::new(); + edits.insert(format!("a/leaf@{SHA}"), "v1".to_string()); + let new = rewrite_refs(&l, &edits).unwrap(); + assert!(new.contains("ref: 'v1'\r\n") && !new.contains("ref: 'v1'\n\n")); + for bad in ["", "a b", "it's", "x:y", SHA, "a\nb"] { + let mut e = BTreeMap::new(); + e.insert(format!("a/leaf@{SHA}"), bad.to_string()); + assert!(rewrite_refs(&l, &e).is_err(), "{bad:?}"); + } + let mut missing = BTreeMap::new(); + missing.insert("a/none@v1".to_string(), "main".to_string()); + assert!(rewrite_refs(&l, &missing).is_err()); + } + + #[test] + fn plan_repairs_the_leaf_and_leaves_the_exempt_caller() { + let l = lock(); + let callers = vec![format!("a/caller@{SHA2}")]; + let mut evidence = BTreeMap::new(); + evidence.insert(format!("a/leaf@{SHA}"), ev(&[], &["main"], Some("main"))); + let plan = plan_lock_fix(&l, &callers, &evidence).unwrap(); + assert_eq!( + plan.edits.get(&format!("a/leaf@{SHA}")).map(String::as_str), + Some("main") + ); + assert!(plan.refused.is_empty()); + let new = plan.new_lock.unwrap(); + assert!(self_sha_lock_records(&new, &callers).is_empty()); + // Idempotent: nothing is left to repair. + assert!(plan_lock_fix(&new, &callers, &evidence) + .unwrap() + .new_lock + .is_none()); + } + + #[test] + fn a_refused_record_stays_flagged_and_blocks_nothing_else() { + let l = lock().replace( + "a/ok@v1':\n ref: 'v1'", + &format!("b/two@{SHA2}':\n ref: '{SHA2}'"), + ); + let callers: Vec = Vec::new(); + let mut evidence = BTreeMap::new(); + evidence.insert(format!("a/leaf@{SHA}"), ev(&["v1.0.0"], &[], None)); + let plan = plan_lock_fix(&l, &callers, &evidence).unwrap(); + // The leaf is repaired, the two without evidence are refused and still flagged. + assert_eq!(plan.edits.len(), 1); + assert_eq!(plan.refused.len(), 2); + assert!(plan.refused.iter().all(|(_, r)| *r == Refusal::NoEvidence)); + let left = self_sha_lock_records(plan.new_lock.as_deref().unwrap(), &callers); + assert_eq!(left.len(), 2); + } + + #[test] + fn reusable_callers_are_read_from_job_level_uses_only() { + let wf = format!( + "jobs:\n g:\n uses: Meta/Standards/.github/workflows/x-reusable.yml@{SHA2} # note\n s:\n steps:\n - uses: actions/checkout@{SHA}\n - uses: \"a/b/.github/workflows/y.yml@v1\"\n t:\n uses: ./.github/workflows/local.yml\n" + ); + // Only the full-SHA reusable caller, lowercased; a step action, a tag + // ref and a local path are not callers. + assert_eq!( + reusable_callers(&wf), + vec![format!("meta/standards@{SHA2}")] + ); + assert!(reusable_callers("name: x\n").is_empty()); + } + + #[test] + fn nothing_to_repair_is_a_plan_with_no_text() { + let plan = plan_lock_fix( + "version: 'v0.0.3'\ndependencies:\n 'a/ok@v1':\n ref: 'v1'\n", + &[], + &BTreeMap::new(), + ) + .unwrap(); + assert!(plan.edits.is_empty() && plan.refused.is_empty() && plan.new_lock.is_none()); + } + + #[test] + fn the_repair_check_catches_an_edit_that_strays() { + let l = lock(); + let mut plan = LockFixPlan::default(); + plan.edits.insert(format!("a/leaf@{SHA}"), "main".into()); + // A rewrite that also changed another line must not pass the check. + let stray = l + .replacen(&format!("ref: '{SHA}'"), "ref: 'main'", 1) + .replace("owner_id: 1", "owner_id: 2"); + assert!(check_rewrite(&l, &stray, &[], &plan).is_err()); + // One that changed nothing must not pass either. + assert!(check_rewrite(&l, &l, &[], &plan).is_err()); + } +} diff --git a/crates/squabble-core/src/rules.rs b/crates/squabble-core/src/rules.rs index 5b809fa..8b2e673 100644 --- a/crates/squabble-core/src/rules.rs +++ b/crates/squabble-core/src/rules.rs @@ -299,15 +299,15 @@ pub fn match_log(log: &str, step: Option<&str>) -> Vec<&'static str> { .collect() } -fn is_sha40(s: &str) -> bool { +pub(crate) fn is_sha40(s: &str) -> bool { s.len() == 40 && s.bytes().all(|b| b.is_ascii_hexdigit()) } -fn indent_of(line: &str) -> usize { +pub(crate) fn indent_of(line: &str) -> usize { line.len() - line.trim_start().len() } -fn unquote(s: &str) -> &str { +pub(crate) fn unquote(s: &str) -> &str { let s = s.trim(); let s = match s.find(" #") { Some(i) if !s.starts_with(['\'', '"']) => s[..i].trim(), @@ -350,7 +350,7 @@ pub fn self_sha_lock_records(lock_yaml: &str, job_level_callers: &[String]) -> V /// The lowercased `owner/repo@<40-hex>` key of a lock record opened by this /// line, or None for any other line (a list item, or a key of another shape). -fn self_sha_record_key(trimmed: &str) -> Option { +pub(crate) fn self_sha_record_key(trimmed: &str) -> Option { if trimmed.starts_with('-') { return None; } diff --git a/docs/decisions/0004-first-line-rule-catalogue.adoc b/docs/decisions/0004-first-line-rule-catalogue.adoc index a28853e..870627c 100644 --- a/docs/decisions/0004-first-line-rule-catalogue.adoc +++ b/docs/decisions/0004-first-line-rule-catalogue.adoc @@ -403,6 +403,40 @@ unverified, and SQ-REF-06 records the OTP 28 miscompile as Hypatia's to fix It becomes a row only with evidence (repositories, OTP versions, reproduced on base). +== The SQ-LOCK-01 executor (`squabble relock`) + +The first executor, owner go 2026-11-14. The catalogue says what to do; +`squabble relock` does it for one rule and no other. + +* **What it changes.** Only the direct `ref:` line of a record keyed + `owner/repo@<40-hex>` whose `ref:` repeats that SHA. Every other byte of the + lock, line endings included, is kept. The ref is chosen in the row's order: + the highest full-semver tag at the SHA, else the highest semver tag, else the + first tag, else the default branch (or the only branch) that contains the + commit. Tags or branches that tie, and a commit that no tag or branch holds, + are referrals, never a guess. +* **What it will not touch.** A record that a job-level reusable caller names + keeps its SHA as its `ref:` by design (the closure rule needs it). The + callers are read from the repository's own workflows (`--workflows`) or a + list (`--callers`); one of the two is required, and a caller is never assumed. +* **Its own check.** Before it returns text it re-reads the result: the line + count is unchanged, only the edited `ref:` lines differ, the edited records + are no longer flagged and the refused ones still are. A failed check returns + no text. +* **Guards.** It is a dry run unless `--write` is given and the guards + (`decide`: the `ESTATE_AUTOFIX` kill switch, two attempts per head, one open + fix PR per rule) say `Apply`. It writes through a temporary file and a + rename, so a failed write leaves the lock as it was. It opens no PR. +* **What it does not claim.** It never reports the rule's check as passed. The + check is the repository's lock gate, run on the PR it feeds. +* **Evidence in, for now.** The tags and branches come from a TSV the caller + gathers (`keytag|branch|defaultname`). Gathering them from git, and + opening the PR, are separate steps that are not built yet. + +First proof (ZeroInflatedCounts.jl, `hyperpolymath/cicd-suite@0da816c0`, which +`hyperpolymath/cicd-suite` has no tag for and holds on its `main`): the +executor's output is byte-identical to the hand repair in ZeroInflatedCounts.jl#22. + == Consequences * 25 rules are first-line (20 `FIX`, 5 `ACT`), 3 are referrals, 16 are