# Typescript Suppressions

> TypeScript suppression policy for linting and type-checking exceptions.

- Skill: `drmoisan/typescript-suppressions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add drmoisan/typescript-suppressions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/drmoisan/typescript-suppressions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: drmoisan (https://skillmd.com/u/drmoisan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/drmoisan/typescript-suppressions

---


# TypeScript Suppression Policy

This rule file summarizes the suppression authorization policy for TypeScript code.

## Authorization Requirement

All ESLint and TypeScript suppressions must either:
1. **Match a pre-authorized pattern** defined in this file, OR
2. **Have explicit user approval** for that specific suppression.

**Escalation path before requesting approval:**
1. First, attempt to resolve the error without a suppression (refactor, restructure, adjust types).
2. If that fails, try at least five more distinct approaches.
3. Continue iterating until you solve the problem or clearly demonstrate why each approach fails.
4. Only after multiple documented failed attempts may you request user approval, providing: the specific rule/error code, each approach tried and why it failed, and why a suppression is the only remaining option.

## Pre-Authorized Patterns

### ESLint — Single-rule, single-line disable

**Pattern:** `// eslint-disable-next-line <rule-name> -- <reason>`

**When authorized:**
- Suppresses exactly one ESLint rule for exactly one following line.
- The reason is specific and local to the code (not "annoying rule", "temporary", or "works").
- The suppression does not hide a real bug or broaden the type surface unnecessarily.

**Required comment format:** The `-- <reason>` suffix is mandatory and must explain why the suppression is safe in this specific local context.

### TypeScript — Single-line expect-error

**Pattern:** `// @ts-expect-error -- <reason>`

**When authorized:**
- A single line is flagged by TypeScript and you can explain the mismatch precisely.
- The reason explains what TypeScript is complaining about AND why this line is safe anyway.
- Prefer fixing types, adding runtime guards, or refining control flow over suppressions.

**Self-auditing:** `@ts-expect-error` fails the build if the error disappears, preventing stale suppressions.

**Required comment format:** The `-- <reason>` suffix is mandatory.

## Explicitly Prohibited Patterns

These patterns require explicit user approval and should generally be avoided:

| Pattern | Reason prohibited |
|---------|-------------------|
| `/* eslint-disable */` | File-level; extremely large blast radius; hides unrelated problems. |
| `/* eslint-disable <rule> */` | File-level; use single-line suppression instead. |
| `// @ts-ignore` | Can silently mask real problems; does not fail when the error disappears. |
| `// @ts-nocheck` | Disables type checking for the entire file; defeats repo type-safety standards. |

## Policy Enforcement Checklist

Before using any suppression, verify:
- [ ] Pattern exactly matches a pre-authorized pattern above.
- [ ] Required comment format (`-- <reason>`) is used.
- [ ] Scope is the smallest possible (single rule, single line).
- [ ] The reason is specific and explains why the code is safe.