TypeScript Code Quality & Idioms

Enforces high-standard TypeScript practices: discriminating unions over loose booleans, readonly immutability, unknown over any, and exhaustive pattern matching.

1. Purpose

Elevate TypeScript code quality and maintainability. A "Discriminating Union" uses a literal tag (e.g. type: 'success' | 'error') to guarantee complete type narrowing at compile time.

2. When to Use

Use this skill when:

• Designing API response types, domain models, or state reducers.
• Refactoring complex state objects with multiple conflicting boolean flags (isLoading, isError, isSuccess).
• Removing legacy any types and replacing with safe generic or unknown types.

3. When Not to Use

• Do not use to run unit tests; use ts-testing.
• Do not use to fix immediate syntax compiler errors; use ts-lint-and-typecheck.

4. Required Inputs

• target_file: Path to the TypeScript file to review or improve.
• improvement_goal: Architectural improvement (e.g. "Model state as discriminating union").

5. Missing-Input Behavior

1. If no goal is specified: review the file against standard TypeScript code quality invariants.
2. Never introduce runtime overhead or change public function behavior.

6. Procedure

Follow these numbered actions:

1. Action 1: Audit for Anti-Patterns
   • Search for any, non-null assertions (!), and conflicting booleans.
2. Action 2: Apply Discriminating Unions
   • Replace conflicting boolean flags with single tagged unions.
3. Action 3: Apply Immutability
   • Add readonly to interface properties and ReadonlyArray<T> to prevented accidental mutation.
4. Action 4: Add Exhaustive Switch Checks
   • Use assertNever(value: never) in default branches.
5. Action 5: Verify Type-Check and Tests
   • Run npx tsc --noEmit and npm test.

7. Decision Rules

• If an array is passed as parameter and not mutated: type as readonly T[].
• If an object is configuration data: use as const assertion.

8. Output Format

Emit the report using this template:

### TypeScript Code Quality Report: [Target File]

- **File Modified**: `[path]`
- **Patterns Applied**: [e.g., Discriminating Unions, Readonly Immutability]
- **Type-Check Status**: PASS
- **Test Status**: PASS

#### Improvements Made
- [Improvement 1 with rationale]
- [Improvement 2 with rationale]

9. Verification Checklist

• Zero any types remain in modified code.
• Discriminating unions replace loose boolean states.
• tsc --noEmit passes cleanly.
• Existing tests pass without regression.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Proposed refactor breaks database serialization formats.

12. Examples

Example 1: Successful Execution

Input:

File: src/state.ts
Issue: State has { isLoading: boolean, error?: string, data?: User }
Goal: Convert to Discriminating Union

Output:

### TypeScript Code Quality Report: src/state.ts

- **File Modified**: `src/state.ts`
- **Patterns Applied**: Discriminating Unions
- **Type-Check Status**: PASS
- **Test Status**: PASS

#### Improvements Made
- Replaced 3 optional properties with typed union:
  ```typescript
  type AsyncState<T> =
    | { status: 'idle' }
    | { status: 'loading' }
    | { status: 'success'; data: T }
    | { status: 'error'; error: Error };

• Eliminates impossible states (e.g. isLoading: true with data defined).

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Make my TS better.

Output:

### TypeScript Code Quality Report: Halted - Missing File

- **Status**: Halted

Please specify the TypeScript file you would like to improve.

Example 3: Expected Final Output

Output:

### TypeScript Code Quality Report: src/options.ts

- **File Modified**: `src/options.ts`
- **Patterns Applied**: Readonly Immutability & `as const`
- **Type-Check Status**: PASS
- **Test Status**: PASS

#### Improvements Made
- Added `readonly` modifier to configuration options interface.