vibe-splain 2.2.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
@@ -981,9 +1003,9 @@ function detectCommunities(nodes, adjacency) {
       if (!neighbors || neighbors.size === 0)
         continue;
       const counts = /* @__PURE__ */ new Map();
-      for (const nb of neighbors) {
+      for (const [nb, weight] of neighbors) {
         const l = label.get(nb);
-        counts.set(l, (counts.get(l) || 0) + 1);
+        counts.set(l, (counts.get(l) || 0) + weight);
       }
       let best = label.get(node), bestCount = -1;
       for (const [l, c] of counts) {
@@ -1175,7 +1197,7 @@ async function scanProject(projectRoot) {
   const undirected = /* @__PURE__ */ new Map();
   for (const node of realNodes) {
     outEdges.set(node, /* @__PURE__ */ new Set());
-    undirected.set(node, /* @__PURE__ */ new Set());
+    undirected.set(node, /* @__PURE__ */ new Map());
   }
   for (const w of work) {
     if (!realSet.has(w.rel))
@@ -1184,8 +1206,11 @@ async function scanProject(projectRoot) {
       if (!realSet.has(target))
         continue;
       outEdges.get(w.rel).add(target);
-      undirected.get(w.rel).add(target);
-      undirected.get(target).add(w.rel);
+      const wDir = w.rel.split(sep)[0];
+      const tDir = target.split(sep)[0];
+      const weight = wDir === tDir ? 1 : 0.5;
+      undirected.get(w.rel).set(target, weight);
+      undirected.get(target).set(w.rel, weight);
     }
   }
   const ranks = pageRank(realNodes, outEdges);
@@ -1268,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,
@@ -1335,8 +1362,42 @@ function buildPillars(real, communities, _stack) {
     const gravB = real.filter((f) => b.memberFiles.includes(f.relativePath)).reduce((s, f) => s + f.gravity, 0);
     return gravB - gravA;
   });
-  const seen = /* @__PURE__ */ new Set();
+  if (pillars.length === 0 && real.length > 0) {
+    pillars.push({ name: "Core", description: "Primary application code.", memberFiles: real.slice(0, 20).map((f) => f.relativePath) });
+  }
+  const finalPillars = [];
   for (const p of pillars) {
+    if (p.memberFiles.length > 15) {
+      const groups = /* @__PURE__ */ new Map();
+      for (const f of p.memberFiles) {
+        let bucket = "Core";
+        if (f.includes("app/") || f.includes("pages/") || f.includes("routes/"))
+          bucket = "Routing";
+        else if (f.includes("components/") || f.includes("ui/"))
+          bucket = "Components";
+        else if (f.includes("hooks/") || f.includes("lib/") || f.includes("utils/"))
+          bucket = "Logic";
+        const d = basename(dirname(f));
+        const key = `${p.name} (${bucket} - ${d})`;
+        if (!groups.has(key))
+          groups.set(key, []);
+        groups.get(key).push(f);
+      }
+      for (const [key, files] of groups) {
+        if (files.length > 0) {
+          finalPillars.push({
+            name: key,
+            description: `Subdivided from ${p.name}`,
+            memberFiles: files
+          });
+        }
+      }
+    } else {
+      finalPillars.push(p);
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of finalPillars) {
     let n = p.name, i = 2;
     while (seen.has(n)) {
       n = `${p.name} ${i++}`;
@@ -1344,10 +1405,7 @@ function buildPillars(real, communities, _stack) {
     p.name = n;
     seen.add(n);
   }
-  if (pillars.length === 0 && real.length > 0) {
-    pillars.push({ name: "Core", description: "Primary application code.", memberFiles: real.slice(0, 20).map((f) => f.relativePath) });
-  }
-  return pillars;
+  return finalPillars;
 }
 function pillarNameFromCluster(files) {
   const hintCounts = /* @__PURE__ */ new Map();
@@ -1444,6 +1502,10 @@ async function readDossier(projectRoot) {
 }
 async function writeDossier(projectRoot, dossier) {
   await dossierMutex.runExclusive(async () => {
+    for (const p of dossier.pillars) {
+      p.decisions = p.decisions.filter((c) => !(c.severity === 1 && c.category === "Convention"));
+      p.cardCount = p.decisions.length;
+    }
     const dir = join5(projectRoot, ".vibe-splainer");
     await mkdir3(dir, { recursive: true });
     const dossierPath = join5(dir, "dossier.json");
@@ -1491,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,
@@ -1507,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;
           }
         }
       }
@@ -1663,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.",
@@ -1683,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) {
@@ -1717,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");
@@ -1742,7 +1807,7 @@ var writeDecisionCardTool = {
       narrative: { type: "string", description: "3-5 sentences. WHY it exists and WHY it's built this way. Do NOT restate the file's header comments." },
       tradeoff: { type: "string", description: "What was given up, or why the obvious approach was rejected. Null only if genuinely none." },
       blastRadius: { type: "string", description: "What breaks if this changes. Ground it in the fan-in (importedBy) from get_file_context." },
-      confidence: { type: "string", enum: ["low", "medium", "high"] },
+      confidence: { type: "string", enum: ["low", "medium", "high"], description: 'Do NOT default to "high". Reserve "high" ONLY for provable execution anti-patterns. Score subjective stylistic choices or abstractions as "low" or "medium".' },
       evidence: {
         type: "array",
         items: {
@@ -1807,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,
@@ -1950,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: {
@@ -2181,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.d.ts

@@ -47,6 +47,7 @@ export declare const writeDecisionCardTool: {
             confidence: {
                 type: string;
                 enum: string[];
+                description: string;
             };
             evidence: {
                 type: string;

package/dist/mcp/tools/write_decision_card.js

@@ -29,7 +29,7 @@ export const writeDecisionCardTool = {
             narrative: { type: 'string', description: "3-5 sentences. WHY it exists and WHY it's built this way. Do NOT restate the file's header comments." },
             tradeoff: { type: 'string', description: 'What was given up, or why the obvious approach was rejected. Null only if genuinely none.' },
             blastRadius: { type: 'string', description: 'What breaks if this changes. Ground it in the fan-in (importedBy) from get_file_context.' },
-            confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+            confidence: { type: 'string', enum: ['low', 'medium', 'high'], description: 'Do NOT default to "high". Reserve "high" ONLY for provable execution anti-patterns. Score subjective stylistic choices or abstractions as "low" or "medium".' },
             evidence: {
                 type: 'array',
                 items: {
@@ -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.2.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",