ts-reviewer 2.1.0 → 3.0.0

package/README.md

@@ -10,7 +10,7 @@ Three modes, one skill:
 
 | Mode | What happens |
 |---|---|
-| **scan** | Analyzes the codebase and writes a prioritized report to `code-smells.md` |
+| **scan** | Analyzes the codebase and writes a prioritized report to `code-smells/report.md` |
 | **fix** | Reads the report and applies fixes file-by-file with tsc/lint/test verification |
 | **auto** | Runs scan, asks you to confirm, fixes everything, deletes the report if clean |
 
@@ -81,7 +81,8 @@ Find issues in this project
 Audit the codebase for security and type safety problems
 ```
 
-Claude will analyze the project and write a report to `code-smells.md` in the project root.
+Claude will analyze the project and write a report to `code-smells/report.md` in the project root.
+With Architecture active, the same directory also holds project discovery, Knip, graph, metric, co-change, rule, and Mermaid artifacts.
 
 #### Domain flags
 
@@ -114,7 +115,7 @@ After reviewing the scan report, ask Claude to fix the issues:
 Fix the issues from the report
 ```
 ```
-Apply fixes from code-smells.md
+Apply fixes from code-smells/report.md
 ```
 
 The fix workflow:
@@ -124,7 +125,7 @@ The fix workflow:
 4. Runs linter, fixes lint errors
 5. Runs full test suite, compares with baseline, fixes any regressions it caused
 6. Repeats verification up to 5 iterations
-7. Updates the report: if all fixed → deletes `code-smells.md`; if some remain → keeps it as an audit trail with BEFORE/AFTER diffs for every fix
+7. Updates the report: if all fixed → deletes `code-smells/report.md`; if some remain → keeps it as an audit trail with BEFORE/AFTER diffs for every fix
 
 **Important:** fix never commits or stages anything. You review the changes and decide what to keep.
 
@@ -238,29 +239,30 @@ The test catches a check line that lost its severity, a block the profile does n
 
 ### Scan mode
 
-1. **Discovery** — detects domain flags, maps the project, reads tsconfig.json, detects linter and test runner. If architecture is active, also maps module relationships and checks for `docs/adr/`.
+1. **Discovery** — detects domain flags, maps the project, reads tsconfig.json, detects linter and test runner, and asks once before downloading a missing architecture tool.
 2. **Diagnostics** — runs `tsc --noEmit`, linter, and LSP diagnostics (if available)
-3. **Analysis** — specialized passes for each active domain (sub-agents in Claude Code, sequential in Claude.ai), each with its own checklist. Every finding passes an Evidence Protocol: verified against the actual file content, confidence-gated, version-gated against the project's TS/runtime.
-4. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, enforces a noise budget, writes `code-smells.md`. Architecture findings appear in a separate `## Architecture Opportunities` section at the end.
+3. **Architecture pre-pass** — when active, writes bounded Knip, graph, metric, co-change, rule, and Mermaid artifacts under `code-smells/`.
+4. **Analysis** — specialized passes judge the candidates against the active checklists; tool output is never a finding by itself.
+5. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, enforces a noise budget, writes `code-smells/report.md`. Architecture findings appear in a separate `## Architecture Opportunities` section at the end.
 
 ### Fix mode
 
-1. Parses `code-smells.md` as the work plan
+1. Parses `code-smells/report.md` as the work plan
 2. Captures test baseline (runs tests before changes)
 3. Applies fixes bottom-to-top within each file (so line numbers don't shift)
 4. Writes regression tests for each testable fix
 5. Runs `tsc --noEmit` after each file
 6. Full verification loop: tsc + linter + test suite (max 5 iterations)
 7. Compares test results with baseline — only fixes regressions it caused
-8. Updates or deletes the report
+8. Updates or deletes the report, keeps the remaining `code-smells/` artifacts, and asks before removing them
 
 ## Tips
 
-- **Add `code-smells.md` to `.gitignore`** — it's a review artifact, not part of your source code.
+- **Add `code-smells/` to `.gitignore`** — it contains review artifacts, not source code.
 
 - **Commit before running fix** — so you can `git diff` to review changes and `git checkout -- .` to revert if needed.
 
-- **Edit the report before fix** — since fix uses `code-smells.md` as its work plan, you can delete issues you don't want fixed, change severities, or add notes before running fix.
+- **Edit the report before fix** — since fix uses `code-smells/report.md` as its work plan, you can delete issues you don't want fixed, change severities, or add notes before running fix.
 
 - **Scoped review for PRs** — `"review my branch against main"` is the most practical mode for day-to-day use. Full codebase audits are better suited for periodic health checks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-reviewer",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Install the TypeScript Code Reviewer skill for Claude Code, Codex, or Antigravity",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,7 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build && npm test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run typecheck && node --test cnlp/skill-format.test.js",
+    "test": "npm run typecheck && node --test cnlp/skill-format.test.js tools.test.mjs",
     "dev": "npm run build && node --enable-source-maps dist/cli.js"
   },
   "keywords": [

package/ts-reviewer/SKILL.md

@@ -28,13 +28,15 @@ inputs:
 - the reference checklists under `references/`
 
 preconditions:
-- `code-smells.md` exists before fix mode runs: it is the work plan, and fix stops with an error when it is absent
+- `code-smells/report.md` exists before fix mode runs: it is the work plan, and fix stops with an error when it is absent
 
 scope:
 - `.ts`, `.mts`, and `.cts` files are reviewed alike
 - `.d.ts` files are reviewed by the Type Safety and Config domains only: a declaration has no runtime behavior
 - `.tsx` is out of scope
 - the analysis scope in a scoped mode is the diff file list, and the reading scope is wider
+- `--affected` widens Architecture evidence to modules reaching a changed module, and does not widen the analysis scope
+- anchor each finding to 1 file, and set `in_diff: true` only when that file is in the diff list
 - read as read-only context: `tsconfig.json`, the configs it extends, and `package.json`
 - read as read-only context: the files the scoped files import 1 level deep, and the shared types in `types.ts`, `*.d.ts`, `interfaces/`, `shared/`
 
@@ -57,11 +59,15 @@ forbidden_behaviors:
 - do not emit the same file and line twice
 - do not boost severity in `full` scope mode: all code is treated alike
 - do not flag a config issue in a scoped mode unless `tsconfig.json` is in the diff
+- do not download and execute a missing analysis tool before the operator approves it once at discovery
+- do not run `npm install` or `npm uninstall` for analysis: use an approved pinned-major `npx -y` command, or record the pre-pass as skipped
 
 outputs:
-- `code-smells.md` in the project root: the scan report, and the work plan fix reads
-- the `## Architecture Opportunities` section of that report, only when Architecture is active and at least 1 candidate is found
-- the audit trail in `code-smells.md` when any issue remains: BEFORE/AFTER for each fixed issue, a status tag for each failed, reverted, or skipped issue, the original entry for each untouched issue
+- `code-smells/report.md` in the project root: the scan report, and the work plan fix reads
+- `code-smells/knip.json`, `projects.json`, `co-change.md`, `cruise-summary.md`, `metrics.md`, and graph and diagram directories when Architecture is active
+- `code-smells/suggested.dependency-cruiser.cjs` when prose declares dependency rules and no machine-readable declaration owns them
+- the `## Architecture Opportunities` section of the report only when Architecture is active and at least 1 confirmed finding exists
+- the audit trail in `code-smells/report.md` when any issue remains: BEFORE/AFTER for each fixed issue, a status tag for each failed, reverted, or skipped issue, the original entry for each untouched issue
 - a regression test for each fix that is testable
 
 run_modes:
@@ -119,40 +125,44 @@ workflow:
 9. audit the config that governs the files in scope, and name that config in the summary
 10. read the linter config: `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`
 11. read `package.json` for the dependencies and the module type, and verify the TypeScript version, `engines.node`, and `@types/node` against `target_stack`
-12. identify the entry points: `index.ts`, `main.ts`, the `exports` of `package.json`
-13. collect the context files named in `scope:` when the scope mode is scoped
-14. map the module relationships when Architecture is active: circular imports, deep relative imports, barrel-file cycles, feature slices, public entry points
-15. scan `docs/adr/`, `doc/adr/`, `adr/`, and `docs/decisions/` for architectural decisions before proposing a change, and skip it silently when none of them exists
-16. report the discovery summary in the shape of `discovery_summary`
+12. identify declared entry points from `package.json#exports`, `main`, `bin`, and the `start`, `dev`, and `serve` scripts
+13. when Architecture is active, inspect local Knip and dependency-cruiser binaries and ask once before running either missing tool through pinned-major `npx -y`
+14. collect the context files named in `scope:` when the scope mode is scoped
+15. identify feature slices and public entry points when Architecture is active, leaving graph discovery to its mechanical pre-pass
+16. collect machine-readable dependency rules and prose from ADR directories, `ARCHITECTURE.md`, README, and `CONTRIBUTING.md`
 17. run `npx tsc --noEmit 2>&1 | head -200` over the full project, and report only the errors in the scoped files
 18. run the linter: `npx eslint [files] --format json` or `npx biome check [files] --reporter json`
 19. query the TypeScript LSP over MCP when it is reachable, then merge and deduplicate against the compiler output
 20. triage every compiler and linter diagnostic through `severity_mapping`
 21. read the reference file named in `domains` before each analysis pass
-22. run only the passes whose domain is in the active domain set, as sub-agents shaped by `subagent_template` or one domain at a time
-23. give every agent all the scoped files when scoped files <= 20, and split by directory above that, with the shared types visible to every agent
-24. re-read the exact lines in the current file state before a finding enters the report
-25. read the callers to verify a data flow a finding rests on, or mark its problem statement with "if <condition>" and cap its severity at Medium
-26. downgrade a flagged non-High pattern that appears 5+ times across the codebase by 1 level, and report it once as a Recurring Pattern
-27. boost a finding carrying `in_diff: true` by 1 level in a scoped mode, and mark it `High [boosted, was Medium — new code]`
-28. deduplicate the findings on the same file, line, and issue, keeping 1
-29. merge the findings 2 domains raise on the same file and line into 1 entry attributing both categories, at the higher severity
-30. consolidate 3+ identical issues into 1 Recurring Pattern entry
-31. keep the top 15 by severity and impact when a single domain produces more than 25 Medium or Low findings, and consolidate the rest into Recurring Pattern entries with their counts
-32. write `code-smells.md` in the shape of `report_format`
-33. sort by severity group, then category, then file path, and place `in_diff: true` before pre-existing in a scoped mode
-34. show the top 10 and summarize the rest in a table when Medium and Low together hold more than 15 issues
-35. recommend that the operator adds `code-smells.md` to `.gitignore`: it is a review artifact
-36. read `references/fix-workflow.md` before fix mode executes: it holds the complete protocol
-37. detect the test runner and run the baseline tests
-38. fix the issues file by file, and run `tsc --noEmit` after each file
-39. run the linter and fix the lint errors it reports
-40. run the full test suite, compare it against the baseline, and fix the regressions
-41. repeat the compiler, linter, and test verification with verification iterations <= 5
-42. update `code-smells.md`: remove what is fixed, mark what failed
-43. show the scan summary in auto mode, and ask the operator whether to proceed with the fix
-44. re-scan after the fix in auto mode with full scan-fix cycles <= 2, and stop when issues persist after the second
-45. delete `code-smells.md` and report success when every issue is fixed
+22. run the mechanical pre-pass in `references/architecture.md` when Architecture is active, passing the approved tool decision and scoped base
+23. report the discovery summary in the shape of `discovery_summary`, including skipped and clean mechanical results
+24. run only the passes whose domain is in the active domain set, as sub-agents shaped by `subagent_template` or one domain at a time
+25. give every agent all the scoped files when scoped files <= 20, and split by directory above that, with the shared types visible to every agent
+26. re-read the exact lines in the current file state before a finding enters the report
+27. read the callers to verify a data flow a finding rests on, or mark its problem statement with "if <condition>" and cap its severity at Medium
+28. downgrade a flagged non-High pattern that appears 5+ times across the codebase by 1 level, and report it once as a Recurring Pattern
+29. boost a finding carrying `in_diff: true` by 1 level in a scoped mode, and mark it `High [boosted, was Medium — new code]`
+30. deduplicate the findings on the same file, line, and issue, keeping 1
+31. merge the findings 2 domains raise on the same file and line into 1 entry attributing both categories, at the higher severity
+32. consolidate 3+ identical issues into 1 Recurring Pattern entry
+33. keep the top 15 by severity and impact when a single domain produces more than 25 Medium or Low findings, and consolidate the rest into Recurring Pattern entries with their counts
+34. write `code-smells/report.md` in the shape of `report_format`
+35. sort by severity group, then category, then file path, and place `in_diff: true` before pre-existing in a scoped mode
+36. show the top 10 and summarize the rest in a table when Medium and Low together hold more than 15 issues
+37. recommend that the operator adds `code-smells/` to `.gitignore`: it holds review artifacts
+38. read `references/fix-workflow.md` before fix mode executes: it holds the complete protocol
+39. detect the test runner and run the baseline tests
+40. fix the issues file by file, and run `tsc --noEmit` after each file
+41. run the linter and fix the lint errors it reports
+42. run the full test suite, compare it against the baseline, and fix the regressions
+43. repeat the compiler, linter, and test verification with verification iterations <= 5
+44. rerun the Architecture mechanical pre-pass on the fixed tree when Architecture is active
+45. update `code-smells/report.md`: remove what is fixed, mark what failed
+46. show the scan summary in auto mode, and ask the operator whether to proceed with the fix
+47. re-scan after the fix in auto mode with full scan-fix cycles <= 2, and stop when issues persist after the second
+48. delete `code-smells/report.md` and report success when every issue is fixed
+49. retain the remaining `code-smells/` artifacts, state what they contain, and remove them only after the operator confirms
 
 scope_commands:
 ```bash
@@ -161,6 +171,7 @@ npx glob '**/*.{ts,mts,cts}' --ignore '**/node_modules/**'
 # or: git ls-files '*.ts' '*.mts' '*.cts'
 
 # uncommitted — staged, unstaged, and untracked
+BASE=HEAD
 git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
 git ls-files --others --exclude-standard -- '*.ts' '*.mts' '*.cts'
 
@@ -170,6 +181,7 @@ git diff --name-only "$BASE"...HEAD -- '*.ts' '*.mts' '*.cts'
 git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
 
 # commits:N — the last N commits
+BASE=HEAD~N
 git diff --name-only HEAD~N..HEAD -- '*.ts' '*.mts' '*.cts'
 
 # the changed hunks, for the severity boost in a scoped mode
@@ -211,6 +223,15 @@ Strict mode: yes / partial / no
 Linter: eslint / biome / none
 Test runner: vitest / jest / mocha / node:test / none
 Files in scope: <N> .ts files (+ <M> context files)
+Architecture projects: <config and source roots, when active>
+Architecture tools: <local or approved npx versions, when active>
+Mechanical results: <module and edge counts, cycles, orphans, and co-change pairs; name clean zeros>
+Skipped pre-passes: <tool and reason, or none>
+Speculative candidates: <names only, or none>
+Declared dependency rules:
+| Rule | Source file:line | Directories |
+|---|---|---|
+| <rule, or none> | <path:line> | <mapping> |
 ```
 
 subagent_template:

package/ts-reviewer/references/architecture.md

@@ -23,8 +23,8 @@ confidence_scale:
 
 | Confidence | Criteria |
 |---|---|
-| strong | the pain repeats, the owning module is named, and the fix path is safe |
-| worth-exploring | the problem is confirmed, and the interface or the migration needs its own design |
+| strong | the pain repeats and the owner is named, or a quoted dependency rule maps 1:1 onto directories |
+| worth-exploring | the problem is confirmed but the interface, migration, inferred rule, or layer mapping needs its own design |
 | speculative | a signal with no call, history, or test evidence behind it |
 
 read_first:
@@ -35,23 +35,56 @@ read_first:
 - dependency direction matters more than layer count: the domain owns the logic, and transport and storage are injected or isolated at the edge
 - 1 adapter is a hypothetical seam and 2 adapters are a real seam: do not introduce a port until at least 2 adapters are justified, production and test at the minimum
 - an architecture finding rests on evidence: named files and symbols, an import or call direction, a repeated change path in `git log`, a duplicated rule, or a test no correct seam can reach
-- state the observation apart from the inference drawn from it, and mark a candidate with no evidence behind it as speculative rather than reporting it as a defect
+- state the observation apart from the inference, and list an evidence-free candidate as speculative in `discovery_summary` rather than reporting it as a defect
 - a defect no test can reach through a correct seam is an architecture finding, and not a reason to write a test past the interface
 - before proposing a module, a port, or a container, check in order: drop the need, an existing module in the repository, the standard library, a platform feature, an installed dependency
 - design a hard-to-reverse proposal twice: compare 2 different interfaces on caller knowledge, seam placement, and migration cost, then recommend 1
 - a cycle is unclear ownership and not a bad graph: move the type or the rule to its owner, and `import type` or a lazy import hides the direction rather than fixing it
 - a path alias shortens an import path and is not an architecture boundary: ownership and a controlled export list are
+- under `--arch`, Knip narrows the observed interface and confirms orphans, while dead-code findings remain owned by Dependency Hygiene
+- apply an exception stated with a dependency rule before reporting it, and cap a path the declaration marks legacy or deprecated at Low
 - pick the simplest form a deepened module can take: a pure function for a transformation, a reducer for events over 1 state, a state machine when a command is valid only in some states, a class only when it owns long-lived state
 
 workflow:
-1. trace 1 typical scenario end to end before naming a finding: entry point, orchestration, domain rule, storage or external call, response
-2. grep for feature-module imports inside the `shared`, `common`, `core`, and `utils` directories, which is the inverted direction
-3. list the importers of each module, and treat a module whose every export has exactly 1 importer as a pass-through candidate for the deletion test
-4. treat an interface or type re-exported unchanged through 3+ files as a pass-through chain
-5. check whether the exports of a utility file imported by most modules share 1 domain concept
-6. read `git log --name-only` and use it twice: a feature whose commits consistently touch 4+ directories is scattered logic, and the directories changing most often are where to start
-7. name the module owning the rule and the module owning the state for each candidate, and mark the candidate speculative when neither is identifiable
-8. run these checks rather than guessing from file names
+1. locate machine-readable dependency rules first, then prose in ADRs, `ARCHITECTURE.md`, README, and `CONTRIBUTING.md`, in that order
+2. resolve conflicting ADRs only through an explicit supersede, and ask when the conflict would produce a High finding
+3. list each extracted rule, its source line, and its directory mapping in `discovery_summary` before using it
+4. write prose-derived rules to `code-smells/suggested.dependency-cruiser.cjs`, and do not add them to the project during scan
+5. when no declaration exists, report observed structure and offer a declaration rather than inventing layers
+6. run the mechanical pre-pass with the commands below against 1 unchanged tree before the semantic pass
+7. classify Knip and dependency-cruiser by parseable output rather than exit code, since both tools use non-zero and zero exits for reportable candidates
+8. record a project with source files and `totalCruised == 0` as a skipped pre-pass, and do not report its mechanical zeros
+9. give the semantic pass `code-smells/metrics.md` rather than a raw graph
+10. cross each co-change pair with the graph: an edge is weak evidence, while no edge across directories is an implicit-contract candidate
+11. read ESLint boundary rules from linter output without converting them, since the linter already executed those rules
+12. consolidate all violating edges for 1 declared rule into 1 candidate, after removing declared exceptions
+13. trace `min(declared entry points, 3)` scenarios, ranked by the number of modules each entry point reaches
+14. grep for feature-module imports inside the `shared`, `common`, `core`, and `utils` directories, which is the inverted direction
+15. apply the deletion test only to a module whose whole export set has 1 importer and that wraps or re-exports another module
+16. treat an interface or type re-exported unchanged through 3+ files as a pass-through chain
+17. inspect the top 20 modules and folders by fan-in for mixed concepts, and use folder instability only to rank layer checks
+18. name the module owning the rule and the module owning the state for each candidate, and mark the candidate speculative when neither is identifiable
+19. after triage, create 2..3 focused Mermaid diagrams tied to the top findings, and do not create a whole-project diagram
+20. generate SVG only after `dot -V` succeeds, and keep Mermaid when Graphviz is unavailable
+21. run these checks rather than reporting a cycle, hub, orphan, co-change pair, or Knip entry directly
+```bash
+# SKILL is the directory this file was loaded from; the main workflow approved missing tools before this pass.
+SKILL=<the directory this file was loaded from>
+KNIP=$([ -x node_modules/.bin/knip ] && echo node_modules/.bin/knip || echo "npx -y knip@6.31.0")
+
+mkdir -p code-smells
+
+node "$SKILL/tools/discover-projects.mjs" > code-smells/projects.json
+$KNIP --reporter json > code-smells/knip.json
+node "$SKILL/tools/co-change.mjs" --projects code-smells/projects.json --out code-smells/co-change.md
+node "$SKILL/tools/run-cruise.mjs" --projects code-smells/projects.json --out code-smells
+
+# In a scoped mode, BASE is the comparison ref computed by scope_commands.
+node "$SKILL/tools/run-cruise.mjs" --projects code-smells/projects.json --out code-smells --base "$BASE"
+
+# After triage, create one diagram for a top finding.
+node "$SKILL/tools/run-cruise.mjs" --projects code-smells/projects.json --out code-smells --focus '<module regex>' --name <finding>
+```
 
 checks:
 - shallow modules — understanding 1 concept requires bouncing across many tiny modules: Medium
@@ -76,6 +109,7 @@ checks:
 - under-engineering — event or string-keyed indirection between 2 modules that only ever talk to each other: Low, a direct typed call is checkable
 - dependency direction — a domain or computation module importing IO directly, `node:fs`, `node:http`, a DB client, or `fetch`, where the classification puts that IO behind a seam: Medium
 - dependency direction — a shared or leaf module, `utils/`, `types/`, or `core/`, importing from a feature module: High, the inverted direction is how import cycles start
+- dependency direction — an import edge contradicting a layer rule the project declares in an ADR or ARCHITECTURE.md: High, quote the rule with its source line and list the violating edges
 - dependency direction — a wire or DTO type from an external API imported deep into a domain module instead of mapped at the seam that owns the external contract: Medium
 - state ownership — 2+ modules mutating 1 entity, cache, or record with no single owning module: High, the write paths cannot be tested or reasoned about apart
 - state ownership — fix: a shared mutable entity, by naming 1 owning module and turning each write into a named command on it
@@ -88,6 +122,7 @@ non_findings:
 - a module with exactly 1 importer that hides an ordering, an invariant, or a decision: 1 importer starts the deletion test and is not a finding by itself
 - a layer count: the direction of the dependencies is the finding, and a layer holding a real rule is not
 - a port with 1 production adapter whose test double checks the same contract: the double is the second adapter
+- duplicated trees whose intent is documented, excluded by tool policy, or maintained in lockstep: report at most the synchronized-edit cost at Low, not the decision
 - formatting, import ordering, and file naming: `references/code-quality.md` owns them, and they are not architecture findings
 
 forbidden_behaviors:
@@ -102,7 +137,8 @@ forbidden_behaviors:
 - do not leave a new structure standing beside the old one: every proposal names the step deleting what it replaces
 - do not propose a change contradicting a decision under `docs/adr/` silently: name the ADR and the conflict, and leave the decision to the operator
 - do not report architecture candidates without naming 1 top recommendation and the reason it goes first
-- do not add an import-linting dependency for 1 rule: use `package.json#exports`, the linter the project already runs, or the workspace layout
+- do not add a dependency as the fix for 1 import rule: use `package.json#exports`, the project's linter, or the workspace layout
+- do not treat an approved `npx` graph tool used during review as a project dependency: it changes neither `package.json` nor the lockfile
 
 dependency_classification:
 
@@ -115,6 +151,9 @@ dependency_classification:
 
 severity_mapping:
 
+- map a project-declared severity to the finding: `error` to High, `warn` to Medium, and `info` to Low
+- copy the declared rule comment into Evidence, since it states the project's rationale and accepted debt
+
 | Severity | Architecture criteria |
 |---|---|
 | Highest | an architecture issue directly causing a security vulnerability, data loss, or a production correctness bug |
@@ -124,6 +163,10 @@ severity_mapping:
 
 fixability:
 
+- an `enforce` change is `report-only`, since scan does not write a project config
+- a `delete` change is `auto` only when no module imports the target
+- a deepening, merge, or ownership move is `needs-confirm`
+
 | Fixability | Meaning | Fix mode behaviour |
 |---|---|---|
 | `auto` | a local change: import path cleanup, a narrow circular-import break, a local module merge with co-located tests | applied in the normal fix loop |
@@ -134,15 +177,17 @@ report_format:
 ```md
 ### TITLE — Severity
 
-- **Confidence:** strong | worth-exploring | speculative
+- **Confidence:** strong | worth-exploring
 - **Files:** relative/path/a.ts, relative/path/b.ts
 - **Problem:** why this causes friction now (not just a pattern name)
 - **Evidence:** the imports, callers, `git log` path, or test the finding rests on
-- **Proposed deepening:** plain-English description of what would change
-- **Interface shape:** rough sketch of the new interface (types, methods, key invariants)
-- **Dependency category:** in-process | local-substitutable | remote-owned | true-external
+- **Change type:** deepening | ownership move | merge | delete | enforce
+- **Proposed change:** plain-English description of what would change
+- **Interface shape:** for deepening or merge only; rough sketch of the new interface and key invariants
+- **Dependency category:** for deepening only; in-process | local-substitutable | remote-owned | true-external
+- **Rule:** for enforce only; the exact rule text and the file where it would live
 - **Test strategy:** how tests would improve (what tests survive, what gets deleted, what's new)
-- **Migration:** prefactor | vertical slices | expand-contract, and the step deleting the replaced code
+- **Migration:** for deepening, merge, ownership move, or delete; prefactor | vertical slices | expand-contract, and the deletion step
 - **Benefits:** locality gained, leverage gained, test impact
 - **Trade-offs:** what gets harder, what is genuinely uncertain
 - **Fixability:** auto | needs-confirm | report-only

package/ts-reviewer/references/fix-workflow.md

@@ -7,13 +7,13 @@ scope:
 - the testing strategy for an architecture fix is owned by `references/architecture.md`
 
 read_first:
-- `code-smells.md` exists in the project root, and a missing report stops the run with the error "No scan report found. Run scan first."
+- `code-smells/report.md` exists in the project root, and a missing report stops the run with the error "No scan report found at code-smells/report.md. Run scan first; the report path changed in v3."
 - the project is inside a git repository, so a change can be reverted
 - recommend that the operator commits or stashes uncommitted work before the fix runs, which leaves `git diff` and `git checkout -- .` usable to review and revert
 - the baseline taken in step 3 decides what counts as a regression: a test failing before the fixes is pre-existing and stays out of the work
 
 workflow:
-1. read `code-smells.md` and extract every issue into a work list
+1. read `code-smells/report.md` and extract every issue into a work list
 2. group the issues by file path, and sort them by line number descending inside each file, so a fix lower in the file does not shift the lines above it
 3. build the work plan
 ```
@@ -77,14 +77,16 @@ Iteration 3: Fixed tsc error. All tests pass. Clean.
 27. stop fixing once the fifth iteration ends with the compiler, the linter, or the suite still not clean, leave the code as it stands, and add a Stabilization section to the report listing the unresolved regressions for the operator
 28. show the operator what a `needs-confirm` architecture finding would change, and describe the reorganization or the interface change
 29. apply an approved `needs-confirm` finding through the same file-by-file compiler loop, and mark a rejected one `[SKIPPED: user rejected]`
-30. delete `code-smells.md` when every issue is fixed, and tell the operator "All N issues fixed. Report deleted. Run scan again to verify."
-31. rewrite `code-smells.md` in the shape of `report_format` when any issue remains, carrying both what was fixed and what was not
-32. leave every change in the working tree, unstaged and uncommitted, including the new regression test files
+30. rerun Knip, dependency-cruiser, and co-change through the Architecture workflow when the report contains architecture findings
+31. delete `code-smells/report.md` when every issue is fixed, and tell the operator "All N issues fixed. Report deleted. Run scan again to verify."
+32. keep `code-smells/` after deleting the report, state what it contains, and ask before removing the directory
+33. rewrite `code-smells/report.md` in the shape of `report_format` when any issue remains, carrying both what was fixed and what was not
+34. leave every change in the working tree, unstaged and uncommitted, including the new regression test files
 
 forbidden_behaviors:
 - do not commit and do not stage: the operator reviews and decides
 - do not delete a file unless the report flagged the whole file as dead code
-- do not modify a file outside the issues in `code-smells.md`, apart from a cascading change such as an import updated after a type rename
+- do not modify a file outside the issues in `code-smells/report.md`, apart from a cascading change such as an import updated after a type rename
 - do not change what the code does: a fix changes how it does it, and only a security fix intentionally changes behaviour, such as validation that now rejects malicious input
 - do not refactor a whole file because of 1 issue: fix exactly what the report names
 - do not apply an ambiguous or risky fix: mark it `[SKIPPED: requires manual review]` and move on, since skipping costs less than breaking the build

package/ts-reviewer/tools/classify-run.mjs

@@ -0,0 +1,26 @@
+// How a tool run is read. Neither the exit code nor the green tick means what it looks like:
+// Knip exits 1 with findings, dependency-cruiser exits 0 with violations, and a cruise that
+// walked zero modules prints "no dependency violations found" over an empty graph.
+export function classifyRun({ label = "", exitCode, stdout = "" }) {
+  const text = String(stdout);
+  const trimmed = text.trim();
+  let parsed = null;
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try { parsed = JSON.parse(trimmed); } catch { parsed = undefined; }
+  }
+  const output = parsed !== null
+    ? (parsed === undefined ? "invalid JSON" : "valid JSON")
+    : (trimmed ? "text" : "empty");
+
+  const cruised = /(\d+) modules(?:, (\d+) dependencies)? cruised/.exec(text);
+  const zeroCruise = label.startsWith("depcruise")
+    && ((cruised && cruised[1] === "0") || parsed?.summary?.totalCruised === 0);
+
+  const reading = zeroCruise ? "failed: 0 modules cruised"
+    : output === "empty" && exitCode !== 0 ? "failed"
+    : exitCode === 0 && output !== "empty" ? "ok"
+    : exitCode !== 0 && output !== "empty" ? "findings, not a failure"
+    : "clean";
+
+  return { output, reading };
+}

package/ts-reviewer/tools/co-change.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Co-change hotspots for the architecture pre-pass. No dependency: git plus this file.
+// Usage: node co-change.mjs [--repo <dir>] [--src <dir>] [--out <file>] [--scope <list-file>]
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+
+const WINDOW = "12.months";
+const MAX_COMMITS = 500;
+const MAX_FILES_PER_COMMIT = 25; // above this a commit is mechanical: a lockfile bump, a format sweep, a mass rename
+const MIN_CO_CHANGES = 5;
+const MIN_RATIO = 0.5;
+const TOP_N = 15;
+const EXTENSIONS = ["*.ts", "*.mts", "*.cts"];
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? fallback : process.argv[i + 1];
+}
+
+const repo = path.resolve(arg("repo", process.cwd()));
+// One or more source roots, comma-separated — the `sourceRoot` values discover-projects.mjs returns.
+// A monorepo needs all of them: measured from the repository root every file in `packages/*` shares
+// one top-level directory, and the cross-directory gate would reject every pair.
+// Deduplicated: two configs commonly resolve the same root, and a repeated root would count a file
+// once per copy.
+const projectsFile = arg("projects", "");
+const rootsArg = projectsFile
+  ? JSON.parse(readFileSync(path.resolve(repo, projectsFile), "utf8")).projects.flatMap((p) => p.sourceRoots).join(",")
+  : arg("src", "");
+const roots = [...new Set(rootsArg.split(",").map((r) => r.trim().replace(/\/*$/, "")).filter(Boolean))];
+const out = arg("out", "");
+const scopeFile = arg("scope", "");
+
+const git = (args) => execFileSync("git", args, { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+
+// Files that exist right now. A pair naming a deleted file is history, not structure.
+const existing = new Set(git(["ls-files", "--", ...EXTENSIONS]).split("\n").filter(Boolean));
+
+// Optional: the analysis scope of a scoped run, one path per line. Used at output time only —
+// intersecting during counting would erase every pair in a mode whose scope is three files.
+const scope = scopeFile
+  ? new Set(readFileSync(scopeFile, "utf8").split("\n").map((l) => l.trim()).filter(Boolean))
+  : null;
+
+const rootOf = (f) => (roots.length ? roots.find((r) => f.startsWith(r + "/")) ?? null : "");
+const inSrc = (f) => rootOf(f) !== null;
+const topDir = (f) => {
+  const root = rootOf(f);
+  const rest = root ? f.slice(root.length + 1) : f;
+  const parts = rest.split("/");
+  // The root itself is part of the identity: `packages/a/src/x` and `packages/b/src/x` are not
+  // the same directory just because both are called `src`.
+  return parts.length > 1 ? `${root}/${parts[0]}` : `${root}/.`;
+};
+
+const log = git([
+  "log", "--no-merges", `--since=${WINDOW}`, `-n${MAX_COMMITS}`,
+  "--format=%H", "--name-only", "--", ...EXTENSIONS,
+]);
+
+const commits = [];
+let current = null;
+for (const line of log.split("\n")) {
+  if (!line.trim()) continue;
+  if (/^[0-9a-f]{40}$/.test(line)) { current = []; commits.push(current); continue; }
+  if (current) current.push(line);
+}
+
+const changes = new Map();
+const pairs = new Map();
+let mechanical = 0;
+
+for (const commit of commits) {
+  const touched = [...new Set(commit)];
+  // The size gate reads the commit as it was, before the existence and src filters —
+  // otherwise a mass rename shrinks into eligibility once its deleted paths drop out.
+  if (touched.length > MAX_FILES_PER_COMMIT) { mechanical++; continue; }
+  const files = touched.filter((f) => existing.has(f) && inSrc(f)).sort();
+  if (files.length < 2) continue;
+  for (const f of files) changes.set(f, (changes.get(f) ?? 0) + 1);
+  for (let i = 0; i < files.length; i++) {
+    for (let j = i + 1; j < files.length; j++) {
+      const key = `${files[i]}\t${files[j]}`;
+      pairs.set(key, (pairs.get(key) ?? 0) + 1);
+    }
+  }
+}
+
+const ranked = [...pairs]
+  .map(([key, co]) => {
+    const [a, b] = key.split("\t");
+    return { a, b, co, ratio: co / Math.min(changes.get(a), changes.get(b)) };
+  })
+  .filter((p) => p.co >= MIN_CO_CHANGES && p.ratio >= MIN_RATIO && topDir(p.a) !== topDir(p.b))
+  .filter((p) => !scope || scope.has(p.a) || scope.has(p.b))
+  .sort((x, y) => y.co - x.co || y.ratio - x.ratio || x.a.localeCompare(y.a))
+  .slice(0, TOP_N);
+
+const report = [
+  `# Co-change pairs`,
+  ``,
+  `Window: last ${WINDOW.replace(".", " ")}, at most ${MAX_COMMITS} commits, merges excluded.`,
+  `Commits read: ${commits.length}. Dropped as mechanical (> ${MAX_FILES_PER_COMMIT} files): ${mechanical}.`,
+  `Gates: co-changes >= ${MIN_CO_CHANGES}, ratio >= ${MIN_RATIO}, different top-level directory.`,
+  ``,
+  ranked.length ? `| Co-changes | Ratio | File A | File B |` : `No pair passed the gates.`,
+  ranked.length ? `|---|---|---|---|` : ``,
+  ...ranked.map((p) => `| ${p.co} | ${p.ratio.toFixed(2)} | \`${p.a}\` | \`${p.b}\` |`),
+].filter((l) => l !== "").join("\n");
+
+if (out) {
+  mkdirSync(path.dirname(path.resolve(repo, out)), { recursive: true });
+  writeFileSync(path.resolve(repo, out), report + "\n", "utf8");
+}
+console.log(report);

package/ts-reviewer/tools/discover-projects.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// Architecture projects for the pre-pass: which tsconfig owns a source set, and where that set lives.
+// Usage: node discover-projects.mjs [--repo <dir>]   → JSON on stdout
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i === -1 ? fallback : process.argv[i + 1];
+}
+
+const repo = path.resolve(arg("repo", process.cwd()));
+
+// ponytail: every tsconfig tracked by git is found by the glob, which is a superset of what a
+// transitive `references` walk reaches. Walk the references only if untracked configs ever matter.
+const configs = execFileSync("git", ["ls-files", "tsconfig*.json", "*/tsconfig*.json", "**/tsconfig*.json"], {
+  cwd: repo, encoding: "utf8",
+}).split("\n").filter(Boolean).sort();
+
+// TSC_BIN lets a caller point at an already-installed compiler; otherwise the project's own
+// typescript is used, and only a project without one reaches for the network.
+const localTsc = process.env.TSC_BIN || path.join(repo, "node_modules", "typescript", "bin", "tsc");
+const runTsc = (args) => {
+  const r = existsSync(localTsc)
+    ? spawnSync(process.execPath, [localTsc, ...args], { cwd: repo, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+    // `-p typescript` names the package; `tsc` names the binary inside it. `npx -y tsc` resolves
+    // to an unrelated package of that name.
+    : spawnSync("npx", ["-y", "-p", "typescript", "tsc", ...args], { cwd: repo, encoding: "utf8", shell: true, maxBuffer: 64 * 1024 * 1024 });
+  // A non-zero status with usable output is a result, not a failure: tsc reports type errors
+  // while still listing the files it resolved.
+  return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+};
+
+const isSource = (f) =>
+  !f.startsWith("node_modules/") && !f.includes("/node_modules/") &&
+  !f.startsWith("../") && !/(^|\/)lib\.[^/]*\.d\.ts$/.test(f) && /\.(ts|mts|cts|tsx)$/.test(f);
+
+const commonDir = (files) => {
+  const dirs = files.map((f) => path.posix.dirname(f).split("/"));
+  const first = dirs[0] ?? [];
+  let i = 0;
+  outer: for (; i < first.length; i++) {
+    for (const d of dirs) if (d[i] !== first[i]) break outer;
+  }
+  return first.slice(0, i).join("/") || ".";
+};
+
+// A config whose files share no directory above the repository root spans several areas. The
+// repository root is useless as a `--collapse` base and as a co-change boundary, so the project
+// carries its top-level directories instead of one meaningless root.
+const sourceRootsOf = (files) => {
+  const common = commonDir(files);
+  if (common !== ".") return [common];
+  return [...new Set(files.map((f) => f.split("/")[0]))].sort();
+};
+
+const workspaces = () => {
+  const out = [];
+  const pkg = path.join(repo, "package.json");
+  if (existsSync(pkg)) {
+    const w = JSON.parse(readFileSync(pkg, "utf8")).workspaces;
+    if (Array.isArray(w)) out.push(...w);
+    else if (w?.packages) out.push(...w.packages);
+  }
+  const pnpm = path.join(repo, "pnpm-workspace.yaml");
+  if (existsSync(pnpm)) {
+    for (const line of readFileSync(pnpm, "utf8").split("\n")) {
+      const m = line.match(/^\s*-\s*['"]?([^'"#]+?)['"]?\s*$/);
+      if (m) out.push(m[1]);
+    }
+  }
+  return out;
+};
+
+// ponytail: regex over the raw text, because `--showConfig` resolves `extends` away and a
+// tsconfig is JSONC, which JSON.parse will not read.
+const rawOf = new Map(configs.map((c) => [c, readFileSync(path.join(repo, c), "utf8")]));
+const declaresOwnSources = (config) => /"(include|files|references)"\s*:/.test(rawOf.get(config) ?? "");
+
+// A config is a base only when another config extends it AND it declares no source set of its own.
+// Being extended is not disqualifying by itself: a root tsconfig can be both the production
+// project and the options other configs inherit, and dropping it skips the product.
+const extended = new Set();
+for (const config of configs) {
+  for (const m of (rawOf.get(config) ?? "").matchAll(/"extends"\s*:\s*"([^"]+)"/g)) {
+    if (m[1].startsWith(".")) {
+      extended.add(path.posix.normalize(path.posix.join(path.posix.dirname(config), m[1])));
+    }
+  }
+}
+const bases = new Set([...extended].filter((c) => !declaresOwnSources(c)));
+
+const projects = [];
+const metadata = [];
+
+for (const config of configs) {
+  if (bases.has(config) || bases.has(config.replace(/\.json$/, ""))) {
+    metadata.push({ config, reason: "extended by another config: it supplies options, not sources" });
+    continue;
+  }
+  const listed = runTsc(["-p", config, "--listFilesOnly"]);
+  const files = listed.stdout.split("\n").map((l) => l.trim().replace(/\\/g, "/")).filter(Boolean)
+    .map((f) => (path.isAbsolute(f) ? path.posix.relative(repo.replace(/\\/g, "/"), f) : f))
+    .filter(isSource)
+    .sort();
+
+  if (files.length === 0) {
+    metadata.push({
+      config,
+      // A solution config aggregating `references` resolves nothing and exits clean; anything else
+      // is a config tsc could not read, and the reason belongs in the report rather than one word.
+      reason: listed.status === 0
+        ? "resolves no source files: a solution config aggregating references"
+        : `tsc could not read it: ${(listed.stderr || listed.stdout).split("\n").filter(Boolean).slice(0, 2).join(" / ") || "no diagnostic"}`,
+      exitCode: listed.status,
+    });
+    continue;
+  }
+
+  const roots = sourceRootsOf(files);
+  projects.push({
+    config,
+    sourceRoots: roots,
+    absoluteSourceRoots: roots.map((r) => path.resolve(repo, r)),
+    fileCount: files.length,
+    files,
+  });
+}
+
+// A test, browser, or tooling config whose file set is contained in another project's is a variant:
+// it contributes unique files only, and gets no aggregate metrics run of its own. Two configs
+// resolving the *same* set are duplicates of each other, and the tie is broken deterministically —
+// shortest path, then lexicographic — so that two runs of one review agree.
+const rank = (c) => [c.split("/").length, c.length, c];
+const beats = (a, b) => {
+  const [x, y] = [rank(a), rank(b)];
+  return x[0] !== y[0] ? x[0] < y[0] : x[1] !== y[1] ? x[1] < y[1] : x[2] < y[2];
+};
+for (const p of projects) {
+  const key = p.files.join("\n");
+  p.variantOf = projects
+    .filter((o) => {
+      if (o === p) return false;
+      const same = o.files.join("\n") === key;
+      if (same) return beats(o.config, p.config);
+      return o.files.length > p.files.length && p.files.every((f) => o.files.includes(f));
+    })
+    .map((o) => o.config)[0] ?? null;
+}
+
+const result = {
+  repo,
+  workspaces: workspaces(),
+  projects: projects.filter((p) => !p.variantOf).map(({ files, ...rest }) => rest),
+  variants: projects.filter((p) => p.variantOf).map(({ files, ...rest }) => rest),
+  metadata,
+};
+console.log(JSON.stringify(result, null, 2));

package/ts-reviewer/tools/run-cruise.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+// Runs dependency-cruiser over every architecture project discover-projects.mjs found.
+//
+//   node run-cruise.mjs --projects code-smells/projects.json --out code-smells [--base <ref>]
+//
+// It exists so that no shell has to hold a ruleset path, a regex, a list of source roots, or a
+// loop: every one of those was a quoting bug waiting in a bash block.
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { classifyRun } from "./classify-run.mjs";
+
+const TOOL = "dependency-cruiser@18.1.0";
+const EXCLUDE = "^(node_modules|node:)";
+const PROJECT_DECLARATIONS = [".dependency-cruiser.cjs", ".dependency-cruiser.js", ".dependency-cruiser.json"];
+
+const arg = (n, d) => { const i = process.argv.indexOf(`--${n}`); return i === -1 ? d : process.argv[i + 1]; };
+const repo = path.resolve(arg("repo", process.cwd()));
+const projectsFile = path.resolve(repo, arg("projects", "code-smells/projects.json"));
+const outDir = path.resolve(repo, arg("out", "code-smells"));
+const base = arg("base", "");
+const declarations = [
+  ...PROJECT_DECLARATIONS.map((name) => path.join(repo, name)),
+  path.join(outDir, "suggested.dependency-cruiser.cjs"),
+];
+
+const { projects } = JSON.parse(readFileSync(projectsFile, "utf8"));
+mkdirSync(path.join(outDir, "graphs"), { recursive: true });
+mkdirSync(path.join(outDir, "diagrams"), { recursive: true });
+
+// ── the ruleset ─────────────────────────────────────────────────────────────
+// A project declaration supplies rules. Its `options` describe the area that project chose to
+// cover, and on any other path they cruise nothing — so only `forbidden` is carried over.
+const MINIMUM = [
+  { name: "no-circular", severity: "warn", from: {}, to: { circular: true } },
+  { name: "no-orphans", severity: "warn", from: { orphan: true }, to: {} },
+  { name: "not-to-unresolvable", severity: "error", from: {}, to: { couldNotResolve: true } },
+];
+
+const declaration = declarations.find((candidate) => existsSync(candidate));
+let forbidden = MINIMUM;
+let rulesFrom = "the minimum ruleset";
+if (declaration) {
+  try {
+    const theirs = createRequire(path.join(repo, "noop.cjs"))(declaration);
+    if (Array.isArray(theirs.forbidden) && theirs.forbidden.length) {
+      forbidden = theirs.forbidden;
+      rulesFrom = `${path.basename(declaration)} (${theirs.forbidden.length} rules), options from the pre-pass`;
+    }
+  } catch (e) {
+    rulesFrom = `${path.basename(declaration)} could not be read (${e.message}); fell back to the minimum ruleset`;
+  }
+}
+
+// `exclude: "^(node_modules|node:)"` does NOT drop Node builtins: dependency-cruiser normalises
+// `node:fs/promises` to the source `fs/promises` and flags it `coreModule`, so nothing starting
+// with `node:` is ever in the graph to match. Scoping the graph to the project's own source roots
+// is exact and drops builtins, node_modules and every external package in one rule.
+const includeOnly = `^(${[...new Set(projects.flatMap((p) => p.sourceRoots))].map((r) => r.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})/`;
+
+const ruleset = path.join(tmpdir(), `arch-ruleset-${process.pid}.cjs`);
+writeFileSync(ruleset, `module.exports = ${JSON.stringify({
+  forbidden,
+  options: {
+    doNotFollow: { path: "node_modules" },
+    exclude: EXCLUDE,
+    includeOnly,
+    tsPreCompilationDeps: true,
+  },
+}, null, 2)};\n`, "utf8");
+
+// ── running the tool ────────────────────────────────────────────────────────
+// `npx` is a .cmd on Windows and needs a shell, which is why every argument is quoted here rather
+// than being handed to the shell bare. The exclude pattern is not passed on the command line at
+// all: it lives in the ruleset above, so no regex ever meets a shell.
+// dependency-cruiser reads a tsconfig with the TypeScript compiler, and resolves `typescript` from
+// its own install location — which, run from the npx cache, is not the project. NODE_PATH is what
+// makes the project's copy visible; without it the cruise silently returns zero modules.
+const projectModules = path.join(repo, "node_modules");
+const nodePath = existsSync(path.join(projectModules, "typescript"))
+  ? projectModules
+  : process.env.NODE_PATH || projectModules;
+const localCruise = path.join(projectModules, ".bin", process.platform === "win32" ? "depcruise.cmd" : "depcruise");
+
+function cruise(label, extraArgs, project) {
+  const toolArgs = ["--config", ruleset, "--ts-config", project.config, ...extraArgs, ...project.sourceRoots];
+  const args = existsSync(localCruise) ? toolArgs : ["-y", TOOL, ...toolArgs];
+  const shell = process.platform === "win32";
+  const started = Date.now();
+  const r = spawnSync(existsSync(localCruise) ? localCruise : "npx", shell ? args.map((a) => JSON.stringify(a)) : args, {
+    cwd: repo, encoding: "utf8", shell, maxBuffer: 256 * 1024 * 1024,
+    env: { ...process.env, NODE_PATH: nodePath },
+  });
+  const run = { label, exitCode: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "", ms: Date.now() - started };
+  return { ...run, ...classifyRun(run) };
+}
+
+// --focus is the post-triage mode: one diagram of one finding's neighbourhood, and nothing else.
+// It runs after the semantic pass, because until a finding exists there is no module to focus on.
+const focus = arg("focus", "");
+if (focus) {
+  const name = arg("name", "focus");
+  for (const project of projects) {
+    const run = cruise(`depcruise focus ${project.config}`,
+      ["--output-type", "mermaid", "--focus", focus, "--focus-depth", arg("depth", "1")], project);
+    if (run.stdout.trim().split("\n").length > 2) {
+      writeFileSync(path.join(outDir, "diagrams", `${name}.mmd`), run.stdout, "utf8");
+      console.log(`Wrote ${path.join(outDir, "diagrams", `${name}.mmd`)} from ${project.config}`);
+      process.exit(0);
+    }
+  }
+  console.log(`No project matched ${focus}: no diagram written.`);
+  process.exit(0);
+}
+
+const results = [];
+for (const project of projects) {
+  const id = project.config.replace(/[/.]/g, "_");
+
+  const metrics = cruise(`depcruise metrics ${project.config}`, ["--metrics", "--output-type", "json"], project);
+  const graph = metrics.output === "valid JSON" ? JSON.parse(metrics.stdout) : null;
+  if (graph) writeFileSync(path.join(outDir, "graphs", `${id}.json`), metrics.stdout, "utf8");
+
+  const err = cruise(`depcruise err ${project.config}`, ["--output-type", "err"], project);
+
+  const collapse = `^${project.sourceRoots[0]}/[^/]+/`;
+  const diagram = cruise(`depcruise mermaid ${project.config}`, ["--output-type", "mermaid", "--collapse", collapse], project);
+  if (diagram.stdout.trim()) writeFileSync(path.join(outDir, "diagrams", `${id}.mmd`), diagram.stdout, "utf8");
+
+  const affected = base
+    ? cruise(`depcruise affected ${project.config}`, ["--affected", base, "--output-type", "text"], project)
+    : null;
+
+  results.push({ project, graph, runs: [metrics, err, diagram, ...(affected ? [affected] : [])] });
+}
+
+// Derived, bounded tables are the semantic pass input. The raw graphs stay on disk.
+const table = (headers, rows) => [
+  `| ${headers.join(" | ")} |`,
+  `|${headers.map(() => "---").join("|")}|`,
+  ...rows.map((row) => `| ${row.map((cell) => String(cell).replaceAll("|", "\\|")).join(" | ")} |`),
+];
+const moduleRows = new Map();
+const folderRows = new Map();
+const cycles = new Set();
+const orphans = new Set();
+const crossDirectory = new Set();
+const violations = new Set();
+const projectRows = [];
+for (const { project, graph } of results) {
+  if (!graph) continue;
+  const modules = graph.modules ?? [];
+  const roots = [...project.sourceRoots].sort((a, b) => b.length - a.length);
+  const area = (source) => {
+    const root = roots.find((candidate) => source === candidate || source.startsWith(`${candidate}/`));
+    const rest = root ? source.slice(root.length).replace(/^\//, "") : source;
+    return `${root ? `${root}/` : ""}${rest.split("/")[0]}`;
+  };
+  for (const module of modules) {
+    const fanIn = module.dependents?.length ?? 0;
+    const previous = moduleRows.get(module.source);
+    if (!previous || previous[1] < fanIn) moduleRows.set(module.source, [module.source, fanIn, module.dependencies?.length ?? 0, module.instability ?? ""]);
+    if (module.orphan) orphans.add(module.source);
+    for (const dependency of module.dependencies ?? []) {
+      if (!dependency.resolved) continue;
+      if (dependency.circular) cycles.add(`${module.source} → ${dependency.resolved}`);
+      if (area(module.source) !== area(dependency.resolved)) crossDirectory.add(`${module.source} → ${dependency.resolved}`);
+    }
+  }
+  for (const folder of graph.folders ?? []) {
+    const previous = folderRows.get(folder.name);
+    if (!previous || previous[2] < folder.afferentCouplings) {
+      folderRows.set(folder.name, [folder.name, folder.moduleCount, folder.afferentCouplings, folder.efferentCouplings, folder.instability]);
+    }
+  }
+  for (const violation of graph.summary?.violations ?? []) {
+    violations.add(`${violation.rule?.name ?? "unnamed"} | ${violation.from ?? ""} | ${violation.to ?? ""}`);
+  }
+  projectRows.push([project.config, modules.length, graph.summary?.totalDependenciesCruised ?? 0, modules.filter((m) => m.orphan).length]);
+}
+const topModules = [...moduleRows.values()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 20);
+const topFolders = [...folderRows.values()].sort((a, b) => b[2] - a[2] || a[0].localeCompare(b[0])).slice(0, 20);
+const metricsLines = [
+  "# Architecture metrics", "",
+  "## Projects", "", ...table(["Project", "Modules", "Edges", "Orphans"], projectRows), "",
+  "## Top modules by fan-in", "", ...table(["Module", "Fan-in", "Fan-out", "Instability"], topModules), "",
+  "## Top folders by fan-in", "", ...table(["Folder", "Modules", "Afferent", "Efferent", "Instability"], topFolders), "",
+  "## Cycles", "", ...(cycles.size ? [...cycles].slice(0, 20).map((edge) => `- ${edge}`) : ["- none"]), "",
+  "## Orphans", "", ...(orphans.size ? [...orphans].slice(0, 20).map((source) => `- ${source}`) : ["- none"]), "",
+  "## Declared rule violations", "", ...(violations.size ? [...violations].slice(0, 50).map((item) => `- ${item}`) : ["- none"]), "",
+  "## Cross-directory edges", "", ...(crossDirectory.size ? [...crossDirectory].slice(0, 50).map((edge) => `- ${edge}`) : ["- none"]), "",
+];
+writeFileSync(path.join(outDir, "metrics.md"), metricsLines.join("\n"), "utf8");
+
+// ── summary ─────────────────────────────────────────────────────────────────
+const lines = [`# Cruise summary`, ``, `Ruleset: ${rulesFrom}`, ``,
+  `| Project | Source roots | Step | Exit | Reading |`, `|---|---|---|---|---|`];
+let failures = 0;
+for (const { project, runs } of results) {
+  for (const run of runs) {
+    if (run.reading.startsWith("failed")) failures++;
+    lines.push(`| ${project.config} | ${project.sourceRoots.join(", ")} | ${run.label.split(" ")[1]} | ${run.exitCode} | ${run.reading} |`);
+  }
+}
+lines.push(``, failures
+  ? `**${failures} step(s) failed.** A cruise of zero modules is a failed pre-pass, not a clean result: record it as skipped and do not read the empty graph as an absence of coupling.`
+  : `All steps produced a graph. Zero findings from these runs are reportable as mechanical zeros.`);
+
+writeFileSync(path.join(outDir, "cruise-summary.md"), lines.join("\n") + "\n", "utf8");
+console.log(lines.join("\n"));
+process.exitCode = 0; // a failed step is reported in the summary, never by this script's exit code