pakem-cli 0.0.0-stage → 1.2.1

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.
Files changed (76) hide show
  1. package/CHANGELOG.md +271 -0
  2. package/LICENSE +21 -0
  3. package/README-ID.md +665 -0
  4. package/README.md +664 -2
  5. package/SKILL.md +264 -0
  6. package/adapters/git-worktree/v1/README.md +17 -0
  7. package/adapters/identity/v1/README.md +26 -0
  8. package/adapters/mcp/v1/README.md +56 -0
  9. package/adapters/storage-sqlite/v1/README.md +5 -0
  10. package/assets/banner.svg +275 -0
  11. package/assets/divider.svg +82 -0
  12. package/assets/footer.svg +174 -0
  13. package/assets/templates/BUG-HISTORY.md +18 -0
  14. package/assets/templates/CONTEXT.md +26 -0
  15. package/assets/templates/DECISIONS.md +8 -0
  16. package/assets/templates/MODULE-MAP.md +14 -0
  17. package/assets/templates/POLICY.json +15 -0
  18. package/assets/templates/PROJECT.md +42 -0
  19. package/conformance/v1/README.md +15 -0
  20. package/coordination/v1/README.md +14 -0
  21. package/coordination/v1/board.schema.json +59 -0
  22. package/coordination/v1/event.schema.json +26 -0
  23. package/coordination/v1/status.schema.json +49 -0
  24. package/evals/README.md +63 -0
  25. package/evals/evals.json +276 -0
  26. package/identity/v1/README.md +14 -0
  27. package/identity/v1/agent-identity.schema.json +95 -0
  28. package/identity/v1/identity-registry.schema.json +29 -0
  29. package/identity/v1/signed-payload.schema.json +42 -0
  30. package/intelligence/v1/README.md +19 -0
  31. package/intelligence/v1/dependency-graph.schema.json +82 -0
  32. package/intelligence/v1/impact-analysis.schema.json +51 -0
  33. package/intelligence/v1/reconciliation.schema.json +156 -0
  34. package/npm/bin/pakem.js +150 -0
  35. package/npm/check-version.js +26 -0
  36. package/package.json +55 -4
  37. package/policy/v1/README.md +15 -0
  38. package/policy/v1/policy.schema.json +20 -0
  39. package/protocol/v1/README.md +68 -0
  40. package/protocol/v1/capabilities.schema.json +17 -0
  41. package/protocol/v1/event.schema.json +114 -0
  42. package/protocol/v1/session.schema.json +51 -0
  43. package/references/artifacts.md +96 -0
  44. package/references/conventions.md +83 -0
  45. package/references/reviews.md +44 -0
  46. package/runtime/v1/README.md +21 -0
  47. package/runtime/v1/approval.schema.json +100 -0
  48. package/runtime/v1/checkpoint.schema.json +17 -0
  49. package/runtime/v1/hook-decision.schema.json +34 -0
  50. package/runtime/v1/hook-payload.schema.json +12 -0
  51. package/runtime/v1/task-evidence.schema.json +38 -0
  52. package/runtime/v1/work-report.schema.json +123 -0
  53. package/runtime/v1/workflow.schema.json +21 -0
  54. package/scripts/__pycache__/pakem.cpython-312.pyc +0 -0
  55. package/scripts/pakem.py +4911 -0
  56. package/scripts/pakem_core/__init__.py +3 -0
  57. package/scripts/pakem_core/__pycache__/__init__.cpython-312.pyc +0 -0
  58. package/scripts/pakem_core/__pycache__/coordination.cpython-312.pyc +0 -0
  59. package/scripts/pakem_core/__pycache__/git_worktree.cpython-312.pyc +0 -0
  60. package/scripts/pakem_core/__pycache__/identity.cpython-312.pyc +0 -0
  61. package/scripts/pakem_core/__pycache__/intelligence.cpython-312.pyc +0 -0
  62. package/scripts/pakem_core/__pycache__/mcp_server.cpython-312.pyc +0 -0
  63. package/scripts/pakem_core/__pycache__/protocol.cpython-312.pyc +0 -0
  64. package/scripts/pakem_core/__pycache__/reconcile.cpython-312.pyc +0 -0
  65. package/scripts/pakem_core/__pycache__/runtime.cpython-312.pyc +0 -0
  66. package/scripts/pakem_core/coordination.py +977 -0
  67. package/scripts/pakem_core/git_worktree.py +265 -0
  68. package/scripts/pakem_core/identity.py +494 -0
  69. package/scripts/pakem_core/intelligence.py +684 -0
  70. package/scripts/pakem_core/mcp_server.py +308 -0
  71. package/scripts/pakem_core/protocol.py +61 -0
  72. package/scripts/pakem_core/reconcile.py +119 -0
  73. package/scripts/pakem_core/runtime.py +457 -0
  74. package/scripts/run_evals.py +289 -0
  75. package/storage/v1/README.md +14 -0
  76. package/storage/v1/team-storage.schema.json +27 -0
@@ -0,0 +1,684 @@
1
+ """Project dependency discovery and change-impact analysis for Pakem.
2
+
3
+ This module is intentionally standard-library-only and has no dependency on the
4
+ CLI. It is a first reference implementation: edges are static, best-effort
5
+ signals, not proof of runtime reachability.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import ast
10
+ import json
11
+ import os
12
+ import re
13
+ import subprocess
14
+ from collections import defaultdict, deque
15
+ from pathlib import Path
16
+
17
+ SKIP_DIRS = {
18
+ ".git", ".hg", ".svn", ".pakem", "node_modules", "vendor", ".venv",
19
+ "venv", "__pycache__", "dist", "build", "target", ".next", ".nuxt",
20
+ ".turbo", ".cache", "coverage", "site-packages", ".tox",
21
+ }
22
+ CODE_EXTS = {
23
+ ".py", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".vue",
24
+ ".svelte", ".go", ".java", ".kt", ".rb", ".rs", ".php", ".cs",
25
+ }
26
+ TEST_DIRS = {"test", "tests", "__tests__", "spec", "specs"}
27
+ TEST_RE = re.compile(
28
+ r"(^test_.*\.py$|_test\.py$|_test\.go$|\.(test|spec)\.[cm]?[jt]sx?$|"
29
+ r"Tests?\.(java|kt|cs)$|_spec\.rb$)", re.I
30
+ )
31
+ JS_IMPORT_RE = re.compile(
32
+ r"(?:\bimport\s+(?:[^;\n]*?\s+from\s+)?|\bexport\s+[^;\n]*?\s+from\s+|"
33
+ r"\brequire\s*\(|\bimport\s*\()\s*[\"']([^\"']+)[\"']",
34
+ re.M,
35
+ )
36
+ GO_IMPORT_RE = re.compile(r"(?m)^\s*(?:import\s+)?\"([^\"]+)\"\s*$")
37
+ JAVA_IMPORT_RE = re.compile(r"(?m)^\s*import\s+(?:static\s+)?([\w.*]+)\s*;")
38
+
39
+ class NoChangesDetected(ValueError):
40
+ """No diff to analyse; an empty result, not a broken repo."""
41
+
42
+
43
+ def _relative(root: Path, path: Path) -> str:
44
+ return path.relative_to(root).as_posix()
45
+
46
+
47
+ def _is_test(path: Path) -> bool:
48
+ return any(part.lower() in TEST_DIRS for part in path.parts) or bool(TEST_RE.search(path.name))
49
+
50
+
51
+ def _language(path: Path) -> str:
52
+ return {
53
+ ".py": "python", ".js": "javascript", ".jsx": "javascript",
54
+ ".mjs": "javascript", ".cjs": "javascript", ".ts": "typescript",
55
+ ".tsx": "typescript", ".vue": "vue", ".svelte": "svelte",
56
+ ".go": "go", ".java": "java", ".kt": "kotlin", ".rb": "ruby",
57
+ ".rs": "rust", ".php": "php", ".cs": "csharp",
58
+ }.get(path.suffix.lower(), "unknown")
59
+
60
+
61
+ def _iter_files(root: Path, include_tests: bool = True):
62
+ for current, dirs, files in os.walk(root):
63
+ dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS and not d.startswith("."))
64
+ base = Path(current)
65
+ for name in sorted(files):
66
+ path = base / name
67
+ if path.suffix.lower() not in CODE_EXTS or (not include_tests and _is_test(path.relative_to(root))):
68
+ continue
69
+ try:
70
+ if path.is_symlink() or path.stat().st_size > 2_000_000:
71
+ continue
72
+ except OSError:
73
+ continue
74
+ yield path
75
+
76
+
77
+ def _strip_jsonc(text: str) -> str:
78
+ """Strip comments and trailing commas, because tsconfig is written as JSONC."""
79
+ out: list[str] = []
80
+ i, size = 0, len(text)
81
+ in_string = False
82
+ while i < size:
83
+ ch = text[i]
84
+ if in_string:
85
+ out.append(ch)
86
+ if ch == "\\" and i + 1 < size:
87
+ out.append(text[i + 1])
88
+ i += 2
89
+ continue
90
+ if ch == '"':
91
+ in_string = False
92
+ i += 1
93
+ continue
94
+ if ch == '"':
95
+ in_string = True
96
+ out.append(ch)
97
+ i += 1
98
+ continue
99
+ if text.startswith("//", i):
100
+ end = text.find("\n", i)
101
+ i = size if end < 0 else end
102
+ continue
103
+ if text.startswith("/*", i):
104
+ end = text.find("*/", i + 2)
105
+ i = size if end < 0 else end + 2
106
+ continue
107
+ out.append(ch)
108
+ i += 1
109
+ return re.sub(r",(\s*[}\]])", r"\1", "".join(out))
110
+
111
+
112
+ def _extends_candidates(base: Path, spec: str):
113
+ spec = spec.strip()
114
+ if not spec:
115
+ return
116
+ if spec.startswith((".", "/")):
117
+ target = (base / spec).resolve()
118
+ yield target if target.suffix else target.with_suffix(".json")
119
+ yield target / "tsconfig.json"
120
+ else:
121
+ package = base / "node_modules" / spec
122
+ yield package / "tsconfig.json"
123
+ if not spec.endswith(".json"):
124
+ yield package
125
+
126
+
127
+ def _tsconfig_options(path: Path, seen: set[Path] | None = None) -> dict:
128
+ """Merged compilerOptions: `extends` first, then the file itself."""
129
+ seen = set() if seen is None else seen
130
+ if path in seen or not path.is_file():
131
+ return {}
132
+ seen.add(path)
133
+ try:
134
+ data = json.loads(_strip_jsonc(path.read_text(encoding="utf-8", errors="replace")))
135
+ except (OSError, ValueError):
136
+ return {}
137
+ if not isinstance(data, dict):
138
+ return {}
139
+ merged: dict = {}
140
+ parents = data.get("extends")
141
+ parents = parents if isinstance(parents, list) else [parents] if isinstance(parents, str) else []
142
+ for parent in parents:
143
+ for candidate in _extends_candidates(path.parent, str(parent)):
144
+ if candidate.is_file():
145
+ merged.update(_tsconfig_options(candidate, seen))
146
+ break
147
+ options = data.get("compilerOptions")
148
+ if isinstance(options, dict):
149
+ merged.update(options)
150
+ return merged
151
+
152
+
153
+ def _js_config(root: Path) -> dict:
154
+ """Aliases and baseUrl from tsconfig/jsconfig, when present.
155
+
156
+ Without this, `@/lib/util` is read as a scoped npm package and every edge in
157
+ the TypeScript project disappears without a trace.
158
+ """
159
+ for name in ("tsconfig.json", "jsconfig.json"):
160
+ path = root / name
161
+ if not path.is_file():
162
+ continue
163
+ options = _tsconfig_options(path)
164
+ base_url = options.get("baseUrl")
165
+ base = ((root / str(base_url)).resolve() if isinstance(base_url, str) else root)
166
+ rules = []
167
+ paths = options.get("paths")
168
+ if isinstance(paths, dict):
169
+ for prefix, targets in paths.items():
170
+ if not isinstance(targets, list) or not prefix:
171
+ continue
172
+ rules.append({"prefix": str(prefix),
173
+ "targets": [str(t) for t in targets if isinstance(t, str)],
174
+ "source": name})
175
+ try:
176
+ base_rel = base.relative_to(root).as_posix() or "."
177
+ except ValueError:
178
+ base_rel = "."
179
+ return {"base": base, "base_rel": base_rel, "rules": rules, "source": name,
180
+ "has_base_url": isinstance(base_url, str)}
181
+ return {"base": root, "base_rel": ".", "rules": [], "source": None, "has_base_url": False}
182
+
183
+
184
+ def _js_candidates(root: Path, base: Path) -> list[str]:
185
+ try:
186
+ relbase = _relative(root, base)
187
+ except ValueError:
188
+ return []
189
+ if relbase in {"", "."}:
190
+ return []
191
+ candidates = [relbase]
192
+ if not Path(relbase).suffix:
193
+ candidates.extend(relbase + ext for ext in (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte", ".json"))
194
+ candidates.extend(f"{relbase}/index{ext}" for ext in (".ts", ".tsx", ".js", ".jsx", ".mjs"))
195
+ elif Path(relbase).suffix in {".js", ".jsx", ".mjs", ".cjs"}:
196
+ stem = str(Path(relbase).with_suffix(""))
197
+ candidates.extend(stem + ext for ext in (".ts", ".tsx", ".js", ".jsx"))
198
+ return candidates
199
+
200
+
201
+ def _alias_targets(specifier: str, rule: dict) -> list[str] | None:
202
+ prefix = rule["prefix"]
203
+ if prefix.endswith("*"):
204
+ head = prefix[:-1]
205
+ if not specifier.startswith(head):
206
+ return None
207
+ rest = specifier[len(head):]
208
+ return [target.replace("*", rest) for target in rule["targets"]]
209
+ if specifier == prefix:
210
+ return list(rule["targets"])
211
+ return None
212
+
213
+
214
+ def _resolve_js(root: Path, importer: Path, specifier: str, file_index: set[str],
215
+ config: dict | None = None) -> tuple[str | None, str | None]:
216
+ """Return (path, None) when resolved, or (None, reason) when not.
217
+
218
+ The reason is used by the caller to report missing imports instead of silently
219
+ dropping them as before.
220
+ """
221
+ config = config or {"base": root, "rules": [], "has_base_url": False}
222
+ if specifier.startswith("."):
223
+ for candidate in _js_candidates(root, (importer.parent / specifier).resolve()):
224
+ if candidate in file_index:
225
+ return candidate, None
226
+ return None, "relative"
227
+ matched = [(rule, targets) for rule in config["rules"]
228
+ for targets in [_alias_targets(specifier, rule)] if targets is not None]
229
+ matched.sort(key=lambda item: -len(item[0]["prefix"]))
230
+ for rule, targets in matched:
231
+ for target in targets:
232
+ for candidate in _js_candidates(root, (config["base"] / target).resolve()):
233
+ if candidate in file_index:
234
+ return candidate, None
235
+ return None, "alias"
236
+ if config.get("has_base_url"):
237
+ for candidate in _js_candidates(root, (config["base"] / specifier).resolve()):
238
+ if candidate in file_index:
239
+ return candidate, None
240
+ # Report only when the first segment points at a directory/file in the repo;
241
+ # everything else is a plain npm package and not the graph's business.
242
+ head = specifier.split("/", 1)[0]
243
+ if head and (root / head).exists():
244
+ return None, "baseUrl"
245
+ return None, None
246
+
247
+
248
+ def _python_imports(root: Path, path: Path, text: str, file_index: set[str]) -> set[str]:
249
+ try:
250
+ tree = ast.parse(text)
251
+ except (SyntaxError, ValueError):
252
+ return set()
253
+ found: set[str] = set()
254
+ for node in ast.walk(tree):
255
+ module = None
256
+ if isinstance(node, ast.Import):
257
+ for alias in node.names:
258
+ module = alias.name
259
+ _resolve_python_module(root, path, module, 0, file_index, found)
260
+ elif isinstance(node, ast.ImportFrom):
261
+ _resolve_python_module(root, path, node.module or "", node.level, file_index, found)
262
+ return found
263
+
264
+
265
+ def _resolve_python_module(root: Path, importer: Path, module: str, level: int,
266
+ file_index: set[str], found: set[str]):
267
+ parts = [p for p in module.split(".") if p]
268
+ bases: list[Path] = []
269
+ if level:
270
+ base = importer.parent
271
+ for _ in range(max(0, level - 1)):
272
+ base = base.parent
273
+ bases.append(base)
274
+ else:
275
+ bases.extend([root, root / "src", root / "app"])
276
+ for base in bases:
277
+ target = base.joinpath(*parts) if parts else base
278
+ try:
279
+ rel = _relative(root, target)
280
+ except ValueError:
281
+ continue
282
+ candidates = [rel + ".py", rel + "/__init__.py"]
283
+ if not parts:
284
+ candidates = [_relative(root, importer.parent / "__init__.py")]
285
+ for candidate in candidates:
286
+ if candidate in file_index and candidate != _relative(root, importer):
287
+ found.add(candidate)
288
+ return
289
+
290
+
291
+ def _circular_dependencies(nodes: list[str], edges: list[tuple[str, str]],
292
+ limit: int = 20) -> tuple[list[list[str]], int]:
293
+ """Strongly connected components (SCC) that contain a cycle.
294
+
295
+ Iterative so large repos do not hit the recursion limit. Returns a list of
296
+ components (each necessarily has a cycle) and the total count before truncation.
297
+ """
298
+ adjacency: dict[str, list[str]] = defaultdict(list)
299
+ for source, target in edges:
300
+ adjacency[source].append(target)
301
+ index: dict[str, int] = {}
302
+ low: dict[str, int] = {}
303
+ on_stack: set[str] = set()
304
+ stack: list[str] = []
305
+ components: list[list[str]] = []
306
+ counter = 0
307
+ for start in nodes:
308
+ if start in index:
309
+ continue
310
+ work: list[tuple[str, int]] = [(start, 0)]
311
+ while work:
312
+ node, position = work.pop()
313
+ if position == 0:
314
+ index[node] = low[node] = counter
315
+ counter += 1
316
+ stack.append(node)
317
+ on_stack.add(node)
318
+ neighbours = adjacency.get(node, [])
319
+ descended = False
320
+ for offset in range(position, len(neighbours)):
321
+ neighbour = neighbours[offset]
322
+ if neighbour not in index:
323
+ work.append((node, offset + 1))
324
+ work.append((neighbour, 0))
325
+ descended = True
326
+ break
327
+ if neighbour in on_stack:
328
+ low[node] = min(low[node], index[neighbour])
329
+ if descended:
330
+ continue
331
+ if low[node] == index[node]:
332
+ component = []
333
+ while True:
334
+ popped = stack.pop()
335
+ on_stack.discard(popped)
336
+ component.append(popped)
337
+ if popped == node:
338
+ break
339
+ if len(component) > 1 or node in adjacency.get(node, ()):
340
+ components.append(sorted(component))
341
+ if work:
342
+ parent = work[-1][0]
343
+ low[parent] = min(low[parent], low[node])
344
+ components.sort(key=lambda comp: (-len(comp), comp))
345
+ return components[:limit], len(components)
346
+
347
+
348
+ def build_dependency_graph(root: str | Path, include_tests: bool = True) -> dict:
349
+ """Build a best-effort, local-file dependency graph for a project."""
350
+ root = Path(root).resolve()
351
+ paths = list(_iter_files(root, include_tests=include_tests))
352
+ rels = sorted(_relative(root, p) for p in paths)
353
+ index = set(rels)
354
+ path_by_rel = {_relative(root, p): p for p in paths}
355
+ module_name = None
356
+ java_package_index: dict[str, list[str]] = defaultdict(list)
357
+ for candidate_rel, candidate_path in path_by_rel.items():
358
+ if candidate_path.suffix.lower() not in {".java", ".kt"}:
359
+ continue
360
+ try:
361
+ candidate_text = candidate_path.read_text(encoding="utf-8", errors="replace")
362
+ except OSError:
363
+ continue
364
+ package_match = re.search(r"(?m)^\s*package\s+([\w.]+)", candidate_text)
365
+ if package_match:
366
+ java_package_index[package_match.group(1)].append(candidate_rel)
367
+ go_mod = root / "go.mod"
368
+ if go_mod.is_file():
369
+ try:
370
+ go_mod_text = go_mod.read_text(encoding="utf-8", errors="replace")
371
+ except OSError:
372
+ go_mod_text = ""
373
+ m = re.search(r"(?m)^module\s+([^\s]+)", go_mod_text)
374
+ module_name = m.group(1) if m else None
375
+
376
+ nodes = []
377
+ edges = set()
378
+ unresolved: list[dict] = []
379
+ config = _js_config(root)
380
+ for rel in rels:
381
+ path = path_by_rel[rel]
382
+ try:
383
+ text = path.read_text(encoding="utf-8", errors="replace")
384
+ except OSError:
385
+ text = ""
386
+ local: set[str] = set()
387
+ suffix = path.suffix.lower()
388
+ if suffix == ".py":
389
+ local = _python_imports(root, path, text, index)
390
+ elif suffix in {".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".vue", ".svelte"}:
391
+ for spec in JS_IMPORT_RE.findall(text):
392
+ resolved, reason = _resolve_js(root, path, spec, index, config)
393
+ if resolved:
394
+ local.add(resolved)
395
+ elif reason:
396
+ unresolved.append({"from": rel, "specifier": spec, "reason": reason})
397
+ elif suffix == ".go" and module_name:
398
+ for spec in GO_IMPORT_RE.findall(text):
399
+ if spec.startswith(module_name + "/"):
400
+ tail = spec[len(module_name) + 1:]
401
+ # Go dependencies are package-level; connect to all local Go files in the package.
402
+ prefix = tail.rstrip("/") + "/"
403
+ matches = [item for item in rels if item.startswith(prefix) and item.endswith(".go")]
404
+ local.update(matches)
405
+ elif suffix in {".java", ".kt"}:
406
+ # Resolve the longest matching local package prefix without scanning
407
+ # every package for each import.
408
+ for imported in JAVA_IMPORT_RE.findall(text):
409
+ parts = imported.split(".")
410
+ for end in range(len(parts), 0, -1):
411
+ package_files = java_package_index.get(".".join(parts[:end]))
412
+ if package_files:
413
+ local.update(package_files)
414
+ break
415
+ for target in local:
416
+ if target != rel:
417
+ edges.add((rel, target))
418
+ try:
419
+ size_bytes = path.stat().st_size
420
+ except OSError:
421
+ size_bytes = 0
422
+ nodes.append({
423
+ "path": rel,
424
+ "language": _language(path),
425
+ "is_test": _is_test(Path(rel)),
426
+ "size_bytes": size_bytes,
427
+ "imports": sorted(local),
428
+ })
429
+
430
+ edge_list = [{"from": src, "to": dst} for src, dst in sorted(edges)]
431
+ ordered_unresolved = sorted(unresolved, key=lambda x: (x["from"], x["specifier"]))
432
+ cycles, cycle_count = _circular_dependencies([node["path"] for node in nodes],
433
+ [(edge["from"], edge["to"]) for edge in edge_list])
434
+ limitations = [
435
+ "Static best-effort analysis; dynamic imports, reflection, generated code, and runtime wiring may be missed.",
436
+ "Edges point from importer to imported local file.",
437
+ ]
438
+ if config["rules"]:
439
+ limitations.append(f"Aliases read from {config['source']} "
440
+ f"({len(config['rules'])} rules, baseUrl: {config['base_rel']}).")
441
+ elif config["source"]:
442
+ limitations.append(f"{config['source']} exists but does not declare `paths`; "
443
+ "non-relative imports are resolved only via baseUrl.")
444
+ return {
445
+ "schema_version": "pakem.dependency-graph/v1",
446
+ "root": ".",
447
+ "node_count": len(nodes),
448
+ "edge_count": len(edge_list),
449
+ "nodes": nodes,
450
+ "edges": edge_list,
451
+ "unresolved_relative_imports": [item for item in ordered_unresolved if item["reason"] == "relative"],
452
+ "unresolved_imports": ordered_unresolved,
453
+ "aliases": [{"prefix": rule["prefix"], "targets": rule["targets"], "source": rule["source"]}
454
+ for rule in config["rules"]],
455
+ "circular_dependencies": cycles,
456
+ "circular_dependency_count": cycle_count,
457
+ "limitations": limitations,
458
+ }
459
+
460
+
461
+ def _git_changed_files(root: Path, base: str | None = None, staged: bool = False) -> list[str]:
462
+ if base and staged:
463
+ raise ValueError("--base and --staged cannot be used together")
464
+ if base:
465
+ # `git diff REF` (without a range) compares REF against the working tree:
466
+ # commits since REF, uncommitted edits, and deleted files are all visible.
467
+ # `REF...HEAD` previously saw only commits and hid the working tree.
468
+ cmd = ["git", "diff", "--name-only", base]
469
+ elif staged:
470
+ cmd = ["git", "diff", "--cached", "--name-only"]
471
+ else:
472
+ cmd = ["git", "diff", "HEAD", "--name-only"]
473
+ try:
474
+ proc = subprocess.run(cmd, cwd=root, capture_output=True, text=True, timeout=15)
475
+ except (OSError, subprocess.TimeoutExpired) as exc:
476
+ raise ValueError(f"failed to read Git changes: {exc}") from exc
477
+ if proc.returncode:
478
+ raise ValueError("project is not a Git repository or REF is not valid; pass --files explicitly")
479
+ result = set(line.strip().replace("\\", "/") for line in proc.stdout.splitlines() if line.strip())
480
+ if not staged:
481
+ # New files have no entry in any diff yet; add them from status.
482
+ try:
483
+ extra = subprocess.run(["git", "ls-files", "--others", "--exclude-standard"], cwd=root,
484
+ capture_output=True, text=True, timeout=15)
485
+ if extra.returncode == 0:
486
+ result.update(line.strip().replace("\\", "/") for line in extra.stdout.splitlines() if line.strip())
487
+ except (OSError, subprocess.TimeoutExpired):
488
+ pass
489
+ return sorted(result)
490
+
491
+
492
+ def _normalize_changed(root: Path, files: list[str]) -> list[str]:
493
+ result = set()
494
+ for value in files:
495
+ raw = Path(value).expanduser()
496
+ full = (raw if raw.is_absolute() else root / raw).resolve()
497
+ try:
498
+ rel = full.relative_to(root).as_posix()
499
+ except ValueError as exc:
500
+ raise ValueError(f"changed path is outside the project root: {value}") from exc
501
+ if rel in {".", ".pakem"} or rel.startswith(".pakem/"):
502
+ continue
503
+ result.add(rel)
504
+ return sorted(result)
505
+
506
+
507
+ def analyze_impact(root: str | Path, changed_files: list[str], graph: dict | None = None) -> dict:
508
+ """Analyze reverse dependency reach and tests affected by changed files."""
509
+ root = Path(root).resolve()
510
+ changed = _normalize_changed(root, changed_files)
511
+ graph = graph or build_dependency_graph(root)
512
+ nodes = {n["path"]: n for n in graph.get("nodes", [])}
513
+ reverse: dict[str, set[str]] = defaultdict(set)
514
+ for edge in graph.get("edges", []):
515
+ reverse[edge["to"]].add(edge["from"])
516
+
517
+ direct: set[str] = set()
518
+ transitive: set[str] = set()
519
+ queue = deque((item, 1) for item in changed if item in nodes)
520
+ seen = set(changed)
521
+ while queue:
522
+ target, depth = queue.popleft()
523
+ for dependent in sorted(reverse.get(target, ())):
524
+ if dependent in seen:
525
+ continue
526
+ seen.add(dependent)
527
+ (direct if depth == 1 else transitive).add(dependent)
528
+ queue.append((dependent, depth + 1))
529
+
530
+ impacted = direct | transitive
531
+ affected_tests = {p for p in impacted if nodes.get(p, {}).get("is_test")}
532
+ changed_tests = {p for p in changed if nodes.get(p, {}).get("is_test")}
533
+ affected_tests.update(changed_tests)
534
+ # A same-stem test is a useful fallback when imports are not explicit.
535
+ changed_stems = {Path(p).stem.removeprefix("test_").removesuffix(".test").removesuffix(".spec") for p in changed}
536
+ for rel, item in nodes.items():
537
+ if item.get("is_test") and any(stem and stem in Path(rel).stem for stem in changed_stems):
538
+ affected_tests.add(rel)
539
+
540
+ sensitive = re.compile(r"(^|[/_.-])(auth|security|crypto|payment|billing|secret|permission|policy|migration|schema)([/_.-]|$)", re.I)
541
+ critical_names = {name.lower() for name in {
542
+ "package.json", "pyproject.toml", "Cargo.toml", "go.mod", "composer.json", "Gemfile",
543
+ "Dockerfile", "docker-compose.yml", "Makefile", "tox.ini", "pytest.ini",
544
+ }}
545
+ dependency_lock_names = {
546
+ "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb",
547
+ "requirements.txt", "requirements.lock", "poetry.lock", "uv.lock", "Pipfile.lock",
548
+ "go.sum", "Cargo.lock", "composer.lock", "Gemfile.lock",
549
+ }
550
+ reasons = []
551
+ score = 0
552
+ for rel in changed:
553
+ lower = rel.lower()
554
+ if sensitive.search(lower):
555
+ score += 4
556
+ reasons.append(f"{rel}: path name indicates a sensitive area")
557
+ if Path(lower).name in critical_names or lower.startswith(".github/workflows/"):
558
+ score += 3
559
+ reasons.append(f"{rel}: configuration/build/deployment file with broad impact")
560
+ if Path(lower).name in {name.lower() for name in dependency_lock_names}:
561
+ score += 2
562
+ reasons.append(f"{rel}: dependency/lockfile change needs compatibility verification")
563
+ if Path(lower).name == ".env" or Path(lower).name.startswith(".env.") or lower.endswith((".pem", ".key")):
564
+ score += 4
565
+ reasons.append(f"{rel}: environment file or key material requires security review")
566
+ if lower.endswith((".sql",)) or "/migrations/" in lower:
567
+ score += 3
568
+ reasons.append(f"{rel}: database/migration change requires focused review")
569
+ if len(impacted) >= 10:
570
+ score += 2
571
+ reasons.append(f"{len(impacted)} dependent files reachable from the change")
572
+ if len(changed) >= 8:
573
+ score += 1
574
+ reasons.append("changed file count is relatively large")
575
+ unresolved = graph.get("unresolved_imports", graph.get("unresolved_relative_imports", [])) or []
576
+ cycles = graph.get("circular_dependencies", []) or []
577
+ changed_in_cycle = [rel for rel in changed if any(rel in component for component in cycles)]
578
+ if changed_in_cycle:
579
+ reasons.append("changed files are in a dependency cycle: " + ", ".join(changed_in_cycle[:3]))
580
+ level = "high" if score >= 4 else "medium" if score >= 2 else "low"
581
+
582
+ recommendations = ["Run the relevant tests before full verification."]
583
+ if affected_tests:
584
+ recommendations.insert(0, "Prioritize tests: " + ", ".join(sorted(affected_tests)))
585
+ else:
586
+ recommendations.insert(0, "No related tests detected; decide the appropriate manual verification.")
587
+ if level == "high":
588
+ recommendations.append("Request additional review for affected security, data, or configuration.")
589
+ if impacted:
590
+ recommendations.append("Review compatibility on direct and transitive dependents.")
591
+ if unresolved:
592
+ recommendations.append(
593
+ f"Graph has {len(unresolved)} unresolved imports (alias/baseUrl/relative); "
594
+ "dependents may go undetected — check tsconfig/jsconfig or verify manually.")
595
+
596
+ return {
597
+ "schema_version": "pakem.impact-analysis/v1",
598
+ "changed_files": changed,
599
+ "direct_dependents": sorted(direct),
600
+ "transitive_dependents": sorted(transitive),
601
+ "affected_tests": sorted(affected_tests),
602
+ "risk": {"level": level, "score": score, "reasons": reasons},
603
+ "summary": {
604
+ "changed_count": len(changed), "direct_dependent_count": len(direct),
605
+ "transitive_dependent_count": len(transitive), "affected_test_count": len(affected_tests),
606
+ },
607
+ "graph_health": {
608
+ "alias_rules": len(graph.get("aliases", []) or []),
609
+ "unresolved_imports": len(unresolved),
610
+ "circular_dependencies": int(graph.get("circular_dependency_count") or len(cycles)),
611
+ "complete": not unresolved,
612
+ },
613
+ "recommendations": recommendations,
614
+ "analysis_limits": [
615
+ "Impact is inferred from static local imports and filename heuristics; verify the result against actual architecture.",
616
+ "A missing edge does not prove that a file is unaffected.",
617
+ ],
618
+ }
619
+
620
+
621
+ def changed_files_for_impact(root: str | Path, files: list[str] | None = None,
622
+ base: str | None = None, staged: bool = False) -> list[str]:
623
+ root = Path(root).resolve()
624
+ if files and (base or staged):
625
+ raise ValueError("use exactly one of --files, --base, or --staged")
626
+ if files:
627
+ return _normalize_changed(root, files)
628
+ detected = _git_changed_files(root, base=base, staged=staged)
629
+ if not detected:
630
+ raise NoChangesDetected("no changes detected; use --files FILE... to specify files")
631
+ return _normalize_changed(root, detected)
632
+
633
+
634
+ def render_graph_text(graph: dict) -> str:
635
+ lines = [f"Dependency Graph: {graph['node_count']} nodes, {graph['edge_count']} edges", ""]
636
+ incoming: dict[str, list[str]] = defaultdict(list)
637
+ for edge in graph.get("edges", []):
638
+ incoming[edge["to"]].append(edge["from"])
639
+ for node in graph.get("nodes", []):
640
+ suffix = " [test]" if node.get("is_test") else ""
641
+ lines.append(f"{node['path']} ({node['language']}){suffix}")
642
+ consumers = sorted(incoming.get(node["path"], []))
643
+ if consumers:
644
+ lines.append(" used by: " + ", ".join(consumers))
645
+ aliases = graph.get("aliases", [])
646
+ if aliases:
647
+ lines.extend(["", f"Aliases ({len(aliases)}):"])
648
+ lines.extend(f" {rule['prefix']} -> {', '.join(rule['targets'])}" for rule in aliases[:10])
649
+ unresolved = graph.get("unresolved_imports", graph.get("unresolved_relative_imports", []))
650
+ if unresolved:
651
+ lines.extend(["", f"Unresolved imports: {len(unresolved)}"])
652
+ lines.extend(f" {x['from']} -> {x['specifier']} ({x.get('reason', 'relative')})"
653
+ for x in unresolved[:20])
654
+ cycles = graph.get("circular_dependencies", [])
655
+ if cycles:
656
+ total = graph.get("circular_dependency_count", len(cycles))
657
+ lines.extend(["", f"Circular dependencies: {total}"])
658
+ for component in cycles[:5]:
659
+ shown = ", ".join(component[:6]) + (" ..." if len(component) > 6 else "")
660
+ lines.append(f" {shown}")
661
+ lines.extend(["", "Note: static best-effort graph; validate important paths manually."])
662
+ return "\n".join(lines)
663
+
664
+
665
+ def render_impact_text(result: dict) -> str:
666
+ lines = [f"Impact Analysis: {result['risk']['level'].upper()} risk (score {result['risk']['score']})", ""]
667
+ for label, key in (("Changed", "changed_files"), ("Direct dependents", "direct_dependents"),
668
+ ("Transitive dependents", "transitive_dependents"), ("Affected tests", "affected_tests")):
669
+ lines.append(f"{label} ({len(result[key])}):")
670
+ lines.extend(" - " + item for item in result[key])
671
+ if not result[key]:
672
+ lines.append(" - (none detected)")
673
+ if result["risk"]["reasons"]:
674
+ lines.extend(["", "Risk signals:"])
675
+ lines.extend(" - " + reason for reason in result["risk"]["reasons"])
676
+ lines.extend(["", "Recommendations:"])
677
+ lines.extend(" - " + item for item in result["recommendations"])
678
+ health = result.get("graph_health")
679
+ if health:
680
+ state = "complete" if health.get("complete") else f"{health.get('unresolved_imports')} unresolved imports"
681
+ lines.extend(["", f"Graph: {state}, {health.get('alias_rules', 0)} aliases, "
682
+ f"{health.get('circular_dependencies', 0)} cycles."])
683
+ lines.extend(["", "Static analysis is advisory; a missing edge does not prove no impact."])
684
+ return "\n".join(lines)