@chappibunny/repolens 1.6.1 → 1.7.1

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.7.1
+
+### 🛡️ AI Output Guardrails
+
+- **System prompt hardening**: Added anti-conversational rules — AI now instructed to never offer additional work, never ask questions, never use second-person address (except onboarding), and to back every claim with context evidence.
+- **Evidence-only constraints**: Architecture weaknesses, exec summary risks, and onboarding complexity hotspots now require concrete evidence from context data (cycle counts, coupling metrics, orphan files). No speculation.
+- **Output sanitizer**: New `sanitizeAIOutput()` strips conversational patterns (`"If you want"`, `"I can produce"`, `"Shall I"`, `"Let me know"`) from both structured JSON and plain-text AI responses before they reach documents.
+- **Structured renderer sanitization**: `renderArchitectureOverviewJSON` now sanitizes weakness bullet items, removing conversational lines even if they survive prompt-level constraints.
+- **Dual-path coverage**: Sanitization applies to both structured JSON mode (Path A) and plain-text fallback (Path B), closing all AI output paths.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",
@@ -67,5 +67,8 @@
   "devDependencies": {
     "tinyexec": "1.0.2",
     "vitest": "^4.0.18"
+  },
+  "overrides": {
+    "yauzl": ">=3.2.1"
   }
 }

package/src/ai/generate-sections.js

@@ -18,6 +18,27 @@ import {
 import { identifyFlowDependencies } from "../analyzers/flow-inference.js";
 import { info, warn } from "../utils/logger.js";
 
+// Strip conversational patterns that LLMs sometimes inject into documentation
+const CONVERSATIONAL_PATTERNS = [
+  /^(?:[-*]\s*)?if you (?:want|need|would like|prefer)[^.\n]*[.\n]/gmi,
+  /^(?:[-*]\s*)?(?:shall|should) I [^.\n]*[.\n]/gmi,
+  /^(?:[-*]\s*)?(?:let me know|feel free)[^.\n]*[.\n]/gmi,
+  /^(?:[-*]\s*)?I can (?:also |additionally )?(?:produce|create|generate|help|provide|suggest|recommend)[^.\n]*[.\n]/gmi,
+  /^(?:[-*]\s*)?(?:would you like|do you want)[^.\n]*[.\n]/gmi,
+  /^(?:[-*]\s*)?(?:here is|here's) (?:a |the )?(?:summary|overview|breakdown)[^.\n]*:\s*$/gmi,
+];
+
+function sanitizeAIOutput(text) {
+  if (!text || typeof text !== "string") return text;
+  let cleaned = text;
+  for (const pattern of CONVERSATIONAL_PATTERNS) {
+    cleaned = cleaned.replace(pattern, "");
+  }
+  // Collapse multiple blank lines left by removals
+  cleaned = cleaned.replace(/\n{3,}/g, "\n\n").trim();
+  return cleaned;
+}
+
 /**
  * Try structured JSON mode first, fall back to plain-text AI, then deterministic.
  */
@@ -41,7 +62,7 @@ async function generateWithStructuredFallback(key, promptText, maxTokens, fallba
 
     if (result.success && result.parsed) {
       const md = renderStructuredToMarkdown(key, result.parsed);
-      if (md) return md;
+      if (md) return sanitizeAIOutput(md);
     }
     // If structured mode failed, fall through to plain-text
     warn(`Structured AI failed for ${key}, trying plain-text mode...`);
@@ -60,7 +81,7 @@ async function generateWithStructuredFallback(key, promptText, maxTokens, fallba
     return fallbackFn();
   }
 
-  return result.text;
+  return sanitizeAIOutput(result.text);
 }
 
 export async function generateExecutiveSummary(context, enrichment = {}) {
@@ -125,6 +146,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 +165,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 +179,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 +221,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 +247,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 +259,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 +411,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 +449,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 +536,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 +605,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 +639,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 +672,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 +751,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();
 

package/src/ai/prompts.js

@@ -57,7 +57,12 @@ Rules:
 - Do not mention AI, LLMs, or that you are an assistant.
 - No markdown tables unless specifically requested.
 - Use simple formatting: headings, paragraphs, lists.
-- Maximum 2 heading levels deep within sections.`;
+- Maximum 2 heading levels deep within sections.
+- You are producing a static document, not participating in a conversation.
+- Never offer to do additional work (no "If you want", "I can also", "Let me know", "Shall I").
+- Never ask the reader questions or invite follow-up.
+- Never address the reader in second person ("you") unless the document type requires it (e.g. onboarding).
+- Every claim must be supported by concrete evidence from the supplied context data.`;
 
 export function createExecutiveSummaryPrompt(context) {
   return `Write an executive summary for a mixed audience of technical and non-technical readers.
@@ -70,7 +75,7 @@ Requirements:
 - Explain the main system areas using the domain information.
 - Explain the business capabilities implied by the codebase structure.
 - Mention key external dependencies only if they are present in the context.
-- Mention architectural or operational risks if they are strongly supported by the context.
+- Mention architectural or operational risks only if they are directly supported by concrete data in the context (e.g. cycle counts, orphan files, coupling metrics).
 - Do not mention file counts more than once.
 - Maximum 500 words.
 - Use this structure:
@@ -89,7 +94,9 @@ Requirements:
 
 ## Operational and architectural risks
 
-## Recommended focus areas`;
+## Recommended focus areas
+
+IMPORTANT: Only list risks and focus areas that are directly evidenced by the context data. Do not speculate.`;
 }
 
 export function createSystemOverviewPrompt(context) {
@@ -183,7 +190,9 @@ Requirements:
 
 ## Architectural strengths
 
-## Architectural weaknesses`;
+## Architectural weaknesses
+
+IMPORTANT: Only list weaknesses that are directly evidenced by the context data (e.g. cycle counts, orphan files, high coupling metrics, missing layers). Do not speculate about what the system lacks.`;
 }
 
 export function createDataFlowsPrompt(flows, context) {
@@ -249,7 +258,9 @@ Requirements:
 
 ## What to understand first
 
-## Known complexity hotspots`;
+## Known complexity hotspots
+
+IMPORTANT: Only cite complexity hotspots that are supported by concrete evidence in the context (e.g. high import counts, circular dependencies, large file counts). Do not speculate about what might be complex.`;
 }
 
 export function createModuleSummaryPrompt(module, context) {
@@ -520,12 +531,22 @@ function renderBusinessDomainsJSON(d) {
   return md;
 }
 
+function sanitizeBulletList(val) {
+  const raw = toBulletList(val);
+  if (!raw) return raw;
+  // Strip conversational lines from bullet lists
+  return raw.split("\n").filter(line => {
+    const lower = line.toLowerCase();
+    return !/(^|\s)(if you (?:want|need|would)|shall i |let me know|i can (?:also )?(?:produce|create|generate|help)|would you like|do you want|feel free)/i.test(lower);
+  }).join("\n");
+}
+
 function renderArchitectureOverviewJSON(d) {
   let md = `# Architecture Overview\n\n`;
   md += `## Architecture Style\n\n${safeStr(d.style)}\n\n`;
   md += `## Layers\n\n${toHeadingSections(d.layers)}\n\n`;
-  md += `## Architectural Strengths\n\n${toBulletList(d.strengths)}\n\n`;
-  md += `## Architectural Weaknesses\n\n${toBulletList(d.weaknesses)}\n`;
+  md += `## Architectural Strengths\n\n${sanitizeBulletList(d.strengths)}\n\n`;
+  md += `## Architectural Weaknesses\n\n${sanitizeBulletList(d.weaknesses)}\n`;
   return md;
 }
 

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 {
@@ -124,11 +204,31 @@ function inferModuleType(modulePath) {
   return "other";
 }
 
-function inferArchitecturalPatterns(modules) {
+function inferArchitecturalPatterns(modules, depGraph = null) {
   const patterns = [];
   const keys = modules.map(m => m.key.toLowerCase());
   
   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");
@@ -137,25 +237,95 @@ function inferArchitecturalPatterns(modules) {
   if (has("hook")) patterns.push("React hooks pattern");
   if (has("store") || has("state") || has("redux") || has("zustand")) patterns.push("Centralized state management");
   
-  // General patterns
+  // General patterns — verified against dep graph when available
   if (has("api") || has("endpoint")) patterns.push("API route pattern");
-  if (has("core") || has("kernel")) patterns.push("Core/kernel architecture");
-  if (has("plugin") || has("extension")) patterns.push("Plugin system");
+
+  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")) patterns.push("Renderer pipeline");
-  if (has("publish") || has("output")) patterns.push("Multi-output publishing");
+
+  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")) patterns.push("Shared utility layer");
+  
+  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 || [],
@@ -165,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 => 
@@ -175,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/flow-inference.js

@@ -1,27 +1,134 @@
-// Infer data flows through the application using heuristics
+// Infer data flows through the application using import graph analysis + heuristics
 
-export function inferDataFlows(scanResult, config) {
+/**
+ * Primary flow inference: uses dep graph when available for real import-chain flows,
+ * falls back to keyword heuristics for repos without dep graph data.
+ */
+export function inferDataFlows(scanResult, config, depGraph = null) {
   const flows = [];
   
-  // Stock/Market Data Flow (if applicable)
+  // If we have dep graph data, build real import-chain flows from entry points
+  if (depGraph?.nodes && depGraph.nodes.length > 0) {
+    const entryFlows = inferFlowsFromEntryPoints(scanResult, depGraph);
+    flows.push(...entryFlows);
+  }
+
+  // Keyword-based heuristic flows (only add if not already covered by import-chain analysis)
+  const existingNames = new Set(flows.map(f => f.name.toLowerCase()));
+
   const marketFlow = inferMarketDataFlow(scanResult);
-  if (marketFlow) flows.push(marketFlow);
+  if (marketFlow && !existingNames.has(marketFlow.name.toLowerCase())) flows.push(marketFlow);
   
-  // Authentication Flow
   const authFlow = inferAuthFlow(scanResult);
-  if (authFlow) flows.push(authFlow);
+  if (authFlow && !existingNames.has(authFlow.name.toLowerCase())) flows.push(authFlow);
   
-  // Content/Article Flow
   const contentFlow = inferContentFlow(scanResult);
-  if (contentFlow) flows.push(contentFlow);
+  if (contentFlow && !existingNames.has(contentFlow.name.toLowerCase())) flows.push(contentFlow);
   
-  // API Integration Flow
   const apiFlow = inferApiIntegrationFlow(scanResult);
-  if (apiFlow) flows.push(apiFlow);
+  if (apiFlow && !existingNames.has(apiFlow.name.toLowerCase())) flows.push(apiFlow);
   
   return flows;
 }
 
+/**
+ * Trace real import chains from entry points through the dep graph.
+ * Entry points: CLI/bin files, page components, API route handlers, index files.
+ */
+function inferFlowsFromEntryPoints(scanResult, depGraph) {
+  const flows = [];
+  if (!depGraph?.nodes) return flows;
+
+  // Find entry points (files with high fan-out and low/zero fan-in)
+  const entryPoints = depGraph.nodes.filter(n => {
+    const key = n.key.toLowerCase();
+    const isEntry = (
+      key.includes("bin/") || 
+      key.includes("cli") ||
+      key.endsWith("/index") ||
+      key.includes("pages/") ||
+      key.includes("app/") ||
+      (n.importedBy.length === 0 && n.imports.length >= 2) // True entry: nothing imports it
+    );
+    return isEntry && n.imports.length >= 2;
+  }).sort((a, b) => {
+    // Prioritize src/ entry points over tests/
+    const aIsTest = a.key.toLowerCase().includes("test");
+    const bIsTest = b.key.toLowerCase().includes("test");
+    if (aIsTest !== bIsTest) return aIsTest ? 1 : -1;
+    return b.imports.length - a.imports.length;
+  });
+
+  // Limit: all src entries + max 2 test entries
+  const srcEntries = entryPoints.filter(n => !n.key.toLowerCase().includes("test"));
+  const testEntries = entryPoints.filter(n => n.key.toLowerCase().includes("test")).slice(0, 2);
+  const selectedEntries = [...srcEntries, ...testEntries].slice(0, 5);
+
+  for (const entry of selectedEntries) {
+    const chain = traceImportChain(entry.key, depGraph, 6);
+    if (chain.length < 2) continue;
+
+    const shortName = entry.key.split("/").pop();
+    const isCliEntry = entry.key.toLowerCase().includes("cli") || entry.key.toLowerCase().includes("bin/");
+    const flowType = isCliEntry ? "Command" : "Request";
+    
+    // Classify each step in the chain
+    const steps = chain.map((nodeKey, i) => {
+      const node = depGraph.nodes.find(n => n.key === nodeKey);
+      const name = nodeKey.split("/").pop();
+      const fanIn = node?.importedBy?.length || 0;
+      const fanOut = node?.imports?.length || 0;
+      
+      if (i === 0) return `\`${name}\` (entry point, imports ${fanOut} modules)`;
+      if (fanIn >= 5) return `\`${name}\` (shared infrastructure, used by ${fanIn} files)`;
+      if (fanOut === 0) return `\`${name}\` (leaf — no further dependencies)`;
+      return `\`${name}\` → imports ${fanOut} module${fanOut === 1 ? "" : "s"}`;
+    });
+
+    flows.push({
+      name: `${shortName} ${flowType} Flow`,
+      description: `Import chain starting from \`${entry.key}\` — traces how this entry point depends on ${chain.length - 1} downstream module${chain.length - 1 === 1 ? "" : "s"}`,
+      steps,
+      modules: chain.slice(0, 8),
+      critical: entry.imports.length >= 5,
+    });
+  }
+
+  return flows;
+}
+
+/**
+ * Trace from an entry node through the dep graph via BFS, following highest-fan-out paths.
+ * Returns an ordered chain of module keys representing the primary dependency path.
+ */
+function traceImportChain(startKey, depGraph, maxDepth = 6) {
+  const chain = [startKey];
+  const visited = new Set([startKey]);
+  let current = startKey;
+
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const node = depGraph.nodes.find(n => n.key === current);
+    if (!node || node.imports.length === 0) break;
+
+    // Follow the most-imported (highest fan-in) dependency first — it's the most interesting path
+    const candidates = node.imports
+      .filter(imp => !visited.has(imp))
+      .map(imp => {
+        const target = depGraph.nodes.find(n => n.key === imp);
+        return { key: imp, fanIn: target?.importedBy?.length || 0 };
+      })
+      .sort((a, b) => b.fanIn - a.fanIn);
+
+    if (candidates.length === 0) break;
+
+    current = candidates[0].key;
+    visited.add(current);
+    chain.push(current);
+  }
+
+  return chain;
+}
+
 function inferMarketDataFlow(scanResult) {
   const { modules, pages, api } = scanResult;
   

package/src/analyzers/graphql-analyzer.js

@@ -31,7 +31,7 @@ const SCHEMA_LIBRARY_PATTERNS = [
   { name: "Apollo Server", pattern: /ApolloServer|@apollo\/server|apollo-server/ },
   { name: "GraphQL Yoga", pattern: /graphql-yoga|createYoga/ },
   { name: "Mercurius", pattern: /mercurius/ },
-  { name: "graphql-js", pattern: /graphql\b.*buildSchema|GraphQLSchema|GraphQLObjectType/ },
+  { name: "graphql-js", pattern: /graphql\b.*\bbuildSchema\b|\bGraphQLSchema\b|\bGraphQLObjectType\b/ },
   { name: "type-graphql", pattern: /type-graphql|@Resolver|@Query|@Mutation/ },
   { name: "Nexus", pattern: /nexus|makeSchema|objectType\(/ },
   { name: "Pothos", pattern: /pothos|SchemaBuilder/ },
@@ -84,8 +84,13 @@ export async function analyzeGraphQL(files, repoRoot) {
   const schemaFiles = files.filter(f => GRAPHQL_EXTENSIONS.some(ext => f.endsWith(ext)));
 
   // Phase 2: Find JS/TS files with inline schema or resolvers
+  // Exclude test files and our own analysis/rendering files (they reference library names as strings, not usage)
+  const testPattern = /(?:^|\/)(?:tests?|__tests?__|spec|__spec__)\/|\.(test|spec)\.[jt]sx?$/i;
+  const selfPatterns = ["graphql-analyzer.js", "renderAnalysis.js"];
   const codeFiles = files.filter(f =>
-    f.endsWith(".js") || f.endsWith(".ts") || f.endsWith(".jsx") || f.endsWith(".tsx")
+    (f.endsWith(".js") || f.endsWith(".ts") || f.endsWith(".jsx") || f.endsWith(".tsx")) &&
+    !testPattern.test(f) &&
+    !selfPatterns.some(s => f.endsWith(s))
   );
 
   // Parse .graphql/.gql files

package/src/docs/generate-doc-set.js

@@ -33,10 +33,10 @@ import path from "node:path";
 export async function generateDocumentSet(scanResult, config, diffData = null, pluginManager = null) {
   info("Building structured context for AI...");
   
-  // Build AI context from scan results
-  const aiContext = buildAIContext(scanResult, config);
-  const moduleContext = buildModuleContext(scanResult.modules, config);
-  const flows = inferDataFlows(scanResult, config);
+  // Build AI context from scan results (dep graph computed later, patched in after)
+  let aiContext = buildAIContext(scanResult, config);
+  let moduleContext = buildModuleContext(scanResult.modules, config);
+  let flows = inferDataFlows(scanResult, config);
   
   // Run extended analysis (v0.8.0)
   const repoRoot = config.__repoRoot || process.cwd();
@@ -63,6 +63,11 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
     await saveBaseline(snapshot, outputDir);
   } catch (e) { warn(`Drift detection failed: ${e.message}`); }
 
+  // Rebuild AI context with dep graph for enriched module roles and pattern verification
+  aiContext = buildAIContext(scanResult, config, depGraph);
+  moduleContext = buildModuleContext(scanResult.modules, config, depGraph);
+  flows = inferDataFlows(scanResult, config, depGraph);
+
   // CODEOWNERS integration
   const codeowners = await parseCodeowners(repoRoot);
   const ownershipMap = codeowners.found
@@ -196,19 +201,19 @@ async function generateDocument(docPlan, context) {
       return await generateArchitectureOverview(aiContext, { depGraph, driftResult });
       
     case "module_catalog":
-      // Hybrid: deterministic skeleton + ownership info
-      return renderModuleCatalogOriginal(config, scanResult, ownershipMap);
+      // Hybrid: deterministic skeleton + ownership info + dep-graph roles
+      return renderModuleCatalogOriginal(config, scanResult, ownershipMap, depGraph);
       
     case "route_map":
-      // Hybrid: deterministic skeleton + AI enhancement (for now, just deterministic)
-      return renderRouteMapOriginal(config, scanResult);
+      // Hybrid: deterministic skeleton + context-aware messaging
+      return renderRouteMapOriginal(config, scanResult, aiContext);
       
     case "api_surface":
       // Hybrid: deterministic skeleton + AI enhancement (for now, just deterministic)
       return renderApiSurfaceOriginal(config, scanResult);
       
     case "data_flows":
-      return await generateDataFlows(flows, aiContext, { depGraph, scanResult });
+      return await generateDataFlows(flows, aiContext, { depGraph, scanResult, moduleContext });
       
     case "arch_diff":
       if (!diffData) {

package/src/renderers/render.js

@@ -1,4 +1,6 @@
-export function renderSystemOverview(cfg, scan) {
+import { computeModuleLevelMetrics, describeModuleDepRole } from "../analyzers/context-builder.js";
+
+export function renderSystemOverview(cfg, scan, depGraph = null) {
   const projectName = cfg.project?.name || "Project";
   const date = new Date().toLocaleDateString("en-US", { month: "long", day: "numeric", year: "numeric" });
 
@@ -17,8 +19,8 @@ export function renderSystemOverview(cfg, scan) {
     `|--------|-------|`,
     `| Files scanned | ${scan.filesCount} |`,
     `| Modules detected | ${scan.modules.length} |`,
-    `| Application pages | ${scan.pages?.length || 0} |`,
-    `| API endpoints | ${scan.api.length} |`,
+    ...(scan.pages?.length ? [`| Application pages | ${scan.pages.length} |`] : []),
+    ...(scan.api.length ? [`| API endpoints | ${scan.api.length} |`] : []),
     ``
   ];
 
@@ -35,9 +37,9 @@ export function renderSystemOverview(cfg, scan) {
       `| Category | Technologies |`,
       `|----------|-------------|`
     );
-    if (frameworks.length) lines.push(`| Frameworks | ${frameworks.join(", ")} |`);
+    lines.push(`| Frameworks | ${frameworks.join(", ") || 'N/A'} |`);
     if (languages.length) lines.push(`| Languages | ${languages.join(", ")} |`);
-    if (buildTools.length) lines.push(`| Build Tools | ${buildTools.join(", ")} |`);
+    lines.push(`| Build Tools | ${buildTools.join(", ") || 'N/A'} |`);
     if (testFrameworks.length) lines.push(`| Testing | ${testFrameworks.join(", ")} |`);
     lines.push(``);
   }
@@ -53,8 +55,8 @@ export function renderSystemOverview(cfg, scan) {
       `## Architecture Summary`,
       ``,
       `The repository is organized as ${sizeDesc} with **${scan.modules.length} modules** spanning **${scan.filesCount} files**. `
-      + (scan.api.length > 0 ? `It exposes **${scan.api.length} API endpoint${scan.api.length === 1 ? "" : "s"}** ` : "")
-      + (scan.pages?.length > 0 ? `and serves **${scan.pages.length} application page${scan.pages.length === 1 ? "" : "s"}**. ` : ". ")
+      + (scan.api.length > 0 ? `It exposes **${scan.api.length} API endpoint${scan.api.length === 1 ? "" : "s"}**. ` : "")
+      + (scan.pages?.length > 0 ? `It serves **${scan.pages.length} application page${scan.pages.length === 1 ? "" : "s"}**. ` : "")
       + `The largest modules are listed below, ranked by file count.`,
       ``
     );
@@ -62,6 +64,7 @@ export function renderSystemOverview(cfg, scan) {
 
   // Largest modules as a table instead of bullets
   const topModules = scan.modules.slice(0, 10);
+  const moduleMetrics = computeModuleLevelMetrics(depGraph, scan.modules);
   if (topModules.length > 0) {
     lines.push(
       `## Largest Modules`,
@@ -70,7 +73,8 @@ export function renderSystemOverview(cfg, scan) {
       `|--------|-------|-------------|`
     );
     for (const m of topModules) {
-      const desc = describeModule(m.key);
+      const depRole = describeModuleDepRole(m.key, moduleMetrics);
+      const desc = describeModule(m.key, depRole);
       lines.push(`| \`${m.key}\` | ${m.fileCount} | ${desc} |`);
     }
     lines.push(``);
@@ -105,36 +109,50 @@ export function renderSystemOverview(cfg, scan) {
   return lines.join("\n");
 }
 
-function describeModule(key) {
+function describeModule(key, depRole = null) {
   const normalized = key.toLowerCase();
-  if (normalized.includes("core")) return "Core business logic and shared foundations";
-  if (normalized.includes("util")) return "Shared utilities and helper functions";
-  if (normalized.includes("api")) return "API route handlers and endpoint definitions";
-  if (normalized.includes("component")) return "Reusable UI components";
-  if (normalized.includes("hook")) return "Custom React hooks";
-  if (normalized.includes("page")) return "Application page components";
-  if (normalized.includes("lib")) return "Library code and third-party integrations";
-  if (normalized.includes("service")) return "Service layer and external integrations";
-  if (normalized.includes("model")) return "Data models and schema definitions";
-  if (normalized.includes("store") || normalized.includes("state")) return "State management";
-  if (normalized.includes("config")) return "Configuration and settings";
-  if (normalized.includes("test")) return "Test suites and fixtures";
-  if (normalized.includes("style") || normalized.includes("css")) return "Styling and design tokens";
-  if (normalized.includes("type")) return "Type definitions and interfaces";
-  if (normalized.includes("middleware")) return "Request middleware and interceptors";
-  if (normalized.includes("auth")) return "Authentication and authorization";
-  if (normalized.includes("render")) return "Rendering logic and output formatters";
-  if (normalized.includes("publish")) return "Publishing and delivery integrations";
-  if (normalized.includes("analyz")) return "Code analysis and intelligence";
-  if (normalized.includes("delivery")) return "Content delivery and distribution";
-  if (normalized.includes("integrat")) return "Third-party service integrations";
-  if (normalized.includes("doc")) return "Documentation generation";
-  if (normalized.includes("bin") || normalized.includes("cli")) return "CLI entry point and commands";
-  return "Application module";
+  // Base description from path keywords
+  let base;
+  if (normalized.includes("core")) base = "Core business logic and shared foundations";
+  else if (normalized.includes("util")) base = "Shared utilities and helper functions";
+  else if (normalized.includes("api")) base = "API route handlers and endpoint definitions";
+  else if (normalized.includes("component")) base = "Reusable UI components";
+  else if (normalized.includes("hook")) base = "Custom React hooks";
+  else if (normalized.includes("page")) base = "Application page components";
+  else if (normalized.includes("lib")) base = "Library code and third-party integrations";
+  else if (normalized.includes("service")) base = "Service layer and external integrations";
+  else if (normalized.includes("model")) base = "Data models and schema definitions";
+  else if (normalized.includes("store") || normalized.includes("state")) base = "State management";
+  else if (normalized.includes("config")) base = "Configuration and settings";
+  else if (normalized.includes("test")) base = "Test suites and fixtures";
+  else if (normalized.includes("style") || normalized.includes("css")) base = "Styling and design tokens";
+  else if (normalized.includes("type")) base = "Type definitions and interfaces";
+  else if (normalized.includes("middleware")) base = "Request middleware and interceptors";
+  else if (normalized.includes("auth")) base = "Authentication and authorization";
+  else if (normalized.includes("render")) base = "Rendering logic and output formatters";
+  else if (normalized.includes("publish")) base = "Publishing and delivery integrations";
+  else if (normalized.includes("analyz")) base = "Code analysis and intelligence";
+  else if (normalized.includes("delivery")) base = "Content delivery and distribution";
+  else if (normalized.includes("integrat")) base = "Third-party service integrations";
+  else if (normalized.includes("doc")) base = "Documentation generation";
+  else if (normalized.includes("bin") || normalized.includes("cli")) base = "CLI entry point and commands";
+  else if (normalized.includes("plugin") || normalized.includes("extension")) base = "Plugin system and extensions";
+  else if (normalized.includes("prompt")) base = "Prompt engineering and templates";
+  else if (normalized.includes("provider")) base = "Service provider adapters";
+  else if (normalized.includes("generate") || normalized.includes("section")) base = "Content generation pipeline";
+  else if (normalized.includes("ai") || normalized.includes("ml")) base = "AI and machine learning integration";
+  else base = "Application module";
+
+  // Enrich with dependency role if available
+  if (depRole) {
+    return `${base} · ${depRole}`;
+  }
+  return base;
 }
 
-export function renderModuleCatalog(cfg, scan, ownershipMap = {}) {
+export function renderModuleCatalog(cfg, scan, ownershipMap = {}, depGraph = null) {
   const hasOwnership = Object.keys(ownershipMap).length > 0;
+  const moduleMetrics = computeModuleLevelMetrics(depGraph, scan.modules);
   const lines = [
     `# Module Catalog`,
     ``,
@@ -172,7 +190,8 @@ export function renderModuleCatalog(cfg, scan, ownershipMap = {}) {
   }
 
   for (const module of scan.modules.slice(0, 100)) {
-    const desc = describeModule(module.key);
+    const depRole = describeModuleDepRole(module.key, moduleMetrics);
+    const desc = describeModule(module.key, depRole);
     const owners = ownershipMap[module.key];
     if (hasOwnership) {
       lines.push(`| \`${module.key}\` | ${module.fileCount} | ${desc} | ${owners ? owners.join(", ") : "—"} |`);
@@ -277,7 +296,7 @@ export function renderApiSurface(cfg, scan) {
   return lines.join("\n");
 }
 
-export function renderRouteMap(cfg, scan) {
+export function renderRouteMap(cfg, scan, aiContext = null) {
   const lines = [
     `# Route Map`,
     ``,
@@ -330,30 +349,61 @@ export function renderRouteMap(cfg, scan) {
   }
 
   if (!scan.pages?.length && !scan.api?.length) {
+    // Determine project type for context-aware messaging
+    const patterns = aiContext?.patterns || [];
+    const isCLI = patterns.some(p => p.toLowerCase().includes("cli"));
+    const isLibrary = patterns.some(p => p.toLowerCase().includes("library") || p.toLowerCase().includes("shared"));
+    const techStack = aiContext?.techStack || {};
+    const hasWebFramework = (techStack.frameworks || []).some(f =>
+      /next|react|vue|angular|express|fastify|hono|koa|django|flask|rails|spring/i.test(f)
+    );
+
     lines.push(
       `## Route Detection`,
-      ``,
-      `No routes were auto-detected in this scan. RepoLens currently supports:`,
-      ``,
-      `| Framework | Pattern | Status |`,
-      `|-----------|---------|--------|`,
-      `| Next.js | \`pages/\` and \`app/\` directories | Supported |`,
-      `| Next.js API | \`pages/api/\` and App Router | Supported |`,
-      `| Express.js | \`app.get\`, \`router.post\`, etc. | Supported |`,
-      `| React Router | \`<Route>\` components | Supported |`,
-      `| Vue Router | \`routes\` array definitions | Supported |`,
-      ``,
-      `If your project uses a different routing framework, open an issue at [github.com/CHAPIBUNNY/repolens](https://github.com/CHAPIBUNNY/repolens/issues) to request support.`,
       ``
     );
+
+    if (isCLI) {
+      lines.push(
+        `This project is a **CLI tool** — it does not expose HTTP routes or serve web pages. This is expected behavior, not a detection failure.`,
+        ``,
+        `CLI tools interact through terminal commands rather than URLs. See the **System Overview** or **Developer Onboarding** documents for command documentation.`,
+        ``
+      );
+    } else if (isLibrary && !hasWebFramework) {
+      lines.push(
+        `This project is a **library/package** — it does not define its own routes or pages. Libraries are consumed by other applications that define their own routing.`,
+        ``
+      );
+    } else {
+      lines.push(
+        `No routes were auto-detected in this scan. RepoLens currently supports:`,
+        ``,
+        `| Framework | Pattern | Status |`,
+        `|-----------|---------|--------|`,
+        `| Next.js | \`pages/\` and \`app/\` directories | Supported |`,
+        `| Next.js API | \`pages/api/\` and App Router | Supported |`,
+        `| Express.js | \`app.get\`, \`router.post\`, etc. | Supported |`,
+        `| Fastify | \`fastify.get\`, \`fastify.post\`, etc. | Supported |`,
+        `| Hono | \`app.get\`, \`app.post\`, etc. | Supported |`,
+        `| React Router | \`<Route>\` components | Supported |`,
+        `| Vue Router | \`routes\` array definitions | Supported |`,
+        ``,
+        `If your project uses a different routing framework, open an issue at [github.com/CHAPIBUNNY/repolens](https://github.com/CHAPIBUNNY/repolens/issues) to request support.`,
+        ``
+      );
+    }
   }
 
-  lines.push(
-    `---`,
-    ``,
-    `*Paths starting with \`/api/\` are backend endpoints; all others are user-facing pages.*`,
-    ``
-  );
+  // Only add the route hint footer for projects that actually have routes
+  if (scan.pages?.length || scan.api?.length) {
+    lines.push(
+      `---`,
+      ``,
+      `*Paths starting with \`/api/\` are backend endpoints; all others are user-facing pages.*`,
+      ``
+    );
+  }
 
   return lines.join("\n");
 }

package/src/renderers/renderDiff.js

@@ -31,6 +31,20 @@ function routePathFromFile(file) {
   return file;
 }
 
+// Files/dirs to exclude from impacted modules (build artifacts, lockfiles, etc.)
+const NOISE_PATTERNS = [
+  /^node_modules/,
+  /^package-lock\.json$/,
+  /^yarn\.lock$/,
+  /^pnpm-lock\.yaml$/,
+  /^\.repolens\//,
+  /^\.git\//,
+];
+
+function isNoiseFile(file) {
+  return NOISE_PATTERNS.some(p => p.test(file));
+}
+
 function moduleFromFile(file) {
   const normalized = file.replace(/\\/g, "/");
   const parts = normalized.split("/");
@@ -50,14 +64,20 @@ export function buildArchitectureDiffData(diff) {
   const addedRoutes = diff.added.filter(isRouteFile).map(routePathFromFile);
   const removedRoutes = diff.removed.filter(isRouteFile).map(routePathFromFile);
 
+  // Filter out noise files (node_modules, lockfiles, etc.) from all lists
+  const added = diff.added.filter(f => !isNoiseFile(f));
+  const removed = diff.removed.filter(f => !isNoiseFile(f));
+  const modified = diff.modified.filter(f => !isNoiseFile(f));
+  const allFiles = [...added, ...removed, ...modified];
   const impactedModules = [
-    ...new Set(
-      [...diff.added, ...diff.removed, ...diff.modified].map(moduleFromFile)
-    )
+    ...new Set(allFiles.map(moduleFromFile))
   ].sort();
 
   return {
     ...diff,
+    added,
+    removed,
+    modified,
     addedRoutes,
     removedRoutes,
     impactedModules