timothyandClaude Opus 4.8
67619b2bf6
Adds scripts/build_decisions_catalog.py, which renders docs/decisions/README.md as a compact table of only 'active' decision records (sorted by key), and its test scripts/tests/test_build_catalog.py. Supports --check for CI drift detection. No decision records are migrated yet, so the generated catalog is currently empty (banner + header only) — expected at this stage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
86 lines
2.8 KiB
Python
86 lines
2.8 KiB
Python
#!/usr/bin/env python3
|
|
"""Generate docs/decisions/README.md — the compact ACTIVE decision catalog / task router.
|
|
|
|
Do not edit docs/decisions/README.md by hand; regenerate with this script. The decisions-validate
|
|
CI job checks it is in sync.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
import scripts.decisions_lib as dl
|
|
|
|
OUTPUT = dl.TOPIC_DIR / "README.md"
|
|
BANNER = "<!-- GENERATED by scripts/build_decisions_catalog.py — do not edit by hand. -->"
|
|
|
|
|
|
def _rel(rec) -> str:
|
|
"""Link from docs/decisions/README.md to the record's heading."""
|
|
src = Path(rec.source).name
|
|
anchor = _anchor(rec.heading)
|
|
if src == "decisions.md":
|
|
return f"../decisions.md#{anchor}"
|
|
return f"{src}#{anchor}"
|
|
|
|
|
|
def _anchor(heading: str) -> str:
|
|
# Gitea/GitHub slugger: lowercase, keep alphanumerics + underscore, spaces/hyphens → '-',
|
|
# drop other punctuation. Keeping '_' matters — headings like "…(`iptv.base_url`)…" anchor to
|
|
# …iptvbase_url…. VERIFY against Gitea's actual output on 2-3 real headings before trusting links
|
|
# (the catalog is the startup surface; a dead link there is expensive).
|
|
out = []
|
|
for ch in heading.lower():
|
|
if ch.isalnum() or ch == "_":
|
|
out.append(ch)
|
|
elif ch in " -":
|
|
out.append("-")
|
|
return "".join(out)
|
|
|
|
|
|
def render_catalog(records) -> str:
|
|
active = sorted(
|
|
[r for r in records if r.status == "active" and r.key],
|
|
key=lambda r: r.key,
|
|
)
|
|
lines = [
|
|
BANNER,
|
|
"",
|
|
"# Active decisions — catalog / task router",
|
|
"",
|
|
"The compact current view of settled decisions. Each row is an **active** record; follow",
|
|
"the link for rationale. Superseded/retired history lives in `archive/`. Regenerated by",
|
|
"`scripts/build_decisions_catalog.py`.",
|
|
"",
|
|
"| Key | Current rule | Since | Record |",
|
|
"| --- | --- | --- | --- |",
|
|
]
|
|
for r in active:
|
|
rule = (r.rule or "").replace("|", "\\|")
|
|
lines.append(f"| `{r.key}` | {rule} | {r.since or ''} | [link]({_rel(r)}) |")
|
|
lines.append("")
|
|
return "\n".join(lines)
|
|
|
|
|
|
def main(argv=None) -> int:
|
|
check = "--check" in (argv or sys.argv[1:])
|
|
want = render_catalog(dl.all_active_records())
|
|
have = OUTPUT.read_text(encoding="utf-8") if OUTPUT.exists() else ""
|
|
if check:
|
|
if want.strip() != have.strip():
|
|
print(
|
|
"build_decisions_catalog: docs/decisions/README.md is stale — regenerate.",
|
|
file=sys.stderr,
|
|
)
|
|
return 1
|
|
print("build_decisions_catalog: catalog up to date")
|
|
return 0
|
|
OUTPUT.write_text(want + "\n", encoding="utf-8")
|
|
print(f"build_decisions_catalog: wrote {OUTPUT}")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|