vibe-splain 2.3.0 → 2.4.0

package/dist/index.js

@@ -119,7 +119,80 @@ async function readAnalysis(projectRoot) {
 async function writeAnalysis(projectRoot, store) {
   const dir = join3(projectRoot, ".vibe-splainer");
   await mkdir2(dir, { recursive: true });
-  await writeFile3(join3(dir, "analysis.json"), JSON.stringify(store, null, 2), "utf8");
+  const dest = join3(dir, "analysis.json");
+  const tmp = dest + ".tmp";
+  await writeFile3(tmp, JSON.stringify(store, null, 2), "utf8");
+  const { rename } = await import("fs/promises");
+  await rename(tmp, dest);
+}
+var LOAD_BEARING_FAN_IN_THRESHOLD = 10;
+function deriveRiskTypes(f) {
+  const kinds = new Set(f.smells.map((s) => s.kind));
+  const types = [];
+  if (f.gravitySignals.cyclomatic > 15)
+    types.push("state_machine");
+  if (kinds.has("god-file"))
+    types.push("god_object");
+  if (f.gravitySignals.fanIn > 15)
+    types.push("deep_coupling");
+  if (kinds.has("swallowed-catch"))
+    types.push("error_sink");
+  if (f.gravitySignals.fanIn > 10 && f.gravitySignals.publicSurface > 8)
+    types.push("mutation_hotspot");
+  if (kinds.has("todo") && kinds.has("suppression"))
+    types.push("tech_debt");
+  return types.length > 0 ? types : ["complexity_hotspot"];
+}
+function deriveConfidence(f) {
+  if (f.gravitySignals.fanIn >= LOAD_BEARING_FAN_IN_THRESHOLD && f.gravity >= 40)
+    return "high";
+  if (f.gravitySignals.fanIn >= 5 || f.gravity >= 25)
+    return "medium";
+  return "low";
+}
+function findRuntimeEntrypoints(relPath, files, entrypoints) {
+  const found = [];
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [relPath];
+  while (queue.length > 0) {
+    const curr = queue.shift();
+    if (visited.has(curr))
+      continue;
+    visited.add(curr);
+    if (entrypoints.has(curr) && curr !== relPath)
+      found.push(curr);
+    if (found.length >= 5)
+      break;
+    const f = files[curr];
+    if (f) {
+      for (const importer of f.importedBy)
+        if (!visited.has(importer))
+          queue.push(importer);
+    }
+  }
+  return found;
+}
+async function writeDeltaTargets(projectRoot, store, entrypoints = /* @__PURE__ */ new Set()) {
+  const domain = (f) => f.pillarHint && !f.pillarHint.startsWith("community-") ? f.pillarHint : null;
+  const targets = Object.values(store.files).filter((f) => f.isRealSource).sort((a, b) => b.gravity - a.gravity).map((f) => ({
+    path: f.relativePath,
+    gravity: f.gravity,
+    isLoadBearing: f.gravitySignals.fanIn >= LOAD_BEARING_FAN_IN_THRESHOLD,
+    blastRadius: f.importedBy,
+    pillarHint: domain(f),
+    domain: domain(f),
+    riskTypes: deriveRiskTypes(f),
+    severity: f.smells.length > 0 ? Math.max(...f.smells.map((s) => s.severity)) : 0,
+    confidence: deriveConfidence(f),
+    runtimeEntrypoints: findRuntimeEntrypoints(f.relativePath, store.files, entrypoints)
+  }));
+  const dir = join3(projectRoot, ".vibe-splainer");
+  await mkdir2(dir, { recursive: true });
+  const dest = join3(dir, "delta_targets.json");
+  const tmp = dest + ".tmp";
+  await writeFile3(tmp, JSON.stringify(targets, null, 2), "utf8");
+  const { rename } = await import("fs/promises");
+  await rename(tmp, dest);
 }
 
 // ../brain/dist/scanner.js
@@ -234,7 +307,14 @@ var DEMOTE_SEGMENTS = /* @__PURE__ */ new Set([
   "fixtures",
   "fixture",
   "__generated__",
-  "__mocks__"
+  "__mocks__",
+  "playwright",
+  "e2e",
+  "__tests__",
+  "cypress",
+  "storybook",
+  "stories",
+  ".storybook"
 ]);
 var VENDOR_SEGMENTS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -1072,6 +1152,19 @@ async function detectStackAndEntrypoints(projectRoot, files) {
     if (base === "main.rs" || base === "lib.rs")
       entrypoints.add(r);
   }
+  if (stack.has("Next.js")) {
+    const appRouterNames = /* @__PURE__ */ new Set(["page", "layout", "route", "loading", "error", "not-found", "template", "default"]);
+    for (const abs of files) {
+      const r = rel(abs);
+      const stem = basename(r, extname(r));
+      const underApp = /(?:^|[/\\])app[/\\]/.test(r);
+      const underPages = /(?:^|[/\\])pages[/\\]/.test(r);
+      if (underApp && appRouterNames.has(stem))
+        entrypoints.add(r);
+      if (underPages && !stem.startsWith("_"))
+        entrypoints.add(r);
+    }
+  }
   return { stack: [...stack], entrypoints };
 }
 var SMELL_WEIGHT = {
@@ -1271,7 +1364,9 @@ async function scanProject(projectRoot) {
     brief: null
   };
   await writeGraph(projectRoot, graph);
-  await writeAnalysis(projectRoot, { files: persisted });
+  const analysisStore = { files: persisted };
+  await writeAnalysis(projectRoot, analysisStore);
+  await writeDeltaTargets(projectRoot, analysisStore, entrypoints);
   const uiUrl = `file://${join4(projectRoot, ".vibe-splainer", "ui", "index.html")}`;
   return {
     projectRoot,
@@ -1482,26 +1577,11 @@ async function writeDossier(projectRoot, dossier) {
       p.decisions = p.decisions.filter((c) => !(c.severity === 1 && c.category === "Convention"));
       p.cardCount = p.decisions.length;
     }
-    const uniqueCards = /* @__PURE__ */ new Map();
-    for (const p of dossier.pillars) {
-      for (const c of p.decisions)
-        uniqueCards.set(c.id, c);
-    }
-    for (const c of dossier.wildDiscoveries)
-      uniqueCards.set(c.id, c);
-    const deltaTargets = Array.from(uniqueCards.values()).filter((c) => c.severity >= 4).map((c) => ({
-      target_path: c.primaryFile,
-      bottleneck_title: c.title,
-      structural_intent: c.thesis,
-      evidence_snippets: c.evidence
-    }));
     const dir = join5(projectRoot, ".vibe-splainer");
     await mkdir3(dir, { recursive: true });
     const dossierPath = join5(dir, "dossier.json");
     const tmp = dossierPath + ".tmp";
     await writeFile4(tmp, JSON.stringify(dossier, null, 2), "utf8");
-    const targetsPath = join5(dir, "delta_targets.json");
-    await writeFile4(targetsPath, JSON.stringify(deltaTargets, null, 2), "utf8");
     const { rename } = await import("fs/promises");
     await rename(tmp, dossierPath);
     await regenerateUI(projectRoot, dossier);
@@ -1544,6 +1624,7 @@ function validateMermaidNodeCount(diagram) {
 import chokidar from "chokidar";
 import { createHash } from "crypto";
 import { readFile as readFile6 } from "fs/promises";
+import { join as join6 } from "path";
 function startWatcher(projectRoot, watchedPaths) {
   const watcher = chokidar.watch(watchedPaths.length > 0 ? watchedPaths : projectRoot, {
     ignoreInitial: true,
@@ -1560,13 +1641,15 @@ function startWatcher(projectRoot, watchedPaths) {
       let mutated = false;
       for (const pillar of dossier.pillars) {
         for (const card of pillar.decisions) {
-          if (card.evidence.some((e) => e.file === filepath || filepath.endsWith(e.file))) {
-            if (card.lastScannedHash !== newHash) {
-              card.status = "stale";
-              if (!dossier.stalePaths.includes(filepath))
-                dossier.stalePaths.push(filepath);
-              mutated = true;
-            }
+          if (!card.primaryFile)
+            continue;
+          const absMatch = filepath === join6(projectRoot, card.primaryFile) || filepath.endsWith("/" + card.primaryFile);
+          if (absMatch && card.lastScannedHash !== newHash) {
+            card.status = "stale";
+            const rel = card.primaryFile;
+            if (!dossier.stalePaths.includes(rel))
+              dossier.stalePaths.push(rel);
+            mutated = true;
           }
         }
       }
@@ -1716,7 +1799,7 @@ async function handleSetProjectBrief(args) {
 
 // dist/mcp/tools/get_file_context.js
 import { readFile as readFile7 } from "fs/promises";
-import { join as join6, relative as relative2, isAbsolute } from "path";
+import { join as join7, relative as relative2, isAbsolute } from "path";
 var getFileContextTool = {
   name: "get_file_context",
   description: "Returns PRE-EXTRACTED evidence for a file so you do not have to read the whole thing and paraphrase its header comment. Returns: gravity/heat scores + signals, importedBy (named fan-in \u2014 use this for blastRadius), hotSpans (the gnarliest function bodies, comment-stripped, each with a reason), smellSpans (located tech debt with \xB13 lines of context), and signature (the exported API surface). Base your evidence on hotSpans/smellSpans \u2014 NEVER on header comments. Pass { full: true } only if you truly need the raw source.",
@@ -1736,7 +1819,7 @@ async function handleGetFileContext(args) {
   const full = args.full === true;
   if (!projectRoot || !filePath)
     throw new Error("projectRoot and filePath are required");
-  const fullPath = isAbsolute(filePath) ? filePath : join6(projectRoot, filePath);
+  const fullPath = isAbsolute(filePath) ? filePath : join7(projectRoot, filePath);
   const relPath = relative2(projectRoot, fullPath);
   const evidence = await getFileAnalysis(fullPath);
   if (!evidence) {
@@ -1770,7 +1853,7 @@ async function handleGetFileContext(args) {
 import { v4 as uuidv4 } from "uuid";
 import { createHash as createHash2 } from "crypto";
 import { readFile as readFile8 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 var CATEGORIES = ["Bottleneck", "Hack", "Smart-Move", "Risk", "Convention", "Dead-Weight"];
 function normalizeSnippet(s) {
   let out = (s ?? "").replace(/\r\n/g, "\n");
@@ -1860,15 +1943,12 @@ async function handleWriteDecisionCard(args) {
   const persisted = store?.files[primaryFile];
   const gravity = persisted ? Math.round(persisted.gravity) : void 0;
   const heat = persisted ? Math.round(persisted.heat) : void 0;
-  let combinedContent = "";
-  for (const e of evidence) {
-    try {
-      combinedContent += await readFile8(join7(projectRoot, e.file), "utf8");
-    } catch {
-      combinedContent += e.snippet;
-    }
+  let primaryContent = "";
+  try {
+    primaryContent = await readFile8(join8(projectRoot, primaryFile), "utf8");
+  } catch {
   }
-  const hash = createHash2("sha256").update(combinedContent).digest("hex");
+  const hash = createHash2("sha256").update(primaryContent).digest("hex");
   const card = {
     id: uuidv4(),
     pillar,
@@ -2003,7 +2083,7 @@ async function handleInspectPillar(args) {
 // dist/mcp/tools/get_wild_discoveries.js
 var getWildDiscoveriesTool = {
   name: "get_wild_discoveries",
-  description: "Returns files with extremely high cognitive complexity (weight \u2265 25) that don't fit standard patterns. These are the most surprising and important parts of the codebase to understand.",
+  description: "Returns Decision Cards that are both high-heat (heat \u2265 60) AND/OR high-severity (severity \u2265 4) \u2014 the files that are load-bearing AND smelly. These are the highest-leverage things to understand and fix first.",
   inputSchema: {
     type: "object",
     properties: {
@@ -2234,7 +2314,7 @@ async function serveCommand() {
 
 // dist/index.js
 var program = new Command();
-program.name("vibe-splain").description("Architectural dossier engine for vibe-coded projects").version("1.0.0");
+program.name("vibe-splain").description("Architectural dossier engine for vibe-coded projects").version("2.3.1");
 program.command("install").description("Patch coding agent MCP config files to register vibe-splain").action(installCommand);
 program.command("serve").description("Start the MCP server (called by the coding agent, not by you)").action(serveCommand);
 program.parse();

package/dist/mcp/tools/get_wild_discoveries.js

@@ -1,7 +1,7 @@
 import { readDossier } from '@vibe-splain/brain';
 export const getWildDiscoveriesTool = {
     name: 'get_wild_discoveries',
-    description: 'Returns files with extremely high cognitive complexity (weight ≥ 25) that don\'t fit standard patterns. These are the most surprising and important parts of the codebase to understand.',
+    description: 'Returns Decision Cards that are both high-heat (heat ≥ 60) AND/OR high-severity (severity ≥ 4) — the files that are load-bearing AND smelly. These are the highest-leverage things to understand and fix first.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/mcp/tools/write_decision_card.js

@@ -99,17 +99,13 @@ export async function handleWriteDecisionCard(args) {
     const persisted = store?.files[primaryFile];
     const gravity = persisted ? Math.round(persisted.gravity) : undefined;
     const heat = persisted ? Math.round(persisted.heat) : undefined;
-    // Hash for staleness.
-    let combinedContent = '';
-    for (const e of evidence) {
-        try {
-            combinedContent += await readFile(join(projectRoot, e.file), 'utf8');
-        }
-        catch {
-            combinedContent += e.snippet;
-        }
+    // Hash the primaryFile so the watcher can detect staleness per-file.
+    let primaryContent = '';
+    try {
+        primaryContent = await readFile(join(projectRoot, primaryFile), 'utf8');
     }
-    const hash = createHash('sha256').update(combinedContent).digest('hex');
+    catch { /* */ }
+    const hash = createHash('sha256').update(primaryContent).digest('hex');
     const card = {
         id: uuidv4(),
         pillar, title, thesis, category, severity, narrative,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vibe-splain",
-  "version": "2.3.0",
-  "description": "Architectural dossier engine for vibe-coded projects. Runs as an MCP server inside your coding agent.",
+  "version": "2.4.0",
+  "description": "Architectural dossier engine for vibe-coded TypeScript/JavaScript projects. Runs as an MCP server inside your coding agent.",
   "type": "module",
   "license": "MIT",
   "author": "abp2204",
@@ -30,7 +30,7 @@
     "node": ">=18"
   },
   "bin": {
-    "vibe-splain": "./dist/index.js"
+    "vibe-splain": "dist/index.js"
   },
   "scripts": {
     "build": "tsc && node build.mjs"