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

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, async patterns, security, tsconfig, modernization, code quality
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 | .codex/skills/ts-reviewer/ | | Antigravity | .agent/skills/ts-reviewer/ |

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

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 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, casts, !, exhaustiveness, generics
    ├── security.md                   # Checklist: injection, pollution, ReDoS, traversal
    ├── async-patterns.md             # Checklist: floating promises, races, cancellation
    ├── 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 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
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

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