feat(tools): fail the gate when docs cite a path that no longer exists

docs/architecture is declared authoritative for settled design, so a page that
cites code which has moved actively misleads every session and every subagent
brief that reads it. Nothing in the gate compared a prose citation against the
tree: docsgen checks the contract schema against Go types, docsite checks
generated artifacts against their Markdown sources, prdlint checks PRD writing
style. All three verify internal consistency, so a page can describe a package
deleted months ago and every check stays green -- which is how a page describing
a removed system survives behind a hand-written "removed" banner.

Add tools/docdrift. It resolves every internal/... citation under docs/ against
the tree and fails on one that dangles, handling the shapes prose actually uses:
a package with a symbol (internal/config.Config), a test with its package
(internal/app/archieui/TestFoo), a file-shape template
(internal/webui/api_<concern>.go), and a Go package pattern (internal/...).
Generated artifacts are skipped so embedded page bodies are not double-counted.

The baseline is a burn-down list of the 48 citations already broken -- packages
that moved (internal/store, internal/memory, internal/nats) and ones never built
(internal/policy, the image and research capability docs). It is not a licence:
the check also fails when an allowlisted citation starts resolving again, so an
exemption cannot outlive its reason. Regenerate with `docdrift list`.

Wire it into `task check` as docs:drift.

Also correct AGENTS.md, which listed `policy` among the cross-cutting packages
sitting under internal/. No such package has ever existed in this tree; the
design is approved and unbuilt (docs/architecture/policy.md). That is exactly
the class of stale claim this check now catches.
This commit is contained in:
sam committed 2026-10-03 00:31:06 +10:00
1 parent dd3abd2c95
commit 0ca1189a33
5 files changed
+647 -2

No files matched your search

+3 -2
View File
@@ -170,10 +170,11 @@ structures found in legacy packages.
- **Dependency Flow:** `cmd → app → {domain, infrastructure}`, with
`infrastructure → domain` implementing contracts. Downward/inward dependencies
only.
- **Cross-Cutting Packages:** `logging`, `events`, `eventbus`, `policy`,
- **Cross-Cutting Packages:** `logging`, `events`, `eventbus`,
`taskstate` sit directly under `internal/`. They may be imported by any layer,
but **must import zero internal packages**. No `shared/`, `utils/`, or
`common/` catch-alls.
`common/` catch-alls. `policy` is designed but not built
(`docs/architecture/policy.md`).
- **File Layout:** One file per API concern (`api_tasks.go`, `api_logs.go`). A
package owns its on-disk format end-to-end (e.g. `internal/logging` defines
and reads its format; transport layers do not parse).
+6
View File
@@ -61,6 +61,11 @@ tasks:
cmds:
- go -C tools run -mod=readonly ./prdlint --repo-root ..
docs:drift:
desc: Reject docs that cite a repository path which no longer exists
cmds:
- go -C tools run -mod=readonly ./docdrift check --repo-root ..
news:
desc: Regenerate the release data artifacts from the changelog
cmds:
@@ -300,6 +305,7 @@ tasks:
- task: proto:lint
- task: docs:check
- task: docs:prds
- task: docs:drift
- task: news:check
- task: docs:artifact:check
- task: vet
+53
View File
@@ -0,0 +1,53 @@
# docdrift baseline: citations in docs/ that no longer resolve to a
# repository path. This is a burn-down list, not a licence -- repoint the
# citation or delete the claim, then remove the line. Regenerate with:
#
# go -C tools run -mod=readonly ./docdrift list --repo-root .. > tools/docdrift/baseline.txt
internal/nats
internal/infrastructure/spec
internal/policy
internal/store
internal/domain/controlplane
internal/memory
internal/memory/builtin.Store
internal/app/archied/config_update.go
internal/domain/plugin
internal/curator
internal/infrastructure/forge
internal/workflow
internal/domain/eda/forgeaction
internal/app/agentworker/review.go
internal/tools/dispatch.go
internal/infrastructure/cronstore
internal/output/report.go
internal/actors/mine.go
internal/domain/research
internal/infrastructure/research/search
internal/tools/search
internal/tools/research
internal/infrastructure/research
internal/domain/workflow/wfeval/yaegi.go
internal/gate/gateeval/yaegi.go
internal/store/events.go
internal/store/captures.go
internal/domain/extensions
internal/domain/extensions/inventory.go
internal/webui/api_extensions.go
internal/app/archied/server.go
internal/infrastructure/image
internal/infrastructure/image/comfyui
internal/app/archied/telegram_setup.go
internal/tools/image/tool.go
internal/infrastructure/image/openai
internal/memory/manager.go
internal/memory/scanner.go
internal/tools/provider/memory
internal/infrastructure/legacyread
internal/domain/eda/module/notify/types.go
internal/domain/eda/module/notify
internal/memory.MemoryProvider
internal/memory.Manager
internal/infrastructure/store
internal/store/interface.go
internal/storerpc
internal/store/store.go
+362
View File
@@ -0,0 +1,362 @@
// Command docdrift rejects documentation that cites a repository path which no
// longer exists.
//
// A page under docs/ states a design, a contract, or a decision, and cites the
// code that carries it. When that code moves or is deleted the sentence
// survives unchanged: it still reads as authoritative, and every session told
// to treat docs/architecture as settled design pays for it. Nothing else in the
// gate compares a prose citation against the tree. docsgen checks the contract
// schema against Go types, docsite checks generated artifacts against their
// Markdown sources, prdlint checks PRD writing style. All three verify internal
// consistency, so a page can describe a package deleted months ago and every
// check stays green -- which is how a page describing a removed system survives
// behind a hand-written "removed" banner.
//
// The baseline is a burn-down list, not a licence. A citation listed there is
// known debt: repoint it or delete the claim, then remove the line. The check
// fails when an allowlisted citation starts resolving again, so the list cannot
// quietly outlive its reasons.
package main
import (
"bufio"
"errors"
"flag"
"fmt"
"io"
"io/fs"
"os"
"path/filepath"
"regexp"
"sort"
"strings"
"unicode"
"unicode/utf8"
)
const (
defaultDir = "docs"
defaultBaseline = "tools/docdrift/baseline.txt"
)
// citationRE matches a repository path cited in prose. The character class
// stops at backticks, brackets, commas and whitespace, so Markdown around the
// citation does not leak into the match.
var citationRE = regexp.MustCompile(`\binternal/[A-Za-z0-9_./-]+`)
// suffixRE strips the line-number suffix some older prose carries.
var suffixRE = regexp.MustCompile(`:\d+$`)
// citation is one prose reference to a repository path.
type citation struct {
Path string // normalized, e.g. internal/config, internal/daemon/daemon.go
File string // repo-relative file it appears in
Line int // 1-based
}
func (c citation) String() string {
return fmt.Sprintf("%s:%d: %s", c.File, c.Line, c.Path)
}
// analysis is the outcome of comparing the tree against the baseline.
type analysis struct {
newDrift []citation // unresolvable and not allowlisted
stale []string // allowlisted but resolving again
unused []string // allowlisted but no longer cited anywhere
known int // unresolvable and allowlisted
scanned int // citations that do resolve
citedFile int // files containing at least one citation
}
func main() {
args := os.Args[1:]
mode := "check"
if len(args) > 0 && !strings.HasPrefix(args[0], "-") {
mode = args[0]
args = args[1:]
}
flags := flag.NewFlagSet("docdrift", flag.ContinueOnError)
flags.SetOutput(io.Discard)
repoRoot := flags.String("repo-root", "..", "path to the Archie repository root")
dir := flags.String("dir", defaultDir, "directory to scan, relative to the repository root")
baselinePath := flags.String("baseline", defaultBaseline, "baseline file, relative to the repository root")
if err := flags.Parse(args); err != nil {
fmt.Fprintf(os.Stderr, "docdrift: %v\n", err)
os.Exit(2)
}
if extra := flags.Args(); len(extra) > 0 {
fmt.Fprintf(os.Stderr, "docdrift: unexpected argument %q\n", extra[0])
os.Exit(2)
}
root, err := filepath.Abs(*repoRoot)
if err != nil {
fmt.Fprintf(os.Stderr, "docdrift: %v\n", err)
os.Exit(2)
}
switch mode {
case "check":
if err := runCheck(root, *dir, filepath.Join(root, *baselinePath)); err != nil {
fmt.Fprintf(os.Stderr, "docdrift: %v\n", err)
os.Exit(2)
}
case "list":
if err := runList(root, *dir); err != nil {
fmt.Fprintf(os.Stderr, "docdrift: %v\n", err)
os.Exit(2)
}
default:
fmt.Fprintf(os.Stderr, "docdrift: unknown mode %q (want check or list)\n", mode)
os.Exit(2)
}
}
// runCheck reports new drift and stale baseline entries, exiting 1 on either.
func runCheck(root, dir, baselinePath string) error {
baseline, err := readBaseline(baselinePath)
if err != nil {
return err
}
result, err := analyse(root, dir, baseline)
if err != nil {
return err
}
for _, c := range result.newDrift {
fmt.Fprintf(os.Stderr, "new drift: %s\n", c)
}
for _, p := range result.stale {
fmt.Fprintf(os.Stderr, "stale baseline entry (now resolves, remove it): %s\n", p)
}
for _, p := range result.unused {
fmt.Fprintf(os.Stderr, "note: baseline entry no longer cited anywhere: %s\n", p)
}
if len(result.newDrift) == 0 && len(result.stale) == 0 {
fmt.Printf("docdrift: %d cited file(s), %d resolving citation(s), %d known-debt citation(s)\n",
result.citedFile, result.scanned, result.known)
return nil
}
fmt.Fprintf(os.Stderr,
"\ndocdrift: %d new dangling citation(s), %d stale baseline entry(ies).\n"+
"Repoint the citation at the code that carries it now, delete the claim it\n"+
"supported, or -- only for a path that is knowingly gone -- add it to %s\n"+
"with the reason in the commit message.\n",
len(result.newDrift), len(result.stale), defaultBaseline)
os.Exit(1)
return nil
}
// runList prints the current debt in baseline format, for regeneration.
func runList(root, dir string) error {
cites, err := scan(root, dir)
if err != nil {
return err
}
fmt.Println("# docdrift baseline: citations in docs/ that no longer resolve to a")
fmt.Println("# repository path. This is a burn-down list, not a licence -- repoint the")
fmt.Println("# citation or delete the claim, then remove the line. Regenerate with:")
fmt.Println("#")
fmt.Println("# go -C tools run -mod=readonly ./docdrift list --repo-root .. > tools/docdrift/baseline.txt")
seen := map[string]bool{}
for _, c := range cites {
if seen[c.Path] || resolves(root, c.Path) {
continue
}
seen[c.Path] = true
fmt.Println(c.Path)
}
return nil
}
// analyse compares every citation in dir against the tree and the baseline.
func analyse(root, dir string, baseline map[string]bool) (analysis, error) {
cites, err := scan(root, dir)
if err != nil {
return analysis{}, err
}
var out analysis
unresolved := map[string]bool{}
files := map[string]bool{}
for _, c := range cites {
files[c.File] = true
if resolves(root, c.Path) {
out.scanned++
continue
}
unresolved[c.Path] = true
if baseline[c.Path] {
out.known++
continue
}
out.newDrift = append(out.newDrift, c)
}
out.citedFile = len(files)
for p := range baseline {
switch {
case resolves(root, p):
out.stale = append(out.stale, p)
case !unresolved[p]:
out.unused = append(out.unused, p)
}
}
sort.Strings(out.stale)
sort.Strings(out.unused)
return out, nil
}
// scan collects every citation in the Markdown files under dir.
func scan(root, dir string) ([]citation, error) {
base := filepath.Join(root, dir)
var out []citation
err := filepath.WalkDir(base, func(path string, d fs.DirEntry, err error) error {
if err != nil {
return err
}
if d.IsDir() {
// Generated artifacts embed page bodies; scanning them would
// double-count every citation they carry.
if d.Name() == "generated" || d.Name() == ".git" || d.Name() == "node_modules" {
return fs.SkipDir
}
return nil
}
if !strings.HasSuffix(d.Name(), ".md") {
return nil
}
return scanFile(root, path, &out)
})
if errors.Is(err, fs.ErrNotExist) {
return nil, fmt.Errorf("scan %s: %w", dir, err)
}
return out, err
}
// scanFile appends every citation found in one file, with its line number.
func scanFile(root, path string, out *[]citation) error {
f, err := os.Open(path)
if err != nil {
return err
}
defer f.Close()
rel, err := filepath.Rel(root, path)
if err != nil {
rel = path
}
scanner := bufio.NewScanner(f)
scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
for line := 1; scanner.Scan(); line++ {
for _, raw := range citationRE.FindAllString(scanner.Text(), -1) {
p := normalize(raw)
if p == "" {
continue
}
*out = append(*out, citation{Path: p, File: rel, Line: line})
}
}
return scanner.Err()
}
// normalize strips the Markdown and Go-pattern decoration a prose citation
// carries, leaving a repository path.
func normalize(raw string) string {
s := strings.TrimRight(raw, ".,;:/")
s = strings.TrimSuffix(s, "/...")
s = suffixRE.ReplaceAllString(s, "")
return strings.TrimRight(s, ".,;:/")
}
// resolves reports whether a citation names something that exists in the tree:
// a file, a directory, or a package directory cited with a symbol attached.
func resolves(root, path string) bool {
for _, c := range candidates(path) {
if c == "" {
continue
}
if _, err := os.Stat(filepath.Join(root, c)); err == nil {
return true
}
if _, err := os.Stat(filepath.Join(root, c+".go")); err == nil {
return true
}
if prefixMatch(root, c) {
return true
}
}
return false
}
// prefixMatch reports whether a citation names a file shape rather than a file.
// `internal/webui/api_<concern>.go` documents a naming convention: the angle
// bracket ends the path token, leaving a truncated final segment. It is
// satisfied when a sibling starts with that segment.
func prefixMatch(root, path string) bool {
dir, base := filepath.Split(path)
if !strings.HasSuffix(base, "_") {
return false
}
entries, err := os.ReadDir(filepath.Join(root, dir))
if err != nil {
return false
}
for _, e := range entries {
if strings.HasPrefix(e.Name(), base) {
return true
}
}
return false
}
// candidates lists the paths a citation could mean: itself, itself with a
// trailing ".Symbol" dropped (a package cited together with a type or
// function), and itself with a trailing "/Symbol" dropped (a test or function
// cited with its package).
func candidates(path string) []string {
out := []string{path}
if strings.HasSuffix(path, ".go") {
return out
}
if i := strings.LastIndex(path, "."); i > strings.LastIndex(path, "/") {
out = append(out, path[:i])
}
if i := strings.LastIndex(path, "/"); i > 0 && isSymbolSegment(path[i+1:]) {
out = append(out, path[:i])
}
return out
}
// isSymbolSegment reports whether a path segment names a Go identifier rather
// than a package directory.
func isSymbolSegment(seg string) bool {
if seg == "" {
return false
}
r, _ := utf8.DecodeRuneInString(seg)
return unicode.IsUpper(r)
}
// readBaseline loads the allowlist: one citation per line, "#" comments.
func readBaseline(path string) (map[string]bool, error) {
f, err := os.Open(path)
if err != nil {
if errors.Is(err, fs.ErrNotExist) {
return map[string]bool{}, nil
}
return nil, err
}
defer f.Close()
out := map[string]bool{}
scanner := bufio.NewScanner(f)
for scanner.Scan() {
line := strings.TrimSpace(scanner.Text())
if line == "" || strings.HasPrefix(line, "#") {
continue
}
out[line] = true
}
return out, scanner.Err()
}
+223
View File
@@ -0,0 +1,223 @@
package main
import (
"os"
"path/filepath"
"testing"
)
func TestNormalize(t *testing.T) {
tests := []struct {
name string
in string
want string
}{
{"bare package", "internal/config", "internal/config"},
{"trailing slash", "internal/policy/", "internal/policy"},
{"file", "internal/daemon/daemon.go", "internal/daemon/daemon.go"},
{"go wildcard", "internal/infrastructure/...", "internal/infrastructure"},
{"package and symbol", "internal/config.Config", "internal/config.Config"},
{"sentence punctuation", "internal/store,", "internal/store"},
{"line number", "internal/store/store.go:120", "internal/store/store.go"},
{"deep wildcard", "internal/domain/...", "internal/domain"},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
if got := normalize(tc.in); got != tc.want {
t.Fatalf("normalize(%q) = %q, want %q", tc.in, got, tc.want)
}
})
}
}
func TestCandidates(t *testing.T) {
tests := []struct {
name string
in string
want []string
}{
{"package with symbol drops the symbol", "internal/config.Config", []string{"internal/config.Config", "internal/config"}},
{"file keeps only itself", "internal/daemon/daemon.go", []string{"internal/daemon/daemon.go"}},
{"bare package", "internal/webui", []string{"internal/webui"}},
{"dotted directory is not a symbol", "internal/domain/eda/module", []string{"internal/domain/eda/module"}},
{"test cited with its package drops the test name", "internal/app/archieui/TestFoo", []string{"internal/app/archieui/TestFoo", "internal/app/archieui"}},
{"lowercase final segment is a package, not a symbol", "internal/domain/curator", []string{"internal/domain/curator"}},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
got := candidates(tc.in)
if len(got) != len(tc.want) {
t.Fatalf("candidates(%q) = %v, want %v", tc.in, got, tc.want)
}
for i := range got {
if got[i] != tc.want[i] {
t.Fatalf("candidates(%q) = %v, want %v", tc.in, got, tc.want)
}
}
})
}
}
// tree builds a throwaway repository root with the given files and directories.
func tree(t *testing.T, files, dirs []string) string {
t.Helper()
root := t.TempDir()
for _, d := range dirs {
if err := os.MkdirAll(filepath.Join(root, d), 0o750); err != nil {
t.Fatal(err)
}
}
for _, f := range files {
p := filepath.Join(root, f)
if err := os.MkdirAll(filepath.Dir(p), 0o750); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(p, []byte("package x\n"), 0o600); err != nil {
t.Fatal(err)
}
}
return root
}
func TestResolves(t *testing.T) {
root := tree(t,
[]string{"internal/config/config.go", "internal/daemon/daemon.go", "internal/webui/api_logs.go"},
[]string{"internal/webui", "internal/domain/workflow", "internal/app/archieui"},
)
tests := []struct {
name string
in string
want bool
}{
{"package directory", "internal/webui", true},
{"nested package directory", "internal/domain/workflow", true},
{"file", "internal/daemon/daemon.go", true},
{"package and symbol resolves via the package", "internal/config.Config", true},
{"package cited without the .go file present", "internal/daemon", true},
{"moved package", "internal/memory", false},
{"deleted file", "internal/app/archied/config_update.go", false},
{"never built", "internal/policy", false},
{"whole package tree", "internal", true},
{"file-shape template resolves against a sibling", "internal/webui/api_", true},
{"test cited with its package resolves via the package", "internal/app/archieui/TestComposeUIServerHoldsNoDaemonState", true},
{"file-shape template with no sibling", "internal/webui/nothing_", false},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
if got := resolves(root, tc.in); got != tc.want {
t.Fatalf("resolves(%q) = %v, want %v", tc.in, got, tc.want)
}
})
}
}
// TestAnalyseSeparatesNewDriftFromKnownDebt pins the gate's core distinction: a
// citation already broken before this change must not fail the build, while one
// that dangles now must.
func TestAnalyseSeparatesNewDriftFromKnownDebt(t *testing.T) {
root := tree(t,
[]string{"internal/config/config.go"},
[]string{"internal/webui"},
)
doc := filepath.Join(root, "docs", "architecture")
if err := os.MkdirAll(doc, 0o750); err != nil {
t.Fatal(err)
}
body := "See `internal/webui` and `internal/memory`.\nAlso `internal/nats` and `internal/config`.\n"
if err := os.WriteFile(filepath.Join(doc, "page.md"), []byte(body), 0o600); err != nil {
t.Fatal(err)
}
got, err := analyse(root, "docs", map[string]bool{"internal/memory": true})
if err != nil {
t.Fatal(err)
}
if len(got.newDrift) != 1 || got.newDrift[0].Path != "internal/nats" {
t.Fatalf("newDrift = %v, want exactly internal/nats", got.newDrift)
}
if got.newDrift[0].Line != 2 {
t.Fatalf("newDrift line = %d, want 2", got.newDrift[0].Line)
}
if got.known != 1 {
t.Fatalf("known = %d, want 1 (internal/memory is allowlisted)", got.known)
}
if got.scanned != 2 {
t.Fatalf("scanned = %d, want 2 (internal/webui, internal/config)", got.scanned)
}
if len(got.stale) != 0 {
t.Fatalf("stale = %v, want none", got.stale)
}
}
// TestAnalyseFlagsAnAllowlistEntryThatResolvesAgain keeps the burn-down list
// honest: once the code comes back, the exemption must go.
func TestAnalyseFlagsAnAllowlistEntryThatResolvesAgain(t *testing.T) {
root := tree(t, []string{"internal/config/config.go"}, []string{"internal/webui", "internal/policy"})
if err := os.MkdirAll(filepath.Join(root, "docs"), 0o750); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(root, "docs", "p.md"), []byte("`internal/policy`\n"), 0o600); err != nil {
t.Fatal(err)
}
got, err := analyse(root, "docs", map[string]bool{"internal/policy": true})
if err != nil {
t.Fatal(err)
}
if len(got.stale) != 1 || got.stale[0] != "internal/policy" {
t.Fatalf("stale = %v, want [internal/policy]", got.stale)
}
if len(got.newDrift) != 0 {
t.Fatalf("newDrift = %v, want none", got.newDrift)
}
}
// TestScanSkipsGeneratedAndNonMarkdown guards the double-count: the generated
// dev-docs artifact embeds every page body, so scanning it would inflate both
// the findings and the baseline.
func TestScanSkipsGeneratedAndNonMarkdown(t *testing.T) {
root := tree(t, nil, []string{"docs/architecture", "docs/data/generated"})
write := func(rel, body string) {
if err := os.WriteFile(filepath.Join(root, rel), []byte(body), 0o600); err != nil {
t.Fatal(err)
}
}
write("docs/architecture/page.md", "`internal/gone`\n")
write("docs/data/generated/dev-docs.json", "{\"body\":\"internal/also-gone\"}\n")
write("docs/notes.txt", "internal/not-markdown\n")
got, err := scan(root, "docs")
if err != nil {
t.Fatal(err)
}
if len(got) != 1 || got[0].Path != "internal/gone" {
t.Fatalf("scan = %v, want exactly [internal/gone]", got)
}
}
func TestReadBaseline(t *testing.T) {
root := t.TempDir()
p := filepath.Join(root, "baseline.txt")
body := "# a comment\n\ninternal/store\ninternal/memory \n"
if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
t.Fatal(err)
}
got, err := readBaseline(p)
if err != nil {
t.Fatal(err)
}
if len(got) != 2 || !got["internal/store"] || !got["internal/memory"] {
t.Fatalf("readBaseline = %v, want internal/store and internal/memory", got)
}
}
// TestReadBaselineMissingIsEmpty lets the tool run before a baseline exists.
func TestReadBaselineMissingIsEmpty(t *testing.T) {
got, err := readBaseline(filepath.Join(t.TempDir(), "absent.txt"))
if err != nil {
t.Fatal(err)
}
if len(got) != 0 {
t.Fatalf("readBaseline = %v, want empty", got)
}
}