ts-reviewer 1.1.0 → 1.2.0

package/package.json

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

package/ts-reviewer/SKILL.md

@@ -33,9 +33,9 @@ Controls which review domains are active. Detected from flags first, then natura
 
 | Flag / phrase | Active domains |
 |---|---|
-| (none / default) | Type Safety, Security, Async Patterns, Modernization, Code Quality, Config |
+| (none / default) | Type Safety, Security, Async Patterns, Modernization, Code Quality, Config, Boundary Validation, Error Handling, Dependency Hygiene |
 | `--arch` / "review architecture" / "find refactoring opportunities" / "deepening review" | Architecture only |
-| `--full` / "full audit" / "full review" / "review everything" | All 7 domains (default 6 + Architecture) |
+| `--full` / "full audit" / "full review" / "review everything" | All 10 domains (default 9 + 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).
@@ -104,30 +104,34 @@ If not specified, default to **full codebase**.
 
 ### Git commands per scope
 
-**`full`** — all `.ts` files:
+**`full`** — all TypeScript files:
 ```bash
-npx glob '**/*.ts' --ignore '**/node_modules/**'
-# or: git ls-files '*.ts'
+npx glob '**/*.{ts,mts,cts}' --ignore '**/node_modules/**'
+# or: git ls-files '*.ts' '*.mts' '*.cts'
 ```
 
 **`uncommitted`** — staged + unstaged + untracked:
 ```bash
-git diff --name-only HEAD -- '*.ts'
-git ls-files --others --exclude-standard -- '*.ts'
+git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
+git ls-files --others --exclude-standard -- '*.ts' '*.mts' '*.cts'
 ```
 
 **`branch`** — current branch vs base:
 ```bash
 BASE=$(git rev-parse --verify main 2>/dev/null && echo main || echo master)
-git diff --name-only "$BASE"...HEAD -- '*.ts'
-git diff --name-only HEAD -- '*.ts'
+git diff --name-only "$BASE"...HEAD -- '*.ts' '*.mts' '*.cts'
+git diff --name-only HEAD -- '*.ts' '*.mts' '*.cts'
 ```
 
 **`commits:N`** — last N commits:
 ```bash
-git diff --name-only HEAD~N..HEAD -- '*.ts'
+git diff --name-only HEAD~N..HEAD -- '*.ts' '*.mts' '*.cts'
 ```
 
+**File type policy:** `.mts`/`.cts` are reviewed like `.ts`. `.d.ts` files are reviewed
+only by the Type Safety and Config domains (declarations have no runtime behavior).
+`.tsx` is out of scope — pure TypeScript only, no frameworks.
+
 ### Context files (scoped reviews)
 
 Analysis scope = diff file list. Reading scope = wider. Always include as read-only:
@@ -143,7 +147,7 @@ Context files are NOT analyzed for issues.
 
 Collect changed hunks:
 ```bash
-git diff -U0 [appropriate range] -- '*.ts' | grep '^@@'
+git diff -U0 [appropriate range] -- '*.ts' '*.mts' '*.cts' | grep '^@@'
 ```
 
 - Issue on **new/modified line**: boost severity +1 (Low→Medium, Medium→High, High→Highest)
@@ -164,6 +168,9 @@ git diff -U0 [appropriate range] -- '*.ts' | grep '^@@'
 
 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.
+   Monorepos: detect workspaces (`workspaces` in package.json, `pnpm-workspace.yaml`) and
+   multiple tsconfigs (`tsconfig.build.json`, per-package configs, `references`). Audit the
+   config that actually governs the files in scope; note which config applies in the summary.
 
 5. **Check for linter configs** — `eslint.config.*`, `.eslintrc.*`, `biome.json`, `deno.json`.
 
@@ -200,7 +207,11 @@ Files in scope: <N> .ts files (+ <M> context files)
 npx tsc --noEmit 2>&1 | head -200
 ```
 
-Compiler errors -> **Highest**. Warnings -> **High**.
+All output lines are errors (tsc emits no warnings). Triage each error:
+- Indicates a runtime hazard (null/undefined access, wrong argument shape,
+  missing property) -> **Highest**
+- Hygiene errors (unused locals, unreachable code, implicit any on internals) -> **High**
+
 In scoped modes: run on full project, report only errors in scoped files.
 
 ### 2b. Linter
@@ -208,7 +219,11 @@ In scoped modes: run on full project, report only errors in scoped files.
 ESLint: `npx eslint [files] --format json 2>/dev/null | head -500`
 Biome: `npx biome check [files] --reporter json 2>/dev/null | head -500`
 
-Map: `error` -> **High**, `warning` -> **Medium**, `info` -> **Low**.
+Map linter severities conservatively — projects configure stylistic rules as `error`:
+- Rule matches a checklist item in a reference file -> use the checklist severity
+- Correctness-class rule (`no-floating-promises`, `no-misused-promises`,
+  `no-unsafe-*`) -> **High**
+- Anything else: `error` -> **Medium**, `warning` -> **Low**, `info` -> **Low**
 
 ### 2c. LSP diagnostics (if available)
 
@@ -228,9 +243,12 @@ Run only the agents whose domain is in the active domain set (see Domain Set sec
 | Security | `references/security.md` | Injection, prototype pollution, ReDoS, path traversal |
 | Async Patterns | `references/async-patterns.md` | Floating promises, race conditions, error propagation |
 | Modernization | `references/modernization.md` | Outdated patterns vs TS 5.9+ idioms |
-| Code Quality | `references/code-quality.md` | Complexity, duplication, naming, dead code |
+| Code Quality | `references/code-quality.md` | Complexity, duplication, naming, dead code, testability |
 | Config | `references/tsconfig.md` | tsconfig.json flags and module setup |
-| Architecture | `references/architecture.md` | Shallow modules, scattered concepts, coupling, dependency seams, testability |
+| Boundary Validation | `references/boundary-validation.md` | Runtime validation at system edges, DTO/domain separation |
+| Error Handling | `references/error-handling.md` | Silent failures, throw hygiene, failure design |
+| Dependency Hygiene | `references/dependency-hygiene.md` | package.json, versions, lockfiles, supply chain |
+| Architecture | `references/architecture.md` | Shallow modules, scattered concepts, coupling, dependency seams, layering |
 
 ### Sub-agent template (Claude Code)
 
@@ -253,7 +271,7 @@ Output JSONL, one object per line:
   "fix": "Concrete recommendation with code example",
   "auto_fixable": true|false,
   "in_diff": true|false,
-  "reference": "URL or docs ref"
+  "reference": "optional — omit unless allowed by the Evidence Protocol"
 }
 ```
 
@@ -274,8 +292,11 @@ Go through each domain one at a time. Same JSON structure.
 
 1. Apply severity boost (scoped modes only): `in_diff: true` -> boost +1 level.
 2. Deduplicate: same file + line + issue -> keep one.
-3. Merge overlapping: keep higher severity, note overlap.
+3. Merge overlapping: keep higher severity, note overlap. If two domains flag the same
+   file + line, merge into one entry attributing both categories — never emit twice.
 4. Consolidate patterns: 3+ identical issues -> one "Recurring Pattern" entry.
+5. Noise budget: if a single domain produces > 25 Medium/Low findings, keep its top 15
+   by severity and impact, consolidate the rest into Recurring Pattern entries with counts.
 
 ### Report structure
 
@@ -289,7 +310,7 @@ Write to `code-smells.md`:
 **TypeScript version:** <version>
 **Scope:** Full / Uncommitted / Branch `x` vs `y` / Last N commits
 **Files analyzed:** N (+ M context)
-**Total issues:** N (X critical, Y high, Z medium, W low)
+**Total issues:** N (X highest, Y high, Z medium, W low)
 **Severity-boosted:** N (scoped modes only)
 
 ## Summary
@@ -379,11 +400,38 @@ See `references/architecture.md` → Severity Mapping for Architecture.
 
 ---
 
+## Evidence Protocol
+
+Every finding must survive verification before it enters the report:
+
+1. **Re-read before reporting.** After drafting a finding, re-read the exact lines in the
+   current file state. The `snippet` must appear verbatim at the stated `line` (±2 lines).
+   If it doesn't, re-locate or drop the finding.
+2. **Check the surrounding context.** If a guard, validation, type narrowing, or comment
+   within the enclosing function/module already handles the case, the finding is a false
+   positive — drop it, don't downgrade it.
+3. **Confidence gate.** Report only findings you can defend with the code in front of you.
+   If a finding depends on runtime behavior you cannot see (external input actually reaching
+   a sink, concurrent callers actually existing), either verify the data flow by reading the
+   callers, or mark the finding's problem statement with "if <condition>" and cap severity
+   at Medium.
+4. **References must be real.** The `reference` field is optional. Only cite
+   typescriptlang.org, developer.mozilla.org, nodejs.org, or a file path inside this skill.
+   Never construct URLs from memory for anything else — omit the field instead.
+5. **Convention override.** If a flagged non-High pattern appears consistently 5+ times
+   across the codebase, treat it as an intentional convention: downgrade one severity level
+   and report it once as a Recurring Pattern, not per occurrence.
+6. **Version gate.** Every finding that recommends newer syntax or APIs must state the
+   minimum TS/runtime version required, verified against the project's actual TS version,
+   `target`/`lib`, and runtime. Never recommend a feature the project cannot use.
+
+---
+
 ## Important Guidelines
 
 - **No framework checks.** Pure TypeScript only.
-- **No false positives from intentional patterns.** `// @ts-expect-error` with explanation = Low.
-  `// @ts-ignore` (legacy) = Medium. Without explanation = Medium.
+- **No false positives from intentional patterns.** Suppression-directive severities are
+  owned by `references/type-safety.md` (Suppression Directives) — follow it, don't improvise.
 - **Respect project conventions.** Don't flag consistent patterns unless harmful.
 - **Be concrete.** Every issue needs a snippet and a fix recommendation.
   "Consider refactoring" is not a valid fix.

package/ts-reviewer/references/architecture.md

@@ -49,6 +49,46 @@ Use these terms in all architecture findings. Don't substitute "component", "ser
 - 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**.
 
+### Under-Engineering
+
+Depth cuts both ways — flag missing abstraction where it already hurts:
+
+- Identical business rule (same constants/branching) implemented in 2+ modules.
+  Severity: **Medium**. Under-abstraction; deepen one module to own the rule.
+- One module accreting unrelated concerns (imports from many unrelated domains, exports
+  serving disjoint caller groups). Severity: **Medium**. Split along caller groups.
+- Event/string-keyed indirection between two modules that only ever talk to each other —
+  a direct typed call would be simpler and checkable. Severity: **Low**.
+
+## Dependency Direction and Layering
+
+Direction matters more than layer count. Detect and flag:
+
+- Domain/computation modules importing IO directly (`node:fs`, `node:http`, DB clients,
+  `fetch`) when the dependency classification says the IO belongs behind a seam.
+  Severity: **Medium**. The domain owns logic; transport/storage is injected or
+  isolated at the edge.
+- Shared/leaf modules (`utils/`, `types/`, `core/`) importing from feature modules —
+  inverted direction; the "shared" code now depends on a specific feature.
+  Severity: **High** — this is how import cycles start.
+- Wire/DTO types from an external API imported deep into domain modules rather than
+  mapped to domain types at the boundary. Severity: **Medium**.
+  Cross-reference: `references/boundary-validation.md`.
+
+## Detection Heuristics
+
+Run these — don't guess from file names:
+
+- Grep feature-module imports inside `shared|common|core|utils` directories
+  (inverted dependency direction).
+- For each module, list its importers. A module whose every export has exactly one
+  importer is a pass-through candidate — apply the deletion test.
+- An interface/type re-exported through 3+ files unchanged marks a pass-through chain.
+- A utility file imported by the majority of modules is a grab-bag candidate — check
+  whether its exports share a domain concept.
+- Change-set locality: in `git log --name-only`, do commits touching one feature
+  consistently touch 4+ directories? That feature's logic is scattered.
+
 ## Dependency Classification
 
 When proposing a deepening fix, classify the dependency to determine test strategy:

package/ts-reviewer/references/async-patterns.md

@@ -13,19 +13,59 @@
 
 ## Error Handling
 
-- `catch(e)` without typing as `unknown` (requires `useUnknownInCatchVariables`).
-  Severity: **Medium**.
-- Empty catch blocks: `catch(e) {}`. Severity: **High** (unless commented).
-- `catch` that only logs without rethrowing. Severity: **Medium**.
-- `Promise.allSettled()` ignoring `'rejected'` entries. Severity: **Medium**.
+All catch/throw/failure-design checks live in `references/error-handling.md` — do not
+duplicate them here. This domain only flags errors *lost to the async machinery*
+(floating promises above, allSettled below).
 
 ## Race Conditions
 
 - Multiple async ops modifying shared state without coordination.
-  Severity: **High**.
+  Severity: **High**. Fix: serialize via a promise chain / async mutex, or make the
+  operations idempotent so ordering doesn't matter.
 - `Promise.race()` where losing promise's side effects still execute.
   Severity: **Medium**.
 - Read-modify-write with `await` in the middle. Severity: **High** in concurrent contexts.
+- Overlapping requests writing to the same variable/state where the earlier response
+  can arrive last (last-write-wins clobbering). Severity: **High** in concurrent contexts.
+  Fix: request-sequence token check before applying the result, or abort the previous
+  request via AbortController.
+- Lazily-initialized async singleton where concurrent first callers each run the
+  initializer. Severity: **Medium**. Fix: memoize the *promise*, not the resolved value:
+  `init ??= doInit(); return init;`
+
+## Timeouts
+
+- `await` on network/IO (fetch, DB call, queue op) with no timeout and no AbortSignal.
+  Severity: **Medium** (internal tools), **High** (request-handling / server paths —
+  a hung dependency hangs every caller).
+  Fix: `fetch(url, { signal: AbortSignal.timeout(5000) })`, or `Promise.race` with a
+  timer for APIs without signal support (clear the timer in `finally`).
+- Timeout implemented with `Promise.race` but the losing operation keeps running and
+  holds resources (sockets, locks). Severity: **Medium**. Fix: abort the operation,
+  don't just abandon the promise.
+
+## Retries
+
+- Retry loop without a max-attempt cap. Severity: **High** (infinite loop under
+  persistent failure).
+- Retries without backoff (tight loop hammering a failing dependency). Severity: **Medium**.
+  Fix: exponential backoff with jitter.
+- Retrying a non-idempotent operation (payment, email send, resource creation).
+  Severity: **Highest** — duplicate side effects. Fix: idempotency key or check-then-act
+  on the server side; otherwise don't retry.
+
+## Concurrency Limits
+
+- `Promise.all(items.map(asyncFn))` where `items` is unbounded (user data, file lists,
+  API pages) and `asyncFn` does network/disk work. Severity: **Medium**.
+  Fix: process in chunks or use a concurrency limiter. Do NOT recommend converting
+  sequential awaits to unbounded `Promise.all` — recommend it only with an explicit
+  concurrency cap when the collection can exceed ~10 items.
+- `Promise.all` where one rejection should not discard sibling results, or where
+  siblings' later rejections become unhandled. Severity: **Medium**.
+  Fix: `Promise.allSettled` + explicit handling of `rejected` entries.
+- `Promise.allSettled()` results used without checking `status === 'rejected'` entries.
+  Severity: **Medium**.
 
 ## Cancellation
 
@@ -47,8 +87,10 @@
 - `async function() { return await bar(); }` — unnecessary await (except in try/catch).
   Severity: **Low**.
 - Mixing `await` and `.then()` chains in same function. Severity: **Low**.
-- Sequential `await` in loop when iterations are independent.
-  Severity: **Medium**. Fix: `Promise.all(items.map(...))` if order doesn't matter.
+- Sequential `await` in loop when iterations are independent AND the collection is small
+  and bounded (< ~10 known items). Severity: **Medium**. Fix: `Promise.all(items.map(...))`.
+  If the collection is unbounded or does network/disk work, require a concurrency cap
+  instead — see Concurrency Limits.
 
 ## Async Iterators
 

package/ts-reviewer/references/boundary-validation.md

@@ -0,0 +1,56 @@
+# Boundary Validation Checklist
+
+Runtime boundaries and data contracts: the places where untyped data from outside the
+process becomes typed. Design rule — **parse, don't validate**: one place where external
+data is checked and converted into a typed value, after which no re-checking anywhere.
+The compiler only knows what happens inside the process; every claim about outside data
+is a promise the code must earn at the boundary.
+
+## Lying to the Compiler at Boundaries
+
+- `as T` (or a typed variable annotation) on `JSON.parse(...)`, `await res.json()`,
+  `process.env.X`, CLI args, queue/socket messages, file contents.
+  Severity: **High** — the canonical unverified-boundary pattern; the type is a wish.
+  Fix: validate at the boundary with a schema (Zod/Valibot/ArkType/ajv) or a hand-written
+  guard, then use the *inferred* type from the schema.
+- `fetch` wrapper generic `get<T>(url): Promise<T>` that casts internally — moves the
+  lie into a helper every caller trusts. Severity: **High**.
+- Validation library already in dependencies while boundaries still cast.
+  Severity: **Medium** — the tool exists; wire it in.
+
+## Environment and Config
+
+- `process.env.X` read scattered through the codebase (with `!` or `as string`).
+  Severity: **Medium**. Fix: validate all env vars once at startup into a typed,
+  frozen config object; everything else imports the config.
+- Missing-required-config discovered deep at first use instead of at startup.
+  Severity: **Medium** — fail fast at boot with a clear message.
+
+## DTO / Domain Separation
+
+- External wire types (API response shapes, DB row types, third-party SDK types)
+  imported into deep domain modules and used as the domain model. Severity: **Medium** —
+  couples core logic to a contract someone else can change; renames/nullability ripple
+  everywhere. Fix: map wire types to domain types at the boundary module; domain code
+  never imports wire types.
+- Internal entities returned directly as API responses (response shaping by leaking the
+  storage/domain object). Severity: **Medium** — leaks fields added later, couples wire
+  format to storage. Fix: explicit response DTO + mapping at the edge.
+
+## Contract Visibility
+
+- Public API boundary (exported package function, HTTP handler, message consumer) whose
+  input constraints exist only as runtime checks deep inside — not visible in the
+  signature or schema. Severity: **Medium**. Fix: schema/type at the boundary is the
+  contract; derive both the static type and the runtime validation from it.
+- Two independent definitions of the same contract (a TypeScript type AND a separate
+  schema, maintained by hand in parallel). Severity: **Medium** — they will drift.
+  Fix: derive the type from the schema (`z.infer`) or generate both from one source.
+
+## Non-Findings
+
+- Do NOT flag missing validation on data that never leaves the process (internal
+  function calls, module-to-module) — that's what static types are for. Boundary
+  validation at every layer is over-engineering, not safety.
+- Do NOT demand a specific validation library; hand-written guards are fine when the
+  shape is small. Flag the missing check, not the missing dependency.

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

@@ -14,6 +14,8 @@
 - Commented-out code blocks (> 2-3 lines). Severity: **Low**. Fix: delete (VCS has history).
 - Unused private class members. Severity: **Low**.
 - Exported symbols never imported anywhere. Severity: **Medium**.
+  Exception: symbols re-exported from package entry points or the `exports` map are the
+  public API surface of a library, not dead code — do not flag.
 - Empty files or import-only files. Severity: **Low**.
 - Defined but never called functions. Severity: **Medium**.
 
@@ -23,15 +25,48 @@
 - Single-letter variables outside trivial loops. Severity: **Low**.
 - Inconsistent conventions (mixing camelCase/snake_case). Severity: **Low**.
 - Booleans without `is`/`has`/`should`/`can` prefix. Severity: **Low**.
+  Report once per codebase as a Recurring Pattern, never per variable.
 - Opaque abbreviations (`usr`, `msg`, `cfg`). Severity: **Low**.
 
 ## Error Handling
 
-- Throwing raw strings. Severity: **Medium**. Fix: `throw new Error(...)`.
-- Custom errors not extending `Error`. Severity: **Medium**.
-- Error messages without context. Severity: **Low**.
-- Missing `cause` chaining (ES2022):
-  `catch(e) { throw new Error("msg", { cause: e }); }`. Severity: **Low**.
+All error-handling checks live in `references/error-handling.md` — do not duplicate here.
+
+## Debug Artifacts
+
+- `debugger;` statement in committed code. Severity: **High** — blocks execution under
+  devtools; never ship.
+- Leftover `console.log`/`console.debug` from debugging sessions (dumps of local
+  variables, "here", "test") in non-CLI code. Severity: **Low**; **Medium** in library
+  code. Don't flag intentional logging or CLI output.
+- Committed `.only` / `.skip` in test files. Severity: **High** — `.only` silently
+  disables the rest of the suite.
+
+## Import-time Side Effects
+
+- Module top-level code performing IO, registrations, or global mutation while the
+  module also exports pure logic. Severity: **Medium** — makes the module untestable
+  and load-order-dependent. Fix: move behind an explicit `init()` or the entry point.
+- Singleton constructed at module scope and imported everywhere. Severity: **Medium** —
+  hidden shared state; nothing can substitute it in tests.
+
+## Testability
+
+- `Date.now()` / `new Date()` / `Math.random()` inline in business logic.
+  Severity: **Medium** — untestable nondeterminism. Fix: inject a clock/rng, or accept
+  the value as a parameter with a default.
+- Logic reachable only through static call chains that cannot be substituted in tests.
+  Severity: **Low**; escalate to **Medium** if tests already work around it with
+  module-mocking hacks.
+
+## Speculative Abstraction
+
+Lightweight over-engineering checks, active in default scans. For the full framework
+(deletion test, seams, depth) load `references/architecture.md` (`--arch` / `--full`).
+
+- Interface with exactly one implementation and no test double using it. Severity: **Low**.
+- Factory/builder for a class constructed in exactly one place. Severity: **Low**.
+- Config option/parameter whose value is identical at every call site. Severity: **Low**.
 
 ## Duplication
 
@@ -63,8 +98,8 @@
 
 ## Module Structure
 
-- Barrel files causing circular dependencies. Severity: **Low** to **Medium**.
-- Circular imports. Severity: **High**.
+- Circular imports (including cycles through barrel files). Severity: **High**.
+  A barrel file that causes no cycle is not a finding by itself.
 - Deep relative imports (`../../../`). Severity: **Low**. Fix: path aliases.
 
 For deeper architectural refactors (shallow modules, dependency seams, module deepening, coupling),

package/ts-reviewer/references/dependency-hygiene.md

@@ -0,0 +1,47 @@
+# Dependency Hygiene Checklist
+
+Audits `package.json`, lockfiles, and the dependency graph. `package.json` is already
+read in Phase 1 — reuse it. Run the cheap machine checks; don't guess.
+
+## Machine Checks (run these)
+
+```bash
+npm audit --json 2>/dev/null | head -100   # or: pnpm audit / yarn npm audit / bun audit
+npm outdated 2>/dev/null | head -50
+```
+
+- Known critical/high advisories in production dependencies. Severity: **High**
+  (Highest if the vulnerable API is actually called in scoped files).
+- Advisories in devDependencies only. Severity: **Low** — build-time exposure.
+- For unused-dependency detection, recommend `knip` or `depcheck` in the report rather
+  than guessing from grep — imports via configs and bins produce false positives.
+
+## package.json Structure
+
+- No lockfile committed (`package-lock.json`/`pnpm-lock.yaml`/`yarn.lock`/`bun.lock`).
+  Severity: **High** — unreproducible installs.
+- Wildcard or `latest` version ranges in dependencies. Severity: **High**.
+- Runtime packages in `devDependencies` (or types/build tools in `dependencies`).
+  Severity: **Medium** — breaks production installs / bloats them.
+- Missing `engines.node` when the code uses version-gated APIs (`AbortSignal.timeout`,
+  `structuredClone`, `using`). Severity: **Low**.
+- Library packages: missing or inconsistent `exports` map vs `main`/`types`
+  (deep imports unblocked, types not resolving under `nodenext`). Severity: **Medium**.
+
+## Dependency Choice
+
+- Duplicate-purpose dependencies (two HTTP clients, two date libs, lodash + ramda).
+  Severity: **Medium** — pick one; note which is less used.
+- Dependency whose installed version is deprecated on npm, or package abandoned with a
+  well-known maintained successor. Severity: **Medium**. Only claim deprecation when
+  `npm outdated`/`npm audit` output or the package's own warnings show it — do not
+  assert abandonment from memory.
+- Trivial dependency replaceable by a few lines or a built-in (left-pad class:
+  `is-odd`, `mkdirp` on Node 10+, `rimraf` vs `fs.rm`). Severity: **Low**.
+
+## Non-Findings
+
+- Do NOT flag version ranges (`^`/`~`) with a lockfile present — that's the normal model.
+- Do NOT recommend adding dependencies to fix findings from other domains unless the
+  checklist item explicitly names one.
+- Do NOT flag a dependency as outdated for being behind by a patch/minor version.

package/ts-reviewer/references/error-handling.md

@@ -0,0 +1,49 @@
+# Error Handling Checklist
+
+Owns all error-handling checks. `code-quality.md` and `async-patterns.md` link here.
+Errors lost specifically to async machinery (floating promises) stay in async-patterns.md.
+
+## Silent Failures
+
+- Empty catch block `catch (e) {}` without an explanatory comment. Severity: **High**.
+- `catch` that only logs and continues, in a code path whose caller assumes success.
+  Severity: **Medium** (High if the swallowed error leaves state partially mutated).
+- `Promise.allSettled()` results used without checking `status === 'rejected'` entries.
+  Severity: **Medium**.
+- Fire-and-forget cleanup (`void cleanup()`) whose failure corrupts subsequent runs.
+  Severity: **Medium**.
+
+## Throw Hygiene
+
+- Throwing non-Error values (strings, objects). Severity: **Medium**.
+  Fix: `throw new Error(...)` — stack traces and `instanceof` depend on it.
+- Custom error classes not extending `Error`. Severity: **Medium**.
+- Rethrow that discards the original: `catch (e) { throw new Error(msg) }`.
+  Severity: **Medium**. Fix: `throw new Error(msg, { cause: e })` (ES2022).
+- Error messages without operational context (what operation, what input id).
+  Severity: **Low**.
+
+## Catch Discipline
+
+- Broad `catch` around a large block treating programmer errors (TypeError,
+  ReferenceError) the same as expected failures — hides bugs as handled conditions.
+  Severity: **Medium**. Fix: narrow the try to the failing operation; re-throw
+  unexpected error types.
+- `catch (e)` where `e` is used as if typed (`e.message` without narrowing) —
+  see type-safety.md `unknown` Discipline. If the project lacks
+  `useUnknownInCatchVariables`, flag the config (tsconfig.md), not every catch site.
+
+## Failure Design (public APIs and module seams)
+
+- Expected, recoverable outcomes (not-found, validation failure, conflict) signaled by
+  `throw` so every caller needs try/catch for normal control flow. Severity: **Medium**.
+  Fix: return a discriminated result: `{ ok: true, value } | { ok: false, error }` —
+  exhaustiveness-checkable, contract visible in the signature. Keep `throw` for
+  unexpected/unrecoverable failures.
+- Exported function's failure modes not derivable from its signature or docs — callers
+  can't discriminate errors except by message string matching. Severity: **Medium**.
+  Fix: typed error classes or result unions; never promise message-string stability.
+- Matching on `e.message` content to branch behavior. Severity: **High** — breaks on
+  any wording change.
+- `process.exit()` inside library/domain code. Severity: **High** — only entry points
+  may decide to terminate.

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

@@ -35,7 +35,7 @@ Check for test runner in this order:
 
 | Signal | Runner | Command |
 |---|---|---|
-| `package.json` has `"scripts": { "test": "..." }` | npm script | `npm test` |
+| `package.json` has `"scripts": { "test": "..." }` AND the script is not the npm placeholder (`echo "Error: no test specified" && exit 1`) | npm script | `npm test` (use `pnpm test` / `yarn test` if a pnpm/yarn lockfile is present) |
 | `vitest.config.*` exists | vitest | `npx vitest run` |
 | `jest.config.*` or `"jest"` in package.json | jest | `npx jest` |
 | `*.test.ts` / `*.spec.ts` + `"mocha"` in devDeps | mocha | `npx mocha` |
@@ -57,8 +57,11 @@ Also detect the test file naming convention:
 
 Run the full test suite BEFORE any changes:
 ```bash
-<test_command> 2>&1 | tee .claude/ts-reviewer-baseline.log
+<test_command> 2>&1 | tee "$TMPDIR/ts-reviewer-baseline.log"
 ```
+Write logs to the OS temp directory (or the project root if temp is unavailable —
+recommend gitignoring them). Do NOT write to `.claude/` — the skill must work in
+non-Claude environments and the directory may not exist.
 
 Record:
 - Total tests: N
@@ -112,6 +115,8 @@ Regression test conventions:
   });
   ```
 - Keep tests focused and minimal — test the specific fix, not the entire function
+- Tell the user these files are candidates to rename and merge into their existing
+  suites — the `.reviewer-fixes` naming is a handoff convention, not a permanent home
 
 ### 4c. Run tsc after each file
 
@@ -119,6 +124,9 @@ Regression test conventions:
 npx tsc --noEmit 2>&1
 ```
 
+On large repos (> ~30 files in the work plan) where a full typecheck is slow, use
+`npx tsc --noEmit --incremental` or batch the check every 3-5 files instead of every file.
+
 If `tsc` reports NEW errors in the file we just fixed or in files affected by our changes:
 - Analyze the errors
 - Fix them immediately (they are likely caused by our refactoring — e.g., type changes
@@ -151,7 +159,7 @@ If linter reports errors in files we changed:
 
 Run the full test suite:
 ```bash
-<test_command> 2>&1 | tee .claude/ts-reviewer-postfix.log
+<test_command> 2>&1 | tee "$TMPDIR/ts-reviewer-postfix.log"
 ```
 
 Compare with baseline:
@@ -340,8 +348,12 @@ When applying an `auto` architecture fix (module merge, import path cleanup, nar
    Fix exactly what the report says, nothing more.
 6. **If uncertain, skip.** If a fix is ambiguous or risky, mark it as
    `[SKIPPED: requires manual review]` and move on. Better to skip than to break.
-7. **Revert individual fixes with `git checkout -- <file>`** before the fix was applied,
-   then re-apply only the safe fixes. Use `git diff` to identify what changed in a file.
+7. **Snapshot before touching, restore to revert.** Before applying the first fix to a
+   file, save its exact current content (copy to a temp/scratch directory, keyed by
+   path). To revert a fix, restore the file from that snapshot and re-apply only the
+   fixes that were verified safe. NEVER use `git checkout -- <file>` or `git restore` —
+   the user may have uncommitted changes in the same file, and those commands destroy
+   them along with the fix.
 
 ---
 

package/ts-reviewer/references/modernization.md

@@ -3,20 +3,30 @@
 Flag outdated patterns when a modern TypeScript equivalent exists.
 All items here are **Medium** or **Low** severity.
 
-## Enums -> const Objects or Union Types (Medium)
-
-```typescript
-// OUTDATED
-enum Direction { Up, Down, Left, Right }
-// MODERN
-const Direction = { Up: 'up', Down: 'down', Left: 'left', Right: 'right' } as const;
-type Direction = (typeof Direction)[keyof typeof Direction];
-// Or simple union: type Direction = 'up' | 'down' | 'left' | 'right';
-```
-Exception: `const enum` in library code for inlining.
-Note: `const enum` is incompatible with `isolatedModules` (used by esbuild, SWC, Babel).
-If the project uses a transpiler with `isolatedModules`, flag `const enum` as **Medium**
-and recommend `as const` objects instead.
+**Version gate (applies to every item):** before flagging, confirm the project's TS
+version, `target`/`lib`, and runtime support the recommended replacement. Every finding
+must state the minimum version required. Never recommend a feature the project cannot use.
+
+## Enums (Medium/Low — scope carefully)
+
+Do NOT blanket-flag every `enum`. Flag these specific cases:
+
+- **Numeric enums** (implicit or explicit numeric values). Severity: **Medium**.
+  Reverse mappings pollute the object; any number was assignable pre-TS5 and the
+  runtime object invites misuse. Fix: string enum, `as const` object, or union:
+  ```typescript
+  const Direction = { Up: 'up', Down: 'down', Left: 'left', Right: 'right' } as const;
+  type Direction = (typeof Direction)[keyof typeof Direction];
+  // Or simple union: type Direction = 'up' | 'down' | 'left' | 'right';
+  ```
+- **`const enum` when the project uses `isolatedModules`** or transpiles with
+  esbuild/SWC/Babel. Severity: **Medium**. Fix: `as const` object.
+  Exception: `const enum` in library code for inlining, compiled with tsc only.
+- **Any enum when `erasableSyntaxOnly` is set** or the project runs TS natively via
+  Node type-stripping. Severity: **Medium** — enums are non-erasable syntax.
+- **String enums in a codebase that uses them consistently:** Severity: **Low**,
+  report once as a Recurring Pattern with the `as const` alternative — this is a
+  style preference, not a defect.
 
 ## `namespace` -> ES Modules (Medium)
 
@@ -30,13 +40,39 @@ Exception: `/// <reference types="..." />` in global `.d.ts` files.
 
 ## `satisfies` Operator (Medium)
 
-Flag `as Type` or explicit type annotation where `satisfies` preserves literal types:
+Flag only when the widening actually matters — NOT every annotated constant:
+- `as Type` on an object literal (silently allows excess/missing property mismatches
+  that `satisfies` would catch), or
+- an explicit annotation where the literal types are consumed downstream
+  (keys used as a union, values used as literal types).
+
 ```typescript
-// BEFORE: loses literal type
+// BEFORE: loses literal type that IS used downstream
 const config: Config = { timeout: 5000 };
 // MODERN: validates AND keeps literal type
 const config = { timeout: 5000 } satisfies Config;
 ```
+An annotated constant whose literal types are never used is fine — do not flag.
+
+## `??` and `?.` (Medium/Low)
+
+- `x || fallback` where `x` can legitimately be `0`, `''`, or `false`.
+  Severity: **Medium** — behavior bug, not style: valid falsy values are replaced.
+  Fix: `x ?? fallback`.
+- `x || fallback` where `x` is only ever `T | null | undefined` (falsy non-nullish
+  impossible per its type). Severity: **Low**. Fix: `??` for intent clarity.
+- `a && a.b && a.b.c` chains. Severity: **Low**. Fix: `a?.b?.c`.
+- `x !== null && x !== undefined ? x : y`. Severity: **Low**. Fix: `x ?? y`.
+- `if (!x) x = y` / `obj.prop = obj.prop ?? init` self-assignment.
+  Severity: **Low**. Fix: `x ??= y` (also `||=`, `&&=` where semantics match).
+
+## Mutation-Safe Array Methods (Medium)
+
+- `.sort()`, `.reverse()`, `.splice()` called on a function parameter, shared array, or
+  anything not created locally in the same scope. Severity: **Medium** — mutates the
+  caller's data. Fix: `toSorted()`, `toReversed()`, `toSpliced()` (ES2023) or copy first.
+- `JSON.parse(JSON.stringify(x))` for deep cloning. Severity: **Low** — silently drops
+  `undefined`, functions; `Date` becomes string. Fix: `structuredClone(x)`.
 
 ## Explicit Resource Management — `using` (Medium)
 
@@ -62,16 +98,16 @@ function createRoute<const T extends string>(path: T) { ... }
 Flag type-only imports missing `import type` or inline `type` keyword.
 If `verbatimModuleSyntax` is enabled, the compiler enforces this — don't double-flag.
 
-## `accessor` Keyword (Low)
+## Redundant get/set Pairs (Low)
 
-Flag get/set pairs that simply read/write a backing field — use `accessor` instead.
+Flag a get/set pair that only reads/writes a private backing field with no validation,
+transformation, or side effect. Fix: replace with a plain public field (or a `readonly`
+field + method if only mutation needs control). Mention the `accessor` keyword only if
+the class already uses standard decorators that require it.
 
-## `Promise` Constructor -> async/await (Low)
+## Promise Constructor Anti-Pattern
 
-Flag `new Promise()` wrapping an already-async function or another promise.
-The promise constructor anti-pattern adds unnecessary nesting.
-Fix: use `async/await` directly.
-Exception: wrapping callback-based APIs — this is the correct use of the constructor.
+Covered in `references/async-patterns.md` (Promise Anti-Patterns) — do not duplicate here.
 
 ## `Object.keys()` / `Object.entries()` Typing (Low)
 
@@ -87,8 +123,25 @@ when `moduleResolution` is `nodenext`.
 - Custom `Awaited<T>` — built-in since TS 4.5.
 - Custom `NoInfer<T>` — built-in since TS 5.4.
 
-## `@ts-expect-error` vs `@ts-ignore` (Low)
+## Modern Runtime APIs (Low, version-gated)
+
+Flag the outdated idiom when the target/runtime supports the modern one:
+
+- `arr[arr.length - 1]` -> `arr.at(-1)` (ES2022).
+- `Object.prototype.hasOwnProperty.call(obj, k)` -> `Object.hasOwn(obj, k)` (ES2022).
+- `str.replace(/x/g, y)` with a literal pattern -> `str.replaceAll('x', y)` (ES2021).
+- Manual reduce-into-groups -> `Object.groupBy` / `Map.groupBy` (ES2024).
+- Array spread + filter/map chains over large iterables -> iterator helpers
+  (`.map`, `.filter`, `.take` on iterators, ES2025).
+- Manual set arithmetic loops -> `Set.prototype.union` / `intersection` /
+  `difference` (ES2025).
+- Manual timeout-promise wiring -> `AbortSignal.timeout(ms)`; combining signals ->
+  `AbortSignal.any([...])` (Node 20+).
+- Bare builtin imports (`import fs from 'fs'`) -> `node:` prefix
+  (`import fs from 'node:fs'`) in Node-targeted code.
+- `require('./data.json')` / untyped JSON loading in ESM -> import attributes:
+  `import data from './data.json' with { type: 'json' }` (Node 20.10+/TS 5.3+).
+
+## Suppression Directives
 
-Flag `// @ts-ignore` without explanation — recommend `// @ts-expect-error` instead.
-`@ts-expect-error` is preferred because it errors if the suppressed error disappears,
-preventing stale suppressions from silently hiding future regressions.
+Covered in `references/type-safety.md` (Suppression Directives) — do not duplicate here.

package/ts-reviewer/references/security.md

@@ -3,6 +3,27 @@
 For pure TypeScript code — no framework-specific issues.
 Focus on patterns dangerous regardless of runtime (Node.js, Deno, Bun, browser).
 
+## Trust Boundaries — read first
+
+Every item below assumes the dangerous value is *attacker-influenced*. Before flagging,
+trace where the value comes from:
+
+**Untrusted sources:** network request bodies/headers/URLs, CLI arguments, environment
+variables in multi-tenant contexts, file contents from user-writable paths, database
+fields that were ever written from user input, messages from queues/sockets, anything
+returned by a third-party API.
+
+**Trusted sources:** literals, values from this codebase's own constants/config files,
+values already validated by a schema at the boundary (note where).
+
+Rules:
+- Value provably static/internal -> downgrade the finding to **Medium** and say why it
+  still matters (fragile pattern), or drop it if the sink is safe by construction.
+- Taint survives transformations: concatenation, template literals, `JSON.parse`,
+  property access on a parsed object all preserve untrustedness.
+- If you cannot trace the source within the files available, report at the listed
+  severity but state the assumption: "assumes `x` can carry external input".
+
 ## Injection
 
 - **`eval()` and `new Function()`** — executing dynamic strings.
@@ -16,6 +37,21 @@ Focus on patterns dangerous regardless of runtime (Node.js, Deno, Bun, browser).
 - **RegExp from user input** — `new RegExp(userInput)`.
   Severity: **High** (ReDoS + injection). Fix: escape input or use static regex.
 
+## SSRF
+
+- `fetch()` / `http.request()` / HTTP client call with a URL built from external input,
+  without a protocol + host allowlist. Severity: **High**. Fix: parse with `new URL()`,
+  check protocol is http(s) and host against an explicit allowlist; reject redirects to
+  internal ranges.
+
+## DOM Sinks (browser code)
+
+- `element.innerHTML = x`, `insertAdjacentHTML`, `document.write` where `x` has any
+  non-literal part. Severity: **High**. Fix: `textContent` for text; a sanitizer
+  (DOMPurify) only when HTML is genuinely required.
+- `location.href = x` / `window.open(x)` from external input — `javascript:` URL risk.
+  Severity: **Medium**. Fix: validate protocol via `new URL()`.
+
 ## Prototype Pollution
 
 - `Object.assign(target, untrustedSource)` where source may contain `__proto__`.
@@ -55,8 +91,15 @@ Focus on patterns dangerous regardless of runtime (Node.js, Deno, Bun, browser).
 
 ## Timing Attacks
 
-- String comparison for secrets using `===`. Severity: **High**.
-  Fix: `crypto.timingSafeEqual()`.
+- String comparison using `===` where both sides are secrets/tokens/MACs/password hashes
+  being verified. Severity: **High**. Fix: `crypto.timingSafeEqual()`.
+  Do NOT flag ordinary string comparisons that merely involve variables named "token" —
+  only comparisons whose result reveals secret equality to an attacker.
+
+## Unsafe Memory
+
+- `Buffer.allocUnsafe()` where the buffer is not immediately and fully overwritten —
+  leaks previous memory contents. Severity: **High**. Fix: `Buffer.alloc()`.
 
 ## Denial of Service
 

package/ts-reviewer/references/tsconfig.md

@@ -22,13 +22,43 @@ If `strict: true` set but a sub-flag explicitly OFF — flag as that flag's seve
 | Flag | Recommended | Severity | Why |
 |---|---|---|---|
 | `noUncheckedIndexedAccess` | `true` | **Medium** | obj[key] returns T\|undefined instead of T |
-| `exactOptionalPropertyTypes` | `true` | **Medium** | Prevents `{ key: undefined }` from satisfying optional `{ key?: string }` |
 | `noFallthroughCasesInSwitch` | `true` | **Medium** | Prevents accidental fall-through |
 | `noImplicitReturns` | `true` | **Medium** | Not all code paths return a value |
 | `noImplicitOverride` | `true` | **Low** | Requires override keyword |
-| `noPropertyAccessFromIndexSignature` | `true` | **Low** | Forces bracket notation |
 | `allowUnreachableCode` | `false` | **Medium** | Should not be true |
 
+## Target and Lib
+
+| Check | Severity | Why |
+|---|---|---|
+| `target` two+ ES versions below minimum runtime in `engines`/docs | **Medium** | Pointless downleveling: slower output, loses native syntax |
+| `lib` includes `dom` in a Node-only project (or vice versa) | **Low** | Wrong globals available at compile time |
+| No `target` set (defaults to ES5 pre-5.0 configs) | **Medium** | Almost never intended in 2026 |
+
+## Legacy Decorators
+
+- `experimentalDecorators: true` (with or without `emitDecoratorMetadata`) and no
+  dependency that requires legacy decorators. Severity: **Medium**.
+  Fix: migrate to standard (TC39) decorators, remove both flags.
+
+## Project Structure (monorepos / large codebases)
+
+- Multiple packages with independent tsconfigs but no `references` / `composite` —
+  cross-package type changes silently skip rechecking dependents. Severity: **Low**;
+  suggest project references only when packages actually import each other's source.
+- Build config drift: `tsconfig.build.json` excludes files that `tsconfig.json`
+  typechecks (or vice versa) so `tsc --noEmit` and the build see different code.
+  Severity: **Medium**.
+
+## Explicit Non-Findings
+
+Do NOT flag:
+- `skipLibCheck: true` — standard practice; checking node_modules types is rarely useful.
+- Missing `exactOptionalPropertyTypes` / `noPropertyAccessFromIndexSignature` in an
+  existing codebase — these are opt-in strictness with real migration cost.
+  Mention once as **Low** suggestions only for greenfield projects (few source files,
+  young git history).
+
 ## Module System
 
 | Setting | Recommendation | Severity |
@@ -37,6 +67,7 @@ If `strict: true` set but a sub-flag explicitly OFF — flag as that flag's seve
 | `moduleResolution` | `"nodenext"` / `"bundler"` | **Medium** (avoid legacy `"node"` / `"node10"`) |
 | `verbatimModuleSyntax` | `true` | **Medium** (enforces `import type`, removes unused imports) |
 | `isolatedModules` | `true` | **Medium** (required by esbuild, SWC, Babel, TS transpile mode) |
+| `erasableSyntaxOnly` | `true` if the project runs TS via Node type-stripping | **Medium** when type-stripping is used without it (enums/namespaces/parameter properties would fail at runtime) |
 
 ## Path Configuration
 
@@ -57,3 +88,5 @@ Flag if present:
 - No linter configured at all: **Medium** (recommend adding one).
 - TypeScript parser not configured in ESLint: **Medium**.
 - Type-aware rules not enabled (e.g., `no-floating-promises`): **Medium**.
+  For ESLint, actionable check: config extends `typescript-eslint` `recommendedTypeChecked`
+  (or `strictTypeChecked`) and sets `parserOptions.projectService` (or `project`).

package/ts-reviewer/references/type-safety.md

@@ -27,12 +27,42 @@
 - `as Type` that narrows a wider type without validation.
   Severity: **High** — a runtime mismatch is a bug waiting to happen.
   Fix: use a type guard, `satisfies`, or a validation function (e.g., Zod, io-ts, hand-written).
-- `as unknown as Type` — double cast is almost always a red flag.
+- `as unknown as Type` or `as any as Type` — double cast is almost always a red flag.
   Severity: **High**.
 - `<Type>value` (angle-bracket cast) — same issue as `as`, plus it conflicts with JSX.
   Severity: **Medium** (prefer `as` syntax, but still flag the underlying safety issue).
 - `as const` used correctly is NOT an issue — do not flag it.
 
+## `unknown` Discipline
+
+- `unknown` narrowed with `as` instead of a runtime check. Severity: **High** — this is
+  `any` with extra steps. Fix: `typeof` / `instanceof` / `in` guards, or schema validation.
+- `catch (e)` handled via `(e as Error).message`. Severity: **Medium**.
+  Fix: `e instanceof Error ? e.message : String(e)`.
+- Public API returning `unknown` where a generic or a discriminated result type is
+  derivable — forces every caller to cast. Severity: **Medium**.
+
+## Structural Typing Traps
+
+- `{}` as a type annotation — means "any non-nullish value", not "empty object" or
+  "plain object". Severity: **Medium**. Fix: `Record<string, unknown>`, `object`, or a
+  concrete shape.
+- Boxed primitive types `String`, `Number`, `Boolean`, `Object` in annotations.
+  Severity: **Medium**. Fix: lowercase primitives.
+- Method shorthand in interfaces intended as strict callbacks:
+  `interface H { handle(e: E): void }` is bivariant even under `strictFunctionTypes`;
+  property syntax `handle: (e: E) => void` is checked contravariantly.
+  Severity: **Low** internal, **Medium** on public APIs where wrong-argument
+  implementations would compile.
+
+## Branded Types (suggestion-level)
+
+- Multiple domain identifiers sharing one primitive type (`userId: string`,
+  `orderId: string`) passed across module boundaries — mix-ups compile silently.
+  Severity: **Low** (suggest, don't insist). Fix: brand the types:
+  `type UserId = string & { readonly __brand: 'UserId' }` plus a constructor function.
+  Only flag when the codebase shows 3+ same-primitive IDs crossing function boundaries.
+
 ## Non-null Assertions (`!`)
 
 - `value!` where `value` could genuinely be `null | undefined` at runtime.
@@ -69,6 +99,10 @@
 - Union types that should be discriminated but aren't (no shared literal field).
   Severity: **Medium**.
 - Discriminant field is `string` instead of a literal type. Severity: **Medium**.
+- Boolean flag soup modeling mutually exclusive states
+  (`{ loading: boolean; error?: E; data?: T }` allows impossible combinations).
+  Severity: **Medium**. Fix: discriminated union —
+  `{ status: 'loading' } | { status: 'error'; error: E } | { status: 'ready'; data: T }`.
 
 ## Index Signatures
 
@@ -99,3 +133,16 @@
   `Parameters`, `Awaited`, `NoInfer`). Severity: **Low**.
 - `Omit` with a key that doesn't exist in the source type — TS silently allows this,
   which may indicate a typo or stale code. Severity: **Low**.
+
+## Readonly Posture
+
+- Mutable arrays/objects in exported signatures where the function never mutates them —
+  `readonly T[]` / `Readonly<T>` communicates the contract and accepts more inputs.
+  Severity: **Low**. Public APIs only; don't flag internals.
+
+## Type-level Complexity
+
+- Conditional type > 2 levels deep, or mapped type with nested `infer`, used in only one
+  place. Severity: **Low**. Fix: inline or simplify to a union/overloads unless the
+  type-level machinery removes real duplication. Clever types are a maintenance cost —
+  the next reader must decode them.