@rvdbreemen/adr-kit-opencode 0.58.0 → 0.59.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 +1 -1
- package/README.md +3 -3
- package/bin/adr +12 -1
- package/bin/adr-retire +86 -2
- package/bin/adr_doctor_checks.py +6 -1
- package/instructions/ADR-guide.md +1 -1
- package/package.json +1 -1
- package/scripts/release_phases.py +30 -6
- package/skills/lint/SKILL.md +18 -1
- package/templates/adr-kit-guide.md +1 -1
- package/templates/cc-settings/guardian-hook-entry.json +1 -1
- package/templates/githooks/pre-commit +1 -1
- package/templates/github-workflows/adr-readiness.yml +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "adr-kit",
|
|
3
3
|
"description": "Architecture Decision Record toolkit for AI coding agents: bootstrap, multi-format authoring, bounded deterministic enforcement, lifecycle workflows, context injection, generated graph indexes, and local health checks.",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.59.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Robert van den Breemen",
|
|
7
7
|
"url": "https://github.com/rvdbreemen"
|
package/README.md
CHANGED
|
@@ -314,7 +314,7 @@ For another project, use the published package:
|
|
|
314
314
|
```json
|
|
315
315
|
{
|
|
316
316
|
"$schema": "https://opencode.ai/config.json",
|
|
317
|
-
"plugin": ["@rvdbreemen/adr-kit-opencode@0.
|
|
317
|
+
"plugin": ["@rvdbreemen/adr-kit-opencode@0.59.0"]
|
|
318
318
|
}
|
|
319
319
|
```
|
|
320
320
|
|
|
@@ -673,7 +673,7 @@ jobs:
|
|
|
673
673
|
- uses: actions/checkout@v4
|
|
674
674
|
with:
|
|
675
675
|
fetch-depth: 0 # both sides of the diff must be available
|
|
676
|
-
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.
|
|
676
|
+
- uses: rvdbreemen/adr-kit/.github/actions/adr-judge@v0.59.0
|
|
677
677
|
with:
|
|
678
678
|
adr-dir: docs/adr/
|
|
679
679
|
```
|
|
@@ -687,7 +687,7 @@ The action also takes `max-diff-bytes` (default 32 MiB, available from the relea
|
|
|
687
687
|
```yaml
|
|
688
688
|
repos:
|
|
689
689
|
- repo: https://github.com/rvdbreemen/adr-kit
|
|
690
|
-
rev: v0.
|
|
690
|
+
rev: v0.59.0
|
|
691
691
|
hooks:
|
|
692
692
|
- id: adr-judge
|
|
693
693
|
```
|
package/bin/adr
CHANGED
|
@@ -137,8 +137,19 @@ def load_adr(path: Path) -> Tuple[Dict, str]:
|
|
|
137
137
|
|
|
138
138
|
|
|
139
139
|
def _atomic_write_text(path: Path, text: str) -> None:
|
|
140
|
-
"""Write one file through a unique same-directory temporary and replace.
|
|
140
|
+
"""Write one file through a unique same-directory temporary and replace.
|
|
141
|
+
|
|
142
|
+
An existing file keeps its line endings. Every reader here goes through
|
|
143
|
+
read_text, which turns CRLF into "\\n", so writing the text back as-is
|
|
144
|
+
rewrote a CRLF record as LF and made one answered question look like a
|
|
145
|
+
whole-file change on a Windows checkout (TASK-213).
|
|
146
|
+
"""
|
|
141
147
|
path.parent.mkdir(parents=True, exist_ok=True)
|
|
148
|
+
try:
|
|
149
|
+
if b"\r\n" in path.read_bytes()[:4096]:
|
|
150
|
+
text = text.replace("\r\n", "\n").replace("\n", "\r\n")
|
|
151
|
+
except OSError:
|
|
152
|
+
pass
|
|
142
153
|
temp_path: Path | None = None
|
|
143
154
|
try:
|
|
144
155
|
with tempfile.NamedTemporaryFile(
|
package/bin/adr-retire
CHANGED
|
@@ -20,7 +20,10 @@ import importlib.util
|
|
|
20
20
|
import json
|
|
21
21
|
import os
|
|
22
22
|
import re
|
|
23
|
+
import stat
|
|
24
|
+
import subprocess
|
|
23
25
|
import sys
|
|
26
|
+
import time
|
|
24
27
|
from datetime import date
|
|
25
28
|
from pathlib import Path
|
|
26
29
|
from typing import Dict, Iterable, List, Optional, Set, Tuple
|
|
@@ -61,6 +64,9 @@ from adr_format import section_text
|
|
|
61
64
|
|
|
62
65
|
# Safety cap for repo-wide file scans (tech-removal signal).
|
|
63
66
|
MAX_FILES = 50_000
|
|
67
|
+
# Bounds for the fallback walk outside git (TASK-212).
|
|
68
|
+
WALK_MAX_ENTRIES = 100_000
|
|
69
|
+
WALK_MAX_SECONDS = 10.0
|
|
64
70
|
|
|
65
71
|
JSON_FENCE_RE = re.compile(r"```json\s*\n(.*?)\n```", re.IGNORECASE | re.DOTALL)
|
|
66
72
|
STATUS_HISTORY_START_RE = re.compile(r"^\s*status_history\s*:\s*$", re.IGNORECASE)
|
|
@@ -189,17 +195,40 @@ def _walk_repo_files(repo_root: Path, extensions: set) -> List[Path]:
|
|
|
189
195
|
if cached is not None:
|
|
190
196
|
return cached
|
|
191
197
|
|
|
198
|
+
listed = _git_listed_files(repo_root, extensions)
|
|
199
|
+
if listed is not None:
|
|
200
|
+
_WALK_CACHE[cache_key] = listed
|
|
201
|
+
return listed
|
|
202
|
+
|
|
192
203
|
result: List[Path] = []
|
|
193
204
|
count = 0
|
|
205
|
+
visited = 0
|
|
206
|
+
deadline = time.monotonic() + WALK_MAX_SECONDS
|
|
194
207
|
skip_dirs = set(IGNORED_DIRS) | {"node_modules", ".tox"}
|
|
195
208
|
for dirpath, dirnames, filenames in os.walk(repo_root, followlinks=False):
|
|
196
|
-
# Prune ignored directories in-place so os.walk skips them
|
|
197
|
-
|
|
209
|
+
# Prune ignored directories in-place so os.walk skips them, and never
|
|
210
|
+
# follow a junction or directory symlink: os.walk(followlinks=False)
|
|
211
|
+
# still descends into Windows junctions (TASK-209, TASK-212).
|
|
212
|
+
dirnames[:] = [
|
|
213
|
+
d for d in dirnames
|
|
214
|
+
if d.lower() not in skip_dirs and not _is_dir_link(Path(dirpath) / d)
|
|
215
|
+
]
|
|
198
216
|
# Never descend into a nested checkout (git worktree, vendored clone):
|
|
199
217
|
# its files are not this project's source.
|
|
200
218
|
dirnames[:] = [
|
|
201
219
|
d for d in dirnames if not (Path(dirpath) / d / ".git").exists()
|
|
202
220
|
]
|
|
221
|
+
# The cap above counts files kept; these bound the walk itself, so a
|
|
222
|
+
# tree that is not a project still ends (TASK-212, as TASK-209 for lint).
|
|
223
|
+
visited += 1 + len(filenames)
|
|
224
|
+
if visited > WALK_MAX_ENTRIES or time.monotonic() > deadline:
|
|
225
|
+
import warnings
|
|
226
|
+
warnings.warn(
|
|
227
|
+
f"[adr-retire] File scan stopped after {visited} entries; "
|
|
228
|
+
f"run it from the project root."
|
|
229
|
+
)
|
|
230
|
+
_WALK_CACHE[cache_key] = result
|
|
231
|
+
return result
|
|
203
232
|
for fname in filenames:
|
|
204
233
|
if Path(fname).suffix.lower() in extensions:
|
|
205
234
|
result.append(Path(dirpath) / fname)
|
|
@@ -216,6 +245,61 @@ def _walk_repo_files(repo_root: Path, extensions: set) -> List[Path]:
|
|
|
216
245
|
return result
|
|
217
246
|
|
|
218
247
|
|
|
248
|
+
def _is_dir_link(path: Path) -> bool:
|
|
249
|
+
"""True for a directory symlink or a Windows junction (not other reparse points)."""
|
|
250
|
+
try:
|
|
251
|
+
st = os.lstat(path)
|
|
252
|
+
except OSError:
|
|
253
|
+
return True
|
|
254
|
+
if stat.S_ISLNK(st.st_mode):
|
|
255
|
+
return True
|
|
256
|
+
link_tags = {
|
|
257
|
+
getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", -1),
|
|
258
|
+
getattr(stat, "IO_REPARSE_TAG_SYMLINK", -1),
|
|
259
|
+
}
|
|
260
|
+
return getattr(st, "st_reparse_tag", 0) in link_tags
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def _git_listed_files(repo_root: Path, extensions) -> Optional[List[Path]]:
|
|
264
|
+
"""Tracked plus untracked-but-not-ignored files, or None outside a git repo.
|
|
265
|
+
|
|
266
|
+
What git ignores is not project source: build output, caches, generated
|
|
267
|
+
graphs. Walking it made this tool's cost depend on whatever a developer
|
|
268
|
+
machine had accumulated (graphify-out/, 67 MB, took a run from well under
|
|
269
|
+
a second to 3.3 s) and hid that from CI, where those folders do not exist
|
|
270
|
+
(TASK-212). git also never lists a nested checkout's files or follows a
|
|
271
|
+
link out of the tree.
|
|
272
|
+
"""
|
|
273
|
+
try:
|
|
274
|
+
proc = subprocess.run(
|
|
275
|
+
["git", "-C", str(repo_root), "ls-files", "-z", "--cached",
|
|
276
|
+
"--others", "--exclude-standard"],
|
|
277
|
+
capture_output=True,
|
|
278
|
+
stdin=subprocess.DEVNULL,
|
|
279
|
+
timeout=60,
|
|
280
|
+
)
|
|
281
|
+
except (OSError, subprocess.SubprocessError):
|
|
282
|
+
return None
|
|
283
|
+
if proc.returncode != 0:
|
|
284
|
+
return None
|
|
285
|
+
skip_dirs = set(IGNORED_DIRS) | {"node_modules", ".tox"}
|
|
286
|
+
files: List[Path] = []
|
|
287
|
+
for rel in proc.stdout.decode("utf-8", "replace").split("\0"):
|
|
288
|
+
if not rel or rel.endswith("/"):
|
|
289
|
+
continue
|
|
290
|
+
parts = rel.split("/")
|
|
291
|
+
if any(p.lower() in skip_dirs for p in parts[:-1]):
|
|
292
|
+
continue
|
|
293
|
+
if Path(rel).suffix.lower() not in extensions:
|
|
294
|
+
continue
|
|
295
|
+
path = repo_root / rel
|
|
296
|
+
if path.is_file():
|
|
297
|
+
files.append(path)
|
|
298
|
+
if len(files) >= MAX_FILES:
|
|
299
|
+
break
|
|
300
|
+
return files
|
|
301
|
+
|
|
302
|
+
|
|
219
303
|
def _source_files(repo_root: Path) -> Iterable[Path]:
|
|
220
304
|
return _walk_repo_files(repo_root, SOURCE_SUFFIXES)
|
|
221
305
|
|
package/bin/adr_doctor_checks.py
CHANGED
|
@@ -249,7 +249,12 @@ def _generated_check(plugin_root: Path, check_only: bool) -> tuple[dict, list[di
|
|
|
249
249
|
"generated-adapters", status="healthy",
|
|
250
250
|
summary="generated client artifacts match canonical inputs",
|
|
251
251
|
), []
|
|
252
|
-
|
|
252
|
+
# A git checkout is source: its adapters are regenerated by the build step
|
|
253
|
+
# a developer runs and commits. Repairing them here rewrote this
|
|
254
|
+
# repository's codex/ and copilot/ from every test that ran doctor in
|
|
255
|
+
# repair mode (TASK-213). Installed payloads are not checkouts and keep
|
|
256
|
+
# the repair.
|
|
257
|
+
if check_only or (plugin_root / ".git").exists():
|
|
253
258
|
return check(
|
|
254
259
|
"generated-adapters", status="stale",
|
|
255
260
|
summary="generated client artifacts drifted",
|
package/package.json
CHANGED
|
@@ -56,14 +56,38 @@ def preflight_done(ctx: Context) -> bool:
|
|
|
56
56
|
return False # cheap, and its answer can change between runs
|
|
57
57
|
|
|
58
58
|
|
|
59
|
+
def _dirty_paths() -> List[str]:
|
|
60
|
+
paths = []
|
|
61
|
+
for line in git("status", "--porcelain")[1].splitlines():
|
|
62
|
+
if len(line) > 3:
|
|
63
|
+
paths.append(line[3:].split(" -> ")[-1].strip().strip('"'))
|
|
64
|
+
return paths
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _release_owned(path: str) -> bool:
|
|
68
|
+
"""A file prepare writes: a declared version site or a generated client tree."""
|
|
69
|
+
registry = json.loads((ROOT / "packaging" / "version-sites.json").read_text(encoding="utf-8"))
|
|
70
|
+
sites = {site["path"] for site in registry.get("sites", [])}
|
|
71
|
+
return path in sites or path.startswith(("codex/", "copilot/"))
|
|
72
|
+
|
|
73
|
+
|
|
59
74
|
def preflight(ctx: Context) -> List[str]:
|
|
60
75
|
notes = []
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
)
|
|
76
|
+
dirty = _dirty_paths()
|
|
77
|
+
if dirty:
|
|
78
|
+
# prepare leaves its bump uncommitted on purpose and asks for a re-run;
|
|
79
|
+
# refusing that tree made the re-run impossible (TASK-213). Accept it
|
|
80
|
+
# only once the version is written and every change is prepare's own.
|
|
81
|
+
stray = [path for path in dirty if not _release_owned(path)]
|
|
82
|
+
if stray or not _version_everywhere(ctx):
|
|
83
|
+
listed = "".join(f"\n {path}" for path in stray)
|
|
84
|
+
raise ReleaseError(
|
|
85
|
+
"the working tree has uncommitted changes. Commit or stash them "
|
|
86
|
+
"first: a release commit must contain the version bump and "
|
|
87
|
+
"nothing that happened to be lying around."
|
|
88
|
+
+ (f"\nNot written by the release:{listed}" if listed else "")
|
|
89
|
+
)
|
|
90
|
+
notes.append(f"continuing a prepared release: {len(dirty)} release file(s) changed")
|
|
67
91
|
code, out, _ = script("check-branch-sync.py")
|
|
68
92
|
if code == 1:
|
|
69
93
|
raise ReleaseError(
|
package/skills/lint/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: lint
|
|
|
3
3
|
description: "Lint ADRs against schema and four verification gates. Use for ADR lint, validation, status-history checks, or file-and-line findings. Read-only."
|
|
4
4
|
argument-hint: "[file or directory; defaults to docs/adr/]"
|
|
5
5
|
disable-model-invocation: true
|
|
6
|
-
allowed-tools: [Read, Glob, Grep]
|
|
6
|
+
allowed-tools: [Read, Bash, Glob, Grep]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# adr-kit lint
|
|
@@ -13,6 +13,23 @@ is empty.
|
|
|
13
13
|
|
|
14
14
|
You are running `/adr-kit:lint`. The user wants to know whether existing ADRs in their project pass the four verification gates that the main `adr` skill enforces and, for v0.14 ADRs, whether their status histories are intact. You read files; you do not modify them. You report.
|
|
15
15
|
|
|
16
|
+
## Run the deterministic CLI first
|
|
17
|
+
|
|
18
|
+
The gates below are implemented by `bin/adr-lint`; run it and report what it
|
|
19
|
+
finds, rather than re-deriving every verdict by reading files:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1)
|
|
23
|
+
python "$ADR_KIT/bin/adr-lint" --format json docs/adr/
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Pass the argument path instead of `docs/adr/` when one was given. Exit 0 is
|
|
27
|
+
clean, 1 means findings, 2 is a configuration or input error: relay its
|
|
28
|
+
message and stop. Use the gate descriptions below to explain each finding
|
|
29
|
+
and to judge what the CLI leaves to judgment (the heuristic Evidence and
|
|
30
|
+
Clarity calls); when the CLI cannot run at all, fall back to reading the
|
|
31
|
+
files yourself and say that you did.
|
|
32
|
+
|
|
16
33
|
The deterministic CLI also returns read-only migration notices. Report them
|
|
17
34
|
even when every canonical ADR passes. A notice may contain an exact
|
|
18
35
|
`adr-migrate --dry-run` command for a supported legacy file or a guided
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- adr-kit-guide v0.
|
|
1
|
+
<!-- adr-kit-guide v0.59.0 -->
|
|
2
2
|
<!-- Canonical project-side ADR guide. Copied from the plugin's templates/adr-kit-guide.md to .claude/adr-kit-guide.md by /adr-kit:init, /adr-kit:upgrade, and /adr-kit:setup. -->
|
|
3
3
|
<!-- This file is plain markdown — readable by Claude Code, headless `claude -p`, shell scripts in pre-commit hooks, evaluator scripts, and any agent that doesn't process @-imports. Do not embed Claude-Code-specific syntax inside this file. -->
|
|
4
4
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"_comment": "ADR Guardian SessionStart hook entry for .claude/settings.json",
|
|
3
3
|
"_note": "Add this entry under hooks.SessionStart[0].hooks[] in the project's .claude/settings.json.",
|
|
4
4
|
"_remove_marker": "adr-guardian-session-start",
|
|
5
|
-
"_wrapper_version": "0.
|
|
5
|
+
"_wrapper_version": "0.59.0",
|
|
6
6
|
"type": "command",
|
|
7
7
|
"command": "ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ 2>/dev/null | sort -V | tail -1) && [ -n \"$ADR_KIT\" ] && _PY=$(command -v python3 || command -v python || command -v py) && [ -n \"$_PY\" ] && \"$_PY\" \"$ADR_KIT/bin/adr-guardian\" check 2>/dev/null || true",
|
|
8
8
|
"timeout": 10
|
|
@@ -52,7 +52,7 @@ set -e
|
|
|
52
52
|
# freezes at install time. adr-guardian compares this stamp against the
|
|
53
53
|
# installed plugin version and nudges /adr-kit:upgrade when the wrapper lags.
|
|
54
54
|
# Maintained by scripts/bump-version.py; do not edit by hand.
|
|
55
|
-
ADR_KIT_WRAPPER_VERSION="0.
|
|
55
|
+
ADR_KIT_WRAPPER_VERSION="0.59.0"
|
|
56
56
|
|
|
57
57
|
if [ "${ADR_KIT_HOOK_DISABLE:-0}" = "1" ]; then
|
|
58
58
|
echo "[adr-kit] hook disabled for this commit (ADR_KIT_HOOK_DISABLE=1)" >&2
|