@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,342 @@
|
|
|
1
|
+
"""Existing ADR/index/lint/staleness health checks used by adr-doctor."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import re
|
|
9
|
+
import subprocess
|
|
10
|
+
import sys
|
|
11
|
+
from datetime import date, datetime
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from typing import Dict, List, Optional
|
|
14
|
+
|
|
15
|
+
from adr_schema import parse_frontmatter, split_frontmatter
|
|
16
|
+
from adr_retrieval_health import run_retrieval_health
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
ADR_FILENAME_RE = re.compile(r"(?i)^ADR-(\d{1,4})-")
|
|
20
|
+
MATERIAL_DRIFT_TYPES = {"accepted_evidence_changed", "missing_gate"}
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _run_json(command: List[str]) -> tuple[int, Dict]:
|
|
24
|
+
result = subprocess.run(command, capture_output=True, text=True)
|
|
25
|
+
try:
|
|
26
|
+
payload = json.loads(result.stdout) if result.stdout.strip() else {}
|
|
27
|
+
except json.JSONDecodeError:
|
|
28
|
+
payload = {"_stdout": result.stdout, "_stderr": result.stderr}
|
|
29
|
+
return result.returncode, payload
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def load_config(adr_dir: Path, explicit: Optional[str]) -> Dict:
|
|
33
|
+
candidates = []
|
|
34
|
+
if explicit:
|
|
35
|
+
candidates.append(Path(explicit))
|
|
36
|
+
candidates.extend([adr_dir / ".adr-kit.json", adr_dir.parent.parent / ".adr-kit.json"])
|
|
37
|
+
for path in candidates:
|
|
38
|
+
if path.exists():
|
|
39
|
+
return json.loads(path.read_text(encoding="utf-8"))
|
|
40
|
+
return {}
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def discover_files(adr_dir: Path) -> List[Path]:
|
|
44
|
+
return sorted(adr_dir.glob("ADR-*.md"), key=lambda p: p.name.lower()) if adr_dir.is_dir() else []
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def load_records(adr_dir: Path) -> List[Dict]:
|
|
48
|
+
records = []
|
|
49
|
+
for path in discover_files(adr_dir):
|
|
50
|
+
text = path.read_text(encoding="utf-8", errors="replace")
|
|
51
|
+
raw, _body = split_frontmatter(text)
|
|
52
|
+
if raw is None:
|
|
53
|
+
continue
|
|
54
|
+
data = parse_frontmatter(raw)
|
|
55
|
+
records.append({"path": path, "data": data, "body": _body})
|
|
56
|
+
return records
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _pointer_parts(pointer: str) -> tuple[Optional[Path], Optional[str]]:
|
|
60
|
+
if pointer.startswith("commit:"):
|
|
61
|
+
return None, None
|
|
62
|
+
path_part = pointer
|
|
63
|
+
symbol = None
|
|
64
|
+
if ":" in pointer and not re.match(r"^[A-Za-z]:[\\/]", pointer):
|
|
65
|
+
path_part, symbol = pointer.split(":", 1)
|
|
66
|
+
return Path(path_part), symbol.strip() if symbol else None
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def pointer_resolves(pointer: str, repo_root: Path) -> bool:
|
|
70
|
+
if pointer.startswith("commit:"):
|
|
71
|
+
commit = pointer.split(":", 1)[1].strip()
|
|
72
|
+
if not commit:
|
|
73
|
+
return False
|
|
74
|
+
result = subprocess.run(
|
|
75
|
+
["git", "-C", str(repo_root), "cat-file", "-e", f"{commit}^{{commit}}"],
|
|
76
|
+
capture_output=True,
|
|
77
|
+
text=True,
|
|
78
|
+
)
|
|
79
|
+
return result.returncode == 0
|
|
80
|
+
rel_path, symbol = _pointer_parts(pointer)
|
|
81
|
+
if rel_path is None:
|
|
82
|
+
return False
|
|
83
|
+
path = repo_root / rel_path
|
|
84
|
+
if not path.is_file():
|
|
85
|
+
return False
|
|
86
|
+
if symbol is None:
|
|
87
|
+
return True
|
|
88
|
+
return symbol in path.read_text(encoding="utf-8", errors="ignore")
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def pointer_changed_after(pointer: str, repo_root: Path, accepted_on: date) -> bool:
|
|
92
|
+
rel_path, _symbol = _pointer_parts(pointer)
|
|
93
|
+
if rel_path is None:
|
|
94
|
+
return False
|
|
95
|
+
path = repo_root / rel_path
|
|
96
|
+
if not path.is_file():
|
|
97
|
+
return False
|
|
98
|
+
changed_on = datetime.fromtimestamp(os.path.getmtime(path)).date()
|
|
99
|
+
return changed_on > accepted_on
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def latest_status_date(body: str, status: str) -> Optional[date]:
|
|
103
|
+
"""Return the latest matching lifecycle-history date, if one exists."""
|
|
104
|
+
pending_date: Optional[date] = None
|
|
105
|
+
matches: List[date] = []
|
|
106
|
+
for line in body.splitlines():
|
|
107
|
+
stripped = line.strip()
|
|
108
|
+
if stripped.startswith("- date:"):
|
|
109
|
+
value = stripped.split(":", 1)[1].strip().strip("\"'")
|
|
110
|
+
try:
|
|
111
|
+
pending_date = date.fromisoformat(value)
|
|
112
|
+
except ValueError:
|
|
113
|
+
pending_date = None
|
|
114
|
+
elif pending_date is not None and stripped.startswith("status:"):
|
|
115
|
+
value = stripped.split(":", 1)[1].strip().strip("\"'")
|
|
116
|
+
if value == status:
|
|
117
|
+
matches.append(pending_date)
|
|
118
|
+
pending_date = None
|
|
119
|
+
return max(matches) if matches else None
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def staleness_findings(records: List[Dict], repo_root: Path, stale_days: int) -> List[Dict]:
|
|
123
|
+
today = date.today()
|
|
124
|
+
findings: List[Dict] = []
|
|
125
|
+
for record in records:
|
|
126
|
+
data = record["data"]
|
|
127
|
+
adr_id = data.get("id", record["path"].stem)
|
|
128
|
+
status = data.get("status")
|
|
129
|
+
date_str = data.get("date")
|
|
130
|
+
adr_date = None
|
|
131
|
+
if date_str:
|
|
132
|
+
try:
|
|
133
|
+
adr_date = date.fromisoformat(date_str)
|
|
134
|
+
except ValueError:
|
|
135
|
+
adr_date = None
|
|
136
|
+
verified = data.get("verified_in", [])
|
|
137
|
+
|
|
138
|
+
if status == "Proposed":
|
|
139
|
+
if verified and all(pointer_resolves(pointer, repo_root) for pointer in verified):
|
|
140
|
+
findings.append({
|
|
141
|
+
"type": "shipped_but_proposed",
|
|
142
|
+
"adr_id": adr_id,
|
|
143
|
+
"file": record["path"].name,
|
|
144
|
+
"message": "Proposed ADR has resolving verified_in evidence",
|
|
145
|
+
})
|
|
146
|
+
if adr_date is not None and (today - adr_date).days > stale_days:
|
|
147
|
+
findings.append({
|
|
148
|
+
"type": "old_proposed",
|
|
149
|
+
"adr_id": adr_id,
|
|
150
|
+
"file": record["path"].name,
|
|
151
|
+
"message": f"Proposed ADR is older than {stale_days} days",
|
|
152
|
+
})
|
|
153
|
+
|
|
154
|
+
if status == "Accepted" and adr_date is not None and verified:
|
|
155
|
+
reviewed_on = latest_status_date(record.get("body", ""), "Accepted")
|
|
156
|
+
evidence_date = max(adr_date, reviewed_on) if reviewed_on else adr_date
|
|
157
|
+
changed = [
|
|
158
|
+
pointer for pointer in verified
|
|
159
|
+
if pointer_changed_after(pointer, repo_root, evidence_date)
|
|
160
|
+
]
|
|
161
|
+
if changed:
|
|
162
|
+
findings.append({
|
|
163
|
+
"type": "accepted_evidence_changed",
|
|
164
|
+
"adr_id": adr_id,
|
|
165
|
+
"file": record["path"].name,
|
|
166
|
+
"message": "Accepted ADR evidence changed after acceptance",
|
|
167
|
+
"pointers": changed,
|
|
168
|
+
})
|
|
169
|
+
return findings
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def gate_findings_from_lint(lint_payload: Dict) -> List[Dict]:
|
|
173
|
+
findings = []
|
|
174
|
+
for item in lint_payload.get("files", []):
|
|
175
|
+
for finding in item.get("findings", []):
|
|
176
|
+
if finding.get("gate") == "consistency" and "gate " in finding.get("summary", ""):
|
|
177
|
+
findings.append({
|
|
178
|
+
"type": "missing_gate",
|
|
179
|
+
"adr_id": f"ADR-{int(item.get('adr_num', 0)):03d}",
|
|
180
|
+
"file": item.get("file"),
|
|
181
|
+
"message": finding["summary"],
|
|
182
|
+
})
|
|
183
|
+
return findings
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def run_audit(repo_root: Path, audit_script: Path) -> Dict:
|
|
187
|
+
result = subprocess.run(
|
|
188
|
+
[sys.executable, str(audit_script), "--root", str(repo_root)],
|
|
189
|
+
capture_output=True,
|
|
190
|
+
text=True,
|
|
191
|
+
)
|
|
192
|
+
try:
|
|
193
|
+
payload = json.loads(result.stdout) if result.stdout.strip() else {}
|
|
194
|
+
except json.JSONDecodeError:
|
|
195
|
+
payload = {"_stdout": result.stdout, "_stderr": result.stderr}
|
|
196
|
+
return {
|
|
197
|
+
"triggered": True,
|
|
198
|
+
"exit_code": result.returncode,
|
|
199
|
+
"candidate_count": int(payload.get("candidate_count", 0) or 0),
|
|
200
|
+
"candidates": payload.get("candidates", []),
|
|
201
|
+
"error": result.stderr.strip() if result.returncode != 0 else None,
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def run_doctor(args) -> Dict:
|
|
206
|
+
adr_dir = Path(args.adr_dir)
|
|
207
|
+
repo_root = Path(args.repo_root).resolve() if args.repo_root else Path.cwd().resolve()
|
|
208
|
+
cfg = load_config(adr_dir, args.config)
|
|
209
|
+
stale_days = args.stale_days
|
|
210
|
+
if stale_days is None:
|
|
211
|
+
stale_days = int(cfg.get("doctor", {}).get("proposed_stale_days", 30))
|
|
212
|
+
|
|
213
|
+
bin_dir = Path(__file__).resolve().parent
|
|
214
|
+
index_script = bin_dir / "adr-index"
|
|
215
|
+
lint_script = bin_dir / "adr-lint"
|
|
216
|
+
audit_script = bin_dir / "adr-discover"
|
|
217
|
+
|
|
218
|
+
if args.fix_index:
|
|
219
|
+
subprocess.run([sys.executable, str(index_script), str(adr_dir)], capture_output=True, text=True)
|
|
220
|
+
|
|
221
|
+
index_code, index_payload = _run_json(
|
|
222
|
+
[sys.executable, str(index_script), "--check", "--format", "json", str(adr_dir)]
|
|
223
|
+
)
|
|
224
|
+
lint_code, lint_payload = _run_json(
|
|
225
|
+
[
|
|
226
|
+
sys.executable,
|
|
227
|
+
str(lint_script),
|
|
228
|
+
"--strict",
|
|
229
|
+
"--format",
|
|
230
|
+
"json",
|
|
231
|
+
"--repo-root",
|
|
232
|
+
str(repo_root),
|
|
233
|
+
str(adr_dir),
|
|
234
|
+
]
|
|
235
|
+
)
|
|
236
|
+
records = load_records(adr_dir)
|
|
237
|
+
findings = staleness_findings(records, repo_root, stale_days)
|
|
238
|
+
findings.extend(gate_findings_from_lint(lint_payload))
|
|
239
|
+
retrieval = run_retrieval_health(adr_dir, config=cfg)
|
|
240
|
+
if retrieval.get("probe_error"):
|
|
241
|
+
findings.append(
|
|
242
|
+
{
|
|
243
|
+
"type": "retrieval_probe_config",
|
|
244
|
+
"adr_id": "ADR-SET",
|
|
245
|
+
"file": Path(retrieval["probe_file"]).name,
|
|
246
|
+
"message": retrieval["probe_error"],
|
|
247
|
+
}
|
|
248
|
+
)
|
|
249
|
+
for probe in retrieval.get("probes", {}).get("results", []):
|
|
250
|
+
if probe.get("status") == "fail":
|
|
251
|
+
findings.append(
|
|
252
|
+
{
|
|
253
|
+
"type": "retrieval_probe",
|
|
254
|
+
"adr_id": "ADR-SET",
|
|
255
|
+
"file": Path(retrieval["probe_file"]).name,
|
|
256
|
+
"message": (
|
|
257
|
+
f"probe {probe['id']} failed; missing={probe['missing']} "
|
|
258
|
+
f"unexpected={probe['unexpected']}"
|
|
259
|
+
),
|
|
260
|
+
"probe": probe,
|
|
261
|
+
}
|
|
262
|
+
)
|
|
263
|
+
findings.extend(
|
|
264
|
+
item
|
|
265
|
+
for item in retrieval.get("metadata_findings", [])
|
|
266
|
+
if item.get("level") == "FAIL"
|
|
267
|
+
)
|
|
268
|
+
material_drift = [
|
|
269
|
+
finding for finding in findings
|
|
270
|
+
if finding.get("type") in MATERIAL_DRIFT_TYPES
|
|
271
|
+
]
|
|
272
|
+
audit_payload = {
|
|
273
|
+
"triggered": False,
|
|
274
|
+
"exit_code": None,
|
|
275
|
+
"candidate_count": 0,
|
|
276
|
+
"candidates": [],
|
|
277
|
+
"reason": None,
|
|
278
|
+
}
|
|
279
|
+
if material_drift:
|
|
280
|
+
audit_payload = run_audit(repo_root, audit_script)
|
|
281
|
+
audit_payload["reason"] = "material_drift"
|
|
282
|
+
|
|
283
|
+
return {
|
|
284
|
+
"adr_dir": str(adr_dir),
|
|
285
|
+
"repo_root": str(repo_root),
|
|
286
|
+
"summary": {
|
|
287
|
+
"index_ok": index_code == 0,
|
|
288
|
+
"lint_ok": lint_code == 0,
|
|
289
|
+
"findings": len(findings),
|
|
290
|
+
"retrieval_status": retrieval["status"],
|
|
291
|
+
"retrieval_advisories": sum(
|
|
292
|
+
item.get("level") == "ADVISORY"
|
|
293
|
+
for item in retrieval.get("metadata_findings", [])
|
|
294
|
+
),
|
|
295
|
+
"retrieval_probe_failures": retrieval.get("probes", {})
|
|
296
|
+
.get("summary", {})
|
|
297
|
+
.get("fail", 0),
|
|
298
|
+
},
|
|
299
|
+
"index": index_payload.get("summary", {}),
|
|
300
|
+
"lint": lint_payload.get("summary", {}),
|
|
301
|
+
"findings": findings,
|
|
302
|
+
"retrieval": retrieval,
|
|
303
|
+
"audit": audit_payload,
|
|
304
|
+
"exit_code": 1 if index_code != 0 or lint_code != 0 or findings else 0,
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def render_text(payload: Dict) -> str:
|
|
309
|
+
lines = [
|
|
310
|
+
f"adr-doctor: {payload['adr_dir']}",
|
|
311
|
+
f"index_ok={payload['summary']['index_ok']} lint_ok={payload['summary']['lint_ok']} findings={payload['summary']['findings']}",
|
|
312
|
+
]
|
|
313
|
+
for finding in payload["findings"]:
|
|
314
|
+
lines.append(f" {finding['type']}: {finding['adr_id']} {finding['message']}")
|
|
315
|
+
audit = payload.get("audit", {})
|
|
316
|
+
if audit.get("triggered"):
|
|
317
|
+
lines.append(
|
|
318
|
+
f"audit_triggered=True reason={audit.get('reason')} candidates={audit.get('candidate_count', 0)}"
|
|
319
|
+
)
|
|
320
|
+
return "\n".join(lines)
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
def main(argv: List[str] | None = None) -> int:
|
|
324
|
+
parser = argparse.ArgumentParser(prog="adr-doctor", description="Run local ADR health checks.")
|
|
325
|
+
parser.add_argument("adr_dir", nargs="?", default="docs/adr")
|
|
326
|
+
parser.add_argument("--repo-root", default=None)
|
|
327
|
+
parser.add_argument("--config", default=None)
|
|
328
|
+
parser.add_argument("--stale-days", type=int, default=None)
|
|
329
|
+
parser.add_argument("--fix-index", action="store_true", help="regenerate index before checking")
|
|
330
|
+
parser.add_argument("--format", choices=["text", "json"], default="text")
|
|
331
|
+
args = parser.parse_args(argv)
|
|
332
|
+
|
|
333
|
+
payload = run_doctor(args)
|
|
334
|
+
if args.format == "json":
|
|
335
|
+
print(json.dumps(payload, indent=2))
|
|
336
|
+
else:
|
|
337
|
+
print(render_text(payload))
|
|
338
|
+
return int(payload["exit_code"])
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
if __name__ == "__main__":
|
|
342
|
+
sys.exit(main())
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
"""Versioned doctor output models and rendering."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
SCHEMA_VERSION = 1
|
|
9
|
+
FAILURE_STATUSES = {"failed", "stale"}
|
|
10
|
+
STATUS_ORDER = {
|
|
11
|
+
"failed": 8,
|
|
12
|
+
"stale": 7,
|
|
13
|
+
"trust-pending": 6,
|
|
14
|
+
"degraded": 5,
|
|
15
|
+
"repaired": 4,
|
|
16
|
+
"disabled": 3,
|
|
17
|
+
"unsupported": 2,
|
|
18
|
+
"healthy": 1,
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def check(
|
|
23
|
+
check_id: str,
|
|
24
|
+
*,
|
|
25
|
+
status: str,
|
|
26
|
+
client: str = "common",
|
|
27
|
+
summary: str,
|
|
28
|
+
evidence: list[dict[str, Any]] | None = None,
|
|
29
|
+
repairs: list[dict[str, Any]] | None = None,
|
|
30
|
+
degradations: list[dict[str, Any]] | None = None,
|
|
31
|
+
actions: list[dict[str, Any]] | None = None,
|
|
32
|
+
required: bool = True,
|
|
33
|
+
extension: dict[str, Any] | None = None,
|
|
34
|
+
) -> dict[str, Any]:
|
|
35
|
+
return {
|
|
36
|
+
"id": check_id,
|
|
37
|
+
"client": client,
|
|
38
|
+
"status": status,
|
|
39
|
+
"required": required,
|
|
40
|
+
"summary": summary,
|
|
41
|
+
"evidence": evidence or [],
|
|
42
|
+
"repairs": repairs or [],
|
|
43
|
+
"degradations": degradations or [],
|
|
44
|
+
"actions": actions or [],
|
|
45
|
+
"extension": extension,
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def benchmark_extension(
|
|
50
|
+
*,
|
|
51
|
+
method_id: str,
|
|
52
|
+
state: str,
|
|
53
|
+
sample_count: int,
|
|
54
|
+
reference_fixture: str,
|
|
55
|
+
budget: dict[str, float | int],
|
|
56
|
+
measurements: dict[str, float | int | None] | None = None,
|
|
57
|
+
) -> dict[str, Any]:
|
|
58
|
+
values = {"p50_ms": None, "p95_ms": None, "max_ms": None}
|
|
59
|
+
values.update(measurements or {})
|
|
60
|
+
return {
|
|
61
|
+
"contract_version": 1,
|
|
62
|
+
"kind": "latency-benchmark",
|
|
63
|
+
"method_id": method_id,
|
|
64
|
+
"state": state,
|
|
65
|
+
"sample_count": sample_count,
|
|
66
|
+
"reference_fixture": reference_fixture,
|
|
67
|
+
"measurements": values,
|
|
68
|
+
"budget": budget,
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def build_report(
|
|
73
|
+
*,
|
|
74
|
+
root: Path,
|
|
75
|
+
mode: str,
|
|
76
|
+
adr: dict[str, Any],
|
|
77
|
+
checks: list[dict[str, Any]],
|
|
78
|
+
repairs: list[dict[str, Any]],
|
|
79
|
+
) -> dict[str, Any]:
|
|
80
|
+
client_status = {}
|
|
81
|
+
for client in ("claude", "codex", "copilot"):
|
|
82
|
+
relevant = [item["status"] for item in checks if item["client"] == client]
|
|
83
|
+
client_status[client] = (
|
|
84
|
+
max(relevant, key=lambda value: STATUS_ORDER.get(value, 0))
|
|
85
|
+
if relevant
|
|
86
|
+
else "unsupported"
|
|
87
|
+
)
|
|
88
|
+
required_failures = [
|
|
89
|
+
item for item in checks
|
|
90
|
+
if item["required"] and item["status"] in FAILURE_STATUSES
|
|
91
|
+
]
|
|
92
|
+
exit_code = 1 if adr.get("exit_code") or required_failures else 0
|
|
93
|
+
statuses = [item["status"] for item in checks]
|
|
94
|
+
if exit_code:
|
|
95
|
+
overall = "failed"
|
|
96
|
+
elif "degraded" in statuses or "trust-pending" in statuses:
|
|
97
|
+
overall = "degraded"
|
|
98
|
+
elif repairs or "repaired" in statuses:
|
|
99
|
+
overall = "repaired"
|
|
100
|
+
else:
|
|
101
|
+
overall = "healthy"
|
|
102
|
+
return {
|
|
103
|
+
"schema_version": SCHEMA_VERSION,
|
|
104
|
+
"mode": mode,
|
|
105
|
+
"root": str(root),
|
|
106
|
+
"overall_status": overall,
|
|
107
|
+
"clients": client_status,
|
|
108
|
+
"summary": {
|
|
109
|
+
"index_ok": adr.get("summary", {}).get("index_ok", False),
|
|
110
|
+
"lint_ok": adr.get("summary", {}).get("lint_ok", False),
|
|
111
|
+
"findings": adr.get("summary", {}).get("findings", 0),
|
|
112
|
+
"checks": len(checks),
|
|
113
|
+
"repairs": len(repairs),
|
|
114
|
+
"required_failures": len(required_failures),
|
|
115
|
+
"adr_findings": adr.get("summary", {}).get("findings", 0),
|
|
116
|
+
},
|
|
117
|
+
"checks": checks,
|
|
118
|
+
"repairs": repairs,
|
|
119
|
+
"adr": adr,
|
|
120
|
+
# Stable legacy fields retained for existing CI consumers.
|
|
121
|
+
"adr_dir": adr.get("adr_dir"),
|
|
122
|
+
"repo_root": adr.get("repo_root"),
|
|
123
|
+
"index": adr.get("index", {}),
|
|
124
|
+
"lint": adr.get("lint", {}),
|
|
125
|
+
"findings": adr.get("findings", []),
|
|
126
|
+
"audit": adr.get("audit", {}),
|
|
127
|
+
"exit_code": exit_code,
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def render_human(report: dict[str, Any]) -> str:
|
|
132
|
+
lines = [
|
|
133
|
+
f"adr-doctor: {report['overall_status']} ({report['mode']})",
|
|
134
|
+
"clients: " + ", ".join(
|
|
135
|
+
f"{name}={status}" for name, status in report["clients"].items()
|
|
136
|
+
),
|
|
137
|
+
(
|
|
138
|
+
f"checks={report['summary']['checks']} "
|
|
139
|
+
f"repairs={report['summary']['repairs']} "
|
|
140
|
+
f"adr_findings={report['summary']['adr_findings']}"
|
|
141
|
+
),
|
|
142
|
+
]
|
|
143
|
+
for item in report["checks"]:
|
|
144
|
+
lines.append(
|
|
145
|
+
f" {item['status']}: {item['client']}/{item['id']} "
|
|
146
|
+
f"{item['summary']}"
|
|
147
|
+
)
|
|
148
|
+
for action in item["actions"]:
|
|
149
|
+
lines.append(f" action: {action.get('command') or action.get('detail')}")
|
|
150
|
+
for repair in report["repairs"]:
|
|
151
|
+
lines.append(f" repaired: {repair['path']} ({repair['kind']})")
|
|
152
|
+
return "\n".join(lines)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def generated_tree_owner(plugin_root: Path) -> str | None:
|
|
156
|
+
"""Which client this tree IS, when it is a generated client tree.
|
|
157
|
+
|
|
158
|
+
Positive identity, not "my import failed". A canonical payload root always
|
|
159
|
+
carries clients/workflows.json: it is the generator's own input, and the
|
|
160
|
+
public payload ships `clients` as a whole include_root, so an installed
|
|
161
|
+
payload has it at its root too. RUNTIME_SUPPORT_FILES deliberately never
|
|
162
|
+
mirrors it -- that absence is the marker read here, which is why mirroring
|
|
163
|
+
it later would silently stop the doctor degrading and start it hard-failing.
|
|
164
|
+
"""
|
|
165
|
+
if (plugin_root / "clients" / "workflows.json").is_file():
|
|
166
|
+
return None
|
|
167
|
+
if (plugin_root / ".codex-plugin" / "plugin.json").is_file():
|
|
168
|
+
return "codex"
|
|
169
|
+
if (plugin_root / "plugin.json").is_file() and (plugin_root / "hooks.json").is_file():
|
|
170
|
+
return "copilot"
|
|
171
|
+
return None
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def client_root(plugin_root: Path, client: str) -> Path | None:
|
|
175
|
+
"""Where this client's owned config lives, or None if not installed here.
|
|
176
|
+
|
|
177
|
+
In a canonical payload root each client owns a subdirectory. In a generated
|
|
178
|
+
client tree there is only one client and it owns the root itself -- codex/
|
|
179
|
+
IS the plugin root for Codex, so codex/.mcp.json sits there and not at
|
|
180
|
+
codex/codex/.mcp.json. Assuming the canonical shape made the doctor report
|
|
181
|
+
six failures against paths that were never meant to exist.
|
|
182
|
+
"""
|
|
183
|
+
owner = generated_tree_owner(plugin_root)
|
|
184
|
+
if owner is None:
|
|
185
|
+
return plugin_root if client == "claude" else plugin_root / client
|
|
186
|
+
return plugin_root if client == owner else None
|