vibe-splain 2.3.0 → 2.3.1

package/dist/index.js

@@ -119,7 +119,29 @@ 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;
+async function writeDeltaTargets(projectRoot, store) {
+  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,
+    // community-{N} labels are internal graph IDs — not useful to Delta Engine
+    pillarHint: f.pillarHint && !f.pillarHint.startsWith("community-") ? f.pillarHint : null
+  }));
+  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
@@ -1271,7 +1293,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);
   const uiUrl = `file://${join4(projectRoot, ".vibe-splainer", "ui", "index.html")}`;
   return {
     projectRoot,
@@ -1482,26 +1506,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 +1553,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 +1570,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 +1728,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 +1748,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 +1782,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 +1872,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 +2012,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 +2243,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.3.1",
+  "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",