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:
1 parent
dd3abd2c95
commit
0ca1189a33
5 files changed
+647
-2
No files matched your search
@@ -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).
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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()
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user