Type-aware TypeScript analysis

Fallow's default analysis is Rust-native, syntactic, and independent of Node.js or the TypeScript compiler. Add --type-aware when a cleanup or refactor depends on exact TypeScript symbol identity across aliases, re-exports, packages, or tests.

The optional companion adds five project-wide capabilities:

• exact symbol-use confirmation for existing dead-code candidates
• symbol traces with namespaces, aliases, and re-export hops
• package API surfaces and cross-file private type leaks
• exact consumers, affected files, and targeted tests
• advisory public-signature type coupling

Use this pass when an actual cleanup or refactor decision depends on TypeScript identity. Keep the normal syntactic run for fast everyday feedback.

fallow type-aware status --format json --quiet
fallow dead-code --unused-class-members --type-aware --format json --quiet
fallow fix --type-aware --dry-run --format json --quiet
fallow dead-code --type-aware --symbol-impact src/api.ts:Client --format json --quiet
fallow health --type-aware --type-coupling --format json --quiet

What this does not replace

Keep tsc --noEmit responsible for compiler correctness. Keep Oxlint responsible for local lint rules. Fallow does not emit TypeScript diagnostics or duplicate local typed lint findings.

Type-aware fallow answers project-wide questions those tools do not:

• Is this exact declaration used through an alias or re-export?
• Which production files and tests depend on this exported symbol?
• Does a public signature expose a package-private type?
• Which public types couple packages or modules together?

Conservative results

Every semantic result reports complete, partial, or unavailable. Fallow removes a dead-code candidate only when the checker resolves its exact declaration identity. Partial or unavailable analysis keeps the original finding and reports a stable omission reason.

fallow fix --type-aware offers a class-member removal only after every owning project returns complete negative evidence and the declaration guard still matches. Always preview with --dry-run.

Use --type-aware-require complete in CI when incomplete semantic evidence must fail the job:

fallow dead-code --type-aware --type-aware-require complete \
  --format json --quiet

Use repeatable --type-aware-project flags when automatic project selection does not include every consumer:

fallow dead-code --type-aware \
  --type-aware-project tsconfig.json \
  --type-aware-project packages/web/tsconfig.json \
  --format json --quiet

Svelte virtual-module exports

Svelte language tooling creates virtual TypeScript modules for .svelte files. TypeScript-Go does not yet expose the plugin integration needed for fallow to construct the same virtual modules. Default component imports and named exports backed by checker-visible declarations remain supported.

When a selected project uses a named import, named re-export, or wildcard re-export whose .svelte target cannot be resolved, fallow abstains with svelte-virtual-module-exports. The project and affected semantic queries are reported as unavailable. Best-effort mode keeps the syntactic result as advisory evidence, while --type-aware-require complete fails the run.

Run svelte-check for authoritative Svelte and TypeScript diagnostics. Do not rewrite valid component exports just to satisfy fallow. Keep the Svelte project configuration intact and use the omission reason until TypeScript-Go provides a supported virtual-module host integration.

Persistent configuration

Keep the feature opt-in per repository:

{
  "typeAware": {
    "enabled": true,
    "projects": ["tsconfig.json"],
    "require": "best-effort"
  }
}

Start with best-effort. Use complete only when partial or unavailable semantic evidence must fail the run.

Performance

Type-aware analysis constructs an additional TypeScript Program and scans checker symbols. On the current public release corpus, marginal overhead is about 92 ms at the median and 2.3 seconds at P95. Large projects can take longer. Editor sessions reuse the loaded Program, while one-shot CLI and CI runs pay the cold setup cost.

Installation

The fallow npm package installs a version-matched optional fallow-type-aware companion. If optional dependencies are disabled, install the exact same version manually. fallow type-aware status verifies discovery, package version, protocol version, and backend version without analyzing the project.

See also