@allansantos-dev/smart-tool 0.9.61 → 0.9.66
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.
- package/CHANGELOG.md +142 -0
- package/README.md +65 -14
- package/affected_tests.py +1 -1
- package/atomic_io.py +8 -2
- package/code_graph.py +25 -8
- package/code_graph_go.py +526 -12
- package/code_graph_java.mjs +19 -10
- package/code_graph_js.cjs +9 -7
- package/comment_check.py +210 -0
- package/config.py +36 -4
- package/daemon_launcher.py +4 -4
- package/doc_check.py +120 -20
- package/doc_cli.py +239 -0
- package/doc_extras.py +561 -0
- package/doc_insights.py +300 -0
- package/doc_prose.py +371 -0
- package/doc_scope.py +869 -0
- package/doc_validate.py +717 -0
- package/duplicates.py +15 -7
- package/endpoint_sync.py +4 -2
- package/hook_decision.py +62 -14
- package/install.py +2 -2
- package/layers.py +237 -0
- package/locales/pt-BR.json +10 -1
- package/model_client.py +10 -5
- package/model_defaults.py +9 -6
- package/model_health.py +9 -3
- package/model_upgrade.py +1 -1
- package/package.json +1 -1
- package/pr_impact.py +84 -0
- package/project_insights_ui.py +1 -1
- package/project_maps_ui.py +1 -1
- package/redirect_rule.py +10 -2
- package/setup_ui.py +21 -6
- package/smart_tool_daemon.py +66 -15
- package/usage_meter.py +6 -1
- package/version.py +1 -1
- package/web_fetch.py +1 -1
package/doc_validate.py
ADDED
|
@@ -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)
|