prunify 0.1.7 → 0.1.8

package/README.md

@@ -175,6 +175,7 @@ All reports are written to `prunify-reports/` (auto-added to `.gitignore`).
 
 | File | Contents |
 |------|----------|
+| `ai_prompt.tsx` | **Agent handoff:** exports `PRUNIFY_CLEANUP_AGENT_PROMPT` — paste into Cursor/Copilot with the other reports attached; includes safety rules and cleanup order. Regenerated every run. |
 | `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 (relative paths; header with tool version + time) |

package/dist/cli.cjs

@@ -512,6 +512,12 @@ ${entry}
 `, "utf-8");
   }
 }
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
 function writeMarkdown(report, outputPath) {
   const lines = [
     `# ${report.title}`,
@@ -679,62 +685,136 @@ function getFileSize(filePath) {
     return 0;
   }
 }
+var RULE = "\u2500".repeat(78);
+var RULE2 = "\u2550".repeat(78);
 function buildDeadCodeReport(safeToDelete, transitivelyDead, chains, deadExports, rootDir) {
   const rel = (p) => import_node_path5.default.relative(rootDir, p).replaceAll("\\", "/");
-  const allDeadFiles = [...safeToDelete, ...transitivelyDead];
-  const totalBytes = allDeadFiles.reduce((sum, f) => sum + getFileSize(f), 0);
-  const totalKb = (totalBytes / 1024).toFixed(1);
+  const sortPaths = (paths) => [...paths].sort((a, b) => rel(a).localeCompare(rel(b), "en"));
+  const safeSorted = sortPaths(safeToDelete);
+  const transSorted = sortPaths(transitivelyDead);
+  const safeBytes = safeSorted.reduce((s, f) => s + getFileSize(f), 0);
+  const transBytes = transSorted.reduce((s, f) => s + getFileSize(f), 0);
+  const fileDeleteBytes = safeBytes + transBytes;
+  const totalKb = (fileDeleteBytes / 1024).toFixed(1);
+  const deadExportFiles = new Set(deadExports.map((e) => e.filePath));
+  const deadExportFileBytes = [...deadExportFiles].reduce((s, f) => s + getFileSize(f), 0);
   const lines = [
-    "========================================",
+    RULE2,
     "  DEAD CODE REPORT",
+    RULE2,
     `  Safe to delete     : ${safeToDelete.length}`,
     `  Transitively dead  : ${transitivelyDead.length}`,
     `  Dead exports       : ${deadExports.length}`,
-    `  Recoverable        : ~${totalKb} KB`,
-    "========================================",
+    `  Recoverable (files): ~${totalKb} KB  (${formatBytes(fileDeleteBytes)})`,
+    RULE2,
+    "",
+    "  HOW TO READ THIS",
+    "",
+    "  1. SAFE TO DELETE \u2014 No other source file imports these. You can delete them",
+    "     first (after review).",
+    "  2. TRANSITIVELY DEAD \u2014 Only referenced by files that are already dead. After",
+    "     removing safe-to-delete files, these become removable too.",
+    "  3. DEAD EXPORTS \u2014 The file is still used, but the listed export is never",
+    "     imported by name. Remove the export (or use it) to tidy the API.",
+    "     Framework routes (pages/, app/, etc.) are not listed here.",
+    "",
+    RULE,
     ""
   ];
-  if (safeToDelete.length > 0) {
+  if (safeSorted.length > 0) {
     lines.push(
       "\u2500\u2500 SAFE TO DELETE \u2500\u2500",
-      "(These files are not imported by any other file in the codebase)",
+      "",
+      "  Nothing in the project imports these paths. Review, then delete.",
       ""
     );
-    for (const filePath of safeToDelete) {
+    for (const filePath of safeSorted) {
       const chain = chains.get(filePath) ?? [];
-      const sizeKb = (getFileSize(filePath) / 1024).toFixed(1);
-      lines.push(`  ${rel(filePath)}  (~${sizeKb} KB)`);
+      const kb = (getFileSize(filePath) / 1024).toFixed(1);
+      lines.push(`  \u2022 ${rel(filePath)}  (~${kb} KB)`);
       if (chain.length > 0) {
-        lines.push(`    \u2514\u2500 also makes dead: ${chain.map(rel).join(", ")}`);
+        lines.push(
+          `      \u21B3 Also becomes orphaned if you delete the line above:`,
+          `        ${chain.map(rel).join(", ")}`
+        );
       }
     }
-    lines.push("");
+    lines.push(
+      "",
+      `  SUBTOTAL \u2014 ${safeSorted.length} file(s) \xB7 ${formatBytes(safeBytes)}`,
+      "",
+      RULE,
+      ""
+    );
   }
-  if (transitivelyDead.length > 0) {
+  if (transSorted.length > 0) {
     lines.push(
       "\u2500\u2500 TRANSITIVELY DEAD \u2500\u2500",
-      "(These files are only imported by dead files \u2014 they become orphaned too)",
+      "",
+      "  Every importer of these files is already in the dead set above.",
       ""
     );
-    for (const filePath of transitivelyDead) {
-      const sizeKb = (getFileSize(filePath) / 1024).toFixed(1);
-      lines.push(`  ${rel(filePath)}  (~${sizeKb} KB)`);
+    for (const filePath of transSorted) {
+      const kb = (getFileSize(filePath) / 1024).toFixed(1);
+      lines.push(`  \u2022 ${rel(filePath)}  (~${kb} KB)`);
     }
-    lines.push("");
+    lines.push(
+      "",
+      `  SUBTOTAL \u2014 ${transSorted.length} file(s) \xB7 ${formatBytes(transBytes)}`,
+      "",
+      RULE,
+      ""
+    );
   }
   if (deadExports.length > 0) {
     lines.push(
       "\u2500\u2500 DEAD EXPORTS \u2500\u2500",
-      "(Exported but never imported by any other file; pages/routes omitted)",
+      "",
+      "  Symbol is exported but never imported by name elsewhere (namespace imports",
+      "  count as \u201Call used\u201D). Route and framework files are excluded.",
       ""
     );
-    for (const entry of deadExports) {
-      lines.push(
-        `  ${rel(entry.filePath)} \u2192 ${entry.exportName} [line ${entry.line}]`
-      );
+    const byFile = /* @__PURE__ */ new Map();
+    for (const e of deadExports) {
+      if (!byFile.has(e.filePath)) byFile.set(e.filePath, []);
+      byFile.get(e.filePath).push(e);
+    }
+    const fileKeys = [...byFile.keys()].sort((a, b) => rel(a).localeCompare(rel(b), "en"));
+    for (const fp of fileKeys) {
+      lines.push(`  ${rel(fp)}`);
+      for (const entry of byFile.get(fp)) {
+        lines.push(`      \u2022 export \u201C${entry.exportName}\u201D  (line ${entry.line})`);
+      }
+      lines.push("");
     }
-    lines.push("");
+    lines.push(
+      `  SUBTOTAL \u2014 ${deadExports.length} export(s) across ${deadExportFiles.size} file(s)`,
+      "",
+      RULE,
+      ""
+    );
   }
+  lines.push(
+    RULE2,
+    "  END OF REPORT \u2014 DISK SPACE & CLEANUP SUMMARY",
+    RULE2,
+    "",
+    "  If you DELETE every file under \u201CSafe to delete\u201D and \u201CTransitively dead\u201D:",
+    "",
+    `      Files removed : ${safeSorted.length + transSorted.length}`,
+    `      Disk freed    : ${formatBytes(fileDeleteBytes)}  (approx., from file sizes on disk)`,
+    "",
+    "  Dead exports do not remove whole files by themselves. Cleaning them saves",
+    `  maintainability first; the ${deadExportFiles.size} file(s) that contain them`,
+    `  total about ${formatBytes(deadExportFileBytes)} on disk (entire files, not`,
+    "  \u201Cexport-only\u201D savings).",
+    "",
+    "  Suggested order: (1) Delete safe-to-delete files \u2192 (2) Delete transitively",
+    "  dead files \u2192 (3) Remove or use dead exports in remaining files.",
+    "",
+    RULE2,
+    ""
+  );
   return lines.join("\n");
 }
 async function runDeadCode(dir, opts) {
@@ -1284,22 +1364,38 @@ async function runAssetCheck(rootDir, opts) {
       writeMarkdown(
         {
           title: "Unused Assets Report",
-          summary: `${result.unusedAssets.length} unused asset(s) found in public/`,
+          summary: `${result.unusedAssets.length} unused \xB7 ${formatBytes(result.unusedAssets.reduce((s, a) => s + a.sizeBytes, 0))} recoverable \u2014 see companion .txt for full detail`,
           sections: [
             {
               title: "Unused Assets",
               headers: ["Asset", "Size (KB)"],
-              rows: result.unusedAssets.map((a) => [
-                a.relativePath,
-                (a.sizeBytes / 1024).toFixed(1)
-              ])
+              rows: result.unusedAssets.slice().sort((a, b) => a.relativePath.localeCompare(b.relativePath, "en")).map((a) => [a.relativePath, (a.sizeBytes / 1024).toFixed(1)])
+            },
+            {
+              title: "If you delete all listed files",
+              rows: [
+                [
+                  "Files removed",
+                  String(result.unusedAssets.length)
+                ],
+                [
+                  "Approx. disk freed",
+                  formatBytes(result.unusedAssets.reduce((s, a) => s + a.sizeBytes, 0))
+                ]
+              ]
             }
           ],
           generatedAt: /* @__PURE__ */ new Date()
         },
         opts.output
       );
-      console.log(import_chalk6.default.cyan(`  Report written to ${opts.output}`));
+      const txtPath = import_node_path8.default.join(
+        import_node_path8.default.dirname(opts.output),
+        `${import_node_path8.default.basename(opts.output, import_node_path8.default.extname(opts.output))}.txt`
+      );
+      import_node_fs8.default.writeFileSync(txtPath, result.report, "utf-8");
+      console.log(import_chalk6.default.cyan(`  Reports written \u2192 ${opts.output}`));
+      console.log(import_chalk6.default.cyan(`                  \u2192 ${txtPath}`));
     }
     return result.unusedAssets;
   } catch (err) {
@@ -1337,32 +1433,163 @@ function getFileSize2(filePath) {
 }
 function buildAssetReport(unused, totalAssets, rootDir) {
   const totalBytes = unused.reduce((s, a) => s + a.sizeBytes, 0);
-  const totalKb = (totalBytes / 1024).toFixed(1);
+  const usedCount = totalAssets - unused.length;
+  const pct = totalAssets > 0 ? (unused.length / totalAssets * 100).toFixed(1) : "0.0";
+  const RULE22 = "\u2550".repeat(78);
+  const RULE3 = "\u2500".repeat(78);
   const lines = [
-    "========================================",
-    "  UNUSED ASSETS REPORT",
-    `  Total assets   : ${totalAssets}`,
-    `  Unused assets  : ${unused.length}`,
-    `  Recoverable    : ~${totalKb} KB`,
-    "========================================",
+    RULE22,
+    "  UNUSED ASSETS REPORT  (public/)",
+    RULE22,
+    `  Total files scanned : ${totalAssets}`,
+    `  Referenced in code  : ${usedCount}`,
+    `  Unused (listed)     : ${unused.length}  (${pct}% of scanned)`,
+    `  Disk size (unused)  : ${formatBytes(totalBytes)}`,
+    RULE22,
+    "",
+    "  HOW TO READ THIS",
+    "",
+    "  Files below live under public/ but their filename or public URL path was not",
+    "  found in your source scan (TS, JS, CSS, HTML, JSON). They may still be used",
+    "  if loaded by URL from a CMS, CDN, or runtime string \u2014 verify before deleting.",
+    "",
+    RULE3,
     ""
   ];
   if (unused.length === 0) {
-    lines.push("  All public assets are referenced in source.", "");
-    return lines.join("\n");
-  }
-  lines.push("\u2500\u2500 UNUSED ASSETS \u2500\u2500", "");
-  for (const asset of unused) {
     lines.push(
-      `UNUSED \u2014 ${asset.relativePath}`,
-      `Size: ~${(asset.sizeBytes / 1024).toFixed(1)} KB`,
-      `Action: Safe to delete if not served directly via URL`,
+      "  No unused assets detected \u2014 everything scanned appears referenced.",
+      "",
+      RULE22,
+      "  END OF REPORT",
+      RULE22,
+      "",
+      "  If you removed nothing: disk savings = 0 (already optimal for this scan).",
+      "",
+      RULE22,
       ""
     );
+    return lines.join("\n");
+  }
+  const sorted = [...unused].sort(
+    (a, b) => a.relativePath.localeCompare(b.relativePath, "en")
+  );
+  lines.push("\u2500\u2500 UNUSED ASSET FILES \u2500\u2500", "", "  Sorted by path.", "");
+  for (const asset of sorted) {
+    const kb = (asset.sizeBytes / 1024).toFixed(1);
+    lines.push(`  \u2022 ${asset.relativePath}  (~${kb} KB)`);
+    lines.push(`      On disk: ${formatBytes(asset.sizeBytes)}`);
+    lines.push("");
   }
+  lines.push(
+    `  SUBTOTAL \u2014 ${sorted.length} file(s) \xB7 ${formatBytes(totalBytes)}`,
+    "",
+    RULE3,
+    "",
+    RULE22,
+    "  END OF REPORT \u2014 DISK SPACE SUMMARY",
+    RULE22,
+    "",
+    "  If you DELETE every unused asset listed above from public/:",
+    "",
+    `      Files removed : ${sorted.length}`,
+    `      Disk freed    : ${formatBytes(totalBytes)}  (sum of file sizes on disk)`,
+    "",
+    "  This does not include savings from dead code \u2014 see dead-code.txt for source files.",
+    "",
+    RULE22,
+    ""
+  );
   return lines.join("\n");
 }
 
+// src/core/agent-prompt.ts
+function buildPromptBody(meta) {
+  const { prunifyVersion, generatedAtIso, projectRootDisplay, reportsDirDisplay } = meta;
+  return `You are assisting with a **careful, incremental** cleanup of a TypeScript/JavaScript codebase.
+
+## Context (prunify ${prunifyVersion})
+
+- **Project root:** ${projectRootDisplay}
+- **Reports folder:** ${reportsDirDisplay}
+- **Report generated (this prompt file):** ${generatedAtIso}
+
+The user has run **prunify** (static analysis). The reports are hints, not ground truth. **False positives are common.**
+
+## Attach these files to the chat (if they exist)
+
+From \`${reportsDirDisplay}\`:
+
+| File | What it means |
+|------|----------------|
+| **dead-code.txt** | Orphan files (safe / transitive), dead exports, sizes. **--delete** uses this for whole-file removal. |
+| **circular.txt** | Import cycles \u2014 usually **refactor**, not delete. |
+| **dupes.md** | Repeated code **blocks** \u2014 merge only after **semantic** review. |
+| **deps.md** | package.json vs imports \u2014 **unused** / **missing** / dev issues. |
+| **assets.md** (+ **assets.txt**) | Unreferenced files under **public/** \u2014 **--delete-assets** uses the report. |
+
+If a file is missing, skip that section of work.
+
+---
+
+## Mandatory safety rules (do not skip)
+
+1. **No bulk deletes.** Work in small batches; one PR or one chat turn per logical change.
+2. **Dead code \u2014 files:** Only delete files listed under **Safe to delete** (or explicitly marked removable in dead-code.txt) **after** you grep/search for dynamic imports, \`require(variable)\`, string-based paths, Next.js \`app/\`/\`pages/\` conventions, and config references.
+3. **Dead code \u2014 exports:** Removing an export can break external consumers or barrels. After removal, run typecheck; fix barrel \`index.ts\` re-exports.
+4. **Barrel files (\`index.ts\`):** A file may be "used" only via \`export * from './X'\`. Do not delete leaf modules until importers and barrels are updated.
+5. **Transitively dead:** Deletion order matters \u2014 follow the report chains; remove importers before importers-only-used-by-dead-code where applicable.
+6. **Circular imports:** Prefer extracting shared code or inverting dependencies; **do not** "fix" by deleting arbitrary cycle members.
+7. **dupes.md:** Identical text \u2260 identical behavior (closures, imports, generics). **Merge duplicates only** when you can prove equivalence; prefer extracting a shared function with tests.
+8. **deps.md \u2014 unused:** prunify scans **src/** imports only. Packages may still be used in **root config**, **scripts**, **CSS**, **tests outside src**, **Next.js** files outside \`src/\`, or **CLI**. Confirm with repo-wide search before \`npm uninstall\`.
+9. **deps.md \u2014 missing:** May be transitive or tooling; verify before adding duplicates.
+10. **assets:** URLs may be built at runtime, come from CMS, or live in strings prunify does not see. Confirm with search before deleting from **public/**.
+
+---
+
+## Suggested order (lowest risk first)
+
+1. **Verify deps.md** \u2014 search the whole repo; adjust package.json only with evidence.
+2. **Dead exports** \u2014 remove unused exports / tidy barrels; typecheck after each batch.
+3. **Safe-to-delete files** \u2014 small batches; run build after.
+4. **Unused assets** \u2014 after string search in app and config.
+5. **dupes.md** \u2014 last; highest judgment; add tests when merging.
+
+---
+
+## After every batch
+
+- Run **lint** and **typecheck** (and **tests** if available).
+- Run **production build** before declaring done.
+- If something fails, **revert** that batch and narrow the change.
+
+---
+
+## What not to do
+
+- Do not delete **pages**, **app routes**, **middleware**, or framework entry files unless the user explicitly asks and you verified they are unused.
+- Do not remove packages because deps.md says "unused" without a repo-wide check.
+- Do not merge duplicate blocks from dupes.md without reading surrounding code.
+
+When uncertain, **list the risk** and ask the user to confirm before editing.`;
+}
+function buildAiPromptTsx(meta) {
+  const body = buildPromptBody(meta);
+  const literal = JSON.stringify(body);
+  return `/* eslint-disable */
+/**
+ * Auto-generated by prunify ${meta.prunifyVersion} \u2014 ${meta.generatedAtIso}
+ * Do not edit by hand; re-run \`npx prunify\` to refresh.
+ *
+ * **For Cursor / Copilot:** attach the files listed inside PRUNIFY_CLEANUP_AGENT_PROMPT
+ * (from prunify-reports/), then paste the prompt or use @-mention on those files plus this file.
+ */
+export const PRUNIFY_CLEANUP_AGENT_PROMPT = ${literal} as const
+
+export default PRUNIFY_CLEANUP_AGENT_PROMPT
+`;
+}
+
 // src/core/report-parser.ts
 var import_node_fs9 = __toESM(require("fs"), 1);
 var import_node_path9 = __toESM(require("path"), 1);
@@ -1384,7 +1611,7 @@ function parseDeadCodeReportContent(content, rootDir) {
     return [...new Set(paths)];
   }
   let section = "none";
-  const fileLineRe = /^\s{2}(.+?)\s+\(~[\d.]+\s+KB\)\s*$/;
+  const fileLineRe = /^\s*(?:•\s+)?(.+?)\s+\(~[\d.]+\s+KB\)\s*$/;
   for (const line of lines) {
     if (line.includes("\u2500\u2500 SAFE TO DELETE \u2500\u2500")) {
       section = "safe";
@@ -1405,7 +1632,9 @@ function parseDeadCodeReportContent(content, rootDir) {
       continue;
     }
     if (section === "safe" || section === "transitive") {
-      if (line.includes("\u2514\u2500") || line.includes("also makes dead")) continue;
+      if (line.includes("\u2514\u2500") || line.includes("\u21B3") || line.includes("also makes dead") || line.includes("SUBTOTAL") || line.includes("\u2500\u2500\u2500")) {
+        continue;
+      }
       const m = fileLineRe.exec(line);
       if (m) {
         const rel = m[1].trim();
@@ -1426,7 +1655,7 @@ function countDeadExportsInReport(content) {
       continue;
     }
     if (section && line.startsWith("\u2500\u2500 ") && line.includes("\u2500\u2500")) break;
-    if (section && /\s→\s.+\[line \d+\]/.test(line)) n++;
+    if (section && /\(line \d+\)/.test(line)) n++;
   }
   return n;
 }
@@ -1434,7 +1663,7 @@ function parseDeadCodeReportSummary(content) {
   const safe = content.match(/Safe to delete\s*:\s*(\d+)/);
   const trans = content.match(/Transitively dead\s*:\s*(\d+)/);
   const exp = content.match(/Dead exports\s*:\s*(\d+)/);
-  const rec = content.match(/Recoverable\s*:\s*(~[\d.]+\s*KB)/i);
+  const rec = content.match(/Recoverable[^:\n]*:\s*(~[\d.]+\s*KB)/i);
   if (!safe || !trans || !exp) return null;
   return {
     safeToDelete: Number(safe[1]),
@@ -1603,7 +1832,8 @@ async function main(opts) {
     }
   }
   if (loadAssetsFromCache) {
-    assetsReportFile = "assets.md";
+    const assetsTxtPath = import_node_path10.default.join(reportsDir, "assets.txt");
+    assetsReportFile = import_node_fs10.default.existsSync(assetsTxtPath) ? "assets.md, assets.txt" : "assets.md";
     unusedAssetCount = unusedAssetPaths.length;
   }
   if (runDeadCode2) {
@@ -1675,7 +1905,7 @@ async function main(opts) {
     const unusedAssets = await runAssetCheck(rootDir, { output: outputPath });
     unusedAssetPaths = unusedAssets.map((a) => a.filePath);
     unusedAssetCount = unusedAssets.length;
-    if (unusedAssetCount > 0) assetsReportFile = "assets.md";
+    if (unusedAssetCount > 0) assetsReportFile = "assets.md, assets.txt";
   }
   if (modules.includes("health")) {
     const outputPath = import_node_path10.default.join(reportsDir, "health-report.md");
@@ -1715,6 +1945,16 @@ async function main(opts) {
   );
   console.log(table.toString());
   console.log();
+  const aiPromptContent = buildAiPromptTsx({
+    prunifyVersion: PKG_VERSION,
+    generatedAtIso: (/* @__PURE__ */ new Date()).toISOString(),
+    projectRootDisplay: import_node_path10.default.relative(process.cwd(), rootDir) || ".",
+    reportsDirDisplay: import_node_path10.default.relative(rootDir, reportsDir).replaceAll("\\", "/") || "prunify-reports"
+  });
+  const aiPromptPath = import_node_path10.default.join(reportsDir, "ai_prompt.tsx");
+  import_node_fs10.default.writeFileSync(aiPromptPath, aiPromptContent, "utf-8");
+  console.log(import_chalk7.default.cyan(`  Agent prompt saved \u2192 ${aiPromptPath}`));
+  console.log();
   if (opts.delete && deadFilePaths.length > 0) {
     console.log(import_chalk7.default.yellow(`Dead code files to delete (${deadFilePaths.length}):`));
     for (const f of deadFilePaths) {