@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/doc_extras.py ADDED
@@ -0,0 +1,561 @@
1
+ """Documents generated beside the three documentation levels from the same code graph, one per key of the config object
2
+ `docs_extras` (each on by default, each turned off with `false`):
3
+
4
+ - before the documentation: `structure` (folders of code, tests and docs), `coverage` (docstring coverage per folder),
5
+ `modules` (Mermaid of the calls between modules);
6
+ - other types: `tests` (what each suite reaches), `configuration` (variables, files and ports the code reads),
7
+ `dependencies` (manifests with the license each installed package declares), `adr` (index and template of decisions);
8
+ - after the documentation: `flows` (Mermaid sequence per entry point), `features_tests` (entry point x tests matrix),
9
+ `index` (a short block between markers inside an existing AGENTS.md or llms.txt);
10
+ - from the history and the names: `hotspots`, `coupling`, `dead_code`, `tour`, `glossary` (see doc_insights); the
11
+ decision candidates from the git log go into the `adr` page.
12
+
13
+ Everything is deterministic: names, counts and links come from the graph and the files, never from a model. The pages
14
+ live under docs/scope/extras and carry the same generated marker, anchors and signature markers as the other pages, so
15
+ `check` and the edit hook cover them. The index block is the only text written outside docs/scope, and only into a file
16
+ that already exists, between its own markers."""
17
+ import glob
18
+ import json
19
+ import os
20
+ import posixpath
21
+ import re
22
+ import tomllib
23
+ from collections import Counter, defaultdict
24
+ from importlib import metadata
25
+
26
+ import atomic_io
27
+ import config
28
+ import doc_insights
29
+ import doc_scope
30
+
31
+ EXTRAS_DIR = "extras"
32
+ INDEX_START = "<!-- smart-tool:index:start -->"
33
+ INDEX_END = "<!-- smart-tool:index:end -->"
34
+ INDEX_FILES = ("AGENTS.md", "llms.txt")
35
+ ADR_DIRS = ("docs/adr", "docs/decisions", "docs/scope/adr")
36
+ MAX_ENTRIES = 100
37
+ MAX_SEQUENCES = 40
38
+ MAX_MESSAGES = 25
39
+ MAX_TREE_LINES = 300
40
+ TREE_DEPTH = 4
41
+ MAX_SOURCE_FILES = 4000
42
+ MAX_SOURCE_BYTES = 1_000_000
43
+ MAX_HITS = 5
44
+ INDEX_ENTRIES = 10
45
+ _INDEX_BLOCK = re.compile(re.escape(INDEX_START) + r"\n(.*?)" + re.escape(INDEX_END), re.S)
46
+ _ENV = [re.compile(pattern) for pattern in (
47
+ r"os\.environ(?:\.get)?\(\s*[\"']([A-Za-z_][A-Za-z0-9_]*)[\"']", r"os\.environ\[\s*[\"']([A-Za-z_][A-Za-z0-9_]*)[\"']",
48
+ r"os\.getenv\(\s*[\"']([A-Za-z_][A-Za-z0-9_]*)[\"']", r"process\.env\.([A-Za-z_][A-Za-z0-9_]*)",
49
+ r"process\.env\[\s*[\"']([A-Za-z_][A-Za-z0-9_]*)[\"']", r"System\.getenv\(\s*\"([A-Za-z_][A-Za-z0-9_]*)\"",
50
+ r"os\.Getenv\(\s*\"([A-Za-z_][A-Za-z0-9_]*)\"")]
51
+ _CONFIG_FILE = re.compile(r"[\"']([\w./\\-]*\.(?:json|ya?ml|toml|ini|env|cfg|conf|properties))[\"']")
52
+ _PORTS = [re.compile(pattern) for pattern in (
53
+ r"(?i)\bport\w*\s*[=:]\s*[\"']?(\d{2,5})\b", r"://[\w.-]+:(\d{2,5})\b", r"listen\(\s*(\d{2,5})\b")]
54
+ _REQUIREMENT = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*([^;#]*)")
55
+ _GO_REQUIRE = re.compile(r"^\s*(?:require\s+)?([\w.-]+\.[\w.-]+/[\w./-]+|[\w.-]+\.[\w.-]+)\s+(v[\w.+-]+)")
56
+ _POM = re.compile(r"<dependency>\s*<groupId>([^<]+)</groupId>\s*<artifactId>([^<]+)</artifactId>(?:\s*<version>([^<]+)</version>)?", re.S)
57
+ _ADR_STATUS = re.compile(r"^\s*(?:[-*]\s*)?(?:\*\*)?Status(?:\*\*)?\s*:?\s*(.+)$", re.I | re.M)
58
+ ADR_TEMPLATE = """# NNNN. Title of the decision
59
+
60
+ Status: proposed | accepted | superseded by NNNN
61
+ Date: YYYY-MM-DD
62
+
63
+ ## Context
64
+
65
+ What forces are at play: the problem, the constraints, what was tried.
66
+
67
+ ## Decision
68
+
69
+ What was chosen, in the active voice ("We use ...").
70
+
71
+ ## Consequences
72
+
73
+ What becomes easier, what becomes harder, what is left to decide."""
74
+ FILES = {"tests": "extras/tests.md", "configuration": "extras/configuration.md", "dependencies": "extras/dependencies.md",
75
+ "adr": "extras/adr/README.md", "structure": "extras/structure.md", "coverage": "extras/coverage.md",
76
+ "modules": "extras/modules.md", "flows": "extras/flows.md", "features_tests": "extras/features-tests.md",
77
+ "hotspots": "extras/hotspots.md", "coupling": "extras/coupling.md", "dead_code": "extras/dead-code.md",
78
+ "tour": "extras/tour.md", "glossary": "extras/glossary.md"}
79
+ TITLES = {"hotspots": "Hotspots", "coupling": "Change coupling", "dead_code": "Dead-code candidates",
80
+ "tour": "Onboarding tour", "glossary": "Glossary","tests": "Tests", "configuration": "Configuration", "dependencies": "Dependencies",
81
+ "adr": "Decision records", "structure": "Folder structure", "coverage": "Docstring coverage",
82
+ "modules": "Modules", "flows": "Flow per entry point", "features_tests": "Entry points x tests"}
83
+
84
+
85
+ def _head(model, title, depth=1):
86
+ """First lines of an extra page: generated marker, title, navigation and the truncation warning when it applies."""
87
+ up = "../" * depth
88
+ lines = [doc_scope.GENERATED, f"# {title}", "", f"[Scope]({up}README.md) · [Functional]({up}functional.md) · "
89
+ f"[Technical]({up}technical/README.md)", ""]
90
+ if model.graph.get("truncated"):
91
+ lines += [doc_scope.TRUNCATED]
92
+ return lines
93
+
94
+
95
+ def _done(lines):
96
+ return "\n".join(lines).rstrip("\n") + "\n"
97
+
98
+
99
+ def _folder(path):
100
+ return posixpath.dirname(path) or "(project root)"
101
+
102
+
103
+ def _source(root, path):
104
+ """Text of a project file, or None when it is too large or not UTF-8."""
105
+ full = os.path.join(root, path)
106
+ try:
107
+ if os.path.getsize(full) > MAX_SOURCE_BYTES:
108
+ return None
109
+ with open(full, encoding="utf-8") as stream:
110
+ return stream.read()
111
+ except (OSError, UnicodeDecodeError):
112
+ return None
113
+
114
+
115
+ def _entries(model, entries):
116
+ """Entry points paired with the tests that reach each, computed once per page set."""
117
+ return [(anchor, model.tests_of(anchor)) for anchor in entries[:MAX_ENTRIES]]
118
+
119
+
120
+ def _tests(model, covering, entries):
121
+ """README of the tests: one row per suite with its functions and the entry points they reach."""
122
+ by_file, reached = defaultdict(list), defaultdict(set)
123
+ for anchor, function in model.function_of.items():
124
+ if model.kind[function["path"]] == "test":
125
+ by_file[function["path"]].append(anchor)
126
+ for entry, tests in covering:
127
+ for test in tests:
128
+ reached[model.function_of[test]["path"]].add(entry)
129
+ lines = _head(model, "Tests")
130
+ if not by_file:
131
+ return _done(lines + ["No test function in the indexed code."])
132
+ lines += ["What each suite reaches through static calls (up to three hops) from its functions: the code files "
133
+ "(with how many functions of each) and the entry points of the functional overview.", "",
134
+ "| Suite | Functions | Code files it reaches | Entry points it reaches |", "|---|---|---|---|"]
135
+ for path in sorted(by_file):
136
+ names = sorted(reached[path], key=lambda a: (model.function_of[a]["path"], model.function_of[a]["start"]))
137
+ shown = [doc_scope.entry_link(model, a, entries, "../functional.md") for a in names[:doc_scope.MAX_LINKS]]
138
+ more = f" (+{len(names) - doc_scope.MAX_LINKS} more)" if len(names) > doc_scope.MAX_LINKS else ""
139
+ files = Counter(model.function_of[a]["path"] for test in by_file[path] for a in model.code_reached(test))
140
+ top = [f"`{f}` ({n})" for f, n in sorted(files.items(), key=lambda i: (-i[1], i[0]))[:3]]
141
+ rest = f" (+{len(files) - 3} more)" if len(files) > 3 else ""
142
+ lines.append(f"| `{path}` | {len(by_file[path])} | {', '.join(top) + rest if top else 'none'} "
143
+ f"| {', '.join(shown) + more if shown else 'none'} |")
144
+ return _done(lines)
145
+
146
+
147
+ def _configuration(model):
148
+ """README of the configuration the code reads: environment variables, config files and ports found by pattern."""
149
+ found = {"Environment variables": defaultdict(list), "Files": defaultdict(list), "Ports": defaultdict(list)}
150
+ paths = [p for p in model.files() if model.kind_of(p) == "code"][:MAX_SOURCE_FILES]
151
+ for path in paths:
152
+ text = _source(model.root, path)
153
+ if text is None:
154
+ continue
155
+ for number, line in enumerate(text.split("\n"), 1):
156
+ for pattern in _ENV:
157
+ for name in pattern.findall(line):
158
+ found["Environment variables"][name].append(f"{path}:{number}")
159
+ for name in _CONFIG_FILE.findall(line):
160
+ found["Files"][name].append(f"{path}:{number}")
161
+ for pattern in _PORTS:
162
+ for port in pattern.findall(line):
163
+ if int(port) <= 65535:
164
+ found["Ports"][port].append(f"{path}:{number}")
165
+ lines = _head(model, "Configuration")
166
+ lines += ["Found by pattern in the code files: a name built at run time is not listed.", ""]
167
+ for title, hits in found.items():
168
+ lines += [f"## {title}", ""]
169
+ if not hits:
170
+ lines += ["None found.", ""]
171
+ continue
172
+ lines += ["| Name | Read at |", "|---|---|"]
173
+ for name in sorted(hits):
174
+ where = sorted(set(hits[name]))
175
+ lines.append(f"| `{name}` | {', '.join(where[:MAX_HITS])}{f' (+{len(where) - MAX_HITS} more)' if len(where) > MAX_HITS else ''} |")
176
+ lines.append("")
177
+ return _done(lines)
178
+
179
+
180
+ def _normal(name):
181
+ return re.sub(r"[-_.]+", "-", name).lower()
182
+
183
+
184
+ def _python_licenses(root):
185
+ """Normalized package name -> license text declared by the packages installed in the project's own virtualenv."""
186
+ folders = []
187
+ for env in (".venv", "venv"):
188
+ folders += glob.glob(os.path.join(root, env, "Lib", "site-packages"))
189
+ folders += glob.glob(os.path.join(root, env, "lib", "python*", "site-packages"))
190
+ licenses = {}
191
+ for dist in metadata.distributions(path=folders) if folders else []:
192
+ info, name = dist.metadata, dist.metadata["Name"]
193
+ text = (info.get("License-Expression") or "").strip()
194
+ if not text:
195
+ classified = [c.split("::")[-1].strip() for c in info.get_all("Classifier", []) if c.startswith("License ::")]
196
+ text = ", ".join(classified) or (info.get("License") or "").strip()
197
+ if "\n" in text or len(text) > 80:
198
+ text = "declared in the package metadata"
199
+ if name:
200
+ licenses[_normal(name)] = text or "none declared"
201
+ return licenses
202
+
203
+
204
+ def _node_license(root, folder, name):
205
+ for base in (folder, ""):
206
+ try:
207
+ with open(os.path.join(root, base, "node_modules", name, "package.json"), encoding="utf-8") as stream:
208
+ data = json.load(stream)
209
+ except (OSError, ValueError):
210
+ continue
211
+ value = data.get("license") or data.get("licenses")
212
+ return value if isinstance(value, str) else json.dumps(value) if value else "none declared"
213
+ return None
214
+
215
+
216
+ def _manifest(root, path):
217
+ """Dependencies declared by one manifest: (rows of ecosystem, name, spec, scope), or a note when unreadable."""
218
+ base = posixpath.basename(path)
219
+ text = _source(root, path)
220
+ if text is None:
221
+ return [], "could not be read as UTF-8 within the size limit"
222
+ rows = []
223
+ try:
224
+ if re.fullmatch(r"requirements[\w.-]*\.txt", base):
225
+ for line in text.splitlines():
226
+ found = _REQUIREMENT.match(line)
227
+ if found and not line.lstrip().startswith(("-", "#")):
228
+ rows.append(("python", found.group(1), found.group(2).strip().rstrip("\\").strip(), "runtime"))
229
+ elif base == "pyproject.toml":
230
+ data = tomllib.loads(text)
231
+ project = data.get("project", {})
232
+ groups = [("runtime", project.get("dependencies", []))] + \
233
+ [(f"extra {k}", v) for k, v in project.get("optional-dependencies", {}).items()]
234
+ for scope, items in groups:
235
+ for item in items:
236
+ found = _REQUIREMENT.match(item)
237
+ if found:
238
+ rows.append(("python", found.group(1), found.group(2).strip(), scope))
239
+ for name, spec in data.get("tool", {}).get("poetry", {}).get("dependencies", {}).items():
240
+ if name.lower() != "python":
241
+ rows.append(("python", name, spec if isinstance(spec, str) else json.dumps(spec), "runtime"))
242
+ elif base == "package.json":
243
+ data = json.loads(text)
244
+ for key, scope in (("dependencies", "runtime"), ("devDependencies", "dev"), ("peerDependencies", "peer"),
245
+ ("optionalDependencies", "optional")):
246
+ rows += [("node", name, spec, scope) for name, spec in (data.get(key) or {}).items()]
247
+ elif base == "go.mod":
248
+ for line in text.splitlines():
249
+ found = _GO_REQUIRE.match(line)
250
+ if found:
251
+ rows.append(("go", found.group(1), found.group(2), "runtime"))
252
+ elif base == "pom.xml":
253
+ rows += [("java", f"{g.strip()}:{a.strip()}", (v or "").strip(), "runtime") for g, a, v in _POM.findall(text)]
254
+ except (ValueError, AttributeError, TypeError) as exc:
255
+ return [], f"could not be parsed ({exc})"
256
+ return rows, ""
257
+
258
+
259
+ def _dependencies(model):
260
+ """Map of the external dependencies of every manifest, with the license each installed package declares."""
261
+ manifests = [p for p in model.files() if re.fullmatch(r"requirements[\w.-]*\.txt|pyproject\.toml|package\.json|go\.mod|pom\.xml",
262
+ posixpath.basename(p))][:50]
263
+ lines = _head(model, "Dependencies")
264
+ if not manifests:
265
+ return _done(lines + ["No dependency manifest found (requirements*.txt, pyproject.toml, package.json, go.mod, pom.xml)."])
266
+ python = _python_licenses(model.root)
267
+ lines += ["Licenses come from the packages installed next to the manifest (the project's virtualenv or node_modules); "
268
+ "a package that is not installed there is marked, never guessed. Go and Maven licenses are not resolved.", ""]
269
+ for path in manifests:
270
+ rows, problem = _manifest(model.root, path)
271
+ lines += [f"## `{path}`", ""]
272
+ if problem:
273
+ lines += [f"Manifest {problem}.", ""]
274
+ continue
275
+ if not rows:
276
+ lines += ["No dependency declared.", ""]
277
+ continue
278
+ lines += ["| Package | Version | Scope | License |", "|---|---|---|---|"]
279
+ for ecosystem, name, spec, scope in sorted(rows, key=lambda r: (r[3], r[1].lower())):
280
+ if ecosystem == "python":
281
+ license_ = python.get(_normal(name), "not installed in the project")
282
+ elif ecosystem == "node":
283
+ license_ = _node_license(model.root, posixpath.dirname(path), name) or "not installed in the project"
284
+ else:
285
+ license_ = "not resolved"
286
+ lines.append(f"| `{name}` | {spec or '-'} | {scope} | {license_} |")
287
+ lines.append("")
288
+ return _done(lines)
289
+
290
+
291
+ def _decisions(model):
292
+ """Markdown files of decision records already in the project (outside the generated ones): (path, title, status)."""
293
+ found = []
294
+ for folder in ADR_DIRS:
295
+ for path in sorted(glob.glob(os.path.join(model.root, folder, "*.md"))):
296
+ text = _source(model.root, os.path.relpath(path, model.root).replace(os.sep, "/"))
297
+ if text is None or text.startswith(doc_scope.GENERATED):
298
+ continue
299
+ title = next((l.lstrip("# ").strip() for l in text.splitlines() if l.startswith("#")), os.path.basename(path))
300
+ status = _ADR_STATUS.search(text)
301
+ found.append((os.path.relpath(path, model.root).replace(os.sep, "/"), title, status.group(1).strip() if status else "-"))
302
+ return found
303
+
304
+
305
+ def _adr(model, commits, note):
306
+ """Index of the project's decision records, the template to copy and the decision candidates in the git log."""
307
+ lines = _head(model, "Decision records", depth=2)
308
+ here = "docs/scope/extras/adr"
309
+ records = _decisions(model)
310
+ lines += ["## Records", ""]
311
+ if records:
312
+ lines += ["| Record | Status |", "|---|---|"]
313
+ lines += [f"| [{title}](<{posixpath.relpath(path, here)}>) | {status} |" for path, title, status in records]
314
+ else:
315
+ lines += ["No record yet in " + ", ".join(f"`{d}`" for d in ADR_DIRS) + "."]
316
+ lines += ["", "## Template", "", "Copy it to a new file named `NNNN-title.md` in `docs/adr`; this page is regenerated "
317
+ "and lists what that folder holds.", "", "```markdown", ADR_TEMPLATE, "```"]
318
+ return _done(lines + doc_insights.adr_section(commits, note))
319
+
320
+
321
+ def _structure(model):
322
+ """Folder tree of the indexed files with the count of code, test and doc files under each folder."""
323
+ totals, children = defaultdict(Counter), defaultdict(set)
324
+ for path in model.files():
325
+ kind = model.kind_of(path) or "other"
326
+ parts = path.split("/")[:-1]
327
+ totals[""][kind] += 1
328
+ for depth in range(1, len(parts) + 1):
329
+ folder = "/".join(parts[:depth])
330
+ totals[folder][kind] += 1
331
+ children["/".join(parts[:depth - 1])].add(folder)
332
+
333
+ def counts(folder):
334
+ shown = [f"{label} {totals[folder][kind]}" for kind, label in (("code", "code"), ("test", "tests"), ("doc", "docs"))
335
+ if totals[folder][kind]]
336
+ return f" ({', '.join(shown)})" if shown else ""
337
+
338
+ body, hidden = [], 0
339
+
340
+ def walk(folder, prefix, depth):
341
+ nonlocal hidden
342
+ kids = sorted(children[folder])
343
+ for index, child in enumerate(kids):
344
+ if len(body) >= MAX_TREE_LINES or depth >= TREE_DEPTH:
345
+ hidden += sum(1 for _ in kids[index:])
346
+ return
347
+ last = index == len(kids) - 1
348
+ body.append(f"{prefix}{'└── ' if last else '├── '}{posixpath.basename(child)}/{counts(child)}")
349
+ walk(child, prefix + (" " if last else "│ "), depth + 1)
350
+
351
+ walk("", "", 0)
352
+ lines = _head(model, "Folder structure")
353
+ lines += ["Folders of the indexed files, with how many code, test and doc files each holds (files in subfolders "
354
+ "included).", "", "```text", f"(project root){counts('')}"] + body + ["```"]
355
+ if hidden:
356
+ lines += ["", f"{hidden} folder(s) are not drawn: the tree stops at {TREE_DEPTH} levels or {MAX_TREE_LINES} lines."]
357
+ return _done(lines)
358
+
359
+
360
+ def _coverage(model):
361
+ """Docstring coverage of the public code functions per folder, as a Markdown table."""
362
+ stats = defaultdict(lambda: [0, 0])
363
+ for anchor in model.public():
364
+ function = model.function_of[anchor]
365
+ row = stats[_folder(function["path"])]
366
+ row[0] += 1
367
+ row[1] += bool(function["documented"])
368
+ lines = _head(model, "Docstring coverage")
369
+ lines += ["| Folder | Public functions | Documented | Coverage |", "|---|---|---|---|"]
370
+ for folder in sorted(stats):
371
+ total, documented = stats[folder]
372
+ lines.append(f"| `{folder}` | {total} | {documented} | {100 * documented // total}% |")
373
+ total = sum(row[0] for row in stats.values())
374
+ documented = sum(row[1] for row in stats.values())
375
+ lines.append(f"| **All** | {total} | {documented} | {100 * documented // total if total else 0}% |")
376
+ return _done(lines)
377
+
378
+
379
+ def _modules(model):
380
+ """Mermaid flowchart of the calls between code modules (files), the strongest edges first."""
381
+ weights = defaultdict(int)
382
+ for source, targets in model.callees.items():
383
+ for target in targets:
384
+ a, b = model.function_of[source]["path"], model.function_of[target]["path"]
385
+ if a != b and model.kind[a] == "code" and model.kind[b] == "code":
386
+ weights[(a, b)] += 1
387
+ edges = sorted(weights.items(), key=lambda item: (-item[1], item[0]))[:doc_scope.MAX_FLOW_EDGES]
388
+ names = sorted({m for edge, _n in edges for m in edge})
389
+ node = {name: f"m{i}" for i, name in enumerate(names)}
390
+ lines = _head(model, "Modules")
391
+ if not edges:
392
+ return _done(lines + ["No call between two code modules in the graph."])
393
+ lines += ["The calls between modules, the strongest " + str(doc_scope.MAX_FLOW_EDGES) + " edges; the number is how "
394
+ "many functions call across.", "", "```mermaid", "flowchart LR"]
395
+ lines += [f' {node[name]}["{name}"]' for name in names]
396
+ lines += [f" {node[a]} -->|{n}| {node[b]}" for (a, b), n in edges]
397
+ lines.append("```")
398
+ return _done(lines)
399
+
400
+
401
+ def _sequence(model, entry):
402
+ """Mermaid sequence diagram of the calls the flow of one entry point makes, depth first, at most MAX_MESSAGES.
403
+
404
+ Returns: (diagram lines, calls of the flow left out, whether any call is drawn).
405
+ """
406
+ edges = model.flow_edges(entry)
407
+ children = defaultdict(list)
408
+ for caller, callee in edges:
409
+ children[caller].append(callee)
410
+ order, stack = [], [entry]
411
+ while stack and len(order) < MAX_MESSAGES:
412
+ current = stack.pop()
413
+ for callee in reversed(children[current]):
414
+ stack.append(callee)
415
+ if current != entry:
416
+ order.append(current)
417
+ parent = {callee: caller for caller, callee in edges}
418
+ modules = []
419
+ for anchor in [entry] + order:
420
+ path = model.function_of[anchor]["path"]
421
+ if path not in modules:
422
+ modules.append(path)
423
+ lines = ["```mermaid", "sequenceDiagram"] + [f" participant P{i} as {path}" for i, path in enumerate(modules)]
424
+ for anchor in order:
425
+ source = model.function_of[parent[anchor]]["path"]
426
+ lines.append(f" P{modules.index(source)}->>P{modules.index(model.function_of[anchor]['path'])}: "
427
+ f"{model.function_of[anchor]['name']}")
428
+ return lines + ["```"], len(edges) - len(order), bool(order)
429
+
430
+
431
+ def _flows(model, entries):
432
+ """One Mermaid sequence diagram per entry point, anchored and signed like the functional overview."""
433
+ lines = _head(model, "Flow per entry point")
434
+ if not entries:
435
+ return _done(lines + ["No entry point found: declare the layers (project_manage action=layers)."])
436
+ lines += ["The static calls each entry point reaches, as a sequence between modules, in the order a depth-first "
437
+ "read of the call graph meets them.", ""]
438
+ for anchor in entries[:MAX_SEQUENCES]:
439
+ function = model.function_of[anchor]
440
+ diagram, left, drawn = _sequence(model, anchor)
441
+ lines += [f'<a id="{doc_scope._escape(anchor)}"></a>', f"## {doc_scope.entry_title(model, anchor, entries)}", "",
442
+ f'<!-- smart-tool:symbol id="{doc_scope._escape(anchor)}" signature="{doc_scope.signature_hash(function["signature"])}" -->',
443
+ "", f"Entry point in `{function['path']}`: {doc_scope.entry_link(model, anchor, entries, '../functional.md')}.", ""]
444
+ lines += diagram if drawn else ["No call from this entry point reaches another code function."]
445
+ if left > 0:
446
+ lines += ["", f"{left} more call(s) of this flow are not drawn."]
447
+ lines.append("")
448
+ if len(entries) > MAX_SEQUENCES:
449
+ lines.append(f"{len(entries) - MAX_SEQUENCES} more entry point(s) are not drawn.")
450
+ return _done(lines)
451
+
452
+
453
+ def _features_tests(model, covering, entries):
454
+ """Matrix of entry points against the tests that reach them, with the entry points no test reaches."""
455
+ lines = _head(model, "Entry points x tests")
456
+ if not covering:
457
+ return _done(lines + ["No entry point found: declare the layers (project_manage action=layers)."])
458
+ lines += ["| Entry point | Tests | Reached by |", "|---|---|---|"]
459
+ for anchor, tests in covering:
460
+ function = model.function_of[anchor]
461
+ shown = ", ".join(f"`{model.function_of[t]['name']}`" for t in tests[:3]) + (f" (+{len(tests) - 3} more)" if len(tests) > 3 else "")
462
+ marker = (f'<a id="{doc_scope._escape(anchor)}"></a><!-- smart-tool:symbol id="{doc_scope._escape(anchor)}" '
463
+ f'signature="{doc_scope.signature_hash(function["signature"])}" -->')
464
+ lines.append(f"| {marker}{doc_scope.entry_link(model, anchor, entries, '../functional.md')} | {len(tests)} | "
465
+ f"{shown or 'no test reaches it'} |")
466
+ bare = [a for a, tests in covering if not tests]
467
+ lines += ["", f"{len(bare)} of {len(covering)} entry point(s) have no test reaching them through static calls."]
468
+ return _done(lines)
469
+
470
+
471
+ def _index(model, entries, files, counts):
472
+ """The short block for AGENTS.md or llms.txt: where the documentation is and the entry points to start from."""
473
+ lines = ["## Project documentation (generated by Smart Tool)", "",
474
+ f"{counts['public']} public functions, {counts['entry_points']} entry points; layers: {counts['layers']}.", ""]
475
+ if model.graph.get("truncated"):
476
+ lines += [doc_scope.TRUNCATED]
477
+ lines += ["- [Plain words](<docs/scope/simple.md>)", "- [Functional overview](<docs/scope/functional.md>)",
478
+ "- [Technical reference](<docs/scope/technical/README.md>)"]
479
+ lines += [f"- [{TITLES[key]}](<docs/scope/{FILES[key]}>)" for key in config.DOCS_EXTRAS if FILES.get(key) in files]
480
+ if entries:
481
+ lines += ["", "Entry points:"]
482
+ lines += [f"- {doc_scope.entry_link(model, a, entries, 'docs/scope/functional.md')} (`{model.function_of[a]['path']}`)"
483
+ for a in entries[:INDEX_ENTRIES]]
484
+ return "\n".join(lines) + "\n"
485
+
486
+
487
+ def build(model, entries, counts, enabled):
488
+ """The enabled extra documents and the index block.
489
+
490
+ Parameters: model (doc_scope._Model); entries (list) entry-point anchors; counts (dict) of the scope index;
491
+ enabled (dict) config docs_extras. Returns: (files: relative path under docs/scope -> text, block: str or None).
492
+ """
493
+ files = {}
494
+ covering = _entries(model, entries) if enabled["tests"] or enabled["features_tests"] else []
495
+ commits, note = doc_insights.history(model.root) if any(enabled[k] for k in ("hotspots", "coupling", "adr")) else ([], None)
496
+ builders = {"hotspots": lambda: doc_insights.hotspots_page(model, _head, _done, commits, note),
497
+ "coupling": lambda: doc_insights.coupling_page(model, _head, _done, commits, note),
498
+ "dead_code": lambda: doc_insights.dead_code_page(model, _head, _done, entries),
499
+ "tour": lambda: doc_insights.tour_page(model, _head, _done, entries),
500
+ "glossary": lambda: doc_insights.glossary_page(model, _head, _done),"tests": lambda: _tests(model, covering, entries), "configuration": lambda: _configuration(model),
501
+ "dependencies": lambda: _dependencies(model), "structure": lambda: _structure(model),
502
+ "coverage": lambda: _coverage(model), "modules": lambda: _modules(model),
503
+ "flows": lambda: _flows(model, entries), "features_tests": lambda: _features_tests(model, covering, entries),
504
+ "adr": lambda: _adr(model, commits, note)}
505
+ for key, make in builders.items():
506
+ if enabled[key]:
507
+ files[FILES[key]] = make()
508
+ block = _index(model, entries, files, counts) if enabled["index"] else None
509
+ return files, block
510
+
511
+
512
+ def _index_target(root):
513
+ return next((name for name in INDEX_FILES if os.path.isfile(os.path.join(root, name))), None)
514
+
515
+
516
+ def write_index(root, block):
517
+ """Put block between the index markers of the existing AGENTS.md (else llms.txt), or take the markers out when block
518
+ is None. A file without markers gets the block appended; nothing else in it is touched.
519
+
520
+ Returns: the file name written, or None when neither file exists.
521
+ """
522
+ target = _index_target(root)
523
+ if target is None:
524
+ return None
525
+ full = os.path.join(root, target)
526
+ with open(full, encoding="utf-8") as stream:
527
+ text = stream.read()
528
+ starts, ends = text.count(INDEX_START), text.count(INDEX_END)
529
+ if starts != ends or starts > 1 or (starts and text.index(INDEX_START) > text.index(INDEX_END)):
530
+ raise ValueError(f"{full} has unbalanced Smart Tool index markers; keep one start and one end marker, or remove both.")
531
+ wrapped = f"{INDEX_START}\n{block}{INDEX_END}" if block is not None else ""
532
+ if starts:
533
+ pattern = re.compile(re.escape(INDEX_START) + r".*?" + re.escape(INDEX_END) + (r"\n?" if block is None else ""), re.S)
534
+ updated = pattern.sub(lambda _m: wrapped, text)
535
+ elif block is None:
536
+ return target
537
+ else:
538
+ updated = (text if not text or text.endswith("\n") else text + "\n") + ("\n" if text else "") + wrapped + "\n"
539
+ if updated != text:
540
+ atomic_io.write_text(full, updated)
541
+ return target
542
+
543
+
544
+ def index_links(root):
545
+ """Links of the index block into docs/scope: list of {file, line, target, anchor}, target relative to docs/scope."""
546
+ target = _index_target(root)
547
+ if target is None:
548
+ return []
549
+ with open(os.path.join(root, target), encoding="utf-8") as stream:
550
+ text = stream.read()
551
+ found = _INDEX_BLOCK.search(text)
552
+ if not found:
553
+ return []
554
+ first = text[:found.start(1)].count("\n") + 1
555
+ prefix, links = doc_scope.DOCS_DIR + "/", []
556
+ for offset, line in enumerate(found.group(1).splitlines()):
557
+ for path, anchor in doc_scope.LINK.findall(line):
558
+ if path.startswith(prefix):
559
+ links.append({"file": target, "line": first + offset, "target": path[len(prefix):],
560
+ "anchor": doc_scope.html.unescape(anchor)})
561
+ return links