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 TypeScript 5.9+ without any framework-specific checks (no React, Vue, Angular, etc.).

What It Does

Three modes, one skill:

| Mode | What happens | |---|---| | scan | Analyzes the codebase and writes a prioritized report to code-smells.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 TypeScript: 5.9+

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.md in the project root.

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 |

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

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

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: TS 5.9+ idioms, ??/?. , 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.

How It Works Under the Hood

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

Fix mode

1. Parses code-smells.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

Tips

• Add code-smells.md to .gitignore — it's a review artifact, not part of your 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.

• 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+ project
• Git repository (for scoped modes and safe revert during fix)
• Node.js with npx available (for tsc, linter)
• Claude Code (recommended) or any Claude interface with skill support

License

MIT