codebrief 1.1.0 → 1.2.0

package/dist/index.js

@@ -79,6 +79,7 @@ var init_utils = __esm({
 });
 
 // src/index.ts
+init_utils();
 import path8 from "path";
 import * as p4 from "@clack/prompts";
 import pc3 from "picocolors";
@@ -305,7 +306,10 @@ async function detectContext(rootDir, onProgress) {
           "**/vendor/**",
           "**/__pycache__/**",
           "**/venv/**",
-          "**/.venv/**"
+          "**/.venv/**",
+          "**/.Trash/**",
+          "**/Library/**",
+          "**/.git/**"
         ],
         stats: true
       }
@@ -859,21 +863,34 @@ function computePageRank(files, edges, iterations = 5, damping = 0.85) {
 }
 async function buildImportGraph(rootDir, language, onProgress) {
   const globs = getSourceGlob(language);
-  const files = await fg2(globs, {
-    cwd: rootDir,
-    ignore: [
-      "**/node_modules/**",
-      "**/dist/**",
-      "**/build/**",
-      "**/.next/**",
-      "**/target/**",
-      "**/vendor/**",
-      "**/__pycache__/**",
-      "**/venv/**",
-      "**/.venv/**"
-    ],
-    absolute: false
-  });
+  let files;
+  try {
+    files = await fg2(globs, {
+      cwd: rootDir,
+      ignore: [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/.next/**",
+        "**/target/**",
+        "**/vendor/**",
+        "**/__pycache__/**",
+        "**/venv/**",
+        "**/.venv/**",
+        "**/.Trash/**",
+        "**/Library/**",
+        "**/.git/**"
+      ],
+      absolute: false
+    });
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM" || code === "EACCES") {
+      onProgress?.("Warning: permission error scanning files \u2014 returning empty graph");
+      return { edges: [], inDegree: /* @__PURE__ */ new Map(), centrality: /* @__PURE__ */ new Map(), externalImportCounts: /* @__PURE__ */ new Map() };
+    }
+    throw err;
+  }
   onProgress?.(`Found ${files.length} source files to analyze`);
   const fileSet = new Set(files);
   const edges = [];
@@ -1401,7 +1418,10 @@ async function generateSnapshot(ctx, customPaths, graph, maxTokens, onProgress,
       "**/build/**",
       "**/*.test.*",
       "**/*.spec.*",
-      "**/__tests__/**"
+      "**/__tests__/**",
+      "**/.Trash/**",
+      "**/Library/**",
+      "**/.git/**"
     ],
     absolute: false
   });
@@ -2963,47 +2983,21 @@ function printSummary(files, ctx, snapshot, analysis) {
   const savings = Math.round(
     (explorationTokens - afterTotal) / explorationTokens * 100
   );
-  const costRows = [
-    { label: "Always loaded", desc: "main context + global rule", value: `~${formatNumber(alwaysOnTokens)} tokens` }
-  ];
-  if (avgScopedTokens > 0) {
-    costRows.push({ label: "Per-task (avg)", desc: "1 scoped rule", value: `~${formatNumber(avgScopedTokens)} tokens` });
-  }
-  costRows.push({ label: "Exploration", desc: "mostly eliminated", value: `~${formatNumber(residualExploration)} tokens` });
-  const maxCostLabel = Math.max(...costRows.map((r) => r.label.length));
-  const maxCostDesc = Math.max(...costRows.map((r) => r.desc.length));
-  const maxCostValue = Math.max(...costRows.map((r) => r.value.length));
-  const afterContentWidth = maxCostLabel + 3 + maxCostDesc + 2 + maxCostValue;
-  const beforeValue = `~${formatNumber(explorationTokens)} tokens`;
-  const beforeLabel = "Exploration to understand codebase";
-  const beforeGap = afterContentWidth - beforeLabel.length - beforeValue.length;
-  console.log(pc.dim("    Before (no context files):"));
-  if (beforeGap >= 2) {
-    console.log(
-      `      ${beforeLabel}${" ".repeat(beforeGap)}${pc.red(beforeValue)}`
-    );
-  } else {
-    console.log(
-      `      ${beforeLabel}  ${pc.red(beforeValue)}`
-    );
-  }
-  console.log("");
-  console.log(pc.dim("    After:"));
-  for (const row of costRows) {
-    console.log(
-      `      ${row.label.padEnd(maxCostLabel)}   ${row.desc.padEnd(maxCostDesc)}  ${pc.green(row.value.padStart(maxCostValue))}`
-    );
-  }
-  const totalText = `Total: ~${formatNumber(afterTotal)} tokens`;
-  const totalPad = afterContentWidth > totalText.length ? " ".repeat(afterContentWidth - totalText.length) : "";
-  console.log(
-    `      ${totalPad}${pc.bold(totalText)}`
-  );
+  const BAR_MAX = 40;
+  const maxVal = Math.max(explorationTokens, afterTotal);
+  const beforeBarLen = Math.max(1, Math.round(explorationTokens / maxVal * BAR_MAX));
+  const afterBarLen = Math.max(1, Math.round(afterTotal / maxVal * BAR_MAX));
+  const BLOCK = "\u2588";
+  const beforeBar = BLOCK.repeat(beforeBarLen);
+  const afterBar = BLOCK.repeat(afterBarLen);
+  const afterPad = " ".repeat(Math.max(0, beforeBarLen - afterBarLen));
+  console.log(`    Before: ${pc.red(beforeBar)}  ~${formatNumber(explorationTokens)} tokens`);
+  console.log(`    After:  ${pc.green(afterBar)}${afterPad}  ~${formatNumber(afterTotal)} tokens`);
   console.log("");
   if (savings > 0) {
     console.log(
       pc.green(
-        `    Estimated savings: ~${savings}% fewer tokens before real work begins`
+        `    Estimated savings: ~${savings}% fewer tokens`
       )
     );
   }
@@ -3047,20 +3041,39 @@ function printSummary(files, ctx, snapshot, analysis) {
       );
     }
   }
-  const exportCoverage = analysis?.exportCoverage;
-  if (exportCoverage && exportCoverage.length > 0) {
-    const totalExports = exportCoverage.reduce((sum, e) => sum + e.totalExports, 0);
-    const totalUsed = exportCoverage.reduce((sum, e) => sum + e.usedExports, 0);
-    const unusedExports = totalExports - totalUsed;
-    const coveragePct = totalExports > 0 ? Math.round(totalUsed / totalExports * 100) : 100;
-    const filesWithUnused = exportCoverage.filter((e) => e.usedExports < e.totalExports).length;
-    if (unusedExports > 0) {
-      console.log("");
-      console.log(
-        pc.dim(
-          `    Export coverage: ${coveragePct}% of exports are used (${unusedExports} unused exports in ${filesWithUnused} file${filesWithUnused === 1 ? "" : "s"})`
-        )
-      );
+  if (analysis) {
+    const findings = [];
+    if (analysis.circularDeps.length > 0) {
+      for (const c of analysis.circularDeps.slice(0, 3)) {
+        const names = c.chain.map((f) => f.split("/").pop()?.replace(/\.[jt]sx?$/, "") ?? f);
+        findings.push(`${analysis.circularDeps.length > 1 ? "" : ""}1 circular dependency chain (${names.slice(0, 2).join(" \u2194 ")})`);
+      }
+      if (analysis.circularDeps.length > 1) {
+        findings[0] = `${analysis.circularDeps.length} circular dependency chain${analysis.circularDeps.length === 1 ? "" : "s"}`;
+      }
+    }
+    const highInstabilityFiles = analysis.instabilities.filter((f) => f.instability > 0.8);
+    if (highInstabilityFiles.length > 0) {
+      findings.push(`${highInstabilityFiles.length} high-instability file${highInstabilityFiles.length === 1 ? "" : "s"}`);
+    }
+    const ec = analysis.exportCoverage;
+    if (ec && ec.length > 0) {
+      const totalExports = ec.reduce((sum, e) => sum + e.totalExports, 0);
+      const totalUsed = ec.reduce((sum, e) => sum + e.usedExports, 0);
+      const unusedExports = totalExports - totalUsed;
+      const filesWithUnused = ec.filter((e) => e.usedExports < e.totalExports).length;
+      if (unusedExports > 0) {
+        findings.push(`${unusedExports} unused export${unusedExports === 1 ? "" : "s"} in ${filesWithUnused} file${filesWithUnused === 1 ? "" : "s"}`);
+      }
+    }
+    console.log("");
+    if (findings.length > 0) {
+      console.log(pc.yellow(`  \u26A0  ${findings.length} finding${findings.length === 1 ? "" : "s"}`));
+      for (const f of findings) {
+        console.log(pc.dim(`     \u25CF ${f}`));
+      }
+    } else {
+      console.log(pc.green(`  \u2713  No structural issues detected`));
     }
   }
   console.log("");
@@ -3395,6 +3408,19 @@ async function main() {
   const maxTokens = maxTokensArg ? parseInt(maxTokensArg.split("=")[1], 10) : void 0;
   const targetDir = args.find((a) => !a.startsWith("-") && a !== "-v") ?? process.cwd();
   const rootDir = path8.resolve(targetDir);
+  const PROJECT_MARKERS = ["package.json", "go.mod", "Cargo.toml", "pyproject.toml", "requirements.txt"];
+  const hasProjectMarker = (await Promise.all(
+    PROJECT_MARKERS.map((f) => fileExists(path8.join(rootDir, f)))
+  )).some(Boolean);
+  if (!hasProjectMarker) {
+    console.log("");
+    p4.intro(pc3.bold(" codebrief "));
+    p4.log.error(`No project found at ${pc3.cyan(rootDir)}`);
+    p4.log.info(`Run ${pc3.bold("npx codebrief")} from a project directory, or pass a path:
+  ${pc3.dim("npx codebrief ./my-project")}`);
+    p4.outro("");
+    process.exit(1);
+  }
   const verboseLog = (msg) => {
     if (verbose) p4.log.info(pc3.dim(msg));
   };
@@ -3471,35 +3497,111 @@ async function main() {
   const fileCount = graph.centrality.size;
   spinner3.start(`Running PageRank on ${fileCount} files...`);
   const hubFiles = getHubFiles(graph);
-  verboseLog(`PageRank: found ${hubFiles.length} hub files`);
-  spinner3.message("Finding circular dependencies...");
+  const topHubName = hubFiles[0]?.path ?? "";
+  spinner3.stop(
+    hubFiles.length > 0 ? `${pc3.green("PageRank")}       found ${pc3.bold(String(hubFiles.length))} hub files` + (topHubName ? pc3.dim(` (top: ${topHubName})`) : "") : `${pc3.green("PageRank")}       ${pc3.dim("no hub files detected")}`
+  );
+  if (verbose && hubFiles.length > 0) {
+    for (const h of hubFiles.slice(0, 5)) {
+      p4.log.info(pc3.dim(`  ${h.path} (centrality: ${h.centrality.toFixed(3)}, imported by ${h.importedBy})`));
+    }
+  }
+  spinner3.start("Finding circular dependencies...");
   const circularDeps = findCircularDeps(graph);
-  verboseLog(`Tarjan SCC: ${circularDeps.length === 0 ? "no cycles found" : `${circularDeps.length} cycle(s)`}`);
-  spinner3.message("Detecting architecture layers...");
+  spinner3.stop(
+    circularDeps.length === 0 ? `${pc3.green("Tarjan SCC")}     no cycles found ${pc3.green("\u2713")}` : `${pc3.yellow("Tarjan SCC")}     ${pc3.bold(String(circularDeps.length))} cycle${circularDeps.length === 1 ? "" : "s"} found`
+  );
+  if (verbose && circularDeps.length > 0) {
+    for (const c of circularDeps.slice(0, 3)) {
+      p4.log.info(pc3.dim(`  ${c.chain.join(" \u2192 ")}`));
+    }
+  }
+  spinner3.start("Detecting architecture layers...");
   const { layers, layerEdges } = detectArchitecturalLayers(graph);
-  verboseLog(`Layers: ${layers.map((l) => l.name).join(", ") || "none detected"}`);
-  spinner3.message("Computing instability metrics...");
+  spinner3.stop(
+    layers.length > 0 ? `${pc3.green("Layers")}         ${layers.map((l) => l.name).join(" \u2192 ")}` : `${pc3.green("Layers")}         ${pc3.dim("no clear layers detected")}`
+  );
+  if (verbose && layers.length > 0) {
+    for (const l of layers) {
+      p4.log.info(pc3.dim(`  ${l.name}: ${l.files.length} files, depends on: ${l.dependsOn.join(", ") || "none"}`));
+    }
+  }
+  spinner3.start("Computing instability metrics...");
   const instabilities = computeInstability(graph);
-  verboseLog(`Instability: ${instabilities.length} high-risk file(s)`);
-  spinner3.message("Detecting module communities...");
+  const highInstability = instabilities.filter((f) => f.instability > 0.8);
+  spinner3.stop(
+    highInstability.length > 0 ? `${pc3.yellow("Instability")}    ${pc3.bold(String(highInstability.length))} high-risk file${highInstability.length === 1 ? "" : "s"}` : `${pc3.green("Instability")}    ${pc3.dim("all files within healthy range")} ${pc3.green("\u2713")}`
+  );
+  if (verbose && highInstability.length > 0) {
+    for (const f of highInstability.slice(0, 5)) {
+      p4.log.info(pc3.dim(`  ${f.path} (I=${f.instability.toFixed(2)}, fan-in=${f.fanIn}, fan-out=${f.fanOut})`));
+    }
+  }
+  spinner3.start("Detecting module communities...");
   const communities = detectCommunities(graph);
-  verboseLog(`Communities: ${communities.length} cluster(s)`);
-  spinner3.message("Computing export coverage...");
+  spinner3.stop(
+    communities.length > 0 ? `${pc3.green("Communities")}    ${pc3.bold(String(communities.length))} module cluster${communities.length === 1 ? "" : "s"}` : `${pc3.green("Communities")}    ${pc3.dim("single cohesive module")}`
+  );
+  if (verbose && communities.length > 0) {
+    for (const c of communities.slice(0, 5)) {
+      p4.log.info(pc3.dim(`  ${c.label} (${c.files.length} files)`));
+    }
+  }
+  spinner3.start("Computing export coverage...");
   const exportCoverage = computeExportCoverage(graph);
-  verboseLog(`Export coverage: ${exportCoverage.length} files analyzed`);
-  spinner3.message("Analyzing git history...");
+  {
+    const totalExp = exportCoverage.reduce((s, e) => s + e.totalExports, 0);
+    const totalUsed = exportCoverage.reduce((s, e) => s + e.usedExports, 0);
+    const unusedCount = totalExp - totalUsed;
+    const filesWithUnused = exportCoverage.filter((e) => e.usedExports < e.totalExports).length;
+    spinner3.stop(
+      unusedCount > 0 ? `${pc3.yellow("Exports")}        ${pc3.bold(String(unusedCount))} unused export${unusedCount === 1 ? "" : "s"} in ${filesWithUnused} file${filesWithUnused === 1 ? "" : "s"}` : `${pc3.green("Exports")}        ${pc3.dim("all exports used")} ${pc3.green("\u2713")}`
+    );
+    if (verbose && unusedCount > 0) {
+      for (const e of exportCoverage.filter((e2) => e2.usedExports < e2.totalExports).slice(0, 5)) {
+        p4.log.info(pc3.dim(`  ${e.file}: ${e.totalExports - e.usedExports} unused of ${e.totalExports}`));
+      }
+    }
+  }
+  spinner3.start("Analyzing git history...");
   const gitActivity = detected.isGitRepo ? analyzeGitActivity(rootDir, verbose ? verboseLog : spinnerProgress) : null;
-  if (gitActivity) verboseLog(`Git: ${gitActivity.hotFiles.length} active files, ${gitActivity.changeCoupling.length} coupled pairs`);
+  if (gitActivity) {
+    const coupledPairs = gitActivity.changeCoupling.length;
+    spinner3.stop(
+      `${pc3.green("Git (90d)")}      ${pc3.bold(String(gitActivity.hotFiles.length))} active file${gitActivity.hotFiles.length === 1 ? "" : "s"}, ${pc3.bold(String(coupledPairs))} coupled pair${coupledPairs === 1 ? "" : "s"}`
+    );
+    if (verbose) {
+      for (const h of gitActivity.hotFiles.slice(0, 5)) {
+        p4.log.info(pc3.dim(`  ${h.path} (${h.commits} commits, last: ${h.lastChanged})`));
+      }
+    }
+  } else {
+    spinner3.stop(`${pc3.green("Git")}            ${pc3.dim("not a git repo \u2014 skipped")}`);
+  }
   const analysis = { hubFiles, circularDeps, layers, layerEdges, gitActivity, instabilities, communities, exportCoverage };
-  const analysisParts = [];
-  if (hubFiles.length > 0) analysisParts.push(`${hubFiles.length} hub files`);
-  if (layers.length > 0) analysisParts.push(`${layers.length} layers`);
-  if (circularDeps.length > 0) analysisParts.push(`${circularDeps.length} circular dep${circularDeps.length === 1 ? "" : "s"}`);
-  if (communities.length > 0) analysisParts.push(`${communities.length} module cluster${communities.length === 1 ? "" : "s"}`);
-  if (gitActivity) analysisParts.push(`${gitActivity.hotFiles.length} active files`);
-  spinner3.stop(
-    analysisParts.length > 0 ? `Analysis: ${analysisParts.join(", ")}.` : "Analysis complete."
-  );
+  {
+    const reportLines = [];
+    reportLines.push(`  Files analyzed:  ${fileCount}`);
+    reportLines.push(`  Import edges:    ${graph.edges.length}`);
+    reportLines.push(`  External pkgs:   ${graph.externalImportCounts.size}`);
+    if (hubFiles.length > 0) {
+      reportLines.push(`  Hub files:       ${hubFiles.length}` + (hubFiles[0] ? ` (most connected: ${hubFiles[0].path})` : ""));
+    }
+    if (layers.length > 0) {
+      reportLines.push(`  Architecture:    ${layers.map((l) => l.name).join(" \u2192 ")}`);
+    }
+    reportLines.push(`  Circular deps:   ${circularDeps.length === 0 ? "none" : `${circularDeps.length} chain${circularDeps.length === 1 ? "" : "s"}`}`);
+    if (gitActivity) {
+      reportLines.push(`  Hot files (90d): ${gitActivity.hotFiles.length}`);
+    }
+    p4.note(reportLines.join("\n"), "Analysis Report");
+    if (circularDeps.length > 0) {
+      for (const c of circularDeps.slice(0, 2)) {
+        const shortChain = c.chain.map((f) => f.split("/").pop() ?? f);
+        p4.log.warn(pc3.yellow(`Cycle: ${shortChain.join(" \u2192 ")}`));
+      }
+    }
+  }
   const savedConfig = await loadConfig(rootDir);
   if (savedConfig?.snapshotHash) {
     const currentHash = await computeSnapshotHash(rootDir, detected.language);