@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_regex.py
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""Killable, bounded regex evaluation for repository-authored policy."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import atexit
|
|
6
|
+
import json
|
|
7
|
+
import queue
|
|
8
|
+
import subprocess
|
|
9
|
+
import sys
|
|
10
|
+
import threading
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from typing import Optional
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
DEFAULT_REGEX_TIMEOUT_SECONDS = 1.0
|
|
16
|
+
DEFAULT_REGEX_INPUT_BYTES = 2 * 1024 * 1024
|
|
17
|
+
DEFAULT_REGEX_PATTERN_CHARS = 4096
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class RegexEvaluationError(RuntimeError):
|
|
21
|
+
"""Base error for a regex that could not be evaluated safely."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class RegexTimeoutError(RegexEvaluationError):
|
|
25
|
+
"""Raised when an isolated regex exceeds its wall-clock budget."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class RegexBudgetError(RegexEvaluationError):
|
|
29
|
+
"""Raised when regex pattern or input exceeds its deterministic budget."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class RegexEvaluator:
|
|
33
|
+
"""One persistent worker process, restarted after timeout or failure."""
|
|
34
|
+
|
|
35
|
+
def __init__(
|
|
36
|
+
self,
|
|
37
|
+
*,
|
|
38
|
+
timeout_seconds: float = DEFAULT_REGEX_TIMEOUT_SECONDS,
|
|
39
|
+
max_input_bytes: int = DEFAULT_REGEX_INPUT_BYTES,
|
|
40
|
+
max_pattern_chars: int = DEFAULT_REGEX_PATTERN_CHARS,
|
|
41
|
+
) -> None:
|
|
42
|
+
self.timeout_seconds = timeout_seconds
|
|
43
|
+
self.max_input_bytes = max_input_bytes
|
|
44
|
+
self.max_pattern_chars = max_pattern_chars
|
|
45
|
+
self._process: Optional[subprocess.Popen[str]] = None
|
|
46
|
+
self._responses: "queue.Queue[Optional[str]]" = queue.Queue()
|
|
47
|
+
|
|
48
|
+
def _start(self) -> None:
|
|
49
|
+
worker = Path(__file__).resolve().with_name("adr_regex_worker.py")
|
|
50
|
+
self._responses = queue.Queue()
|
|
51
|
+
self._process = subprocess.Popen(
|
|
52
|
+
[sys.executable, str(worker)],
|
|
53
|
+
stdin=subprocess.PIPE,
|
|
54
|
+
stdout=subprocess.PIPE,
|
|
55
|
+
stderr=subprocess.DEVNULL,
|
|
56
|
+
text=True,
|
|
57
|
+
encoding="utf-8",
|
|
58
|
+
errors="replace",
|
|
59
|
+
bufsize=1,
|
|
60
|
+
)
|
|
61
|
+
assert self._process.stdout is not None
|
|
62
|
+
# Capture stdout and the response queue as locals so that if the
|
|
63
|
+
# evaluator is restarted (e.g. after a timeout), the old reader thread
|
|
64
|
+
# puts its sentinel None into the *old* queue rather than the new one.
|
|
65
|
+
_stdout = self._process.stdout
|
|
66
|
+
_responses: "queue.Queue[Optional[str]]" = self._responses
|
|
67
|
+
|
|
68
|
+
def _read() -> None:
|
|
69
|
+
for response in _stdout:
|
|
70
|
+
_responses.put(response)
|
|
71
|
+
_responses.put(None)
|
|
72
|
+
|
|
73
|
+
threading.Thread(target=_read, daemon=True).start()
|
|
74
|
+
|
|
75
|
+
def close(self) -> None:
|
|
76
|
+
process = self._process
|
|
77
|
+
self._process = None
|
|
78
|
+
if process is None:
|
|
79
|
+
return
|
|
80
|
+
if process.stdin is not None:
|
|
81
|
+
try:
|
|
82
|
+
process.stdin.close()
|
|
83
|
+
except OSError:
|
|
84
|
+
pass
|
|
85
|
+
try:
|
|
86
|
+
process.wait(timeout=0.2)
|
|
87
|
+
except subprocess.TimeoutExpired:
|
|
88
|
+
process.kill()
|
|
89
|
+
process.wait()
|
|
90
|
+
|
|
91
|
+
def _terminate(self) -> None:
|
|
92
|
+
process = self._process
|
|
93
|
+
self._process = None
|
|
94
|
+
if process is not None and process.poll() is None:
|
|
95
|
+
process.kill()
|
|
96
|
+
process.wait()
|
|
97
|
+
|
|
98
|
+
def search(self, pattern: str, text: str, flags: int = 0) -> bool:
|
|
99
|
+
if len(pattern) > self.max_pattern_chars:
|
|
100
|
+
raise RegexBudgetError(
|
|
101
|
+
f"pattern length {len(pattern)} exceeds {self.max_pattern_chars} characters"
|
|
102
|
+
)
|
|
103
|
+
input_bytes = len(text.encode("utf-8", errors="replace"))
|
|
104
|
+
if input_bytes > self.max_input_bytes:
|
|
105
|
+
raise RegexBudgetError(
|
|
106
|
+
f"input size {input_bytes} exceeds {self.max_input_bytes} bytes"
|
|
107
|
+
)
|
|
108
|
+
if self._process is None or self._process.poll() is not None:
|
|
109
|
+
self._start()
|
|
110
|
+
assert self._process is not None
|
|
111
|
+
assert self._process.stdin is not None
|
|
112
|
+
request = json.dumps(
|
|
113
|
+
{"pattern": pattern, "text": text, "flags": flags},
|
|
114
|
+
ensure_ascii=False,
|
|
115
|
+
separators=(",", ":"),
|
|
116
|
+
)
|
|
117
|
+
try:
|
|
118
|
+
self._process.stdin.write(request + "\n")
|
|
119
|
+
self._process.stdin.flush()
|
|
120
|
+
except (BrokenPipeError, OSError) as exc:
|
|
121
|
+
self._terminate()
|
|
122
|
+
raise RegexEvaluationError(f"isolated regex worker failed: {exc}") from exc
|
|
123
|
+
try:
|
|
124
|
+
response_line = self._responses.get(timeout=self.timeout_seconds)
|
|
125
|
+
except queue.Empty as exc:
|
|
126
|
+
self._terminate()
|
|
127
|
+
raise RegexTimeoutError(
|
|
128
|
+
f"regex exceeded {self.timeout_seconds:.3f}s wall-clock budget"
|
|
129
|
+
) from exc
|
|
130
|
+
if response_line is None:
|
|
131
|
+
self._terminate()
|
|
132
|
+
raise RegexEvaluationError("isolated regex worker exited unexpectedly")
|
|
133
|
+
try:
|
|
134
|
+
response = json.loads(response_line)
|
|
135
|
+
except json.JSONDecodeError as exc:
|
|
136
|
+
self._terminate()
|
|
137
|
+
raise RegexEvaluationError(
|
|
138
|
+
"isolated regex worker returned invalid JSON"
|
|
139
|
+
) from exc
|
|
140
|
+
if not response.get("ok"):
|
|
141
|
+
raise RegexEvaluationError(
|
|
142
|
+
f"isolated regex worker rejected pattern: {response.get('error', 'unknown error')}"
|
|
143
|
+
)
|
|
144
|
+
return bool(response.get("matched"))
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
_DEFAULT_EVALUATOR: Optional[RegexEvaluator] = None
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def bounded_regex_search(pattern: str, text: str, flags: int = 0) -> bool:
|
|
151
|
+
"""Search in an isolated process with fixed input and wall-clock budgets."""
|
|
152
|
+
global _DEFAULT_EVALUATOR
|
|
153
|
+
if _DEFAULT_EVALUATOR is None:
|
|
154
|
+
_DEFAULT_EVALUATOR = RegexEvaluator()
|
|
155
|
+
return _DEFAULT_EVALUATOR.search(pattern, text, flags)
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def _close_default() -> None:
|
|
159
|
+
global _DEFAULT_EVALUATOR
|
|
160
|
+
if _DEFAULT_EVALUATOR is not None:
|
|
161
|
+
_DEFAULT_EVALUATOR.close()
|
|
162
|
+
_DEFAULT_EVALUATOR = None
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
atexit.register(_close_default)
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Isolated regex worker for adr-kit policy evaluation.
|
|
3
|
+
|
|
4
|
+
The parent process owns all timeouts and can terminate this process if CPython's
|
|
5
|
+
backtracking regex engine becomes unresponsive.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import json
|
|
11
|
+
import re
|
|
12
|
+
import sys
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def main() -> int:
|
|
16
|
+
for line in sys.stdin:
|
|
17
|
+
try:
|
|
18
|
+
request = json.loads(line)
|
|
19
|
+
pattern = re.compile(request["pattern"], int(request.get("flags", 0)))
|
|
20
|
+
match = pattern.search(request["text"])
|
|
21
|
+
response = {"ok": True, "matched": match is not None}
|
|
22
|
+
except (KeyError, TypeError, ValueError, re.error) as exc:
|
|
23
|
+
response = {"ok": False, "error": str(exc)}
|
|
24
|
+
sys.stdout.write(json.dumps(response, separators=(",", ":")) + "\n")
|
|
25
|
+
sys.stdout.flush()
|
|
26
|
+
return 0
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
if __name__ == "__main__":
|
|
30
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
"""Read-only selective-context probes and retrieval metadata health."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import re
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Dict, List, Optional, Sequence
|
|
9
|
+
|
|
10
|
+
from adr_query import IndexQueryError, load_index_graph, query_records
|
|
11
|
+
|
|
12
|
+
MAX_PROBES = 100
|
|
13
|
+
MAX_EXPECTATIONS = 20
|
|
14
|
+
DEFAULT_PROBE_FILE = "adr-context-probes.json"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class ProbeConfigError(ValueError):
|
|
18
|
+
"""Raised when a project retrieval-probe file is malformed."""
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def _string_array(
|
|
22
|
+
value: object,
|
|
23
|
+
field: str,
|
|
24
|
+
*,
|
|
25
|
+
maximum: int,
|
|
26
|
+
adr_ids: bool = False,
|
|
27
|
+
) -> List[str]:
|
|
28
|
+
if not isinstance(value, list) or len(value) > maximum:
|
|
29
|
+
raise ProbeConfigError(f"{field} must be an array with at most {maximum} items")
|
|
30
|
+
result: List[str] = []
|
|
31
|
+
for item in value:
|
|
32
|
+
if not isinstance(item, str) or not item.strip() or len(item) > 240:
|
|
33
|
+
raise ProbeConfigError(f"{field} entries must be non-empty strings")
|
|
34
|
+
if adr_ids and not re.fullmatch(r"ADR-\d{3,4}", item):
|
|
35
|
+
raise ProbeConfigError(f"{field} contains invalid ADR id {item!r}")
|
|
36
|
+
result.append(item)
|
|
37
|
+
if len({item.casefold() for item in result}) != len(result):
|
|
38
|
+
raise ProbeConfigError(f"{field} entries must be unique")
|
|
39
|
+
return result
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def load_probes(path: Path) -> Dict:
|
|
43
|
+
try:
|
|
44
|
+
payload = json.loads(path.read_text(encoding="utf-8"))
|
|
45
|
+
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
|
|
46
|
+
raise ProbeConfigError(f"cannot read retrieval probes: {exc}") from exc
|
|
47
|
+
if not isinstance(payload, dict) or payload.get("schema_version") != 1:
|
|
48
|
+
raise ProbeConfigError("retrieval probes require schema_version 1")
|
|
49
|
+
allowed_root = {"$schema", "schema_version", "probes"}
|
|
50
|
+
if set(payload) - allowed_root:
|
|
51
|
+
raise ProbeConfigError(
|
|
52
|
+
"unknown retrieval-probe root field(s): "
|
|
53
|
+
+ ", ".join(sorted(set(payload) - allowed_root))
|
|
54
|
+
)
|
|
55
|
+
probes = payload.get("probes")
|
|
56
|
+
if not isinstance(probes, list) or len(probes) > MAX_PROBES:
|
|
57
|
+
raise ProbeConfigError(f"probes must be an array with at most {MAX_PROBES} items")
|
|
58
|
+
ids = set()
|
|
59
|
+
normalized = []
|
|
60
|
+
allowed_probe = {
|
|
61
|
+
"id",
|
|
62
|
+
"query",
|
|
63
|
+
"paths",
|
|
64
|
+
"components",
|
|
65
|
+
"symbols",
|
|
66
|
+
"topics",
|
|
67
|
+
"limit",
|
|
68
|
+
"expect",
|
|
69
|
+
}
|
|
70
|
+
for raw in probes:
|
|
71
|
+
if not isinstance(raw, dict) or set(raw) - allowed_probe:
|
|
72
|
+
raise ProbeConfigError("each retrieval probe must be a known-field object")
|
|
73
|
+
probe_id = raw.get("id")
|
|
74
|
+
query = raw.get("query")
|
|
75
|
+
limit = raw.get("limit", 3)
|
|
76
|
+
expect = raw.get("expect")
|
|
77
|
+
if (
|
|
78
|
+
not isinstance(probe_id, str)
|
|
79
|
+
or not re.fullmatch(r"[a-z][a-z0-9-]{0,79}", probe_id)
|
|
80
|
+
or probe_id in ids
|
|
81
|
+
):
|
|
82
|
+
raise ProbeConfigError(f"invalid or duplicate probe id {probe_id!r}")
|
|
83
|
+
if not isinstance(query, str) or not query.strip() or len(query) > 1000:
|
|
84
|
+
raise ProbeConfigError(f"{probe_id}: query must be a non-empty string")
|
|
85
|
+
if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 20:
|
|
86
|
+
raise ProbeConfigError(f"{probe_id}: limit must be between 1 and 20")
|
|
87
|
+
if (
|
|
88
|
+
not isinstance(expect, dict)
|
|
89
|
+
or set(expect) - {"include", "exclude"}
|
|
90
|
+
):
|
|
91
|
+
raise ProbeConfigError(f"{probe_id}: expect must contain include/exclude")
|
|
92
|
+
include = _string_array(
|
|
93
|
+
expect.get("include", []),
|
|
94
|
+
f"{probe_id}.expect.include",
|
|
95
|
+
maximum=MAX_EXPECTATIONS,
|
|
96
|
+
adr_ids=True,
|
|
97
|
+
)
|
|
98
|
+
exclude = _string_array(
|
|
99
|
+
expect.get("exclude", []),
|
|
100
|
+
f"{probe_id}.expect.exclude",
|
|
101
|
+
maximum=MAX_EXPECTATIONS,
|
|
102
|
+
adr_ids=True,
|
|
103
|
+
)
|
|
104
|
+
if set(include) & set(exclude):
|
|
105
|
+
raise ProbeConfigError(f"{probe_id}: include and exclude overlap")
|
|
106
|
+
ids.add(probe_id)
|
|
107
|
+
normalized.append(
|
|
108
|
+
{
|
|
109
|
+
"id": probe_id,
|
|
110
|
+
"query": query.strip(),
|
|
111
|
+
"paths": _string_array(
|
|
112
|
+
raw.get("paths", []), f"{probe_id}.paths", maximum=32
|
|
113
|
+
),
|
|
114
|
+
"components": _string_array(
|
|
115
|
+
raw.get("components", []), f"{probe_id}.components", maximum=32
|
|
116
|
+
),
|
|
117
|
+
"symbols": _string_array(
|
|
118
|
+
raw.get("symbols", []), f"{probe_id}.symbols", maximum=32
|
|
119
|
+
),
|
|
120
|
+
"topics": _string_array(
|
|
121
|
+
raw.get("topics", []), f"{probe_id}.topics", maximum=32
|
|
122
|
+
),
|
|
123
|
+
"limit": limit,
|
|
124
|
+
"expect": {"include": include, "exclude": exclude},
|
|
125
|
+
}
|
|
126
|
+
)
|
|
127
|
+
return {"schema_version": 1, "probes": normalized}
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _metadata_findings(records: Sequence[Dict], strict: bool) -> List[Dict]:
|
|
131
|
+
findings = []
|
|
132
|
+
for record in records:
|
|
133
|
+
metadata = record.get("metadata", {})
|
|
134
|
+
if (
|
|
135
|
+
record.get("status") != "Accepted"
|
|
136
|
+
or not isinstance(metadata, dict)
|
|
137
|
+
or metadata.get("binding") is not True
|
|
138
|
+
):
|
|
139
|
+
continue
|
|
140
|
+
contract = record.get("decision_contract", {})
|
|
141
|
+
has_contract = isinstance(contract, dict) and any(
|
|
142
|
+
isinstance(values, list) and any(str(value).strip() for value in values)
|
|
143
|
+
for values in contract.values()
|
|
144
|
+
)
|
|
145
|
+
has_selective_data = any(
|
|
146
|
+
isinstance(record.get(field), list) and record.get(field)
|
|
147
|
+
for field in ("topics", "aliases", "components", "symbols")
|
|
148
|
+
)
|
|
149
|
+
if (
|
|
150
|
+
record.get("context_scope") != "global"
|
|
151
|
+
and not has_selective_data
|
|
152
|
+
and not has_contract
|
|
153
|
+
):
|
|
154
|
+
findings.append(
|
|
155
|
+
{
|
|
156
|
+
"type": "selective_context_metadata",
|
|
157
|
+
"level": "FAIL" if strict else "ADVISORY",
|
|
158
|
+
"adr_id": record.get("id"),
|
|
159
|
+
"file": record.get("path"),
|
|
160
|
+
"message": (
|
|
161
|
+
"Accepted binding ADR has no selective retrieval metadata; "
|
|
162
|
+
"add topics, aliases, components, symbols, a Decision Contract, "
|
|
163
|
+
"or explicitly mark context_scope: global"
|
|
164
|
+
),
|
|
165
|
+
}
|
|
166
|
+
)
|
|
167
|
+
return findings
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def evaluate_probes(
|
|
171
|
+
records: Sequence[Dict],
|
|
172
|
+
relationships: Sequence[Dict],
|
|
173
|
+
schema_version: int,
|
|
174
|
+
adr_dir: Path,
|
|
175
|
+
probes: Sequence[Dict],
|
|
176
|
+
) -> Dict:
|
|
177
|
+
results = []
|
|
178
|
+
passed = 0
|
|
179
|
+
for probe in probes:
|
|
180
|
+
ranked = query_records(
|
|
181
|
+
records,
|
|
182
|
+
relationships,
|
|
183
|
+
probe["query"],
|
|
184
|
+
adr_dir,
|
|
185
|
+
limit=probe["limit"],
|
|
186
|
+
include_history=False,
|
|
187
|
+
paths=probe["paths"],
|
|
188
|
+
components=probe["components"],
|
|
189
|
+
symbols=probe["symbols"],
|
|
190
|
+
topics=probe["topics"],
|
|
191
|
+
source=f"index-v{schema_version}",
|
|
192
|
+
schema_version=schema_version,
|
|
193
|
+
)
|
|
194
|
+
actual = [
|
|
195
|
+
{
|
|
196
|
+
"rank": rank,
|
|
197
|
+
"adr_id": item["adr_id"],
|
|
198
|
+
"authority": item["authority"],
|
|
199
|
+
"role": item["role"],
|
|
200
|
+
"score": item["score"],
|
|
201
|
+
"matches": item["matches"],
|
|
202
|
+
}
|
|
203
|
+
for rank, item in enumerate(ranked, start=1)
|
|
204
|
+
]
|
|
205
|
+
actual_ids = [item["adr_id"] for item in actual]
|
|
206
|
+
missing = [
|
|
207
|
+
adr_id
|
|
208
|
+
for adr_id in probe["expect"]["include"]
|
|
209
|
+
if adr_id not in actual_ids
|
|
210
|
+
]
|
|
211
|
+
unexpected = [
|
|
212
|
+
adr_id
|
|
213
|
+
for adr_id in probe["expect"]["exclude"]
|
|
214
|
+
if adr_id in actual_ids
|
|
215
|
+
]
|
|
216
|
+
historical = [
|
|
217
|
+
item["adr_id"]
|
|
218
|
+
for item in actual
|
|
219
|
+
if item["authority"] == "historical"
|
|
220
|
+
]
|
|
221
|
+
ok = not missing and not unexpected and not historical
|
|
222
|
+
passed += int(ok)
|
|
223
|
+
results.append(
|
|
224
|
+
{
|
|
225
|
+
"id": probe["id"],
|
|
226
|
+
"status": "pass" if ok else "fail",
|
|
227
|
+
"query": probe["query"],
|
|
228
|
+
"inputs": {
|
|
229
|
+
"paths": probe["paths"],
|
|
230
|
+
"components": probe["components"],
|
|
231
|
+
"symbols": probe["symbols"],
|
|
232
|
+
"topics": probe["topics"],
|
|
233
|
+
"limit": probe["limit"],
|
|
234
|
+
},
|
|
235
|
+
"expected": probe["expect"],
|
|
236
|
+
"actual": actual,
|
|
237
|
+
"missing": missing,
|
|
238
|
+
"unexpected": unexpected,
|
|
239
|
+
"historical_leakage": historical,
|
|
240
|
+
}
|
|
241
|
+
)
|
|
242
|
+
return {
|
|
243
|
+
"configured": bool(probes),
|
|
244
|
+
"summary": {
|
|
245
|
+
"total": len(probes),
|
|
246
|
+
"pass": passed,
|
|
247
|
+
"fail": len(probes) - passed,
|
|
248
|
+
},
|
|
249
|
+
"results": results,
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def _load_config(adr_dir: Path) -> Dict:
|
|
254
|
+
path = adr_dir / ".adr-kit.json"
|
|
255
|
+
if not path.is_file():
|
|
256
|
+
return {}
|
|
257
|
+
try:
|
|
258
|
+
payload = json.loads(path.read_text(encoding="utf-8"))
|
|
259
|
+
except (OSError, UnicodeError, json.JSONDecodeError):
|
|
260
|
+
return {}
|
|
261
|
+
return payload if isinstance(payload, dict) else {}
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def run_retrieval_health(
|
|
265
|
+
adr_dir: Path,
|
|
266
|
+
*,
|
|
267
|
+
probe_path: Optional[Path] = None,
|
|
268
|
+
config: Optional[Dict] = None,
|
|
269
|
+
) -> Dict:
|
|
270
|
+
cfg = config if isinstance(config, dict) else _load_config(adr_dir)
|
|
271
|
+
context_cfg = cfg.get("context", {}) if isinstance(cfg, dict) else {}
|
|
272
|
+
mode = context_cfg.get("retrieval_completeness", "advisory")
|
|
273
|
+
if mode not in {"off", "advisory", "strict"}:
|
|
274
|
+
mode = "advisory"
|
|
275
|
+
configured_path = probe_path or adr_dir / str(
|
|
276
|
+
context_cfg.get("probes_file", DEFAULT_PROBE_FILE)
|
|
277
|
+
)
|
|
278
|
+
configured_path = configured_path.resolve()
|
|
279
|
+
try:
|
|
280
|
+
configured_path.relative_to(adr_dir.resolve())
|
|
281
|
+
except ValueError:
|
|
282
|
+
return {
|
|
283
|
+
"status": "fail",
|
|
284
|
+
"source": None,
|
|
285
|
+
"schema_version": None,
|
|
286
|
+
"probe_file": configured_path.as_posix(),
|
|
287
|
+
"probe_error": "retrieval probe file must stay within the ADR directory",
|
|
288
|
+
"index_error": None,
|
|
289
|
+
"metadata_mode": mode,
|
|
290
|
+
"metadata_findings": [],
|
|
291
|
+
"probes": {
|
|
292
|
+
"configured": False,
|
|
293
|
+
"summary": {"total": 0, "pass": 0, "fail": 1},
|
|
294
|
+
"results": [],
|
|
295
|
+
},
|
|
296
|
+
}
|
|
297
|
+
try:
|
|
298
|
+
records, relationships, version = load_index_graph(adr_dir)
|
|
299
|
+
except IndexQueryError as exc:
|
|
300
|
+
return {
|
|
301
|
+
"status": "degraded",
|
|
302
|
+
"source": None,
|
|
303
|
+
"schema_version": None,
|
|
304
|
+
"probe_file": configured_path.as_posix(),
|
|
305
|
+
"index_error": str(exc),
|
|
306
|
+
"metadata_mode": mode,
|
|
307
|
+
"metadata_findings": [],
|
|
308
|
+
"probes": {
|
|
309
|
+
"configured": configured_path.is_file(),
|
|
310
|
+
"summary": {"total": 0, "pass": 0, "fail": 0},
|
|
311
|
+
"results": [],
|
|
312
|
+
},
|
|
313
|
+
}
|
|
314
|
+
try:
|
|
315
|
+
probe_payload = (
|
|
316
|
+
load_probes(configured_path)
|
|
317
|
+
if configured_path.is_file()
|
|
318
|
+
else {"schema_version": 1, "probes": []}
|
|
319
|
+
)
|
|
320
|
+
probes = evaluate_probes(
|
|
321
|
+
records,
|
|
322
|
+
relationships,
|
|
323
|
+
version,
|
|
324
|
+
adr_dir,
|
|
325
|
+
probe_payload["probes"],
|
|
326
|
+
)
|
|
327
|
+
probe_error = None
|
|
328
|
+
except ProbeConfigError as exc:
|
|
329
|
+
probes = {
|
|
330
|
+
"configured": True,
|
|
331
|
+
"summary": {"total": 0, "pass": 0, "fail": 1},
|
|
332
|
+
"results": [],
|
|
333
|
+
}
|
|
334
|
+
probe_error = str(exc)
|
|
335
|
+
metadata = [] if mode == "off" else _metadata_findings(records, mode == "strict")
|
|
336
|
+
failed = (
|
|
337
|
+
bool(probe_error)
|
|
338
|
+
or probes["summary"]["fail"] > 0
|
|
339
|
+
or any(item["level"] == "FAIL" for item in metadata)
|
|
340
|
+
)
|
|
341
|
+
return {
|
|
342
|
+
"status": "fail" if failed else "pass",
|
|
343
|
+
"source": f"index-v{version}",
|
|
344
|
+
"schema_version": version,
|
|
345
|
+
"probe_file": configured_path.as_posix(),
|
|
346
|
+
"probe_error": probe_error,
|
|
347
|
+
"index_error": None,
|
|
348
|
+
"metadata_mode": mode,
|
|
349
|
+
"metadata_findings": metadata,
|
|
350
|
+
"probes": probes,
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
|
|
354
|
+
def render_retrieval_health(payload: Dict) -> str:
|
|
355
|
+
probe_summary = payload["probes"]["summary"]
|
|
356
|
+
lines = [
|
|
357
|
+
"ADR selective-context health:",
|
|
358
|
+
f" status={payload['status']} source={payload.get('source') or 'unavailable'}",
|
|
359
|
+
(
|
|
360
|
+
" probes="
|
|
361
|
+
f"{probe_summary['pass']} pass/{probe_summary['fail']} fail/"
|
|
362
|
+
f"{probe_summary['total']} total"
|
|
363
|
+
),
|
|
364
|
+
(
|
|
365
|
+
" retrieval_metadata="
|
|
366
|
+
f"{len(payload.get('metadata_findings', []))} finding(s) "
|
|
367
|
+
f"[{payload.get('metadata_mode', 'advisory')}]"
|
|
368
|
+
),
|
|
369
|
+
]
|
|
370
|
+
if payload.get("index_error"):
|
|
371
|
+
lines.append(f" index_error={payload['index_error']}")
|
|
372
|
+
if payload.get("probe_error"):
|
|
373
|
+
lines.append(f" probe_error={payload['probe_error']}")
|
|
374
|
+
for result in payload["probes"]["results"]:
|
|
375
|
+
if result["status"] == "fail":
|
|
376
|
+
actual = ", ".join(
|
|
377
|
+
f"{item['adr_id']}({item['authority']})"
|
|
378
|
+
for item in result["actual"]
|
|
379
|
+
) or "none"
|
|
380
|
+
lines.append(
|
|
381
|
+
f" FAIL {result['id']}: query={result['query']!r}; "
|
|
382
|
+
f"missing={result['missing']}; unexpected={result['unexpected']}; "
|
|
383
|
+
f"actual={actual}"
|
|
384
|
+
)
|
|
385
|
+
return "\n".join(lines)
|