|
| 1 | +package docsclaims |
| 2 | + |
| 3 | +import ( |
| 4 | + "io/fs" |
| 5 | + "os" |
| 6 | + "path/filepath" |
| 7 | + "regexp" |
| 8 | + "strings" |
| 9 | + "testing" |
| 10 | +) |
| 11 | + |
| 12 | +// A falsified is one absolute the code has already made false, plus the way a |
| 13 | +// document is allowed to keep saying it: conditioned. |
| 14 | +// |
| 15 | +// - absolute is the phrasing that is false on its own. |
| 16 | +// - qualifier is what must appear close after it for the sentence to be true. |
| 17 | +// A document that never says the absolute at all is never a finding — this |
| 18 | +// guard has no opinion about what a document must contain. |
| 19 | +// - address is the code that falsifies it, carried into the failure message |
| 20 | +// so whoever reads the failure can retrace it instead of trusting it. |
| 21 | +type falsified struct { |
| 22 | + name string |
| 23 | + absolute *regexp.Regexp |
| 24 | + qualifier *regexp.Regexp |
| 25 | + address string |
| 26 | +} |
| 27 | + |
| 28 | +// How far after the absolute the qualifier may sit, in whitespace-normalised |
| 29 | +// bytes. Wide enough for a qualifier pushed onto the next wrapped line, narrow |
| 30 | +// enough that a mention elsewhere in the paragraph does not launder it. |
| 31 | +const qualifierWindow = 200 |
| 32 | + |
| 33 | +// optIn is the flag ADR 0032 shipped; naming it is what conditions both claims. |
| 34 | +var optIn = regexp.MustCompile(`--accept-loaded-user-config`) |
| 35 | + |
| 36 | +// The two absolutes ADR 0032 falsified. d537739 conditioned both where they |
| 37 | +// stood in docs/EXAMPLES.md (:451, :460 today); they are encoded here so that |
| 38 | +// no document — that one or a new one — can state either as an absolute again. |
| 39 | +var falsifiedByADR0032 = []falsified{ |
| 40 | + { |
| 41 | + name: `"no planned node gets that any more"`, |
| 42 | + absolute: regexp.MustCompile(`no planned node gets that any more`), |
| 43 | + qualifier: optIn, |
| 44 | + address: "internal/coordinator/coordinator.go:763-764 — toolPolicyFor sets " + |
| 45 | + "policy.SettingSources = nil when the run typed --accept-loaded-user-config, " + |
| 46 | + "so every planned node of such a run does get the operator's configuration", |
| 47 | + }, |
| 48 | + { |
| 49 | + name: "\"as every planned node's always has\", of `--strict-mcp-config`", |
| 50 | + absolute: regexp.MustCompile(`every planned node('s)? always has`), |
| 51 | + qualifier: optIn, |
| 52 | + address: "internal/coordinator/coordinator.go:765 sets policy.StrictMCPConfig = false " + |
| 53 | + "under --accept-loaded-user-config, and internal/runner/claude_protocol.go:55-56 " + |
| 54 | + "emits --strict-mcp-config only when it is true, so such a node's argv carries none", |
| 55 | + }, |
| 56 | +} |
| 57 | + |
| 58 | +// expectedRoots is asserted PRESENT in the walk — it is never used to select |
| 59 | +// what gets scanned. Scanning follows the walk, so a document that lands under |
| 60 | +// docs/ or plugin/ tomorrow is scanned tomorrow with no edit here; this list |
| 61 | +// only fails the day the walk stops reaching a document it used to reach. |
| 62 | +var expectedRoots = []string{ |
| 63 | + "README.md", |
| 64 | + "README.ko.md", |
| 65 | + "DESIGN.md", |
| 66 | + "SECURITY.md", |
| 67 | + "CONTRIBUTING.md", |
| 68 | + "CHANGELOG.md", |
| 69 | + "docs/EXAMPLES.md", |
| 70 | + "docs/LIMITATIONS.md", |
| 71 | + "docs/INSTALL.md", |
| 72 | + "docs/adr/0032-a-planned-node-may-carry-the-operators-configuration.md", |
| 73 | + "plugin/README.md", |
| 74 | + "plugin/commands/graph.md", |
| 75 | + "plugin/agents/oh-my-graph.md", |
| 76 | + "plugin/skills/run-graph/SKILL.md", |
| 77 | +} |
| 78 | + |
| 79 | +// walkedSubtrees is the scope, not a file list: every Markdown file at the |
| 80 | +// repository root, and every Markdown file anywhere under these. |
| 81 | +var walkedSubtrees = []string{"docs", "plugin"} |
| 82 | + |
| 83 | +type finding struct { |
| 84 | + line int |
| 85 | + claim falsified |
| 86 | + quote string |
| 87 | +} |
| 88 | + |
| 89 | +func TestDocSetIsWalkedAndReachesEveryExpectedRoot(t *testing.T) { |
| 90 | + root := repoRoot(t) |
| 91 | + docs := docSet(t, root) |
| 92 | + |
| 93 | + found := make(map[string]bool, len(docs)) |
| 94 | + for _, rel := range docs { |
| 95 | + found[rel] = true |
| 96 | + } |
| 97 | + for _, want := range expectedRoots { |
| 98 | + if !found[want] { |
| 99 | + t.Errorf("the walk no longer reaches %s (%d documents found). "+ |
| 100 | + "A guard that scans nothing passes; fix the walk, do not shrink this list.", |
| 101 | + want, len(docs)) |
| 102 | + } |
| 103 | + } |
| 104 | +} |
| 105 | + |
| 106 | +func TestScanFiresOnTheAbsoluteAndNotOnTheConditionedForm(t *testing.T) { |
| 107 | + cases := []struct { |
| 108 | + name string |
| 109 | + text string |
| 110 | + want int |
| 111 | + }{ |
| 112 | + { |
| 113 | + // docs/EXAMPLES.md:457-458 as it stood before d537739, verbatim. |
| 114 | + name: "the absolute, as it shipped", |
| 115 | + text: "what declining buys: it does **not** hand the node your environment back,\n" + |
| 116 | + "because no planned node gets that any more. `--no-agent-mapping` remains the\n", |
| 117 | + want: 1, |
| 118 | + }, |
| 119 | + { |
| 120 | + name: "the same claim, conditioned", |
| 121 | + text: "because no planned node gets that any more — unless the run typed\n" + |
| 122 | + "`--accept-loaded-user-config`, in which case every planned node has it\n", |
| 123 | + want: 0, |
| 124 | + }, |
| 125 | + { |
| 126 | + name: "the strict-mcp-config absolute, wrapped across lines", |
| 127 | + text: "(Its argv also carries `--strict-mcp-config`, as every planned node's\n" + |
| 128 | + "always has; whether that closes MCP is unmeasured.)\n", |
| 129 | + want: 1, |
| 130 | + }, |
| 131 | + { |
| 132 | + name: "the same claim, conditioned", |
| 133 | + text: "(Its argv also carries `--strict-mcp-config`, as every planned node's always\n" + |
| 134 | + "has unless the run typed `--accept-loaded-user-config`, which drops it.)\n", |
| 135 | + want: 0, |
| 136 | + }, |
| 137 | + { |
| 138 | + // Requirement 3: absence is never a failure. This document states |
| 139 | + // neither claim, mentions neither flag, and must be silent. |
| 140 | + name: "a document that claims nothing at all", |
| 141 | + text: "# Install\n\n`go install github.com/jitokim/oh-my-graph/cmd/oh-my-graph@latest`\n", |
| 142 | + want: 0, |
| 143 | + }, |
| 144 | + } |
| 145 | + |
| 146 | + for _, tc := range cases { |
| 147 | + t.Run(tc.name, func(t *testing.T) { |
| 148 | + got := scan([]byte(tc.text)) |
| 149 | + if len(got) != tc.want { |
| 150 | + t.Fatalf("scan found %d finding(s), want %d: %+v", len(got), tc.want, got) |
| 151 | + } |
| 152 | + }) |
| 153 | + } |
| 154 | +} |
| 155 | + |
| 156 | +func TestNoDocumentStatesAnAbsoluteADR0032Falsified(t *testing.T) { |
| 157 | + root := repoRoot(t) |
| 158 | + for _, rel := range docSet(t, root) { |
| 159 | + raw, err := os.ReadFile(filepath.Join(root, rel)) |
| 160 | + if err != nil { |
| 161 | + t.Fatalf("read %s: %v", rel, err) |
| 162 | + } |
| 163 | + for _, f := range scan(raw) { |
| 164 | + t.Errorf("%s:%d states %s unconditionally.\n quoted: %q\n falsified by: %s\n"+ |
| 165 | + " Condition it on --accept-loaded-user-config, or drop it.", |
| 166 | + rel, f.line, f.claim.name, f.quote, f.claim.address) |
| 167 | + } |
| 168 | + } |
| 169 | +} |
| 170 | + |
| 171 | +// scan reports every absolute stated in raw with nothing conditioning it. |
| 172 | +func scan(raw []byte) []finding { |
| 173 | + text, offsets := normalize(raw) |
| 174 | + var findings []finding |
| 175 | + for _, claim := range falsifiedByADR0032 { |
| 176 | + for _, m := range claim.absolute.FindAllStringIndex(text, -1) { |
| 177 | + end := m[1] + qualifierWindow |
| 178 | + if end > len(text) { |
| 179 | + end = len(text) |
| 180 | + } |
| 181 | + if claim.qualifier.MatchString(text[m[1]:end]) { |
| 182 | + continue |
| 183 | + } |
| 184 | + quoteEnd := m[1] + 60 |
| 185 | + if quoteEnd > len(text) { |
| 186 | + quoteEnd = len(text) |
| 187 | + } |
| 188 | + findings = append(findings, finding{ |
| 189 | + line: lineOf(raw, offsets[m[0]]), |
| 190 | + claim: claim, |
| 191 | + quote: text[m[0]:quoteEnd], |
| 192 | + }) |
| 193 | + } |
| 194 | + } |
| 195 | + return findings |
| 196 | +} |
| 197 | + |
| 198 | +// normalize collapses every run of whitespace to one space, so a claim the |
| 199 | +// author wrapped across two lines still reads as one sentence. It returns the |
| 200 | +// offset in raw of each byte it kept, which is what turns a match back into a |
| 201 | +// line number. |
| 202 | +func normalize(raw []byte) (string, []int) { |
| 203 | + var b strings.Builder |
| 204 | + offsets := make([]int, 0, len(raw)) |
| 205 | + prevSpace := false |
| 206 | + for i, c := range raw { |
| 207 | + if c == ' ' || c == '\t' || c == '\n' || c == '\r' { |
| 208 | + if prevSpace { |
| 209 | + continue |
| 210 | + } |
| 211 | + b.WriteByte(' ') |
| 212 | + offsets = append(offsets, i) |
| 213 | + prevSpace = true |
| 214 | + continue |
| 215 | + } |
| 216 | + b.WriteByte(c) |
| 217 | + offsets = append(offsets, i) |
| 218 | + prevSpace = false |
| 219 | + } |
| 220 | + return b.String(), offsets |
| 221 | +} |
| 222 | + |
| 223 | +func lineOf(raw []byte, offset int) int { |
| 224 | + return 1 + strings.Count(string(raw[:offset]), "\n") |
| 225 | +} |
| 226 | + |
| 227 | +// docSet derives the documents to scan: every *.md at the repository root, and |
| 228 | +// every *.md under each walked subtree. Nothing is excluded, because an |
| 229 | +// exclusion is the shape of the miss this guard exists to stop. |
| 230 | +func docSet(t *testing.T, root string) []string { |
| 231 | + t.Helper() |
| 232 | + |
| 233 | + entries, err := os.ReadDir(root) |
| 234 | + if err != nil { |
| 235 | + t.Fatalf("read repository root %s: %v", root, err) |
| 236 | + } |
| 237 | + var docs []string |
| 238 | + for _, e := range entries { |
| 239 | + if !e.IsDir() && strings.HasSuffix(e.Name(), ".md") { |
| 240 | + docs = append(docs, e.Name()) |
| 241 | + } |
| 242 | + } |
| 243 | + |
| 244 | + for _, sub := range walkedSubtrees { |
| 245 | + err := filepath.WalkDir(filepath.Join(root, sub), func(path string, d fs.DirEntry, err error) error { |
| 246 | + if err != nil { |
| 247 | + return err |
| 248 | + } |
| 249 | + if d.IsDir() || !strings.HasSuffix(d.Name(), ".md") { |
| 250 | + return nil |
| 251 | + } |
| 252 | + rel, err := filepath.Rel(root, path) |
| 253 | + if err != nil { |
| 254 | + return err |
| 255 | + } |
| 256 | + docs = append(docs, filepath.ToSlash(rel)) |
| 257 | + return nil |
| 258 | + }) |
| 259 | + if err != nil { |
| 260 | + t.Fatalf("walk %s: %v", sub, err) |
| 261 | + } |
| 262 | + } |
| 263 | + return docs |
| 264 | +} |
| 265 | + |
| 266 | +func repoRoot(t *testing.T) string { |
| 267 | + t.Helper() |
| 268 | + |
| 269 | + root, err := filepath.Abs(filepath.Join("..", "..")) |
| 270 | + if err != nil { |
| 271 | + t.Fatalf("resolve repository root: %v", err) |
| 272 | + } |
| 273 | + if _, err := os.Stat(filepath.Join(root, "go.mod")); err != nil { |
| 274 | + t.Fatalf("no go.mod at %s — this guard is scanning the wrong tree: %v", root, err) |
| 275 | + } |
| 276 | + return root |
| 277 | +} |
0 commit comments