@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
package/bin/adr-related
ADDED
|
@@ -0,0 +1,401 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""adr-related: ADR dependency graph for a single ADR.
|
|
3
|
+
|
|
4
|
+
Walks the whole ADR set and prints the inbound and outbound edges for the
|
|
5
|
+
given ADR:
|
|
6
|
+
|
|
7
|
+
- Outbound: entries in its "## Related Decisions" section, its
|
|
8
|
+
"Superseded by ADR-X" / "Amended by ADR-X" status references, and any
|
|
9
|
+
"Supersedes ADR-X" claims it makes.
|
|
10
|
+
- Inbound: every other ADR that references it, with the reference kind
|
|
11
|
+
(related, supersedes, superseded-by, amended-by, mention).
|
|
12
|
+
|
|
13
|
+
Matching is whole-token only: looking for ADR-043 never matches ADR-0430.
|
|
14
|
+
Dangling references (target id does not exist in the set) are flagged.
|
|
15
|
+
|
|
16
|
+
Read-only. Exit 0 on success, 2 on usage/config errors (unknown ADR id,
|
|
17
|
+
missing directory).
|
|
18
|
+
|
|
19
|
+
Usage:
|
|
20
|
+
adr-related ADR-007
|
|
21
|
+
adr-related 7 --adr-dir docs/adr
|
|
22
|
+
adr-related ADR-007 --format json
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import argparse
|
|
28
|
+
import importlib.machinery
|
|
29
|
+
import importlib.util
|
|
30
|
+
import json
|
|
31
|
+
import re
|
|
32
|
+
import sys
|
|
33
|
+
from pathlib import Path
|
|
34
|
+
from typing import Dict, List, Optional
|
|
35
|
+
|
|
36
|
+
_BIN_DIR = Path(__file__).resolve().parent
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _load_sibling(name: str):
|
|
40
|
+
"""Import bin/<name>.py by explicit path, WITHOUT touching sys.path.
|
|
41
|
+
|
|
42
|
+
SEC-HIGH (TASK-62): `sys.path.insert(0, _BIN_DIR)` put this directory ahead
|
|
43
|
+
of the standard library for every import, so a module committed next to
|
|
44
|
+
this script executed as code -- and it re-added the very directory
|
|
45
|
+
CPython's -P / PYTHONSAFEPATH removes. Siblings are registered in
|
|
46
|
+
sys.modules under their bare name, so the plain `from adr_* import ...`
|
|
47
|
+
statements below (and the lazy ones inside functions) resolve from the
|
|
48
|
+
cache instead of the path. bin/adr-judge carries the full rationale.
|
|
49
|
+
"""
|
|
50
|
+
cached = sys.modules.get(name)
|
|
51
|
+
if cached is not None:
|
|
52
|
+
return cached
|
|
53
|
+
loader = importlib.machinery.SourceFileLoader(name, str(_BIN_DIR / f"{name}.py"))
|
|
54
|
+
spec = importlib.util.spec_from_loader(name, loader)
|
|
55
|
+
module = importlib.util.module_from_spec(spec)
|
|
56
|
+
sys.modules[name] = module
|
|
57
|
+
loader.exec_module(module)
|
|
58
|
+
return module
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
# Dependency order: adr_catalog imports adr_format and adr_schema.
|
|
62
|
+
_load_sibling("adr_format")
|
|
63
|
+
_load_sibling("adr_schema")
|
|
64
|
+
_load_sibling("adr_catalog")
|
|
65
|
+
|
|
66
|
+
from adr_catalog import load_adr_record
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
# ---------------------------------------------------------------------------
|
|
70
|
+
# Module-level compiled regexes (all linear; no nested quantifiers)
|
|
71
|
+
# ---------------------------------------------------------------------------
|
|
72
|
+
|
|
73
|
+
# ADR id token. \b on both sides gives whole-token matching: the greedy
|
|
74
|
+
# \d{1,4} consumes all adjacent digits, so ADR-0430 can never be read as
|
|
75
|
+
# ADR-043 plus a stray "0".
|
|
76
|
+
_ADR_TOKEN_RE = re.compile(r"\bADR-(\d{1,4})\b", re.IGNORECASE)
|
|
77
|
+
|
|
78
|
+
# ADR id from a filename (no trailing \b: filenames continue with "-slug").
|
|
79
|
+
_ADR_FILENAME_RE = re.compile(r"ADR-(\d{1,4})", re.IGNORECASE)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
# Reference kinds, in display order (most specific first).
|
|
83
|
+
KIND_ORDER = ["supersedes", "superseded-by", "amended-by", "related", "mention"]
|
|
84
|
+
_KIND_RANK = {k: i for i, k in enumerate(KIND_ORDER)}
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
# ---------------------------------------------------------------------------
|
|
88
|
+
# Per-ADR record
|
|
89
|
+
# ---------------------------------------------------------------------------
|
|
90
|
+
|
|
91
|
+
class AdrRefs:
|
|
92
|
+
"""Reference profile of a single ADR file.
|
|
93
|
+
|
|
94
|
+
Plain class (not @dataclass) for SourceFileLoader compatibility,
|
|
95
|
+
matching bin/adr-status.
|
|
96
|
+
"""
|
|
97
|
+
|
|
98
|
+
__slots__ = (
|
|
99
|
+
"path", "adr_id", "title", "status",
|
|
100
|
+
"related_ids", "supersedes_ids", "superseded_by_ids",
|
|
101
|
+
"amended_by_ids", "mention_ids",
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
def __init__(
|
|
105
|
+
self,
|
|
106
|
+
path: Path,
|
|
107
|
+
adr_id: str,
|
|
108
|
+
title: str,
|
|
109
|
+
status: str,
|
|
110
|
+
related_ids: List[str],
|
|
111
|
+
supersedes_ids: List[str],
|
|
112
|
+
superseded_by_ids: List[str],
|
|
113
|
+
amended_by_ids: List[str],
|
|
114
|
+
mention_ids: List[str],
|
|
115
|
+
) -> None:
|
|
116
|
+
self.path = path
|
|
117
|
+
self.adr_id = adr_id
|
|
118
|
+
self.title = title
|
|
119
|
+
self.status = status
|
|
120
|
+
self.related_ids = related_ids
|
|
121
|
+
self.supersedes_ids = supersedes_ids
|
|
122
|
+
self.superseded_by_ids = superseded_by_ids
|
|
123
|
+
self.amended_by_ids = amended_by_ids
|
|
124
|
+
self.mention_ids = mention_ids
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def normalize_adr_id(raw: str) -> Optional[str]:
|
|
128
|
+
"""Normalize 'ADR-7', 'adr-007', or '7' to 'ADR-007'. None if invalid."""
|
|
129
|
+
s = raw.strip()
|
|
130
|
+
m = re.fullmatch(r"(?:ADR-)?(\d{1,4})", s, re.IGNORECASE)
|
|
131
|
+
if not m:
|
|
132
|
+
return None
|
|
133
|
+
return f"ADR-{int(m.group(1)):03d}"
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def _ids_from(pattern: re.Pattern, text: str) -> List[str]:
|
|
137
|
+
"""Unique normalized ADR ids matched by pattern, in first-seen order."""
|
|
138
|
+
seen: List[str] = []
|
|
139
|
+
for m in pattern.finditer(text):
|
|
140
|
+
adr_id = f"ADR-{int(m.group(1)):03d}"
|
|
141
|
+
if adr_id not in seen:
|
|
142
|
+
seen.append(adr_id)
|
|
143
|
+
return seen
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def parse_adr_refs(path: Path) -> Optional[AdrRefs]:
|
|
147
|
+
"""Read one ADR file and extract its reference profile.
|
|
148
|
+
|
|
149
|
+
Returns None if the file cannot be read or the name has no ADR id.
|
|
150
|
+
"""
|
|
151
|
+
m = _ADR_FILENAME_RE.search(path.name)
|
|
152
|
+
if not m:
|
|
153
|
+
return None
|
|
154
|
+
adr_id = f"ADR-{int(m.group(1)):03d}"
|
|
155
|
+
|
|
156
|
+
try:
|
|
157
|
+
content = path.read_text(encoding="utf-8")
|
|
158
|
+
record = load_adr_record(path)
|
|
159
|
+
except OSError:
|
|
160
|
+
return None
|
|
161
|
+
|
|
162
|
+
title = record["title"]
|
|
163
|
+
status = record["status"]
|
|
164
|
+
related_ids = record["related_ids"]
|
|
165
|
+
supersedes_ids = record["supersedes"]
|
|
166
|
+
superseded_by_ids = (
|
|
167
|
+
[record["superseded_by"]] if record["superseded_by"] else []
|
|
168
|
+
)
|
|
169
|
+
amended_by_ids = record["amended_by"]
|
|
170
|
+
|
|
171
|
+
classified = set(related_ids) | set(supersedes_ids) | set(superseded_by_ids) | set(amended_by_ids)
|
|
172
|
+
mention_ids = [
|
|
173
|
+
i for i in _ids_from(_ADR_TOKEN_RE, content)
|
|
174
|
+
if i != adr_id and i not in classified
|
|
175
|
+
]
|
|
176
|
+
|
|
177
|
+
return AdrRefs(
|
|
178
|
+
path=path,
|
|
179
|
+
adr_id=adr_id,
|
|
180
|
+
title=title,
|
|
181
|
+
status=status,
|
|
182
|
+
related_ids=related_ids,
|
|
183
|
+
supersedes_ids=supersedes_ids,
|
|
184
|
+
superseded_by_ids=superseded_by_ids,
|
|
185
|
+
amended_by_ids=amended_by_ids,
|
|
186
|
+
mention_ids=mention_ids,
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def load_adr_set(adr_dir: Path) -> List[AdrRefs]:
|
|
191
|
+
"""Load reference profiles for every ADR-*.md in adr_dir, sorted by name."""
|
|
192
|
+
records: List[AdrRefs] = []
|
|
193
|
+
for f in sorted(adr_dir.glob("ADR-*.md")):
|
|
194
|
+
rec = parse_adr_refs(f)
|
|
195
|
+
if rec is not None:
|
|
196
|
+
records.append(rec)
|
|
197
|
+
return records
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
# ---------------------------------------------------------------------------
|
|
201
|
+
# Graph construction
|
|
202
|
+
# ---------------------------------------------------------------------------
|
|
203
|
+
|
|
204
|
+
def _edges_of(rec: AdrRefs, include_mentions: bool) -> List[Dict[str, str]]:
|
|
205
|
+
"""Flatten one ADR's references into (target, kind) edge dicts."""
|
|
206
|
+
edges: List[Dict[str, str]] = []
|
|
207
|
+
kinds = [
|
|
208
|
+
("supersedes", rec.supersedes_ids),
|
|
209
|
+
("superseded-by", rec.superseded_by_ids),
|
|
210
|
+
("amended-by", rec.amended_by_ids),
|
|
211
|
+
("related", rec.related_ids),
|
|
212
|
+
]
|
|
213
|
+
if include_mentions:
|
|
214
|
+
kinds.append(("mention", rec.mention_ids))
|
|
215
|
+
for kind, ids in kinds:
|
|
216
|
+
for target in ids:
|
|
217
|
+
edges.append({"adr_id": target, "kind": kind})
|
|
218
|
+
return edges
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def build_graph(target_id: str, records: List[AdrRefs]) -> Dict:
|
|
222
|
+
"""Build the inbound/outbound graph for target_id over the loaded set.
|
|
223
|
+
|
|
224
|
+
Raises KeyError if target_id is not in the set.
|
|
225
|
+
"""
|
|
226
|
+
by_id: Dict[str, AdrRefs] = {r.adr_id: r for r in records}
|
|
227
|
+
if target_id not in by_id:
|
|
228
|
+
raise KeyError(target_id)
|
|
229
|
+
target = by_id[target_id]
|
|
230
|
+
|
|
231
|
+
def enrich(edge: Dict[str, str]) -> Dict:
|
|
232
|
+
other = by_id.get(edge["adr_id"])
|
|
233
|
+
return {
|
|
234
|
+
"adr_id": edge["adr_id"],
|
|
235
|
+
"kind": edge["kind"],
|
|
236
|
+
"exists": other is not None,
|
|
237
|
+
"title": other.title if other else None,
|
|
238
|
+
"status": other.status if other else None,
|
|
239
|
+
"path": str(other.path) if other else None,
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
# Outbound: the four explicit reference kinds of the target itself.
|
|
243
|
+
# Plain mentions inside the target are not outbound edges; they carry
|
|
244
|
+
# no declared relationship.
|
|
245
|
+
outbound = [enrich(e) for e in _edges_of(target, include_mentions=False)]
|
|
246
|
+
|
|
247
|
+
# Inbound: every other ADR whose references point at the target,
|
|
248
|
+
# including plain mentions (a mention of this ADR is still a dependency
|
|
249
|
+
# signal worth seeing).
|
|
250
|
+
inbound: List[Dict] = []
|
|
251
|
+
for rec in records:
|
|
252
|
+
if rec.adr_id == target_id:
|
|
253
|
+
continue
|
|
254
|
+
for edge in _edges_of(rec, include_mentions=True):
|
|
255
|
+
if edge["adr_id"] != target_id:
|
|
256
|
+
continue
|
|
257
|
+
inbound.append({
|
|
258
|
+
"adr_id": rec.adr_id,
|
|
259
|
+
"kind": edge["kind"],
|
|
260
|
+
"title": rec.title,
|
|
261
|
+
"status": rec.status,
|
|
262
|
+
"path": str(rec.path),
|
|
263
|
+
})
|
|
264
|
+
|
|
265
|
+
def sort_key(e: Dict):
|
|
266
|
+
return (e["adr_id"], _KIND_RANK.get(e["kind"], len(KIND_ORDER)))
|
|
267
|
+
|
|
268
|
+
outbound.sort(key=sort_key)
|
|
269
|
+
inbound.sort(key=sort_key)
|
|
270
|
+
|
|
271
|
+
dangling = sorted({e["adr_id"] for e in outbound if not e["exists"]})
|
|
272
|
+
|
|
273
|
+
return {
|
|
274
|
+
"adr": {
|
|
275
|
+
"adr_id": target.adr_id,
|
|
276
|
+
"title": target.title,
|
|
277
|
+
"status": target.status,
|
|
278
|
+
"path": str(target.path),
|
|
279
|
+
},
|
|
280
|
+
"outbound": outbound,
|
|
281
|
+
"inbound": inbound,
|
|
282
|
+
"dangling": dangling,
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
# ---------------------------------------------------------------------------
|
|
287
|
+
# Formatting
|
|
288
|
+
# ---------------------------------------------------------------------------
|
|
289
|
+
|
|
290
|
+
def format_human(graph: Dict) -> str:
|
|
291
|
+
adr = graph["adr"]
|
|
292
|
+
lines = [
|
|
293
|
+
f"{adr['adr_id']} {adr['title']}".rstrip(),
|
|
294
|
+
f"Status: {adr['status']} | {adr['path']}",
|
|
295
|
+
"",
|
|
296
|
+
"Outbound (this ADR references):",
|
|
297
|
+
]
|
|
298
|
+
|
|
299
|
+
if graph["outbound"]:
|
|
300
|
+
for e in graph["outbound"]:
|
|
301
|
+
label = f" -> {e['adr_id']} [{e['kind']}]"
|
|
302
|
+
if e["exists"]:
|
|
303
|
+
title = f" {e['title']}" if e["title"] else ""
|
|
304
|
+
label += f"{title} ({e['status']})"
|
|
305
|
+
else:
|
|
306
|
+
label += " ** DANGLING: target not found **"
|
|
307
|
+
lines.append(label)
|
|
308
|
+
else:
|
|
309
|
+
lines.append(" (none)")
|
|
310
|
+
|
|
311
|
+
lines.append("")
|
|
312
|
+
lines.append("Inbound (other ADRs referencing this one):")
|
|
313
|
+
if graph["inbound"]:
|
|
314
|
+
for e in graph["inbound"]:
|
|
315
|
+
title = f" {e['title']}" if e["title"] else ""
|
|
316
|
+
lines.append(f" <- {e['adr_id']} [{e['kind']}]{title} ({e['status']})")
|
|
317
|
+
else:
|
|
318
|
+
lines.append(" (none)")
|
|
319
|
+
|
|
320
|
+
if graph["dangling"]:
|
|
321
|
+
lines.append("")
|
|
322
|
+
lines.append(
|
|
323
|
+
"WARNING: dangling references (no such ADR in the set): "
|
|
324
|
+
+ ", ".join(graph["dangling"])
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
return "\n".join(lines)
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
# ---------------------------------------------------------------------------
|
|
331
|
+
# CLI entry point
|
|
332
|
+
# ---------------------------------------------------------------------------
|
|
333
|
+
|
|
334
|
+
def _ensure_utf8_stdout() -> None:
|
|
335
|
+
"""Force stdout/stderr to UTF-8 on Windows consoles defaulting to cp1252."""
|
|
336
|
+
import io
|
|
337
|
+
if hasattr(sys.stdout, "reconfigure"):
|
|
338
|
+
try:
|
|
339
|
+
sys.stdout.reconfigure(encoding="utf-8")
|
|
340
|
+
sys.stderr.reconfigure(encoding="utf-8")
|
|
341
|
+
except (AttributeError, io.UnsupportedOperation):
|
|
342
|
+
pass
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
def main() -> None:
|
|
346
|
+
_ensure_utf8_stdout()
|
|
347
|
+
|
|
348
|
+
parser = argparse.ArgumentParser(
|
|
349
|
+
description="Show the dependency graph (inbound + outbound edges) for one ADR.",
|
|
350
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
351
|
+
epilog=__doc__,
|
|
352
|
+
)
|
|
353
|
+
parser.add_argument(
|
|
354
|
+
"adr_id",
|
|
355
|
+
metavar="ADR-NNN",
|
|
356
|
+
help="ADR identifier (ADR-007, adr-7, or just 7)",
|
|
357
|
+
)
|
|
358
|
+
parser.add_argument(
|
|
359
|
+
"--adr-dir",
|
|
360
|
+
dest="adr_dir",
|
|
361
|
+
default="docs/adr",
|
|
362
|
+
help="Directory containing ADR-*.md files (default: docs/adr)",
|
|
363
|
+
)
|
|
364
|
+
parser.add_argument(
|
|
365
|
+
"--format",
|
|
366
|
+
choices=["human", "json"],
|
|
367
|
+
default="human",
|
|
368
|
+
help="Output format (default: human)",
|
|
369
|
+
)
|
|
370
|
+
|
|
371
|
+
args = parser.parse_args()
|
|
372
|
+
|
|
373
|
+
target_id = normalize_adr_id(args.adr_id)
|
|
374
|
+
if target_id is None:
|
|
375
|
+
print(f"adr-related: invalid ADR id: {args.adr_id}", file=sys.stderr)
|
|
376
|
+
sys.exit(2)
|
|
377
|
+
|
|
378
|
+
adr_dir = Path(args.adr_dir)
|
|
379
|
+
if not adr_dir.is_dir():
|
|
380
|
+
print(f"adr-related: directory not found: {adr_dir}", file=sys.stderr)
|
|
381
|
+
sys.exit(2)
|
|
382
|
+
|
|
383
|
+
records = load_adr_set(adr_dir)
|
|
384
|
+
try:
|
|
385
|
+
graph = build_graph(target_id, records)
|
|
386
|
+
except KeyError:
|
|
387
|
+
print(
|
|
388
|
+
f"adr-related: {target_id} not found in {adr_dir} "
|
|
389
|
+
f"({len(records)} ADRs scanned)",
|
|
390
|
+
file=sys.stderr,
|
|
391
|
+
)
|
|
392
|
+
sys.exit(2)
|
|
393
|
+
|
|
394
|
+
if args.format == "json":
|
|
395
|
+
print(json.dumps(graph, indent=2))
|
|
396
|
+
else:
|
|
397
|
+
print(format_human(graph))
|
|
398
|
+
|
|
399
|
+
|
|
400
|
+
if __name__ == "__main__":
|
|
401
|
+
main()
|
package/bin/adr-renumber
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""adr-renumber: safely renumber one ADR and update all cross-references.
|
|
3
|
+
|
|
4
|
+
Built for the merge-collision workflow: two parallel branches both claim
|
|
5
|
+
ADR-043, CI fails on the duplicate-number check in adr-lint, and one of the
|
|
6
|
+
two files must move to a free number. This tool renames the file, rewrites
|
|
7
|
+
the heading, and updates every whole-token reference to the old id across
|
|
8
|
+
all ADRs in the directory: Related Decisions entries, "Superseded by" and
|
|
9
|
+
"Amended by" status strings, Status History mentions, and plain ADR-NNN
|
|
10
|
+
references.
|
|
11
|
+
|
|
12
|
+
Safety properties:
|
|
13
|
+
- Dry-run by default: prints the full plan (file rename plus every rewrite
|
|
14
|
+
with file:line) and changes nothing. --apply executes the plan.
|
|
15
|
+
- Whole-token matching only: renumbering ADR-043 never touches ADR-0430.
|
|
16
|
+
- Refuses (exit 2) when the target number is already taken or the source
|
|
17
|
+
does not exist.
|
|
18
|
+
- All regexes are linear: no nested or lazy quantifiers (see the
|
|
19
|
+
0.19.1/0.19.2 ReDoS history in CHANGELOG.md).
|
|
20
|
+
|
|
21
|
+
Exit codes:
|
|
22
|
+
0 success (plan printed, or --apply completed)
|
|
23
|
+
2 input error (source missing, target taken, ambiguous source, bad id)
|
|
24
|
+
|
|
25
|
+
Usage:
|
|
26
|
+
adr-renumber ADR-043 # dry-run, target = next free number
|
|
27
|
+
adr-renumber ADR-043 --to ADR-051 # dry-run with explicit target
|
|
28
|
+
adr-renumber ADR-043 --to ADR-051 --apply # execute
|
|
29
|
+
adr-renumber docs/adr/ADR-043-foo.md --to ADR-051 # disambiguate duplicates
|
|
30
|
+
adr-renumber ADR-043 --adr-dir docs/decisions
|
|
31
|
+
|
|
32
|
+
Deterministic, stdlib-only, Python 3.10+.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
from __future__ import annotations
|
|
36
|
+
|
|
37
|
+
import argparse
|
|
38
|
+
import re
|
|
39
|
+
import sys
|
|
40
|
+
from pathlib import Path
|
|
41
|
+
from typing import Dict, List, Optional, Tuple
|
|
42
|
+
|
|
43
|
+
ADR_FILENAME_RE = re.compile(r"(?i)^ADR-(\d{1,4})-")
|
|
44
|
+
ADR_ID_RE = re.compile(r"(?i)^ADR-(\d{1,4})$")
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class RenumberError(Exception):
|
|
48
|
+
"""Raised on input errors; maps to exit code 2."""
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def parse_adr_id(raw: str) -> int:
|
|
52
|
+
"""Return the integer number of an ADR-NNN id, or raise RenumberError."""
|
|
53
|
+
m = ADR_ID_RE.match(raw.strip())
|
|
54
|
+
if not m:
|
|
55
|
+
raise RenumberError(f"{raw!r} does not match ADR-NNN (e.g. ADR-043)")
|
|
56
|
+
return int(m.group(1))
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def discover_adrs(adr_dir: Path) -> List[Path]:
|
|
60
|
+
"""Return sorted ADR markdown files in adr_dir (non-recursive)."""
|
|
61
|
+
if not adr_dir.is_dir():
|
|
62
|
+
raise RenumberError(f"ADR directory not found: {adr_dir}")
|
|
63
|
+
return sorted(
|
|
64
|
+
(p for p in adr_dir.glob("*.md") if ADR_FILENAME_RE.match(p.name)),
|
|
65
|
+
key=lambda p: p.name.lower(),
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def numbers_in_use(files: List[Path]) -> Dict[int, List[Path]]:
|
|
70
|
+
"""Map ADR number -> list of files carrying that number."""
|
|
71
|
+
grouped: Dict[int, List[Path]] = {}
|
|
72
|
+
for fp in files:
|
|
73
|
+
m = ADR_FILENAME_RE.match(fp.name)
|
|
74
|
+
if m:
|
|
75
|
+
grouped.setdefault(int(m.group(1)), []).append(fp)
|
|
76
|
+
return grouped
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def next_free_number(in_use: Dict[int, List[Path]]) -> int:
|
|
80
|
+
"""Return max(used) + 1. Gaps are not reused: a gap usually means a
|
|
81
|
+
retired or reserved number, and reusing it would resurrect stale
|
|
82
|
+
references."""
|
|
83
|
+
return (max(in_use) + 1) if in_use else 1
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def token_pattern(num: int) -> "re.Pattern[str]":
|
|
87
|
+
"""Whole-token pattern for every common spelling of an ADR id.
|
|
88
|
+
|
|
89
|
+
Matches ADR-43, ADR-043, ADR-0043 (whichever spellings differ), but
|
|
90
|
+
never ADR-0430: a digit may not follow the number. \\b before 'ADR'
|
|
91
|
+
rejects mid-word hits. Pure alternation of literals: linear time.
|
|
92
|
+
"""
|
|
93
|
+
spellings = sorted({str(num), f"{num:03d}", f"{num:04d}"}, key=len, reverse=True)
|
|
94
|
+
alt = "|".join(spellings)
|
|
95
|
+
return re.compile(rf"\bADR-(?:{alt})(?!\d)")
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def renamed_filename(name: str, new_num: int) -> str:
|
|
99
|
+
"""Replace the leading ADR-NNN- of a filename with the new number."""
|
|
100
|
+
m = ADR_FILENAME_RE.match(name)
|
|
101
|
+
if not m:
|
|
102
|
+
raise RenumberError(f"{name!r} is not an ADR filename (ADR-NNN-...)")
|
|
103
|
+
return f"ADR-{new_num:03d}-" + name[m.end():]
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def find_source(source_arg: str, adr_dir: Path, files: List[Path]) -> Tuple[Path, int]:
|
|
107
|
+
"""Resolve the source argument (ADR-NNN id or file path) to one file."""
|
|
108
|
+
candidate = Path(source_arg)
|
|
109
|
+
if candidate.suffix.lower() == ".md":
|
|
110
|
+
if not candidate.is_file():
|
|
111
|
+
candidate = adr_dir / candidate.name
|
|
112
|
+
if not candidate.is_file():
|
|
113
|
+
raise RenumberError(f"source file not found: {source_arg}")
|
|
114
|
+
m = ADR_FILENAME_RE.match(candidate.name)
|
|
115
|
+
if not m:
|
|
116
|
+
raise RenumberError(
|
|
117
|
+
f"{candidate.name!r} is not an ADR filename (ADR-NNN-...)"
|
|
118
|
+
)
|
|
119
|
+
return candidate, int(m.group(1))
|
|
120
|
+
|
|
121
|
+
num = parse_adr_id(source_arg)
|
|
122
|
+
matches = [
|
|
123
|
+
fp for fp in files
|
|
124
|
+
if (m := ADR_FILENAME_RE.match(fp.name)) and int(m.group(1)) == num
|
|
125
|
+
]
|
|
126
|
+
if not matches:
|
|
127
|
+
raise RenumberError(f"no ADR with number {num:03d} found in {adr_dir}")
|
|
128
|
+
if len(matches) > 1:
|
|
129
|
+
names = ", ".join(fp.name for fp in matches)
|
|
130
|
+
raise RenumberError(
|
|
131
|
+
f"ADR-{num:03d} is ambiguous ({names}); "
|
|
132
|
+
f"pass the file path of the one to renumber"
|
|
133
|
+
)
|
|
134
|
+
return matches[0], num
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def build_plan(
|
|
138
|
+
files: List[Path], source: Path, old_num: int, new_num: int
|
|
139
|
+
) -> List[Tuple[Path, int, str, str]]:
|
|
140
|
+
"""Return rewrite entries: (file, 1-based line, old line, new line)."""
|
|
141
|
+
pat = token_pattern(old_num)
|
|
142
|
+
new_id = f"ADR-{new_num:03d}"
|
|
143
|
+
plan: List[Tuple[Path, int, str, str]] = []
|
|
144
|
+
for fp in files:
|
|
145
|
+
text = fp.read_text(encoding="utf-8", errors="replace")
|
|
146
|
+
for lineno, line in enumerate(text.splitlines(), start=1):
|
|
147
|
+
new_line, n = pat.subn(new_id, line)
|
|
148
|
+
if n:
|
|
149
|
+
plan.append((fp, lineno, line, new_line))
|
|
150
|
+
return plan
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def apply_plan(
|
|
154
|
+
files: List[Path], source: Path, old_num: int, new_num: int
|
|
155
|
+
) -> Path:
|
|
156
|
+
"""Rewrite references in every file, then rename the source. Returns the
|
|
157
|
+
new source path."""
|
|
158
|
+
pat = token_pattern(old_num)
|
|
159
|
+
new_id = f"ADR-{new_num:03d}"
|
|
160
|
+
for fp in files:
|
|
161
|
+
text = fp.read_text(encoding="utf-8")
|
|
162
|
+
new_text, n = pat.subn(new_id, text)
|
|
163
|
+
if n:
|
|
164
|
+
fp.write_text(new_text, encoding="utf-8")
|
|
165
|
+
new_path = source.with_name(renamed_filename(source.name, new_num))
|
|
166
|
+
source.rename(new_path)
|
|
167
|
+
return new_path
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def main(argv: Optional[List[str]] = None) -> int:
|
|
171
|
+
parser = argparse.ArgumentParser(
|
|
172
|
+
prog="adr-renumber",
|
|
173
|
+
description=(
|
|
174
|
+
"Renumber one ADR and update all cross-references. "
|
|
175
|
+
"Dry-run by default; pass --apply to execute."
|
|
176
|
+
),
|
|
177
|
+
)
|
|
178
|
+
parser.add_argument(
|
|
179
|
+
"source",
|
|
180
|
+
help="ADR id (ADR-043) or file path of the ADR to renumber",
|
|
181
|
+
)
|
|
182
|
+
parser.add_argument(
|
|
183
|
+
"--to", metavar="ADR-NNN", default=None,
|
|
184
|
+
help="Target id (default: next free number, max in use + 1)",
|
|
185
|
+
)
|
|
186
|
+
parser.add_argument(
|
|
187
|
+
"--adr-dir", metavar="DIR", default="docs/adr",
|
|
188
|
+
help="ADR directory (default: docs/adr)",
|
|
189
|
+
)
|
|
190
|
+
parser.add_argument(
|
|
191
|
+
"--apply", action="store_true",
|
|
192
|
+
help="Execute the plan (default is dry-run)",
|
|
193
|
+
)
|
|
194
|
+
parser.add_argument(
|
|
195
|
+
"--version", action="version", version="adr-renumber 0.1.0",
|
|
196
|
+
)
|
|
197
|
+
args = parser.parse_args(argv)
|
|
198
|
+
|
|
199
|
+
try:
|
|
200
|
+
adr_dir = Path(args.adr_dir)
|
|
201
|
+
files = discover_adrs(adr_dir)
|
|
202
|
+
source, old_num = find_source(args.source, adr_dir, files)
|
|
203
|
+
in_use = numbers_in_use(files)
|
|
204
|
+
|
|
205
|
+
if args.to is not None:
|
|
206
|
+
new_num = parse_adr_id(args.to)
|
|
207
|
+
else:
|
|
208
|
+
new_num = next_free_number(in_use)
|
|
209
|
+
|
|
210
|
+
if new_num == old_num:
|
|
211
|
+
raise RenumberError(
|
|
212
|
+
f"target ADR-{new_num:03d} equals the source number"
|
|
213
|
+
)
|
|
214
|
+
if new_num in in_use:
|
|
215
|
+
taken_by = ", ".join(fp.name for fp in in_use[new_num])
|
|
216
|
+
raise RenumberError(
|
|
217
|
+
f"target ADR-{new_num:03d} is already taken by {taken_by}"
|
|
218
|
+
)
|
|
219
|
+
except RenumberError as e:
|
|
220
|
+
print(f"adr-renumber: {e}", file=sys.stderr)
|
|
221
|
+
return 2
|
|
222
|
+
|
|
223
|
+
old_id = f"ADR-{old_num:03d}"
|
|
224
|
+
new_id = f"ADR-{new_num:03d}"
|
|
225
|
+
new_name = renamed_filename(source.name, new_num)
|
|
226
|
+
|
|
227
|
+
print(f"Plan: renumber {old_id} -> {new_id}")
|
|
228
|
+
print(f" rename: {source} -> {source.with_name(new_name)}")
|
|
229
|
+
if len(in_use.get(old_num, [])) > 1:
|
|
230
|
+
others = ", ".join(
|
|
231
|
+
fp.name for fp in in_use[old_num] if fp != source
|
|
232
|
+
)
|
|
233
|
+
print(
|
|
234
|
+
f" warning: {old_id} is duplicated (also: {others}); "
|
|
235
|
+
f"rewritten references may belong to either file. Review the plan."
|
|
236
|
+
)
|
|
237
|
+
|
|
238
|
+
plan = build_plan(files, source, old_num, new_num)
|
|
239
|
+
for fp, lineno, old_line, new_line in plan:
|
|
240
|
+
print(f" {fp}:{lineno}: {old_line.strip()}")
|
|
241
|
+
print(f" -> {new_line.strip()}")
|
|
242
|
+
print(f" {len(plan)} line(s) to rewrite across {len(files)} ADR file(s).")
|
|
243
|
+
|
|
244
|
+
if not args.apply:
|
|
245
|
+
print("Dry run: no changes made. Re-run with --apply to execute.")
|
|
246
|
+
return 0
|
|
247
|
+
|
|
248
|
+
new_path = apply_plan(files, source, old_num, new_num)
|
|
249
|
+
print(f"Applied: {len(plan)} line(s) rewritten; renamed to {new_path}")
|
|
250
|
+
return 0
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
if __name__ == "__main__":
|
|
254
|
+
sys.exit(main())
|