ts-reviewer 1.0.0 → 1.1.0

package/README.md

@@ -14,16 +14,17 @@ Three modes, one skill:
 | **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 |
 
-The review covers six domains, each with its own detailed checklist:
-
-| Domain | Examples |
-|---|---|
-| **Type Safety** | `any` abuse, unsafe casts, non-null assertions, missing exhaustive checks |
-| **Security** | Injection, prototype pollution, ReDoS, path traversal, hardcoded secrets |
-| **Async Patterns** | Floating promises, race conditions, missing error propagation, `forEach(async...)` |
-| **Modernization** | `enum` → `as const`, missing `satisfies`, `using` keyword, `import type` |
-| **Code Quality** | Dead code, complexity, duplication, hacky patterns, error handling |
-| **Config** | tsconfig.json strict flags, module resolution, deprecated options |
+The review covers six domains by default, each with its own detailed checklist. Add `--arch` or `--full` to include architecture analysis:
+
+| Domain | Examples | Default |
+|---|---|---|
+| **Type Safety** | `any` abuse, unsafe casts, non-null assertions, missing exhaustive checks | ✓ |
+| **Security** | Injection, prototype pollution, ReDoS, path traversal, hardcoded secrets | ✓ |
+| **Async Patterns** | Floating promises, race conditions, missing error propagation, `forEach(async...)` | ✓ |
+| **Modernization** | `enum` → `as const`, missing `satisfies`, `using` keyword, `import type` | ✓ |
+| **Code Quality** | Dead code, complexity, duplication, hacky patterns, error handling | ✓ |
+| **Config** | tsconfig.json strict flags, module resolution, deprecated options | ✓ |
+| **Architecture** | Shallow modules, scattered concepts, tight coupling, dependency seams, testability | `--arch` / `--full` |
 
 ## Installation
 
@@ -75,7 +76,29 @@ 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 (or `.claude/code-smells.md` if that directory exists).
+Claude will analyze the project and write a report to `code-smells.md` in the project root.
+
+#### Domain flags
+
+By default, only the six core domains run. Use flags to control which domains are active:
+
+| Flag | What runs |
+|---|---|
+| *(none)* | Type Safety, Security, Async, Modernization, Code Quality, Config |
+| `--arch` | Architecture only (shallow modules, coupling, dependency seams) |
+| `--full` | All seven domains |
+
+Examples:
+
+```
+Review my TypeScript code --arch
+```
+```
+Full audit --full
+```
+```
+Review architecture of this project
+```
 
 ### Fix — apply fixes from the report
 
@@ -136,6 +159,14 @@ Issues on unchanged lines are listed separately as pre-existing tech debt — in
 | **Medium** | Tech debt — clean up when you're already editing that file |
 | **Low** | Style and conventions — improve when convenient |
 
+Architecture findings use the same scale. Each candidate also carries a **Fixability** tag:
+
+| Fixability | Meaning |
+|---|---|
+| `auto` | Applied automatically during fix mode |
+| `needs-confirm` | Shown to you first — only applied after explicit approval |
+| `report-only` | Left as documentation — never auto-applied |
+
 ## Project Structure
 
 ```
@@ -153,21 +184,22 @@ ts-reviewer/
     ├── modernization.md              # Checklist: TS 5.9+ idioms, satisfies, using, as const
     ├── code-quality.md               # Checklist: complexity, dead code, naming, duplication
     ├── tsconfig.md                   # Checklist: strict flags, module resolution, deprecated
+    ├── architecture.md               # Checklist: shallow modules, coupling, seams, deepening
     └── fix-workflow.md               # Complete fix protocol: tests, verification, rollback
 ```
 
-**SKILL.md** (349 lines) is the orchestrator — it routes between scan/fix/auto modes, defines scope detection, severity scale, and report format. It stays under the 500-line recommended limit for Claude skills.
+**SKILL.md** is the orchestrator — it routes between scan/fix/auto modes, detects domain flags (`--arch`, `--full`), defines scope detection, severity scale, and report format.
 
-**Reference files** contain the detailed checklists and protocols. Each analysis agent reads only the reference file relevant to its domain, keeping context focused. The fix workflow is in its own reference file because it's a complex multi-step protocol.
+**Reference files** contain the detailed checklists and protocols. Each analysis agent reads only the reference file relevant to its domain, keeping context focused. Architecture analysis is opt-in and loaded only when the domain is active.
 
 ## How It Works Under the Hood
 
 ### Scan mode
 
-1. **Discovery** — maps the project, reads tsconfig.json, detects linter and test runner
+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/`.
 2. **Diagnostics** — runs `tsc --noEmit`, linter, and LSP diagnostics (if available)
-3. **Analysis** — six specialized passes (sub-agents in Claude Code, sequential in Claude.ai), each with its own checklist
-4. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, writes `code-smells.md`
+3. **Analysis** — specialized passes for each active domain (sub-agents in Claude Code, sequential in Claude.ai), each with its own checklist
+4. **Report** — deduplicates, applies severity boost (scoped modes), consolidates recurring patterns, writes `code-smells.md`. Architecture findings appear in a separate `## Architecture Opportunities` section at the end.
 
 ### Fix mode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-reviewer",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Install the TypeScript Code Reviewer skill for Claude Code, Codex, or Antigravity",
   "license": "MIT",
   "repository": {

package/ts-reviewer/SKILL.md

@@ -1,18 +1,12 @@
 ---
 name: ts-reviewer
 description: >
-  Deep TypeScript code review and auto-fix tool. Three modes: scan (find issues),
-  fix (apply fixes from scan report), auto (scan + fix + verify in one pass).
-  Supports scoped review: full codebase, uncommitted changes, branch diff (PR review),
-  or last N commits. Outputs a prioritized report and can auto-fix issues with
-  regression tests and verification.
-  Use this skill whenever the user asks to "review", "audit", "check", "lint", "find issues",
-  "find problems", "find bugs", "fix issues", "fix code smells", "auto-fix",
-  "review and fix", "clean up code", or "review code quality" in a TypeScript project.
-  Also trigger when the user mentions "tech debt", "code health", "refactor candidates",
-  "security audit", "modernize", "review my changes", "review my PR", "check what I changed",
-  "review last commit", or "review uncommitted" in a TypeScript context. Works with pure
-  TypeScript 5.9+ codebases — no framework-specific checks (React, Vue, Angular, etc.).
+  TypeScript code review and auto-fix. Modes: scan, fix, auto. Scopes: full codebase,
+  uncommitted, branch diff, last N commits. Trigger on: review, audit, check, lint,
+  find issues, find bugs, fix issues, fix code smells, auto-fix, review and fix,
+  clean up code, tech debt, code health, security audit, modernize, review my changes,
+  review my PR, review last commit. Architecture review: --arch, --full, review architecture,
+  find refactoring opportunities, full audit. Pure TypeScript 5.9+ only.
 ---
 
 # TypeScript Code Reviewer
@@ -33,6 +27,22 @@ This skill operates in three modes. Detect the mode from the user's request:
 **`fix`** — Read `code-smells.md` and apply fixes with verification.
 **`auto`** — Run scan, then fix, then re-scan to verify. Delete report if clean.
 
+## Domain Set
+
+Controls which review domains are active. Detected from flags first, then natural-language phrases.
+
+| Flag / phrase | Active domains |
+|---|---|
+| (none / default) | Type Safety, Security, Async Patterns, Modernization, Code Quality, Config |
+| `--arch` / "review architecture" / "find refactoring opportunities" / "deepening review" | Architecture only |
+| `--full` / "full audit" / "full review" / "review everything" | All 7 domains (default 6 + Architecture) |
+
+Parse order: check for explicit `--arch` / `--full` / `--no-arch` flags in the user's message first.
+Fall back to phrase detection. If no flag or phrase matches → default domain set (no architecture).
+
+Architecture domain is **off** in default scans. It loads `references/architecture.md` and adds
+an `## Architecture Opportunities` section to `code-smells.md` only when active.
+
 ## Report File Location
 
 - Always write to `code-smells.md` in the project root (not in `.claude/`)
@@ -145,21 +155,28 @@ git diff -U0 [appropriate range] -- '*.ts' | grep '^@@'
 
 ## Phase 1 — Discovery (scan mode)
 
-1. **Detect scope mode** from user's request. Build file list.
+1. **Detect domain set** from flags and phrases (see Domain Set section above).
+
+2. **Detect scope mode** from user's request. Build file list.
    If scoped mode yields 0 files, ask whether to fall back to full.
 
-2. **Map project tree** — full structure regardless of scope.
+3. **Map project tree** — full structure regardless of scope.
 
-3. **Read `tsconfig.json`**. Load `references/tsconfig.md` and audit config flags.
+4. **Read `tsconfig.json`**. Load `references/tsconfig.md` and audit config flags.
    In scoped modes: only flag config if `tsconfig.json` is in diff or if full review.
 
-4. **Check for linter configs** — `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`.
+5. **Check for linter configs** — `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`.
+
+6. **Read `package.json`** — TS version, dependencies, module type.
 
-5. **Read `package.json`** — TS version, dependencies, module type.
+7. **Identify entry points** — `index.ts`, `main.ts`, exports in `package.json`.
 
-6. **Identify entry points** — `index.ts`, `main.ts`, exports in `package.json`.
+8. **Collect context files** (scoped modes only).
 
-7. **Collect context files** (scoped modes only).
+9. **Architecture discovery** (only if Architecture is in active domain set):
+   - Map module relationships: note circular imports, deep relative imports, barrel-file cycles, feature slices, public entry points.
+   - Check if `docs/adr/` exists — if so, scan it for architectural decisions before proposing changes. Skip silently if absent.
+   - Do NOT require `CONTEXT.md` or any domain-doc files.
 
 Discovery summary:
 ```
@@ -203,6 +220,8 @@ Query TypeScript LSP via MCP if accessible. Merge with compiler output, deduplic
 
 Read the corresponding reference file before each analysis pass.
 
+Run only the agents whose domain is in the active domain set (see Domain Set section).
+
 | Agent | Reference file | Focus |
 |---|---|---|
 | Type Safety | `references/type-safety.md` | `any`, casts, `!`, exhaustiveness, generics |
@@ -211,6 +230,7 @@ Read the corresponding reference file before each analysis pass.
 | Modernization | `references/modernization.md` | Outdated patterns vs TS 5.9+ idioms |
 | Code Quality | `references/code-quality.md` | Complexity, duplication, naming, dead code |
 | Config | `references/tsconfig.md` | tsconfig.json flags and module setup |
+| Architecture | `references/architecture.md` | Shallow modules, scattered concepts, coupling, dependency seams, testability |
 
 ### Sub-agent template (Claude Code)
 
@@ -297,6 +317,23 @@ Write to `code-smells.md`:
 ## Recurring Patterns
 ## Config Issues
 ## Pre-existing Issues (scoped modes only)
+
+## Architecture Opportunities
+(only when Architecture is in active domain set AND at least one candidate found — omit entirely otherwise)
+
+### TITLE — Severity
+
+- **Files:** relative/path/a.ts, relative/path/b.ts
+- **Problem:** why this causes friction now
+- **Proposed deepening:** what would change
+- **Interface shape:** rough sketch of new interface
+- **Dependency category:** in-process | local-substitutable | remote-owned | true-external
+- **Test strategy:** how tests improve
+- **Benefits:** locality, leverage, test impact
+- **Trade-offs:** what gets harder
+- **Fixability:** auto | needs-confirm | report-only
+
+---
 ````
 
 ### Sorting
@@ -337,6 +374,9 @@ Key principles:
 
 In scoped modes: these are base severities before diff-aware boost.
 
+Architecture findings use the same severity scale with domain-specific criteria.
+See `references/architecture.md` → Severity Mapping for Architecture.
+
 ---
 
 ## Important Guidelines

package/ts-reviewer/references/architecture.md

@@ -0,0 +1,118 @@
+# Architecture Review Checklist
+
+Loaded only when architecture review is active (`--arch` or `--full` flag).
+
+## Glossary
+
+Use these terms in all architecture findings. Don't substitute "component", "service", "API", "boundary".
+
+- **Module** — anything with an interface and an implementation: function, class, package, feature slice.
+- **Interface** — everything a caller must know: types, invariants, error modes, ordering, config. Not just the TypeScript `interface` keyword.
+- **Implementation** — the code inside the module.
+- **Depth** — leverage at the interface. Deep = large behaviour behind small interface. Shallow = interface nearly as complex as implementation.
+- **Seam** — where the interface lives; a place behaviour can be altered without editing in place. Prefer over "boundary".
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Leverage** — what callers get from depth: more capability per unit of interface they must learn.
+- **Locality** — what maintainers get from depth: change, bugs, and knowledge concentrated in one place.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally complex — what matters is how small its interface is relative to what it hides.
+- **Deletion test.** Imagine deleting the module. If complexity vanishes → it was a pass-through. If complexity reappears across callers → it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If tests must reach past the interface into internals, the module is the wrong shape.
+- **One adapter = hypothetical seam. Two adapters = real seam.** Don't introduce a port unless at least two adapters are justified (production + test at minimum). Single-adapter seams are just indirection.
+
+## Smell Checklist
+
+### Shallow Modules
+
+- Understanding one concept requires bouncing across many tiny modules. Severity: **Medium**.
+- Module interface is nearly as complex as its implementation (shallow). Severity: **Medium**.
+- Pass-through wrapper / manager / helper / service that adds no hidden complexity. Severity: **Medium**. Apply deletion test.
+- Pure functions extracted only for testability, but real bugs hide in orchestration — no locality. Severity: **Medium**.
+
+### Coupling and Boundaries
+
+- Tight coupling leaks across module interfaces (callers must know implementation details). Severity: **High**.
+- Tests must reach into module internals or mock too many neighbors to test one thing. Severity: **High**.
+- Public API exports implementation details, config, ordering constraints, or internal error modes that callers should not need to know. Severity: **Medium**.
+
+### Import and Module Structure
+
+*Note: circular imports and deep relative imports are also flagged by the Code Quality domain in all scan modes. Architecture domain provides deeper refactoring guidance when Code Quality flags them.*
+
+- Barrel-file cycles or circular import chains that can't be resolved by reordering. Severity: **High**.
+- Deep relative imports (`../../../`) indicating modules not co-located with what they depend on. Severity: **Low**. Suggest path aliases or co-location.
+
+### Locality
+
+- Shared utility module mixes unrelated domain concepts (a grab-bag util). Severity: **Medium**.
+- Feature logic split by technical layer (e.g. controller / service / repo per feature) in a way that destroys locality — change to one feature requires touching 4+ files. Severity: **Medium**.
+
+## Dependency Classification
+
+When proposing a deepening fix, classify the dependency to determine test strategy:
+
+**1. In-process** — pure computation or in-memory state, no I/O.
+- Strategy: merge modules, test through the deepened interface directly. No adapter needed.
+
+**2. Local-substitutable** — DB, filesystem, etc. with usable local stand-ins (PGLite, in-memory filesystem).
+- Strategy: deepen using the stand-in in tests. The seam is internal; no port at the external interface.
+
+**3. Remote but owned** — internal services across a network boundary.
+- Strategy: define a port (TypeScript interface) at the seam. Production adapter + in-memory adapter for tests.
+- The deep module owns the logic; only the transport is injected.
+
+**4. True external** — third-party services (Stripe, Twilio, etc.) you don't control.
+- Strategy: inject a port; provide a mock adapter for tests.
+
+**Rule:** don't introduce a port unless at least two adapters are justified. A single-adapter seam is indirection without benefit.
+
+## Candidate Report Format
+
+Each architecture finding uses this format in the `## Architecture Opportunities` section:
+
+```md
+### TITLE — Severity
+
+- **Files:** relative/path/a.ts, relative/path/b.ts
+- **Problem:** why this causes friction now (not just a pattern name)
+- **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
+- **Test strategy:** how tests would improve (what tests survive, what gets deleted, what's new)
+- **Benefits:** locality gained, leverage gained, test impact
+- **Trade-offs:** what gets harder, what is genuinely uncertain
+- **Fixability:** auto | needs-confirm | report-only
+```
+
+## Severity Mapping for Architecture
+
+| Level | Architecture criteria |
+|---|---|
+| **Highest** | Architecture issue directly causing a security vulnerability, data loss, or production correctness bug |
+| **High** | Circular imports or cross-module coupling that blocks reliable tests or causes recurring defects |
+| **Medium** | Shallow modules, scattered domain logic, pass-through abstractions, hard-to-test orchestration |
+| **Low** | Small interface leaks, minor naming drift between module interface and what it exposes |
+
+## Fixability Mapping
+
+| Fixability | Meaning | Fix mode behavior |
+|---|---|---|
+| `auto` | Local change: import path cleanup, narrow circular-import break, local module merge with co-located tests | Applied in normal fix loop |
+| `needs-confirm` | Interface change, dependency inversion, test replacement, feature-slice reorganization | Shown to user, NOT applied automatically |
+| `report-only` | Broad migration, ambiguous domain model, change requiring product/domain decision | Never applied, left as documentation |
+
+## Naming Guidance
+
+Use names that already exist in the codebase (function names, type names, file names, package names). Don't invent domain terms. If a deepened module needs a name, prefer a name already used in adjacent code.
+
+## Architecture Fix Rules
+
+When applying `auto` fixability architecture findings:
+
+- Write new tests at the deepened module's interface. Old unit tests on shallow modules that are now merged become redundant — delete them.
+- Tests assert observable behavior through the interface, not internal state.
+- Don't expose internal seams through the interface just because tests need them.
+- Tests that have to change when the implementation changes are testing past the interface.
+- For large architecture changes classified `needs-confirm`, show a diff/migration plan and wait for explicit go-ahead before touching code.

package/ts-reviewer/references/code-quality.md

@@ -67,6 +67,9 @@
 - Circular imports. Severity: **High**.
 - Deep relative imports (`../../../`). Severity: **Low**. Fix: path aliases.
 
+For deeper architectural refactors (shallow modules, dependency seams, module deepening, coupling),
+load `references/architecture.md` — available only when architecture review is enabled (`--arch` or `--full`).
+
 ## Comments
 
 - JSDoc repeating the type info. Severity: **Low**.

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

@@ -298,6 +298,34 @@ After fix completes:
 
 ---
 
+## Architecture Fixes
+
+Architecture findings in the `## Architecture Opportunities` section carry a `Fixability:` field.
+Fix mode behavior is determined by that field:
+
+| Fixability | Fix mode behavior |
+|---|---|
+| `auto` | Apply in normal fix loop. Run `tsc --noEmit` after each file as usual. |
+| `needs-confirm` | Surface to user with a diff/migration plan. Do NOT apply automatically. Wait for explicit go-ahead. |
+| `report-only` | Never apply. Leave in report as documentation. Mark `[SKIPPED: report-only]`. |
+
+### Testing strategy for architecture fixes
+
+When applying an `auto` architecture fix (module merge, import path cleanup, narrow circular-import break):
+
+1. Write new tests at the **deepened module's interface** — test observable behavior, not internal state.
+2. Delete old unit tests that tested the shallow modules being merged — they become redundant once the deeper module's interface tests cover the same behavior.
+3. Tests must survive internal refactors. If a test must change when implementation changes, it's testing past the interface.
+4. Don't expose internal seams through the module interface just to make tests easier to write.
+
+### `needs-confirm` flow
+
+1. Show the user what would change (describe the reorganization or interface change).
+2. If the user approves, apply the fix using the same file-by-file + `tsc` verification loop.
+3. If the user rejects, mark the finding `[SKIPPED: user rejected]` in the report and move on.
+
+---
+
 ## Fix Safety Rules
 
 1. **NEVER commit or stage.** The user reviews and decides.