@allansantos-dev/smart-tool 0.9.61 → 0.9.65

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,717 @@
1
+ """Self-validation of the generated documentation scope: every claim the pages make is checked against the code, the
2
+ code graph, the command lines the code declares and the manifests, and the result is written as a pass/fail report
3
+ with the evidence of each check (docs/scope/validation.md).
4
+
5
+ Checks, in three groups:
6
+
7
+ - code to technical: signature markers, links, line claims, callers/calls/tests lists, coverage and its numbers;
8
+ - functional to product: entry points and their flows, the features a launcher runs (`__main__` blocks, package.json
9
+ bin, pyproject scripts), the argparse command lines, the prose written by the agent, the tests per entry point;
10
+ - coherence: link labels against the headings they point to, counts across pages, the glossary, navigation and
11
+ dependency versions against the manifests.
12
+
13
+ A failing check is never silent: the verdict is fail, the report lists each failure with file and line, and
14
+ `generate` returns the verdict at the top of its answer.
15
+ """
16
+ import html
17
+ import json
18
+ import os
19
+ import posixpath
20
+ import re
21
+ import tomllib
22
+ from collections import defaultdict
23
+
24
+ import atomic_io
25
+ import doc_cli
26
+ import doc_extras
27
+ import doc_insights
28
+ import doc_scope
29
+
30
+ REPORT = "validation.md"
31
+ MAX_EVIDENCE = 3
32
+ MAX_FINDINGS = 60
33
+ MAX_CORPUS_FILES = 4000
34
+ _ANY_LINK = re.compile(r"\[((?:[^\[\]]|\[[^\]]*\])*)\]\((<[^>]*>|[^)\s]+)\)")
35
+ _HEADING = re.compile(r"^#{1,6} (.+)$")
36
+ _LINE_CLAIM = re.compile(r"\(line (\d+)\)")
37
+ _PATH_LINE = re.compile(r"([\w./@-]+\.\w+):(\d+)")
38
+ _UNLINKED = re.compile(r"`([^`]+)` \(([^)]+)\)")
39
+ _MORE = re.compile(r"\(\+(\d+) more\)")
40
+ _CODE_SPAN = re.compile(r"`([^`\n]+)`")
41
+ _OPTION = re.compile(r"(?<![\w`-])(--[a-z][\w-]+)")
42
+ _VERSION = re.compile(r"(?<![\w.])v?(\d+\.\d+\.\d+)(?!\w|\.\w)")
43
+ _SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*:", re.I)
44
+
45
+
46
+ class _Check:
47
+ """One check: the claims it verified (with a few as evidence) and those that failed, each with where and why."""
48
+
49
+ def __init__(self, key, title):
50
+ self.key, self.title = key, title
51
+ self.checked, self.pending, self.evidence, self.failures, self.notes = 0, 0, [], [], []
52
+
53
+ def ok(self, evidence):
54
+ self.checked += 1
55
+ if len(self.evidence) < MAX_EVIDENCE and evidence not in self.evidence:
56
+ self.evidence.append(evidence)
57
+
58
+ def fail(self, where, problem):
59
+ self.checked += 1
60
+ self.failures.append(f"{where}: {problem}")
61
+
62
+ def verify(self, condition, where, evidence, problem):
63
+ if condition:
64
+ self.ok(evidence)
65
+ else:
66
+ self.fail(where, problem)
67
+
68
+ @property
69
+ def status(self):
70
+ if self.failures:
71
+ return "fail"
72
+ return "pending" if self.pending and not self.checked else "pass"
73
+
74
+ def score(self):
75
+ return 100.0 * (self.checked - len(self.failures)) / self.checked if self.checked else None
76
+
77
+
78
+ def _pages(root):
79
+ """Text of each generated page under docs/scope, the previous report left out."""
80
+ folder = os.path.join(root, doc_scope.DOCS_DIR)
81
+ found = {}
82
+ for rel in doc_scope._generated_files(root):
83
+ if rel != REPORT:
84
+ with open(os.path.join(folder, rel), encoding="utf-8") as stream:
85
+ found[rel] = stream.read()
86
+ return found
87
+
88
+
89
+ def _sections(text):
90
+ """Anchored sections of a page: anchor -> {'line', 'heading' (None for an anchor inside a table row), 'body'}."""
91
+ found, current, lines = {}, None, text.split("\n")
92
+ for number, line in enumerate(lines, 1):
93
+ anchors = doc_scope.ANCHOR.findall(line)
94
+ if anchors:
95
+ anchor = html.unescape(anchors[0])
96
+ following = lines[number] if number < len(lines) else ""
97
+ heading = _HEADING.match(following) if line.strip().startswith("<a id=") else None
98
+ current = found[anchor] = {"line": number, "heading": heading.group(1) if heading else None, "body": []}
99
+ if current is not None:
100
+ current["body"].append((number, line))
101
+ return found
102
+
103
+
104
+ def _links(rel, text):
105
+ """Links of a page: (line, label, target path, anchor or None); external links (with a scheme) left out."""
106
+ found = []
107
+ for number, line in enumerate(text.split("\n"), 1):
108
+ for label, target in _ANY_LINK.findall(line):
109
+ target = target[1:-1] if target.startswith("<") else target
110
+ if _SCHEME.match(target):
111
+ continue
112
+ path, _sep, anchor = target.partition("#")
113
+ found.append((number, label, path, html.unescape(anchor) if _sep else None))
114
+ return found
115
+
116
+
117
+ def _resolve(rel, path):
118
+ return posixpath.normpath(posixpath.join(posixpath.dirname(rel), path)) if path else rel
119
+
120
+
121
+ def _function_line(model, function, number):
122
+ """True when the project file's line holds the function's own name (its definition line)."""
123
+ text = model.read(function["path"])
124
+ lines = text.split("\n") if text else []
125
+ name = function["name"].split(".")[-1].split("@")[0]
126
+ return 0 < number <= len(lines) and re.search(rf"\b{re.escape(name)}\b", lines[number - 1]) is not None
127
+
128
+
129
+ def claims_of(body):
130
+ """Claims a prose block makes that the code must back: its code spans, its command-line options outside code spans
131
+ and its version numbers.
132
+
133
+ Parameters: body (str) prose text.
134
+ Returns: list of str, in order of appearance by kind.
135
+ """
136
+ return _CODE_SPAN.findall(body) + _OPTION.findall(_CODE_SPAN.sub("", body)) + _VERSION.findall(body)
137
+
138
+
139
+ class Corpus:
140
+ """Names, paths, source text and command-line options of the project a prose claim is checked against, read once."""
141
+
142
+ def __init__(self, model):
143
+ self.model = model
144
+ self._known = None
145
+
146
+ def _read(self):
147
+ if self._known is None:
148
+ model = self.model
149
+ names = set()
150
+ for function in model.function_of.values():
151
+ names.add(function["name"])
152
+ names.update(function["name"].split("."))
153
+ names.update(s["name"] for s in model.graph.get("symbols") or [])
154
+ files = set(model.files())
155
+ folders = {posixpath.dirname(p) for p in files}
156
+ texts = [model.read(p) or "" for p in sorted(files) if model.kind_of(p) != "doc"][:MAX_CORPUS_FILES]
157
+ options = {f for d in model.command_lines() for c in d["commands"] for a in c["arguments"] for f in a["flags"]}
158
+ self._known = (names, files | folders, "\n".join(texts), options)
159
+ return self._known
160
+
161
+ def supports(self, claim):
162
+ """Whether the code backs claim: a name, path, option or text of the code, or several words each of them.
163
+
164
+ Parameters: claim (str).
165
+ Returns: bool.
166
+ """
167
+ names, paths, text, options = self._read()
168
+ bare = claim.strip().rstrip("()").removesuffix("()")
169
+ if bare in names or bare.rstrip("/") in paths or bare in options or bare in text:
170
+ return True
171
+ words = [w.strip(".,:;()[]{}'\"") for w in bare.split()]
172
+ return len(words) > 1 and all(w in names or w in paths or w in options or w in text for w in words if w)
173
+
174
+
175
+ class _Validation:
176
+ def __init__(self, model, entries):
177
+ self.model, self.entries, self.root = model, entries, model.root
178
+ self.pages = _pages(model.root)
179
+ self.sections = {rel: _sections(text) for rel, text in self.pages.items()}
180
+ self.public = model.public()
181
+ self.corpus = Corpus(model)
182
+ self.checks = []
183
+
184
+ def check(self, key, title):
185
+ found = _Check(key, title)
186
+ self.checks.append(found)
187
+ return found
188
+
189
+ def _technical_pages(self):
190
+ return [rel for rel in self.pages if rel.startswith("technical/") and rel != "technical/README.md"]
191
+
192
+ def _anchors_of(self, rel):
193
+ return set(self.sections.get(rel, {}))
194
+
195
+ def markers(self):
196
+ check = self.check("markers", "Every signature marker and entry paragraph matches its function in the code")
197
+ markers, _anchors, _links = doc_scope._scan(self.root)
198
+ by_path = defaultdict(list)
199
+ for symbol in self.model.graph.get("symbols") or []:
200
+ by_path[symbol["path"]].append(symbol)
201
+ current, stamps = doc_scope._current_code(self.root, {m["id"].rpartition("::")[0] for m in markers}, by_path)
202
+ for marker in markers:
203
+ now = current.get(marker["id"])
204
+ check.verify(now == marker["signature"], f"{marker['file']}:{marker['line']}",
205
+ f"`{marker['id']}` ({marker['file']}:{marker['line']}) has the signature of the code",
206
+ f"`{marker['id']}` " + ("no longer exists in the code" if now is None else "changed its signature"))
207
+ for item in doc_scope.stale_prose(self.pages, stamps):
208
+ check.fail(f"{item['file']}:{item['line']}", f"the paragraph of `{item['id']}` was written for other code of "
209
+ "the function: its body changed since")
210
+
211
+ def links(self):
212
+ check = self.check("links", "Every link resolves to an existing page, file and anchor")
213
+ known = set(self.pages) | {REPORT}
214
+ for rel, text in self.pages.items():
215
+ for number, _label, path, anchor in _links(rel, text):
216
+ self._link(check, rel, number, path, anchor, known, _resolve(rel, path))
217
+ block = self._index_block()
218
+ if block:
219
+ name, first, text = block
220
+ for number, _label, path, anchor in _links(name, text):
221
+ target = path[len(doc_scope.DOCS_DIR) + 1:] if path.startswith(doc_scope.DOCS_DIR + "/") else None
222
+ if target is None:
223
+ check.verify(os.path.exists(os.path.join(self.root, path)), f"{name}:{first + number - 1}",
224
+ f"{name} links `{path}`", f"`{path}` does not exist")
225
+ else:
226
+ self._link(check, name, first + number - 1, target, anchor, known, target, shown=f"{name}:{first + number - 1}")
227
+
228
+ def _link(self, check, rel, number, path, anchor, known, target, shown=None):
229
+ where = shown or f"{rel}:{number}"
230
+ if target.startswith("../"):
231
+ exists = os.path.exists(os.path.normpath(os.path.join(self.root, doc_scope.DOCS_DIR, target)))
232
+ check.verify(exists, where, f"{where} links `{path}`, which exists", f"`{path}` does not exist")
233
+ return
234
+ if target not in known:
235
+ check.fail(where, f"`{path or rel}` is not a page of the documentation")
236
+ return
237
+ if anchor is None or target == REPORT:
238
+ check.ok(f"{where} links the page `{target}`")
239
+ return
240
+ check.verify(anchor in self._anchors_of(target), where, f"{where} links `{target}#{anchor}`",
241
+ f"anchor `{anchor}` is not on `{target}`")
242
+
243
+ def _index_block(self):
244
+ name = doc_extras._index_target(self.root)
245
+ if name is None:
246
+ return None
247
+ with open(os.path.join(self.root, name), encoding="utf-8") as stream:
248
+ text = stream.read()
249
+ found = doc_extras._INDEX_BLOCK.search(text)
250
+ return (name, text[:found.start(1)].count("\n") + 1, found.group(1)) if found else None
251
+
252
+ def lines(self):
253
+ check = self.check("lines", "Every line number the pages give points at the code it names")
254
+ for rel in self._technical_pages() + ["functional.md"]:
255
+ for anchor, section in self.sections.get(rel, {}).items():
256
+ function = self.model.function_of.get(anchor)
257
+ if function is None:
258
+ continue
259
+ for number, line in section["body"][:8]:
260
+ claim = _LINE_CLAIM.search(line)
261
+ if claim and (line.startswith("`") or line.startswith("Entry point in")):
262
+ at = int(claim.group(1))
263
+ check.verify(_function_line(self.model, function, at), f"{rel}:{number}",
264
+ f"`{function['name']}` is at {function['path']}:{at}",
265
+ f"line {at} of `{function['path']}` does not hold `{function['name']}`")
266
+ break
267
+ for rel, text in self.pages.items():
268
+ if rel not in ("extras/configuration.md", "extras/dead-code.md"):
269
+ continue
270
+ for number, line in enumerate(text.split("\n"), 1):
271
+ name = _CODE_SPAN.search(line)
272
+ if not name or not (line.startswith("| `") or line.startswith("- `")):
273
+ continue
274
+ for path, at in _PATH_LINE.findall(line):
275
+ source = self.model.read(path)
276
+ rows = source.split("\n") if source else []
277
+ word = name.group(1).split(".")[-1]
278
+ held = 0 < int(at) <= len(rows) and word in rows[int(at) - 1]
279
+ check.verify(held, f"{rel}:{number}", f"`{name.group(1)}` is at {path}:{at}",
280
+ f"line {at} of `{path}` does not hold `{name.group(1)}`")
281
+
282
+ def relations(self):
283
+ check = self.check("relations", "Callers, calls and tests of each technical entry match the code graph")
284
+ model = self.model
285
+ for rel in self._technical_pages():
286
+ for anchor, section in self.sections[rel].items():
287
+ if anchor not in model.function_of:
288
+ continue
289
+ callers = set(model.callers_in_code(anchor))
290
+ expected = {"Called by": callers, "Calls": set(model.callees[anchor])}
291
+ listed = {key: None for key in expected}
292
+ tests_line = None
293
+ for number, line in section["body"]:
294
+ for key in expected:
295
+ if line.startswith(f"- {key}: "):
296
+ listed[key] = (number, line)
297
+ if line.startswith("- Tests: "):
298
+ tests_line = (number, line)
299
+ name = model.function_of[anchor]["name"]
300
+ for key, want in expected.items():
301
+ if listed[key] is None:
302
+ check.verify(not want, f"{rel}:{section['line']}", f"`{name}` lists no {key.lower()}: the graph has none",
303
+ f"`{name}` does not list its {len(want)} {key.lower()}")
304
+ continue
305
+ number, line = listed[key]
306
+ linked = {html.unescape(a) for _t, a in doc_scope.LINK.findall(line)}
307
+ more = _MORE.search(line)
308
+ total = len(doc_scope.LINK.findall(line)) + len(_UNLINKED.findall(line)) + (int(more.group(1)) if more else 0)
309
+ wrong = linked - want
310
+ check.verify(not wrong and total == len(want), f"{rel}:{number}",
311
+ f"`{name}`: {total} {key.lower()} as in the graph",
312
+ f"`{name}` lists {total} {key.lower()}, the graph has {len(want)}"
313
+ + (f"; not in the graph: {', '.join(sorted(wrong))}" if wrong else ""))
314
+ tests = model.tests_of(anchor)
315
+ shown = [t for t, _p in _UNLINKED.findall(tests_line[1])] if tests_line else []
316
+ names = [model.function_of[t]["name"] for t in tests[:doc_scope.MAX_LINKS]]
317
+ check.verify(shown == names, f"{rel}:{tests_line[0] if tests_line else section['line']}",
318
+ f"`{name}`: {len(shown)} test(s) reach it", f"`{name}` lists tests {shown}, the graph reaches {names}")
319
+
320
+ def coverage(self):
321
+ check = self.check("coverage", "Every public function has its technical entry and the coverage numbers are real")
322
+ model = self.model
323
+ documented_at = {}
324
+ for rel in self._technical_pages():
325
+ for anchor in self.sections[rel]:
326
+ documented_at[anchor] = rel
327
+ for anchor in self.public:
328
+ check.verify(anchor in documented_at, f"technical: `{anchor}`", f"`{anchor}` is on {documented_at.get(anchor)}",
329
+ "public function with no technical entry")
330
+ for anchor, rel in documented_at.items():
331
+ if anchor not in set(self.public):
332
+ check.fail(f"{rel}:{self.sections[rel][anchor]['line']}", f"`{anchor}` is not a public code function")
333
+ gaps = [a for a in self.public if not model.function_of[a]["documented"]]
334
+ check.notes.append(f"Gaps: {len(gaps)} of {len(self.public)} public functions have no docstring"
335
+ + (f" (first: {', '.join(f'`{a}`' for a in gaps[:5])})" if gaps else "") + ".")
336
+ stats = defaultdict(lambda: [0, 0])
337
+ for anchor in self.public:
338
+ function = model.function_of[anchor]
339
+ row = stats[posixpath.dirname(function["path"]) or "(project root)"]
340
+ row[0] += 1
341
+ row[1] += bool(function["documented"])
342
+ stats["**All**"] = [len(self.public), len(self.public) - len(gaps)]
343
+ text = self.pages.get("extras/coverage.md")
344
+ if text is not None:
345
+ rows = {}
346
+ for number, line in enumerate(text.split("\n"), 1):
347
+ cells = [c.strip() for c in line.strip("|").split("|")]
348
+ if len(cells) == 4 and cells[1].isdigit():
349
+ rows[cells[0].strip("`")] = (number, int(cells[1]), int(cells[2]))
350
+ for folder, (total, documented) in stats.items():
351
+ number, *shown = rows.get(folder, (None, None, None))
352
+ check.verify(shown == [total, documented], f"extras/coverage.md:{number or 1}",
353
+ f"coverage of `{folder}`: {documented}/{total}",
354
+ f"`{folder}` shows {shown}, the code has {total} public and {documented} documented")
355
+ technical = self.pages.get("technical/README.md", "")
356
+ for number, line in enumerate(technical.split("\n"), 1):
357
+ found = re.match(r"\| \[`[^`]*`\]\(<([^>]+)>\) \| (\d+) \| (\d+) \|$", line)
358
+ if found:
359
+ page = posixpath.normpath(posixpath.join("technical", found.group(1)))
360
+ anchors = [a for a in self.sections.get(page, {}) if a in model.function_of]
361
+ documented = sum(1 for a in anchors if model.function_of[a]["documented"])
362
+ check.verify([len(anchors), documented] == [int(found.group(2)), int(found.group(3))],
363
+ f"technical/README.md:{number}", f"`{page}`: {len(anchors)} entries, {documented} documented",
364
+ f"`{page}` shows {found.group(2)}/{found.group(3)}, the page holds {len(anchors)}/{documented}")
365
+
366
+ def entry_points(self):
367
+ check = self.check("entry_points", "Each entry point of the functional overview is a real entry point and its flow is reachable")
368
+ model, launched = self.model, set(self.model.launched())
369
+ top = model.rule.layers[0]["name"] if model.rule else None
370
+ sections = {a: s for a, s in self.sections.get("functional.md", {}).items() if not a.startswith("cli:")}
371
+ for anchor, section in sections.items():
372
+ where = f"functional.md:{section['line']}"
373
+ function = model.function_of.get(anchor)
374
+ if function is None:
375
+ check.fail(where, f"`{anchor}` is not a function of the code")
376
+ continue
377
+ reasons = [r for r, held in (("named main", function["name"].split(".")[-1] == "main"),
378
+ ("run by a __main__ block", anchor in launched),
379
+ ("called by no code function", not model.callers_in_code(anchor)),
380
+ (f"in the top layer {top}", top and model.layer_of.get(function["path"]) == top)) if held]
381
+ check.verify(reasons, where, f"`{function['name']}` ({function['path']}) is an entry point: {reasons[0] if reasons else ''}",
382
+ f"`{function['name']}` is called by {', '.join(sorted(model.callers_in_code(anchor)))[:200]}")
383
+ flow = set(model.flow(anchor))
384
+ listed, total = set(), 0
385
+ for _number, line in section["body"]:
386
+ if line.startswith("- ") and ": " in line:
387
+ listed |= {html.unescape(a) for _t, a in doc_scope.LINK.findall(line)}
388
+ more = _MORE.search(line)
389
+ total += len(doc_scope.LINK.findall(line)) + len(_UNLINKED.findall(line)) + (int(more.group(1)) if more else 0)
390
+ check.verify(listed <= flow and total == len(flow), where, f"flow of `{function['name']}`: {total} function(s) reached",
391
+ f"flow of `{function['name']}` lists {total}, the code reaches {len(flow)}"
392
+ + (f"; unreachable: {', '.join(sorted(listed - flow))}" if listed - flow else ""))
393
+ for anchor in self.entries:
394
+ if anchor not in sections:
395
+ check.fail("functional.md", f"entry point `{anchor}` of the code has no section")
396
+
397
+ def features(self):
398
+ check = self.check("features", "Every feature a launcher runs (__main__ block, package.json bin, pyproject script) is documented")
399
+ model = self.model
400
+ documented = {a for a in self.sections.get("functional.md", {}) if not a.startswith("cli:")}
401
+ files, by_name = set(model.files()), {}
402
+ for anchor, function in model.function_of.items():
403
+ by_name.setdefault((function["path"], function["name"]), anchor)
404
+ for path in model._python_code():
405
+ source = model.read(path)
406
+ if not source or "__main__" not in source:
407
+ continue
408
+ for target in doc_cli.launched(path, source, files):
409
+ anchor = by_name.get(target)
410
+ check.verify(anchor in documented, path, f"`{path}` runs `{target[1]}` ({target[0]}), documented",
411
+ f"runs `{target[1]}` ({target[0]}), which has no section in functional.md")
412
+ for path in sorted(p for p in files if posixpath.basename(p) in ("package.json", "pyproject.toml")):
413
+ text = model.read(path)
414
+ try:
415
+ data = json.loads(text) if path.endswith(".json") else tomllib.loads(text)
416
+ except (ValueError, TypeError):
417
+ continue
418
+ folder = posixpath.dirname(path)
419
+ if path.endswith(".json"):
420
+ bins = data.get("bin")
421
+ bins = {data.get("name", ""): bins} if isinstance(bins, str) else bins if isinstance(bins, dict) else {}
422
+ for command, script in bins.items():
423
+ script = posixpath.normpath(posixpath.join(folder, script))
424
+ if script not in files:
425
+ check.notes.append(f"{path}: command `{command}` runs `{script}`, which is not a file of the "
426
+ "repository (a build output), so it was not checked")
427
+ continue
428
+ hit = [a for a in documented if model.function_of.get(a, {}).get("path") == script]
429
+ check.verify(hit, path, f"command `{command}` runs `{script}`, documented",
430
+ f"command `{command}` runs `{script}`, which has no entry point in functional.md")
431
+ for command, spec in ((data.get("project") or {}).get("scripts") or {}).items() if not path.endswith(".json") else ():
432
+ module, _sep, name = str(spec).partition(":")
433
+ target = doc_cli._module_file(path, module, 0, files)
434
+ hit = by_name.get((target, name.split(".")[0])) if target else None
435
+ check.verify(hit in documented, path, f"script `{command}` runs `{spec}`, documented",
436
+ f"script `{command}` runs `{spec}`, which has no section in functional.md")
437
+
438
+ def command_lines(self):
439
+ check = self.check("command_line", "The commands, arguments and options documented are those the code declares")
440
+ model = self.model
441
+ sections = self.sections.get("functional.md", {})
442
+ expected = {doc_scope.cli_anchor(d): d for d in model.command_lines()}
443
+ for anchor, definition in expected.items():
444
+ where = f"{definition['path']}:{definition['line']}"
445
+ section = sections.get(anchor)
446
+ if section is None:
447
+ check.fail(where, f"command line {doc_scope.cli_title(definition)} is missing from functional.md")
448
+ continue
449
+ body = {line: number for number, line in section["body"]}
450
+ want = doc_cli.lines(definition)
451
+ commands = iter(definition["commands"])
452
+ command = None
453
+ for line in want:
454
+ if not line.startswith(" "):
455
+ command = next(commands)
456
+ shown = f"{doc_cli.command_title(command)} at {definition['path']}:{command['line']}"
457
+ check.verify(line in body, where, shown, f"not documented: {line.strip()}")
458
+ for line, number in body.items():
459
+ if line.startswith(("- ", " - ")) and line not in want:
460
+ check.fail(f"functional.md:{number}", f"not in the code: {line.strip()}")
461
+ runners = {html.unescape(a) for _t, a in doc_scope.LINK.findall("\n".join(body))}
462
+ check.verify(runners == set(doc_scope.cli_runners(model, definition, self.entries)), f"functional.md:{section['line']}",
463
+ f"{doc_scope.cli_title(definition)} is run by {len(runners)} entry point(s)",
464
+ "the entry points listed as running it differ from the call graph")
465
+ for anchor, section in sections.items():
466
+ if anchor.startswith("cli:") and anchor not in expected:
467
+ check.fail(f"functional.md:{section['line']}", f"command line `{anchor}` is not in the code")
468
+
469
+ def prose(self):
470
+ check = self.check("prose", "Each claim of the written prose is backed by the code")
471
+ for rel, text in self.pages.items():
472
+ for block in doc_scope.PROSE.finditer(text):
473
+ key, body = block.groups()
474
+ if not body.strip():
475
+ check.pending += 1
476
+ continue
477
+ number = text[:block.start()].count("\n") + 2
478
+ claims = claims_of(body)
479
+ if not claims:
480
+ check.ok(f"{rel}:{number}: block `{key}` names nothing to check")
481
+ for claim in claims:
482
+ check.verify(self.corpus.supports(claim), f"{rel}:{number}", f"`{claim}` ({rel}, block `{key}`) is in the code",
483
+ f"`{claim}` (block `{key}`) is not found in the code, its files or its command lines")
484
+ if check.pending:
485
+ check.notes.append(f"{check.pending} prose block(s) are empty: the agent writes them (see prose_pending of generate).")
486
+
487
+ def entry_tests(self):
488
+ check = self.check("entry_tests", "The tests per entry point match the code graph")
489
+ text = self.pages.get("extras/features-tests.md")
490
+ if text is None:
491
+ return
492
+ rows = 0
493
+ for number, line in enumerate(text.split("\n"), 1):
494
+ marker = doc_scope.MARKER.search(line)
495
+ if not marker or not line.startswith("|"):
496
+ continue
497
+ rows += 1
498
+ anchor = html.unescape(marker.group(1))
499
+ count = int(line.split("|")[2].strip())
500
+ tests = self.model.tests_of(anchor) if anchor in self.model.function_of else []
501
+ check.verify(count == len(tests), f"extras/features-tests.md:{number}", f"`{anchor}`: {count} test(s)",
502
+ f"`{anchor}` shows {count} test(s), the graph reaches {len(tests)}")
503
+ bare = sum(1 for a in self.entries[:rows] if not self.model.tests_of(a))
504
+ found = re.search(r"^(\d+) of (\d+) entry point", text, re.M)
505
+ check.verify(found and [int(found.group(1)), int(found.group(2))] == [bare, rows], "extras/features-tests.md",
506
+ f"{bare} of {rows} entry points have no test", f"the summary line does not say {bare} of {rows}")
507
+
508
+ def labels(self):
509
+ check = self.check("labels", "Every link that names a section carries the name of its heading")
510
+ headings = {(rel, a): s["heading"] for rel, found in self.sections.items() for a, s in found.items() if s["heading"]}
511
+ for rel, text in self.pages.items():
512
+ for number, label, path, anchor in _links(rel, text):
513
+ heading = headings.get((_resolve(rel, path), anchor)) if anchor else None
514
+ if heading is None or "`" not in label:
515
+ continue
516
+ check.verify(label == heading, f"{rel}:{number}", f"{rel}:{number} links {heading}",
517
+ f"label {label} differs from the heading {heading}")
518
+
519
+ def counts(self):
520
+ check = self.check("counts", "Counts and names agree across pages")
521
+ entries = [a for a in self.sections.get("functional.md", {}) if not a.startswith("cli:")]
522
+ total = len(entries)
523
+ readme = self.pages.get("README.md", "")
524
+ found = re.search(r"^(\d+) public functions on (\d+) technical pages; (\d+) entry points", readme, re.M)
525
+ technical = self._technical_pages()
526
+ if found:
527
+ check.verify(int(found.group(3)) == total, "README.md", f"README: {total} entry points",
528
+ f"README says {found.group(3)} entry points, functional.md has {total}")
529
+ check.verify(int(found.group(1)) == len(self.public), "README.md", f"README: {len(self.public)} public functions",
530
+ f"README says {found.group(1)} public functions, the code has {len(self.public)}")
531
+ check.verify(int(found.group(2)) == len(technical), "README.md", f"README: {len(technical)} technical pages",
532
+ f"README says {found.group(2)} technical pages, there are {len(technical)}")
533
+ else:
534
+ check.fail("README.md", "the counts line is missing")
535
+ simple = self.pages.get("simple.md", "")
536
+ shown = len(re.findall(r"^### ", simple.split("## What it does", 1)[-1], re.M))
537
+ check.verify(shown == total, "simple.md", f"simple.md: {total} entry points", f"simple.md has {shown} entry points, functional.md {total}")
538
+ for rel, pattern in (("extras/flows.md", r"^(\d+) more entry point\(s\) are not drawn"),
539
+ ("extras/tour.md", r"^(\d+) more entry point\(s\) in the")):
540
+ text = self.pages.get(rel)
541
+ if text is None or not total:
542
+ continue
543
+ listed = len(re.findall(r"^## ", text, re.M)) if rel.endswith("flows.md") else len(re.findall(r"^\d+\. ", text, re.M))
544
+ more = re.search(pattern, text, re.M)
545
+ check.verify(listed + (int(more.group(1)) if more else 0) == total, rel, f"{rel}: {total} entry points",
546
+ f"{rel} accounts for {listed + (int(more.group(1)) if more else 0)} entry points, functional.md has {total}")
547
+ block = self._index_block()
548
+ if block:
549
+ found = re.search(r"^(\d+) public functions, (\d+) entry points", block[2], re.M)
550
+ check.verify(found and [int(found.group(1)), int(found.group(2))] == [len(self.public), total], block[0],
551
+ f"{block[0]}: {len(self.public)} public functions, {total} entry points",
552
+ f"{block[0]} counts differ from the pages ({len(self.public)} public, {total} entry points)")
553
+ for number, line in enumerate(self.pages.get("extras/hotspots.md", "").split("\n"), 1):
554
+ cells = [c.strip() for c in line.strip().strip("|").split("|")]
555
+ if len(cells) == 5 and cells[1].isdigit() and cells[0].startswith("`"):
556
+ path, commits, size, score = cells[0].strip("`"), int(cells[1]), int(cells[2]), int(cells[3])
557
+ lines = doc_insights._lines(self.model, path)
558
+ check.verify(size == lines and score == commits * size, f"extras/hotspots.md:{number}",
559
+ f"`{path}`: {lines} lines, score {commits} x {lines}",
560
+ f"`{path}` shows {size} lines and score {score}; the file has {lines} lines")
561
+ name, source = doc_scope.project_name(self.model)
562
+ title = simple.split("\n", 2)[1] if simple.count("\n") > 1 else ""
563
+ check.verify(title == f"# {name} in plain words", "simple.md:2",
564
+ f"project name `{name}` as declared in {source or 'the folder name'}",
565
+ f"title {title!r} differs from the project name `{name}` ({source or 'folder'})")
566
+
567
+ def glossary(self):
568
+ check = self.check("glossary", "Glossary words and examples come from the code and the summary uses them")
569
+ text = self.pages.get("extras/glossary.md")
570
+ if text is None:
571
+ return
572
+ terms = {w: (n, examples) for w, n, examples in doc_insights.terms(self.model)}
573
+ names = {f["name"].split(".")[-1] for f in self.model.function_of.values()}
574
+ words = set()
575
+ for number, line in enumerate(text.split("\n"), 1):
576
+ cells = [c.strip() for c in line.strip().strip("|").split("|")]
577
+ if len(cells) != 3 or not cells[1].isdigit():
578
+ continue
579
+ word = cells[0].strip("`")
580
+ words.add(word)
581
+ examples = _CODE_SPAN.findall(cells[2])
582
+ check.verify(word in terms and terms[word][0] == int(cells[1]) and set(examples) <= names,
583
+ f"extras/glossary.md:{number}", f"`{word}`: {cells[1]} functions, e.g. {', '.join(examples[:2])}",
584
+ f"`{word}` shows {cells[1]} function(s) and {examples}, the code has {terms.get(word, (0, []))}")
585
+ used = re.search(r"^Words this project uses: (.+) \(\[glossary\]", self.pages.get("simple.md", ""), re.M)
586
+ for word in used.group(1).split(", ") if used else []:
587
+ check.verify(word in words, "simple.md", f"`{word}` is in the glossary", f"`{word}` is not in the glossary")
588
+
589
+ def navigation(self):
590
+ check = self.check("navigation", "Every page is reachable from the scope README and links back to it")
591
+ known = set(self.pages) | {REPORT}
592
+ edges = defaultdict(set)
593
+ for rel, text in self.pages.items():
594
+ for _number, _label, path, _anchor in _links(rel, text):
595
+ edges[rel].add(_resolve(rel, path))
596
+ seen, frontier = {"README.md"}, ["README.md"]
597
+ while frontier:
598
+ current = frontier.pop()
599
+ for target in edges[current] & known - seen:
600
+ seen.add(target)
601
+ frontier.append(target)
602
+ for rel in sorted(known):
603
+ check.verify(rel in seen, rel, f"`{rel}` is reachable from README.md", "no link chain from README.md reaches it")
604
+ for rel, text in self.pages.items():
605
+ if rel == "README.md":
606
+ continue
607
+ head = "\n".join(text.split("\n")[:8])
608
+ back = {_resolve(rel, p) for _n, _l, p, _a in _links(rel, head)}
609
+ check.verify(back & {"README.md", "technical/README.md", "extras/adr/README.md"}, rel,
610
+ f"`{rel}` links back to an index", "no navigation link back to an index in its first lines")
611
+
612
+ def versions(self):
613
+ check = self.check("versions", "Dependency versions match the manifests")
614
+ text = self.pages.get("extras/dependencies.md")
615
+ if text is None:
616
+ return
617
+ current, shown = None, defaultdict(dict)
618
+ for line in text.split("\n"):
619
+ section = re.match(r"^## `([^`]+)`$", line)
620
+ if section:
621
+ current = section.group(1)
622
+ continue
623
+ cells = [c.strip() for c in line.strip().strip("|").split("|")]
624
+ if current and len(cells) == 4 and cells[0].startswith("`"):
625
+ shown[current][(cells[0].strip("`"), cells[2])] = cells[1]
626
+ for path, rows in shown.items():
627
+ declared, problem = doc_extras._manifest(self.root, path)
628
+ if problem:
629
+ check.fail(path, f"manifest {problem}")
630
+ continue
631
+ want = {(name, scope): spec or "-" for _e, name, spec, scope in declared}
632
+ for key, spec in want.items():
633
+ check.verify(rows.get(key) == spec, f"extras/dependencies.md ({path})", f"`{key[0]}` {spec} as in {path}",
634
+ f"`{key[0]}` shows {rows.get(key)!r}, {path} declares {spec!r}")
635
+ for key in set(rows) - set(want):
636
+ check.fail(f"extras/dependencies.md ({path})", f"`{key[0]}` is not declared in {path}")
637
+
638
+ def run(self):
639
+ for step in (self.markers, self.links, self.lines, self.relations, self.coverage, self.entry_points,
640
+ self.features, self.command_lines, self.prose, self.entry_tests, self.labels, self.counts,
641
+ self.glossary, self.navigation, self.versions):
642
+ step()
643
+ scored = [c.score() for c in self.checks if c.score() is not None]
644
+ failed = [c for c in self.checks if c.status == "fail"]
645
+ pending = sum(c.pending for c in self.checks)
646
+ verdict = "fail" if failed else "incomplete" if pending else "pass"
647
+ return {"verdict": verdict, "score": round(sum(scored) / len(scored), 1) if scored else 0.0,
648
+ "claims_checked": sum(c.checked for c in self.checks),
649
+ "claims_failed": sum(len(c.failures) for c in self.checks), "prose_pending": pending,
650
+ "checks": self.checks}
651
+
652
+
653
+ _GROUPS = (("Code to technical documentation", ("markers", "links", "lines", "relations", "coverage")),
654
+ ("Functional documentation to the product", ("entry_points", "features", "command_line", "prose", "entry_tests")),
655
+ ("Coherence", ("labels", "counts", "glossary", "navigation", "versions")))
656
+
657
+
658
+ def _report(result):
659
+ by_key = {c.key: c for c in result["checks"]}
660
+ verdict = {"fail": "FAIL", "incomplete": "PASS with prose pending", "pass": "PASS"}[result["verdict"]]
661
+ lines = [doc_scope.GENERATED, "# Documentation validation", "",
662
+ "[Scope](README.md) · [Functional](functional.md) · [Technical](technical/README.md)", "",
663
+ f"**Verdict: {verdict}** · score {result['score']} / 100 · {result['claims_checked']} claims checked, "
664
+ f"{result['claims_failed']} failed · {result['prose_pending']} prose block(s) pending", "",
665
+ "Each check reads the generated pages and verifies their claims against the code on disk, the code graph, "
666
+ "the command lines the code declares and the manifests. The score is the mean, over the checks, of the "
667
+ "share of claims that hold. Not checked claim by claim: the change coupling and the commit counts (they "
668
+ "come from the git history), the Mermaid diagrams, the module and folder trees and the decision records.",
669
+ "", "| Check | Status | Claims | Failed |", "|---|---|---|---|"]
670
+ lines += [f"| {c.title} | {c.status} | {c.checked} | {len(c.failures)} |" for c in result["checks"]]
671
+ for group, keys in _GROUPS:
672
+ lines += ["", f"## {group}"]
673
+ for key in keys:
674
+ check = by_key[key]
675
+ lines += ["", f"### {check.title}", "", f"Status: **{check.status}** · {check.checked} claim(s) checked, "
676
+ f"{len(check.failures)} failed.", ""]
677
+ lines += [f"- {note}" for note in check.notes]
678
+ lines += [f"- Evidence: {item}" for item in check.evidence]
679
+ if check.failures:
680
+ lines += ["", f"Failures ({len(check.failures)}):", ""]
681
+ lines += [f"- {item}" for item in check.failures[:MAX_FINDINGS]]
682
+ if len(check.failures) > MAX_FINDINGS:
683
+ lines.append(f"- ... and {len(check.failures) - MAX_FINDINGS} more")
684
+ return "\n".join(lines) + "\n"
685
+
686
+
687
+ def run(model, entries, limit=30):
688
+ """Validate the documentation already written under docs/scope and write the report.
689
+
690
+ Parameters: model (doc_scope._Model) of the current code; entries (list) its entry-point anchors; limit (int)
691
+ failures listed per check in the answer.
692
+ Returns: dict with 'verdict' (pass | incomplete | fail), 'score', claim counts, 'report' (path) and 'checks'.
693
+ """
694
+ result = _Validation(model, entries).run()
695
+ path = os.path.normpath(os.path.join(model.root, doc_scope.DOCS_DIR, REPORT))
696
+ if os.path.exists(path):
697
+ with open(path, encoding="utf-8") as stream:
698
+ if stream.readline().rstrip("\n") != doc_scope.GENERATED:
699
+ raise ValueError(f"{path} exists and was not written by Smart Tool; move it before validating.")
700
+ atomic_io.write_text(path, _report(result))
701
+ checks = [{"check": c.key, "status": c.status, "claims": c.checked, "failed": len(c.failures),
702
+ **({"failures": c.failures[:limit]} if c.failures else {})} for c in result["checks"]]
703
+ return {**{k: v for k, v in result.items() if k != "checks"}, "report": path, "checks": checks}
704
+
705
+
706
+ def validate(root, view_id=None, limit=30):
707
+ """Validate the generated documentation of a project against its current code (the standalone action).
708
+
709
+ Parameters: root (str) project folder; view_id (str or None) index view; limit (int) failures listed per check.
710
+ Returns: the dict of run.
711
+ """
712
+ if not os.path.isdir(os.path.join(root, doc_scope.DOCS_DIR)):
713
+ raise ValueError(f"No {doc_scope.DOCS_DIR} in the project yet: generate it with project_manage action=docs generate=true.")
714
+ model = doc_scope._Model(root, view_id)
715
+ if not model.graph.get("symbols"):
716
+ raise ValueError(f"The code graph of {root} is empty: index the project first (project_manage action=index).")
717
+ return run(model, model.entry_points(), limit)