vibe-splain 2.1.1 → 2.2.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 {
@@ -1047,7 +1204,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 +1220,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,25 +1281,59 @@ 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();
   for (const p of pillars) {
@@ -1153,19 +1349,33 @@ function buildPillars(real, communities, stack) {
   }
   return pillars;
 }
-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());
@@ -1492,6 +1702,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
@@ -1720,17 +1931,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/package.json

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