vibe-splain 2.1.1 → 2.3.0

package/dist/index.js

@@ -244,6 +244,163 @@ var VENDOR_SEGMENTS = /* @__PURE__ */ new Set([
   "third_party",
   "third-party"
 ]);
+var PILLAR_KEYWORDS = {
+  "Auth": [
+    "passport",
+    "jsonwebtoken",
+    "bcrypt",
+    "bcryptjs",
+    "oauth",
+    "session",
+    "cookie-parser",
+    "next-auth",
+    "@auth/",
+    "lucia",
+    "clerk",
+    "@clerk/",
+    "supabase/auth",
+    "@supabase/auth-helpers",
+    "iron-session",
+    "jose",
+    "jwt",
+    "@auth/core",
+    "arctic"
+  ],
+  "Database": [
+    "prisma",
+    "@prisma/",
+    "mongoose",
+    "sequelize",
+    "typeorm",
+    "knex",
+    "pg",
+    "mysql",
+    "mysql2",
+    "better-sqlite3",
+    "drizzle-orm",
+    "drizzle",
+    "kysely",
+    "@supabase/supabase-js",
+    "mongodb",
+    "redis",
+    "ioredis"
+  ],
+  "Payments": [
+    "stripe",
+    "@stripe/",
+    "paypal",
+    "braintree",
+    "plaid",
+    "lemonsqueezy",
+    "@lemonsqueezy/",
+    "paddle",
+    "lemon-squeezy"
+  ],
+  "Routing": [
+    "express",
+    "fastify",
+    "koa",
+    "koa-router",
+    "next/router",
+    "next/navigation",
+    "react-router",
+    "@remix-run/",
+    "hono",
+    "express-rate-limit",
+    "cors",
+    "helmet"
+  ],
+  "Queue": [
+    "bull",
+    "bullmq",
+    "amqplib",
+    "kafkajs",
+    "kafka",
+    "upstash",
+    "@upstash/",
+    "bee-queue",
+    "agenda"
+  ],
+  "Storage": [
+    "aws-sdk",
+    "@aws-sdk/",
+    "multer",
+    "cloudinary",
+    "@google-cloud/storage",
+    "minio",
+    "@vercel/blob",
+    "sharp",
+    "imagekit"
+  ],
+  "Config": [
+    "dotenv",
+    "convict",
+    "env-var",
+    "@t3-oss/env",
+    "envalid"
+  ],
+  "Email": [
+    "nodemailer",
+    "resend",
+    "@sendgrid/",
+    "postmark",
+    "@resend/",
+    "mailgun"
+  ],
+  "Realtime": [
+    "socket.io",
+    "ws",
+    "pusher",
+    "ably",
+    "@supabase/realtime",
+    "socket.io-client"
+  ]
+};
+var PILLAR_PATH_PATTERNS = {
+  "Auth": /(?:^|[\/\\])(?:auth|login|signup|register|session|oauth)(?:[\/\\]|$)/i,
+  "Database": /(?:^|[\/\\])(?:db|database|models?|schema|migrations?|seeds?)(?:[\/\\]|$)/i,
+  "Payments": /(?:^|[\/\\])(?:pay|payments?|billing|checkout|subscriptions?|stripe)(?:[\/\\]|$)/i,
+  "Routing": /(?:^|[\/\\])(?:routes?|router|middleware|api)(?:[\/\\]|$)/i,
+  "Queue": /(?:^|[\/\\])(?:queues?|workers?|jobs?|consumers?|producers?)(?:[\/\\]|$)/i,
+  "Storage": /(?:^|[\/\\])(?:storage|uploads?|s3|blobs?|media)(?:[\/\\]|$)/i,
+  "Config": /(?:^|[\/\\])(?:config|env|settings?)(?:[\/\\]|$)/i,
+  "Email": /(?:^|[\/\\])(?:emails?|mail|notifications?)(?:[\/\\]|$)/i
+};
+var MEANINGLESS_SEGMENTS = /* @__PURE__ */ new Set([
+  "src",
+  "lib",
+  "app",
+  "pages",
+  "components",
+  "modules",
+  "features",
+  "core",
+  "common",
+  "shared",
+  "internal",
+  "pkg",
+  "packages"
+]);
+function matchPillarByImports(importSpecs) {
+  const scores = /* @__PURE__ */ new Map();
+  for (const spec of importSpecs) {
+    for (const [pillar, keywords] of Object.entries(PILLAR_KEYWORDS)) {
+      if (keywords.some((kw) => spec === kw || spec.startsWith(kw + "/"))) {
+        scores.set(pillar, (scores.get(pillar) || 0) + 1);
+      }
+    }
+  }
+  if (scores.size === 0)
+    return null;
+  return [...scores.entries()].sort((a, b) => b[1] - a[1])[0][0];
+}
+function matchPillarByPath(relPath) {
+  for (const [pillar, pattern] of Object.entries(PILLAR_PATH_PATTERNS)) {
+    if (pattern.test(relPath))
+      return pillar;
+  }
+  return null;
+}
 async function collectFiles(dir, projectRoot, acc) {
   let entries;
   try {
@@ -824,9 +981,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) {
@@ -1018,7 +1175,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))
@@ -1027,8 +1184,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);
@@ -1047,7 +1207,10 @@ async function scanProject(projectRoot) {
       publicSurface: w.ast.publicSurface,
       loc: w.ast.loc
     };
-    let gravityRaw = centrality * 50 + Math.log2(fanIn + 1) * 8 + Math.log2(w.ast.cyclomatic + 1) * 4 + Math.log2(w.ast.publicSurface + 1) * 3;
+    const depthRatio = (w.ast.cyclomatic + w.ast.maxNesting * 2) / Math.max(1, w.ast.publicSurface);
+    const depthFactor = Math.min(1, Math.log2(depthRatio + 1) / 3);
+    const adjustedCentrality = centrality * (0.3 + 0.7 * depthFactor);
+    let gravityRaw = adjustedCentrality * 50 + Math.log2(fanIn + 1) * 6 + Math.log2(w.ast.cyclomatic + 1) * 7 + Math.log2(w.ast.publicSurface + 1) * 2 + (w.ast.maxNesting >= 4 ? 5 : 0);
     if (!real)
       gravityRaw *= 0.2;
     const gravity = Math.max(0, Math.min(100, gravityRaw));
@@ -1060,7 +1223,9 @@ async function scanProject(projectRoot) {
       magicNumbers: w.ast.magicNumbers
     };
     const heat = real ? computeHeat(w.ast.smells) : 0;
-    const pillarHint = real ? `community-${communities.get(w.rel)}` : null;
+    const keywordPillar = matchPillarByImports(w.importSpecs);
+    const pathPillar = matchPillarByPath(w.rel);
+    const pillarHint = real ? keywordPillar || pathPillar || `community-${communities.get(w.rel)}` : null;
     const fa = {
       path: w.abs,
       relativePath: w.rel,
@@ -1119,28 +1284,96 @@ async function scanProject(projectRoot) {
     graph
   };
 }
-function buildPillars(real, communities, stack) {
-  const groups = /* @__PURE__ */ new Map();
+function buildPillars(real, communities, _stack) {
+  const keywordGroups = /* @__PURE__ */ new Map();
+  const unlabeled = [];
   for (const a of real) {
-    const c = communities.get(a.relativePath);
-    if (c === void 0)
-      continue;
-    if (!groups.has(c))
-      groups.set(c, []);
-    groups.get(c).push(a);
-  }
-  const sorted = [...groups.entries()].map(([id, files]) => ({ id, files, weight: files.reduce((s, f) => s + f.gravity, 0) })).filter((g) => g.files.length >= 2).sort((a, b) => b.weight - a.weight).slice(0, 6);
-  const pillars = sorted.map((g, idx) => {
-    const top = [...g.files].sort((a, b) => b.gravity - a.gravity);
-    const name = pillarName(top, idx);
-    return {
+    if (a.pillarHint && !a.pillarHint.startsWith("community-")) {
+      if (!keywordGroups.has(a.pillarHint))
+        keywordGroups.set(a.pillarHint, []);
+      keywordGroups.get(a.pillarHint).push(a);
+    } else {
+      unlabeled.push(a);
+    }
+  }
+  const pillars = [];
+  for (const [name, files] of keywordGroups) {
+    const sorted = [...files].sort((a, b) => b.gravity - a.gravity);
+    pillars.push({
       name,
-      description: `Graph cluster of ${g.files.length} files centered on ${basename(top[0].relativePath)}.`,
-      memberFiles: top.map((f) => f.relativePath)
-    };
+      description: `${name} subsystem: ${files.length} file${files.length > 1 ? "s" : ""} centered on ${basename(sorted[0].relativePath)}.`,
+      memberFiles: sorted.map((f) => f.relativePath)
+    });
+  }
+  if (unlabeled.length > 0) {
+    const communityGroups = /* @__PURE__ */ new Map();
+    for (const a of unlabeled) {
+      const c = communities.get(a.relativePath);
+      if (c === void 0)
+        continue;
+      if (!communityGroups.has(c))
+        communityGroups.set(c, []);
+      communityGroups.get(c).push(a);
+    }
+    const remainingSlots = Math.max(0, 6 - pillars.length);
+    const sorted = [...communityGroups.entries()].map(([id, files]) => ({ id, files, weight: files.reduce((s, f) => s + f.gravity, 0) })).filter((g) => g.files.length >= 2).sort((a, b) => b.weight - a.weight).slice(0, remainingSlots);
+    for (const g of sorted) {
+      const top = [...g.files].sort((a, b) => b.gravity - a.gravity);
+      const name = pillarNameFromCluster(top);
+      const existing = pillars.find((p) => p.name === name);
+      if (existing) {
+        existing.memberFiles.push(...top.map((f) => f.relativePath));
+        existing.description = `${name} subsystem: ${existing.memberFiles.length} files centered on ${basename(existing.memberFiles[0])}.`;
+      } else {
+        pillars.push({
+          name,
+          description: `${g.files.length} files centered on ${basename(top[0].relativePath)}.`,
+          memberFiles: top.map((f) => f.relativePath)
+        });
+      }
+    }
+  }
+  pillars.sort((a, b) => {
+    const gravA = real.filter((f) => a.memberFiles.includes(f.relativePath)).reduce((s, f) => s + f.gravity, 0);
+    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++}`;
@@ -1148,24 +1381,35 @@ 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 pillarName(files, idx) {
+function pillarNameFromCluster(files) {
+  const hintCounts = /* @__PURE__ */ new Map();
+  for (const f of files) {
+    if (f.pillarHint && !f.pillarHint.startsWith("community-")) {
+      hintCounts.set(f.pillarHint, (hintCounts.get(f.pillarHint) || 0) + 1);
+    }
+  }
+  if (hintCounts.size > 0) {
+    const best = [...hintCounts.entries()].sort((a, b) => b[1] - a[1])[0];
+    if (best[1] >= files.length * 0.4)
+      return best[0];
+  }
   const dirs = files.map((f) => dirname(f.relativePath)).filter((d) => d && d !== ".");
   if (dirs.length) {
-    const counts = /* @__PURE__ */ new Map();
+    const segCounts = /* @__PURE__ */ new Map();
     for (const d of dirs) {
-      const seg = d.split(sep).pop();
-      counts.set(seg, (counts.get(seg) || 0) + 1);
+      const segments = d.split(sep).filter((s) => !MEANINGLESS_SEGMENTS.has(s.toLowerCase()));
+      const meaningful = segments.pop();
+      if (meaningful)
+        segCounts.set(meaningful, (segCounts.get(meaningful) || 0) + 1);
     }
-    const top = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    const top = [...segCounts.entries()].sort((a, b) => b[1] - a[1])[0];
     if (top)
       return titleCase(top[0]);
   }
-  return `Cluster ${idx + 1}`;
+  const topFile = basename(files[0].relativePath, extname(files[0].relativePath));
+  return titleCase(topFile);
 }
 function titleCase(s) {
   return s.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
@@ -1234,11 +1478,30 @@ 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 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);
@@ -1492,6 +1755,7 @@ async function handleGetFileContext(args) {
     heatSignals: evidence.heatSignals,
     importedBy: persisted?.importedBy ?? [],
     imports: persisted?.imports ?? [],
+    pillarHint: persisted?.pillarHint ?? null,
     signature: evidence.signature,
     hotSpans: evidence.hotSpans,
     smellSpans: evidence.smellSpans
@@ -1531,7 +1795,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: {
@@ -1720,17 +1984,17 @@ var inspectPillarTool = {
 };
 async function handleInspectPillar(args) {
   const projectRoot = args.projectRoot;
-  const pillarName2 = args.pillarName;
-  if (!projectRoot || !pillarName2)
+  const pillarName = args.pillarName;
+  if (!projectRoot || !pillarName)
     throw new Error("projectRoot and pillarName are required");
   const dossier = await readDossier(projectRoot);
   if (!dossier) {
     return { error: "No dossier found. Run scan_project first." };
   }
-  const pillar = dossier.pillars.find((p) => p.name === pillarName2);
+  const pillar = dossier.pillars.find((p) => p.name === pillarName);
   if (!pillar) {
     return {
-      error: `Pillar "${pillarName2}" not found. Available pillars: ${dossier.pillars.map((p) => p.name).join(", ")}`
+      error: `Pillar "${pillarName}" not found. Available pillars: ${dossier.pillars.map((p) => p.name).join(", ")}`
     };
   }
   return pillar;

package/dist/mcp/tools/get_file_context.js

@@ -39,6 +39,7 @@ export async function handleGetFileContext(args) {
         heatSignals: evidence.heatSignals,
         importedBy: persisted?.importedBy ?? [],
         imports: persisted?.imports ?? [],
+        pillarHint: persisted?.pillarHint ?? null,
         signature: evidence.signature,
         hotSpans: evidence.hotSpans,
         smellSpans: evidence.smellSpans,

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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-splain",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Architectural dossier engine for vibe-coded projects. Runs as an MCP server inside your coding agent.",
   "type": "module",
   "license": "MIT",