raintree-technology/cleanup-weak-types

Replace weak escape-hatch types with strong types inferred from actual usage. Per-occurrence verification — each replacement is typechecked individually, reverted if it breaks. Conservative on public APIs.

Preflight

1. Language detect: TS/JS (any, unknown, as unknown as, Function, Object), Python (Any, missing type hints), Go (interface{}, any since 1.18), Rust (Box<dyn Any> is rare; mostly look for Box<dyn Trait> where a concrete type would do).
2. Git state: refuse on dirty tree.
3. Report dir: ensure exists.
4. Read project conventions: check for a check:weak-types or similar script in package.json. Check tsconfig.json for strict/noImplicitAny flags. Check mypy.ini / pyproject.toml [tool.mypy] for strictness.
5. Read allow-list: many projects allow weak types in specific files (e.g., *.test.ts, generated code, third-party shim files). Find and respect them.

Detect

TypeScript / JavaScript

# Explicit `any`
grep -rn --include="*.ts" --include="*.tsx" -E "\b(: any\b|<any>|as any\b|as unknown as)" \
  --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.next . > /tmp/ts-weak.txt

# Compiler-derived implicit-any (more accurate than grep)
npx tsc --noImplicitAny --noEmit 2>&1 | grep "implicitly has an 'any' type" > /tmp/ts-implicit-any.txt

For each occurrence, capture the surrounding context (function signature, callers).

Python

# Explicit Any imports + usage
grep -rn --include="*.py" -E "(from typing import.*Any|: Any\b|-> Any\b)" . > /tmp/py-any.txt

# Mypy strict mode finds untyped functions
mypy --disallow-untyped-defs --no-incremental . > /tmp/py-untyped.txt 2>&1 || true

Go

grep -rn --include="*.go" -E "\binterface\{\}|\bany\b" . > /tmp/go-any.txt

Rust

grep -rn --include="*.rs" -E "(Box<dyn |&dyn )" . > /tmp/rust-dyn.txt

Assess

Write .claude/cleanup-reports/cleanup-weak-types-{YYYY-MM-DD}.md:

# Weak Types Assessment — YYYY-MM-DD

## Summary
- Total weak-type sites: N
- HIGH (safe to auto-fix): X
- MEDIUM (public API or cross-package): Y
- LOW (justified — e.g., genuine unknown JSON, third-party): Z

## Findings

### HIGH — `apps/app/lib/parse.ts:45` `function process(data: any)`
- Inferable type: `data` is always called with `{ id: string; events: Event[] }` (3 callers checked).
- Replacement: `function process(data: { id: string; events: Event[] })`.
- Even better: lift to a named type `ProcessInput`.

### MEDIUM — `packages/sdk/src/client.ts:12` `function send(payload: any): Promise<any>`
- Public API of an SDK package — changing the type is a breaking change.
- Recommendation: introduce a generic `<T, R>` and have callers specify, OR use `unknown` and require validation.

### LOW — `lib/json.ts:8` `function parseJson(s: string): unknown`
- Genuinely unknown — JSON.parse output. Keep as `unknown`, ensure callers narrow.

## Critical Assessment
[2-3 paragraphs: where are weak types concentrated? Boundary code (HTTP handlers, JSON parsing) often justifies them. Internal logic almost never does.]

Apply

Auto-fix HIGH only, ONE AT A TIME with typecheck between each. This is essential — bulk type changes can cascade in hard-to-predict ways.

Confidence rubric

HIGH (auto-apply, individually):

• The weak type is in a private/internal function.
• All callers are in the same repo and pass the same type (or a small finite set easily expressed as a union).
• Replacement is mechanically derivable from usage.
• No re-export of the symbol from a package boundary.

MEDIUM (report only):

• Public API surface (exported from a package, used by a .d.ts, part of an SDK).
• Generic-amenable signatures (suggest the generic but don't apply).
• Discriminated union opportunities — the human picks the discriminator field.
• as unknown as casts — these usually indicate a deeper type design problem.

LOW (note, no action):

• Boundary code receiving genuine unknown input (HTTP body before validation, JSON.parse, dynamic config).
• Third-party shim files where the actual library is untyped.
• Test files (allowed in most weak-type allow-lists).

Execution (HIGH, individually)

For EACH HIGH finding:

1. Capture the exact git diff of the proposed change.
2. Apply the change (Edit).
3. Run scoped typecheck: npm run typecheck or npx tsc --noEmit. For Python: mypy <file>.
4. If typecheck fails OR introduces new errors elsewhere: git checkout -- <file>, downgrade this finding to MEDIUM in the report, continue.
5. If typecheck passes, move on.

After all HIGH findings processed, single commit: chore(cleanup): cleanup-weak-types — strengthened N type signatures.

Verify

# Full typecheck across the repo (not just changed files)
npm run typecheck 2>&1 || npx tsc --noEmit
mypy --strict . 2>&1 || mypy . 2>&1
go build ./... 2>&1
cargo check 2>&1

# Tests — important here, since type changes can affect runtime via narrowing
npm test 2>&1
pytest 2>&1
go test ./... 2>&1
cargo test 2>&1

# Project-specific weak-types gate (if the project defines one)
npm run check:weak-types 2>/dev/null || true

If anything fails after the per-file pass somehow (rare but possible across-file inference): revert all and downgrade. Should rarely happen because we typecheck after each.

Output

• "Strengthened N weak types. M deferred for review."
• Report path with breakdown of HIGH/MEDIUM/LOW.
• Verify status.

NEVER

• Bulk replace any with unknown — that's a different defect, not a fix. Both are weak; unknown just forces narrowing.
• Replace any with an over-narrow type that breaks one of N callers — verify ALL callers fit.
• Touch generated types (Drizzle $inferSelect, OpenAPI codegen, Prisma) — fix the codegen config instead.
• Add // @ts-ignore or # type: ignore to make the change pass — that's hiding the problem.
• Modify ambient .d.ts declarations for third-party libraries.
• Remove an as unknown as cast without understanding why it was added — it's often masking a type incompatibility worth investigating, not silently fixing.
• Auto-add generics to public APIs — that's a contract change requiring human design.