fix(workflow): make gate.diff-rules fail closed on a change it never read

Follow-up to the gate.diff-rules step (archie-core-8szi). The step's contract
said it diffed the worktree; Trees.Diff reports the merge base against HEAD, so
only committed work was visible and a definition placing the step before the
committing step ran every rule against an empty diff and returned nil --
'load and check nothing', indistinguishable in the run's events from a pass.
This commit is contained in:
sam committed 2026-09-21 20:44:54 +10:00
commit 5f186ffa8b
7 files changed
+341 -7

No files matched your search

@@ -136,6 +136,15 @@ func (h *hybridTrees) ChangedFileStats(ctx context.Context, dir, base string) (t
return h.local.ChangedFileStats(ctx, dir, base)
}
// HasUncommittedChanges is the capability the diff-rules placement guard reads
// to tell "nothing has changed" from "not committed yet". It is not part of
// workflow.Trees for the same reason ChangedFileStats is not, and without this
// forwarder the in-container path -- every production run -- would answer the
// guard for the wrong reason.
func (h *hybridTrees) HasUncommittedChanges(ctx context.Context, dir string) (bool, error) {
return h.local.HasUncommittedChanges(ctx, dir)
}
var _ workflow.Trees = (*hybridTrees)(nil)
// chownTree recursively chowns dir to uid:gid so the daemon -- running as
@@ -919,3 +919,25 @@ func TestHybridTreesForwardsChangedFileStatsToItsLocalManager(t *testing.T) {
t.Errorf("SHAs = (%q, %q), want both resolved", stats.BaseSHA, stats.HeadSHA)
}
}
// uncommittedChangeReporter mirrors the unexported optional interface package
// workflow type-asserts on TaskContext.Trees to tell a change that is not
// committed yet from a branch with no change. It is restated here for the same
// reason changeStatsReader is: an unexported interface cannot be named from this
// package, so this assertion is the only way this side can pin that the
// in-container Trees can answer at all.
type uncommittedChangeReporter interface {
HasUncommittedChanges(ctx context.Context, dir string) (bool, error)
}
// TestHybridTreesCanReportUncommittedWork is the in-container half of the
// diff-rules placement guard. Every production workflow.Run executes in
// archie-agent against a hybridTrees, and a workflow whose only Trees cannot
// answer would fail the guard for the wrong reason -- or, worse, look capable
// while forwarding nothing.
func TestHybridTreesCanReportUncommittedWork(t *testing.T) {
var trees any = &hybridTrees{local: &worktree.Manager{}}
if _, ok := trees.(uncommittedChangeReporter); !ok {
t.Fatal("hybridTrees cannot report uncommitted work, so the in-container diff-rules guard would refuse every run")
}
}
+63 -6
View File
@@ -38,11 +38,20 @@ import (
// pattern: 'panic\('
// message: new panic() call -- use error returns instead
//
// The step diffs the worktree against the repository's base branch, matches
// each rule against the ADDED lines of that diff, and reports every match with
// its file and new-file line number. An error-level finding parks the run with
// the findings in the task's park reason; a warn-level finding is logged and
// nothing else. A rule that matches nothing is silent.
// The step diffs the change the branch has COMMITTED against the repository's
// base branch, matches each rule against the ADDED lines of that diff, and
// reports every match with its file and new-file line number. An error-level
// finding parks the run with the findings in the task's park reason; a
// warn-level finding is logged and nothing else. A rule that matches nothing is
// silent, and the number of added lines read is logged on every run, so
// "checked nothing" is distinguishable from "found nothing".
//
// Where the step sits is part of its contract, not a matter of taste: the rules
// read commits, never the worktree's own edits (Trees.Diff reports the merge
// base against HEAD), so the step must follow the step that commits the change.
// A run that would read no committed change while the worktree still holds
// uncommitted work fails on the spot and says which step it must follow,
// instead of reporting no findings for a change it never read.
//
// What it deliberately does not do is inspect a changed file's whole contents:
// a rule reads what the change adds, so a rule cannot be satisfied or broken by
@@ -127,8 +136,19 @@ func runDiffRules(ctx context.Context, tc *TaskContext, rules []compiledDiffRule
return fmt.Errorf("%s: diff against %s: %w", DiffRulesStepName, base, err)
}
added := addedDiffLines(diff)
// The count is the run's own evidence of what the rules read: without it, a
// step that read nothing and a step whose rules matched nothing leave the
// same trace.
tc.Log.Info("diff rules read the committed change", "base", base, "added_lines", len(added), "rules", len(rules))
if diff == "" {
if err := refuseAChangeThatIsNotCommitted(ctx, tc); err != nil {
return err
}
}
var blocking []diffFinding
for _, finding := range matchDiffRules(rules, addedDiffLines(diff)) {
for _, finding := range matchDiffRules(rules, added) {
logRuleFinding(tc, finding)
if finding.Level == DiffRuleLevelError {
blocking = append(blocking, finding)
@@ -144,6 +164,43 @@ func runDiffRules(ctx context.Context, tc *TaskContext, rules []compiledDiffRule
return nil
}
// uncommittedChangeReporter is the optional capability through which a Trees
// implementation reports whether a worktree holds work no commit has captured
// yet: staged, unstaged or untracked. It is separate from the Trees contract for
// the same reason changeStatsReader is (steps.go): it is a capability one
// consumer needs, not a question every Trees implementation must answer. Both
// production implementations do answer it -- *worktree.Manager reads git, and
// hybridTrees forwards to its local manager, which is the path every production
// run takes.
type uncommittedChangeReporter interface {
HasUncommittedChanges(ctx context.Context, dir string) (bool, error)
}
// refuseAChangeThatIsNotCommitted fails the step when it read no committed
// change at all while the worktree still holds work. It is the guard the empty
// diff alone cannot provide: an empty diff is either "nothing has changed" or
// "the change is not committed yet", and only the worktree can say which.
//
// A clean worktree with nothing committed is a genuine no-op and is allowed. A
// Trees implementation that cannot answer at all is refused rather than assumed
// clean, because for a gate silence about the change is a failure, not a pass.
func refuseAChangeThatIsNotCommitted(ctx context.Context, tc *TaskContext) error {
const follow = "this step must follow the step that commits the change"
reporter, ok := tc.Trees.(uncommittedChangeReporter)
if !ok {
return fmt.Errorf("%s: no committed change to check and this worktree implementation cannot report uncommitted work: %s", DiffRulesStepName, follow)
}
uncommitted, err := reporter.HasUncommittedChanges(ctx, tc.Dir)
if err != nil {
return fmt.Errorf("%s: read uncommitted work: %w", DiffRulesStepName, err)
}
if !uncommitted {
return nil
}
return fmt.Errorf("%s: no committed change to check but the worktree holds uncommitted work: %s", DiffRulesStepName, follow)
}
// logRuleFinding records one finding under the severity of its effect -- a
// blocking finding is a warning an operator acts on, an advisory one is
// informational -- while the rule's own declared level rides along as
+117 -1
View File
@@ -261,7 +261,10 @@ func TestDiffRulesStepAppliesRulesToTheCommittedDiff(t *testing.T) {
// The removed line is at old-file line 21 and the kept comment is at
// new-file line 4: neither is something this change added.
omitDetail: []string{"main.go:21", "main.go:4:", "notes.md:1"},
wantLog: []string{"rule_level=error", "file=main.go line=3", "rule=no-new-panic"},
// added_lines=4 is the run's evidence that the rules read the change
// (two added lines in the first hunk, one in the second, one in the
// other file). A step that read nothing must not leave the same trace.
wantLog: []string{"rule_level=error", "file=main.go line=3", "rule=no-new-panic", "added_lines=4"},
},
{
name: "a warn rule is advisory",
@@ -313,6 +316,7 @@ func TestDiffRulesStepAppliesRulesToTheCommittedDiff(t *testing.T) {
diff: "",
wantParked: false,
omitLog: []string{"no-new-panic"},
wantLog: []string{"added_lines=0"},
},
}
@@ -524,3 +528,115 @@ func TestDiffRulesStepReadsARealDiff(t *testing.T) {
t.Errorf("park Detail = %q, want it to locate the added line as main.go:5", tc.Outcome.Detail)
}
}
// bareTrees is a workflow.Trees implementation that cannot report uncommitted
// work: it exposes the interface by delegation, so no optional capability rides
// along with it.
type bareTrees struct{ Trees }
// errUncommittedUnavailable is what a Trees implementation reports when it could
// not read whether the worktree holds uncommitted work.
var errUncommittedUnavailable = errors.New("status unavailable")
// TestDiffRulesStepRefusesToCheckAChangeThatIsNotCommitted is the placement
// contract. The step reads what the branch has COMMITTED, and only a worktree
// with uncommitted work left in it can tell "this change is not committed yet"
// apart from "there is no change" -- so a step placed before the step that
// commits must fail loudly rather than report no findings and let the run
// proceed, which is a gate that never looked.
func TestDiffRulesStepRefusesToCheckAChangeThatIsNotCommitted(t *testing.T) {
t.Parallel()
const rule = "rules:\n - id: no-new-panic\n level: error\n pattern: 'panic\\('\n message: new panic() call\n"
tests := []struct {
name string
diff string
uncommitted bool
uncommittedErr error
// trees overrides the fake with a variant, e.g. one that hides the
// optional capability.
trees func(*fakeTrees) Trees
wantErr []string
wantParked bool
wantLog []string
}{
{
name: "uncommitted work with no committed change is refused",
uncommitted: true,
wantErr: []string{"uncommitted", "must follow the step that commits"},
wantLog: []string{"added_lines=0"},
},
{
name: "a clean worktree with no committed change is a no-op",
wantLog: []string{"added_lines=0"},
},
{
name: "a Trees that cannot report uncommitted work is refused, not passed",
trees: func(f *fakeTrees) Trees { return bareTrees{Trees: f} },
wantErr: []string{"cannot report", "must follow the step that commits"},
},
{
name: "a failed uncommitted read is propagated",
uncommittedErr: errUncommittedUnavailable,
wantErr: []string{"uncommitted"},
},
{
name: "a committed change is checked even when the worktree is dirty",
diff: diffTwoFiles,
uncommitted: true,
wantParked: true,
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
stage, err := diffRulesStage(t, rule)
if err != nil {
t.Fatalf("factory: %v", err)
}
var log bytes.Buffer
fake := &fakeTrees{diff: test.diff, uncommitted: test.uncommitted, uncommittedErr: test.uncommittedErr}
tc := diffRulesTaskContext("", &log)
tc.Trees = fake
if test.trees != nil {
tc.Trees = test.trees(fake)
}
err = stage.Run(context.Background(), tc)
if len(test.wantErr) > 0 {
requireRefusalNaming(t, err, test.wantErr, tc.Outcome)
} else if err != nil {
t.Fatalf("stage.Run() = %v, want nil", err)
}
if test.wantParked && tc.Outcome.Status != StatusParked {
t.Errorf("Outcome = %+v, want a parked outcome for the committed violation", tc.Outcome)
}
for _, want := range test.wantLog {
if !strings.Contains(log.String(), want) {
t.Errorf("log = %q, want it to contain %q", log.String(), want)
}
}
})
}
}
// requireRefusalNaming checks the stage refused, that its error names every part
// the case expects, and that the refusal is not dressed up as a verdict: a step
// that could not check the change has no finding to park on.
func requireRefusalNaming(t *testing.T, err error, want []string, outcome Outcome) {
t.Helper()
if err == nil {
t.Fatalf("stage.Run() = nil, want the refusal naming %v", want)
}
for _, fragment := range want {
if !strings.Contains(err.Error(), fragment) {
t.Errorf("stage.Run() error = %v, want it to name %q", err, fragment)
}
}
if outcome.Status != "" {
t.Errorf("Outcome = %+v, want none: a step that cannot check the change is a stage failure, not a verdict", outcome)
}
}
@@ -463,6 +463,11 @@ type fakeTrees struct {
// change (StageReview, the diff-rules step).
diff string
diffErr error
// uncommitted and uncommittedErr are what HasUncommittedChanges reports,
// the optional capability a step that reads commits uses to tell "no
// change" from "not committed yet". The zero value is a clean worktree.
uncommitted bool
uncommittedErr error
resumed bool
resumeDir string
@@ -491,6 +496,10 @@ func (f *fakeTrees) Diff(context.Context, string, string) (string, error) { retu
func (f *fakeTrees) ChangedFiles(context.Context, string, string) ([]string, error) { return nil, nil }
func (f *fakeTrees) HasUncommittedChanges(context.Context, string) (bool, error) {
return f.uncommitted, f.uncommittedErr
}
func (f *fakeTrees) ChangedLines(context.Context, string, string) (int, error) {
return f.changedLines, nil
}
+31
View File
@@ -646,6 +646,37 @@ func (m *Manager) patchFromMergeBase(ctx context.Context, dir, base string) (*ob
return p, bases[0].Hash, nil
}
// HasUncommittedChanges reports whether the worktree holds work no commit has
// captured yet: staged, unstaged or untracked. Ignored files do not count, the
// same rule CommitAll's own status check applies when it decides whether there
// is anything to commit.
//
// It exists because Diff cannot answer this: Diff reports what the branch has
// committed against the merge base and never reads the worktree, so a stage
// that must inspect the committed change has no way to tell "nothing has
// changed" from "the change is not committed yet" without this.
func (m *Manager) HasUncommittedChanges(ctx context.Context, dir string) (bool, error) {
if err := ctx.Err(); err != nil {
return false, err
}
r, err := git.PlainOpen(dir)
if err != nil {
return false, fmt.Errorf("open worktree: %w", err)
}
wt, err := r.Worktree()
if err != nil {
return false, fmt.Errorf("open worktree: %w", err)
}
if err := ctx.Err(); err != nil {
return false, err
}
status, err := wt.Status()
if err != nil {
return false, fmt.Errorf("read status: %w", err)
}
return !status.IsClean(), nil
}
// ChangedLines reports lines added+deleted vs the base branch -- the
// input to the diff-size cap.
func (m *Manager) ChangedLines(ctx context.Context, dir, base string) (int, error) {
+90
View File
@@ -1459,3 +1459,93 @@ func TestChangedFileStatsRecordsTheDiffedBaseNotTheAdvancedTip(t *testing.T) {
}
}
}
// TestHasUncommittedChangesReportsWorkNoCommitHasCaptured pins the signal a step
// that reads the COMMITTED change uses to tell "nothing has changed" from "the
// change is not committed yet": the two are indistinguishable in the diff
// alone, and a gate that cannot tell them apart passes a change it never read.
//
// The ignored-file case is the one that keeps the signal usable: a worktree
// full of build output is clean for the purpose of "is there work to commit",
// and reporting it dirty would refuse a correctly placed gate.
func TestHasUncommittedChangesReportsWorkNoCommitHasCaptured(t *testing.T) {
ctx := context.Background()
host := newLocalRemote(t, "acme", "todo")
m := newManager(t, host)
dir, _, err := m.Prepare(ctx, "acme", "todo", testBase, 7, "feat: mine", "", "feature")
if err != nil {
t.Fatalf("Prepare() error = %v", err)
}
assertDirty := func(want bool, what string) {
t.Helper()
dirty, err := m.HasUncommittedChanges(ctx, dir)
if err != nil {
t.Fatalf("HasUncommittedChanges() error = %v (%s)", err, what)
}
if dirty != want {
t.Errorf("HasUncommittedChanges() = %v %s, want %v", dirty, what, want)
}
}
commit := func(message string) {
t.Helper()
if _, err := m.CommitAll(ctx, dir, message); err != nil {
t.Fatalf("CommitAll(%q) error = %v", message, err)
}
}
assertDirty(false, "on a freshly prepared worktree")
// An untracked file is the state a build stage leaves behind: work no commit
// has captured yet.
if err := os.WriteFile(filepath.Join(dir, "fix.txt"), []byte("fix\n"), 0o600); err != nil {
t.Fatal(err)
}
assertDirty(true, "with an untracked file")
commit("feat: fix")
assertDirty(false, "after the untracked file was committed")
// An edit to a tracked file is the same signal.
if err := os.WriteFile(filepath.Join(dir, "fix.txt"), []byte("fix changed\n"), 0o600); err != nil {
t.Fatal(err)
}
assertDirty(true, "with a modified tracked file")
// Staging it without committing it does not clear the signal.
r, err := git.PlainOpen(dir)
if err != nil {
t.Fatal(err)
}
wt, err := r.Worktree()
if err != nil {
t.Fatal(err)
}
if _, err := wt.Add("fix.txt"); err != nil {
t.Fatalf("stage fix.txt: %v", err)
}
assertDirty(true, "with a staged but uncommitted change")
commit("feat: fix changed")
assertDirty(false, "after the staged change was committed")
// Build output, ignored by the repository, is not work waiting to be
// committed. The .gitignore itself must be committed first, or it is the
// untracked file under test.
if err := os.WriteFile(filepath.Join(dir, ".gitignore"), []byte("build/\n"), 0o600); err != nil {
t.Fatal(err)
}
commit("chore: ignore build output")
if err := os.MkdirAll(filepath.Join(dir, "build"), 0o700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "build", "out.bin"), []byte("output\n"), 0o600); err != nil {
t.Fatal(err)
}
assertDirty(false, "with ignored build output in the worktree")
// A directory that is not a repository cannot answer, and must say so rather
// than report a clean worktree.
if _, err := m.HasUncommittedChanges(ctx, t.TempDir()); err == nil {
t.Error("HasUncommittedChanges() error = nil outside a repository, want the open failure")
}
}