@chappibunny/repolens 1.6.0 → 1.7.0

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/core/scan.js

@@ -29,13 +29,22 @@ function isExpressRoute(content) {
 }
 
 function isReactRouterFile(content) {
-  // Detect React Router patterns
-  return content.includes("<Route") || content.includes("createBrowserRouter") || content.includes("createRoutesFromElements");
+  // Detect React Router patterns — require import evidence, not just string mentions
+  const hasImport = /import\s+.*?from\s+['"]react-router/.test(content)
+    || /require\s*\(\s*['"]react-router/.test(content);
+  const hasJSX = /<Route\s/.test(content);
+  const hasFactory = /createBrowserRouter\s*\(/.test(content)
+    || /createRoutesFromElements\s*\(/.test(content);
+  return hasImport || hasJSX || hasFactory;
 }
 
 function isVueRouterFile(content) {
-  // Detect Vue Router patterns  
-  return (content.includes("createRouter") || content.includes("VueRouter")) && content.includes("routes");
+  // Detect Vue Router patterns — require import evidence, not just string mentions
+  const hasImport = /import\s+.*?from\s+['"]vue-router/.test(content)
+    || /require\s*\(\s*['"]vue-router/.test(content);
+  const hasConstructor = /new\s+VueRouter\s*\(/.test(content);
+  const hasFactory = /createRouter\s*\(/.test(content) && hasImport;
+  return hasImport || hasConstructor || hasFactory;
 }
 
 function isNextPage(file) {
@@ -159,6 +168,10 @@ async function extractRepoMetadata(repoRoot) {
     if (allDeps["nestjs"] || allDeps["@nestjs/core"]) metadata.frameworks.push("NestJS");
     if (allDeps["svelte"]) metadata.frameworks.push("Svelte");
     if (allDeps["solid-js"]) metadata.frameworks.push("Solid");
+    if (allDeps["hono"]) metadata.frameworks.push("Hono");
+    if (allDeps["koa"]) metadata.frameworks.push("Koa");
+    if (allDeps["hapi"] || allDeps["@hapi/hapi"]) metadata.frameworks.push("Hapi");
+    if (allDeps["electron"]) metadata.frameworks.push("Electron");
 
     // Detect test frameworks
     if (allDeps["vitest"]) metadata.testFrameworks.push("Vitest");
@@ -166,6 +179,7 @@ async function extractRepoMetadata(repoRoot) {
     if (allDeps["mocha"]) metadata.testFrameworks.push("Mocha");
     if (allDeps["playwright"]) metadata.testFrameworks.push("Playwright");
     if (allDeps["cypress"]) metadata.testFrameworks.push("Cypress");
+    if (allDeps["ava"]) metadata.testFrameworks.push("Ava");
 
     // Detect build tools
     if (allDeps["vite"]) metadata.buildTools.push("Vite");
@@ -173,9 +187,25 @@ async function extractRepoMetadata(repoRoot) {
     if (allDeps["rollup"]) metadata.buildTools.push("Rollup");
     if (allDeps["esbuild"]) metadata.buildTools.push("esbuild");
     if (allDeps["turbo"]) metadata.buildTools.push("Turborepo");
+    if (allDeps["tsup"]) metadata.buildTools.push("tsup");
+    if (allDeps["swc"] || allDeps["@swc/core"]) metadata.buildTools.push("SWC");
+    if (allDeps["parcel"]) metadata.buildTools.push("Parcel");
 
-    // Detect TypeScript
+    // Detect languages
     if (allDeps["typescript"]) metadata.languages.add("TypeScript");
+
+    // Infer JavaScript if package.json exists (any npm project uses JS/Node)
+    metadata.languages.add("JavaScript");
+
+    // Detect Node.js runtime indicators
+    const hasNodeEngines = pkg.engines && pkg.engines.node;
+    const hasBin = pkg.bin != null;
+    const hasNodeDeps = allDeps["node-fetch"] || allDeps["fs-extra"] || allDeps["dotenv"]
+      || allDeps["commander"] || allDeps["yargs"] || allDeps["chalk"]
+      || allDeps["inquirer"] || allDeps["ora"] || allDeps["execa"];
+    if (hasNodeEngines || hasBin || hasNodeDeps || pkg.type === "module") {
+      metadata.languages.add("Node.js");
+    }
   } catch {
     // No package.json or invalid JSON
   }
@@ -241,30 +271,29 @@ function extractExpressRoutes(content) {
 
 function extractReactRoutes(content, file) {
   const routes = [];
+  const lines = content.split("\n");
   
   // Match <Route path="..." />
   const routePattern = /<Route\s+[^>]*path\s*=\s*['"`]([^'"`]+)['"`][^>]*\/?>/gi;
   let match;
 
   while ((match = routePattern.exec(content)) !== null) {
-    const [, path] = match;
-    routes.push({
-      file,
-      path,
-      framework: "React Router"
-    });
+    const [, routePath] = match;
+    if (isValidRoutePath(routePath)) {
+      routes.push({ file, path: routePath, framework: "React Router" });
+    }
   }
 
-  // Match path: "..." in route objects  
-  const objectPattern = /path\s*:\s*['"`]([^'"`]+)['"`]/gi;
-  while ((match = objectPattern.exec(content)) !== null) {
-    const [, path] = match;
-    if (!routes.some(r => r.path === path)) {
-      routes.push({
-        file,
-        path,
-        framework: "React Router"
-      });
+  // Match path: "..." in route objects (skip comment lines)
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) continue;
+    const objectMatch = /path\s*:\s*['"`]([^'"`]+)['"`]/i.exec(trimmed);
+    if (objectMatch) {
+      const routePath = objectMatch[1];
+      if (isValidRoutePath(routePath) && !routes.some(r => r.path === routePath)) {
+        routes.push({ file, path: routePath, framework: "React Router" });
+      }
     }
   }
 
@@ -273,23 +302,31 @@ function extractReactRoutes(content, file) {
 
 function extractVueRoutes(content, file) {
   const routes = [];
-  
-  // Match path: '...' or path: "..." in Vue router definitions
-  const pathPattern = /path\s*:\s*['"`]([^'"`]+)['"`]/gi;
-  let match;
-
-  while ((match = pathPattern.exec(content)) !== null) {
-    const [, path] = match;
-    routes.push({
-      file,
-      path,
-      framework: "Vue Router"
-    });
+  const lines = content.split("\n");
+
+  // Match path: '...' or path: "..." in Vue router definitions (skip comment lines)
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) continue;
+    const match = /path\s*:\s*['"`]([^'"`]+)['"`]/i.exec(trimmed);
+    if (match) {
+      const routePath = match[1];
+      if (isValidRoutePath(routePath) && !routes.some(r => r.path === routePath)) {
+        routes.push({ file, path: routePath, framework: "Vue Router" });
+      }
+    }
   }
 
   return routes;
 }
 
+function isValidRoutePath(p) {
+  // Filter out placeholder/documentation strings and non-path values
+  if (!p || p === "..." || p === "*" || p.length > 200) return false;
+  // Must look like a URL path (starts with / or is a relative segment)
+  return p.startsWith("/") || /^[a-zA-Z0-9]/.test(p);
+}
+
 export async function scanRepo(cfg) {
   const repoRoot = cfg.__repoRoot;
 

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: hookScanResult });
+      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");
 }