ts-reviewer 1.0.0

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

@@ -0,0 +1,358 @@
+# Fix Workflow Protocol
+
+This document describes the complete fix mode protocol.
+Read this before executing any fix or auto mode operation.
+
+## Prerequisites
+
+- `code-smells.md` must exist in the project root.
+  If missing, stop with error: "No scan report found. Run scan first."
+- The project must be in a git repository (for safe revert if needed).
+- Recommend the user commit or stash uncommitted work before fix runs,
+  so they can `git diff` or `git checkout -- .` to revert all changes.
+
+## Step 1 — Parse the Report
+
+Read `code-smells.md` and extract all issues into a work list.
+Group issues by file path. Within each file, sort by line number **descending**
+(fix from bottom of file upward so line numbers above don't shift).
+
+Build the work plan:
+```
+File: src/auth/token.ts
+  - Line 142: [High] Unsafe `as` cast — type-safety
+  - Line 87:  [Medium] Floating promise — async
+  - Line 23:  [Low] `enum` should be `as const` — modernization
+
+File: src/api/handler.ts
+  - Line 201: [Highest] eval() with user input — security
+  - Line 55:  [Medium] Missing exhaustive check — type-safety
+```
+
+## Step 2 — Detect Test Infrastructure
+
+Check for test runner in this order:
+
+| Signal | Runner | Command |
+|---|---|---|
+| `package.json` has `"scripts": { "test": "..." }` | npm script | `npm test` |
+| `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` |
+| `deno.json` exists | deno | `deno test` |
+| `bun.lockb` or `bun.lock` exists | bun | `bun test` |
+| Node.js 18+ and `*.test.ts` files | node:test | `node --test` |
+
+If no test infrastructure found:
+- Warn the user: "No test runner detected. Fixes will be applied without test verification."
+- Skip all test-related steps (baseline, regression tests, verification).
+- Still run `tsc --noEmit` and linter after fixes.
+
+Also detect the test file naming convention:
+- `*.test.ts` vs `*.spec.ts`
+- `__tests__/` directory vs co-located with source
+- Test framework imports (`describe/it` vs `test` vs `Deno.test`)
+
+## Step 3 — Capture Test Baseline
+
+Run the full test suite BEFORE any changes:
+```bash
+<test_command> 2>&1 | tee .claude/ts-reviewer-baseline.log
+```
+
+Record:
+- Total tests: N
+- Passing: N
+- Failing: N (list these — they are pre-existing failures, NOT our responsibility)
+- Test run command used
+
+This baseline is critical. After our fixes, any NEW failures are regressions we caused.
+Pre-existing failures that still fail are not our problem.
+
+## Step 4 — Apply Fixes File-by-File
+
+Process one file at a time. For each file:
+
+### 4a. Apply all fixes in the file
+
+Go through the file's issues sorted by line number descending.
+For each issue:
+
+1. Read the current state of the file (lines may have shifted from previous fixes in same file).
+2. Apply the fix described in the report.
+3. If the fix involves replacing a pattern (e.g., `enum` -> `as const`), update ALL
+   references to that symbol across the codebase (imports, usages).
+
+### 4b. Write regression tests
+
+For each fix, write a regression test if the issue is testable.
+
+**Testable issues** (write a regression test):
+- Type safety: incorrect cast → test that the function handles the correct type
+- Security: eval/injection → test that the sanitized version rejects malicious input
+- Async: floating promise → test that errors propagate correctly
+- Bugs: missing null check → test with null/undefined input
+
+**Non-testable issues** (skip regression test):
+- Style changes (naming, formatting)
+- Config changes (tsconfig flags)
+- Modernization that doesn't change behavior (enum -> as const with same values)
+- Complexity reduction (splitting a function — behavior unchanged)
+
+Regression test conventions:
+- Match the project's existing test naming convention and framework
+- Place tests next to existing test files, or in `__tests__/` if that's the convention
+- Name: `<original-file>.reviewer-fixes.test.ts` (or `.spec.ts` per convention)
+- Each test should be clearly labeled with the issue title:
+  ```typescript
+  describe('ts-reviewer fixes: src/auth/token.ts', () => {
+    it('should not use unsafe cast for token payload (type-safety)', () => {
+      // test that validates the fix
+    });
+  });
+  ```
+- Keep tests focused and minimal — test the specific fix, not the entire function
+
+### 4c. Run tsc after each file
+
+```bash
+npx tsc --noEmit 2>&1
+```
+
+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
+  that affect consumers)
+- Re-run `tsc` to confirm
+- If unable to fix after 2 attempts on the same error, revert the last fix in this file
+  and mark the issue as `[FIX FAILED: caused type errors]` in the report
+
+### 4d. Move to next file
+
+Repeat 4a-4c for each file in the work plan.
+
+## Step 5 — Linter Pass
+
+After all files are fixed, run the linter:
+
+```bash
+# ESLint
+npx eslint [changed_files] --format json 2>/dev/null
+# or Biome
+npx biome check [changed_files] --reporter json 2>/dev/null
+```
+
+If linter reports errors in files we changed:
+- Auto-fix what's auto-fixable: `npx eslint --fix [files]` or `npx biome check --fix [files]`
+- For remaining errors: fix manually
+- Re-run linter to confirm clean
+
+## Step 6 — Test Verification
+
+Run the full test suite:
+```bash
+<test_command> 2>&1 | tee .claude/ts-reviewer-postfix.log
+```
+
+Compare with baseline:
+
+| Baseline | Post-fix | Verdict |
+|---|---|---|
+| PASS | PASS | OK — no regression |
+| FAIL | FAIL | OK — pre-existing failure, not our problem |
+| PASS | FAIL | REGRESSION — we broke this, must fix |
+| FAIL | PASS | BONUS — we accidentally fixed a pre-existing failure |
+| (new) | FAIL | Our new regression test fails — must fix |
+| (new) | PASS | Our new regression test passes — good |
+
+For each REGRESSION:
+1. Analyze the test failure and the stack trace.
+2. Identify which fix caused it (check git diff for the relevant file).
+3. Either fix the regression or revert the offending fix.
+4. Mark reverted fixes as `[FIX REVERTED: caused test regression in <test>]`.
+
+## Step 7 — Verification Loop
+
+After fixing regressions, repeat:
+1. `tsc --noEmit`
+2. Linter check
+3. Full test suite
+
+If new issues appear, fix them. **Maximum 5 iterations** of this loop.
+
+After 5 iterations, if issues remain:
+- Stop fixing
+- Leave the code in its current state
+- Update the report with a "Stabilization" section listing unresolved regressions
+- The user will need to handle these manually
+
+Iteration tracking:
+```
+Iteration 1: Fixed 12/15 issues. 2 test regressions found.
+Iteration 2: Fixed 2 regressions. 1 new tsc error.
+Iteration 3: Fixed tsc error. All tests pass. Clean.
+-> Done at iteration 3.
+```
+
+## Step 8 — Update Report
+
+After fix completes, decide what to do with `code-smells.md`:
+
+### All issues fixed successfully
+
+Delete `code-smells.md`. The report served its purpose and the codebase is clean.
+Inform the user: "All N issues fixed. Report deleted. Run scan again to verify."
+
+### Some issues remain (failed, reverted, skipped, or not auto-fixable)
+
+Keep `code-smells.md` as a complete audit trail. The file must show the full picture:
+both what was fixed and what wasn't. This is important because:
+- The user can trace regressions back to a specific fix
+- The user can see at a glance what still needs manual attention
+- A "fixed" issue that later causes problems can be identified and reverted
+
+Rewrite the report with this structure:
+
+```markdown
+# TypeScript Code Review Report
+
+**Project:** <n>
+**Scanned:** <original scan date>
+**Fixed:** <fix date>
+**Total issues found:** N
+**Fixed:** N | **Failed:** N | **Skipped:** N | **Remaining:** N
+
+## Fix Summary
+
+<1-2 sentences: what was done, what remains>
+
+## Fixed Issues
+
+### [TITLE] — [FIXED]
+
+**Original severity:** High | **Category:** type-safety | **File:** `path` | **Line:** N
+
+```typescript
+// BEFORE (original code)
+```
+
+```typescript
+// AFTER (applied fix)
+```
+
+**Regression test:** `path/to/file.reviewer-fixes.test.ts` (or "not applicable")
+
+---
+
+## Remaining Issues
+
+### Unfixed (failed/reverted/skipped)
+
+### [TITLE] — [FIX FAILED: reason] or [FIX REVERTED: reason] or [SKIPPED: reason]
+
+**Severity:** High | **Category:** security | **File:** `path` | **Line:** N
+
+```typescript
+// code snippet
+```
+
+**Problem:** <explanation>
+**Recommended fix:** <what should be done manually>
+**Why auto-fix failed:** <specific reason>
+
+---
+
+### Not attempted (not auto-fixable or not in scope)
+
+<these keep their original format from the scan report>
+
+## Config Issues
+## Recurring Patterns
+```
+
+Status tags for each issue:
+- `[FIXED]` — successfully applied and verified
+- `[FIX FAILED: <reason>]` — attempted but couldn't complete (tsc errors, etc.)
+- `[FIX REVERTED: <reason>]` — applied but caused test regression, rolled back
+- `[SKIPPED: requires manual review]` — too risky or ambiguous to auto-fix
+- No tag — not attempted (not auto-fixable or out of scope)
+
+### BEFORE/AFTER for fixed issues
+
+Every `[FIXED]` issue must include both the original code and the replacement.
+This serves as a diff the user can review, and if something breaks later,
+they can identify which fix to revert by looking at the AFTER block.
+Keep snippets minimal (3-7 lines) — just the changed portion.
+
+## Step 9 — Final State
+
+After fix completes:
+- All code changes are in the working tree, NOT staged, NOT committed
+- The user can:
+  - `git diff` to review all changes
+  - `git add -p` to selectively stage
+  - `git checkout -- .` to revert everything
+  - Run tests themselves to verify
+- New regression test files are also unstaged
+- `code-smells.md` is either deleted (all clean) or updated with full audit trail
+
+---
+
+## Fix Safety Rules
+
+1. **NEVER commit or stage.** The user reviews and decides.
+2. **NEVER delete files** unless the file was entirely dead code flagged in the report.
+3. **NEVER modify files outside the scope** of issues in `code-smells.md`,
+   except for necessary cascading changes (e.g., updating imports after a type rename).
+4. **Preserve all existing behavior.** Fixes should not change what the code does,
+   only how it does it (safer types, modern syntax, proper error handling).
+   The exception is security fixes that intentionally change behavior (e.g., adding input
+   validation that rejects previously-accepted malicious input).
+5. **Keep changes minimal.** Don't refactor an entire file because of one issue.
+   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.
+
+---
+
+## Test Runner Quick Reference
+
+### vitest
+```bash
+npx vitest run                          # run all tests once
+npx vitest run --reporter json          # JSON output for parsing
+npx vitest run src/auth/                # run tests in directory
+```
+
+### jest
+```bash
+npx jest                                # run all
+npx jest --json                         # JSON output
+npx jest --testPathPattern auth         # filter by path
+```
+
+### mocha
+```bash
+npx mocha                               # run all
+npx mocha --reporter json               # JSON output
+```
+
+### node:test
+```bash
+node --test                              # run all *.test.* files
+node --test --test-reporter spec         # detailed output
+```
+
+### deno
+```bash
+deno test                                # run all
+deno test --filter "auth"                # filter
+```
+
+### bun
+```bash
+bun test                                 # run all
+bun test --bail                          # stop on first failure
+```

package/ts-reviewer/references/modernization.md

@@ -0,0 +1,94 @@
+# Modernization Checklist — TypeScript 5.9+
+
+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.
+
+## `namespace` -> ES Modules (Medium)
+
+Flag `namespace` blocks that could be split into separate files with ES module exports.
+Exception: declaration merging in `.d.ts` files.
+
+## `/// <reference>` -> import (Medium)
+
+Flag `/// <reference path="..." />` that could be a regular `import`.
+Exception: `/// <reference types="..." />` in global `.d.ts` files.
+
+## `satisfies` Operator (Medium)
+
+Flag `as Type` or explicit type annotation where `satisfies` preserves literal types:
+```typescript
+// BEFORE: loses literal type
+const config: Config = { timeout: 5000 };
+// MODERN: validates AND keeps literal type
+const config = { timeout: 5000 } satisfies Config;
+```
+
+## Explicit Resource Management — `using` (Medium)
+
+Flag manual try/finally cleanup for disposable resources:
+```typescript
+// BEFORE
+const handle = openFile('data.txt');
+try { /* work */ } finally { handle.close(); }
+// MODERN
+using handle = openFile('data.txt');
+```
+Only flag if the runtime supports `Symbol.dispose` (Node.js 20+, Deno 1.38+, Bun 0.6+).
+
+## `const` Type Parameters (Low)
+
+```typescript
+// MODERN
+function createRoute<const T extends string>(path: T) { ... }
+```
+
+## `import type` and Inline `type` (Low)
+
+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)
+
+Flag get/set pairs that simply read/write a backing field — use `accessor` instead.
+
+## `Promise` Constructor -> async/await (Low)
+
+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.
+
+## `Object.keys()` / `Object.entries()` Typing (Low)
+
+Flag `as keyof` casts after `Object.keys()` — suggest a typed helper.
+
+## Module Resolution (Medium)
+
+Flag `require()` in `.ts` files, `module.exports`, missing `.js` extensions
+when `moduleResolution` is `nodenext`.
+
+## Deprecated Utility Types (Low)
+
+- 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)
+
+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.

package/ts-reviewer/references/security.md

@@ -0,0 +1,75 @@
+# Security Checklist
+
+For pure TypeScript code — no framework-specific issues.
+Focus on patterns dangerous regardless of runtime (Node.js, Deno, Bun, browser).
+
+## Injection
+
+- **`eval()` and `new Function()`** — executing dynamic strings.
+  Severity: **Highest**. Fix: lookup table, strategy pattern, safe parser.
+- **Template literals in shell commands** — `exec(\`cmd ${userInput}\`)`.
+  Severity: **Highest**. Fix: `execFile` with argument arrays.
+- **Dynamic `import()` with user-controlled paths**.
+  Severity: **Highest**. Fix: whitelist allowed module paths.
+- **SQL/NoSQL injection** — string concatenation in queries.
+  Severity: **Highest**. Fix: parameterized queries.
+- **RegExp from user input** — `new RegExp(userInput)`.
+  Severity: **High** (ReDoS + injection). Fix: escape input or use static regex.
+
+## Prototype Pollution
+
+- `Object.assign(target, untrustedSource)` where source may contain `__proto__`.
+  Severity: **High**. Fix: `structuredClone()`, filter keys, or `Object.create(null)`.
+- Recursive merge without guarding `__proto__`, `constructor`, `prototype`.
+  Severity: **High**.
+- `obj[dynamicKey] = value` with external input key.
+  Severity: **High**. Fix: validate key or use `Map`.
+
+## Unsafe Deserialization
+
+- `JSON.parse(untrusted)` without schema validation.
+  Severity: **Medium**. Fix: validate with Zod/io-ts/ajv after parsing.
+  Note: `JSON.parse` itself does not execute arbitrary code — the risk is accepting
+  malformed data that bypasses business logic, not injection.
+- YAML/TOML from untrusted sources without safe parser. Severity: **High**.
+
+## Path Traversal
+
+- File operations with user paths without normalization.
+  Severity: **Highest**. Fix: `path.resolve()` + verify within base dir.
+- `path.join(base, userInput)` — does NOT prevent `..` traversal.
+  Severity: **Highest**. Fix: resolve full path, check `startsWith(baseDir)`.
+
+## Secrets and Credentials
+
+- Hardcoded API keys, tokens, passwords in source. Severity: **Highest**.
+- Secrets logged to console. Severity: **High**.
+- Secrets in error messages. Severity: **High**.
+
+## Cryptography
+
+- `Math.random()` for security-sensitive values. Severity: **Highest**.
+  Fix: `crypto.randomUUID()`, `crypto.getRandomValues()`.
+- Hardcoded IVs, salts, seeds. Severity: **High**.
+- Deprecated algorithms (MD5, SHA1 for security, DES). Severity: **High**.
+
+## Timing Attacks
+
+- String comparison for secrets using `===`. Severity: **High**.
+  Fix: `crypto.timingSafeEqual()`.
+
+## Denial of Service
+
+- **ReDoS** — nested quantifiers: `(a+)+`, `(a|a)+`. Severity: **High**.
+- Unbounded data processing without size limits. Severity: **Medium**.
+- Recursive functions without depth limits on untrusted input. Severity: **High**.
+
+## Information Disclosure
+
+- Error messages exposing internals to end users. Severity: **Medium**.
+- `console.log`/`console.debug` with sensitive data in production. Severity: **Medium**.
+
+## Race Conditions (security-relevant)
+
+- TOCTOU in file operations. Severity: **High**.
+- Auth checks separated from protected action by `await`. Severity: **High**.

package/ts-reviewer/references/tsconfig.md

@@ -0,0 +1,59 @@
+# tsconfig.json Checklist
+
+## Strict Mode Flags
+
+`"strict": true` enables all below. If off, check each individually.
+
+| Flag | Severity if missing | Why |
+|---|---|---|
+| `strictNullChecks` | **Highest** | Without it, null/undefined assignable to everything |
+| `strictFunctionTypes` | **High** | Contravariant parameter checking |
+| `strictBindCallApply` | **Medium** | Type-checks bind/call/apply |
+| `strictPropertyInitialization` | **High** | Catches uninitialized class properties |
+| `noImplicitAny` | **High** | Prevents silent any inference |
+| `noImplicitThis` | **Medium** | Catches untyped this |
+| `useUnknownInCatchVariables` | **Medium** | catch(e) types as unknown not any |
+| `alwaysStrict` | **Low** | Emits "use strict" |
+
+If `strict: true` set but a sub-flag explicitly OFF — flag as that flag's severity.
+
+## Additional Safety Flags
+
+| 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 |
+
+## Module System
+
+| Setting | Recommendation | Severity |
+|---|---|---|
+| `module` | `"nodenext"` / `"preserve"` / `"esnext"` | **Medium** |
+| `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) |
+
+## Path Configuration
+
+- Path aliases must match bundler/runtime config. Mismatches: **High**.
+- Aliases pointing to non-existent dirs: **High**.
+
+## Deprecated Flags
+
+Flag if present:
+- `suppressImplicitAnyIndexErrors` — **Medium**
+- `suppressExcessPropertyErrors` — **Medium**
+- `noStrictGenericChecks` — **High**
+- `importsNotUsedAsValues` — **Low** (replaced by verbatimModuleSyntax)
+- `preserveValueImports` — **Low** (replaced by verbatimModuleSyntax)
+
+## Linter Config
+
+- 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**.

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

@@ -0,0 +1,101 @@
+# Type Safety Checklist
+
+## Suppression Directives
+
+- `// @ts-ignore` without explanation. Severity: **Medium**.
+  Recommend `// @ts-expect-error` with a comment explaining why the error is expected.
+- `// @ts-expect-error` that no longer suppresses any error (stale). Severity: **Low**.
+  The directive should be removed — it was masking nothing.
+- `// @ts-ignore` or `// @ts-expect-error` used to hide a type safety issue that could
+  be fixed properly. Severity: **Medium**. Fix: address the root cause instead.
+
+## `any` Abuse
+
+- Explicit `any` in function parameters, return types, or variable declarations.
+  Severity: **Medium** (internal code), **High** (public API / exported functions).
+- Implicit `any` from missing type annotations where TS cannot infer.
+  Severity: **Medium**.
+- `any[]` where a typed array or generic is possible. Severity: **Medium**.
+- `Record<string, any>` — usually should be `Record<string, unknown>` or a proper interface.
+  Severity: **Medium**.
+- `Function` type — almost always wrong. Use a specific signature. Severity: **High**.
+  `Function` bypasses all type checking on arguments and return value.
+- `object` type (lowercase) — too broad, prefer a specific interface. Severity: **Low**.
+
+## Unsafe Casts
+
+- `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.
+  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.
+
+## Non-null Assertions (`!`)
+
+- `value!` where `value` could genuinely be `null | undefined` at runtime.
+  Severity: **High**.
+- `value!` right after a check that already narrowed the type — redundant, not harmful.
+  Severity: **Low** (remove the `!`, the narrowing already handles it).
+- `document.getElementById('x')!` — acceptable in DOM code with known IDs,
+  but flag if it's in a library or server-side code. Severity: **Medium**.
+
+## Exhaustiveness
+
+- `switch` on a discriminated union missing a `default: assertNever(x)` or equivalent.
+  Severity: **High** — adding a new variant to the union won't cause a compile error.
+  Fix: add an exhaustive check:
+  ```typescript
+  function assertNever(x: never): never {
+    throw new Error(`Unexpected value: ${x}`);
+  }
+  ```
+- `if/else if` chains on union types without a final `else` that handles the rest.
+  Severity: **Medium**.
+
+## Generics
+
+- Unnecessary generics — `function foo<T>(x: T): T` where `T` is never constrained
+  and the function doesn't actually use the generic relationship. Severity: **Low**.
+- Missing constraints — `<T>` where `<T extends SomeBase>` is needed. Severity: **Medium**.
+- Over-constrained generics that accept only one concrete type — just use that type.
+  Severity: **Low**.
+- Generic with default that hides complexity: `<T = any>`. Severity: **Medium**.
+
+## Discriminated Unions
+
+- 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**.
+
+## Index Signatures
+
+- `obj[key]` without checking if `key` exists — especially dangerous
+  when `noUncheckedIndexedAccess` is disabled. Severity: **Medium** if the flag is off.
+- Using `in` operator or `hasOwnProperty` without narrowing. Severity: **Medium**.
+
+## Return Types
+
+- Public/exported functions missing explicit return types. Severity: **Medium**.
+  (Internal functions can rely on inference — don't flag those unless the inferred type is `any`.)
+- Functions that return different types in different branches without a union return type.
+  Severity: **High** — the inferred type might be wider than intended.
+
+## Type Predicates and Assertion Functions
+
+- Type guard functions that return `boolean` instead of `x is Type`.
+  Severity: **Low** (works but loses narrowing at call site).
+- Assertion functions (`asserts x is Type`) that don't actually throw on failure.
+  Severity: **High** — the compiler trusts the assertion.
+- Type predicates that lie — the runtime check doesn't match the declared narrowing.
+  Severity: **Highest** — this silently causes type mismatches.
+
+## Utility Types
+
+- Hand-rolled types that duplicate built-in utility types
+  (`Partial`, `Required`, `Pick`, `Omit`, `Record`, `Readonly`, `ReturnType`,
+  `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**.