@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-retire
ADDED
|
@@ -0,0 +1,467 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""adr-retire: find Accepted ADRs that should be reviewed for retirement.
|
|
3
|
+
|
|
4
|
+
The command evaluates four independent signals:
|
|
5
|
+
|
|
6
|
+
1. No status change within the configured age threshold.
|
|
7
|
+
2. Explicit technology terms from the Decision section no longer appear in
|
|
8
|
+
project source files.
|
|
9
|
+
3. A "Superseded by ADR-NNN" target cannot be found.
|
|
10
|
+
4. An Enforcement block contains risky regex or path-glob patterns.
|
|
11
|
+
|
|
12
|
+
All processing is deterministic and stdlib-only.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import argparse
|
|
18
|
+
import importlib.machinery
|
|
19
|
+
import importlib.util
|
|
20
|
+
import json
|
|
21
|
+
import os
|
|
22
|
+
import re
|
|
23
|
+
import sys
|
|
24
|
+
from datetime import date
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Dict, Iterable, List, Optional, Set, Tuple
|
|
27
|
+
|
|
28
|
+
_BIN_DIR = Path(__file__).resolve().parent
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _load_sibling(name: str):
|
|
32
|
+
"""Import bin/<name>.py by explicit path, WITHOUT touching sys.path.
|
|
33
|
+
|
|
34
|
+
SEC-HIGH (TASK-62): `sys.path.insert(0, _BIN_DIR)` put this directory ahead
|
|
35
|
+
of the standard library for every import, so a module committed next to
|
|
36
|
+
this script executed as code -- and it re-added the very directory
|
|
37
|
+
CPython's -P / PYTHONSAFEPATH removes. Siblings are registered in
|
|
38
|
+
sys.modules under their bare name, so the plain `from adr_* import ...`
|
|
39
|
+
statements below (and the lazy ones inside functions) resolve from the
|
|
40
|
+
cache instead of the path. bin/adr-judge carries the full rationale.
|
|
41
|
+
"""
|
|
42
|
+
cached = sys.modules.get(name)
|
|
43
|
+
if cached is not None:
|
|
44
|
+
return cached
|
|
45
|
+
loader = importlib.machinery.SourceFileLoader(name, str(_BIN_DIR / f"{name}.py"))
|
|
46
|
+
spec = importlib.util.spec_from_loader(name, loader)
|
|
47
|
+
module = importlib.util.module_from_spec(spec)
|
|
48
|
+
sys.modules[name] = module
|
|
49
|
+
loader.exec_module(module)
|
|
50
|
+
return module
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
# Dependency order: adr_catalog imports adr_format and adr_schema.
|
|
54
|
+
_load_sibling("adr_format")
|
|
55
|
+
_load_sibling("adr_schema")
|
|
56
|
+
_load_sibling("adr_catalog")
|
|
57
|
+
|
|
58
|
+
from adr_catalog import ADR_FILENAME_RE
|
|
59
|
+
from adr_catalog import adr_status as extract_status
|
|
60
|
+
from adr_format import section_text
|
|
61
|
+
|
|
62
|
+
# Safety cap for repo-wide file scans (tech-removal signal).
|
|
63
|
+
MAX_FILES = 50_000
|
|
64
|
+
|
|
65
|
+
JSON_FENCE_RE = re.compile(r"```json\s*\n(.*?)\n```", re.IGNORECASE | re.DOTALL)
|
|
66
|
+
STATUS_HISTORY_START_RE = re.compile(r"^\s*status_history\s*:\s*$", re.IGNORECASE)
|
|
67
|
+
HISTORY_DATE_RE = re.compile(r"^\s*(?:-\s*)?date\s*:\s*[\"']?(\d{4}-\d{2}-\d{2})", re.IGNORECASE)
|
|
68
|
+
SOURCE_SUFFIXES = {
|
|
69
|
+
".c", ".cc", ".cpp", ".go", ".h", ".hpp", ".ino", ".java", ".js",
|
|
70
|
+
".json", ".py", ".rs", ".sh", ".ts", ".tsx", ".yaml", ".yml",
|
|
71
|
+
}
|
|
72
|
+
IGNORED_DIRS = {
|
|
73
|
+
".git", ".pytest_cache", ".venv", "__pycache__", "docs", "node_modules", "vendor"
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class RetireError(Exception):
|
|
78
|
+
"""Raised on configuration or input errors."""
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def load_adr_set(adr_dir: Path) -> List[Tuple[str, Path, str]]:
|
|
82
|
+
"""Return ADR id, path, and UTF-8 content for ADR markdown files."""
|
|
83
|
+
adrs = []
|
|
84
|
+
if not adr_dir.is_dir():
|
|
85
|
+
return adrs
|
|
86
|
+
for file in sorted(adr_dir.glob("*.md")):
|
|
87
|
+
match = ADR_FILENAME_RE.match(file.name)
|
|
88
|
+
if not match:
|
|
89
|
+
continue
|
|
90
|
+
adr_id = f"ADR-{int(match.group(1)):03d}"
|
|
91
|
+
try:
|
|
92
|
+
adrs.append((adr_id, file, file.read_text(encoding="utf-8")))
|
|
93
|
+
except OSError as exc:
|
|
94
|
+
print(f"[adr-retire] WARN: {file}: {exc}", file=sys.stderr)
|
|
95
|
+
return adrs
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def extract_section(text: str, heading: str) -> str:
|
|
99
|
+
"""Return section content until the next level-two heading."""
|
|
100
|
+
role = {
|
|
101
|
+
"Status": "status",
|
|
102
|
+
"Decision": "decision",
|
|
103
|
+
"Enforcement": "enforcement",
|
|
104
|
+
}.get(heading)
|
|
105
|
+
if role:
|
|
106
|
+
return section_text(text, role)
|
|
107
|
+
match = re.search(
|
|
108
|
+
rf"^##\s+{re.escape(heading)}\s*$\n+(.*?)(?=^##\s+|\Z)",
|
|
109
|
+
text,
|
|
110
|
+
re.IGNORECASE | re.MULTILINE | re.DOTALL,
|
|
111
|
+
)
|
|
112
|
+
return match.group(1) if match else ""
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _status_history_dates(content: str) -> List[date]:
|
|
116
|
+
dates = []
|
|
117
|
+
in_history = False
|
|
118
|
+
for line in content.splitlines():
|
|
119
|
+
stripped = line.strip()
|
|
120
|
+
if not in_history:
|
|
121
|
+
if STATUS_HISTORY_START_RE.match(line):
|
|
122
|
+
in_history = True
|
|
123
|
+
continue
|
|
124
|
+
if stripped.startswith("```") or stripped.startswith("## "):
|
|
125
|
+
break
|
|
126
|
+
match = HISTORY_DATE_RE.match(line)
|
|
127
|
+
if match:
|
|
128
|
+
try:
|
|
129
|
+
dates.append(date.fromisoformat(match.group(1)))
|
|
130
|
+
except ValueError:
|
|
131
|
+
pass
|
|
132
|
+
return dates
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def _status_line_date(content: str) -> Optional[date]:
|
|
136
|
+
status_section = extract_section(content, "Status")
|
|
137
|
+
match = re.search(r"\b(\d{4}-\d{2}-\d{2})\b", status_section)
|
|
138
|
+
if not match:
|
|
139
|
+
return None
|
|
140
|
+
try:
|
|
141
|
+
return date.fromisoformat(match.group(1))
|
|
142
|
+
except ValueError:
|
|
143
|
+
return None
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def detect_90day_staleness(
|
|
147
|
+
adr_id: str, content: str, config: Dict, as_of: Optional[date] = None
|
|
148
|
+
) -> float:
|
|
149
|
+
"""Return 1.0 when no known status update occurred within the threshold."""
|
|
150
|
+
del adr_id
|
|
151
|
+
threshold = int(config.get("retirement", {}).get("threshold_days", 90))
|
|
152
|
+
history_dates = _status_history_dates(content)
|
|
153
|
+
last_change = max(history_dates) if history_dates else _status_line_date(content)
|
|
154
|
+
if last_change is None:
|
|
155
|
+
return 0.0
|
|
156
|
+
age_days = ((as_of or date.today()) - last_change).days
|
|
157
|
+
return 1.0 if age_days >= threshold else 0.0
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def _technology_terms(content: str) -> List[str]:
|
|
161
|
+
"""Extract explicit backticked technology identifiers from Decision."""
|
|
162
|
+
decision = extract_section(content, "Decision")
|
|
163
|
+
ignored = {"true", "false", "none", "null", "accepted", "proposed"}
|
|
164
|
+
terms = set()
|
|
165
|
+
for raw in re.findall(r"`([^`\n]+)`", decision):
|
|
166
|
+
term = raw.strip()
|
|
167
|
+
if (
|
|
168
|
+
re.fullmatch(r"[A-Za-z][A-Za-z0-9_.+#-]{1,49}", term)
|
|
169
|
+
and term.lower() not in ignored
|
|
170
|
+
):
|
|
171
|
+
terms.add(term)
|
|
172
|
+
return sorted(terms, key=str.lower)
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
_WALK_CACHE: Dict[Tuple[str, frozenset], List[Path]] = {}
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def _walk_repo_files(repo_root: Path, extensions: set) -> List[Path]:
|
|
179
|
+
"""Walk repo without following symlinks, with a file-count safety cap.
|
|
180
|
+
|
|
181
|
+
Replaces rglob('*') which would follow symlinks and could fall into
|
|
182
|
+
infinite cycles or escape the repo root (SEC-LOW).
|
|
183
|
+
|
|
184
|
+
Memoized per (repo_root, extensions): scoring N ADRs used to trigger N
|
|
185
|
+
identical full-tree walks, which made runtime linear in ADR count.
|
|
186
|
+
"""
|
|
187
|
+
cache_key = (str(repo_root), frozenset(extensions))
|
|
188
|
+
cached = _WALK_CACHE.get(cache_key)
|
|
189
|
+
if cached is not None:
|
|
190
|
+
return cached
|
|
191
|
+
|
|
192
|
+
result: List[Path] = []
|
|
193
|
+
count = 0
|
|
194
|
+
skip_dirs = set(IGNORED_DIRS) | {"node_modules", ".tox"}
|
|
195
|
+
for dirpath, dirnames, filenames in os.walk(repo_root, followlinks=False):
|
|
196
|
+
# Prune ignored directories in-place so os.walk skips them.
|
|
197
|
+
dirnames[:] = [d for d in dirnames if d.lower() not in skip_dirs]
|
|
198
|
+
# Never descend into a nested checkout (git worktree, vendored clone):
|
|
199
|
+
# its files are not this project's source.
|
|
200
|
+
dirnames[:] = [
|
|
201
|
+
d for d in dirnames if not (Path(dirpath) / d / ".git").exists()
|
|
202
|
+
]
|
|
203
|
+
for fname in filenames:
|
|
204
|
+
if Path(fname).suffix.lower() in extensions:
|
|
205
|
+
result.append(Path(dirpath) / fname)
|
|
206
|
+
count += 1
|
|
207
|
+
if count >= MAX_FILES:
|
|
208
|
+
import warnings
|
|
209
|
+
warnings.warn(
|
|
210
|
+
f"[adr-retire] File scan capped at {MAX_FILES} files. "
|
|
211
|
+
f"Some files may be missed."
|
|
212
|
+
)
|
|
213
|
+
_WALK_CACHE[cache_key] = result
|
|
214
|
+
return result
|
|
215
|
+
_WALK_CACHE[cache_key] = result
|
|
216
|
+
return result
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _source_files(repo_root: Path) -> Iterable[Path]:
|
|
220
|
+
return _walk_repo_files(repo_root, SOURCE_SUFFIXES)
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def resolve_present_terms(repo_root: Path, terms: Iterable[str]) -> Set[str]:
|
|
224
|
+
"""Return the subset of lowercased `terms` that occur in any source file.
|
|
225
|
+
|
|
226
|
+
Single pass: each source file is read at most once regardless of how many
|
|
227
|
+
ADRs are being scored. Stops early once every term has been located.
|
|
228
|
+
"""
|
|
229
|
+
pending = {term.lower() for term in terms if term}
|
|
230
|
+
found: Set[str] = set()
|
|
231
|
+
if not pending:
|
|
232
|
+
return found
|
|
233
|
+
for source_file in _source_files(repo_root):
|
|
234
|
+
try:
|
|
235
|
+
source = source_file.read_text(encoding="utf-8", errors="ignore").lower()
|
|
236
|
+
except OSError:
|
|
237
|
+
continue
|
|
238
|
+
hits = {term for term in pending if term in source}
|
|
239
|
+
if hits:
|
|
240
|
+
found |= hits
|
|
241
|
+
pending -= hits
|
|
242
|
+
if not pending:
|
|
243
|
+
break
|
|
244
|
+
return found
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def detect_tech_removal(
|
|
248
|
+
adr_id: str,
|
|
249
|
+
content: str,
|
|
250
|
+
repo_root: Path,
|
|
251
|
+
present_terms: Optional[Set[str]] = None,
|
|
252
|
+
) -> float:
|
|
253
|
+
"""Return 1.0 only when explicit decision terms vanish from source.
|
|
254
|
+
|
|
255
|
+
`present_terms` is the precomputed set of lowercased terms known to exist
|
|
256
|
+
in the tree. When omitted the term set is resolved on demand, preserving
|
|
257
|
+
the original single-ADR behaviour for direct callers.
|
|
258
|
+
"""
|
|
259
|
+
del adr_id
|
|
260
|
+
terms = _technology_terms(content)
|
|
261
|
+
if not terms:
|
|
262
|
+
return 0.0
|
|
263
|
+
lowered = [term.lower() for term in terms]
|
|
264
|
+
if present_terms is None:
|
|
265
|
+
present_terms = resolve_present_terms(repo_root, lowered)
|
|
266
|
+
return 0.0 if any(term in present_terms for term in lowered) else 1.0
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def detect_supersession_broken(
|
|
270
|
+
adr_id: str, content: str, all_adr_ids: List[str]
|
|
271
|
+
) -> float:
|
|
272
|
+
"""Return 1.0 when an ADR references a missing superseding ADR."""
|
|
273
|
+
del adr_id
|
|
274
|
+
match = re.search(r"Superseded\s+by\s+(ADR-\d{1,4})", content, re.IGNORECASE)
|
|
275
|
+
if not match:
|
|
276
|
+
return 0.0
|
|
277
|
+
target_num = int(re.search(r"\d+", match.group(1)).group(0))
|
|
278
|
+
return 0.0 if f"ADR-{target_num:03d}" in all_adr_ids else 1.0
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def _enforcement_rules(content: str) -> Optional[List[Dict]]:
|
|
282
|
+
section = extract_section(content, "Enforcement")
|
|
283
|
+
if not section:
|
|
284
|
+
return []
|
|
285
|
+
match = JSON_FENCE_RE.search(section)
|
|
286
|
+
if not match:
|
|
287
|
+
return []
|
|
288
|
+
try:
|
|
289
|
+
enforcement = json.loads(match.group(1))
|
|
290
|
+
except json.JSONDecodeError:
|
|
291
|
+
return None
|
|
292
|
+
rules = []
|
|
293
|
+
for key in ("forbid_pattern", "forbid_import", "require_pattern"):
|
|
294
|
+
value = enforcement.get(key, [])
|
|
295
|
+
if isinstance(value, list):
|
|
296
|
+
rules.extend(rule for rule in value if isinstance(rule, dict))
|
|
297
|
+
return rules
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
def detect_policy_mismatch(adr_id: str, content: str, config: Dict) -> float:
|
|
301
|
+
"""Return the fraction of Enforcement rules containing risky patterns."""
|
|
302
|
+
del adr_id
|
|
303
|
+
if config.get("retirement", {}).get("check_policy_mismatch", True) is False:
|
|
304
|
+
return 0.0
|
|
305
|
+
rules = _enforcement_rules(content)
|
|
306
|
+
if rules is None:
|
|
307
|
+
return 1.0
|
|
308
|
+
if not rules:
|
|
309
|
+
return 0.0
|
|
310
|
+
risky = 0
|
|
311
|
+
for rule in rules:
|
|
312
|
+
pattern = str(rule.get("pattern", ""))
|
|
313
|
+
path_glob = str(rule.get("path_glob", ""))
|
|
314
|
+
unescaped_dot = re.search(r"(?<!\\)\.(?![*+?{])", pattern)
|
|
315
|
+
excessive_wildcard = re.search(r"(?<!\\)\.\*(?:.*(?<!\\)\.\*)?", pattern)
|
|
316
|
+
broad_glob = path_glob in {"*", "**", "**/*", "**/*.*"} or path_glob.startswith("**/")
|
|
317
|
+
if unescaped_dot or excessive_wildcard or broad_glob:
|
|
318
|
+
risky += 1
|
|
319
|
+
return round(risky / len(rules), 2)
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
def score_adr(
|
|
323
|
+
adr_id: str,
|
|
324
|
+
content: str,
|
|
325
|
+
all_adr_ids: List[str],
|
|
326
|
+
repo_root: Path,
|
|
327
|
+
config: Dict,
|
|
328
|
+
as_of: Optional[date] = None,
|
|
329
|
+
present_terms: Optional[Set[str]] = None,
|
|
330
|
+
) -> Dict:
|
|
331
|
+
"""Return four-signal score and recommendation for one ADR."""
|
|
332
|
+
status = extract_status(content)
|
|
333
|
+
signals = {
|
|
334
|
+
"staleness_90day": 0.0,
|
|
335
|
+
"tech_removal": 0.0,
|
|
336
|
+
"broken_supersession": 0.0,
|
|
337
|
+
"policy_mismatch": 0.0,
|
|
338
|
+
}
|
|
339
|
+
if status and config.get("retirement", {}).get("check_supersession", True):
|
|
340
|
+
signals["broken_supersession"] = detect_supersession_broken(
|
|
341
|
+
adr_id, content, all_adr_ids
|
|
342
|
+
)
|
|
343
|
+
if status and status.lower() == "accepted":
|
|
344
|
+
signals["staleness_90day"] = detect_90day_staleness(
|
|
345
|
+
adr_id, content, config, as_of
|
|
346
|
+
)
|
|
347
|
+
if config.get("retirement", {}).get("check_tech_removal", True):
|
|
348
|
+
signals["tech_removal"] = detect_tech_removal(
|
|
349
|
+
adr_id, content, repo_root, present_terms
|
|
350
|
+
)
|
|
351
|
+
signals["policy_mismatch"] = detect_policy_mismatch(adr_id, content, config)
|
|
352
|
+
score = round(sum(signals.values()) / 4.0, 2)
|
|
353
|
+
recommendation = "KEEP"
|
|
354
|
+
if score >= 0.8:
|
|
355
|
+
recommendation = "RETIRE"
|
|
356
|
+
elif score >= 0.6:
|
|
357
|
+
recommendation = "REVIEW"
|
|
358
|
+
elif score >= 0.4:
|
|
359
|
+
recommendation = "MONITOR"
|
|
360
|
+
return {
|
|
361
|
+
"adr_id": adr_id,
|
|
362
|
+
"status": status,
|
|
363
|
+
"retirement_score": score,
|
|
364
|
+
"signals": signals,
|
|
365
|
+
"recommendation": recommendation,
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def render_markdown(results: List[Dict]) -> str:
|
|
370
|
+
lines = ["# ADR Retirement Candidates", ""]
|
|
371
|
+
if not results:
|
|
372
|
+
return "\n".join(lines + ["No candidates met the reporting threshold.", ""])
|
|
373
|
+
for result in results:
|
|
374
|
+
lines.extend(
|
|
375
|
+
[
|
|
376
|
+
f"## {result['adr_id']} - {result['recommendation']}",
|
|
377
|
+
"",
|
|
378
|
+
f"Retirement score: **{result['retirement_score']:.2f}**",
|
|
379
|
+
"",
|
|
380
|
+
"| Signal | Score |",
|
|
381
|
+
"| --- | ---: |",
|
|
382
|
+
]
|
|
383
|
+
)
|
|
384
|
+
lines.extend(
|
|
385
|
+
f"| {signal} | {score:.2f} |"
|
|
386
|
+
for signal, score in result["signals"].items()
|
|
387
|
+
)
|
|
388
|
+
lines.append("")
|
|
389
|
+
return "\n".join(lines)
|
|
390
|
+
|
|
391
|
+
|
|
392
|
+
def render_text(results: List[Dict]) -> str:
|
|
393
|
+
if not results:
|
|
394
|
+
return "No ADR retirement candidates."
|
|
395
|
+
return "\n".join(
|
|
396
|
+
f"{result['adr_id']} {result['recommendation']} "
|
|
397
|
+
f"score={result['retirement_score']:.2f}"
|
|
398
|
+
for result in results
|
|
399
|
+
)
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
def main(argv: Optional[List[str]] = None) -> int:
|
|
403
|
+
parser = argparse.ArgumentParser(description="Detect ADR retirement candidates.")
|
|
404
|
+
parser.add_argument("adr_dir", nargs="?", default="docs/adr", help="ADR directory")
|
|
405
|
+
parser.add_argument(
|
|
406
|
+
"--format", choices=["json", "markdown", "text"], default="text",
|
|
407
|
+
help="Output format (default: text)",
|
|
408
|
+
)
|
|
409
|
+
parser.add_argument(
|
|
410
|
+
"--threshold", type=float, default=0.0,
|
|
411
|
+
help="Minimum retirement score to report (default: 0.0)",
|
|
412
|
+
)
|
|
413
|
+
parser.add_argument("--config", type=Path, default=None, help="Path to .adr-kit.json")
|
|
414
|
+
parser.add_argument("--repo-root", type=Path, default=None, help="Project source root")
|
|
415
|
+
args = parser.parse_args(argv)
|
|
416
|
+
|
|
417
|
+
adr_dir = Path(args.adr_dir).resolve()
|
|
418
|
+
repo_root = (args.repo_root or adr_dir.parent.parent).resolve()
|
|
419
|
+
if args.threshold < 0.0 or args.threshold > 1.0:
|
|
420
|
+
raise RetireError("--threshold must be in the range 0.0 to 1.0")
|
|
421
|
+
|
|
422
|
+
config = {}
|
|
423
|
+
config_candidates = [args.config] if args.config else [
|
|
424
|
+
adr_dir / ".adr-kit.json",
|
|
425
|
+
repo_root / ".adr-kit.json",
|
|
426
|
+
]
|
|
427
|
+
config_path = next((path for path in config_candidates if path and path.exists()), None)
|
|
428
|
+
if config_path:
|
|
429
|
+
try:
|
|
430
|
+
config = json.loads(config_path.read_text(encoding="utf-8"))
|
|
431
|
+
except json.JSONDecodeError as exc:
|
|
432
|
+
raise RetireError(f"Malformed config: {config_path}: {exc}") from exc
|
|
433
|
+
|
|
434
|
+
adrs = load_adr_set(adr_dir)
|
|
435
|
+
adr_ids = [adr_id for adr_id, _, _ in adrs]
|
|
436
|
+
|
|
437
|
+
# Resolve every ADR's technology terms in one pass over the tree, rather
|
|
438
|
+
# than re-walking and re-reading the repo once per ADR.
|
|
439
|
+
present_terms: Optional[Set[str]] = None
|
|
440
|
+
if config.get("retirement", {}).get("check_tech_removal", True):
|
|
441
|
+
all_terms: Set[str] = set()
|
|
442
|
+
for _, _, content in adrs:
|
|
443
|
+
all_terms.update(term.lower() for term in _technology_terms(content))
|
|
444
|
+
present_terms = resolve_present_terms(repo_root, all_terms)
|
|
445
|
+
|
|
446
|
+
results = [
|
|
447
|
+
score_adr(adr_id, content, adr_ids, repo_root, config, present_terms=present_terms)
|
|
448
|
+
for adr_id, _, content in adrs
|
|
449
|
+
]
|
|
450
|
+
results = [result for result in results if result["retirement_score"] >= args.threshold]
|
|
451
|
+
results.sort(key=lambda result: (-result["retirement_score"], result["adr_id"]))
|
|
452
|
+
|
|
453
|
+
if args.format == "json":
|
|
454
|
+
print(json.dumps(results, indent=2))
|
|
455
|
+
elif args.format == "markdown":
|
|
456
|
+
print(render_markdown(results))
|
|
457
|
+
else:
|
|
458
|
+
print(render_text(results))
|
|
459
|
+
return 0
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
if __name__ == "__main__":
|
|
463
|
+
try:
|
|
464
|
+
sys.exit(main())
|
|
465
|
+
except RetireError as exc:
|
|
466
|
+
print(f"[adr-retire] ERROR: {exc}", file=sys.stderr)
|
|
467
|
+
sys.exit(2)
|