dead-code-cleanup

---
name: "dead-code-cleanup"
description: "Identify and safely remove dead code, deprecated code, and unused exports from codebase. Use when you need to clean up unused or obsolete code."
license: "MIT"
---

# Dead Code Cleanup Command

## Purpose

Systematically identify and remove unused code while maintaining project integrity.

**Target Code**:

- Unused exports/functions/classes with no references
- Deprecated code without active migration plan
- Orphaned files (no imports from anywhere)
- Unreachable code paths

**Critical Constraint**: Project must build and pass all tests after cleanup.

---

## User Input

```text
$ARGUMENTS
```

**Interpretation**:

| Input                      | Action                                            |
| -------------------------- | ------------------------------------------------- |
| Empty                      | Analyze entire codebase                           |
| Path (e.g., `src/legacy/`) | Analyze specified directory                       |
| `--dry-run`                | Report only, no deletions                         |
| `--auto`                   | Delete HIGH confidence items without confirmation |

---

## Preservation Rules (NEVER DELETE)

### Absolute Preservation

| Category                  | Detection Method                              | Examples                       |
| ------------------------- | --------------------------------------------- | ------------------------------ |
| **Public API**            | `package.json` exports, `index.ts` re-exports | Library entry points           |
| **Planned Features**      | TODO/FIXME with ticket/issue                  | `// TODO(#123): implement`     |
| **Framework Conventions** | Path-based (pages/, app/, api/)               | Next.js routes, NestJS modules |
| **Test Infrastructure**   | Imported by `*.test.*`, `*.spec.*`            | Fixtures, mocks, test utils    |
| **Dynamic Imports**       | `import()`, `require()` patterns              | Lazy loading, code splitting   |
| **Build Dependencies**    | Referenced in package.json scripts            | Build tools, CLI scripts       |
| **External Contracts**    | GraphQL types, API schemas                    | Schema definitions             |

### Special Cases

**Exported but unused internally**:

- Public library → PRESERVE (external consumers unknown)
- Private app → Flag for review

**Deprecated with timeline**:

- Deadline NOT passed → PRESERVE
- Deadline passed + no usage → DELETE

---

## Analysis Workflow

### Phase 1: Context Gathering

**1.1 Detect Project Type**

```bash
# Framework detection
[ -f "next.config.js" ] && echo "Next.js"
[ -f "tsconfig.json" ] && echo "TypeScript"
[ -f "go.mod" ] && echo "Go"
```

**1.2 Identify Package Scope**

```bash
# Public library vs private app
grep '"private": false' package.json && echo "PUBLIC_LIBRARY"
```

**1.3 Map Public API Surface**

- Check `package.json` exports field
- Find `index.ts` re-exports
- List Go exported symbols (capital letter)

### Phase 2: Dead Code Detection

**2.1 Unused Exports**

For each export statement:

1. Search for import references across codebase
2. Check dynamic import patterns
3. Verify not in public API surface

**2.2 Deprecated Code**

```bash
grep -rn "@deprecated" --include="*.ts" --include="*.go"
grep -rn "DEPRECATED" --include="*.ts" --include="*.go"
```

**2.3 Orphaned Files**

Files not imported anywhere:

- Exclude: entry points, config files, scripts
- Exclude: test files, type declarations
- Flag: utility files with no imports

### Phase 3: Validation

**For each candidate**:

1. **Cross-reference check**: Search all possible import patterns
2. **String reference check**: Filename as string (dynamic loading)
3. **Comment reference check**: TODO/FIXME mentioning future use
4. **Preservation rule check**: Apply rules from above

**Confidence Classification**:

| Level  | Criteria                                      | Action                      |
| ------ | --------------------------------------------- | --------------------------- |
| HIGH   | No references, not preserved, clear dead code | Auto-delete (with `--auto`) |
| MEDIUM | No direct refs, but string/comment mentions   | Ask confirmation            |
| LOW    | Exported publicly, ambiguous usage            | Report only                 |

### Phase 4: Safe Deletion

**4.1 Pre-Deletion**

```bash
# Warn if uncommitted changes
git status --porcelain | grep -q . && echo "⚠️ Uncommitted changes exist"
```

**4.2 Incremental Deletion**

- Delete in batches (5-10 items)
- Verify after each batch
- Stop on first failure

**4.3 Post-Deletion Verification**

```bash
# Must pass after each batch
{build_command}  # npm run build / go build ./...
{test_command}   # npm test / go test ./...
{lint_command}   # npm run lint / golangci-lint run
```

**4.4 Rollback on Failure**

```bash
git checkout -- {failed_files}
```

---

## Output Format

### Final Report

```markdown
# 🧹 Dead Code Cleanup Report

**Generated**: {timestamp}
**Scope**: {analyzed_paths}

---

## 📊 Summary

| Category        | Count   | Lines       |
| --------------- | ------- | ----------- |
| Unused Exports  | {n}     | {lines}     |
| Deprecated Code | {n}     | {lines}     |
| Orphaned Files  | {n}     | {lines}     |
| **TOTAL**       | **{n}** | **{lines}** |

---

## 🔴 DELETED (HIGH Confidence)

### {file_path}:{line}

- **Type**: {function/class/variable}
- **Reason**: No references found
- **Verification**: Build ✓ Tests ✓

---

## 🟡 SKIPPED - Needs Review

### {file_path}:{line}

- **Type**: {function/class/variable}
- **Reason**: {why detected as dead}
- **Skip Reason**: {why preserved}
- **Action**: {recommended next step}

---

## 🟢 PRESERVED (Matched Rules)

### {file_path}:{line}

- **Rule**: {which preservation rule}
- **Detail**: {specifics}

---

## ✅ Verification Results

- Build: {PASS/FAIL}
- Tests: {PASS/FAIL} ({passed}/{total})
- Lint: {PASS/FAIL}
```

---

## Key Rules

### ✅ Must Do

- Run build + tests after EVERY deletion batch
- Document skip reasons for every preserved item
- Report all skipped items in final summary
- Preserve items matching preservation rules

### ❌ Must Not Do

- Delete without verification
- Ignore preservation rules
- Skip final report generation
- Batch too many deletions (max 10 per batch)

### 🛡️ Safety First

- When uncertain → SKIP and report
- When ambiguous → Ask user
- When build fails → Rollback immediately

---

## Example Usage

```bash
# Report only (no deletions)
/dead-code-cleanup --dry-run

# Analyze specific directory
/dead-code-cleanup src/legacy/

# Auto-delete HIGH confidence items
/dead-code-cleanup --auto

# Default: interactive mode
/dead-code-cleanup
```