vibe-splain 2.4.0 → 2.4.1

package/dist/index.js

@@ -106,6 +106,7 @@ async function writeGraph(projectRoot, graph) {
 
 // ../brain/dist/analysis.js
 import { join as join3 } from "path";
+import { createHash } from "crypto";
 import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir2 } from "fs/promises";
 async function readAnalysis(projectRoot) {
   const p = join3(projectRoot, ".vibe-splainer", "analysis.json");
@@ -125,67 +126,437 @@ async function writeAnalysis(projectRoot, store) {
   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));
+var ENTRYPOINT_ROLES = /* @__PURE__ */ new Set([
+  "app_route_page",
+  "app_route_handler",
+  "pages_route",
+  "pages_api_route",
+  "trpc_api_route"
+]);
+function findRuntimeEntrypoints(relPath, files, maxDepth = 8) {
+  const results = [];
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [{ path: relPath, depth: 0 }];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (seen.has(current.path))
+      continue;
+    seen.add(current.path);
+    if (current.path !== relPath) {
+      const meta2 = files[current.path];
+      if (meta2 && ENTRYPOINT_ROLES.has(meta2.frameworkRole)) {
+        results.push({
+          path: current.path,
+          frameworkRole: meta2.frameworkRole,
+          productDomain: meta2.productDomain,
+          distance: current.depth
+        });
+        if (results.length >= 8)
+          break;
+        continue;
+      }
+    }
+    if (current.depth >= maxDepth)
+      continue;
+    const meta = files[current.path];
+    if (!meta)
+      continue;
+    for (const importer of meta.importedBy) {
+      if (!seen.has(importer)) {
+        queue.push({ path: importer, depth: current.depth + 1 });
+      }
+    }
+  }
+  const byPath = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    const existing = byPath.get(r.path);
+    if (!existing || r.distance < existing.distance)
+      byPath.set(r.path, r);
+  }
+  return [...byPath.values()].sort((a, b) => a.distance - b.distance);
+}
+function deriveEntrypointTraceStatus(entrypoints, unresolved) {
+  if (entrypoints.length > 0 && unresolved.length === 0)
+    return "complete";
+  if (entrypoints.length > 0)
+    return "partial";
+  if (unresolved.length > 0)
+    return "blocked_by_alias_resolution";
+  return "no_runtime_entrypoint_found";
+}
+function computeLoadBearingScore(f, entrypoints) {
+  let score = 0;
+  if (f.gravity >= 85)
+    score += 2;
+  if (f.heat >= 60)
+    score += 1;
+  if (entrypoints.length >= 2)
+    score += 2;
+  if (f.importedBy.length >= 3)
+    score += 1;
+  if (f.sideEffectProfile.includes("database_write"))
+    score += 3;
+  if (f.sideEffectProfile.includes("booking_mutation"))
+    score += 3;
+  if (f.sideEffectProfile.includes("payment_mutation"))
+    score += 3;
+  if (f.sideEffectProfile.includes("auth_token_mutation"))
+    score += 3;
+  if (f.sideEffectProfile.includes("webhook_delivery"))
+    score += 2;
+  if (f.sideEffectProfile.includes("webhook_ingress"))
+    score += 2;
+  if (f.sideEffectProfile.includes("calendar_mutation"))
+    score += 2;
+  if (f.sideEffectProfile.includes("redirect"))
+    score += 1;
+  if (f.sideEffectProfile.includes("analytics_event"))
+    score += 1;
+  const highImpactDomains = [
+    "booking_creation",
+    "payments",
+    "auth_oauth",
+    "webhooks",
+    "payments_webhooks"
+  ];
+  if (highImpactDomains.includes(f.productDomain))
+    score += 2;
+  const maxSeverity = f.smells.length > 0 ? Math.max(...f.smells.map((s) => s.severity)) : 0;
+  if (maxSeverity === 5)
+    score += 3;
+  return score;
+}
+function computeSeverity(f, entrypoints) {
+  let score = 0;
+  if (f.sideEffectProfile.includes("database_write"))
+    score += 3;
+  if (f.sideEffectProfile.includes("booking_mutation"))
+    score += 4;
+  if (f.sideEffectProfile.includes("payment_mutation"))
+    score += 4;
+  if (f.sideEffectProfile.includes("auth_token_mutation"))
+    score += 4;
+  if (f.sideEffectProfile.includes("webhook_delivery"))
+    score += 3;
+  if (f.sideEffectProfile.includes("webhook_ingress"))
+    score += 3;
+  if (f.sideEffectProfile.includes("calendar_mutation"))
+    score += 3;
+  if (f.productDomain === "booking_creation")
+    score += 3;
+  if (f.productDomain === "payments" || f.productDomain === "payments_webhooks")
+    score += 3;
+  if (f.productDomain === "auth_oauth")
+    score += 3;
+  if (f.productDomain === "webhooks")
+    score += 2;
+  if (f.gravity >= 85)
+    score += 2;
+  if (f.heat >= 70)
+    score += 2;
+  if (f.heatSignals.maxNesting >= 4)
+    score += 1;
+  if (f.heatSignals.longFunctions >= 1)
+    score += 1;
+  if (f.heatSignals.swallowedCatches >= 1)
+    score += 1;
+  if (entrypoints.length >= 2)
+    score += 2;
+  if (score >= 10)
+    return 5;
+  if (score >= 7)
+    return 4;
+  if (score >= 4)
+    return 3;
+  if (score >= 2)
+    return 2;
+  return 1;
+}
+function inferRiskTypes(f) {
   const types = [];
-  if (f.gravitySignals.cyclomatic > 15)
+  const kinds = new Set(f.smells.map((s) => s.kind));
+  if (f.gravitySignals.cyclomatic > 20)
     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("god-file")) {
+    if (f.frameworkRole === "hook")
+      types.push("god_hook");
+    else
+      types.push("god_component");
+  }
+  if (f.sideEffectProfile.length > 3 && !f.sideEffectProfile.includes("none_detected")) {
+    types.push("side_effect_coupling");
+  }
+  if (f.productDomain === "forms" && f.gravitySignals.fanIn > 5 && f.gravitySignals.publicSurface > 8)
+    types.push("registry_bottleneck");
+  if (f.sideEffectProfile.some((s) => ["booking_mutation", "payment_mutation", "auth_token_mutation"].includes(s)) && f.gravitySignals.cyclomatic > 10)
+    types.push("mutation_orchestration");
+  if (ENTRYPOINT_ROLES.has(f.frameworkRole) && f.sideEffectProfile.includes("database_write"))
+    types.push("route_handler_write_path");
   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"];
+    types.push("error_swallowing");
+  if (f.sideEffectProfile.includes("local_storage") || f.sideEffectProfile.includes("indexed_db"))
+    types.push("storage_persistence_risk");
+  if (types.length === 0)
+    types.push("complexity_hotspot");
+  return types;
+}
+function inferObservableOutputs(f) {
+  const outputs = [];
+  if (f.sideEffectProfile.includes("redirect"))
+    outputs.push("redirect_url");
+  if (ENTRYPOINT_ROLES.has(f.frameworkRole))
+    outputs.push("http_status");
+  if (f.frameworkRole === "app_route_handler" || f.frameworkRole === "pages_api_route") {
+    outputs.push("json_response_shape");
+  }
+  if (f.productDomain === "booking_creation" || f.productDomain === "booking_management") {
+    outputs.push("booking_uid");
+  }
+  if (f.productDomain === "payments" || f.productDomain === "payments_webhooks") {
+    outputs.push("payment_status");
+  }
+  if (f.productDomain === "auth_oauth") {
+    outputs.push("auth_token");
+  }
+  if (f.sideEffectProfile.includes("webhook_delivery") || f.sideEffectProfile.includes("webhook_ingress")) {
+    outputs.push("webhook_payload");
+  }
+  if (f.sideEffectProfile.includes("calendar_mutation")) {
+    outputs.push("calendar_event_id");
+  }
+  if (f.sideEffectProfile.includes("email_send")) {
+    outputs.push("email_payload");
+  }
+  if (f.sideEffectProfile.includes("analytics_event")) {
+    outputs.push("sdk_event_name");
+  }
+  if (f.frameworkRole === "hook" || f.frameworkRole === "store") {
+    outputs.push("ui_state_transition");
+  }
+  return [...new Set(outputs)];
+}
+function inferWriteIntents(f) {
+  const intents = [];
+  if (f.productDomain === "booking_creation") {
+    intents.push("create_booking");
+    if (f.relativePath.includes("reschedule") || f.relativePath.includes("Reschedule"))
+      intents.push("reschedule_booking");
+    if (f.relativePath.includes("recurring") || f.relativePath.includes("Recurring")) {
+      intents.push("create_recurring_booking");
+    }
+  }
+  if (f.productDomain === "booking_management") {
+    intents.push("cancel_booking");
+  }
+  if (f.productDomain === "event_type_configuration") {
+    intents.push("update_event_type");
+  }
+  if (f.productDomain === "availability") {
+    intents.push("update_availability");
+  }
+  if (f.productDomain === "payments") {
+    intents.push("create_payment");
+  }
+  if (f.productDomain === "payments_webhooks") {
+    intents.push("handle_payment_webhook");
+  }
+  if (f.productDomain === "auth_oauth") {
+    intents.push("issue_auth_token");
+    intents.push("refresh_auth_token");
+  }
+  if (f.sideEffectProfile.includes("webhook_delivery")) {
+    intents.push("send_webhook");
+  }
+  if (f.productDomain === "settings") {
+    intents.push("update_user_settings");
+  }
+  if (f.sideEffectProfile.includes("local_storage") || f.sideEffectProfile.includes("indexed_db")) {
+    intents.push("persist_local_state");
+  }
+  return intents.length > 0 ? intents : ["none_detected"];
+}
+function inferPatchRisk(f, score, riskTypes) {
+  if (score >= 12 || f.productDomain === "booking_creation" && riskTypes.includes("mutation_orchestration")) {
+    return {
+      level: "critical",
+      reason: `${f.productDomain} domain with ${riskTypes.join(", ")} \u2014 any patch risks breaking live booking, payment, or auth flows.`
+    };
+  }
+  if (score >= 8 || f.sideEffectProfile.includes("payment_mutation") || f.sideEffectProfile.includes("auth_token_mutation")) {
+    return {
+      level: "high",
+      reason: `${f.productDomain} writes to external state (${f.sideEffectProfile.filter((s) => ["payment_mutation", "auth_token_mutation", "database_write", "webhook_delivery"].includes(s)).join(", ") || "database"}). Changes require integration testing.`
+    };
+  }
+  if (score >= 5 || f.importedBy.length >= 5) {
+    return {
+      level: "medium",
+      reason: `Imported by ${f.importedBy.length} files. Interface changes will cascade.`
+    };
+  }
+  return {
+    level: "low",
+    reason: "Locally contained \u2014 limited blast radius."
+  };
+}
+function inferSafePatchStrategy(f, riskTypes) {
+  if (riskTypes.includes("mutation_orchestration")) {
+    return "Do not rewrite inline. Extract pure decision logic into a tested reducer or state machine first. Preserve all side-effect call sites (redirect URLs, SDK event names, response shapes) as invariants.";
+  }
+  if (riskTypes.includes("registry_bottleneck")) {
+    return "Add new entries without removing existing keys. Treat the registry map as append-only until all consumers are verified.";
+  }
+  if (riskTypes.includes("route_handler_write_path")) {
+    return "Add integration tests covering success and failure paths before modifying. Verify HTTP status codes and response shapes are preserved.";
+  }
+  if (riskTypes.includes("god_component") || riskTypes.includes("god_hook")) {
+    return "Extract sub-concerns into separate modules first. Only refactor the extraction points after tests confirm equivalence.";
+  }
+  if (f.sideEffectProfile.includes("database_write")) {
+    return "Wrap changes in a transaction or use a feature flag. Run against a staging database before production.";
+  }
+  return "Review importedBy before patching. Run affected integration tests.";
+}
+function inferDoNotTouch(f) {
+  const items = [];
+  if (f.sideEffectProfile.includes("payment_mutation"))
+    items.push("payment flow branch");
+  if (f.sideEffectProfile.includes("auth_token_mutation"))
+    items.push("token issuance / refresh branch");
+  if (f.sideEffectProfile.includes("webhook_delivery") || f.sideEffectProfile.includes("webhook_ingress")) {
+    items.push("webhook payload shape");
+  }
+  if (f.sideEffectProfile.includes("redirect"))
+    items.push("redirect URL strings");
+  if (f.sideEffectProfile.includes("analytics_event"))
+    items.push("SDK event names");
+  if (f.sideEffectProfile.includes("booking_mutation")) {
+    items.push("booking success response shape", "recurring booking branch");
+  }
+  if (f.productDomain === "auth_oauth")
+    items.push("OAuth callback URLs", "token scopes");
+  return items;
+}
+function inferTestProbes(f, writeIntents, observableOutputs) {
+  const probes = [];
+  if (writeIntents.includes("create_booking")) {
+    probes.push({
+      name: "standard booking success",
+      scenario: "create a standard booking and assert success redirect and booking uid",
+      expectedObservable: ["booking_uid", "redirect_url", "sdk_event_name"].filter((o) => observableOutputs.includes(o))
+    });
+  }
+  if (writeIntents.includes("reschedule_booking")) {
+    probes.push({
+      name: "reschedule booking",
+      scenario: "reschedule an existing booking and assert reschedule event path",
+      expectedObservable: ["booking_uid", "redirect_url"].filter((o) => observableOutputs.includes(o))
+    });
+  }
+  if (writeIntents.includes("create_recurring_booking")) {
+    probes.push({
+      name: "recurring booking",
+      scenario: "create recurring booking and assert recurring success behavior",
+      expectedObservable: ["booking_uid", "redirect_url"].filter((o) => observableOutputs.includes(o))
+    });
+  }
+  if (writeIntents.includes("handle_payment_webhook")) {
+    probes.push({
+      name: "payment webhook ingestion",
+      scenario: "send a valid payment webhook and assert booking/payment state updated",
+      expectedObservable: ["payment_status", "booking_uid", "http_status"].filter((o) => observableOutputs.includes(o))
+    });
+  }
+  if (writeIntents.includes("issue_auth_token")) {
+    probes.push({
+      name: "token issuance",
+      scenario: "complete OAuth flow and assert access token issued with correct scopes",
+      expectedObservable: ["auth_token", "http_status"].filter((o) => observableOutputs.includes(o))
+    });
+  }
+  return probes;
+}
+function buildRawEvidence(f) {
+  return f.hotSpans.map((span) => ({
+    file: f.relativePath,
+    startLine: span.startLine,
+    endLine: span.endLine,
+    rawSourceExcerpt: span.snippet,
+    evidenceHash: createHash("sha256").update(span.snippet).digest("hex").slice(0, 12)
+  }));
 }
 function deriveConfidence(f) {
-  if (f.gravitySignals.fanIn >= LOAD_BEARING_FAN_IN_THRESHOLD && f.gravity >= 40)
+  if (f.gravitySignals.fanIn >= 10 && 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);
-    }
+function validateTarget(target) {
+  const warn = (msg) => console.error(`[vibe-splain] WARN ${target.path}: ${msg}`);
+  const err = (msg) => console.error(`[vibe-splain] ERR  ${target.path}: ${msg}`);
+  if (target.severity >= 4 && target.runtimeEntrypoints.length === 0) {
+    warn("high severity target has no runtime entrypoints \u2014 check alias resolution");
   }
-  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)
-  }));
+  if (target.severity === 5 && !target.isLoadBearing) {
+    err("severity 5 target must be load bearing");
+  }
+  if (target.productDomain === "routing_infrastructure" && !target.path.includes("middleware") && !target.path.includes("router") && !target.path.includes("Navigation")) {
+    warn("possible over-classification as routing_infrastructure");
+  }
+  if ((target.path.includes("payment") || target.path.includes("stripe") || target.path.includes("paypal")) && !target.sideEffectProfile.includes("payment_mutation") && !target.sideEffectProfile.includes("webhook_ingress")) {
+    warn("payment file missing payment side effect classification");
+  }
+  if (target.rawEvidence.some((e) => e.rawSourceExcerpt.includes("// ..") || e.rawSourceExcerpt.includes("/* ..."))) {
+    err("raw evidence appears summarized or annotated");
+  }
+}
+async function writeDeltaTargets(projectRoot, store, _entrypoints = /* @__PURE__ */ new Set()) {
+  const targets = Object.values(store.files).filter((f) => f.isRealSource).sort((a, b) => b.gravity - a.gravity).map((f) => {
+    const runtimeEntrypoints = findRuntimeEntrypoints(f.relativePath, store.files);
+    const entrypointTraceStatus = deriveEntrypointTraceStatus(runtimeEntrypoints, f.importsUnresolved);
+    const loadBearingScore = computeLoadBearingScore(f, runtimeEntrypoints);
+    const severity = computeSeverity(f, runtimeEntrypoints);
+    const riskTypes = inferRiskTypes(f);
+    const observableOutputs = inferObservableOutputs(f);
+    const writeIntents = inferWriteIntents(f);
+    const patchRisk = inferPatchRisk(f, loadBearingScore, riskTypes);
+    const rawEvidence = buildRawEvidence(f);
+    const confidence = deriveConfidence(f);
+    const fileHashInput = f.hotSpans.map((h) => h.snippet).join("");
+    const fileHash = createHash("sha256").update(fileHashInput || f.relativePath).digest("hex").slice(0, 12);
+    const target = {
+      path: f.relativePath,
+      frameworkRole: f.frameworkRole,
+      productDomain: f.productDomain,
+      gravity: Math.round(f.gravity),
+      heat: Math.round(f.heat),
+      severity,
+      confidence,
+      isLoadBearing: loadBearingScore >= 5,
+      loadBearingScore,
+      riskTypes,
+      sideEffectProfile: f.sideEffectProfile,
+      blastRadius: f.importedBy,
+      runtimeEntrypoints,
+      entrypointTraceStatus,
+      blockedImports: f.importsUnresolved,
+      observableOutputs,
+      writeIntents,
+      patchRisk,
+      safePatchStrategy: inferSafePatchStrategy(f, riskTypes),
+      doNotTouch: inferDoNotTouch(f),
+      testProbes: inferTestProbes(f, writeIntents, observableOutputs),
+      rawEvidence,
+      analysisAnnotation: `${f.frameworkRole} in ${f.productDomain} domain. fanIn=${f.gravitySignals.fanIn} cyclomatic=${f.gravitySignals.cyclomatic} loc=${f.gravitySignals.loc}`,
+      hashes: {
+        fileHash,
+        evidenceHash: rawEvidence.map((e) => e.evidenceHash).join("-")
+      }
+    };
+    validateTarget(target);
+    return target;
+  });
   const dir = join3(projectRoot, ".vibe-splainer");
   await mkdir2(dir, { recursive: true });
   const dest = join3(dir, "delta_targets.json");
@@ -376,20 +747,6 @@ var PILLAR_KEYWORDS = {
     "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",
@@ -440,7 +797,6 @@ 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,
@@ -481,6 +837,144 @@ function matchPillarByPath(relPath) {
   }
   return null;
 }
+function inferFrameworkRole(relPath) {
+  const p = relPath.replace(/\\/g, "/");
+  if (/\.test\.|\.spec\./.test(p))
+    return "test";
+  if (/\.generated\.|__generated__|\.prisma\//.test(p))
+    return "generated";
+  if (/(?:^|\/)app\/.*\/page\.tsx?$/.test(p))
+    return "app_route_page";
+  if (/(?:^|\/)app\/.*\/layout\.tsx?$/.test(p))
+    return "app_route_layout";
+  if (/(?:^|\/)app\/.*\/route\.tsx?$/.test(p))
+    return "app_route_handler";
+  if (/(?:^|\/)app\/.*\/loading\.tsx?$/.test(p))
+    return "app_loading_boundary";
+  if (/(?:^|\/)app\/.*\/error\.tsx?$/.test(p))
+    return "app_error_boundary";
+  if (/(?:^|\/)pages\/api\/trpc\//.test(p))
+    return "trpc_api_route";
+  if (/(?:^|\/)pages\/api\//.test(p))
+    return "pages_api_route";
+  if (/(?:^|\/)pages\//.test(p))
+    return "pages_route";
+  if (/\/hooks\/|\/use[A-Z][^/]*\.(ts|tsx)$/.test(p))
+    return "hook";
+  if (/\/stores?\/|[Ss]tore\.(ts|tsx)$/.test(p))
+    return "store";
+  if (/[Pp]rovider\.(tsx?|jsx?)$|\/providers?\//.test(p))
+    return "provider";
+  if (/\.types\.ts$|\/types\.ts$|\/types\/[^/]+\.ts$/.test(p))
+    return "type_definition";
+  if (/\.(tsx|jsx)$/.test(p))
+    return "component";
+  if (/\.(ts|js|mjs|cjs)$/.test(p))
+    return "utility";
+  return "unknown";
+}
+function inferProductDomain(relPath, importSpecs) {
+  const p = relPath.toLowerCase().replace(/\\/g, "/");
+  if (/\.test\.|\.spec\.|__tests__|\/e2e\/|\/playwright\/|\/cypress\//.test(p)) {
+    return "test_infrastructure";
+  }
+  if (/\.generated\.|__generated__|\.prisma\//.test(p)) {
+    return "generated_noise";
+  }
+  if (p.includes("booking-audit") || p.includes("bookingaudit"))
+    return "booking_audit";
+  if (p.includes("bookeventform") || p.includes("availabletimes") || p.includes("availabletimeslots") || p.includes("usebookings") || p.includes("/pages/api/book/") || p.includes("/api/book/") || p.includes("/booking-successful/") || p.includes("/reschedule/") || p.includes("booking-page-wrapper") || p.includes("/book/") && !p.includes("booking-audit"))
+    return "booking_creation";
+  if (p.includes("modules/bookings") || p.includes("components/booking/actions") || p.includes("/bookings/[status]") || p.includes("/booking/[uid]") || p.includes("/bookings/"))
+    return "booking_management";
+  if (p.includes("event-types") || p.includes("eventtypes") || p.includes("eventavailabilitytab") || p.includes("eventadvancedtab") || p.includes("eventlimits") || p.includes("eventrecurring"))
+    return "event_type_configuration";
+  if (p.includes("availability") || p.includes("/schedules/") || p.includes("/slots/"))
+    return "availability";
+  if (p.includes("oauth") || p.includes("nextauth") || p.includes("/auth/oauth") || p.includes("/api/auth/") || importSpecs.some((s) => s.includes("arctic") || s.includes("@auth/core")))
+    return "auth_oauth";
+  if (p.includes("/auth/") || p.includes("signup") || p.includes("login") || p.includes("forgot-password") || p.includes("reset-password") || p.includes("two-factor") || p.includes("verify-email") || importSpecs.some((s) => s.includes("next-auth") || s.includes("@clerk/")))
+    return "auth";
+  if ((p.includes("stripe") || p.includes("paypal") || p.includes("btcpay") || p.includes("alby") || p.includes("payment")) && (p.includes("webhook") || p.includes("hook")))
+    return "payments_webhooks";
+  if (p.includes("stripe") || p.includes("paypal") || p.includes("btcpay") || p.includes("alby") || p.includes("payment") || p.includes("billing") || p.includes("checkout") || p.includes("subscription") || importSpecs.some((s) => s.includes("stripe") || s.includes("@stripe/")))
+    return "payments";
+  if (p.includes("webhook"))
+    return "webhooks";
+  if (p.includes("app-store") || p.includes("appstore") || p.includes("/apps/") || p.includes("modules/apps"))
+    return "apps_marketplace";
+  if (p.includes("calendar") || p.includes("selected-calendars") || importSpecs.some((s) => s.includes("googleapis") || s.includes("@google-cloud/")))
+    return "calendar_integrations";
+  if (p.includes("video") || p.includes("calvideo") || p.includes("daily.co"))
+    return "video";
+  if (p.includes("onboarding") || p.includes("getting-started"))
+    return "onboarding";
+  if (p.includes("/settings/") || p.includes("/settings."))
+    return "settings";
+  if (p.includes("/admin/") || p.includes("/admin."))
+    return "admin";
+  if (p.includes("data-table") || p.includes("datatable") || p.includes("datasegment") || p.includes("segment"))
+    return "data_table";
+  if (p.includes("shell/navigation") || p.includes("navigationitem") || p.includes("/shell/") || p.includes("sidebar") || p.includes("topnav") || p.includes("mainnav"))
+    return "shell_navigation";
+  if (p.includes("form-builder") || p.includes("formbuilder") || p.includes("/forms/") || p.includes("routingforms"))
+    return "forms";
+  if (p.includes("embed"))
+    return "embed";
+  if (p.includes("notification") || p.includes("/email/") || p.includes("/emails/") || importSpecs.some((s) => s.includes("nodemailer") || s.includes("resend") || s.includes("@sendgrid/")))
+    return "notifications";
+  if (p.includes("middleware") && !p.includes("pages/api/") || p.includes("/router.") || p.includes("routerconfig"))
+    return "routing_infrastructure";
+  return "unknown";
+}
+function inferSideEffectProfile(source, importSpecs) {
+  const effects = /* @__PURE__ */ new Set();
+  if (/router\.(push|replace|back)\(|redirect\(|notFound\(|permanentRedirect\(/.test(source)) {
+    effects.add("redirect");
+  }
+  if (/["']use server["']/.test(source))
+    effects.add("server_action");
+  if (/useMutation\b|\.mutate\b|\.mutateAsync\b/.test(source))
+    effects.add("trpc_mutation");
+  if (/sdkActionManager\.fire|telemetry\.|posthog\.|mixpanel\.|amplitude\.|ga\(/.test(source) || importSpecs.some((s) => /analytics|telemetry|posthog|mixpanel|amplitude/.test(s)))
+    effects.add("analytics_event");
+  if (/prisma\s*[.?]\s*\w+\s*[.?]\s*(create|update|upsert|delete|deleteMany|updateMany|createMany|transaction|executeRaw|queryRaw)\b/.test(source)) {
+    effects.add("database_write");
+  }
+  if (/prisma\s*[.?]\s*\w+\s*[.?]\s*(findMany|findUnique|findFirst|findFirstOrThrow|findUniqueOrThrow|count|aggregate|groupBy)\b/.test(source)) {
+    effects.add("database_read");
+  }
+  if (/createBooking|handleNewBooking|cancelBooking|rescheduleBooking|handleBooking|createRecurring/.test(source)) {
+    effects.add("booking_mutation");
+  }
+  if (importSpecs.some((s) => /stripe|paypal|btcpay|alby/.test(s.toLowerCase())) || /stripe\.|paymentIntent|createPaymentIntent|confirmPayment|createCharge/.test(source))
+    effects.add("payment_mutation");
+  if (/signIn\b|signOut\b|createSession|destroySession|issueToken|refreshToken|getToken/.test(source)) {
+    effects.add("auth_token_mutation");
+  }
+  if (/triggerWebhook|sendWebhook|webhook\.send\b/.test(source))
+    effects.add("webhook_delivery");
+  if (/webhookSecret|stripe\.webhooks\.constructEvent|validateWebhook|verifyWebhook/.test(source)) {
+    effects.add("webhook_ingress");
+  }
+  if (/sendEmail|sendMail\b|mailer\./.test(source) || importSpecs.some((s) => /nodemailer|resend|sendgrid|postmark|mailgun/.test(s)))
+    effects.add("email_send");
+  if (/createCalendarEvent|updateCalendarEvent|deleteCalendarEvent|calendar\.events\.(insert|update|delete|patch)/.test(source)) {
+    effects.add("calendar_mutation");
+  }
+  if (/revalidatePath\b|revalidateTag\b/.test(source))
+    effects.add("cache_revalidation");
+  if (/localStorage\.|sessionStorage\./.test(source))
+    effects.add("local_storage");
+  if (/indexedDB\b|new Dexie|idb\./.test(source))
+    effects.add("indexed_db");
+  if (/\bfetch\s*\(|axios\.(get|post|put|patch|delete)\b/.test(source)) {
+    effects.add("external_api_call");
+  }
+  if (effects.size === 0)
+    effects.add("none_detected");
+  return [...effects];
+}
 async function collectFiles(dir, projectRoot, acc) {
   let entries;
   try {
@@ -580,18 +1074,46 @@ function extractImports(source, lang) {
   }
   return specs;
 }
+var MONOREPO_ALIASES = [
+  { prefix: "~/", replacement: "" },
+  { prefix: "@components/", replacement: "components/" },
+  { prefix: "@lib/", replacement: "lib/" },
+  { prefix: "@server/", replacement: "server/" },
+  { prefix: "@calcom/web/", replacement: "" },
+  { prefix: "@calcom/features/", replacement: "../packages/features/" },
+  { prefix: "@calcom/lib/", replacement: "../packages/lib/" },
+  { prefix: "@calcom/prisma/", replacement: "../packages/prisma/" },
+  { prefix: "@calcom/trpc/", replacement: "../packages/trpc/" },
+  { prefix: "@calcom/ui/", replacement: "../packages/ui/" },
+  { prefix: "@calcom/emails/", replacement: "../packages/emails/" }
+];
+function resolveAlias(spec) {
+  for (const { prefix, replacement } of MONOREPO_ALIASES) {
+    if (spec.startsWith(prefix)) {
+      return replacement + spec.slice(prefix.length);
+    }
+  }
+  return null;
+}
 var JS_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
 function resolveImport(spec, fromAbs, lang, projectRoot, fileSet, basenameIndex) {
   if (lang === "python") {
-    return resolvePython(spec, fromAbs, projectRoot, fileSet);
+    return { resolved: resolvePython(spec, fromAbs, projectRoot, fileSet), isAlias: false };
   }
   if (lang === "typescript" || lang === "tsx" || lang === "javascript") {
-    if (!spec.startsWith("."))
-      return null;
-    const base = join4(dirname(fromAbs), spec);
-    return tryJsCandidates(base, projectRoot, fileSet);
+    if (spec.startsWith(".")) {
+      const base = join4(dirname(fromAbs), spec);
+      return { resolved: tryJsCandidates(base, projectRoot, fileSet), isAlias: false };
+    }
+    const aliasResolved = resolveAlias(spec);
+    if (aliasResolved !== null) {
+      const base = join4(projectRoot, aliasResolved);
+      const resolved = tryJsCandidates(base, projectRoot, fileSet);
+      return { resolved, isAlias: true };
+    }
+    return { resolved: null, isAlias: false };
   }
-  return resolveGeneric(spec, projectRoot, fileSet, basenameIndex);
+  return { resolved: resolveGeneric(spec, projectRoot, fileSet, basenameIndex), isAlias: false };
 }
 function tryJsCandidates(base, projectRoot, fileSet) {
   const candidates = [];
@@ -625,10 +1147,6 @@ function resolvePython(spec, fromAbs, projectRoot, fileSet) {
     if (fileSet.has(rel))
       return rel;
   }
-  if (!spec.startsWith(".")) {
-    const last = spec.split(".").pop();
-    void last;
-  }
   return null;
 }
 function resolveGeneric(spec, projectRoot, fileSet, basenameIndex) {
@@ -806,7 +1324,7 @@ function collectFunctionNodes(root) {
   walk(root);
   return out;
 }
-function catchIsSwallowed(node, lang) {
+function catchIsSwallowed(node, _lang) {
   const bodyText = node.text;
   const inner = bodyText.replace(/^[^{:]*[{:]/, "");
   const meaningful = inner.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("//") && !l.startsWith("#") && l !== "}" && l !== "pass");
@@ -1218,24 +1736,42 @@ async function scanProject(projectRoot) {
     const ast = analyzeAst(source, lang, tree);
     const importSpecs = extractImports(source, lang);
     graph.nodes[rel] = { imports: importSpecs };
-    work.push({ abs: file, rel, lang, source, ast, importSpecs, pathDemote: pathDemoteReason(rel) });
+    const frameworkRole = inferFrameworkRole(rel);
+    const productDomain = inferProductDomain(rel, importSpecs);
+    const sideEffectProfile = inferSideEffectProfile(source, importSpecs);
+    work.push({
+      abs: file,
+      rel,
+      lang,
+      source,
+      ast,
+      importSpecs,
+      pathDemote: pathDemoteReason(rel),
+      frameworkRole,
+      productDomain,
+      sideEffectProfile
+    });
   }
   const importedBy = /* @__PURE__ */ new Map();
   const importsResolved = /* @__PURE__ */ new Map();
+  const importsUnresolved = /* @__PURE__ */ new Map();
   const fanOut = /* @__PURE__ */ new Map();
   for (const w of work) {
     importedBy.set(w.rel, /* @__PURE__ */ new Set());
     importsResolved.set(w.rel, /* @__PURE__ */ new Set());
+    importsUnresolved.set(w.rel, /* @__PURE__ */ new Set());
   }
   for (const w of work) {
     const distinctModules = /* @__PURE__ */ new Set();
     for (const spec of w.importSpecs) {
       distinctModules.add(spec);
-      const target = resolveImport(spec, w.abs, w.lang, projectRoot, fileSet, basenameIndex);
-      if (target && target !== w.rel && importedBy.has(target)) {
-        importedBy.get(target).add(w.rel);
-        importsResolved.get(w.rel).add(target);
-        graph.edges.push({ from: w.rel, to: target });
+      const { resolved, isAlias } = resolveImport(spec, w.abs, w.lang, projectRoot, fileSet, basenameIndex);
+      if (resolved && resolved !== w.rel && importedBy.has(resolved)) {
+        importedBy.get(resolved).add(w.rel);
+        importsResolved.get(w.rel).add(resolved);
+        graph.edges.push({ from: w.rel, to: resolved });
+      } else if (resolved === null && isAlias) {
+        importsUnresolved.get(w.rel).add(spec);
       }
     }
     fanOut.set(w.rel, distinctModules.size);
@@ -1330,7 +1866,10 @@ async function scanProject(projectRoot) {
       gravitySignals,
       heatSignals,
       smells: w.ast.smells,
-      pillarHint
+      pillarHint,
+      frameworkRole: w.frameworkRole,
+      productDomain: w.productDomain,
+      sideEffectProfile: w.sideEffectProfile
     };
     analyses.push(fa);
     persisted[w.rel] = {
@@ -1345,12 +1884,17 @@ async function scanProject(projectRoot) {
       smells: w.ast.smells,
       pillarHint,
       importedBy: [...importedBy.get(w.rel)].filter((src) => isRealSource.get(src)),
-      imports: [...importsResolved.get(w.rel)]
+      imports: [...importsResolved.get(w.rel)],
+      importsUnresolved: [...importsUnresolved.get(w.rel)],
+      frameworkRole: w.frameworkRole,
+      productDomain: w.productDomain,
+      sideEffectProfile: w.sideEffectProfile,
+      hotSpans: w.ast.hotSpans
     };
   }
   const realAnalyses = analyses.filter((a) => a.isRealSource).sort((a, b) => b.gravity - a.gravity);
   const wildCandidates = realAnalyses.filter((a) => a.heat >= 60 || a.smells.some((s) => s.severity >= 4)).sort((a, b) => b.heat - a.heat);
-  const pillars = buildPillars(realAnalyses, communities, stack);
+  const pillars = buildPillars(realAnalyses, persisted, communities, stack);
   const topGravity = realAnalyses.slice(0, 12).map((a) => a.relativePath);
   const topHeat = wildCandidates.slice(0, 12).map((a) => a.relativePath);
   const map = {
@@ -1379,7 +1923,7 @@ async function scanProject(projectRoot) {
     graph
   };
 }
-function buildPillars(real, communities, _stack) {
+function buildPillars(real, persisted, communities, _stack) {
   const keywordGroups = /* @__PURE__ */ new Map();
   const unlabeled = [];
   for (const a of real) {
@@ -1441,15 +1985,29 @@ function buildPillars(real, communities, _stack) {
     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/"))
+        const pf = persisted[f];
+        const role = pf?.frameworkRole || "unknown";
+        const domain = pf?.productDomain || "unknown";
+        let bucket;
+        if (domain !== "unknown" && domain !== "routing_infrastructure" && domain !== "test_infrastructure" && domain !== "generated_noise") {
+          bucket = domainToGroupLabel(domain);
+        } else if (role === "hook") {
+          bucket = "Hooks";
+        } else if ([
+          "app_route_page",
+          "app_route_handler",
+          "app_route_layout",
+          "pages_route",
+          "pages_api_route",
+          "trpc_api_route"
+        ].includes(role)) {
+          bucket = "Routes";
+        } else if (role === "component") {
           bucket = "Components";
-        else if (f.includes("hooks/") || f.includes("lib/") || f.includes("utils/"))
+        } else {
           bucket = "Logic";
-        const d = basename(dirname(f));
-        const key = `${p.name} (${bucket} - ${d})`;
+        }
+        const key = `${p.name} (${bucket})`;
         if (!groups.has(key))
           groups.set(key, []);
         groups.get(key).push(f);
@@ -1478,6 +2036,32 @@ function buildPillars(real, communities, _stack) {
   }
   return finalPillars;
 }
+function domainToGroupLabel(domain) {
+  const labels = {
+    booking_creation: "Booking",
+    booking_management: "Booking",
+    booking_audit: "Booking Audit",
+    event_type_configuration: "Event Types",
+    availability: "Availability",
+    auth: "Auth",
+    auth_oauth: "Auth OAuth",
+    payments: "Payments",
+    payments_webhooks: "Payment Webhooks",
+    webhooks: "Webhooks",
+    apps_marketplace: "Apps",
+    calendar_integrations: "Calendar",
+    video: "Video",
+    onboarding: "Onboarding",
+    settings: "Settings",
+    admin: "Admin",
+    data_table: "Data Table",
+    shell_navigation: "Shell",
+    forms: "Forms",
+    embed: "Embed",
+    notifications: "Notifications"
+  };
+  return labels[domain] || titleCase(domain.replace(/_/g, " "));
+}
 function pillarNameFromCluster(files) {
   const hintCounts = /* @__PURE__ */ new Map();
   for (const f of files) {
@@ -1622,7 +2206,7 @@ function validateMermaidNodeCount(diagram) {
 
 // ../brain/dist/watcher.js
 import chokidar from "chokidar";
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { readFile as readFile6 } from "fs/promises";
 import { join as join6 } from "path";
 function startWatcher(projectRoot, watchedPaths) {
@@ -1637,7 +2221,7 @@ function startWatcher(projectRoot, watchedPaths) {
       if (!dossier)
         return;
       const content = await readFile6(filepath, "utf8");
-      const newHash = createHash("sha256").update(content).digest("hex");
+      const newHash = createHash2("sha256").update(content).digest("hex");
       let mutated = false;
       for (const pillar of dossier.pillars) {
         for (const card of pillar.decisions) {
@@ -1851,7 +2435,7 @@ async function handleGetFileContext(args) {
 
 // dist/mcp/tools/write_decision_card.js
 import { v4 as uuidv4 } from "uuid";
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { readFile as readFile8 } from "fs/promises";
 import { join as join8 } from "path";
 var CATEGORIES = ["Bottleneck", "Hack", "Smart-Move", "Risk", "Convention", "Dead-Weight"];
@@ -1948,7 +2532,7 @@ async function handleWriteDecisionCard(args) {
     primaryContent = await readFile8(join8(projectRoot, primaryFile), "utf8");
   } catch {
   }
-  const hash = createHash2("sha256").update(primaryContent).digest("hex");
+  const hash = createHash3("sha256").update(primaryContent).digest("hex");
   const card = {
     id: uuidv4(),
     pillar,
@@ -2314,7 +2898,7 @@ async function serveCommand() {
 
 // dist/index.js
 var program = new Command();
-program.name("vibe-splain").description("Architectural dossier engine for vibe-coded projects").version("2.3.1");
+program.name("vibe-splain").description("Architectural dossier engine for vibe-coded projects").version("2.4.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/package.json

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