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). | | --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