TypeScript Lint and Type-Check

Resolves TypeScript compiler errors and linter violations at the root cause. Enforces strict typing with zero tolerance for @ts-ignore or any.

1. Purpose

Diagnose and solve TypeScript compile errors. "Type Narrowing" refines union types using type guards. "Type Assertion" (as Type) is restricted to verified invariants.

2. When to Use

Use this skill when:

• npx tsc --noEmit fails with TS error codes (TS2322, TS2345, TS2532).
• ESLint reports @typescript-eslint/no-explicit-any or no-unused-vars.
• Upgrading TypeScript compiler versions.

3. When Not to Use

• Do not use for Python type checking; use py-lint-and-typecheck.
• Do not use for runtime test execution; use ts-testing.

4. Required Inputs

• target_file: TypeScript file with compiler or lint errors.
• error_message: Compiler or linter diagnostic output.

5. Missing-Input Behavior

1. If no file is specified: run npx tsc --noEmit across project to discover failing files.
2. Absolute Ban: Never add // @ts-ignore, // @ts-nocheck, or cast to any.
3. If property may be undefined (TS2532): add optional chaining (?.) or a defensive guard clause.

6. Procedure

Follow these numbered actions:

1. Action 1: Run TypeScript Compiler
   • Execute npx tsc --noEmit. Extract file, line, and TSxxxx code.
2. Action 2: Match Error Pattern to Root Cause
   • TS2322 (Type mismatch): Align interface properties or provide default value.
   • TS2532 (Object is possibly undefined): Add if (!obj) return ... guard.
   • TS2345 (Argument type mismatch): Check parameter types in function signature.
3. Action 3: Apply Type-Safe Modification
   • Edit the target file cleanly.
4. Action 4: Run Linter
   • Execute npx eslint <target_file> or npx @biomejs/biome check <target_file>.
5. Action 5: Re-Verify Clean Compile
   • Confirm npx tsc --noEmit exits with code 0.

7. Decision Rules

• If a third-party module lacks types: check if npm i -D @types/<package> exists.
• If handling unknown API JSON: define a Zod schema or TypeScript interface; do not declare as any.

8. Output Format

Emit the report using this template:

### TypeScript Type-Check Report: [Target File]

- **Compiler Command**: `npx tsc --noEmit` -> PASS
- **Linter Command**: `npx eslint [file]` -> PASS
- **Errors Resolved**: [Count]

#### Resolved Diagnostics
| Line | Error Code | Diagnostic Description | Root Cause Fix |
| :--- | :--- | :--- | :--- |
| `[Line]` | `TS2322` | Type 'null' not assignable to 'string' | Added nullish coalescing default value |

#### Verification Status
- Zero type errors, zero `@ts-ignore` comments.

9. Verification Checklist

• tsc --noEmit exits code 0.
• No @ts-ignore, @ts-expect-error, or any added.
• Linter exits code 0.
• Unused variables and imports deleted.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Fixing the type error requires breaking public export contracts in a published library.

12. Examples

Example 1: Successful Execution

Input:

File: src/api.ts
Error: TS2532: Object is possibly 'undefined' on line 24: return req.user.id;

Output:

### TypeScript Type-Check Report: src/api.ts

- **Compiler Command**: `npx tsc --noEmit` -> PASS
- **Linter Command**: `npx eslint src/api.ts` -> PASS
- **Errors Resolved**: 1

#### Resolved Diagnostics
| Line | Error Code | Diagnostic Description | Root Cause Fix |
| :--- | :--- | :--- | :--- |
| 24 | `TS2532` | Object is possibly 'undefined' | Added guard: `if (!req.user) throw new UnauthorizedError(); return req.user.id;` |

#### Verification Status
- Zero type errors, zero `@ts-ignore` comments.

Example 2: Ambiguous or Missing Input

Input:

Fix tsc.

Output:

### TypeScript Type-Check Report: Halted - No Errors Provided

- **Status**: Halted

Please provide the compiler error output or run `npx tsc --noEmit` to list active diagnostics.

Example 3: Expected Final Output

Output:

### TypeScript Type-Check Report: src/config.ts

- **Compiler Command**: `npx tsc --noEmit` -> PASS
- **Errors Resolved**: 2

#### Resolved Diagnostics
| Line | Error Code | Diagnostic Description | Root Cause Fix |
| :--- | :--- | :--- | :--- |
| 10 | `TS2345` | Argument of type 'string \| undefined' not assignable to 'string' | Validated env variable exists before passing to parser |