dead-code-detector

What this skill does

# Dead Code Detector

Find and remove unused code across Python, TypeScript, and Rust codebases.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## Tools by Language

| Language   | Tool                                                      | Detects                                       |
| ---------- | --------------------------------------------------------- | --------------------------------------------- |
| Python     | [vulture](https://github.com/jendrikseipp/vulture) v2.14+ | Unused imports, functions, classes, variables |
| TypeScript | [knip](https://knip.dev/) v5.0+                           | Unused exports, dependencies, files           |
| Rust       | `cargo clippy` + `rustc` lints                            | Unused functions, imports, dead_code warnings |

**Why these tools?**

- **vulture**: AST-based, confidence scoring (60-100%), whitelist support
- **knip**: Successor to ts-prune (maintenance mode), monorepo-aware, auto-fix
- **cargo clippy**: Built-in to Rust toolchain, zero additional deps

---

## When to Use This Skill

Use this skill when:

- Cleaning up a codebase before release
- Refactoring to reduce maintenance burden
- Investigating bundle size / compile time issues
- Onboarding to understand what code is actually used

**NOT for**: Code duplication (use `quality-tools:code-clone-assistant`)

---

## Quick Start Workflow

### Python (vulture)

```bash
# Step 1: Install
uv pip install vulture

# Step 2: Scan with 80% confidence threshold
vulture src/ --min-confidence 80

# Step 3: Generate whitelist for false positives
vulture src/ --make-whitelist > vulture_whitelist.py

# Step 4: Re-scan with whitelist
vulture src/ vulture_whitelist.py --min-confidence 80
```

### TypeScript (knip)

```bash
# Step 1: Install (project-local recommended)
bun add -d knip

# Step 2: Initialize config
bunx knip --init

# Step 3: Scan for dead code
bunx knip

# Step 4: Auto-fix (removes unused exports)
bunx knip --fix
```

### Rust (cargo clippy)

```bash
# Step 1: Scan for dead code warnings
cargo clippy -- -W dead_code -W unused_imports -W unused_variables

# Step 2: For stricter enforcement
cargo clippy -- -D dead_code  # Deny (error) instead of warn

# Step 3: Auto-fix what's possible
cargo clippy --fix --allow-dirty
```

---

## Confidence and False Positives

### Python (vulture)

| Confidence | Meaning                                     | Action                          |
| ---------- | ------------------------------------------- | ------------------------------- |
| 100%       | Guaranteed unused in analyzed files         | Safe to remove                  |
| 80-99%     | Very likely unused                          | Review before removing          |
| 60-79%     | Possibly unused (dynamic calls, frameworks) | Add to whitelist if intentional |

**Common false positives** (framework-invoked code):

- Route handlers / controller methods (invoked by web frameworks)
- Test fixtures and setup utilities (invoked by test runners)
- Public API surface exports (re-exported for consumers)
- Background job handlers (invoked by task queues / schedulers)
- Event listeners / hooks (invoked by event systems)
- Serialization callbacks (invoked during encode/decode)

### TypeScript (knip)

Knip uses TypeScript's type system for accuracy. Configure in `knip.json`:

```json
{
  "entry": ["src/index.ts"],
  "project": ["src/**/*.ts"],
  "ignore": ["**/*.test.ts"],
  "ignoreDependencies": ["@types/*"]
}
```

### Rust

Suppress false positives with attributes:

```rust
#[allow(dead_code)]  // Single item
fn intentionally_unused() {}

// Or module-wide
#![allow(dead_code)]
```

---

## Integration with CI

### Python (pyproject.toml)

```toml
[tool.vulture]
min_confidence = 80
paths = ["src"]
exclude = ["*_test.py", "conftest.py"]
```

### TypeScript (package.json)

```json
{
  "scripts": {
    "dead-code": "knip",
    "dead-code:fix": "knip --fix"
  }
}
```

### Rust (Cargo.toml)

```toml
[lints.rust]
dead_code = "warn"
unused_imports = "warn"
```

---

## Reference Documentation

For detailed information, see:

- [Python Workflow](./references/python-workflow.md) - vulture advanced usage
- [TypeScript Workflow](./references/typescript-workflow.md) - knip configuration
- [Rust Workflow](./references/rust-workflow.md) - clippy lint categories

---

## Troubleshooting

| Issue                          | Cause                         | Solution                                                       |
| ------------------------------ | ----------------------------- | -------------------------------------------------------------- |
| Reports framework-invoked code | Framework magic / callbacks   | Add to whitelist or exclusion config                           |
| Misses dynamically loaded code | Not in static entry points    | Configure entry points to include plugin/extension directories |
| Warns about test-only helpers  | Test code compiled separately | Use conditional compilation or test-specific exclusions        |
| Too many false positives       | Threshold too low             | Increase confidence threshold or configure ignore patterns     |
| Missing type-only references   | Compile-time only usage       | Most modern tools handle this; check tool version              |

---

## Multi-Perspective Validation (Critical)

**IMPORTANT**: Before removing any detected "dead code", spawn parallel subagents to validate findings from multiple perspectives. Dead code may actually be **unimplemented features** or **incomplete integrations**.

### Classification Matrix

| Finding Type          | True Dead Code                | Unimplemented Feature               | Incomplete Integration        |
| --------------------- | ----------------------------- | ----------------------------------- | ----------------------------- |
| Unused callable       | No callers, no tests, no docs | Has TODO/FIXME, referenced in specs | Partial call chain exists     |
| Unused export/public  | Not imported anywhere         | In public API, documented           | Used in sibling module        |
| Unused import/include | Typo, refactored away         | Needed for side effects             | Type-only or compile-time     |
| Unused binding        | Assigned but never read       | Placeholder for future              | Debug/instrumentation removed |

### Validation Workflow

After running detection tools, **spawn these parallel subagents**:

```
┌─────────────────────────────────────────────────────────────────┐
│                    Dead Code Findings                           │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Intent Agent    │ │ Integration     │ │ History Agent   │
│                 │ │ Agent           │ │                 │
│ - Check TODOs   │ │ - Trace call    │ │ - Git blame     │
│ - Search specs  │ │   chains        │ │ - Commit msgs   │
│ - Find issues   │ │ - Check exports │ │ - PR context    │
│ - Read ADRs     │ │ - Test coverage │ │ - Author intent │
└─────────────────┘ └─────────────────┘ └─────────────────┘
          │                   │                   │
          └───────────────────┼───────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              AskUserQuestion: Confirm Classification            │
│  [ ] True dead code - safe to remove                            │
│  [ ] Unimplemented - create GitHub Issue to track               │
│  [ ] Incomplete - investigate integration gaps                  │
│  [ ] False positive - add to whitelist                          │
└──────────────────────────────────