Pure TypeScript Reviewer

An AI skill for deep code review and auto-fix of pure TypeScript codebases. Finds bugs, type safety holes, security vulnerabilities, async anti-patterns, outdated practices, and code smells — then fixes them with regression tests and verification.

Built for one fixed stack — TypeScript 5.9.x, ES2024, Node 24 — without any framework-specific checks (no React, Vue, Angular, etc.). Anything below the stack is a finding, anything above it is never recommended.

What It Does

Three modes, one skill:

| Mode | What happens | |---|---| | 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 |

The review covers nine 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, unknown discipline, missing exhaustive checks | ✓ | | Security | Injection, SSRF, prototype pollution, ReDoS, path traversal, hardcoded secrets | ✓ | | Async Patterns | Floating promises, race conditions, missing timeouts, unbounded concurrency, forEach(async...) | ✓ | | Modernization | Numeric enums, \|\| vs ??, mutating array methods, satisfies, using keyword | ✓ | | Code Quality | Dead code, complexity, duplication, debug artifacts, import-time side effects, testability | ✓ | | Config | tsconfig.json strict flags, target/lib, module resolution, deprecated options | ✓ | | Boundary Validation | as T on JSON.parse/fetch/env, DTO vs domain model separation, contract drift | ✓ | | Error Handling | Silent failures, throw hygiene, cause chaining, failure design at API seams | ✓ | | Dependency Hygiene | Lockfiles, wildcard versions, npm audit, duplicate-purpose and trivial deps | ✓ | | Architecture | Shallow modules, scattered concepts, tight coupling, dependency direction, layering | --arch / --full |

Installation

Install with npx

From the root of the project where you want to install the skill:

npx ts-reviewer

The installer prints a short summary before installation:

TypeScript Code Reviewer
Checks: type safety, security, async patterns, boundary validation, error handling, modernization, code quality, tsconfig, dependency hygiene
Target stack: TypeScript 5.9.x, ES2024, Node 24

Then it asks which AI agents to install for. Use Up/Down arrows to move, Space to toggle, and Enter to confirm.

Supported targets:

| AI agent | Install path | |---|---| | Claude Code | .claude/skills/ts-reviewer/ | | Codex | .agents/skills/ts-reviewer/ | | Antigravity | .agent/skills/ts-reviewer/ |

Note on Codex: project-local skills belong in .agents/ per the Codex docs; ~/.codex/ is the global per-user directory. Codex also reads a project-local .codex/ implicitly, so installs from older versions of this installer keep working — but .agents/ is the correct location going forward.

In non-interactive terminals, the installer selects all supported targets.

Manual Install

You can still copy the ts-reviewer/ folder directly into the skill directory for your AI agent.

Usage

Scan — find issues

Just ask Claude to review your code:

Review my TypeScript code

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/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

By default, only the nine core domains run. Use flags to control which domains are active:

| Flag | What runs | |---|---| | (none) | Type Safety, Security, Async, Modernization, Code Quality, Config, Boundary Validation, Error Handling, Dependency Hygiene | | --arch | Architecture only (shallow modules, coupling, dependency direction, seams) | | --full | All ten domains | | --no-arch | The nine core domains — overrides --arch, --full, and any phrase that would enable architecture |

Examples:

Review my TypeScript code --arch

Full audit --full

Review architecture of this project

Fix — apply fixes from the report

After reviewing the scan report, ask Claude to fix the issues:

Fix the issues from the report

Apply fixes from code-smells/report.md

The fix workflow:

1. Parses the report as a work plan
2. Runs existing tests to capture a baseline (knows what was already failing)
3. Fixes issues file-by-file, writes regression tests, runs tsc after each file
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/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.

Auto — scan + fix in one pass

Review and fix my TypeScript code

Auto-fix code smells

Runs scan, shows you the summary, asks if you want to proceed with fixes, then runs the full fix cycle. If everything is clean afterward, the report is deleted.

Scope Modes

By default the entire codebase is reviewed. You can narrow the scope:

| What you say | What gets reviewed | |---|---| | "review my code" | Full codebase | | "review my changes", "check uncommitted" | Staged + unstaged + untracked .ts/.mts/.cts files | | "review my PR", "diff against main" | All changes on current branch vs base | | "review last commit", "check last 3 commits" | Last N commits |

Diff-aware severity boost

In scoped modes, issues on new/modified lines get their severity boosted by one level (Low→Medium, Medium→High, etc.). A Medium code smell in a three-year-old file is tech debt; the same smell in code you wrote today should be fixed before merging.

Issues on unchanged lines are listed separately as pre-existing tech debt — informational, not blocking.

Severity Scale

| Level | Meaning | |---|---| | Highest | Active bugs, security vulnerabilities, data loss risks | | High | Bugs waiting to happen, will break under edge cases | | 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

AGENTS.md                             # How to edit the review rules — read before changing anything below
CLAUDE.md                             # Pointer to AGENTS.md, picked up automatically by Claude Code

src/                                  # npm/npx installer source
├── cli.ts                            # CLI entrypoint and provider prompt
├── prompt.ts                         # raw-mode keyboard multi-select
└── paths.ts                          # target directories and skill asset loading

cnlp/                                 # the CNL-P format the skill files are written in
├── cnlp-format.md                    # the standard: forms, line rules, lexicon
├── cnlp.js                           # the checker — Node builtins only, no dependencies
├── skill-format.test.js              # the conformance test, run by `npm test`
└── profiles/                         # what each kind of document may contain
    ├── skill.md                      #   → ts-reviewer/SKILL.md
    ├── reference.md                  #   → ts-reviewer/references/*.md
    ├── guide.md                      #   → AGENTS.md
    └── profile.md                    #   → the profiles themselves

ts-reviewer/
├── SKILL.md                          # Main skill file — mode routing, workflow orchestration
└── references/
    ├── type-safety.md                # Checklist: any, unknown, casts, !, exhaustiveness, branded types
    ├── security.md                   # Checklist: trust boundaries, injection, SSRF, pollution, ReDoS
    ├── async-patterns.md             # Checklist: floating promises, races, timeouts, retries, cancellation
    ├── boundary-validation.md        # Checklist: runtime validation at edges, DTO/domain separation
    ├── error-handling.md             # Checklist: silent failures, throw hygiene, failure design
    ├── modernization.md              # Checklist: patterns below the stack, ??/?. , satisfies, using, toSorted
    ├── code-quality.md               # Checklist: complexity, dead code, debug artifacts, testability
    ├── tsconfig.md                   # Checklist: strict flags, target/lib, module resolution, deprecated
    ├── dependency-hygiene.md         # Checklist: lockfiles, versions, npm audit, dependency choice
    ├── architecture.md               # Checklist: shallow modules, coupling, dependency direction, seams
    └── fix-workflow.md               # Complete fix protocol: tests, verification, rollback

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. Architecture analysis is opt-in and loaded only when the domain is active.

Editing the Rules

As of 2.0.0, SKILL.md and every reference file are written in CNL-P — a block-structured format an agent reads as instructions rather than prose. One rule per line, one term per concept, no headings, a hard 250-character line limit.

A check line looks like this:

- injection — `eval()` and `new Function()` executing a dynamic string: Highest, use a lookup table, a strategy, or a safe parser

The format is enforced, not merely recommended:

npm test        # typecheck + conformance and tool tests

The test catches a check line that lost its severity, a block the profile does not declare, blocks out of order, a banned vague word, and a line over the limit — each reported with its file and line number.

Before adding or changing a rule, read AGENTS.md. It states which file owns which domain, the shape of a check line, the severity scale, which block takes what, and the line rules. Claude Code picks this up on its own through CLAUDE.md; for another agent, point it at AGENTS.md explicitly.

How It Works Under the Hood

Scan mode

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. Architecture pre-pass — when active, writes bounded Knip, graph, metric, co-change, rule, and Mermaid artifacts under code-smells/, with project coverage and bounded failure diagnostics.
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, and validates its contract before the scan succeeds. Architecture findings appear in a separate ## Architecture Opportunities section at the end.

Validate a report directly with node ts-reviewer/tools/validate-report.mjs --repo . --report code-smells/report.md. It checks headings, counts, finding anchors, architecture fields, and linked artifacts without adding a dependency. An error is a defect of the report that rewriting it fixes; a warning names an outcome of the mechanical pre-pass — a graph with no diagram, say — that the report cannot fix, and warnings do not fail the run.

Fix mode

1. Validates code-smells/report.md and stops before changing code when the report is invalid
2. Parses the report as the work plan
3. Captures test baseline (runs tests before changes)
4. Applies fixes bottom-to-top within each file (so line numbers don't shift)
5. Writes regression tests for each testable fix
6. Runs tsc --noEmit after each file
7. Runs the full verification loop: tsc + linter + test suite (max 5 iterations)
8. Compares test results with baseline — only fixes regressions it caused
9. Updates or deletes the report, keeps the remaining code-smells/ artifacts, and asks before removing them

Tips

• 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/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.

Requirements

• TypeScript 5.9.x project targeting ES2024 on Node 24
• Git repository (for scoped modes and safe revert during fix)
• Node 24 with npx available (for tsc, linter)
• Claude Code (recommended) or any Claude interface with skill support

License

MIT