Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions crates/squabble-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ mod inbox;
mod lock_verifier;
mod phase;
mod relock;
mod relock_gather;
mod triage;
mod verify;
mod zero_job;
Expand Down
39 changes: 35 additions & 4 deletions crates/squabble-cli/src/relock.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,20 @@
//! opens a PR and never claims the rule's check passed: that check is the
//! repository's lock gate, run on the PR.

use crate::relock_gather::gather;
use squabble_core::lockfix::{plan_lock_fix, reusable_callers, LockFixPlan, RefEvidence};
use squabble_core::rules::{decide, rule, Decision, GuardInput};
use squabble_core::rules::{decide, rule, self_sha_lock_records, Decision, GuardInput};
use std::collections::BTreeMap;
use std::process::ExitCode;

pub const USAGE: &str = "usage: squabble relock --lock <file> --evidence <tsv> (--workflows <dir> | --callers <file>) [--attempts <n>] [--open-fix-pr] [--write]";
pub const USAGE: &str = "usage: squabble relock --lock <file> (--evidence <tsv> | --gather) (--workflows <dir> | --callers <file>) [--attempts <n>] [--open-fix-pr] [--write]";

#[derive(Default)]
struct Args {
lock: Option<String>,
evidence: Option<String>,
gather: bool,
remote_base: Option<String>,
callers: Option<String>,
workflows: Option<String>,
attempts: u32,
Expand All @@ -40,6 +43,8 @@ fn parse_args(args: &[String]) -> Result<Args, String> {
match flag.as_str() {
"--lock" => a.lock = Some(value("--lock")?),
"--evidence" => a.evidence = Some(value("--evidence")?),
"--gather" => a.gather = true,
"--remote-base" => a.remote_base = Some(value("--remote-base")?),
"--callers" => a.callers = Some(value("--callers")?),
"--workflows" => a.workflows = Some(value("--workflows")?),
"--attempts" => {
Expand Down Expand Up @@ -106,6 +111,33 @@ fn print_plan(plan: &LockFixPlan) {
}
}

/// The evidence: from `--evidence`, or gathered from each flagged record's
/// own repository with `--gather`. Exactly one of the two. A record whose
/// lookup fails is reported and left without evidence, so it is a referral.
fn collect_evidence(
a: &Args,
lock: &str,
callers: &[String],
) -> Result<BTreeMap<String, RefEvidence>, String> {
match (&a.evidence, a.gather) {
(Some(p), false) => parse_evidence(&read(p)?),
(None, true) => {
let base = a.remote_base.as_deref().unwrap_or("https://github.com");
let mut found = BTreeMap::new();
for key in self_sha_lock_records(lock, callers) {
match gather(base, &key) {
Ok(e) => {
found.insert(key, e);
}
Err(why) => println!("gather-failed\t{key}\t{why}"),
}
}
Ok(found)
}
_ => Err("give exactly one of --evidence <tsv> or --gather".into()),
}
}

/// 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.
Expand Down Expand Up @@ -146,10 +178,9 @@ pub fn run(args: &[String]) -> ExitCode {
fn run_inner(args: &[String]) -> Result<ExitCode, String> {
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 evidence = collect_evidence(&a, &lock, &callers)?;
let plan = plan_lock_fix(&lock, &callers, &evidence)?;
print_plan(&plan);
let guards = GuardInput {
Expand Down
239 changes: 239 additions & 0 deletions crates/squabble-cli/src/relock_gather.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,239 @@
// SPDX-License-Identifier: MPL-2.0
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
//! Evidence for `squabble relock --gather`: ask an action's own repository
//! which tags point at a SHA and, failing that, which branches contain it.
//!
//! Read-only: it only runs `git ls-remote`, `git init --bare` in a private
//! temporary directory, and a blob-less `git fetch` into it. It never writes
//! to the repository it asks and never to the lock.

use squabble_core::lockfix::RefEvidence;
use std::path::{Path, PathBuf};
use std::process::Command;
use std::sync::atomic::{AtomicU32, Ordering};

/// Run git, return stdout. Any non-zero exit is an error that names the
/// command's stderr, so a failed lookup is loud.
fn git(dir: Option<&Path>, args: &[&str]) -> Result<String, String> {
let mut cmd = Command::new("git");
cmd.args(args)
.env_remove("GIT_DIR")
.env_remove("GIT_WORK_TREE")
.env_remove("GIT_INDEX_FILE")
.env("GIT_TERMINAL_PROMPT", "0");
if let Some(d) = dir {
cmd.current_dir(d);
}
let out = cmd.output().map_err(|e| format!("cannot run git: {e}"))?;
if out.status.success() {
Ok(String::from_utf8_lossy(&out.stdout).into_owned())
} else {
let err = String::from_utf8_lossy(&out.stderr);
Err(format!("git {} failed: {}", args.join(" "), err.trim()))
}
}

/// Split `owner/repo@<sha>` into the repository path and the SHA.
fn split_key(key: &str) -> Result<(&str, &str), String> {
key.split_once('@')
.filter(|(repo, _)| repo.matches('/').count() == 1)
.ok_or_else(|| format!("`{key}` is not owner/repo@sha"))
}

/// The tags whose commit is `sha`, from `git ls-remote --tags` output. An
/// annotated tag's commit is its peeled `^{}` line, a lightweight tag's is its
/// own line.
fn tags_from_ls_remote(output: &str, sha: &str) -> Vec<String> {
let mut commit_of: Vec<(String, String)> = Vec::new();
for line in output.lines() {
let Some((id, name)) = line.split_once('\t') else {
continue;
};
let Some(tag) = name.strip_prefix("refs/tags/") else {
continue;
};
match tag.strip_suffix("^{}") {
Some(base) => match commit_of.iter_mut().find(|(n, _)| n == base) {
Some(entry) => entry.1 = id.to_string(),
None => commit_of.push((base.to_string(), id.to_string())),
},
None if !commit_of.iter().any(|(n, _)| n == tag) => {
commit_of.push((tag.to_string(), id.to_string()));
}
None => {}
}
}
let mut tags: Vec<String> = commit_of
.into_iter()
.filter(|(_, id)| id.eq_ignore_ascii_case(sha))
.map(|(n, _)| n)
.collect();
tags.sort();
tags
}

/// The default branch from `git ls-remote --symref <url> HEAD`.
fn default_branch(url: &str) -> Option<String> {
let out = git(None, &["ls-remote", "--symref", url, "HEAD"]).ok()?;
out.lines()
.find_map(|l| l.strip_prefix("ref: refs/heads/"))
.and_then(|l| l.split_whitespace().next())
.map(String::from)
}

/// A temporary directory removed when dropped.
struct TempDir(PathBuf);

impl TempDir {
fn new() -> Result<Self, String> {
static N: AtomicU32 = AtomicU32::new(0);
let p = std::env::temp_dir().join(format!(
"squabble-gather-{}-{}",
std::process::id(),
N.fetch_add(1, Ordering::Relaxed)
));
std::fs::create_dir_all(&p).map_err(|e| format!("cannot create {}: {e}", p.display()))?;
Ok(TempDir(p))
}
}

impl Drop for TempDir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}

/// The branches of `url` that contain `sha`: every branch's history without
/// blobs, then `for-each-ref --contains`. An unknown commit (not reachable
/// from any branch) is no branches, not an error.
fn branches_containing(url: &str, sha: &str) -> Result<Vec<String>, String> {
let tmp = TempDir::new()?;
let dir = tmp.0.as_path();
git(Some(dir), &["init", "--bare", "-q"])?;
git(
Some(dir),
&[
"fetch",
"-q",
"--no-tags",
"--filter=blob:none",
url,
"+refs/heads/*:refs/heads/*",
],
)?;
if git(Some(dir), &["cat-file", "-e", &format!("{sha}^{{commit}}")]).is_err() {
return Ok(Vec::new());
}
let out = git(
Some(dir),
&[
"for-each-ref",
"--contains",
sha,
"--format=%(refname:short)",
"refs/heads",
],
)?;
Ok(out.lines().map(String::from).collect())
}

/// Gather the evidence for one record key against `<base>/<owner>/<repo>`.
/// Branches are asked only when no tag holds the commit.
pub fn gather(base: &str, key: &str) -> Result<RefEvidence, String> {
let (repo, sha) = split_key(key)?;
let url = format!("{}/{repo}", base.trim_end_matches('/'));
let tags = tags_from_ls_remote(&git(None, &["ls-remote", "--tags", &url])?, sha);
let branches = if tags.is_empty() {
branches_containing(&url, sha)?
} else {
Vec::new()
};
Ok(RefEvidence {
tags,
branches,
default_branch: default_branch(&url),
})
}

#[cfg(test)]
mod tests {
use super::*;

const A: &str = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
const B: &str = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";

#[test]
fn ls_remote_tags_lightweight_annotated_and_others() {
let out = format!(
"{A}\trefs/tags/v1.0.0\n{B}\trefs/tags/v2.0.0\n{A}\trefs/tags/v2.0.0^{{}}\n{B}\trefs/tags/other\nnot a line\n{B}\trefs/heads/main\n"
);
// v1.0.0 is lightweight at A; v2.0.0 is annotated and its peeled commit is A.
assert_eq!(tags_from_ls_remote(&out, A), vec!["v1.0.0", "v2.0.0"]);
assert_eq!(tags_from_ls_remote(&out, B), vec!["other"]);
assert!(tags_from_ls_remote(&out, "cccccccccccccccccccccccccccccccccccccccc").is_empty());
}

#[test]
fn keys_must_be_owner_repo_at_sha() {
assert_eq!(split_key("a/b@abc").unwrap(), ("a/b", "abc"));
for bad in ["a@abc", "a/b/c@abc", "nothing"] {
assert!(split_key(bad).is_err(), "{bad}");
}
}

/// A local "remote": `<base>/o/r` holding one commit on main, an annotated
/// tag v1.0.0 on it, a second commit on main, and a branch `topic` at the
/// second commit. Returns (base dir, first sha, second sha).
fn fixture() -> (TempDir, String, String) {
let base = TempDir::new().unwrap();
let repo = base.0.join("o").join("r");
std::fs::create_dir_all(&repo).unwrap();
let g = |args: &[&str]| git(Some(&repo), args).unwrap();
g(&["init", "-q", "-b", "main"]);
g(&["config", "user.email", "t@example.invalid"]);
g(&["config", "user.name", "t"]);
g(&["config", "commit.gpgsign", "false"]);
g(&["commit", "-q", "--allow-empty", "-m", "one"]);
let first = g(&["rev-parse", "HEAD"]).trim().to_string();
g(&["tag", "-a", "v1.0.0", "-m", "v1"]);
g(&["commit", "-q", "--allow-empty", "-m", "two"]);
let second = g(&["rev-parse", "HEAD"]).trim().to_string();
g(&["branch", "topic"]);
(base, first, second)
}

fn base_of(t: &TempDir) -> String {
t.0.to_string_lossy().into_owned()
}

#[test]
fn an_annotated_tag_is_found_by_its_peeled_commit_and_branches_are_not_asked() {
let (base, first, _) = fixture();
let e = gather(&base_of(&base), &format!("o/r@{first}")).unwrap();
assert_eq!(e.tags, vec!["v1.0.0"]);
assert!(e.branches.is_empty());
assert_eq!(e.default_branch.as_deref(), Some("main"));
}

#[test]
fn without_a_tag_the_branches_that_contain_the_commit_are_named() {
let (base, _, second) = fixture();
let e = gather(&base_of(&base), &format!("o/r@{second}")).unwrap();
assert!(e.tags.is_empty());
assert_eq!(e.branches, vec!["main", "topic"]);
assert_eq!(e.default_branch.as_deref(), Some("main"));
}

#[test]
fn a_commit_no_branch_holds_is_no_evidence_not_an_error() {
let (base, _, _) = fixture();
let e = gather(&base_of(&base), &format!("o/r@{B}")).unwrap();
assert!(e.tags.is_empty() && e.branches.is_empty());
}

#[test]
fn an_unreachable_remote_is_an_error() {
let base = TempDir::new().unwrap();
assert!(gather(&base_of(&base), &format!("nope/none@{A}")).is_err());
}
}
14 changes: 10 additions & 4 deletions docs/decisions/0004-first-line-rule-catalogue.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -436,13 +436,19 @@ The first executor, owner go 2026-11-14. The catalogue says what to do;
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 (`key<TAB>tag|branch|default<TAB>name`). Gathering them from git, and
opening the PR, are separate steps that are not built yet.
* **Evidence.** `--evidence <tsv>` takes it from a file
(`key<TAB>tag|branch|default<TAB>name`). `--gather` asks each flagged record's
own repository instead (read-only): the tags whose commit is the SHA (an
annotated tag by its peeled commit), and only when there is none, the branches
that contain it, from a blob-less fetch into a private temporary directory,
plus the default branch. Exactly one of the two is given. A lookup that fails
is reported (`gather-failed`) and the record is left as a referral; a commit
that no branch holds is no evidence, not an error. Opening the PR is a
separate step that is 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.
executor's output, with the evidence gathered live by `--gather`, is byte-identical to the hand repair in ZeroInflatedCounts.jl#22. The same run on ResidualEvidenceTypes.jl's `actions/upload-artifact@bbbca2dd…` (one tag at that SHA, `v7.0.0`) names `v7.0.0`.

== Consequences

Expand Down
Loading