---
name: refactor-cleaner-skill
description: Dead code cleanup via pipeline knip + depcheck + ts-prune + javadoc-coverage (multi-language safe removal)
category: maintenance
triggers:
  - "dead code"
  - "unused"
  - "cleanup"
  - "remove unused imports"
  - "knip"
  - "depcheck"
  - "ts-prune"
license: MIT
author: Federico Calò
---

# Refactor cleaner skill

> Cleanup safe di dead code multi-language usando tool established (knip per
> JS/TS, depcheck per deps, ts-prune per export, javadoc-coverage per Java
> unused). Mai eliminare a occhio.

## When to invoke

Auto-invoke quando:

- Post-refactor architetturale (codice migrato, residui da pulire)
- Periodicamente (quarterly cleanup)
- Pre-release (riduzione bundle size)
- L'utente chiede "rimuovi import inutili" / "cleanup" / "dead code"

**Anti-trigger**: development attivo di una feature (cleanup pre-merge OK,
non mid-development); codice legacy intoccabile (no test → no safety net per
removal).

## Steps

### 1. Snapshot baseline

```bash
# Baseline: cosa è "vivo" oggi
git status
git diff --stat HEAD~10

# Test suite verde PRIMA di cleanup
npm test && mvn test && pytest
```

### 2. Run tool catalog ([knip-depcheck-tsprune-pipeline.md](references/knip-depcheck-tsprune-pipeline.md))

```bash
# TypeScript/JavaScript
npx knip                    # unused files, exports, deps
npx depcheck                # unused npm deps
npx ts-prune                # unused TS exports

# Python
pip install vulture
vulture src/                # unused code/imports

# Java
mvn dependency:analyze      # unused / undeclared deps
# IntelliJ: Code → Inspect → Unused declaration
```

### 3. Triage findings

Per ogni segnalazione:

- **Confermato dead** (no test, no import) → safe remove
- **Forse vivo** (riflessione, dynamic import, plugin) → KEEP (annota in
  `.knip.json` come excluded)
- **Test only** (usato solo da test) → valuta se test stesso è obsoleto

### 4. Remove iterativo

- Rimuovi **1 file/blocco alla volta**
- Run test suite dopo OGNI rimozione
- Se test fallisce → undo + investiga (era vivo)
- Commit atomico: `refactor: remove unused <module>`

### 5. Verify bundle/build impact

```bash
# Bundle size
npm run build && du -sh dist/

# Build time
time mvn clean package
```

### 6. Document

In SUMMARY.md aggiungi sezione "Dead code removed":

- File rimossi: N (LoC -X)
- Deps rimosse: N
- Bundle size impact: -Y KB
- Build time impact: -Zs

## Anti-patterns

- ❌ Rimuovere a occhio senza tool (false positive = lavoro 2x)
- ❌ Rimuovere senza test verdi pre-cleanup (no safety net)
- ❌ Rimuovere senza test post-ogni-step (impossibile sapere chi ha rotto)
- ❌ Commit batch "remove 50 unused files" (no bisect possibile)
- ❌ Ignorare riflessione / dynamic import / DI con stringa (false positive
  del tool)

## Tool comparison

| Tool | Linguaggio | Cosa rileva |
|------|------------|-------------|
| knip | JS/TS | File / export / deps / binari unused (più completo) |
| depcheck | JS/TS | Solo deps unused / mancanti (più semplice) |
| ts-prune | TS | Solo TypeScript export unused |
| vulture | Python | Code / import / variable unused |
| mvn dependency:analyze | Java/Maven | Deps unused / undeclared |
| `unimport` | Python | Solo import (più mirato) |

## References

- [knip-depcheck-tsprune-pipeline.md](references/knip-depcheck-tsprune-pipeline.md)
  — pipeline completa con config esempi
- [safe-removal-checklist.md](references/safe-removal-checklist.md) —
  checklist pre/post removal per evitare regression da dynamic reference

## Esempio invocazione

> **User**: "cleanup post-refactor del modulo blog"
>
> **Claude (con refactor-cleaner-skill)**:
> 1. Snapshot: git status pulito, test verdi ✓
> 2. `npx knip --workspace frontend` → 12 unused files, 3 unused deps, 47 exports
> 3. Triage: 8 files confermati dead, 4 falsi positivi (lazy route)
> 4. Remove iterativo 8 files + test post ogni: tutto verde
> 5. Bundle size: -28KB ✓
> 6. SUMMARY: "Removed 8 unused TS files (-2400 LoC), 3 deps (-2.1MB
>    node_modules), bundle -28KB"