@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,674 @@
|
|
|
1
|
+
"""adr_quality_core: the four-gate ADR quality scorer, separated from its CLI.
|
|
2
|
+
|
|
3
|
+
`bin/adr-quality` was both the scorer and the command, and that made the scorer
|
|
4
|
+
unreachable. Readiness computed its own "quality" from three booleans -- is
|
|
5
|
+
there decision text, is there a verified_in, are the open questions closed --
|
|
6
|
+
while the real weighted scorer sat behind a command line that only
|
|
7
|
+
`accept --auto` ever invoked. So a vague ADR and a sharp one were queued for
|
|
8
|
+
grilling identically, and the evaluator that could have told them apart was
|
|
9
|
+
never asked.
|
|
10
|
+
|
|
11
|
+
Moving the scoring here makes it importable, which is what puts it on a shipped
|
|
12
|
+
path: readiness reads it in-process, the guardian queue ranks on it, and
|
|
13
|
+
`bin/adr-quality` becomes the rendering shell it always should have been.
|
|
14
|
+
Nothing about the scores changed in the move.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import importlib.machinery
|
|
20
|
+
import importlib.util
|
|
21
|
+
import json
|
|
22
|
+
import re
|
|
23
|
+
import sys
|
|
24
|
+
from dataclasses import dataclass
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Dict, List, Optional
|
|
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
|
+
_load_sibling("adr_format")
|
|
54
|
+
|
|
55
|
+
from adr_format import detect_profile, required_headings, section_text
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
REQUIRED_SECTIONS = [
|
|
59
|
+
"## Status",
|
|
60
|
+
"## Context",
|
|
61
|
+
"## Decision",
|
|
62
|
+
"## Alternatives Considered",
|
|
63
|
+
"## Consequences",
|
|
64
|
+
"## Related Decisions",
|
|
65
|
+
"## References",
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
VALID_STATUSES = {
|
|
69
|
+
"proposed", "accepted", "deprecated", "superseded", "amended",
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
ADR_ID_RE = re.compile(r"(?i)^ADR-(\d{1,4})-")
|
|
73
|
+
ADR_REF_RE = re.compile(r"\bADR-(\d{3})\b", re.IGNORECASE)
|
|
74
|
+
METRICS_RE = re.compile(r"\d+\s*(ms|MB|GB|KB|%|req|s|hours?)\b")
|
|
75
|
+
FILE_LINE_RE = re.compile(r"[\w./]+:\d+")
|
|
76
|
+
EXTERNAL_LINK_RE = re.compile(r"https?://")
|
|
77
|
+
# Unified vague-words set; identical to bin/adr-lint's check_quality_gate().
|
|
78
|
+
VAGUE_WORDS_RE = re.compile(
|
|
79
|
+
r"\b(appropriate|somehow|maybe|possibly|might|could|"
|
|
80
|
+
r"should\s+consider|might\s+consider)\b",
|
|
81
|
+
re.IGNORECASE,
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
# Precompiled section-heading patterns: one regex per required section, used
|
|
85
|
+
# for both presence checks (gate_completeness) and slicing (_section_text).
|
|
86
|
+
_SECTION_PRESENCE_RE: Dict[str, re.Pattern] = {
|
|
87
|
+
section: re.compile(r"^" + re.escape(section) + r"\b", re.MULTILINE)
|
|
88
|
+
for section in REQUIRED_SECTIONS
|
|
89
|
+
}
|
|
90
|
+
_SECTION_BODY_RE: Dict[str, re.Pattern] = {
|
|
91
|
+
section: re.compile(
|
|
92
|
+
r"^" + re.escape(section) + r"\s*$\n(.*?)(?=\n##\s+|\Z)",
|
|
93
|
+
re.MULTILINE | re.DOTALL,
|
|
94
|
+
)
|
|
95
|
+
for section in REQUIRED_SECTIONS
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
# Acronym scanning (gate_clarity).
|
|
99
|
+
_ACRO_RE = re.compile(r"\b([A-Z]{2,})\b")
|
|
100
|
+
_ACRO_DEFINED_RE = re.compile(
|
|
101
|
+
r"\b([A-Z]{2,})\b\s*(?:\(|stands\s+for|means\b|\:)"
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
# ---------------------------------------------------------------------------
|
|
106
|
+
# Structured quality issues
|
|
107
|
+
# ---------------------------------------------------------------------------
|
|
108
|
+
|
|
109
|
+
ISSUE_MESSAGES: Dict[str, str] = {
|
|
110
|
+
"MISSING_SECTION": "Required section missing: {detail}",
|
|
111
|
+
"DECISION_TOO_SHORT":
|
|
112
|
+
"Decision section too short ({detail} chars, minimum 100)",
|
|
113
|
+
"TOO_FEW_ALTERNATIVES":
|
|
114
|
+
"Too few alternatives considered ({detail} found, minimum 2)",
|
|
115
|
+
"CONSEQUENCES_EMPTY": "Consequences section is empty",
|
|
116
|
+
"NO_REFERENCES": "References section is empty or contains only 'None'",
|
|
117
|
+
"NO_MEASUREMENTS":
|
|
118
|
+
"No quantitative measurements found (e.g., '50 ms', '10 MB', '30%')",
|
|
119
|
+
"NO_EXTERNAL_LINK":
|
|
120
|
+
"No external links found in the document; add https:// references",
|
|
121
|
+
"NO_FILE_LINE_REF":
|
|
122
|
+
"No file:line references found (e.g., 'src/main.py:42')",
|
|
123
|
+
"VAGUE_LANGUAGE": "Decision section uses vague language: {detail}",
|
|
124
|
+
"NO_TITLE": "No ADR title heading found (expected '# ADR-NNN Title')",
|
|
125
|
+
"ACRONYM_UNEXPLAINED": "More than 3 undefined acronyms: {detail}",
|
|
126
|
+
"CONTEXT_TOO_SHORT":
|
|
127
|
+
"Context section too short ({detail} chars, minimum 50)",
|
|
128
|
+
"NO_RELATED_DECISIONS":
|
|
129
|
+
"Related Decisions is empty or 'None'; reference related ADRs "
|
|
130
|
+
"(or explain why there are none)",
|
|
131
|
+
"ORPHAN_RELATED_ID": "Referenced ADRs do not exist: {detail}",
|
|
132
|
+
"INVALID_STATUS":
|
|
133
|
+
"Status section has no valid status value "
|
|
134
|
+
"(expected one of: {detail})",
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
# Severity ordering for triage display (lower = more severe).
|
|
138
|
+
SEVERITY_ORDER: Dict[str, int] = {"high": 0, "medium": 1, "low": 2}
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
@dataclass
|
|
142
|
+
class QualityIssue:
|
|
143
|
+
"""Structured issue produced by a quality gate.
|
|
144
|
+
|
|
145
|
+
``code`` is a stable machine-readable identifier (see ISSUE_MESSAGES);
|
|
146
|
+
``detail`` is free-form context interpolated into the human message.
|
|
147
|
+
"""
|
|
148
|
+
|
|
149
|
+
code: str
|
|
150
|
+
detail: str = ""
|
|
151
|
+
severity: str = "medium" # "high" | "medium" | "low"
|
|
152
|
+
|
|
153
|
+
def message(self) -> str:
|
|
154
|
+
template = ISSUE_MESSAGES.get(self.code, self.code)
|
|
155
|
+
try:
|
|
156
|
+
return template.format(detail=self.detail)
|
|
157
|
+
except (KeyError, IndexError):
|
|
158
|
+
return template
|
|
159
|
+
|
|
160
|
+
def to_dict(self) -> Dict:
|
|
161
|
+
return {
|
|
162
|
+
"code": self.code,
|
|
163
|
+
"detail": self.detail,
|
|
164
|
+
"severity": self.severity,
|
|
165
|
+
"message": self.message(),
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def _section_text(content: str, heading: str) -> str:
|
|
170
|
+
"""Extract text of a markdown section (up to the next ## heading or EOF)."""
|
|
171
|
+
role = {
|
|
172
|
+
"## Status": "status",
|
|
173
|
+
"## Context": "context",
|
|
174
|
+
"## Decision": "decision",
|
|
175
|
+
"## Alternatives Considered": "alternatives",
|
|
176
|
+
"## Consequences": "consequences",
|
|
177
|
+
"## Related Decisions": "related",
|
|
178
|
+
"## References": "references",
|
|
179
|
+
}.get(heading)
|
|
180
|
+
if role:
|
|
181
|
+
return section_text(content, role)
|
|
182
|
+
pat = _SECTION_BODY_RE.get(heading)
|
|
183
|
+
if pat is None:
|
|
184
|
+
# Fallback for any heading not in REQUIRED_SECTIONS.
|
|
185
|
+
pat = re.compile(
|
|
186
|
+
r"^" + re.escape(heading) + r"\s*$\n(.*?)(?=\n##\s+|\Z)",
|
|
187
|
+
re.MULTILINE | re.DOTALL,
|
|
188
|
+
)
|
|
189
|
+
m = pat.search(content)
|
|
190
|
+
return m.group(1) if m else ""
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def gate_completeness(content: str) -> Dict:
|
|
194
|
+
"""Gate 1: Completeness (0.0-1.0).
|
|
195
|
+
|
|
196
|
+
Checks:
|
|
197
|
+
- All 7 required sections present (each missing: -1/7)
|
|
198
|
+
- ## Decision section > 100 chars (else: -0.1)
|
|
199
|
+
- ## Alternatives Considered contains >= 2 bullet/heading items (else: -0.15)
|
|
200
|
+
- ## Consequences section present and not empty (else: -0.1)
|
|
201
|
+
|
|
202
|
+
Returns: {score: float, issues: List[QualityIssue], checks: Dict[str, bool]}
|
|
203
|
+
"""
|
|
204
|
+
issues: List[QualityIssue] = []
|
|
205
|
+
checks: Dict[str, bool] = {}
|
|
206
|
+
|
|
207
|
+
# Check all required sections present
|
|
208
|
+
missing_sections = []
|
|
209
|
+
profile = detect_profile(content)
|
|
210
|
+
effective_sections = (
|
|
211
|
+
required_headings(profile)
|
|
212
|
+
if profile in {"madr", "nygard", "canonical"}
|
|
213
|
+
else REQUIRED_SECTIONS
|
|
214
|
+
)
|
|
215
|
+
for section in effective_sections:
|
|
216
|
+
pattern = _SECTION_PRESENCE_RE.get(section) or re.compile(
|
|
217
|
+
r"^" + re.escape(section) + r"\b", re.MULTILINE
|
|
218
|
+
)
|
|
219
|
+
present = bool(pattern.search(content))
|
|
220
|
+
checks[f"section_{section.replace('## ', '').replace(' ', '_').lower()}"] = present
|
|
221
|
+
if not present:
|
|
222
|
+
missing_sections.append(section)
|
|
223
|
+
|
|
224
|
+
score = 1.0
|
|
225
|
+
n_missing = len(missing_sections)
|
|
226
|
+
if n_missing > 0:
|
|
227
|
+
score -= n_missing / 7.0
|
|
228
|
+
missing_names = ", ".join(s.replace("## ", "") for s in missing_sections)
|
|
229
|
+
issues.append(QualityIssue(
|
|
230
|
+
code="MISSING_SECTION",
|
|
231
|
+
detail=missing_names,
|
|
232
|
+
severity="high",
|
|
233
|
+
))
|
|
234
|
+
|
|
235
|
+
# Check Decision section length
|
|
236
|
+
decision_text = _section_text(content, "## Decision")
|
|
237
|
+
decision_len = len(decision_text.strip())
|
|
238
|
+
decision_long_enough = decision_len > 100
|
|
239
|
+
checks["decision_length_ok"] = decision_long_enough
|
|
240
|
+
if not decision_long_enough:
|
|
241
|
+
score -= 0.1
|
|
242
|
+
issues.append(QualityIssue(
|
|
243
|
+
code="DECISION_TOO_SHORT",
|
|
244
|
+
detail=str(decision_len),
|
|
245
|
+
severity="medium",
|
|
246
|
+
))
|
|
247
|
+
|
|
248
|
+
# Check Alternatives Considered has >= 2 items
|
|
249
|
+
alternatives_text = _section_text(content, "## Alternatives Considered")
|
|
250
|
+
list_items = re.findall(r"^[-*]\s+\S", alternatives_text, re.MULTILINE)
|
|
251
|
+
heading_items = re.findall(r"^###\s+\S", alternatives_text, re.MULTILINE)
|
|
252
|
+
total_alternatives = len(list_items) + len(heading_items)
|
|
253
|
+
enough_alternatives = total_alternatives >= 2
|
|
254
|
+
checks["alternatives_count_ok"] = enough_alternatives
|
|
255
|
+
if not enough_alternatives:
|
|
256
|
+
score -= 0.15
|
|
257
|
+
issues.append(QualityIssue(
|
|
258
|
+
code="TOO_FEW_ALTERNATIVES",
|
|
259
|
+
detail=str(total_alternatives),
|
|
260
|
+
severity="medium",
|
|
261
|
+
))
|
|
262
|
+
|
|
263
|
+
# Check Consequences present and not empty
|
|
264
|
+
consequences_text = _section_text(content, "## Consequences")
|
|
265
|
+
consequences_ok = bool(consequences_text.strip())
|
|
266
|
+
checks["consequences_not_empty"] = consequences_ok
|
|
267
|
+
if not consequences_ok:
|
|
268
|
+
score -= 0.1
|
|
269
|
+
issues.append(QualityIssue(
|
|
270
|
+
code="CONSEQUENCES_EMPTY",
|
|
271
|
+
severity="high",
|
|
272
|
+
))
|
|
273
|
+
|
|
274
|
+
score = max(0.0, min(1.0, score))
|
|
275
|
+
return {"score": score, "issues": issues, "checks": checks}
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def gate_evidence(content: str) -> Dict:
|
|
279
|
+
"""Gate 2: Evidence (0.0-1.0).
|
|
280
|
+
|
|
281
|
+
Checks:
|
|
282
|
+
- ## References section contains >= 1 non-'None' entry: +0.4
|
|
283
|
+
- Number/measurement present (regex r'\\d+\\s*(ms|MB|GB|KB|%|req|s|hours?)'): +0.3
|
|
284
|
+
- External link present (http:// or https://): +0.2
|
|
285
|
+
- file:line reference present: +0.1
|
|
286
|
+
|
|
287
|
+
Returns: {score: float, issues: List[str], checks: Dict[str, bool]}
|
|
288
|
+
"""
|
|
289
|
+
issues: List[QualityIssue] = []
|
|
290
|
+
checks: Dict[str, bool] = {}
|
|
291
|
+
|
|
292
|
+
# Check References section has at least 1 non-None entry
|
|
293
|
+
refs_text = _section_text(content, "## References")
|
|
294
|
+
refs_lines = [
|
|
295
|
+
ln.strip() for ln in refs_text.splitlines()
|
|
296
|
+
if ln.strip() and ln.strip().lower() not in ("none.", "none", "-")
|
|
297
|
+
]
|
|
298
|
+
has_references = bool(refs_lines)
|
|
299
|
+
checks["references_present"] = has_references
|
|
300
|
+
score = 0.0
|
|
301
|
+
if has_references:
|
|
302
|
+
score += 0.4
|
|
303
|
+
else:
|
|
304
|
+
issues.append(QualityIssue(code="NO_REFERENCES", severity="high"))
|
|
305
|
+
|
|
306
|
+
# Check for metrics/measurements in the whole document
|
|
307
|
+
has_metrics = bool(METRICS_RE.search(content))
|
|
308
|
+
checks["metrics_present"] = has_metrics
|
|
309
|
+
if has_metrics:
|
|
310
|
+
score += 0.3
|
|
311
|
+
else:
|
|
312
|
+
issues.append(QualityIssue(code="NO_MEASUREMENTS", severity="low"))
|
|
313
|
+
|
|
314
|
+
# Check for external links
|
|
315
|
+
has_external_link = bool(EXTERNAL_LINK_RE.search(content))
|
|
316
|
+
checks["external_link_present"] = has_external_link
|
|
317
|
+
if has_external_link:
|
|
318
|
+
score += 0.2
|
|
319
|
+
else:
|
|
320
|
+
issues.append(QualityIssue(code="NO_EXTERNAL_LINK", severity="low"))
|
|
321
|
+
|
|
322
|
+
# Check for file:line references
|
|
323
|
+
has_file_line = bool(FILE_LINE_RE.search(content))
|
|
324
|
+
checks["file_line_reference_present"] = has_file_line
|
|
325
|
+
if has_file_line:
|
|
326
|
+
score += 0.1
|
|
327
|
+
else:
|
|
328
|
+
issues.append(QualityIssue(code="NO_FILE_LINE_REF", severity="low"))
|
|
329
|
+
|
|
330
|
+
score = max(0.0, min(1.0, score))
|
|
331
|
+
return {"score": score, "issues": issues, "checks": checks}
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
def gate_clarity(content: str) -> Dict:
|
|
335
|
+
"""Gate 3: Clarity (0.0-1.0).
|
|
336
|
+
|
|
337
|
+
Checks:
|
|
338
|
+
- ## Decision section has no vague language ('might', 'maybe', 'possibly',
|
|
339
|
+
'could', 'should consider'): vague_words check
|
|
340
|
+
- ADR has a title (# ADR-NNN title present): +0.3
|
|
341
|
+
- Acronyms defined: check if all-caps words (>=2 letters) appear at least once
|
|
342
|
+
with a definition pattern. If > 3 undefined acronyms: -0.2
|
|
343
|
+
- ## Context section > 50 chars: +0.2
|
|
344
|
+
|
|
345
|
+
Returns: {score: float, issues: List[str], checks: Dict[str, bool]}
|
|
346
|
+
"""
|
|
347
|
+
issues: List[QualityIssue] = []
|
|
348
|
+
checks: Dict[str, bool] = {}
|
|
349
|
+
|
|
350
|
+
score = 0.5 # base score
|
|
351
|
+
|
|
352
|
+
# Check Decision section for vague language
|
|
353
|
+
decision_text = _section_text(content, "## Decision")
|
|
354
|
+
has_vague = bool(VAGUE_WORDS_RE.search(decision_text))
|
|
355
|
+
checks["no_vague_language"] = not has_vague
|
|
356
|
+
if has_vague:
|
|
357
|
+
vague_found = VAGUE_WORDS_RE.findall(decision_text)
|
|
358
|
+
issues.append(QualityIssue(
|
|
359
|
+
code="VAGUE_LANGUAGE",
|
|
360
|
+
detail=", ".join(repr(w) for w in vague_found[:5]),
|
|
361
|
+
severity="medium",
|
|
362
|
+
))
|
|
363
|
+
score -= 0.15
|
|
364
|
+
|
|
365
|
+
# Check ADR has a title heading
|
|
366
|
+
has_title = bool(re.search(r"^#\s+ADR-\d+", content, re.MULTILINE | re.IGNORECASE))
|
|
367
|
+
checks["has_title"] = has_title
|
|
368
|
+
if has_title:
|
|
369
|
+
score += 0.3
|
|
370
|
+
else:
|
|
371
|
+
issues.append(QualityIssue(code="NO_TITLE", severity="high"))
|
|
372
|
+
|
|
373
|
+
# Check acronyms are defined (all-caps words >= 2 letters).
|
|
374
|
+
# Stopwords that are definitely not acronyms.
|
|
375
|
+
acro_stopwords = frozenset({
|
|
376
|
+
"OK", "TO", "BY", "AS", "IS", "ON", "OR", "AN", "AT", "IN", "OF",
|
|
377
|
+
"IF", "DO", "NO", "SO", "UP", "US", "WE", "MY", "IT",
|
|
378
|
+
"ADR", "ID", # ADR is always defined in the context of this tool
|
|
379
|
+
})
|
|
380
|
+
# Words followed by definition patterns: '(', 'stands for', 'means', ':'
|
|
381
|
+
defined_acros = {m.group(1) for m in _ACRO_DEFINED_RE.finditer(content)}
|
|
382
|
+
|
|
383
|
+
undefined_acros = set()
|
|
384
|
+
for m in _ACRO_RE.finditer(content):
|
|
385
|
+
acro = m.group(1)
|
|
386
|
+
if acro not in acro_stopwords and acro not in defined_acros:
|
|
387
|
+
undefined_acros.add(acro)
|
|
388
|
+
|
|
389
|
+
acros_ok = len(undefined_acros) <= 3
|
|
390
|
+
checks["acronyms_defined"] = acros_ok
|
|
391
|
+
if not acros_ok:
|
|
392
|
+
score -= 0.2
|
|
393
|
+
issues.append(QualityIssue(
|
|
394
|
+
code="ACRONYM_UNEXPLAINED",
|
|
395
|
+
detail=", ".join(sorted(undefined_acros)[:5]),
|
|
396
|
+
severity="low",
|
|
397
|
+
))
|
|
398
|
+
|
|
399
|
+
# Check Context section > 50 chars
|
|
400
|
+
context_text = _section_text(content, "## Context")
|
|
401
|
+
context_len = len(context_text.strip())
|
|
402
|
+
context_ok = context_len > 50
|
|
403
|
+
checks["context_sufficient"] = context_ok
|
|
404
|
+
if context_ok:
|
|
405
|
+
score += 0.2
|
|
406
|
+
else:
|
|
407
|
+
issues.append(QualityIssue(
|
|
408
|
+
code="CONTEXT_TOO_SHORT",
|
|
409
|
+
detail=str(context_len),
|
|
410
|
+
severity="medium",
|
|
411
|
+
))
|
|
412
|
+
|
|
413
|
+
score = max(0.0, min(1.0, score))
|
|
414
|
+
return {"score": score, "issues": issues, "checks": checks}
|
|
415
|
+
|
|
416
|
+
|
|
417
|
+
def gate_consistency(content: str, adr_dir: Optional[Path] = None) -> Dict:
|
|
418
|
+
"""Gate 4: Consistency (0.0-1.0).
|
|
419
|
+
|
|
420
|
+
Checks:
|
|
421
|
+
- ## Related Decisions section not empty (not just 'None.'): +0.4
|
|
422
|
+
- If adr_dir given: check if mentioned ADR-NNN numbers exist: +0.3
|
|
423
|
+
- ## Status section contains a valid status value: +0.3
|
|
424
|
+
|
|
425
|
+
Returns: {score: float, issues: List[str], checks: Dict[str, bool]}
|
|
426
|
+
"""
|
|
427
|
+
issues: List[QualityIssue] = []
|
|
428
|
+
checks: Dict[str, bool] = {}
|
|
429
|
+
|
|
430
|
+
score = 0.0
|
|
431
|
+
|
|
432
|
+
# Check Related Decisions not empty
|
|
433
|
+
related_text = _section_text(content, "## Related Decisions")
|
|
434
|
+
related_lines = [
|
|
435
|
+
ln.strip() for ln in related_text.splitlines()
|
|
436
|
+
if ln.strip() and ln.strip().lower() not in ("none.", "none", "-")
|
|
437
|
+
]
|
|
438
|
+
has_related = bool(related_lines)
|
|
439
|
+
checks["related_decisions_present"] = has_related
|
|
440
|
+
if has_related:
|
|
441
|
+
score += 0.4
|
|
442
|
+
else:
|
|
443
|
+
issues.append(QualityIssue(
|
|
444
|
+
code="NO_RELATED_DECISIONS",
|
|
445
|
+
severity="medium",
|
|
446
|
+
))
|
|
447
|
+
|
|
448
|
+
# Check if mentioned ADR references exist in adr_dir
|
|
449
|
+
mentioned_adrs = set(ADR_REF_RE.findall(content))
|
|
450
|
+
if adr_dir and adr_dir.is_dir() and mentioned_adrs:
|
|
451
|
+
existing_nums = set()
|
|
452
|
+
for f in adr_dir.glob("ADR-*.md"):
|
|
453
|
+
m = re.match(r"(?i)ADR-(\d+)-", f.name)
|
|
454
|
+
if m:
|
|
455
|
+
existing_nums.add(int(m.group(1)))
|
|
456
|
+
missing_refs = [
|
|
457
|
+
f"ADR-{num}" for num in sorted(mentioned_adrs)
|
|
458
|
+
if int(num) not in existing_nums
|
|
459
|
+
]
|
|
460
|
+
refs_valid = not missing_refs
|
|
461
|
+
checks["referenced_adrs_exist"] = refs_valid
|
|
462
|
+
if refs_valid:
|
|
463
|
+
score += 0.3
|
|
464
|
+
else:
|
|
465
|
+
issues.append(QualityIssue(
|
|
466
|
+
code="ORPHAN_RELATED_ID",
|
|
467
|
+
detail=", ".join(missing_refs),
|
|
468
|
+
severity="high",
|
|
469
|
+
))
|
|
470
|
+
elif mentioned_adrs:
|
|
471
|
+
# ADR references found but can't verify — give partial credit
|
|
472
|
+
checks["referenced_adrs_exist"] = True
|
|
473
|
+
score += 0.3
|
|
474
|
+
else:
|
|
475
|
+
checks["referenced_adrs_exist"] = False
|
|
476
|
+
# No ADR references mentioned — don't add to score if no related decisions
|
|
477
|
+
if has_related:
|
|
478
|
+
score += 0.3
|
|
479
|
+
|
|
480
|
+
# Check Status section for a valid status value
|
|
481
|
+
status_text = _section_text(content, "## Status")
|
|
482
|
+
status_match = re.search(r"\b([A-Za-z]+)\b", status_text)
|
|
483
|
+
has_valid_status = False
|
|
484
|
+
if status_match:
|
|
485
|
+
status_word = status_match.group(1).lower()
|
|
486
|
+
has_valid_status = status_word in VALID_STATUSES
|
|
487
|
+
checks["valid_status"] = has_valid_status
|
|
488
|
+
if has_valid_status:
|
|
489
|
+
score += 0.3
|
|
490
|
+
else:
|
|
491
|
+
issues.append(QualityIssue(
|
|
492
|
+
code="INVALID_STATUS",
|
|
493
|
+
detail=", ".join(sorted(VALID_STATUSES)),
|
|
494
|
+
severity="high",
|
|
495
|
+
))
|
|
496
|
+
|
|
497
|
+
score = max(0.0, min(1.0, score))
|
|
498
|
+
return {"score": score, "issues": issues, "checks": checks}
|
|
499
|
+
|
|
500
|
+
|
|
501
|
+
def _grade(overall: float) -> str:
|
|
502
|
+
if overall >= 0.85:
|
|
503
|
+
return "A"
|
|
504
|
+
if overall >= 0.70:
|
|
505
|
+
return "B"
|
|
506
|
+
if overall >= 0.55:
|
|
507
|
+
return "C"
|
|
508
|
+
return "D"
|
|
509
|
+
|
|
510
|
+
|
|
511
|
+
def _extract_adr_id(adr_path: Path) -> str:
|
|
512
|
+
m = ADR_ID_RE.match(adr_path.name)
|
|
513
|
+
if m:
|
|
514
|
+
return f"ADR-{int(m.group(1)):03d}"
|
|
515
|
+
return adr_path.stem
|
|
516
|
+
|
|
517
|
+
|
|
518
|
+
# Per-code recommendation strings. Driven by the structured issue code rather
|
|
519
|
+
# than human-text matching, so wording changes don't silently break behaviour.
|
|
520
|
+
_RECOMMENDATIONS_BY_CODE: Dict[str, str] = {
|
|
521
|
+
"MISSING_SECTION": "Add the missing required sections listed above",
|
|
522
|
+
"DECISION_TOO_SHORT":
|
|
523
|
+
"Expand ## Decision to > 100 characters explaining the rationale",
|
|
524
|
+
"TOO_FEW_ALTERNATIVES":
|
|
525
|
+
"Add at least 2 alternatives in ## Alternatives Considered "
|
|
526
|
+
"(including 'do nothing')",
|
|
527
|
+
"CONSEQUENCES_EMPTY":
|
|
528
|
+
"Fill in ## Consequences with benefits, trade-offs, and risks",
|
|
529
|
+
"NO_REFERENCES":
|
|
530
|
+
"Add at least one entry to ## References (issue, file, or external link)",
|
|
531
|
+
"NO_MEASUREMENTS":
|
|
532
|
+
"Add measurements to ## Consequences (e.g., '50 ms', '10 MB', '30%')",
|
|
533
|
+
"NO_EXTERNAL_LINK": "Add at least one https:// link in ## References",
|
|
534
|
+
"NO_FILE_LINE_REF":
|
|
535
|
+
"Add a file:line reference (e.g., 'src/main.py:42') in ## References",
|
|
536
|
+
"VAGUE_LANGUAGE":
|
|
537
|
+
"Replace vague language in ## Decision with a concrete, "
|
|
538
|
+
"declarative statement",
|
|
539
|
+
"NO_TITLE": "Add a title heading '# ADR-NNN Title' as the first line",
|
|
540
|
+
"ACRONYM_UNEXPLAINED":
|
|
541
|
+
"Define acronyms on first use, e.g., 'REST (Representational "
|
|
542
|
+
"State Transfer)'",
|
|
543
|
+
"CONTEXT_TOO_SHORT":
|
|
544
|
+
"Expand ## Context to > 50 chars; explain the problem and constraints",
|
|
545
|
+
"NO_RELATED_DECISIONS":
|
|
546
|
+
"Reference related ADRs in ## Related Decisions "
|
|
547
|
+
"(or state 'None' with explanation)",
|
|
548
|
+
"ORPHAN_RELATED_ID":
|
|
549
|
+
"Verify that referenced ADR numbers exist in the docs/adr/ directory",
|
|
550
|
+
"INVALID_STATUS":
|
|
551
|
+
"Set a valid status in ## Status: Proposed, Accepted, Deprecated, "
|
|
552
|
+
"Superseded, or Amended",
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
|
|
556
|
+
def _recommendations_from_issues(issues: List[QualityIssue]) -> List[str]:
|
|
557
|
+
"""Generate concrete action items from structured issue codes."""
|
|
558
|
+
recs: List[str] = []
|
|
559
|
+
for issue in issues:
|
|
560
|
+
rec = _RECOMMENDATIONS_BY_CODE.get(issue.code)
|
|
561
|
+
if rec is None:
|
|
562
|
+
recs.append(issue.message())
|
|
563
|
+
else:
|
|
564
|
+
recs.append(rec)
|
|
565
|
+
return recs
|
|
566
|
+
|
|
567
|
+
|
|
568
|
+
def score_adr_quality(content: str, adr_path: Path) -> Dict:
|
|
569
|
+
"""Calculate composite quality score.
|
|
570
|
+
|
|
571
|
+
Returns:
|
|
572
|
+
{
|
|
573
|
+
"overall": float, # weighted: completeness*0.4 + evidence*0.2 + clarity*0.2 + consistency*0.2
|
|
574
|
+
"gates": {
|
|
575
|
+
"completeness": {"score": float, "issues": [...], "checks": {...}},
|
|
576
|
+
"evidence": {"score": float, "issues": [...], "checks": {...}},
|
|
577
|
+
"clarity": {"score": float, "issues": [...], "checks": {...}},
|
|
578
|
+
"consistency": {"score": float, "issues": [...], "checks": {...}},
|
|
579
|
+
},
|
|
580
|
+
"issues": List[str], # all issues combined, sorted by severity
|
|
581
|
+
"recommendations": List[str], # concrete action items
|
|
582
|
+
"grade": str, # "A" (>=0.85), "B" (>=0.70), "C" (>=0.55), "D" (<0.55)
|
|
583
|
+
}
|
|
584
|
+
"""
|
|
585
|
+
adr_dir = adr_path.parent if adr_path.parent.is_dir() else None
|
|
586
|
+
|
|
587
|
+
comp = gate_completeness(content)
|
|
588
|
+
evid = gate_evidence(content)
|
|
589
|
+
clar = gate_clarity(content)
|
|
590
|
+
cons = gate_consistency(content, adr_dir)
|
|
591
|
+
|
|
592
|
+
overall = (
|
|
593
|
+
comp["score"] * 0.4
|
|
594
|
+
+ evid["score"] * 0.2
|
|
595
|
+
+ clar["score"] * 0.2
|
|
596
|
+
+ cons["score"] * 0.2
|
|
597
|
+
)
|
|
598
|
+
overall = max(0.0, min(1.0, round(overall, 4)))
|
|
599
|
+
|
|
600
|
+
# Single-pass triage: collect all QualityIssues across the four gates,
|
|
601
|
+
# then sort by severity (high -> medium -> low). The previous 12-way
|
|
602
|
+
# comprehension was O(4 * 3 * n) and re-evaluated _severity_label
|
|
603
|
+
# repeatedly; this is O(n log n) with a tiny constant.
|
|
604
|
+
all_issues: List[QualityIssue] = [
|
|
605
|
+
issue
|
|
606
|
+
for gate_result in (comp, evid, clar, cons)
|
|
607
|
+
for issue in gate_result["issues"]
|
|
608
|
+
]
|
|
609
|
+
all_issues.sort(key=lambda i: SEVERITY_ORDER.get(i.severity, 99))
|
|
610
|
+
|
|
611
|
+
return {
|
|
612
|
+
"overall": overall,
|
|
613
|
+
"grade": _grade(overall),
|
|
614
|
+
"gates": {
|
|
615
|
+
"completeness": comp,
|
|
616
|
+
"evidence": evid,
|
|
617
|
+
"clarity": clar,
|
|
618
|
+
"consistency": cons,
|
|
619
|
+
},
|
|
620
|
+
"issues": all_issues,
|
|
621
|
+
"recommendations": _recommendations_from_issues(all_issues),
|
|
622
|
+
}
|
|
623
|
+
|
|
624
|
+
|
|
625
|
+
# The threshold `bin/adr-quality` has always exited 1 below. Named here so the
|
|
626
|
+
# queue and the readiness report agree with the command rather than each
|
|
627
|
+
# carrying their own number.
|
|
628
|
+
QUALITY_THRESHOLD = 0.70
|
|
629
|
+
|
|
630
|
+
|
|
631
|
+
def score_path(path: Path) -> Optional[Dict]:
|
|
632
|
+
"""Score one ADR file. None when it cannot be read -- never raises.
|
|
633
|
+
|
|
634
|
+
Callers on a queue or a hook path must not fail because one record is
|
|
635
|
+
unreadable; adr-lint is what reports a malformed ADR.
|
|
636
|
+
"""
|
|
637
|
+
try:
|
|
638
|
+
content = path.read_text(encoding="utf-8", errors="replace")
|
|
639
|
+
except OSError:
|
|
640
|
+
return None
|
|
641
|
+
try:
|
|
642
|
+
return score_adr_quality(content, path)
|
|
643
|
+
except (ValueError, KeyError, re.error):
|
|
644
|
+
return None
|
|
645
|
+
|
|
646
|
+
|
|
647
|
+
def score_directory(adr_dir: Path, statuses: Optional[List[str]] = None) -> Dict[str, Dict]:
|
|
648
|
+
"""Score every ADR in a directory, keyed by ADR id.
|
|
649
|
+
|
|
650
|
+
`statuses`, when given, restricts the scan -- the guardian evaluates
|
|
651
|
+
Accepted records on its own cadence so quality decay stays visible instead
|
|
652
|
+
of frozen at the moment of acceptance.
|
|
653
|
+
"""
|
|
654
|
+
_load_sibling("adr_schema")
|
|
655
|
+
_load_sibling("adr_catalog")
|
|
656
|
+
from adr_catalog import adr_status, discover_adr_files
|
|
657
|
+
|
|
658
|
+
wanted = {status.casefold() for status in statuses} if statuses else None
|
|
659
|
+
scores: Dict[str, Dict] = {}
|
|
660
|
+
for path in discover_adr_files(adr_dir):
|
|
661
|
+
try:
|
|
662
|
+
content = path.read_text(encoding="utf-8", errors="replace")
|
|
663
|
+
except OSError:
|
|
664
|
+
continue
|
|
665
|
+
if wanted is not None:
|
|
666
|
+
status = (adr_status(content) or "").strip().casefold()
|
|
667
|
+
if status not in wanted:
|
|
668
|
+
continue
|
|
669
|
+
try:
|
|
670
|
+
result = score_adr_quality(content, path)
|
|
671
|
+
except (ValueError, KeyError, re.error):
|
|
672
|
+
continue
|
|
673
|
+
scores[_extract_adr_id(path)] = result
|
|
674
|
+
return scores
|