check-type-test-coverage

Report which exported .d.ts declarations are covered by a sibling *.test-d.ts file.

It walks a directory, pairs every *.test-d.ts with its matching *.d.ts, parses both, and tells you which exported types/values from the declaration file are exercised by a type-level assertion in the test file.

Requirements

• Node.js >= 22 (uses the built-in node:test runner and parseArgs)

Install

npm install --save-dev check-type-test-coverage

Or run it ad-hoc without installing:

npx check-type-test-coverage ./packages

Usage

check-type-test-coverage <dir> [options]

Options

| Flag | Default | Description | | ---------------- | ------- | ------------------------------------------------------------------------- | | --min <n> | 100 | Minimum overall coverage required to pass (0–100). | | --augmentation | false | Also count declarations added via declare module "..." augmentation blocks. Off by default, so a package whose only surface is augmentation is not silently reported as 100%. | | --ignore <glob>| — | Skip files matching this glob. Repeatable, e.g. --ignore '**/vendor/**' --ignore '**/*.gen.d.ts'. | | --tsconfig <p> | — | Use this tsconfig's baseUrl/paths for module resolution. Needed to match --augmentation across path-aliased modules (e.g. import { X } from "pkg/x"). | | --namespace-members | false | Also count members declared inside an exported namespace that lack an explicit export — in a .d.ts they're still accessible API. Skips _-prefixed internal names. Without this, a namespace counts as one declaration regardless of how many functions it hides. | | --json | false | Emit machine-readable JSON instead of the human-readable report. | | --verbose | false | Show all unrecognized assertions and extra diagnostics. | | -h, --help | — | Show usage. |

Exit codes

| Code | Meaning | | ---- | --------------------------------------------- | | 0 | Coverage >= --min. | | 1 | Coverage below --min. | | 2 | Usage error (missing/invalid arguments). |

Examples

Check a packages directory and require full coverage:

check-type-test-coverage ./packages

Allow partial coverage (useful while ramping up):

check-type-test-coverage ./packages --min 80

Emit JSON for downstream tooling:

check-type-test-coverage ./packages --json > coverage.json

How it works

1. Walks <dir> and finds every *.d.ts and *.test-d.ts.
2. Pairs each test file with its sibling *.d.ts:
   • Tests without a sibling declaration are reported as orphans.
   • Declaration files without a sibling test are reported as untested and contribute 0% to the overall coverage (all their exported declarations count as uncovered).
3. Parses both files via the TypeScript compiler API to:
   • Collect every exported declaration from the .d.ts.
   • Collect every type-level assertion from the .test-d.ts.
4. Reports the percentage of declarations referenced by at least one assertion.

Scripts

npm test            # run the test suite
npm run test:coverage  # run tests with 100% coverage gate

Project layout

.
├── index.js           # CLI entry point
├── src/
│   ├── lib.js         # walk + evaluate pipeline
│   ├── tsAnalyze.js   # TS AST analysis (declarations + assertions)
│   ├── files.js       # filesystem traversal / pairing
│   ├── report.js      # human + aggregate report rendering
│   └── utils.js
└── test/              # node:test suite + fixtures

License

MIT © Italo Jose