tomevault-io 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
$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
# Framework detection
[ -f "next.config.js" ] && echo "Next.js"
[ -f "tsconfig.json" ] && echo "TypeScript"
[ -f "go.mod" ] && echo "Go"
1.2 Identify Package Scope
# Public library vs private app
grep '"private": false' package.json && echo "PUBLIC_LIBRARY"
1.3 Map Public API Surface
- Check
package.jsonexports field - Find
index.tsre-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
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
# 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
# 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
git checkout -- {failed_files}
Output Format
Final Report
# 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
# 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.