Ban type assertions
A curated collection of practical, evidence-backed skills for coding agents.
npx -y skills add zacharygcook/agent-skills --skill ban-type-assertionsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 26 days oldThe repository was created 26 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Enforce a TypeScript policy that bans `as` type assertions and replace casts with compiler-verified narrowing or runtime validation. Use when introducing the ESLint rule, removing violations, reviewing assertion workarounds, or designing typed data boundaries.
SKILL.md
2.4 KB, as published. Nobody here has run it
Ban Type Assertions
Configure @typescript-eslint/consistent-type-assertions with assertionStyle: "never", then replace assertions with code the compiler or runtime can verify. Treat as const according to the repository's explicit policy.
Decision Order
1. Validate external data
Parse JSON, network responses, storage, database rows, messages, and other untrusted inputs with the repository's runtime schema library.
// Avoid
const value = JSON.parse(raw) as Payload
// Prefer
const value = PayloadSchema.parse(JSON.parse(raw))
Use non-throwing parse APIs where failure needs structured handling or request context.
2. Narrow with control flow
Use discriminated unions, exhaustive switch, typeof, instanceof, and in when TypeScript can prove the result.
if (error instanceof Error && "code" in error) {
handleCode(error.code)
}
3. Improve the API or types
Fix overly broad return types, generic inference, duplicate domain types, and missing package contracts. Prefer satisfies when checking an object without changing its inferred type.
4. Document a genuine exception
Use a narrow lint suppression only for an unavoidable library/type-system gap. Explain why it is safe and why normal narrowing cannot work. Do not quietly raise a ratchet threshold.
Avoid Disguised Assertions
A custom predicate returning value is T is still an assertion unless its checks fully establish T. Use schema validation for rich object shapes. Do not replace one cast with a weak guard that only checks one property.
Rollout
- Locate all TypeScript packages and their ESLint configurations.
- Enable the rule consistently.
- Inventory violations and classify boundary, narrowing, API-design, and unavoidable cases.
- Fix violations package by package.
- Add a CI check or zero-tolerance report if repository lint scope can miss files.
- Run lint, typecheck, focused tests, the full suite when practical, and unused-export checks after shared-type changes.
Test fixtures must satisfy the same schemas as production data; do not disable the rule in tests merely to keep incomplete mocks.