@rvdbreemen/adr-kit-opencode 0.52.0
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/.claude-plugin/plugin.json +29 -0
- package/LICENSE +21 -0
- package/README.md +850 -0
- package/bin/adr +1552 -0
- package/bin/adr-audit +454 -0
- package/bin/adr-context +584 -0
- package/bin/adr-discover +546 -0
- package/bin/adr-doctor +166 -0
- package/bin/adr-generate-scripts +421 -0
- package/bin/adr-grill-signal +131 -0
- package/bin/adr-guardian +1263 -0
- package/bin/adr-index +199 -0
- package/bin/adr-judge +2832 -0
- package/bin/adr-judge-precommit +87 -0
- package/bin/adr-lint +2087 -0
- package/bin/adr-mcp +1093 -0
- package/bin/adr-migrate +644 -0
- package/bin/adr-quality +275 -0
- package/bin/adr-readiness +211 -0
- package/bin/adr-readiness-ci +111 -0
- package/bin/adr-related +401 -0
- package/bin/adr-renumber +254 -0
- package/bin/adr-retire +467 -0
- package/bin/adr-settings +399 -0
- package/bin/adr-status +797 -0
- package/bin/adr-suggest +803 -0
- package/bin/adr-watch +674 -0
- package/bin/adr_catalog.py +536 -0
- package/bin/adr_config.py +280 -0
- package/bin/adr_doctor_checks.py +407 -0
- package/bin/adr_doctor_core.py +342 -0
- package/bin/adr_doctor_models.py +186 -0
- package/bin/adr_doctor_probes.py +216 -0
- package/bin/adr_format.py +786 -0
- package/bin/adr_grill_signal.py +123 -0
- package/bin/adr_guardian_queue.py +218 -0
- package/bin/adr_history_scan.py +278 -0
- package/bin/adr_index_core.py +443 -0
- package/bin/adr_llm.py +333 -0
- package/bin/adr_llm_judge_migration.py +314 -0
- package/bin/adr_quality_core.py +674 -0
- package/bin/adr_query.py +678 -0
- package/bin/adr_readiness.py +442 -0
- package/bin/adr_readiness_ci.py +123 -0
- package/bin/adr_regex.py +165 -0
- package/bin/adr_regex_worker.py +30 -0
- package/bin/adr_retrieval_health.py +385 -0
- package/bin/adr_schema.py +448 -0
- package/bin/adr_state.py +172 -0
- package/bin/bump-version +71 -0
- package/clients/workflows.json +229 -0
- package/hooks/__init__.py +1 -0
- package/hooks/adapters/__init__.py +13 -0
- package/hooks/adapters/claude.py +27 -0
- package/hooks/adapters/codex.py +26 -0
- package/hooks/adapters/copilot.py +11 -0
- package/hooks/adr-hook.py +128 -0
- package/hooks/adr_hook_core.py +843 -0
- package/hooks/adr_pr_guard.py +367 -0
- package/instructions/ADR-guide.md +48 -0
- package/instructions/adr.coding.md +82 -0
- package/instructions/adr.review.md +182 -0
- package/opencode/plugin.ts +451 -0
- package/package.json +41 -0
- package/schemas/adr-context-probes.schema.json +56 -0
- package/schemas/adr-enforcement.schema.json +57 -0
- package/schemas/adr-frontmatter.schema.json +144 -0
- package/schemas/adr-index.schema.json +276 -0
- package/schemas/adr-kit-config.schema.json +371 -0
- package/schemas/adr-readiness.schema.json +41 -0
- package/schemas/client-capabilities.schema.json +503 -0
- package/schemas/client-certification.schema.json +101 -0
- package/schemas/doctor-output.schema.json +92 -0
- package/schemas/marketplace.json.schema.json +70 -0
- package/schemas/plugin.json.schema.json +67 -0
- package/scripts/adr_settings.py +239 -0
- package/scripts/benchmark-adr-grilling.py +323 -0
- package/scripts/benchmark-client-generation.py +178 -0
- package/scripts/build-client-adapters.py +139 -0
- package/scripts/bump-version.py +304 -0
- package/scripts/check-branch-sync.py +243 -0
- package/scripts/check-release-version.py +81 -0
- package/scripts/client_certification.py +153 -0
- package/scripts/client_evidence.py +280 -0
- package/scripts/client_generation.py +288 -0
- package/scripts/client_generation_artifacts.py +351 -0
- package/scripts/client_generation_model.py +173 -0
- package/scripts/client_generation_state.py +260 -0
- package/scripts/client_support_matrix.py +360 -0
- package/scripts/install-agent-envs.py +300 -0
- package/scripts/probe-client-events.py +183 -0
- package/scripts/project_setup.py +379 -0
- package/scripts/refresh-otgw-corpus.py +219 -0
- package/scripts/settings.py +81 -0
- package/scripts/setup-project.py +205 -0
- package/scripts/sync-agent-plugins.py +17 -0
- package/scripts/version_sites.py +377 -0
- package/skills/adr/SKILL.md +780 -0
- package/skills/audit/SKILL.md +103 -0
- package/skills/context/SKILL.md +77 -0
- package/skills/grill/SKILL.md +84 -0
- package/skills/grill/agents/openai.yaml +4 -0
- package/skills/guardian/SKILL.md +316 -0
- package/skills/init/SKILL.md +499 -0
- package/skills/install-hooks/SKILL.md +154 -0
- package/skills/judge/SKILL.md +168 -0
- package/skills/lint/SKILL.md +321 -0
- package/skills/migrate/SKILL.md +313 -0
- package/skills/related/SKILL.md +62 -0
- package/skills/retire/SKILL.md +41 -0
- package/skills/review/SKILL.md +167 -0
- package/skills/settings/SKILL.md +73 -0
- package/skills/setup/SKILL.md +128 -0
- package/skills/supersede/SKILL.md +136 -0
- package/skills/upgrade/SKILL.md +273 -0
- package/templates/adr-kit-guide.md +354 -0
- package/templates/adr-template.canonical.md +115 -0
- package/templates/adr-template.madr.md +131 -0
- package/templates/adr-template.md +131 -0
- package/templates/adr-template.nygard.md +111 -0
- package/templates/cc-settings/guardian-hook-entry.json +9 -0
- package/templates/githooks/pre-commit +337 -0
- package/templates/github-workflows/adr-audit.yml +58 -0
- package/templates/github-workflows/adr-guardian-audit.yml +133 -0
- package/templates/github-workflows/adr-index-check.yml +30 -0
- package/templates/github-workflows/adr-judge.yml +31 -0
- package/templates/github-workflows/adr-readiness.yml +18 -0
- package/templates/validate_adr_template.py +38 -0
- package/templates/validate_adr_template.sh +74 -0
|
@@ -0,0 +1,443 @@
|
|
|
1
|
+
"""adr_index_core: the ADR index generator, separated from its CLI.
|
|
2
|
+
|
|
3
|
+
`bin/adr-index` was both the renderer and the command. That was fine while the
|
|
4
|
+
only caller was the command line, and it stopped being fine when the guardian
|
|
5
|
+
needed to answer one question at SessionStart -- *is the committed index still
|
|
6
|
+
what the generator would produce?* -- without spawning a subprocess, which its
|
|
7
|
+
own contract forbids.
|
|
8
|
+
|
|
9
|
+
So the rendering and comparison live here, importable like every other
|
|
10
|
+
``adr_*.py`` sibling, and ``bin/adr-index`` is the thin argument-parsing shell
|
|
11
|
+
over it. Nothing about the output changed in the move; the generator is still
|
|
12
|
+
the single source of truth for all three artefacts (README block, ADR-INDEX.md,
|
|
13
|
+
ADR-INDEX.json).
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import importlib.machinery
|
|
19
|
+
import importlib.util
|
|
20
|
+
import io
|
|
21
|
+
import json
|
|
22
|
+
import re
|
|
23
|
+
import sys
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
from typing import Dict, List, Optional
|
|
26
|
+
|
|
27
|
+
_BIN_DIR = Path(__file__).resolve().parent
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _load_sibling(name: str):
|
|
31
|
+
"""Import bin/<name>.py by explicit path, WITHOUT touching sys.path.
|
|
32
|
+
|
|
33
|
+
SEC-HIGH (TASK-62): `sys.path.insert(0, _BIN_DIR)` put this directory ahead
|
|
34
|
+
of the standard library for every import, so a module committed next to
|
|
35
|
+
this script executed as code -- and it re-added the very directory
|
|
36
|
+
CPython's -P / PYTHONSAFEPATH removes. Siblings are registered in
|
|
37
|
+
sys.modules under their bare name, so the plain `from adr_* import ...`
|
|
38
|
+
statements below (and the lazy ones inside functions) resolve from the
|
|
39
|
+
cache instead of the path. bin/adr-judge carries the full rationale.
|
|
40
|
+
"""
|
|
41
|
+
cached = sys.modules.get(name)
|
|
42
|
+
if cached is not None:
|
|
43
|
+
return cached
|
|
44
|
+
loader = importlib.machinery.SourceFileLoader(name, str(_BIN_DIR / f"{name}.py"))
|
|
45
|
+
spec = importlib.util.spec_from_loader(name, loader)
|
|
46
|
+
module = importlib.util.module_from_spec(spec)
|
|
47
|
+
sys.modules[name] = module
|
|
48
|
+
loader.exec_module(module)
|
|
49
|
+
return module
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
# Dependency order: adr_catalog imports adr_format and adr_schema.
|
|
53
|
+
_load_sibling("adr_format")
|
|
54
|
+
_load_sibling("adr_schema")
|
|
55
|
+
_load_sibling("adr_catalog")
|
|
56
|
+
|
|
57
|
+
from adr_catalog import (
|
|
58
|
+
build_graph_document,
|
|
59
|
+
discover_adr_files,
|
|
60
|
+
enforcement_globs as catalog_enforcement_globs,
|
|
61
|
+
load_adr_records,
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
BEGIN = "<!-- adr-kit-index:begin -->"
|
|
66
|
+
END = "<!-- adr-kit-index:end -->"
|
|
67
|
+
|
|
68
|
+
TITLE_RE = re.compile(r"^#\s+ADR-\d+[:\s]\s*(.+)$", re.MULTILINE)
|
|
69
|
+
DECISION_SECTION_RE = re.compile(
|
|
70
|
+
r"^##\s+Decision(.*?)(?=^##|\Z)", re.IGNORECASE | re.MULTILINE | re.DOTALL
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def _ensure_utf8_streams() -> None:
|
|
75
|
+
for stream_name in ("stdout", "stderr"):
|
|
76
|
+
stream = getattr(sys, stream_name, None)
|
|
77
|
+
if stream is None:
|
|
78
|
+
continue
|
|
79
|
+
buffer = getattr(stream, "buffer", None)
|
|
80
|
+
if buffer is None:
|
|
81
|
+
continue
|
|
82
|
+
try:
|
|
83
|
+
setattr(
|
|
84
|
+
sys,
|
|
85
|
+
stream_name,
|
|
86
|
+
io.TextIOWrapper(buffer, encoding="utf-8", newline="\n"),
|
|
87
|
+
)
|
|
88
|
+
except (AttributeError, ValueError):
|
|
89
|
+
pass
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def enforcement_globs(text: str) -> List[str]:
|
|
93
|
+
"""Return all path_glob strings from the ADR's Enforcement block."""
|
|
94
|
+
return catalog_enforcement_globs(text)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def discover_files(adr_dir: Path) -> List[Path]:
|
|
98
|
+
return discover_adr_files(adr_dir)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def load_index(adr_dir: Path) -> List[Dict]:
|
|
102
|
+
"""Load every ADR in adr_dir as a context-index row. One read per file."""
|
|
103
|
+
return load_adr_records(adr_dir)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _escape_cell(value: str) -> str:
|
|
107
|
+
return value.replace("|", "\\|").replace("\n", " ").strip()
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def render_markdown(rows: List[Dict]) -> str:
|
|
111
|
+
lines = [
|
|
112
|
+
"<!-- Generated by bin/adr-index. Do not edit by hand; regenerate with: bin/adr-index -o docs/adr/ADR-INDEX.md -->",
|
|
113
|
+
"",
|
|
114
|
+
"# ADR Index",
|
|
115
|
+
"",
|
|
116
|
+
"One row per Architecture Decision Record. Scope is the Enforcement "
|
|
117
|
+
"`path_glob` set that governs where the decision applies; only "
|
|
118
|
+
"`Accepted` ADRs are injected at edit time (ADR-004).",
|
|
119
|
+
"",
|
|
120
|
+
"| ADR | Status | Scope | Decision |",
|
|
121
|
+
"| --- | --- | --- | --- |",
|
|
122
|
+
]
|
|
123
|
+
for row in rows:
|
|
124
|
+
scope = ", ".join(f"`{glob}`" for glob in row["scope"]) if row["scope"] else "-"
|
|
125
|
+
decision = _escape_cell(row["decision"]) or "-"
|
|
126
|
+
lines.append(
|
|
127
|
+
f"| {row['adr_id']} | {row['status']} | {scope} | {decision} |"
|
|
128
|
+
)
|
|
129
|
+
if not rows:
|
|
130
|
+
lines.append("| _(none)_ | | | |")
|
|
131
|
+
return "\n".join(lines) + "\n"
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def render_context_json(rows: List[Dict]) -> str:
|
|
135
|
+
payload = [
|
|
136
|
+
{
|
|
137
|
+
"adr_id": row["adr_id"],
|
|
138
|
+
"title": row["title"],
|
|
139
|
+
"status": row["status"],
|
|
140
|
+
"format": row["format"],
|
|
141
|
+
"scope": row["scope"],
|
|
142
|
+
"decision": row["decision"],
|
|
143
|
+
"path": row["path"],
|
|
144
|
+
}
|
|
145
|
+
for row in rows
|
|
146
|
+
]
|
|
147
|
+
return json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def render_graph_json(rows: List[Dict]) -> str:
|
|
151
|
+
return json.dumps(
|
|
152
|
+
build_graph_document(rows),
|
|
153
|
+
indent=2,
|
|
154
|
+
ensure_ascii=False,
|
|
155
|
+
) + "\n"
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def _find_adr_dir(explicit: Optional[str]) -> Optional[Path]:
|
|
159
|
+
if explicit:
|
|
160
|
+
path = Path(explicit)
|
|
161
|
+
return path if path.is_dir() else None
|
|
162
|
+
for candidate in (Path("docs/adr"), Path("adr"), Path(".")):
|
|
163
|
+
if candidate.is_dir() and discover_files(candidate):
|
|
164
|
+
return candidate
|
|
165
|
+
return None
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _readme_record(record: Dict) -> Dict:
|
|
169
|
+
return {
|
|
170
|
+
"id": record["adr_id"],
|
|
171
|
+
"title": record["title"],
|
|
172
|
+
"status": record["status"],
|
|
173
|
+
"date": record["date"],
|
|
174
|
+
"supersedes": record["supersedes"],
|
|
175
|
+
"superseded_by": record["superseded_by"],
|
|
176
|
+
"file": record["path"],
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def _supersession_note(record: Dict) -> str:
|
|
181
|
+
notes: List[str] = []
|
|
182
|
+
if record.get("superseded_by"):
|
|
183
|
+
notes.append(f"Superseded by {record['superseded_by']}")
|
|
184
|
+
supersedes = record.get("supersedes") or []
|
|
185
|
+
if supersedes:
|
|
186
|
+
notes.append("Supersedes " + ", ".join(supersedes))
|
|
187
|
+
return "; ".join(notes) if notes else "-"
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def render_generated_readme_block(records: List[Dict], issues: List[str]) -> str:
|
|
191
|
+
status_counts: Dict[str, int] = {}
|
|
192
|
+
for record in records:
|
|
193
|
+
status_counts[record["status"]] = status_counts.get(record["status"], 0) + 1
|
|
194
|
+
|
|
195
|
+
lines = [
|
|
196
|
+
BEGIN,
|
|
197
|
+
"## ADR Index",
|
|
198
|
+
"",
|
|
199
|
+
"Generated by `bin/adr-index`. Do not edit between the sentinels.",
|
|
200
|
+
"",
|
|
201
|
+
"### Summary",
|
|
202
|
+
"",
|
|
203
|
+
"| Metric | Count |",
|
|
204
|
+
"| --- | ---: |",
|
|
205
|
+
f"| Total ADRs | {len(records)} |",
|
|
206
|
+
]
|
|
207
|
+
for status, count in sorted(status_counts.items()):
|
|
208
|
+
lines.append(f"| {status} | {count} |")
|
|
209
|
+
lines.extend(
|
|
210
|
+
[
|
|
211
|
+
f"| Duplicate IDs | {len(issues)} |",
|
|
212
|
+
"",
|
|
213
|
+
"### Decisions",
|
|
214
|
+
"",
|
|
215
|
+
"| ADR | Title | Status | Date | Supersession | File |",
|
|
216
|
+
"| --- | --- | --- | --- | --- | --- |",
|
|
217
|
+
]
|
|
218
|
+
)
|
|
219
|
+
for record in records:
|
|
220
|
+
lines.append(
|
|
221
|
+
"| "
|
|
222
|
+
+ " | ".join(
|
|
223
|
+
[
|
|
224
|
+
_escape_cell(record["id"]),
|
|
225
|
+
_escape_cell(record["title"]),
|
|
226
|
+
_escape_cell(record["status"]),
|
|
227
|
+
_escape_cell(record["date"] or "-"),
|
|
228
|
+
_escape_cell(_supersession_note(record)),
|
|
229
|
+
_escape_cell(record["file"]),
|
|
230
|
+
]
|
|
231
|
+
)
|
|
232
|
+
+ " |"
|
|
233
|
+
)
|
|
234
|
+
if issues:
|
|
235
|
+
lines.extend(["", "### Index Issues", ""])
|
|
236
|
+
lines.extend(f"- {issue}" for issue in issues)
|
|
237
|
+
lines.append(END)
|
|
238
|
+
lines.append("")
|
|
239
|
+
return "\n".join(lines)
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def default_readme(block: str) -> str:
|
|
243
|
+
return "\n".join(
|
|
244
|
+
[
|
|
245
|
+
"# Architecture Decision Records",
|
|
246
|
+
"",
|
|
247
|
+
"This README contains the generated local ADR index.",
|
|
248
|
+
"",
|
|
249
|
+
block.rstrip(),
|
|
250
|
+
"",
|
|
251
|
+
]
|
|
252
|
+
)
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def update_readme(existing: Optional[str], block: str) -> str:
|
|
256
|
+
if existing is None:
|
|
257
|
+
return default_readme(block)
|
|
258
|
+
if BEGIN in existing and END in existing:
|
|
259
|
+
before, rest = existing.split(BEGIN, 1)
|
|
260
|
+
_old, after = rest.split(END, 1)
|
|
261
|
+
return before.rstrip() + "\n\n" + block.rstrip() + after
|
|
262
|
+
return existing.rstrip() + "\n\n" + block.rstrip() + "\n"
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def build_readme_payload(adr_dir: Path, readme: Path) -> Dict:
|
|
266
|
+
index_rows = load_index(adr_dir)
|
|
267
|
+
records = [_readme_record(record) for record in index_rows]
|
|
268
|
+
grouped: Dict[str, List[str]] = {}
|
|
269
|
+
for record in records:
|
|
270
|
+
grouped.setdefault(record["id"], []).append(record["file"])
|
|
271
|
+
issues = [
|
|
272
|
+
f"{adr_id} appears in multiple files: {', '.join(files)}"
|
|
273
|
+
for adr_id, files in sorted(grouped.items())
|
|
274
|
+
if len(files) > 1
|
|
275
|
+
]
|
|
276
|
+
block = render_generated_readme_block(records, issues)
|
|
277
|
+
existing = readme.read_text(encoding="utf-8") if readme.exists() else None
|
|
278
|
+
desired_readme = update_readme(existing, block)
|
|
279
|
+
markdown_path = adr_dir / "ADR-INDEX.md"
|
|
280
|
+
json_path = adr_dir / "ADR-INDEX.json"
|
|
281
|
+
desired_markdown = render_markdown(index_rows)
|
|
282
|
+
desired_json = render_graph_json(index_rows)
|
|
283
|
+
current_markdown = (
|
|
284
|
+
markdown_path.read_text(encoding="utf-8") if markdown_path.exists() else None
|
|
285
|
+
)
|
|
286
|
+
current_json = json_path.read_text(encoding="utf-8") if json_path.exists() else None
|
|
287
|
+
readme_changed = existing != desired_readme
|
|
288
|
+
markdown_changed = current_markdown != desired_markdown
|
|
289
|
+
json_changed = current_json != desired_json
|
|
290
|
+
return {
|
|
291
|
+
"adr_dir": str(adr_dir),
|
|
292
|
+
"readme": str(readme),
|
|
293
|
+
"context_markdown": str(markdown_path),
|
|
294
|
+
"context_json": str(json_path),
|
|
295
|
+
"summary": {
|
|
296
|
+
"total": len(records),
|
|
297
|
+
"duplicates": len(issues),
|
|
298
|
+
"changed": readme_changed or markdown_changed or json_changed,
|
|
299
|
+
"readme_changed": readme_changed,
|
|
300
|
+
"context_markdown_changed": markdown_changed,
|
|
301
|
+
"context_json_changed": json_changed,
|
|
302
|
+
},
|
|
303
|
+
"issues": issues,
|
|
304
|
+
"records": records,
|
|
305
|
+
"_desired_readme": desired_readme,
|
|
306
|
+
"_desired_markdown": desired_markdown,
|
|
307
|
+
"_desired_json": desired_json,
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
|
|
311
|
+
def render_readme_text(payload: Dict, check: bool) -> str:
|
|
312
|
+
summary = payload["summary"]
|
|
313
|
+
lines = [
|
|
314
|
+
f"adr-index {'check' if check else 'write'}: {payload['readme']}",
|
|
315
|
+
f"ADRs: {summary['total']}; duplicates: {summary['duplicates']}; changed: {summary['changed']}",
|
|
316
|
+
"Artifacts: "
|
|
317
|
+
f"README={summary['readme_changed']}; "
|
|
318
|
+
f"Markdown={summary['context_markdown_changed']}; "
|
|
319
|
+
f"JSON={summary['context_json_changed']}",
|
|
320
|
+
]
|
|
321
|
+
for issue in payload["issues"]:
|
|
322
|
+
lines.append(f" issue: {issue}")
|
|
323
|
+
return "\n".join(lines)
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
INDEX_ARTIFACTS = ("README.md", "ADR-INDEX.md", "ADR-INDEX.json")
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
def stale_index_artifacts(adr_dir: Path) -> List[str]:
|
|
330
|
+
"""Which generated index artefacts no longer match the ADRs, if any.
|
|
331
|
+
|
|
332
|
+
Returns the artefact filenames that would change if the generator ran now.
|
|
333
|
+
An empty list means the committed index tells the truth.
|
|
334
|
+
|
|
335
|
+
Callers on a hook budget should gate this behind ``index_probably_fresh``:
|
|
336
|
+
this function reads and re-renders every ADR, which is cheap on a normal
|
|
337
|
+
set and not free on a large one.
|
|
338
|
+
"""
|
|
339
|
+
if not adr_dir.is_dir() or not discover_adr_files(adr_dir):
|
|
340
|
+
# No ADRs means no index to be stale about. Reporting three missing
|
|
341
|
+
# artefacts in a project that has not written its first decision yet is
|
|
342
|
+
# a false alarm, and a false alarm is how a check gets ignored.
|
|
343
|
+
return []
|
|
344
|
+
try:
|
|
345
|
+
payload = build_readme_payload(adr_dir, adr_dir / "README.md")
|
|
346
|
+
except (OSError, ValueError):
|
|
347
|
+
# A generator that cannot run is not evidence of a stale index. Say
|
|
348
|
+
# nothing rather than nudge about a failure the user cannot act on.
|
|
349
|
+
return []
|
|
350
|
+
desired = {
|
|
351
|
+
"README.md": payload.pop("_desired_readme"),
|
|
352
|
+
"ADR-INDEX.md": payload.pop("_desired_markdown"),
|
|
353
|
+
"ADR-INDEX.json": payload.pop("_desired_json"),
|
|
354
|
+
}
|
|
355
|
+
stale: List[str] = []
|
|
356
|
+
for name, want in desired.items():
|
|
357
|
+
path = adr_dir / name
|
|
358
|
+
try:
|
|
359
|
+
have = path.read_text(encoding="utf-8")
|
|
360
|
+
except OSError:
|
|
361
|
+
stale.append(name)
|
|
362
|
+
continue
|
|
363
|
+
if have != want:
|
|
364
|
+
stale.append(name)
|
|
365
|
+
return stale
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
def index_probably_fresh(adr_dir: Path) -> bool:
|
|
369
|
+
"""Cheap mtime precondition: no ADR is newer than every index artefact.
|
|
370
|
+
|
|
371
|
+
True means "skip the full render" for an advisory nudge. It is deliberately
|
|
372
|
+
NOT proof of freshness -- a hand-edited ADR-INDEX.md is newer than every
|
|
373
|
+
ADR and still wrong, and a checkout can give every file the same timestamp.
|
|
374
|
+
Use it to avoid work, never to certify a result. The real answer is
|
|
375
|
+
``stale_index_artifacts``, and CI runs that one unconditionally.
|
|
376
|
+
"""
|
|
377
|
+
if not adr_dir.is_dir():
|
|
378
|
+
return True
|
|
379
|
+
try:
|
|
380
|
+
newest_adr = max(
|
|
381
|
+
(path.stat().st_mtime for path in discover_adr_files(adr_dir)),
|
|
382
|
+
default=None,
|
|
383
|
+
)
|
|
384
|
+
if newest_adr is None:
|
|
385
|
+
return True
|
|
386
|
+
oldest_index = min(
|
|
387
|
+
(adr_dir / name).stat().st_mtime for name in INDEX_ARTIFACTS
|
|
388
|
+
)
|
|
389
|
+
except OSError:
|
|
390
|
+
return False
|
|
391
|
+
return oldest_index >= newest_adr
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
# Measured on this repository, 2026-08-05: a full in-process render of 29 ADRs
|
|
395
|
+
# costs ~84 ms median, about 4.7 ms per ADR, against a 2.8 ms freshness probe.
|
|
396
|
+
# Through a subprocess the same work costs ~302 ms, which is why ADR-021 requires
|
|
397
|
+
# in-process regeneration rather than spawning the generator.
|
|
398
|
+
MS_PER_ADR_RENDER = 4.7
|
|
399
|
+
RENDER_FIXED_COST_MS = 50.0
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
def projected_render_ms(adr_dir: Path) -> float:
|
|
403
|
+
"""What a full regeneration of this directory is likely to cost.
|
|
404
|
+
|
|
405
|
+
Deliberately a projection from a count rather than a trial run: the point is
|
|
406
|
+
to decide whether to start, and a measurement that had to render first would
|
|
407
|
+
have already spent the budget it exists to protect.
|
|
408
|
+
"""
|
|
409
|
+
try:
|
|
410
|
+
count = sum(1 for _ in discover_adr_files(adr_dir))
|
|
411
|
+
except OSError:
|
|
412
|
+
return float("inf")
|
|
413
|
+
return RENDER_FIXED_COST_MS + count * MS_PER_ADR_RENDER
|
|
414
|
+
|
|
415
|
+
|
|
416
|
+
def regenerate_index(adr_dir: Path, readme: Optional[Path] = None) -> List[str]:
|
|
417
|
+
"""Rewrite the generated index artefacts in place. Returns what changed.
|
|
418
|
+
|
|
419
|
+
The write half of `bin/adr-index`, without the process. ADR-021 needs this
|
|
420
|
+
callable from the hook: spawning the generator costs ~302 ms against ~84 ms
|
|
421
|
+
in-process, and the events that may regenerate carry a budget that cannot
|
|
422
|
+
hold the difference.
|
|
423
|
+
|
|
424
|
+
Raises rather than guessing when the ADR set has issues the generator cannot
|
|
425
|
+
resolve -- the caller is a fail-open hook and decides what to do with that.
|
|
426
|
+
"""
|
|
427
|
+
payload = build_readme_payload(adr_dir, readme or (adr_dir / "README.md"))
|
|
428
|
+
desired_readme = payload.pop("_desired_readme")
|
|
429
|
+
desired_markdown = payload.pop("_desired_markdown")
|
|
430
|
+
desired_json = payload.pop("_desired_json")
|
|
431
|
+
if payload["issues"]:
|
|
432
|
+
raise ValueError("; ".join(str(issue) for issue in payload["issues"]))
|
|
433
|
+
|
|
434
|
+
target_readme = readme or (adr_dir / "README.md")
|
|
435
|
+
adr_dir.mkdir(parents=True, exist_ok=True)
|
|
436
|
+
target_readme.parent.mkdir(parents=True, exist_ok=True)
|
|
437
|
+
target_readme.write_text(desired_readme, encoding="utf-8")
|
|
438
|
+
(adr_dir / "ADR-INDEX.md").write_text(desired_markdown, encoding="utf-8")
|
|
439
|
+
(adr_dir / "ADR-INDEX.json").write_text(desired_json, encoding="utf-8")
|
|
440
|
+
# `summary["changed"]` is a boolean in the CLI's payload, not a list of
|
|
441
|
+
# names. Report which artefacts this call rewrote rather than passing that
|
|
442
|
+
# flag through as if it were the answer.
|
|
443
|
+
return list(INDEX_ARTIFACTS) if payload["summary"].get("changed") else []
|