prunify 0.1.5 → 0.1.7

package/README.md

@@ -28,7 +28,7 @@
 
 | Module | What it finds |
 |--------|---------------|
-| 🗑️ **Dead code** | Files and named exports that are never imported anywhere in the codebase |
+| 🗑️ **Dead code** | **Safe to delete** (nothing imports them), **transitively dead** (only dead files import them), and **dead exports** (live files with unused named exports) |
 | 🔁 **Duplicate code** | Functions with identical bodies, suspiciously similar names, and duplicate constants |
 | ♻️ **Circular imports** | Dependency cycles that can cause runtime bugs and bundler issues |
 | 📦 **Unused dependencies** | Packages declared in `package.json` that are never actually imported |
@@ -81,7 +81,7 @@ npx prunify --ci
 ✔ Parsed codebase — 142 file(s) found
 ✔ Import graph built — 389 edge(s)
 
-✔ Dead code analysis complete — 7 item(s) found
+✔ Dead code analysis complete — 3 safe to delete, 1 transitively dead, 3 dead export(s)
 ✔ Duplicate scan complete — 3 duplicate block(s) found
 ✔ Circular import analysis complete — 2 cycle(s) found
 ✔ Dependency audit complete — 4 issue(s) found
@@ -89,15 +89,22 @@ npx prunify --ci
 
 Summary
 
-┌──────────────────────┬───────┬──────────────────┐
-│ Check                │ Found │ Output File      │
-├──────────────────────┼───────┼──────────────────┤
-│ Dead Files / Exports │ 7     │ dead-code.txt    │
-│ Duplicate Clusters   │ 3     │ dupes.md         │
-│ Unused Packages      │ 4     │ deps.md          │
-│ Circular Deps        │ 2     │ circular.txt     │
-│ Unused Assets        │ 5     │ assets.md        │
-└──────────────────────┴───────┴──────────────────┘
+========================================
+  DEAD CODE REPORT
+  Safe to delete     : 3
+  Transitively dead  : 1
+  Dead exports       : 3
+  Recoverable        : ~12.4 KB
+========================================
+
+┌───────────────────────────┬───────┬──────────────────┐
+│ Check                     │ Found │ Output File      │
+├───────────────────────────┼───────┼──────────────────┤
+│ Circular Dependencies     │ 2     │ circular.txt     │
+│ Duplicate Clusters        │ 3     │ dupes.md         │
+│ Unused Packages           │ 4     │ deps.md          │
+│ Unused Assets             │ 5     │ assets.md        │
+└───────────────────────────┴───────┴──────────────────┘
 ```
 
 ---
@@ -112,10 +119,23 @@ Summary
 | `--ignore <pattern>` | — | Glob pattern to exclude from analysis. Repeatable. |
 | `--out <path>` | `<dir>/prunify-reports/` | Directory to write report files to. |
 | `--html` | `false` | Generate `code_health.html` — a self-contained page with an SVG score gauge. |
-| `--delete` | `false` | After analysis, prompt to permanently delete dead files. |
-| `--ci` | `false` | Non-interactive mode. Exits `1` if any issues are found. |
+| `--delete` | `false` | Prompt to permanently delete dead **code files** (safe to delete + transitively dead — not dead exports). See **Delete commands & cached reports** below. |
+| `--delete-assets` | `false` | Prompt to delete unused files under `public/` from the asset report. Only paths inside `public/` are removed. See **Delete commands & cached reports** below. |
+| `--ci` | `false` | Non-interactive mode. Exits `1` if any issues are found. With `--delete` / `--delete-assets`, does not prompt and does **not** delete files. |
 | `-v, --version` | — | Print the installed version. |
 
+### Delete commands & cached reports
+
+When you use **`--delete`** or **`--delete-assets`**, prunify prefers your last report so you do not have to re-scan the whole repo every time:
+
+| Flag | If the report already exists | If the report is missing |
+|------|------------------------------|---------------------------|
+| **`--delete`** | Reads file paths from `prunify-reports/dead-code.txt` (skips dead-code analysis and may skip building the import graph when no other module needs it). | Runs dead-code analysis, writes `dead-code.txt`, then prompts to delete. |
+| **`--delete-assets`** | Reads paths from `prunify-reports/assets.md` (skips the asset scan). | Runs the asset scan, writes `assets.md`, then prompts to delete. |
+
+- **`dead-code.txt`** starts with a line like `prunify <version> — <ISO timestamp>` so you know which run produced it.
+- Keep your dependency on prunify up to date (e.g. `"prunify": "^0.1.5"` in `devDependencies`) so you get the latest detection logic; pinning an old exact version will not pick up fixes from npm.
+
 ### More examples
 
 ```bash
@@ -131,9 +151,18 @@ npx prunify --only health --html
 # Only check unused public assets
 npx prunify --only assets
 
-# Delete dead files after reviewing
+# First run: analyse + write reports, then prompt to delete dead code files
 npx prunify --delete
 
+# Later: delete from existing dead-code.txt only (no graph build if e.g. --only deps)
+npx prunify --only deps --delete
+
+# Unused public assets: scan + prompt to delete
+npx prunify --only assets --delete-assets
+
+# Reuse assets.md only (no asset scan)
+npx prunify --delete-assets
+
 # Strict CI gate — fails the build if any issues exist
 npx prunify --ci
 ```
@@ -146,11 +175,11 @@ All reports are written to `prunify-reports/` (auto-added to `.gitignore`).
 
 | File | Contents |
 |------|----------|
-| `dead-code.txt` | Dead files and exports with chain analysis and recoverable byte count |
+| `dead-code.txt` | Header with tool version + time, then **Safe to delete**, **Transitively dead**, and **Dead exports** sections (sizes and optional chains). Used by `--delete` when re-running deletes. |
 | `dupes.md` | Duplicate function clusters with AI-ready refactor prompts |
-| `circular.txt` | Circular dependency chains |
+| `circular.txt` | Circular dependency chains (relative paths; header with tool version + time) |
 | `deps.md` | Unused packages |
-| `assets.md` | Unused files found in `public/` with sizes |
+| `assets.md` | Unused files found in `public/` with sizes (Markdown table). Used by `--delete-assets` when re-running deletes. |
 | `health-report.md` | Combined report with health score (with `--only health`) |
 | `code_health.html` | Self-contained HTML page with SVG score gauge (with `--html`) |
 
@@ -158,16 +187,15 @@ All reports are written to `prunify-reports/` (auto-added to `.gitignore`).
 
 ## How Dead Code Detection Works
 
-prunify builds a directed import graph of your entire codebase, then runs a depth-first traversal starting from your entry points.
+prunify builds a directed import graph (with `tsconfig.json` path aliases) and a **reverse** map of “who imports this file”.
 
-**Entry point auto-detection order:**
+1. **Safe to delete** — No other project file imports this file, and it is not treated as an app entry (e.g. Next.js `pages/` / `app/` routes) or a known framework/config file (`next.config.*`, `middleware.*`, `tailwind.config.*`, etc.).
+2. **Transitively dead** — The file is only imported by files that are already dead; removing the safe-to-delete roots would leave it orphaned.
+3. **Dead exports** — The file is still used, but specific named exports are never imported by name elsewhere (namespace imports count as “all exports used”). Files under **`pages/`** / **`src/pages/`**, route trees like **`src/routes/`**, **`src/views/`**, **`src/screens/`**, and Next.js App Router entry files (**`page.tsx`**, **`layout.tsx`**, **`route.ts`**, etc. under **`app/`** / **`src/app/`**) are **excluded** — the framework consumes those exports without normal `import` edges.
 
-1. Next.js — all files inside `pages/` and `app/` directories
-2. `package.json` `"main"` and `"module"` fields
-3. Common fallbacks — `src/main`, `src/index`, `src/App`, `index` (all TS/JS extensions)
-4. If none found — files with no importers are used as roots (safest heuristic)
+**Why not “reachable from entry” only?** A pure reachability scan from entry points can mark heavily shared modules as dead if any link in the chain fails to resolve. The importer-based model matches the usual meaning of “nothing uses this file.”
 
-Any file not reachable from an entry point is flagged as dead. Circular dependencies are handled correctly — files in a cycle that are reachable from an entry point are always marked live.
+**Circular imports** are reported separately in `circular.txt`; they are not lumped into “safe to delete.”
 
 ---
 
@@ -218,7 +246,8 @@ src/
 ├── cli.ts                  # Entry point & CLI flag handling
 ├── core/
 │   ├── parser.ts           # File discovery + ts-morph AST parsing
-│   ├── graph.ts            # Import graph builder, DFS traversal, cycle detection
+│   ├── graph.ts            # Import graph builder, cycle detection, reverse graph
+│   ├── report-parser.ts    # Parse dead-code.txt / assets.md for --delete / --delete-assets
 │   └── reporter.ts         # Markdown / JSON / HTML output writer
 ├── modules/
 │   ├── dead-code.ts        # Dead file + dead export detection