find-type-gaps

TODAY=!date +%Y-%m-%d

Find Type Gaps

Identifies missing or incomplete type annotations in gradually-typed codebases. Type coverage is a safety net that sits alongside test coverage: typed code catches a class of bugs at analysis time, makes refactoring safer, and reduces the cognitive load of reading unfamiliar code. This skill surfaces gaps ranked by how much adding types would help — prioritizing public API surfaces and high-churn files.

Prerequisites

• Working directory is the root of the repository
• Optional: $1 — path to limit the scan (defaults to .)
• Language support:
  • Python: mypy (uv tool install mypy) or pyright (npm install -g pyright)
  • TypeScript: type errors via tsc --noEmit; strict mode gaps via tsconfig.json flags
  • JavaScript: @ts-check JSDoc annotations; tsc --allowJs --checkJs
• Not applicable to fully-typed languages (Go, Rust, Java, C#)

What Counts as a Type Gap

Language	Gap
Python	Function parameter with no annotation; return type missing; Any used where a concrete type is possible; untyped class attribute
TypeScript	any used explicitly; as any cast; function with implicit any parameter; missing return type on exported function
JavaScript	No JSDoc @param/@returns; no @ts-check at file top; untyped exported function

Steps

1. Detect Language

find ${1:-.} -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -5

Proceed only if Python, TypeScript, or JavaScript files are present. Report "not applicable" for fully-typed languages.

2. Measure Type Coverage

Python — mypy:

mypy ${1:-.} \
  --ignore-missing-imports \
  --no-error-summary \
  --any-exprs-report .mypy-type-report \
  2>/dev/null | rg "error:|note:" | head -40

Parse the any-exprs report for per-file coverage:

cat .mypy-type-report/any-exprs.txt 2>/dev/null | \
  awk 'NR>1 {print $3"% typed\t"$1}' | sort -n | head -30

Python — pyright (stricter, faster):

pyright ${1:-.} --outputjson 2>/dev/null | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
for d in data.get('generalDiagnostics', []):
    if 'unknown' in d.get('message','').lower() or 'Any' in d.get('message',''):
        print(d['file'].split('/')[-1], d['range']['start']['line'], d['message'][:80])
" 2>/dev/null | head -30