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:

•Search for import references across codebase
•Check dynamic import patterns
•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:

•Cross-reference check: Search all possible import patterns
•String reference check: Filename as string (dynamic loading)
•Comment reference check: TODO/FIXME mentioning future use
•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