1. The Problem — What is Difficult or Frustrating?
Type Guard can silently drift from TypeScript type
2. Who Experiences It — The Affected Audience
TypeScript developer
3. The Proposed Tool — Specific Web App or Software Concept
A command‑line utility that parses a TypeScript project, extracts type guard functions, and validates them against the declared target types.
4. Core Features & Architecture
1.Guard Extraction
Scans source files to locate functions whose return type is a type predicate and records their signatures.
SolvesIdentifies the exact guards that need verification without manual enumeration. 2.Type Alignment Check
Uses the TypeScript type checker to compare the guard's runtime checks with the structural requirements of the target type, reporting mismatched properties or missing checks.
SolvesDetects the silent drift between guard logic and the associated type. 3.Continuous Integration Hook
Outputs a machine‑readable report that can be integrated into CI pipelines, causing a build to fail when drift is detected.
SolvesPrevents drift from reaching production by enforcing verification on every commit. 5. Potential Value — Operational Impact
Developers receive immediate feedback when a guard no longer matches its type, eliminating the need for manual cross‑checking and keeping runtime validation reliable.
Limitations & Technical Boundaries
The tool cannot see or evaluate dynamic validation that depends on external runtime data such as API responses, and it does not rewrite guard code automatically.
6. Suggested Validation Questions (Not Researched Facts)
Suggested exploration questions to confirm real demand, alternatives, and willingness to pay before building:
- Demand question: How often do you discover that a custom type guard no longer matches its interface after a type change?
- Possible existing alternatives to check: tsd, tslint, eslint-plugin-typescript, Gap to test: whether these tools cover automatic structural verification of type guard implementations
- Willingness-to-pay question: What monthly price would you consider fair for a tool that automatically alerts you to any mismatch between type guards and their target types?
Technical Feasibility & Platform Terms RiskRelies on access to the TypeScript compiler API and its type‑checking capabilities.
🛠️ Technical Blueprint & Implementation Concept
**Implementation Overview:** The tool would be a **Node.js CLI utility** leveraging the **TypeScript Compiler API (tsc)** and **TypeScript ESLint Plugin** for deep type analysis. The frontend would be a **minimalist TUI (Text-Based UI)** using **ink.js** for CI-friendly output, while the backend would use **TypeScript’s `ts` module** to parse ASTs and extract type guard signatures via **`ts-simple-ast`** for cleaner DOM traversal. **Core Workflow:** 1. **Guard Extraction:** - Use **`tsc --noEmit`** to generate a **program** object, then traverse the AST with **`ts-simple-ast`** to identify functions with return types like `x is T` (type predicates). - Record signatures (parameters, return type) via **`ts.isTypePredicateNode`** and **`ts.getReturnTypeOfSignature`**. - Store metadata in a **JSON schema** (e.g., `{ guardName: string, targetType: ts.Type, filePath: string }`). 2. **Type Alignment Check:** - For each guard, **reconstruct the target type** (`T`) using **`ts.getTypeOfSymbolAtLocation`** on the type’s declaration. - Use **`ts.checker.getResolvedSignature`** to compare runtime checks (e.g., `if ('prop' in x)`) against the type’s structural requirements (e.g., `{ prop: string }`). - Flag mismatches via **`ts.isTypeAssignableTo`** or **`ts.isTypeCompatibleWith`**, prioritizing **excess property checks** (e.g., a guard missing `required: true` fields). 3. **CI Integration:** - Output **JUnit XML** (for CI like GitHub Actions) or **GitHub Annotation Format** via **`@actions/github`**. - Fail builds on drift using **`process.exit(1)`** with a **color-coded TUI** (red for errors, yellow for warnings) via **ink.js**. **Dependencies:** - `@types/node`, `typescript` (v5.0+ for `tsc` API), - `ts-simple-ast` (for AST traversal), - `ink` (TUI), `@actions/github` (CI), - `zod` (for validating the JSON report schema).
📊 The Limitations of Current Alternatives
Existing tools like **`tsd`**, **`eslint-plugin-typescript`**, or **`@typescript-eslint`** lack **automated structural validation** of type guards. Developers must: - Manually audit guards post-type changes (e.g., adding `readonly` to an interface breaks `in` checks). - Rely on **ad-hoc tests** (e.g., `expect(isUser(x)).toBe(true)`), which miss edge cases like **optional properties** or **deeply nested types**. Enterprise solutions (e.g., **Snyk Code**, **SonarTypeScript**) focus on **security/vulnerabilities**, not **type-guard drift**. Their **static analysis** is shallow—missing the **semantic gap** between runtime checks and TypeScript’s type system. Even **`tsc --strict`** won’t catch guards that silently accept invalid shapes (e.g., `{ id: number }` vs. `{ id: string | undefined }`).
🎯 Key Engineering Value & Benefits
This tool **eliminates silent type-guard failures** by enforcing **compile-time-like checks at runtime boundaries**. For teams using **domain-specific types** (e.g., GraphQL schemas, API contracts), it: - **Reduces debug cycles** by catching drift **before** runtime errors (e.g., `TypeError: Cannot read property 'nested' of undefined`). - **Lowers CI noise** by replacing flaky tests with **deterministic type validation**. - **Future-proofs refactors**: Automates the **‘did you update the guard?’** mental tax, critical for **large codebases** (e.g., 100+ type guards in a monorepo). The **zero-maintenance** CI hook ensures **zero-cost enforcement**, while the **TUI** provides **actionable feedback** without context-switching to IDEs.
Relevant Platform Categories
Categories where this tool could be deployed or integrated.
