@chappibunny/repolens 1.15.3 → 1.15.5

package/src/analyzers/context-builder.js

@@ -1,6 +1,7 @@
 // Build structured AI context from deterministic scan results
 
-import { groupModulesByDomain, pathHasKeyword } from "./domain-inference.js";
+import { groupModulesByDomain, pathHasKeyword, stripContainerSegments, hasContainerSegment } from "./domain-inference.js";
+import { isTestPath } from "../utils/path-roles.js";
 
 /**
  * Compute per-module dependency metrics from the dep graph.
@@ -28,56 +29,92 @@ export function computeModuleDepMetrics(depGraph) {
 }
 
 /**
- * Build a module-level dep metrics map (aggregating file-level metrics).
+ * Find the module a file belongs to: the module with the longest key that is a path
+ * prefix of the file. Files at the repository root belong to `root`.
+ */
+function buildModuleLookup(modules) {
+  const keys = modules.map((m) => m.key).sort((x, y) => y.length - x.length);
+  const cache = new Map();
+  return (file) => {
+    const norm = String(file || "").replace(/\\/g, "/");
+    if (cache.has(norm)) return cache.get(norm);
+    let found = null;
+    for (const key of keys) {
+      if (key === "root") continue;
+      if (norm === key || norm.startsWith(`${key}/`)) { found = key; break; }
+    }
+    if (!found && !norm.includes("/") && keys.includes("root")) found = "root";
+    cache.set(norm, found);
+    return found;
+  };
+}
+
+/**
+ * Build a module-level dep metrics map from file-level edges.
  * moduleKey → { fanIn, fanOut, isHub, isOrphan, isLeaf, isOrchestrator }
+ * fanIn and fanOut count distinct other modules, not file-to-file edges, so a folder
+ * of 77 test files that imports one helper 77 times still has a fan-out of 1.
  */
 export function computeModuleLevelMetrics(depGraph, modules) {
-  const fileMetrics = computeModuleDepMetrics(depGraph);
-  if (fileMetrics.size === 0 || !modules) return new Map();
+  if (!depGraph?.nodes || depGraph.nodes.length === 0 || !modules) return new Map();
 
-  const moduleLevelMap = new Map();
+  const moduleOf = buildModuleLookup(modules);
+  const fileToModule = new Map();
+  for (const node of depGraph.nodes) {
+    fileToModule.set(node.key, moduleOf(node.file || node.key));
+  }
 
-  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++;
-          }
-        }
-      }
+  const importedFrom = new Map(); // module -> Set of modules it imports
+  const importersOf = new Map();  // module -> Set of modules importing it
+  const fileCounts = new Map();
+  for (const node of depGraph.nodes) {
+    const from = fileToModule.get(node.key);
+    if (!from) continue;
+    fileCounts.set(from, (fileCounts.get(from) || 0) + 1);
+    for (const target of node.imports) {
+      const to = fileToModule.get(target);
+      if (!to || to === from) continue;
+      if (!importedFrom.has(from)) importedFrom.set(from, new Set());
+      if (!importersOf.has(to)) importersOf.set(to, new Set());
+      importedFrom.get(from).add(to);
+      importersOf.get(to).add(from);
     }
+  }
 
-    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,
-      });
-    }
+  const moduleLevelMap = new Map();
+  const hubThreshold = Math.max(3, Math.floor(modules.length * 0.15));
+  for (const mod of modules) {
+    if (!fileCounts.has(mod.key)) continue;
+    const fanIn = importersOf.get(mod.key)?.size || 0;
+    const fanOut = importedFrom.get(mod.key)?.size || 0;
+    moduleLevelMap.set(mod.key, {
+      fanIn,
+      fanOut,
+      isHub: fanIn >= hubThreshold,
+      isOrphan: fanIn === 0 && fanOut === 0,
+      isLeaf: fanOut === 0 && fanIn > 0,
+      isOrchestrator: fanOut >= 5 && fanIn < fanOut,
+    });
   }
 
   return moduleLevelMap;
 }
 
+/**
+ * Is this project a command-line tool? Package metadata decides when it is known
+ * (a library with a build helper in `bin/` is a library). Otherwise a CLI pattern does.
+ */
+export function isCliProject(context) {
+  const kind = context?.project?.kind;
+  if (kind === "cli") return true;
+  if (kind === "library") return false;
+  return (context?.patterns || []).some((p) => String(p).toLowerCase().startsWith("cli tool"));
+}
+
+export function isLibraryProject(context) {
+  return context?.project?.kind === "library";
+}
+
 export function buildAIContext(scanResult, config, depGraph = null) {
   const { filesCount, modules, api, pages, metadata } = scanResult;
   
@@ -129,12 +166,13 @@ export function buildAIContext(scanResult, config, depGraph = null) {
   };
   
   // Identify key architectural patterns (verified against dep graph when available)
-  const patterns = inferArchitecturalPatterns(modules, depGraph);
+  const patterns = inferArchitecturalPatterns(modules, depGraph, metadata?.projectKind);
   
   // Build compact context object
   return {
     project: {
       name: config.project.name,
+      kind: metadata?.projectKind || "unknown",
       filesScanned: filesCount,
       modulesDetected: modules.length,
       pagesDetected: pages?.length || 0,
@@ -159,6 +197,8 @@ export function buildAIContext(scanResult, config, depGraph = null) {
     techStack,
     
     patterns,
+
+    findings: inferFindings(depGraph),
     
     repoRoots: config.module_roots || [],
 
@@ -175,7 +215,15 @@ export function buildAIContext(scanResult, config, depGraph = null) {
 }
 
 function inferModuleType(modulePath) {
-  const has = (keyword) => pathHasKeyword(modulePath, keyword);
+  // `src` and `lib` only say where code lives. `lib/ogg` is typed by `ogg`, and a bare
+  // `lib` is the project's source, not a "shared library" layer.
+  const typedPath = stripContainerSegments(modulePath);
+  const fromContainer = hasContainerSegment(modulePath);
+  const has = (keyword) => pathHasKeyword(typedPath, keyword);
+  // Page, route, and view describe a folder of pages. A build script called
+  // `build-pages.js` is not one.
+  const isFile = /\.[a-z0-9]+$/i.test(String(modulePath).split("/").pop() || "");
+  const hasDirectory = (keyword) => pathHasKeyword(directoryPath(typedPath), keyword);
 
   if (has("test") || has("spec")) return "test";
   if (has("api") || has("endpoint")) return "api";
@@ -183,7 +231,7 @@ function inferModuleType(modulePath) {
   if (has("lib") || has("util") || has("helper") || has("common") || has("shared")) return "library";
   if (has("hook")) return "hooks";
   if (has("store") || has("state") || has("redux") || has("zustand")) return "state";
-  if (has("page") || has("route") || has("view")) return "route";
+  if (isFile ? (hasDirectory("page") || hasDirectory("route") || hasDirectory("view")) : (has("page") || has("route") || has("view"))) return "route";
   if (has("config") || has("setting") || has("env")) return "config";
   if (has("core") || has("kernel") || has("foundation")) return "core";
   if (has("render") || has("template") || has("format")) return "renderer";
@@ -201,19 +249,10 @@ function inferModuleType(modulePath) {
   if (has("service")) return "service";
   if (has("app")) return "app";
 
-  return "other";
+  return fromContainer ? "source" : "other";
 }
 
-function isTestEvidence(modulePath) {
-  const norm = String(modulePath || "").replace(/\\/g, "/");
-  if (/(^|\/)__(tests|mocks)__(\/|$)/.test(norm)) return true;
-  if (/(^|\/)(test|tests|spec|specs|fixtures|testdata)(\/|$)/.test(norm)) return true;
-  const base = norm.split("/").pop() || "";
-  if (/^(test_|spec_)/.test(base)) return true;
-  if (/(_test|_spec)\.[a-z0-9]+$/i.test(base)) return true;
-  if (/\.(test|spec)\.[a-z0-9]+$/i.test(base)) return true;
-  return false;
-}
+const isTestEvidence = isTestPath;
 
 const API_DIRECTORY_SEGMENTS = new Set([
   "api", "apis", "route", "routes", "router", "routers",
@@ -233,14 +272,15 @@ function directoryPath(modulePath) {
   return parts.join("/");
 }
 
-function inferArchitecturalPatterns(modules, depGraph = null) {
+function inferArchitecturalPatterns(modules, depGraph = null, projectKind = null) {
   const patterns = [];
   const production = modules.filter((module) => !isTestEvidence(module.key));
   const tests = modules.filter((module) => isTestEvidence(module.key));
   const keys = production.map(m => m.key.toLowerCase());
 
+  // `lib` and `src` only say where code lives, so they never count as evidence for a pattern.
   const has = (keyword) => keys.some((key) => (
-    keyword.includes("/") ? key.includes(keyword) : pathHasKeyword(key, keyword)
+    keyword.includes("/") ? key.includes(keyword) : pathHasKeyword(stripContainerSegments(key), keyword)
   ));
   const matchingKeys = (keywords, source = production) => {
     const found = [];
@@ -249,7 +289,7 @@ function inferArchitecturalPatterns(modules, depGraph = null) {
         const key = module.key;
         const matched = keyword.includes("/")
           ? key.toLowerCase().includes(keyword)
-          : pathHasKeyword(key, keyword);
+          : pathHasKeyword(stripContainerSegments(key), keyword);
         if (matched && !found.includes(key)) found.push(key);
       }
     }
@@ -271,7 +311,6 @@ function inferArchitecturalPatterns(modules, depGraph = null) {
 
   // 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) => {
@@ -309,11 +348,18 @@ function inferArchitecturalPatterns(modules, depGraph = null) {
     patterns.push(`API route pattern — ${sample}${more}`);
   }
 
-  if (has("core") || has("kernel")) {
+  // A directory named core/ or kernel/ is evidence. A file called core.ts is not:
+  // it is as likely a cross-platform entry point as a kernel.
+  const coreDirs = production
+    .filter((module) => directoryPath(module.key).split("/").some((segment) => ["core", "kernel"].includes(segment.toLowerCase())))
+    .map((module) => module.key);
+  if (coreDirs.length > 0) {
     const note = moduleMetrics.size > 0 && verifyHub("core")
       ? "high fan-in"
       : "";
-    cite("Core/kernel architecture", ["core", "kernel"], note);
+    const sample = coreDirs.slice(0, 3).map((key) => `\`${key}\``).join(", ");
+    const more = coreDirs.length > 3 ? ` (+${coreDirs.length - 3} more)` : "";
+    patterns.push(`Core/kernel architecture — ${[`${sample}${more}`, note].filter(Boolean).join("; ")}`);
   }
 
   if (has("plugin") || has("extension")) {
@@ -334,7 +380,8 @@ function inferArchitecturalPatterns(modules, depGraph = null) {
   }
 
   if (has("analyz") || has("detect") || has("inspect")) cite("Analysis pipeline", ["analyz", "detect", "inspect"]);
-  if (has("cli") || has("command") || has("bin")) cite("CLI tool architecture", ["cli", "command", "bin"]);
+  // A library's `bin/` folder is build tooling. Only a CLI package gets this pattern.
+  if (projectKind !== "library" && (has("cli") || has("command") || has("bin"))) cite("CLI tool architecture", ["cli", "command", "bin"]);
 
   if (has("util") || has("helper") || has("lib")) {
     const verified = moduleMetrics.size > 0 && verifyHub("util") || verifyHub("helper") || verifyHub("lib");
@@ -354,14 +401,24 @@ function inferArchitecturalPatterns(modules, depGraph = null) {
     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;
 }
 
+/**
+ * Warnings about the code that are not architectural patterns, for example
+ * circular dependencies. Docs list these as findings, never as a pattern.
+ */
+export function inferFindings(depGraph = null) {
+  const findings = [];
+  const cycles = depGraph?.stats?.cycles;
+  if (cycles > 0) {
+    findings.push(`⚠️ ${cycles} circular dependency cycle${cycles === 1 ? "" : "s"} detected`);
+  }
+  return findings;
+}
+
 /**
  * Generate a dependency-aware role description for a module.
  */

package/src/analyzers/dependency-graph.js

@@ -16,6 +16,7 @@ import {
   isGoStdlib,
   parseGoModule,
 } from "./import-parsers.js";
+import { isNonProductPath } from "../utils/path-roles.js";
 
 const JS_EXTENSIONS = new Set([".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"]);
 const PY_EXTENSIONS = new Set([".py", ".pyw"]);
@@ -70,6 +71,8 @@ function emptyResult() {
     edges: [],
     cycles: [],
     externalDeps: [],
+    externalRuntime: [],
+    externalDev: [],
     stats: null,
     summary: null,
   };
@@ -89,15 +92,19 @@ function goPackageImportPath(file, modulePath) {
   return rel || ".";
 }
 
+// Hubs describe the product. Test helpers, examples, and build scripts are neither hubs
+// nor reasons for a product file to count as one.
 function aggregateHubs(nodes, fileKeyToFile, modulePath, hubThreshold) {
   const groups = new Map();
   for (const node of nodes) {
+    if (isNonProductPath(node.file || node.key)) continue;
     const pkg = goPackageImportPath(node.file, modulePath);
     const key = pkg || node.key;
     if (!groups.has(key)) groups.set(key, new Set());
     const importers = groups.get(key);
     for (const importer of node.importedBy || []) {
       const importerFile = fileKeyToFile.get(importer) || importer;
+      if (isNonProductPath(importerFile)) continue;
       if (pkg && goPackageImportPath(importerFile, modulePath) === pkg) continue;
       importers.add(importer);
     }
@@ -156,6 +163,40 @@ export async function analyzeDependencyGraph(files, repoRoot) {
 
   for (const file of codeFiles) register(file);
 
+  // A package importing its own name (examples, docs, tests written like user code)
+  // is not a dependency. Resolve the nearest package.json for each file.
+  const packageNameByDir = new Map();
+  async function ownPackageName(file) {
+    let dir = path.dirname(file);
+    const visited = [];
+    for (;;) {
+      if (packageNameByDir.has(dir)) {
+        const cached = packageNameByDir.get(dir);
+        for (const d of visited) packageNameByDir.set(d, cached);
+        return cached;
+      }
+      visited.push(dir);
+      const raw = await readFileSafe(path.join(repoRoot, dir, "package.json"));
+      if (raw) {
+        let name = null;
+        try {
+          const parsed = JSON.parse(raw);
+          if (typeof parsed?.name === "string") name = parsed.name;
+        } catch {
+          // invalid package.json: keep walking up
+        }
+        if (name) {
+          for (const d of visited) packageNameByDir.set(d, name);
+          return name;
+        }
+      }
+      if (dir === "." || dir === "" || dir === path.dirname(dir)) break;
+      dir = path.dirname(dir);
+    }
+    for (const d of visited) packageNameByDir.set(d, null);
+    return null;
+  }
+
   const pyIndex = indexPythonModules(pyFiles);
   const goModulePath = goFiles.length > 0 ? await loadGoModule(repoRoot) : null;
 
@@ -163,12 +204,15 @@ export async function analyzeDependencyGraph(files, repoRoot) {
     const content = await readFileSafe(path.join(repoRoot, file));
     if (!content) continue;
     const fromKey = normalizeFileKey(file);
+    const selfName = await ownPackageName(file);
     for (const imported of extractJsImports(content)) {
       if (imported.typeOnly) continue;
       if (isRelativeImport(imported.specifier)) {
         addEdge(fromKey, resolveImportPath(file, imported.specifier));
       } else {
-        addExternal(fromKey, externalPackageName(imported.specifier));
+        const name = externalPackageName(imported.specifier);
+        if (name && name === selfName) continue;
+        addExternal(fromKey, name);
       }
     }
   }
@@ -234,13 +278,22 @@ export async function analyzeDependencyGraph(files, repoRoot) {
   // Stats
   const totalImports = result.edges.length;
   const orphans = result.nodes.filter(n => n.imports.length === 0 && n.importedBy.length === 0);
-  const hubThreshold = Math.max(5, Math.floor(result.nodes.length * 0.1));
+  const sourceNodeCount = result.nodes.filter((n) => !isNonProductPath(n.file || n.key)).length;
+  const hubThreshold = Math.max(5, Math.round(sourceNodeCount * 0.07));
   const hubs = aggregateHubs(result.nodes, fileKeyToFile, goModulePath, hubThreshold);
 
+  // Runtime vs development packages, from the nearest package.json.
+  const { runtime: externalRuntime, dev: externalDev } = await splitExternalDeps(result, repoRoot);
+  result.externalRuntime = externalRuntime;
+  result.externalDev = externalDev;
+
   result.stats = {
     totalFiles: codeFiles.length,
+    sourceFiles: codeFiles.filter((file) => !isNonProductPath(file)).length,
     totalEdges: totalImports,
     externalDeps: result.externalDeps.length,
+    externalRuntime: externalRuntime.length,
+    externalDev: externalDev.length,
     cycles: result.cycles.length,
     orphanFiles: orphans.length,
     hubs,
@@ -257,6 +310,48 @@ export async function analyzeDependencyGraph(files, repoRoot) {
   return result;
 }
 
+/**
+ * Split external packages into runtime dependencies and development tooling.
+ * A package declared in `devDependencies` is development tooling. One declared in
+ * `dependencies`, `optionalDependencies`, or `peerDependencies` is runtime. An undeclared
+ * package is runtime when a product file (not a test, example, or build script) imports it.
+ * Without a root package.json (Python, Go) every package counts as runtime.
+ */
+async function splitExternalDeps(result, repoRoot) {
+  const raw = await readFileSafe(path.join(repoRoot, "package.json"));
+  let pkg = null;
+  try { pkg = raw ? JSON.parse(raw) : null; } catch { pkg = null; }
+  if (!pkg) return { runtime: [...result.externalDeps], dev: [] };
+
+  const declaredRuntime = new Set([
+    ...Object.keys(pkg.dependencies || {}),
+    ...Object.keys(pkg.optionalDependencies || {}),
+    ...Object.keys(pkg.peerDependencies || {}),
+  ]);
+  const declaredDev = new Set(Object.keys(pkg.devDependencies || {}));
+
+  const productImports = new Set();
+  for (const node of result.nodes) {
+    if (isNonProductPath(node.file || node.key) || isBuildScript(node.file || node.key)) continue;
+    for (const name of node.externalImports || []) productImports.add(name);
+  }
+
+  const runtime = [];
+  const dev = [];
+  for (const name of result.externalDeps) {
+    if (declaredRuntime.has(name)) runtime.push(name);
+    else if (declaredDev.has(name)) dev.push(name);
+    else if (productImports.has(name)) runtime.push(name);
+    else dev.push(name);
+  }
+  return { runtime, dev };
+}
+
+function isBuildScript(file) {
+  const base = String(file || "").replace(/\\/g, "/").split("/").pop() || "";
+  return /^build([-_.]|$)/i.test(base) || /\.config\.[cm]?[jt]s$/i.test(base);
+}
+
 /**
  * Detect all cycles in a directed graph using DFS with 3-color marking.
  * Returns an array of cycle paths (each path ends where it started).

package/src/analyzers/domain-inference.js

@@ -17,7 +17,7 @@ const DEFAULT_DOMAIN_HINTS = [
     description: "Content publishing, management, and delivery"
   },
   { 
-    match: ["search", "filter", "query", "index", "catalog", "browse"], 
+    match: ["search", "query", "index", "catalog", "browse"], 
     domain: "Search & Discovery",
     description: "Search functionality, filtering, and content discovery"
   },
@@ -62,7 +62,7 @@ const DEFAULT_DOMAIN_HINTS = [
     description: "Database access, models, and data persistence"
   },
   {
-    match: ["config", "setting", "env", "constant"],
+    match: ["config", "setting", "env"],
     domain: "Configuration",
     description: "Application configuration and environment settings"
   },
@@ -92,7 +92,7 @@ const DEFAULT_DOMAIN_HINTS = [
     description: "Content and artifact publishing, deployment, and distribution"
   },
   {
-    match: ["analyz", "inspect", "detect", "lint", "scan", "parse"],
+    match: ["analyz", "inspect", "detect", "lint", "scan"],
     domain: "Analysis & Detection",
     description: "Code analysis, pattern detection, and static inspection"
   },
@@ -171,13 +171,54 @@ function domainEvidenceText(hint, modulePath, keyword, evidence) {
   return bits.join("; ");
 }
 
+// Entry and barrel file names say nothing about what a module does. `lib/index.ts`
+// is not "Search & Discovery" because it is called index.
+const ENTRY_FILE_STEMS = new Set(["index", "main", "mod", "__init__", "__main__"]);
+
+/** Drop a trailing entry/barrel file name (`lib/index.ts` → `lib`). Directories named `index` stay. */
+export function stripEntryFileName(modulePath) {
+  const parts = String(modulePath).replace(/\\/g, "/").split("/");
+  const last = parts[parts.length - 1] || "";
+  const dot = last.lastIndexOf(".");
+  if (dot > 0 && ENTRY_FILE_STEMS.has(last.slice(0, dot).toLowerCase())) {
+    parts.pop();
+    return parts.join("/");
+  }
+  return parts.join("/");
+}
+
+// Folder names that only say "code lives here". `lib/ogg` is about ogg, not about being a lib.
+export const GENERIC_CONTAINER_SEGMENTS = new Set(["src", "lib", "libs", "source", "sources", "packages", "pkg", "internal"]);
+
+/**
+ * Drop generic container folders (`src`, `lib`, ...) from a path so they do not pick a
+ * domain on their own. Returns "" when nothing else is left (`lib`, `src/lib`).
+ */
+export function stripContainerSegments(modulePath) {
+  return String(modulePath)
+    .replace(/\\/g, "/")
+    .split("/")
+    .filter((segment) => segment && !GENERIC_CONTAINER_SEGMENTS.has(segment.toLowerCase()))
+    .join("/");
+}
+
+/** True when the path has a generic container folder (`lib/ogg`, `src`). */
+export function hasContainerSegment(modulePath) {
+  return String(modulePath).replace(/\\/g, "/").split("/").some((segment) => GENERIC_CONTAINER_SEGMENTS.has(segment.toLowerCase()));
+}
+
 export function inferDomain(modulePath, customHints = [], evidence = {}) {
+  const customSet = new Set(customHints);
   const hints = [...customHints, ...DEFAULT_DOMAIN_HINTS];
+  const entryStripped = stripEntryFileName(modulePath);
+  const defaultPath = stripContainerSegments(entryStripped);
 
   for (const hint of hints) {
+    // User-defined hints see the full path. Built-in guesses ignore entry file names.
+    const searchPath = customSet.has(hint) ? modulePath : defaultPath;
     for (const keyword of hint.match) {
       if (REACT_HOOK_KEYWORDS.has(keyword) && !evidence.react) continue;
-      if (pathHasKeyword(modulePath, keyword)) {
+      if (pathHasKeyword(searchPath, keyword)) {
         return {
           domain: hint.domain,
           description: domainEvidenceText(hint, modulePath, keyword, evidence),
@@ -188,6 +229,16 @@ export function inferDomain(modulePath, customHints = [], evidence = {}) {
     }
   }
   
+  // A source folder with no keyword of its own is core code, not "uncategorized".
+  if (hasContainerSegment(entryStripped)) {
+    return {
+      domain: "Core Source",
+      description: "The project's own source code, grouped by folder",
+      confidence: "none",
+      matchedKeyword: null
+    };
+  }
+
   return {
     domain: "Other",
     description: "Uncategorized module",

package/src/analyzers/flow-inference.js

@@ -1,9 +1,33 @@
+import { isToolingPath, isTestPath } from "../utils/path-roles.js";
+
 // Infer data flows through the application using import graph analysis + heuristics
 
 /**
  * Primary flow inference: uses dep graph when available for real import-chain flows,
  * falls back to keyword heuristics for repos without dep graph data.
  */
+// File names too generic to name a flow ("gen Request Flow", "util Integration Flow").
+const GENERIC_FLOW_NAMES = new Set([
+  "gen", "generate", "util", "utils", "helper", "helpers", "misc", "common", "types", "constants",
+]);
+
+/**
+ * Drop flows that are noise: no steps, nothing beyond the starting file, a name that is only
+ * a generic helper word, or a chain that starts in tests, tooling, examples, or docs.
+ */
+export function filterNoiseFlows(flows) {
+  return (flows || []).filter((flow) => {
+    if (!flow) return false;
+    const steps = Array.isArray(flow.steps) ? flow.steps : [];
+    if (steps.length < 2) return false;
+    const origin = flow.modules?.[0];
+    if (origin && (isToolingPath(origin) || isTestPath(origin))) return false;
+    const stem = String(flow.name || "").split(" ")[0].toLowerCase();
+    if (GENERIC_FLOW_NAMES.has(stem)) return false;
+    return true;
+  });
+}
+
 export function inferDataFlows(scanResult, config, depGraph = null) {
   const flows = [];
   
@@ -28,7 +52,12 @@ export function inferDataFlows(scanResult, config, depGraph = null) {
   const apiFlow = inferApiIntegrationFlow(scanResult);
   if (apiFlow && !existingNames.has(apiFlow.name.toLowerCase())) flows.push(apiFlow);
   
-  return flows;
+  return filterNoiseFlows(flows);
+}
+
+/** Same key the dependency graph gives a file: no extension, no trailing /index. */
+function fileKey(file) {
+  return String(file).replace(/\\/g, "/").replace(/\.(js|ts|jsx|tsx|mjs|cjs)$/, "").replace(/\/index$/, "");
 }
 
 /**
@@ -39,12 +68,22 @@ function inferFlowsFromEntryPoints(scanResult, depGraph) {
   const flows = [];
   if (!depGraph?.nodes) return flows;
 
+  const isLibrary = scanResult?.metadata?.projectKind === "library";
+  const packageEntryKeys = new Set(
+    (scanResult?.metadata?.packageEntryFiles || []).map((file) => fileKey(file)),
+  );
+
   // Find entry points (files with high fan-out and low/zero fan-in)
   const entryPoints = depGraph.nodes.filter(n => {
     const key = n.key.toLowerCase();
+    // Build configs (`webpack.config`) wire up tooling. They are not how data moves.
+    if (/\.config$/.test(key)) return false;
+    // In a library, `bin/` holds build helpers. The package entry is what callers use.
+    if (isLibrary && /(^|\/)bin\//.test(key)) return false;
     const isEntry = (
-      key.includes("bin/") || 
-      key.includes("cli") ||
+      packageEntryKeys.has(n.key) ||
+      (!isLibrary && key.includes("bin/")) ||
+      (!isLibrary && key.includes("cli")) ||
       key.endsWith("/index") ||
       key.includes("pages/") ||
       key.includes("app/") ||
@@ -53,15 +92,15 @@ function inferFlowsFromEntryPoints(scanResult, depGraph) {
     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");
+    const aIsTest = isTestPath(a.key);
+    const bIsTest = isTestPath(b.key);
     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 srcEntries = entryPoints.filter(n => !isTestPath(n.key));
+  const testEntries = entryPoints.filter(n => isTestPath(n.key)).slice(0, 2);
   const selectedEntries = [...srcEntries, ...testEntries].slice(0, 5);
 
   for (const entry of selectedEntries) {
@@ -69,8 +108,8 @@ function inferFlowsFromEntryPoints(scanResult, depGraph) {
     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";
+    const isCliEntry = !isLibrary && (entry.key.toLowerCase().includes("cli") || entry.key.toLowerCase().includes("bin/"));
+    const flowType = isCliEntry ? "Command" : isLibrary && packageEntryKeys.has(entry.key) ? "Library" : "Request";
     
     // Classify each step in the chain
     const steps = chain.map((nodeKey, i) => {