find-dead-code

# Find Dead Code

Identify dead code in a codebase. **Core rule: code only used in tests is still dead code.** Only production usage counts.

## Step 1: Detect Languages, Scope & Test Boundaries

Determine the project structure:

1. Check for config files: `package.json`, `tsconfig.json`, `pyproject.toml`, `setup.py`, `Package.swift`, `.xcodeproj`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`
2. Glob for source files: `**/*.ts`, `**/*.py`, `**/*.swift`, `**/*.go`, `**/*.rs`, `**/*.java`
3. Identify source roots — where production code lives (e.g., `src/`, `lib/`, `Sources/`)
4. **Partition the codebase** into analysis units by top-level source directories (e.g., `src/auth/`, `src/api/`, `src/utils/`, `lib/models/`). Each directory becomes one subagent's scope in Step 3.

If the user specified a scope, restrict analysis to that scope.

### Test File Patterns

Establish which files are test files. Code referenced ONLY from these locations is dead.

| Language | Test file patterns |
|----------|-------------------|
| TS/JS | `*.test.{ts,tsx,js,jsx}`, `*.spec.{ts,tsx,js,jsx}`, `__tests__/**`, `__mocks__/**`, `*.stories.{ts,tsx,js,jsx}` |
| Python | `test_*.py`, `*_test.py`, `tests/**`, `test/**`, `conftest.py` |
| Swift | `*Tests.swift`, `*Test.swift`, `Tests/**`, `*UITests.swift`, `XCTestCase` subclasses |
| Go | `*_test.go`, `testdata/**` |
| Rust | `tests/**`, `benches/**`, `#[cfg(test)]` modules (inline test modules within source files) |
| Java/Kotlin | `src/test/**`, `*Test.java`, `*Tests.java`, `*Spec.java`, `*Test.kt` |
| General | `fixtures/**`, `__fixtures__/**`, `mocks/**`, `testutils/**`, `testhelpers/**`, `spec/**` |

Also exclude: test runner configs (`jest.config.*`, `vitest.config.*`, `pytest.ini`), storybook files, benchmark files.

## Step 2: Quick Wins — CLI Tools (Optional)

If a CLI tool is installed, run it as a fast first pass for **zero-reference** dead code.

| Language | Tool | Check | Run |
|----------|------|-------|-----|
| TS/JS | `knip` | `npx knip --version` | `npx knip --no-exit-code` |
| Python | `vulture` | `vulture --version` | `vulture <src_dirs> --min-confidence 80` |
| Swift | `periphery` | `which periphery` | `periphery scan --skip-build` |
| Go | `deadcode` | `which deadcode` | `deadcode ./...` |
| Rust | compiler warnings | — | `cargo build 2>&1 \| grep "dead_code"` |

**Important limitation:** CLI tools count test imports as real usage. They **cannot** detect code that is only used in tests. They only find symbols with literally zero references anywhere. Step 3 is required for test-only detection.

If no CLI tool is installed, skip to Step 3. Do not ask the user to install anything.

## Step 3: Test-Only Analysis — Parallel Subagents (Core)

This is the primary analysis. Use the Agent tool to launch one subagent per top-level source directory from Step 1 in a single assistant message so they run concurrently. Each Agent call uses `model: "opus"` and does not set `run_in_background`. Expect one Agent tool call per directory, capped at 8 by the Rules section. State the count explicitly when emitting the calls.

### Subagent Strategy

Each subagent receives:

1. **Its assigned directory** to scan for exported symbols
2. **The test file patterns** from Step 1
3. **The full project root path** so it can grep across the entire codebase

### Subagent Task

Each subagent performs these steps on its assigned directory:

**a) Find exported/public symbols:**

| Language | Exported symbol patterns |
|----------|--------------------------|
| TS/JS | `export function`, `export const`, `export let`, `export var`, `export class`, `export interface`, `export type`, `export enum`, `export default`, `module.exports` |
| Python | Top-level `def` and `class` in non-`_`-prefixed modules, module-level constants (`FOO = ...`), symbols in `__all__`, public functions (no `_` prefix) |
| Swift | `public func`, `public var`, `public let`, `public class`, `public struct`, `public enum`, `public protocol`, `open class`, `open func`, `open var` |
| Go | Capitalized identifiers: `func FooBar`, `type FooBar struct`, `var FooBar`, `const FooBar` (Go uses capitalization for public visibility) |
| Rust | `pub fn`, `pub struct`, `pub enum`, `pub trait`, `pub const`, `pub static`, `pub type`, `pub mod` |
| Java/Kotlin | `public class`, `public static`, `public void`, `public` fields, `val`/`var` properties, `fun ` (top-level), `@Bean`, `@Component`, `@Service` annotated classes |

**b) For each symbol, grep across the entire codebase** for references, excluding:
- The definition file itself
- Generated/vendored directories (`node_modules/`, `dist/`, `build/`, `vendor/`, `__pycache__/`, `.tox/`, `.build/`, `DerivedData/`, `target/`)

**c) Classify each reference** as test or production based on the test file patterns.

**CRITICAL — same-module references count as production usage.** A symbol called by another production file within the same module/package is alive. Do not report symbols as "dead" when they have zero *external* callers but are used internally. Only report symbols with zero production references from *any* file. "Unnecessarily public" (could be `internal`/unexported) is a visibility issue, not dead code — do not include it.

**d) Report structured results** for each symbol:
- Symbol name, type (function/class/const/etc.), definition file and line range
- Number of production references (with file paths) — including same-module references
- Number of test references (with file paths)
- Classification: `dead` (zero prod refs anywhere), `test-only` (only test refs), `alive` (has prod refs)

### Merging Results

After all subagents complete, collect and merge their results. Deduplicate any symbols that appear in multiple reports (e.g., re-exports).

## Step 4: Filter, Classify & Evaluate

Apply these filters to the merged results from Steps 2 and 3:

1. **Framework entry points**: Skip symbols used by convention — React components in barrel files, Django views in URL con