@rvdbreemen/adr-kit-opencode 0.57.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/bin/adr-lint CHANGED
@@ -39,8 +39,10 @@ import json
39
39
  import os
40
40
  import re
41
41
  import shutil
42
+ import stat
42
43
  import subprocess
43
44
  import sys
45
+ import time
44
46
  from datetime import date
45
47
  from pathlib import Path
46
48
  from typing import Dict, Iterable, List, Optional, Set, Tuple
@@ -256,9 +258,17 @@ TEXT_SCAN_SKIP_DIRS = {
256
258
  "__pycache__",
257
259
  "backlog",
258
260
  "docs",
261
+ "graphify-out",
259
262
  "node_modules",
260
263
  "vendor",
261
264
  }
265
+ # Budgets for the gate scan. A repo root that is not a project root (an
266
+ # unexpected cwd, a junction into a share) must end in a "not verified"
267
+ # finding, not in a walk that runs for a day.
268
+ GATE_SCAN_MAX_FILES = 5000
269
+ GATE_SCAN_MAX_ENTRIES = 100_000
270
+ GATE_SCAN_MAX_SECONDS = 10.0
271
+ GATE_SCAN_MAX_FILE_BYTES = 1024 * 1024
262
272
 
263
273
 
264
274
  class PolicyError(Exception):
@@ -998,6 +1008,7 @@ def _verified_pointer_resolves(pointer: str, repo_root: Path) -> bool:
998
1008
  result = subprocess.run(
999
1009
  ["git", "-C", str(repo_root), "cat-file", "-e", f"{commit}^{{commit}}"],
1000
1010
  capture_output=True,
1011
+ stdin=subprocess.DEVNULL,
1001
1012
  text=True,
1002
1013
  timeout=5,
1003
1014
  )
@@ -1021,45 +1032,99 @@ def _verified_pointer_resolves(pointer: str, repo_root: Path) -> bool:
1021
1032
  return False
1022
1033
 
1023
1034
 
1024
- def _iter_gate_scan_files(repo_root: Path):
1025
- count = 0
1035
+ def _is_dir_link(path: Path) -> bool:
1036
+ """True for a symlinked directory or a Windows junction.
1037
+
1038
+ os.walk(followlinks=False) only skips what os.path.islink reports, and a
1039
+ junction is not a symlink to it: a junction back into the tree was walked
1040
+ until the path limit, and one into a network share blocked on its reads.
1041
+ """
1042
+ try:
1043
+ st = os.lstat(path)
1044
+ except OSError:
1045
+ return True
1046
+ if stat.S_ISLNK(st.st_mode):
1047
+ return True
1048
+ # Only junctions and symlinks: OneDrive placeholders and dedup volumes
1049
+ # are reparse points too, and their contents are this project's own.
1050
+ link_tags = {
1051
+ getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", -1),
1052
+ getattr(stat, "IO_REPARSE_TAG_SYMLINK", -1),
1053
+ }
1054
+ return getattr(st, "st_reparse_tag", 0) in link_tags
1055
+
1056
+
1057
+ def _iter_gate_scan_files(repo_root: Path, stopped: Optional[List[str]] = None):
1058
+ """Yield the files a gate name may appear in, within fixed budgets.
1059
+
1060
+ Every budget counts what the walk costs, not only what it yields: the old
1061
+ 5000-file cap counted yielded files, so directories and skipped files were
1062
+ unbounded. When a budget runs out the reason is appended to `stopped`.
1063
+ """
1064
+ def stop(reason: str) -> None:
1065
+ if stopped is not None:
1066
+ stopped.append(reason)
1067
+
1068
+ deadline = time.monotonic() + GATE_SCAN_MAX_SECONDS
1069
+ visited = 0
1070
+ yielded = 0
1026
1071
  for dirpath, dirnames, filenames in os.walk(repo_root, followlinks=False):
1072
+ current = Path(dirpath)
1027
1073
  dirnames[:] = [
1028
1074
  d for d in dirnames
1029
1075
  if d not in TEXT_SCAN_SKIP_DIRS and d.lower() not in TEXT_SCAN_SKIP_DIRS
1076
+ and not _is_dir_link(current / d)
1030
1077
  ]
1031
1078
  # Never descend into a nested checkout (git worktree, vendored clone):
1032
1079
  # its files belong to another tree, not to this project's source.
1033
1080
  dirnames[:] = [
1034
- d for d in dirnames if not (Path(dirpath) / d / ".git").exists()
1081
+ d for d in dirnames if not (current / d / ".git").exists()
1035
1082
  ]
1036
- current = Path(dirpath)
1037
1083
  try:
1038
1084
  rel_first = current.relative_to(repo_root).parts[:1]
1039
1085
  except ValueError:
1040
1086
  rel_first = ()
1041
1087
  preferred_dir = bool(rel_first and rel_first[0] in TEXT_SCAN_DIRS)
1088
+ visited += 1 + len(filenames)
1089
+ if visited > GATE_SCAN_MAX_ENTRIES:
1090
+ stop(f"scan stopped after {GATE_SCAN_MAX_ENTRIES} entries")
1091
+ return
1092
+ if time.monotonic() >= deadline:
1093
+ stop(f"scan stopped after {GATE_SCAN_MAX_SECONDS:g} seconds")
1094
+ return
1042
1095
  for fname in filenames:
1043
1096
  path = current / fname
1044
- if fname == "evaluate.py" or preferred_dir or path.suffix.lower() in TEXT_SCAN_SUFFIXES:
1045
- yield path
1046
- count += 1
1047
- if count >= 5000:
1048
- return
1097
+ if not (fname == "evaluate.py" or preferred_dir or path.suffix.lower() in TEXT_SCAN_SUFFIXES):
1098
+ continue
1099
+ try:
1100
+ if path.stat().st_size > GATE_SCAN_MAX_FILE_BYTES:
1101
+ continue
1102
+ except OSError:
1103
+ continue
1104
+ yield path
1105
+ yielded += 1
1106
+ if yielded >= GATE_SCAN_MAX_FILES:
1107
+ stop(f"scan stopped after reading {GATE_SCAN_MAX_FILES} files")
1108
+ return
1049
1109
 
1050
1110
 
1051
- def _resolve_gates_locally(gates: Iterable[str], repo_root: Path) -> Set[str]:
1052
- """Return the subset of `gates` that appear somewhere under repo_root.
1111
+ def _scan_gates(
1112
+ gates: Iterable[str], repo_root: Path
1113
+ ) -> Tuple[Set[str], Optional[str]]:
1114
+ """Return the gates found under repo_root, and why the scan stopped early.
1053
1115
 
1054
1116
  One pass over the scan set regardless of how many gates are checked. The
1055
1117
  previous per-gate helper re-walked and re-read the whole tree for every
1056
- gate, making lint runtime O(gates x files).
1118
+ gate, making lint runtime O(gates x files). The second value is None when
1119
+ the scan was complete, so a gate absent from the first value is missing;
1120
+ otherwise it names the budget that ran out and absence proves nothing.
1057
1121
  """
1058
1122
  pending = {g.strip() for g in gates if g and g.strip()}
1059
1123
  found: Set[str] = set()
1060
1124
  if not pending:
1061
- return found
1062
- for path in _iter_gate_scan_files(repo_root):
1125
+ return found, None
1126
+ stopped: List[str] = []
1127
+ for path in _iter_gate_scan_files(repo_root, stopped):
1063
1128
  try:
1064
1129
  text = path.read_text(encoding="utf-8", errors="ignore")
1065
1130
  except OSError:
@@ -1069,8 +1134,13 @@ def _resolve_gates_locally(gates: Iterable[str], repo_root: Path) -> Set[str]:
1069
1134
  found |= hits
1070
1135
  pending -= hits
1071
1136
  if not pending:
1072
- break
1073
- return found
1137
+ return found, None
1138
+ return found, (stopped[0] if stopped else None)
1139
+
1140
+
1141
+ def _resolve_gates_locally(gates: Iterable[str], repo_root: Path) -> Set[str]:
1142
+ """Return the subset of `gates` that appear somewhere under repo_root."""
1143
+ return _scan_gates(gates, repo_root)[0]
1074
1144
 
1075
1145
 
1076
1146
  def _gate_exists_locally(gate: str, repo_root: Path) -> bool:
@@ -1121,7 +1191,7 @@ def detect_frontmatter_consistency(
1121
1191
  and record["data"].get("binding") is True
1122
1192
  and record["data"].get("gate")
1123
1193
  }
1124
- present_gates = _resolve_gates_locally(_wanted_gates, repo_root)
1194
+ present_gates, gate_scan_stopped = _scan_gates(_wanted_gates, repo_root)
1125
1195
 
1126
1196
  for adr_id, record in reported.items():
1127
1197
  data = record["data"]
@@ -1177,7 +1247,14 @@ def detect_frontmatter_consistency(
1177
1247
  if not gate:
1178
1248
  add(record, "Accepted binding ADR requires a named gate")
1179
1249
  elif str(gate).strip() not in present_gates:
1180
- add(record, f"gate {gate!r} was not found under {repo_root}")
1250
+ if gate_scan_stopped:
1251
+ add(
1252
+ record,
1253
+ f"gate {gate!r} could not be verified under {repo_root}: "
1254
+ f"{gate_scan_stopped}; pass --repo-root the project root",
1255
+ )
1256
+ else:
1257
+ add(record, f"gate {gate!r} was not found under {repo_root}")
1181
1258
 
1182
1259
  return issues
1183
1260
 
@@ -1330,6 +1407,7 @@ def _previous_revision(path: Path) -> Optional[str]:
1330
1407
  ["git", "show", f"HEAD:./{path.name}"],
1331
1408
  cwd=str(path.parent),
1332
1409
  capture_output=True,
1410
+ stdin=subprocess.DEVNULL,
1333
1411
  text=True,
1334
1412
  encoding="utf-8",
1335
1413
  errors="replace",
package/bin/adr-migrate CHANGED
@@ -59,10 +59,12 @@ from adr_format import (
59
59
  AdrFormatError,
60
60
  classify_format,
61
61
  convert_profile,
62
+ has_role_heading,
63
+ heading,
62
64
  is_migration_candidate,
63
65
  migration_notice,
64
66
  normalize_profile,
65
- unfilled_required_sections,
67
+ unfilled_required_roles,
66
68
  )
67
69
  from adr_schema import migrate_text
68
70
  from adr_catalog import load_adr_record
@@ -168,6 +170,7 @@ def migrate_file(
168
170
  after, changed, issues = migrate_text(before, path)
169
171
  detected_source = None
170
172
  unfilled: List[str] = []
173
+ machine_written: List[str] = []
171
174
  if not issues and to_profile is not None:
172
175
  try:
173
176
  after, detected_source = convert_profile(
@@ -178,12 +181,23 @@ def migrate_file(
178
181
  # into it. That is a hole, not content, and saying nothing about it
179
182
  # is how a migrated record reaches `adr accept` still unwritten.
180
183
  # Report only what THIS run left unfilled, so a hole the author
181
- # already had is not blamed on the migration.
184
+ # already had is not blamed on the migration. Compare roles, each
185
+ # side read in its own profile: across profiles the same role has
186
+ # a different title (TASK-201).
187
+ already = set(unfilled_required_roles(before, detected_source))
182
188
  unfilled = [
183
- s
184
- for s in unfilled_required_sections(after, to_profile)
185
- if s not in unfilled_required_sections(before, to_profile)
189
+ heading(to_profile, role)
190
+ for role in unfilled_required_roles(after, to_profile)
191
+ if role not in already
186
192
  ]
193
+ # The conversion writes "- None." into a Related Decisions section
194
+ # it had to add. That is real content to every detector, by
195
+ # design, but nobody answered it: the author never saw the
196
+ # section. Name it for review rather than as a hole (TASK-202).
197
+ if not has_role_heading(
198
+ before, detected_source, "related"
199
+ ) and has_role_heading(after, to_profile, "related"):
200
+ machine_written.append(heading(to_profile, "related"))
187
201
  except AdrFormatError as exc:
188
202
  issues = [str(exc)]
189
203
  if not issues and changed and write:
@@ -205,6 +219,7 @@ def migrate_file(
205
219
  "source_profile": detected_source,
206
220
  "target_profile": to_profile,
207
221
  "unfilled_sections": unfilled,
222
+ "machine_written_sections": machine_written,
208
223
  }
209
224
 
210
225
 
@@ -228,6 +243,11 @@ def render_text(target: Path, results: List[Dict], check: bool, dry_run: bool) -
228
243
  for section in result.get("unfilled_sections") or []:
229
244
  unfilled_any = True
230
245
  lines.append(f" needs content: ## {section}")
246
+ for section in result.get("machine_written_sections") or []:
247
+ lines.append(
248
+ f" review: ## {section} (written as '- None.' by the "
249
+ f"migration; confirm it, or name the related ADRs)"
250
+ )
231
251
  if result["issues"]:
232
252
  lines.append(f" failed: {result['file']}")
233
253
  for issue in result["issues"]:
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
- dirnames[:] = [d for d in dirnames if d.lower() not in skip_dirs]
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