io.github.CloudCorpRecords/typegap

typegap

Every codebase has files where the types gave up: a cast to any here, a @ts-ignore there. typegap tells you which of those files hurt most. It counts type debt per file and weights each file's score by how many other files import it, so a sloppy file that half the codebase depends on ranks above an equally sloppy leaf file nobody touches.

• The any count — six textual pattern families, applied line by line in a fixed order, with each family's matched spans removed before the next family runs so no span is counted twice:

  1. Array<any> (a boundary — a character that is not [A-Za-z0-9_$], or the line edge — is required before Array)
  2. Record<string, any> and Record<string,any> (a boundary is required before Record)
  3. <any> (no boundary requirement)
  4. any[] (a boundary is required before any, which is why company[] does not count)
  5. : any (the character after any must be a boundary)
  6. as any (a boundary is required before as and after any, which is why has any does not count)

  Because earlier families remove their spans, Array<any> counts once rather than again as <any>, and : any[] counts once under any[].

• Suppression counts — plain substring counts over the whole file: @ts-ignore, @ts-expect-error, and @ts-nocheck.
• Debt and blast radius — debt = 2 * any_count + 3 * ts_ignore_count + 1 * ts_expect_error_count + 5 * ts_nocheck_count, and blast_radius = debt * (1 + imported_by). Suppressions that silence the compiler weigh more than a stray any, and @ts-nocheck — which opts a whole file out — weighs most of all.

Counting is textual on purpose: comments and string literals are not parsed, so a pattern inside one counts like code. That keeps the tool deterministic and honest about its scope — it measures where debt markers cluster, not what the compiler thinks of them.

The result lists only the files with debt, sorted by blast radius descending, then debt descending, then path ascending. Alongside the list it reports how many files were scanned, how many carry debt, the any and debt totals over every supplied file, and the worst file's path (null when nothing supplied carries debt).

Validation is strict: a missing or empty file list, a file missing its path or content, an empty, non-string, or duplicate path, a non-string content, or an imported_by that is not an integer >= 0 is an error naming the offending path (for example files[1].imported_by must be an integer >= 0), and no partial ranking is produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/typegap rank --input args.json
npx @reneturcios/typegap --version

args.json contains the full arguments object:

{
  "files": [
    {
      "path": "src/api.ts",
      "content": "let raw: any;\n// @ts-ignore\n",
      "imported_by": 12
    },
    { "path": "src/clean.ts", "content": "export const n: number = 1;\n" }
  ]
}

imported_by is optional per file and defaults to 0; content is required but may be empty. The ranking is printed as JSON:

{
  "files": [
    {
      "path": "src/api.ts",
      "any_count": 1,
      "ts_ignore_count": 1,
      "ts_expect_error_count": 0,
      "ts_nocheck_count": 0,
      "debt": 5,
      "imported_by": 12,
      "blast_radius": 65
    }
  ],
  "scanned_files": 2,
  "files_with_debt": 1,
  "total_any": 1,
  "total_debt": 5,
  "worst_file": "src/api.ts"
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/typegap mcp

MCP client config:

{
  "mcpServers": {
    "typegap": {
      "command": "npx",
      "args": ["-y", "@reneturcios/typegap", "mcp"]
    }
  }
}

Tools

• rank_type_debt — Rank files by type debt.

  • files (array, required, at least one) — source files as {path, content, imported_by?} objects; path is unique across the set, content is the full source text, and imported_by says how many other files import the file

  Returns {files, scanned_files, files_with_debt, total_any, total_debt, worst_file}.

Docker

docker run -i ghcr.io/cloudcorprecords/typegap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/typegap rank --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios