@chappibunny/repolens 1.15.4 → 1.15.5

package/src/core/scan.js

@@ -5,6 +5,7 @@ import { info, warn } from "../utils/logger.js";
 import { trackScan } from "../utils/telemetry.js";
 import { detectMonorepo } from "../analyzers/monorepo-detector.js";
 import { isInsideRoot } from "../utils/safe-path.js";
+import { isTestPath } from "../utils/path-roles.js";
 
 const norm = (p) => p.replace(/\\/g, "/");
 
@@ -101,6 +102,9 @@ function moduleKeyForFile(file, moduleRoots) {
     if (normalized === root) return root;
     if (normalized.startsWith(`${root}/`)) {
       const remainder = normalized.slice(root.length + 1);
+      // A file directly under the root belongs to the root itself. Only a sub-directory
+      // is its own module, so a flat `src/` is one module and not one module per file.
+      if (!remainder.includes("/")) return root;
       const nextSegment = remainder.split("/")[0];
       return nextSegment ? `${root}/${nextSegment}` : root;
     }
@@ -149,6 +153,26 @@ function routePathFromFile(file) {
   return file;
 }
 
+/**
+ * Source files a package.json names as its public entry: `main`, `module`, `types`, and every
+ * string under `exports`. Paths are repo-relative with no leading `./`.
+ */
+function packageEntryFiles(pkg) {
+  const found = new Set();
+  const add = (value) => {
+    if (typeof value !== "string" || !/\.(c|m)?[jt]sx?$/.test(value) || value.endsWith(".d.ts")) return;
+    found.add(value.replace(/^\.\//, ""));
+  };
+  const walk = (value) => {
+    if (typeof value === "string") add(value);
+    else if (value && typeof value === "object") Object.values(value).forEach(walk);
+  };
+  add(pkg.main);
+  add(pkg.module);
+  walk(pkg.exports);
+  return [...found];
+}
+
 /**
  * Detect languages from file extensions
  */
@@ -204,9 +228,12 @@ function detectLanguagesFromFiles(files) {
 
   for (const file of files) {
     const ext = path.extname(file).toLowerCase();
-    if (extensionMap[ext]) {
-      languages.add(extensionMap[ext]);
-    }
+    if (!extensionMap[ext]) continue;
+    // Type declarations (`index.d.ts`) and type tests describe a JavaScript library's
+    // types. They do not make the library a TypeScript project.
+    if (ext === ".ts" && /\.d\.ts$/i.test(file)) continue;
+    if (extensionMap[ext] === "TypeScript" && isTestPath(file)) continue;
+    languages.add(extensionMap[ext]);
   }
 
   return languages;
@@ -268,7 +295,9 @@ async function extractRepoMetadata(repoRoot, files = []) {
     if (allDeps["parcel"]) metadata.buildTools.push("Parcel");
 
     // Detect TypeScript from dependencies (supplements file detection)
-    if (allDeps["typescript"]) metadata.languages.add("TypeScript");
+    // A `typescript` devDependency alone does not make the source TypeScript: plain JavaScript
+    // libraries use it to check their `.d.ts` files. Trust it only when no files were scanned.
+    if (allDeps["typescript"] && files.length === 0) metadata.languages.add("TypeScript");
 
     // Detect Node.js runtime indicators
     const hasNodeEngines = pkg.engines && pkg.engines.node;
@@ -279,6 +308,23 @@ async function extractRepoMetadata(repoRoot, files = []) {
     if (hasNodeEngines || hasBin || hasNodeDeps || pkg.type === "module") {
       metadata.languages.add("Node.js");
     }
+
+    // A package with a library entry point (main, module, exports, types) is a library even
+    // when it also ships a `bin/` helper. Only a package with a bin and no library entry is a CLI.
+    // When it has both, the description decides: "Library that parses..." is a library,
+    // while a package that calls itself a CLI keeps that label.
+    const hasLibraryEntry = Boolean(pkg.main || pkg.module || pkg.exports || pkg.types || pkg.typings || pkg.browser);
+    const isShippedApp = Boolean(allDeps["electron"] || allDeps["next"]);
+    metadata.packageEntryFiles = packageEntryFiles(pkg);
+    if (hasLibraryEntry && !isShippedApp) {
+      const description = String(pkg.description || "");
+      const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.join(" ") : "";
+      const saysLibrary = /\b(library|sdk|parser|toolkit|framework)\b/i.test(description);
+      const saysCli = /\bcli\b|command[- ]line/i.test(`${description} ${keywords}`);
+      metadata.projectKind = hasBin && !saysLibrary && saysCli ? "cli" : "library";
+    } else if (hasBin && !hasLibraryEntry) {
+      metadata.projectKind = "cli";
+    }
   } catch {
     // No package.json or invalid JSON
   }

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

@@ -130,6 +130,11 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   
   for (const docPlan of activeDocuments) {
     docIndex++;
+    const emptyReason = emptyDocumentReason(docPlan, { config, scanResult, graphqlResult });
+    if (emptyReason) {
+      info(`[${docIndex}/${totalDocs}] Skipping ${docPlan.key}: ${emptyReason}`);
+      continue;
+    }
     info(`[${docIndex}/${totalDocs}] Generating ${docPlan.key}...`);
     let content = null;
     
@@ -237,6 +242,22 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   };
 }
 
+/**
+ * Documents that would only say "nothing found" are not written. A library has no GraphQL
+ * schema and no routes, so those two pages would be noise. A document the config lists
+ * explicitly in `documentation.sections` is always written.
+ */
+export function emptyDocumentReason(docPlan, { config, scanResult, graphqlResult }) {
+  if (config?.documentation?.sections?.includes(docPlan.key)) return null;
+  if (docPlan.key === "graphql_schema" && !graphqlResult?.detected) {
+    return "no GraphQL schema detected";
+  }
+  if (docPlan.key === "route_map" && !(scanResult?.pages?.length) && !(scanResult?.api?.length)) {
+    return "no pages or API routes detected";
+  }
+  return null;
+}
+
 async function generateDocument(docPlan, context) {
   const { key } = docPlan;
   const { scanResult, config, aiContext, moduleContext, flows, diffData, graphqlResult, tsResult, jsdocResult, depGraph, driftResult, securityResult, codeHealthResult, ownershipMap, pluginManager } = context;

package/src/renderers/render.js

@@ -1,4 +1,4 @@
-import { computeModuleLevelMetrics, describeModuleDepRole } from "../analyzers/context-builder.js";
+import { computeModuleLevelMetrics, describeModuleDepRole, isCliProject, isLibraryProject } from "../analyzers/context-builder.js";
 import { moduleEvidence, pathHasKeyword } from "../analyzers/domain-inference.js";
 
 export function renderSystemOverview(cfg, scan, depGraph = null) {
@@ -447,8 +447,8 @@ export function renderRouteMap(cfg, scan, aiContext = null) {
   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 isCLI = isCliProject(aiContext);
+    const isLibrary = isLibraryProject(aiContext) || 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)

package/src/renderers/renderAnalysis.js

@@ -343,7 +343,11 @@ export function renderDependencyGraph(depResult) {
   lines.push(`|--------|-------|`);
   lines.push(`| Source files | ${s.totalFiles} |`);
   lines.push(`| Import edges | ${s.totalEdges} |`);
-  lines.push(`| External packages | ${s.externalDeps} |`);
+  if (Array.isArray(depResult.externalDev) && depResult.externalDev.length > 0) {
+    lines.push(`| External packages | ${s.externalDeps} (${depResult.externalRuntime.length} runtime, ${depResult.externalDev.length} dev/test tooling) |`);
+  } else {
+    lines.push(`| External packages | ${s.externalDeps} |`);
+  }
   lines.push(`| Circular dependencies | ${s.cycles} |`);
   lines.push(`| Orphan files (no imports or importers) | ${s.orphanFiles} |`);
   lines.push("");
@@ -352,7 +356,7 @@ export function renderDependencyGraph(depResult) {
   if (s.hubs.length > 0) {
     lines.push("## Hub Modules");
     lines.push("");
-    lines.push("These are the most-imported modules in the codebase. Changes to hub modules have the widest blast radius and should be reviewed carefully:");
+    lines.push("These are the most-imported product modules (tests, examples, and build scripts are not counted). Changes to hub modules have the widest blast radius and should be reviewed carefully:");
     lines.push("");
     lines.push("| Module | Imported By |");
     lines.push("|--------|-------------|");
@@ -384,14 +388,29 @@ export function renderDependencyGraph(depResult) {
     lines.push("");
     lines.push(`The codebase imports **${depResult.externalDeps.length}** external package${depResult.externalDeps.length === 1 ? "" : "s"}. These are third-party modules (not the language standard library):`);
     lines.push("");
-    // Render as a compact table for cleaner output
-    const sorted = [...depResult.externalDeps].sort();
-    lines.push("| Package |");
-    lines.push("|---------|");
-    for (const dep of sorted) {
-      lines.push(`| \`${dep}\` |`);
+    const split = Array.isArray(depResult.externalDev) && depResult.externalDev.length > 0;
+    if (split) {
+      const renderTable = (title, names) => {
+        if (names.length === 0) return;
+        lines.push(`### ${title}`);
+        lines.push("");
+        lines.push("| Package |");
+        lines.push("|---------|");
+        for (const dep of [...names].sort()) lines.push(`| \`${dep}\` |`);
+        lines.push("");
+      };
+      renderTable(`Runtime (${depResult.externalRuntime.length})`, depResult.externalRuntime);
+      renderTable(`Development and test tooling (${depResult.externalDev.length})`, depResult.externalDev);
+    } else {
+      // Render as a compact table for cleaner output
+      const sorted = [...depResult.externalDeps].sort();
+      lines.push("| Package |");
+      lines.push("|---------|");
+      for (const dep of sorted) {
+        lines.push(`| \`${dep}\` |`);
+      }
+      lines.push("");
     }
-    lines.push("");
   }
 
   lines.push("---");

package/src/utils/path-roles.js

@@ -0,0 +1,58 @@
+// Path roles: is a file test code, or tooling/example code rather than the product?
+// Shared by the dependency graph, flow inference, pattern inference, and security scan
+// so tests and examples never drive hub lists, coupling advice, or severity.
+
+const TEST_DIRECTORIES = new Set([
+  "test", "tests", "spec", "specs", "__tests__", "__mocks__", "fixtures", "testdata", "e2e", "cypress",
+]);
+
+// Directories holding tooling, samples, and docs. Code in here describes a build script
+// or an example, not how the product works.
+export const TOOLING_DIRECTORIES = new Set([
+  "doc", "docs", "doc-gen", "docgen", "scripts", "script", "tools", "tooling",
+  "example", "examples", "demo", "demos", "sample", "samples",
+  "benchmark", "benchmarks", "bench", "fixtures", "tasks",
+]);
+
+function segments(filePath) {
+  return String(filePath || "").replace(/\\/g, "/").toLowerCase().split("/");
+}
+
+// Directory part of a path. A last segment without an extension (`test`, `examples/amd`)
+// is a directory key such as a module, so it counts too.
+function directorySegments(filePath) {
+  const parts = segments(filePath);
+  const last = parts[parts.length - 1] || "";
+  return /\.[a-z0-9]+$/.test(last) ? parts.slice(0, -1) : parts;
+}
+
+/** True for files in a test directory or named like a test (`a.test.js`, `a_test.go`, `test_a.py`). */
+export function isTestPath(filePath) {
+  const parts = segments(filePath);
+  if (directorySegments(filePath).some((segment) => TEST_DIRECTORIES.has(segment))) return true;
+  const base = parts[parts.length - 1] || "";
+  if (/^(test_|spec_)/.test(base)) return true;
+  if (/(_test|_spec)\.[a-z0-9]+$/.test(base)) return true;
+  if (/\.(test|spec)\.[a-z0-9]+$/.test(base)) return true;
+  return false;
+}
+
+/** True when a directory above the file is a tooling, example, or docs directory. */
+export function isToolingPath(filePath) {
+  return directorySegments(filePath).some((segment) => TOOLING_DIRECTORIES.has(segment));
+}
+
+/**
+ * Build-time or example code: runs on a maintainer's machine or in a browser demo, not in
+ * the shipped library. Includes `build*.js` scripts and anything under a tooling directory.
+ */
+export function isBuildOrExamplePath(filePath) {
+  if (isToolingPath(filePath)) return true;
+  const base = segments(filePath).pop() || "";
+  return /^build([-_.]|$)/.test(base);
+}
+
+/** Test code or tooling/example code: not part of the product's own architecture. */
+export function isNonProductPath(filePath) {
+  return isTestPath(filePath) || isToolingPath(filePath);
+}