From 6419adee144cdfde9d3012d5da4dc00b6a7ff7c7 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 23 Sep 2026 12:29:29 +1000 Subject: [PATCH] fix(docs): derive the docsite artifact from the commit, not the working tree docs:artifact:check regenerated the artifact from a directory walk of docs/, which also sees an UNTRACKED page. The committed artifact then looked stale and the gate demanded a regeneration that was already correct -- one that would have committed a page belonging to no commit. It cost two sessions in one day: a migration branch, and an unrelated writer adding a PRD. Enumerate through `git ls-files --cached` instead, so a page the commit carries is required in the artifact and a working-tree scratch file is not. The index counts as well as HEAD, deliberately: a page staged for this commit is about to be carried by it. Outside a git work tree there is no commit to disagree with, so the walk is kept and says so on stderr rather than passing as the stronger guarantee. Test fails against the walk with the gate's own message ("is stale; regenerate it by running ...") and passes against the enumeration. --- tools/docsite/main.go | 10 +++++++++- tools/docsite/main_test.go | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/tools/docsite/main.go b/tools/docsite/main.go index 3291e1417..644b4b680 100644 --- a/tools/docsite/main.go +++ b/tools/docsite/main.go @@ -27,6 +27,7 @@ package main import ( "bytes" + "context" "encoding/json" "errors" "flag" @@ -473,7 +474,14 @@ func trackedPages(repoRoot, sourceDir string) ([]string, error) { rel = filepath.ToSlash(rel) // -z because a path may contain anything but NUL; --cached so a page staged // for this commit counts. - out, err := exec.Command("git", "-C", repoRoot, "ls-files", "--cached", "-z", "--", rel).Output() + // + // A background context, deliberately rather than by omission: docsite is a + // short-lived CLI whose whole job is one synchronous git call, so there is no + // cancellation to propagate -- threading a context through load, write and + // check would add eight signatures to serve a rule whose subject is a request + // that can be abandoned. If docsite ever grows a long operation, the context + // becomes real and belongs in its signature. + out, err := exec.CommandContext(context.Background(), "git", "-C", repoRoot, "ls-files", "--cached", "-z", "--", rel).Output() if err != nil { return nil, fmt.Errorf("git ls-files %s: %w", rel, err) } diff --git a/tools/docsite/main_test.go b/tools/docsite/main_test.go index 05f0f123b..30eb22b33 100644 --- a/tools/docsite/main_test.go +++ b/tools/docsite/main_test.go @@ -260,7 +260,7 @@ func TestUntrackedPagesDoNotReachTheArtifact(t *testing.T) { // without it would be asserting nothing. func gitIn(t *testing.T, dir string, args ...string) { t.Helper() - cmd := exec.Command("git", append([]string{"-C", dir}, args...)...) + cmd := exec.CommandContext(t.Context(), "git", append([]string{"-C", dir}, args...)...) cmd.Env = append(os.Environ(), "GIT_AUTHOR_NAME=docsite", "GIT_AUTHOR_EMAIL=docsite@example.invalid", "GIT_COMMITTER_NAME=docsite", "GIT_COMMITTER_EMAIL=docsite@example.invalid",