TypeScript type coverage auditor — find the holes without compiling
TypeScript is only as strong as its type annotations. any creeps in during rapid prototyping, functions lose explicit return types, and noImplicitAny stays disabled "just for now." Over time, this erodes the safety net.
typegap works statically — it parses ASTs from .ts/.tsx files and reports type holes without needing tsc to succeed.
The package is not published to npm yet. Install the current version from a source checkout:
git clone https://github.com/rogerchappel/typegap.git
cd typegap
npm ci
npm run build
npm install --global .
# Scan current directory
typegap
# Scan a specific directory with detail
typegap ./src --detail
# Output as JSON
typegap --format json
# Set a minimum coverage threshold (exits 1 if below)
typegap --min-coverage 90
# Save and compare baselines
typegap --baseline coverage.json
# ... later ...
typegap --compare coverage.jsonThe global install points at the checkout, so rebuild after pulling changes.
When the first npm release is available, npm install --global typegap will
become the registry installation path; it is not supported today.
Until registry publication, import the built entry point from the checkout:
import { analyzeDirectory } from "./typegap/dist/index.js";
const result = await analyzeDirectory("./src");
console.log(result.coverage);| Issue | Description |
|---|---|
| 🔴 any | Annotations containing any, including nested weak types |
| 🟣 unknown | Annotations containing unknown, including nested weak types |
Missing type annotations — implicit any or missing return types |
It also catches weak types nested in generics (Array<any>, Record<string, any>), object type properties, methods and index signatures, and function type
parameters or returns. When one annotation contains both, any takes precedence
over unknown.
TypeGap — Type Coverage Report
Coverage: 64.3%
Files: 12
Annotatable: 140
Annotated: 90
Implicit: 50
Any: 8
Unknown: 2
Files
┌────────────────────────────────────────────────────────────┐
│ 100.0% ✓ src/utils/helpers.ts
│ 75.0% src/core/parser.ts (1 any, 2 implicit)
│ 50.0% src/api/handler.ts (5 any, 3 implicit)
└────────────────────────────────────────────────────────────┘
Details
src/api/handler.ts:42 any → process(data)
src/api/handler.ts:58 implicit → transform(params)
src/core/utils.ts:15 implicit → format(value)
| Flag | Description |
|---|---|
[directory] |
Directory to scan (default: .) |
--ignore <patterns> |
Glob patterns to ignore (comma-separated) |
--format <type> |
Output format: text or json (default: text) |
--detail |
Show per-file type annotation details |
--baseline <file> |
Save coverage baseline to a JSON file |
--compare <file> |
Compare against a saved baseline |
--min-coverage <n> |
Exit non-zero if coverage drops below n% |
--pattern <pattern> |
Custom glob pattern for target files |
CI should also run from a source checkout until the package is published:
# .github/workflows/types-lint.yml
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm run build
- name: Check type coverage
run: node dist/cli.js --min-coverage 80- Finds all
.ts/.tsxfiles using glob - Parses each file with
@typescript-eslint/typescript-estree - Walks the AST for functions, arrows, parameters, variables
- Classifies each annotatable node: explicit,
any,unknown, or implicit - Calculates coverage as
(total - implicit) / total * 100
- Function / arrow return types
- Function / arrow parameters (including destructured and rest params)
- Variable declarations with explicit type annotations
- Catch clause parameters
Constructor methods are excluded (they cannot have return types). Inferred-only variables (e.g., const x = 5) are not flagged — only explicit annotation sites are audited.
See CONTRIBUTING.md for setup and development guidelines.
git clone https://github.com/rogerchappel/typegap.git
cd typegap
npm install
npm run build
npm test- TypeScript type coverage auditor — find the holes without compiling; it is intended for local, reviewable developer workflows rather than unattended production automation.
- Review generated output before using it in commits, releases, issue updates, or connector actions.
- Avoid passing secrets, private customer data, or unredacted logs through fixtures, examples, or command output.
- Treat warnings and non-zero exits from
typegapas review signals, then rerun the documented verification command after changes.
MIT © Roger Chappel
Typegap supports Node.js 20.19+ and 22 or newer. Node.js 21 is not supported because the shipped runtime dependency set does not support those releases.
Run the same release gate used by CI before opening a PR:
npm run release:checkThe release gate covers:
npm run audit:all- audit the complete dependency graph, including development toolingnpm run audit:prod- audit shipped dependencies for known vulnerabilitiesnpm run check- tsc --noEmitnpm run lint- eslint src --ext .tsnpm run build- tsc && chmod +x dist/cli.jsnpm test- vitest run --coveragenpm run smoke- npm run build && node dist/cli.js --help && node dist/cli.js fixtures --format textnpm run validate- bash scripts/validate.shnpm run package:smoke- npm run build && node scripts/package-smoke.mjsnpm run release:check- full and production audits, typecheck, lint, tests, smoke checks, and package smoke check
Typegap is currently available from its source checkout, not the npm registry. The commands in Quick Start are the supported installation workflow while the project prepares its first release.
Run the release gate before tagging or publishing:
npm run release:check
npm pack --dry-runThe package smoke check prints the tarball contents, installs the current checkout into an isolated npm prefix, invokes the installed CLI, and imports the public API. This catches missing runtime files and stale installation instructions before release.