docs: enhance 5 thin commands and add Rust API example

Commands enhanced with multi-language support, error recovery strategies,
and structured step-by-step workflows:
- build-fix: build system detection table, fix loop, recovery strategies
- test-coverage: framework detection, test generation rules, before/after report
- refactor-clean: safety tiers (SAFE/CAUTION/DANGER), multi-language tools
- update-codemaps: codemap format spec, diff detection, metadata headers
- update-docs: source-of-truth mapping, staleness checks, generated markers

New example:
- rust-api-CLAUDE.md: Axum + SQLx + PostgreSQL with layered architecture,
  thiserror patterns, compile-time SQL verification, integration test examples
This commit is contained in:
Affaan Mustafa
2026-02-12 15:38:27 -08:00
parent 4209421349
commit 733295b44e
6 changed files with 611 additions and 91 deletions

View File

@@ -1,28 +1,80 @@
# Refactor Clean
Safely identify and remove dead code with test verification:
Safely identify and remove dead code with test verification at every step.
1. Run dead code analysis tools:
- knip: Find unused exports and files
- depcheck: Find unused dependencies
- ts-prune: Find unused TypeScript exports
## Step 1: Detect Dead Code
2. Generate comprehensive report in .reports/dead-code-analysis.md
Run analysis tools based on project type:
3. Categorize findings by severity:
- SAFE: Test files, unused utilities
- CAUTION: API routes, components
- DANGER: Config files, main entry points
| Tool | What It Finds | Command |
|------|--------------|---------|
| knip | Unused exports, files, dependencies | `npx knip` |
| depcheck | Unused npm dependencies | `npx depcheck` |
| ts-prune | Unused TypeScript exports | `npx ts-prune` |
| vulture | Unused Python code | `vulture src/` |
| deadcode | Unused Go code | `deadcode ./...` |
| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
4. Propose safe deletions only
If no tool is available, use Grep to find exports with zero imports:
```
# Find exports, then check if they're imported anywhere
```
5. Before each deletion:
- Run full test suite
- Verify tests pass
- Apply change
- Re-run tests
- Rollback if tests fail
## Step 2: Categorize Findings
6. Show summary of cleaned items
Sort findings into safety tiers:
Never delete code without running tests first!
| Tier | Examples | Action |
|------|----------|--------|
| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
## Step 3: Safe Deletion Loop
For each SAFE item:
1. **Run full test suite** — Establish baseline (all green)
2. **Delete the dead code** — Use Edit tool for surgical removal
3. **Re-run test suite** — Verify nothing broke
4. **If tests fail** — Immediately revert with `git checkout -- <file>` and skip this item
5. **If tests pass** — Move to next item
## Step 4: Handle CAUTION Items
Before deleting CAUTION items:
- Search for dynamic imports: `import()`, `require()`, `__import__`
- Search for string references: route names, component names in configs
- Check if exported from a public package API
- Verify no external consumers (check dependents if published)
## Step 5: Consolidate Duplicates
After removing dead code, look for:
- Near-duplicate functions (>80% similar) — merge into one
- Redundant type definitions — consolidate
- Wrapper functions that add no value — inline them
- Re-exports that serve no purpose — remove indirection
## Step 6: Summary
Report results:
```
Dead Code Cleanup
──────────────────────────────
Deleted: 12 unused functions
3 unused files
5 unused dependencies
Skipped: 2 items (tests failed)
Saved: ~450 lines removed
──────────────────────────────
All tests passing ✅
```
## Rules
- **Never delete without running tests first**
- **One deletion at a time** — Atomic changes make rollback easy
- **Skip if uncertain** — Better to keep dead code than break production
- **Don't refactor while cleaning** — Separate concerns (clean first, refactor later)