@chappibunny/repolens 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.7.0
+
+### ✨ Features
+
+- **Dependency-weighted module roles**: Module catalog now shows import-based role labels (e.g. "Orchestrator — coordinates 54 modules", "Critical shared infrastructure — imported by 55 modules") derived from real dependency graph metrics.
+- **Context-aware route map**: CLI tools now get a helpful explanation ("This project is a CLI tool — it does not expose HTTP routes") instead of an empty route table with a stale footer.
+- **Verified architecture patterns**: Detected patterns now include confidence labels (e.g. "naming only" vs evidence-backed) based on dependency graph verification.
+- **Import-chain data flows**: Data flows are now traced from real entry points via import chains, replacing hardcoded template flows. Shows actual module dependencies and downstream traces.
+- **CLI-aware tech stack labels**: All 4 key documents (Executive Summary, System Overview, Architecture Overview, Developer Onboarding) now show "N/A (CLI tool)" instead of "Not detected" for Frameworks and Build Tools when the project is a CLI tool.
+- **Test flow filtering**: Test file flows are now filtered from Executive Summary, Data Flows, and Developer Onboarding documents, keeping output focused on production code paths.
+- **Hub flow cleanup**: Integration flows derived from dependency graph hubs no longer list test files as importers in their step chains.
+
+### 🐛 Bug Fixes
+
+- **GraphQL false positives**: The GraphQL analyzer now excludes test files and its own analysis/rendering source files from scanning, preventing self-detection of library patterns (e.g. detecting "Apollo Server" from regex pattern strings).
+- **GraphQL pattern precision**: The `graphql-js` detection pattern now uses word boundaries (`\bGraphQLSchema\b`) to avoid false matches from function names like `renderGraphQLSchema`.
+- **Change impact noise filtering**: Architecture diff now filters `node_modules/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `.repolens/`, and `.git/` from both the Impacted Modules list and the file lists (Added/Removed/Modified).
+- **Zero-value suppression**: Documents no longer show "serves 0 application pages" or "0 API endpoints" for CLI tools — these rows are conditionally hidden when values are zero.
+- **Module label enrichment**: `describeModule()` now recognizes 6 additional module types (plugin, prompt, provider, generate/section, ai/ml), reducing generic "Application module" fallbacks.
+
 ## 1.6.0
 
 ### ✨ Features

package/README.md

@@ -25,7 +25,7 @@ RepoLens scans your repository, generates living architecture documentation, and
 
 > **Try it now** — no installation required. Run `npx @chappibunny/repolens demo` on any repo for an instant local preview.
 
-[![RepoLens Demo](https://img.youtube.com/vi/hNd7xim_rTE/maxresdefault.jpg)](https://youtu.be/hNd7xim_rTE)
+[![RepoLens Demo](https://img.youtube.com/vi/Lpyg0dGsiws/maxresdefault.jpg)](https://youtu.be/Lpyg0dGsiws)
 
 ▶️ *Click to watch on YouTube*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",
@@ -64,10 +64,11 @@
     "js-yaml": "^4.1.0",
     "node-fetch": "^3.3.2"
   },
-  "optionalDependencies": {
-    "@mermaid-js/mermaid-cli": "^11.12.0"
-  },
   "devDependencies": {
+    "tinyexec": "1.0.2",
     "vitest": "^4.0.18"
+  },
+  "overrides": {
+    "yauzl": ">=3.2.1"
   }
 }

package/src/ai/generate-sections.js

@@ -125,6 +125,18 @@ function getFallbackExecutiveSummary(context, enrichment = {}) {
   const languageList = context.techStack.languages.join(", ") || "multiple languages";
   const domainSummary = context.domains.slice(0, 5).map(d => d.name).join(", ");
   const testFrameworks = context.techStack.testFrameworks || [];
+  const isCLI = (context.patterns || []).some(p => p.toLowerCase().includes("cli"));
+
+  // Build the "what it does" line based on project type
+  let interfaceLine;
+  if (isCLI) {
+    interfaceLine = "It operates as a **command-line tool**, interacting through terminal commands rather than a web interface.";
+  } else {
+    const parts = [];
+    if (context.project.apiRoutesDetected > 0) parts.push(`exposes **${context.project.apiRoutesDetected} API endpoint${context.project.apiRoutesDetected === 1 ? "" : "s"}**`);
+    if (context.project.pagesDetected > 0) parts.push(`serves **${context.project.pagesDetected} application page${context.project.pagesDetected === 1 ? "" : "s"}** to end users`);
+    interfaceLine = parts.length > 0 ? `It ${parts.join(" and ")}.` : "";
+  }
 
   let output = `# Executive Summary
 
@@ -132,7 +144,7 @@ function getFallbackExecutiveSummary(context, enrichment = {}) {
 
 ${context.project.name} is a ${frameworkList} application built with ${languageList}. The codebase contains **${context.project.modulesDetected} modules** spread across **${context.project.filesScanned} files**, organized into ${context.domains.length} functional domain${context.domains.length === 1 ? "" : "s"}.
 
-${context.project.apiRoutesDetected > 0 ? `The system exposes **${context.project.apiRoutesDetected} API endpoint${context.project.apiRoutesDetected === 1 ? "" : "s"}** and` : "It"} serves **${context.project.pagesDetected} application page${context.project.pagesDetected === 1 ? "" : "s"}** to end users.
+${interfaceLine}
 
 ## Primary Functional Areas
 
@@ -146,9 +158,9 @@ ${context.domains.map(d => `| ${d.name} | ${d.moduleCount} | ${d.description ||
 
 | Category | Details |
 |----------|---------|
-| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Frameworks | ${context.techStack.frameworks.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 | Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
-| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 ${testFrameworks.length > 0 ? `| Test Frameworks | ${testFrameworks.join(", ")} |\n` : ""}`;
 
   // Module type breakdown
@@ -188,11 +200,12 @@ ${testFrameworks.length > 0 ? `| Test Frameworks | ${testFrameworks.join(", ")}
     }
   }
 
-  // Data flows
-  if (flows && flows.length > 0) {
+  // Data flows (filter out test file flows for exec summary)
+  const summaryFlows = (flows || []).filter(f => !f.name?.toLowerCase().includes('test'));
+  if (summaryFlows.length > 0) {
     output += `\n## Key Data Flows\n\n`;
-    output += `${flows.length} data flow${flows.length === 1 ? "" : "s"} identified:\n\n`;
-    for (const flow of flows) {
+    output += `${summaryFlows.length} data flow${summaryFlows.length === 1 ? "" : "s"} identified:\n\n`;
+    for (const flow of summaryFlows) {
       output += `- **${flow.name}**${flow.critical ? " (critical)" : ""} — ${flow.description}\n`;
     }
   }
@@ -213,6 +226,7 @@ function getFallbackSystemOverview(context, enrichment = {}) {
   const sizeLabel = context.project.modulesDetected > 50 ? "large-scale" :
                     context.project.modulesDetected > 20 ? "medium-sized" : "focused";
   const testFrameworks = context.techStack.testFrameworks || [];
+  const isCLI = (context.patterns || []).some(p => p.toLowerCase().includes("cli"));
 
   let output = `# System Overview
 
@@ -224,16 +238,14 @@ This is a ${sizeLabel} codebase organized into **${context.project.modulesDetect
 |--------|-------|
 | Files scanned | ${context.project.filesScanned} |
 | Modules | ${context.project.modulesDetected} |
-| Application pages | ${context.project.pagesDetected} |
-| API endpoints | ${context.project.apiRoutesDetected} |
-
+${context.project.pagesDetected > 0 ? `| Application pages | ${context.project.pagesDetected} |\n` : ""}${context.project.apiRoutesDetected > 0 ? `| API endpoints | ${context.project.apiRoutesDetected} |\n` : ""}
 ## Technology Stack
 
 | Category | Technologies |
 |----------|-------------|
-| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Frameworks | ${context.techStack.frameworks.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 | Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
-| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 ${testFrameworks.length > 0 ? `| Test Frameworks | ${testFrameworks.join(", ")} |\n` : ""}
 ## Detected Patterns
 
@@ -378,6 +390,7 @@ function getFallbackBusinessDomains(context, enrichment = {}) {
 
 function getFallbackArchitectureOverview(context, enrichment = {}) {
   const { depGraph, driftResult } = enrichment;
+  const isCLI = (context.patterns || []).some(p => p.toLowerCase().includes("cli"));
   const patternDesc = context.patterns.length > 0
     ? `The detected architectural patterns are **${context.patterns.join(", ")}**. These patterns shape how data and control flow through the system.`
     : "No specific architectural patterns were detected. The project appears to follow a straightforward directory-based organization.";
@@ -415,13 +428,13 @@ ${context.domains.slice(0, 8).map(d => `| **${d.name}** | ${d.description || "Ha
 
 | Category | Technologies |
 |----------|-------------|
-| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Frameworks | ${context.techStack.frameworks.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 | Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
-| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 
 ## Scale & Complexity
 
-The repository comprises **${context.project.filesScanned} files** organized into **${context.project.modulesDetected} modules**. ${context.project.apiRoutesDetected > 0 ? `It exposes **${context.project.apiRoutesDetected} API endpoint${context.project.apiRoutesDetected === 1 ? "" : "s"}** and` : "It"} serves **${context.project.pagesDetected} application page${context.project.pagesDetected === 1 ? "" : "s"}**.
+The repository comprises **${context.project.filesScanned} files** organized into **${context.project.modulesDetected} modules**.${context.project.apiRoutesDetected > 0 ? ` It exposes **${context.project.apiRoutesDetected} API endpoint${context.project.apiRoutesDetected === 1 ? "" : "s"}**.` : ""}${context.project.pagesDetected > 0 ? ` It serves **${context.project.pagesDetected} application page${context.project.pagesDetected === 1 ? "" : "s"}**.` : ""}${isCLI ? " It operates as a command-line tool." : ""}
 `;
 
   // Dependency graph health
@@ -502,8 +515,8 @@ function getFallbackDataFlows(flows, context, enrichment = {}) {
   let output = `# Data Flows\n\n`;
   output += `> Data flows describe how information moves through the system — from external inputs through processing layers to storage or presentation.\n\n`;
 
-  // Combine heuristic flows with dep-graph-derived flows
-  const allFlows = [...(flows || [])];
+  // Combine heuristic flows with dep-graph-derived flows, filtering out test file flows
+  const allFlows = [...(flows || [])].filter(f => !f.name?.toLowerCase().includes('test'));
 
   // Generate additional flows from dependency graph hub chains
   if (depGraph?.nodes && depGraph.nodes.length > 0 && allFlows.length < 3) {
@@ -571,6 +584,7 @@ function getFallbackDeveloperOnboarding(context, enrichment = {}) {
   const frameworkList = context.techStack.frameworks.join(", ") || "general-purpose tools";
   const languageList = context.techStack.languages.join(", ") || "standard languages";
   const testFrameworks = context.techStack.testFrameworks || [];
+  const isCLI = (context.patterns || []).some(p => p.toLowerCase().includes("cli"));
   const routes = context.routes || {};
   const pages = routes.pages || [];
   const apis = routes.apis || [];
@@ -604,9 +618,9 @@ ${context.repoRoots.map(root => `| \`${root}\` | ${describeRoot(root)} |`).join(
 
 | Category | Technologies |
 |----------|-------------|
-| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Frameworks | ${context.techStack.frameworks.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 | Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
-| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || (isCLI ? "N/A (CLI tool)" : "Not detected")} |
 ${testFrameworks.length > 0 ? `| Test Frameworks | ${testFrameworks.join(", ")} |\n` : ""}
 ## Largest Modules
 
@@ -637,11 +651,12 @@ ${context.topModules.slice(0, 10).map(m => `| \`${m.key}\` | ${m.fileCount} | ${
     }
   }
 
-  // Data flows overview
-  if (flows && flows.length > 0) {
+  // Data flows overview (filter out test flows)
+  const onboardingFlows = (flows || []).filter(f => !f.name?.toLowerCase().includes('test'));
+  if (onboardingFlows.length > 0) {
     output += `## How Data Flows\n\n`;
     output += `Understanding these flows will help you see how the system works end-to-end:\n\n`;
-    for (const flow of flows) {
+    for (const flow of onboardingFlows) {
       output += `- **${flow.name}** — ${flow.description}\n`;
     }
     output += "\n";
@@ -715,7 +730,8 @@ function inferFlowsFromDepGraph(depGraph) {
     .slice(0, 3);
 
   for (const hub of hubs) {
-    const importers = hub.importedBy.slice(0, 5);
+    const testPattern = /(?:^|\/)(?:tests?|__tests?__|spec|__spec__)\/|\.(test|spec)\.[jt]sx?$/i;
+    const importers = hub.importedBy.filter(i => !testPattern.test(i)).slice(0, 5);
     const downstream = hub.imports.slice(0, 3);
     const shortName = hub.key.split("/").pop();
 
@@ -736,20 +752,31 @@ function inferFlowsFromDepGraph(depGraph) {
 
 function describeRoot(root) {
   const lower = root.toLowerCase().replace(/\/$/, "");
+  // Check the last segment for nested paths like src/core, src/analyzers
+  const lastSeg = lower.split("/").pop();
   if (/^src$|^lib$/.test(lower)) return "Application source code";
-  if (/^test|^__test|^spec/.test(lower)) return "Test suites";
-  if (/^doc/.test(lower)) return "Documentation";
-  if (/^bin$|^scripts?$/.test(lower)) return "CLI entry points and scripts";
-  if (/^config/.test(lower)) return "Configuration files";
-  if (/^public$|^static$|^assets$/.test(lower)) return "Static assets";
-  if (/^dist$|^build$|^out$/.test(lower)) return "Build output";
-  if (/^\.github$/.test(lower)) return "GitHub Actions and workflows";
-  if (/^api$/.test(lower)) return "API definitions";
-  if (/^components?$/.test(lower)) return "Shared UI components";
-  if (/^pages?$|^views?$|^screens?$/.test(lower)) return "Application pages/views";
-  if (/^utils?$|^helpers?$/.test(lower)) return "Utility functions";
-  if (/^services?$/.test(lower)) return "Service layer";
-  if (/^hooks?$/.test(lower)) return "Custom hooks";
+  if (/^test|^__test|^spec/.test(lastSeg)) return "Test suites";
+  if (/^doc/.test(lastSeg)) return "Documentation";
+  if (/^bin$|^scripts?$/.test(lastSeg)) return "CLI entry points and scripts";
+  if (/^config/.test(lastSeg)) return "Configuration files";
+  if (/^public$|^static$|^assets$/.test(lastSeg)) return "Static assets";
+  if (/^dist$|^build$|^out$/.test(lastSeg)) return "Build output";
+  if (/^\.github$/.test(lastSeg)) return "GitHub Actions and workflows";
+  if (/^api$|^endpoint/.test(lastSeg)) return "API definitions";
+  if (/^components?$|^ui$/.test(lastSeg)) return "Shared UI components";
+  if (/^pages?$|^views?$|^screens?$/.test(lastSeg)) return "Application pages/views";
+  if (/^utils?$|^helpers?$/.test(lastSeg)) return "Utility functions";
+  if (/^services?$/.test(lastSeg)) return "Service layer";
+  if (/^hooks?$/.test(lastSeg)) return "Custom hooks";
+  if (/^core$|^kernel$|^engine$/.test(lastSeg)) return "Core logic and foundations";
+  if (/^analyz/.test(lastSeg)) return "Code analysis and detection";
+  if (/^render/.test(lastSeg)) return "Rendering and output formatting";
+  if (/^publish/.test(lastSeg)) return "Publishing and distribution";
+  if (/^deliver/.test(lastSeg)) return "Content delivery";
+  if (/^integrat/.test(lastSeg)) return "Third-party integrations";
+  if (/^plugin/.test(lastSeg)) return "Plugin and extension system";
+  if (/^ai$|^ml$|^llm$/.test(lastSeg)) return "AI/ML features and providers";
+  if (/^middleware/.test(lastSeg)) return "Middleware pipeline";
   return "Project files";
 }
 

package/src/analyzers/context-builder.js

@@ -2,7 +2,83 @@
 
 import { groupModulesByDomain } from "./domain-inference.js";
 
-export function buildAIContext(scanResult, config) {
+/**
+ * Compute per-module dependency metrics from the dep graph.
+ * Returns a Map<normalizedKey, { fanIn, fanOut, isHub, isOrphan, isLeaf, isOrchestrator }>.
+ */
+export function computeModuleDepMetrics(depGraph) {
+  const metrics = new Map();
+  if (!depGraph?.nodes) return metrics;
+
+  const hubThreshold = Math.max(3, Math.floor(depGraph.nodes.length * 0.05));
+
+  for (const node of depGraph.nodes) {
+    const fanIn = node.importedBy.length;
+    const fanOut = node.imports.length;
+    metrics.set(node.key, {
+      fanIn,
+      fanOut,
+      isHub: fanIn >= hubThreshold,
+      isOrphan: fanIn === 0 && fanOut === 0,
+      isLeaf: fanOut === 0 && fanIn > 0,
+      isOrchestrator: fanOut >= 5 && fanIn < fanOut,
+    });
+  }
+  return metrics;
+}
+
+/**
+ * Build a module-level dep metrics map (aggregating file-level metrics).
+ * moduleKey → { fanIn, fanOut, isHub, isOrphan, isLeaf, isOrchestrator }
+ */
+export function computeModuleLevelMetrics(depGraph, modules) {
+  const fileMetrics = computeModuleDepMetrics(depGraph);
+  if (fileMetrics.size === 0 || !modules) return new Map();
+
+  const moduleLevelMap = new Map();
+
+  for (const mod of modules) {
+    const moduleKey = mod.key;
+    const lowerKey = moduleKey.toLowerCase();
+
+    // Find all file-level nodes that belong to this module
+    let totalFanIn = 0;
+    let totalFanOut = 0;
+    let fileCount = 0;
+
+    for (const [nodeKey, m] of fileMetrics) {
+      if (nodeKey === lowerKey || nodeKey.startsWith(lowerKey + "/") || nodeKey === moduleKey || nodeKey.startsWith(moduleKey + "/")) {
+        // Count only external edges (crossing module boundary)
+        if (depGraph?.nodes) {
+          const node = depGraph.nodes.find(n => n.key === nodeKey);
+          if (node) {
+            const externalIn = node.importedBy.filter(imp => !imp.startsWith(moduleKey + "/") && imp !== moduleKey).length;
+            const externalOut = node.imports.filter(imp => !imp.startsWith(moduleKey + "/") && imp !== moduleKey).length;
+            totalFanIn += externalIn;
+            totalFanOut += externalOut;
+            fileCount++;
+          }
+        }
+      }
+    }
+
+    if (fileCount > 0) {
+      const hubThreshold = Math.max(5, Math.floor(modules.length * 0.15));
+      moduleLevelMap.set(moduleKey, {
+        fanIn: totalFanIn,
+        fanOut: totalFanOut,
+        isHub: totalFanIn >= hubThreshold,
+        isOrphan: totalFanIn === 0 && totalFanOut === 0,
+        isLeaf: totalFanOut === 0 && totalFanIn > 0,
+        isOrchestrator: totalFanOut >= 5 && totalFanIn < totalFanOut,
+      });
+    }
+  }
+
+  return moduleLevelMap;
+}
+
+export function buildAIContext(scanResult, config, depGraph = null) {
   const { filesCount, modules, api, pages, metadata } = scanResult;
   
   // Get domain hints from config if available
@@ -17,13 +93,17 @@ export function buildAIContext(scanResult, config) {
   // Group modules by business domain
   const domainGroups = groupModulesByDomain(modules, customHints);
   
-  // Identify top modules
+  // Compute module-level dependency metrics
+  const moduleMetrics = computeModuleLevelMetrics(depGraph, modules);
+  
+  // Identify top modules with enriched types
   const topModules = modules
     .slice(0, 15)
     .map(m => ({
       key: m.key,
       fileCount: m.fileCount,
-      type: inferModuleType(m.key)
+      type: inferModuleType(m.key),
+      depRole: describeModuleDepRole(m.key, moduleMetrics),
     }));
   
   // Categorize routes
@@ -48,8 +128,8 @@ export function buildAIContext(scanResult, config) {
     testFrameworks: metadata?.testFrameworks || []
   };
   
-  // Identify key architectural patterns
-  const patterns = inferArchitecturalPatterns(modules);
+  // Identify key architectural patterns (verified against dep graph when available)
+  const patterns = inferArchitecturalPatterns(modules, depGraph);
   
   // Build compact context object
   return {
@@ -97,39 +177,155 @@ export function buildAIContext(scanResult, config) {
 function inferModuleType(modulePath) {
   const lower = modulePath.toLowerCase();
   
-  if (lower.includes("api")) return "api";
-  if (lower.includes("component")) return "ui";
-  if (lower.includes("lib") || lower.includes("util")) return "library";
+  if (lower.includes("test") || lower.includes("spec") || lower.includes("__test")) return "test";
+  if (lower.includes("api") || lower.includes("endpoint")) return "api";
+  if (lower.includes("component") || lower.includes("widget")) return "ui";
+  if (lower.includes("lib") || lower.includes("util") || lower.includes("helper") || lower.includes("common") || lower.includes("shared")) return "library";
   if (lower.includes("hook")) return "hooks";
-  if (lower.includes("store") || lower.includes("state")) return "state";
-  if (lower.includes("page") || lower.includes("route")) return "route";
+  if (lower.includes("store") || lower.includes("state") || lower.includes("redux") || lower.includes("zustand")) return "state";
+  if (lower.includes("page") || lower.includes("route") || lower.includes("view")) return "route";
+  if (lower.includes("config") || lower.includes("setting") || lower.includes("env")) return "config";
+  if (lower.includes("core") || lower.includes("kernel") || lower.includes("foundation")) return "core";
+  if (lower.includes("render") || lower.includes("template") || lower.includes("format")) return "renderer";
+  if (lower.includes("publish") || lower.includes("output") || lower.includes("export")) return "publisher";
+  if (lower.includes("analyz") || lower.includes("inspect") || lower.includes("detect")) return "analyzer";
+  if (lower.includes("plugin") || lower.includes("extension") || lower.includes("addon")) return "plugin";
+  if (lower.includes("deliver") || lower.includes("dispatch") || lower.includes("send")) return "delivery";
+  if (lower.includes("doc") || lower.includes("generate")) return "documentation";
+  if (lower.includes("integrat") || lower.includes("connect") || lower.includes("adapter")) return "integration";
+  if (lower.includes("cli") || lower.includes("command") || lower.includes("bin")) return "cli";
+  if (lower.includes("ai") || lower.includes("ml") || lower.includes("model") || lower.includes("prompt")) return "ai";
+  if (lower.includes("auth") || lower.includes("login") || lower.includes("session")) return "auth";
+  if (lower.includes("data") || lower.includes("db") || lower.includes("model") || lower.includes("schema")) return "data";
+  if (lower.includes("middleware")) return "middleware";
+  if (lower.includes("service")) return "service";
   if (lower.includes("app")) return "app";
   
   return "other";
 }
 
-function inferArchitecturalPatterns(modules) {
+function inferArchitecturalPatterns(modules, depGraph = null) {
   const patterns = [];
+  const keys = modules.map(m => m.key.toLowerCase());
   
-  const hasAppRouter = modules.some(m => m.key.includes("app/"));
-  const hasPagesRouter = modules.some(m => m.key.includes("pages/"));
-  const hasComponents = modules.some(m => m.key.includes("component"));
-  const hasLib = modules.some(m => m.key.includes("lib"));
-  const hasHooks = modules.some(m => m.key.includes("hook"));
-  const hasStore = modules.some(m => m.key.includes("store") || m.key.includes("state"));
-  const hasApi = modules.some(m => m.key.includes("api"));
-  
-  if (hasAppRouter) patterns.push("Next.js App Router");
-  if (hasPagesRouter) patterns.push("Next.js Pages Router");
-  if (hasComponents && hasLib) patterns.push("Layered component architecture");
-  if (hasHooks) patterns.push("React hooks pattern");
-  if (hasStore) patterns.push("Centralized state management");
-  if (hasApi) patterns.push("API route pattern");
+  const has = (keyword) => keys.some(k => k.includes(keyword));
+
+  // Compute module-level metrics for verification
+  const moduleMetrics = depGraph ? computeModuleLevelMetrics(depGraph, modules) : new Map();
+  const hasCycles = depGraph?.cycles?.length > 0;
   
+  // Verify pattern: a module matching `keyword` has high fan-in (truly central)
+  const verifyHub = (keyword) => {
+    for (const [mKey, m] of moduleMetrics) {
+      if (mKey.toLowerCase().includes(keyword) && m.fanIn >= 3) return true;
+    }
+    return false;
+  };
+
+  // Verify pattern: modules matching keyword have mostly outbound deps (orchestrators)
+  const verifyOrchestrator = (keyword) => {
+    for (const [mKey, m] of moduleMetrics) {
+      if (mKey.toLowerCase().includes(keyword) && m.fanOut >= 3) return true;
+    }
+    return false;
+  };
+  
+  // Web framework patterns
+  if (has("app/")) patterns.push("Next.js App Router");
+  if (has("pages/")) patterns.push("Next.js Pages Router");
+  if (has("component") && has("lib")) patterns.push("Layered component architecture");
+  if (has("hook")) patterns.push("React hooks pattern");
+  if (has("store") || has("state") || has("redux") || has("zustand")) patterns.push("Centralized state management");
+  
+  // General patterns — verified against dep graph when available
+  if (has("api") || has("endpoint")) patterns.push("API route pattern");
+
+  if (has("core") || has("kernel")) {
+    if (moduleMetrics.size > 0 && verifyHub("core")) {
+      patterns.push("Core/kernel architecture (verified — high fan-in)");
+    } else if (moduleMetrics.size > 0) {
+      patterns.push("Core/kernel architecture (naming only)");
+    } else {
+      patterns.push("Core/kernel architecture");
+    }
+  }
+
+  if (has("plugin") || has("extension")) {
+    if (moduleMetrics.size > 0 && (verifyHub("plugin") || verifyOrchestrator("plugin") || verifyHub("loader"))) {
+      patterns.push("Plugin system (verified — loader/registry detected)");
+    } else if (moduleMetrics.size > 0) {
+      patterns.push("Plugin system (naming only)");
+    } else {
+      patterns.push("Plugin system");
+    }
+  }
+
+  if (has("middleware")) patterns.push("Middleware pipeline");
+
+  if (has("render") || has("template")) {
+    if (moduleMetrics.size > 0 && verifyOrchestrator("render")) {
+      patterns.push("Renderer pipeline (verified — multi-output)");
+    } else {
+      patterns.push("Renderer pipeline");
+    }
+  }
+
+  if (has("publish") || has("output")) {
+    if (moduleMetrics.size > 0 && verifyOrchestrator("publish")) {
+      patterns.push("Multi-output publishing (verified — multiple targets)");
+    } else {
+      patterns.push("Multi-output publishing");
+    }
+  }
+
+  if (has("analyz") || has("detect") || has("inspect")) patterns.push("Analysis pipeline");
+  if (has("cli") || has("command") || has("bin")) patterns.push("CLI tool architecture");
+  
+  if (has("util") || has("helper") || has("lib")) {
+    if (moduleMetrics.size > 0 && verifyHub("util") || verifyHub("helper") || verifyHub("lib")) {
+      patterns.push("Shared utility layer (verified — high fan-in)");
+    } else {
+      patterns.push("Shared utility layer");
+    }
+  }
+  
+  if (has("integrat") || has("adapter") || has("connect")) patterns.push("Integration adapters");
+  if (has("ai") || has("prompt") || has("provider")) patterns.push("AI/LLM integration");
+  if (has("deliver") || has("dispatch")) patterns.push("Delivery pipeline");
+  if (has("test") || has("spec")) patterns.push("Dedicated test infrastructure");
+
+  // Structural patterns from dep graph (not keyword-based)
+  if (depGraph?.stats) {
+    if (depGraph.stats.cycles === 0 && depGraph.stats.totalEdges > 10) {
+      patterns.push("Acyclic dependency graph — clean layering");
+    }
+    if (hasCycles) {
+      patterns.push(`⚠️ ${depGraph.stats.cycles} circular dependency cycle(s) detected`);
+    }
+  }
+
   return patterns;
 }
 
-export function buildModuleContext(modules, config) {
+/**
+ * Generate a dependency-aware role description for a module.
+ */
+function describeModuleDepRole(moduleKey, moduleMetrics) {
+  const m = moduleMetrics.get(moduleKey);
+  if (!m) return null;
+
+  if (m.isOrphan) return "Isolated (no imports or importers)";
+  if (m.isHub && m.fanIn >= 15) return `Critical shared infrastructure (imported by ${m.fanIn} modules)`;
+  if (m.isHub) return `Shared infrastructure (imported by ${m.fanIn} modules)`;
+  if (m.isOrchestrator) return `Orchestrator (coordinates ${m.fanOut} modules)`;
+  if (m.isLeaf) return `Leaf module (consumed only, ${m.fanIn} importer${m.fanIn === 1 ? "" : "s"})`;
+  if (m.fanIn > 0 && m.fanOut > 0) return `Connector (${m.fanIn} in, ${m.fanOut} out)`;
+  return null;
+}
+
+export { describeModuleDepRole };
+
+export function buildModuleContext(modules, config, depGraph = null) {
   const customHints = config.domains 
     ? Object.entries(config.domains).map(([key, domain]) => ({
         match: domain.match || [],
@@ -139,6 +335,7 @@ export function buildModuleContext(modules, config) {
     : [];
   
   const domainGroups = groupModulesByDomain(modules, customHints);
+  const moduleMetrics = computeModuleLevelMetrics(depGraph, modules);
   
   return modules.map(module => {
     const domain = domainGroups.find(d => 
@@ -149,6 +346,7 @@ export function buildModuleContext(modules, config) {
       key: module.key,
       fileCount: module.fileCount,
       type: inferModuleType(module.key),
+      depRole: describeModuleDepRole(module.key, moduleMetrics),
       domain: domain?.name || "Other",
       domainDescription: domain?.description || "Uncategorized"
     };

package/src/analyzers/domain-inference.js

@@ -32,7 +32,7 @@ const DEFAULT_DOMAIN_HINTS = [
     description: "Payment processing and subscription management"
   },
   { 
-    match: ["api", "endpoint", "route", "handler", "controller", "middleware"], 
+    match: ["api", "endpoint", "handler", "controller", "middleware"], 
     domain: "API Layer",
     description: "Backend API endpoints and request handling"
   },
@@ -75,6 +75,61 @@ const DEFAULT_DOMAIN_HINTS = [
     match: ["job", "queue", "worker", "cron", "task", "scheduler", "background"],
     domain: "Background Jobs",
     description: "Background processing, job queues, and scheduled tasks"
+  },
+  {
+    match: ["core", "kernel", "foundation", "engine"],
+    domain: "Core Engine",
+    description: "Core business logic and foundational modules"
+  },
+  {
+    match: ["render", "template", "format", "output"],
+    domain: "Rendering & Output",
+    description: "Content rendering, formatting, and output generation"
+  },
+  {
+    match: ["publish", "deploy", "release", "distribute"],
+    domain: "Publishing & Delivery",
+    description: "Content and artifact publishing, deployment, and distribution"
+  },
+  {
+    match: ["analyz", "inspect", "detect", "lint", "scan", "parse"],
+    domain: "Analysis & Detection",
+    description: "Code analysis, pattern detection, and static inspection"
+  },
+  {
+    match: ["plugin", "extension", "addon", "module"],
+    domain: "Plugin System",
+    description: "Extensibility framework, plugins, and add-ons"
+  },
+  {
+    match: ["deliver", "dispatch", "send", "transport"],
+    domain: "Delivery",
+    description: "Content delivery and distribution channels"
+  },
+  {
+    match: ["doc", "generate", "markdown", "readme"],
+    domain: "Documentation",
+    description: "Documentation generation and management"
+  },
+  {
+    match: ["integrat", "connect", "adapter", "bridge", "gateway"],
+    domain: "Integrations",
+    description: "Third-party service integrations and adapters"
+  },
+  {
+    match: ["cli", "command", "bin", "terminal", "shell", "prompt"],
+    domain: "CLI & Commands",
+    description: "Command-line interface and terminal commands"
+  },
+  {
+    match: ["ai", "ml", "llm", "gpt", "openai", "anthropic", "gemini"],
+    domain: "AI & Machine Learning",
+    description: "AI/ML integration, LLM providers, and intelligent features"
+  },
+  {
+    match: ["service", "provider", "client", "sdk"],
+    domain: "Services",
+    description: "Service layer, providers, and external client SDKs"
   }
 ];