@chappibunny/repolens 1.16.1 → 1.16.3

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

@@ -130,7 +130,7 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   
   for (const docPlan of activeDocuments) {
     docIndex++;
-    const emptyReason = emptyDocumentReason(docPlan, { config, scanResult, graphqlResult });
+    const emptyReason = emptyDocumentReason(docPlan, { config, scanResult, graphqlResult, jsdocResult });
     if (emptyReason) {
       info(`[${docIndex}/${totalDocs}] Skipping ${docPlan.key}: ${emptyReason}`);
       continue;
@@ -244,10 +244,11 @@ 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
+ * schema and no routes, so those two pages would be noise, and a CLI or library with no
+ * routes, no external API clients, and no documented exports has no API Surface to show. A document the config lists
  * explicitly in `documentation.sections` is always written.
  */
-export function emptyDocumentReason(docPlan, { config, scanResult, graphqlResult }) {
+export function emptyDocumentReason(docPlan, { config, scanResult, graphqlResult, jsdocResult = null }) {
   if (config?.documentation?.sections?.includes(docPlan.key)) return null;
   if (docPlan.key === "graphql_schema" && !graphqlResult?.detected) {
     return "no GraphQL schema detected";
@@ -255,9 +256,16 @@ export function emptyDocumentReason(docPlan, { config, scanResult, graphqlResult
   if (docPlan.key === "route_map" && !(scanResult?.pages?.length) && !(scanResult?.api?.length)) {
     return "no pages or API routes detected";
   }
+  if (docPlan.key === "api_surface" && !(scanResult?.api?.length) && !(scanResult?.externalApis?.length) && !hasDocumentedExports(jsdocResult)) {
+    return "no API routes, external API integrations, or documented exports detected";
+  }
   return null;
 }
 
+function hasDocumentedExports(jsdocResult) {
+  return Boolean(jsdocResult?.detected && Array.isArray(jsdocResult.exports) && jsdocResult.exports.length > 0);
+}
+
 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/help.js

@@ -32,6 +32,8 @@ It detects Python, Go, Rust, Java/Kotlin, JavaScript/TypeScript, Ruby, PHP,
 C#, Swift, and C/C++ (and combinations) and sets scan.include plus
 module_roots from the files it finds. A repository with no recognized
 language gets multi-language globs, not JavaScript-only defaults.
+Detection is not full analysis: the dependency graph and code health read
+JavaScript/TypeScript, Python, and Go only.
 
 The target directory must already exist.
 
@@ -129,9 +131,12 @@ Options:
   --help, -h            Show this help
 
 With no config, demo detects the repository language and scans matching
-files (Python, Go, Rust, Java, JavaScript, and others). It does not publish
-to Notion or Confluence. A scan that matches 0 files exits 2 and does not
-write empty docs.
+files (Python, Go, Rust, Java, JavaScript, and others) for modules and file
+structure. The dependency graph and code health cover JavaScript/TypeScript,
+Python, and Go only; for other languages (for example Java, Kotlin, or C#)
+those pages say the language is not supported yet instead of showing a
+score. It does not publish to Notion or Confluence. A scan that matches
+0 files exits 2 and does not write empty docs.
 
 The target directory must already exist.
 

package/src/renderers/render.js

@@ -151,6 +151,18 @@ function describeModule(key, depRole = null, evidence = {}) {
   return base;
 }
 
+// A module whose files are mostly tests and fixtures is not "Application module".
+// The file count stays the same; the role says how much of it is test code.
+export function describeModuleWithTests(module, desc) {
+  const total = Number(module?.fileCount) || 0;
+  const tests = Number(module?.testFileCount) || 0;
+  if (!total || tests * 2 < total) return desc;
+  if (/^Test suites and fixtures/.test(desc)) return desc;
+  const role = desc.replace(/^Application module( · )?/, "");
+  const base = `Mostly tests and fixtures (${tests} of ${total} files)`;
+  return role ? `${base} · ${role}` : base;
+}
+
 export function renderModuleCatalog(cfg, scan, ownershipMap = {}, depGraph = null) {
   const hasOwnership = Object.keys(ownershipMap).length > 0;
   const moduleMetrics = computeModuleLevelMetrics(depGraph, scan.modules);
@@ -192,7 +204,7 @@ export function renderModuleCatalog(cfg, scan, ownershipMap = {}, depGraph = nul
 
   for (const module of scan.modules.slice(0, 100)) {
     const depRole = describeModuleDepRole(module.key, moduleMetrics);
-    const desc = describeModule(module.key, depRole, moduleEvidence(module.key, depGraph));
+    const desc = describeModuleWithTests(module, describeModule(module.key, depRole, moduleEvidence(module.key, depGraph)));
     const owners = ownershipMap[module.key];
     if (hasOwnership) {
       lines.push(`| \`${module.key}\` | ${module.fileCount} | ${desc} | ${owners ? owners.join(", ") : "—"} |`);
@@ -236,7 +248,7 @@ export function renderApiSurface(cfg, scan, jsdocResult = null) {
 
   if (!scan.api.length) {
     lines.push(
-      `No API routes were detected in this scan. If your project uses a routing framework (Express, Fastify, NestJS, etc.), ensure the relevant directories are included in your \`scan.include\` patterns.`,
+      `No HTTP API routes were detected. RepoLens reads Next.js API routes and Express-style \`app.get(...)\` / \`router.post(...)\` handlers in JavaScript and TypeScript; libraries and CLIs usually have none.`,
       ``
     );
   } else {

package/src/renderers/renderAnalysis.js

@@ -4,6 +4,8 @@
 //   - Dependency Graph
 //   - Architecture Drift
 
+import { coverageNotice } from "../analyzers/language-coverage.js";
+
 export function renderGraphQLSchema(graphqlResult) {
   if (!graphqlResult?.detected) {
     return [
@@ -316,6 +318,10 @@ export function renderTypeGraph(tsResult) {
 }
 
 export function renderDependencyGraph(depResult) {
+  const coverageLines = coverageNotice(depResult?.coverage, "import analysis");
+  if (!depResult?.nodes?.length && depResult?.coverage?.status === "unsupported") {
+    return ["# Dependency Graph", "", ...coverageLines].join("\n");
+  }
   if (!depResult?.nodes?.length) {
     return [
       "# Dependency Graph",
@@ -332,6 +338,7 @@ export function renderDependencyGraph(depResult) {
   lines.push("");
   lines.push(`> ${depResult.summary}`);
   lines.push("");
+  lines.push(...coverageLines);
   lines.push("This document maps every import relationship in the codebase, identifies the most-connected modules, and flags circular dependencies that may complicate refactoring or increase build times.");
   lines.push("");
 
@@ -526,6 +533,10 @@ export function renderArchitectureDrift(driftResult) {
 }
 
 export function renderCodeHealth(healthResult) {
+  const coverageLines = coverageNotice(healthResult?.coverage, "code health");
+  if (!healthResult?.modules?.length && healthResult?.coverage?.status === "unsupported") {
+    return ["# Code Health Report", "", ...coverageLines].join("\n");
+  }
   if (!healthResult?.modules?.length) {
     return [
       "# Code Health Report",
@@ -544,6 +555,7 @@ export function renderCodeHealth(healthResult) {
   lines.push("");
   lines.push(`> ${healthResult.summary}`);
   lines.push("");
+  lines.push(...coverageLines);
   lines.push("This report synthesizes complexity, coupling, documentation, and security signals into a single health score per module. Lower scores indicate higher risk and maintenance burden.");
   lines.push("");
 

package/src/utils/js-lexer.js

@@ -0,0 +1,146 @@
+// Remove JavaScript/TypeScript comments while keeping every string, template literal
+// (including `${...}` expressions, which may hold their own comments and strings),
+// and regular-expression literal intact. Comment text becomes spaces; newlines stay,
+// so offsets and line numbers still match the source.
+
+const REGEX_PREFIX_WORDS = new Set([
+  "return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "throw",
+  "case", "do", "else", "yield", "await",
+]);
+
+function blank(text) {
+  return text.replace(/[^\n]/g, " ");
+}
+
+function isIdentPart(ch) {
+  return /[A-Za-z0-9_$]/.test(ch || "");
+}
+
+export function stripJsComments(source) {
+  const src = String(source ?? "");
+  const n = src.length;
+  let out = "";
+  let i = 0;
+  // Stack of contexts: { type: "code", depth, inTemplate } or { type: "template" }.
+  const stack = [{ type: "code", depth: 0, inTemplate: false }];
+  // Last significant code token, to tell a regex literal from division.
+  let lastChar = "";
+  let lastWord = "";
+
+  while (i < n) {
+    const ctx = stack[stack.length - 1];
+    const ch = src[i];
+
+    if (ctx.type === "template") {
+      if (ch === "\\") {
+        out += src.slice(i, i + 2);
+        i += 2;
+        continue;
+      }
+      if (ch === "`") {
+        out += ch;
+        i += 1;
+        stack.pop();
+        lastChar = "`";
+        lastWord = "";
+        continue;
+      }
+      if (ch === "$" && src[i + 1] === "{") {
+        out += "${";
+        i += 2;
+        stack.push({ type: "code", depth: 0, inTemplate: true });
+        lastChar = "{";
+        lastWord = "";
+        continue;
+      }
+      out += ch;
+      i += 1;
+      continue;
+    }
+
+    // code context
+    const next = src[i + 1];
+    if (ch === "/" && next === "/") {
+      const nl = src.indexOf("\n", i);
+      const end = nl === -1 ? n : nl;
+      out += blank(src.slice(i, end));
+      i = end;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      const close = src.indexOf("*/", i + 2);
+      const end = close === -1 ? n : close + 2;
+      out += blank(src.slice(i, end));
+      i = end;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      let j = i + 1;
+      while (j < n) {
+        if (src[j] === "\\") { j += 2; continue; }
+        if (src[j] === ch || src[j] === "\n") { j += 1; break; }
+        j += 1;
+      }
+      out += src.slice(i, Math.min(j, n));
+      i = Math.min(j, n);
+      lastChar = ch;
+      lastWord = "";
+      continue;
+    }
+    if (ch === "`") {
+      out += ch;
+      i += 1;
+      stack.push({ type: "template" });
+      continue;
+    }
+    if (ch === "/") {
+      const regexAllowed = lastChar === "" || "([{,;:!?&|~^=<>+-*%".includes(lastChar) || REGEX_PREFIX_WORDS.has(lastWord);
+      if (regexAllowed) {
+        let j = i + 1;
+        let inClass = false;
+        while (j < n) {
+          const c = src[j];
+          if (c === "\\") { j += 2; continue; }
+          if (c === "\n") break;
+          if (c === "[") inClass = true;
+          else if (c === "]") inClass = false;
+          else if (c === "/" && !inClass) { j += 1; break; }
+          j += 1;
+        }
+        while (j < n && /[a-z]/i.test(src[j])) j += 1;
+        out += src.slice(i, j);
+        i = j;
+        lastChar = ")";
+        lastWord = "";
+        continue;
+      }
+    }
+    if (ch === "{") ctx.depth += 1;
+    if (ch === "}") {
+      if (ctx.inTemplate && ctx.depth === 0) {
+        out += ch;
+        i += 1;
+        stack.pop();
+        continue;
+      }
+      ctx.depth -= 1;
+    }
+    if (isIdentPart(ch)) {
+      let j = i;
+      while (j < n && isIdentPart(src[j])) j += 1;
+      const word = src.slice(i, j);
+      out += word;
+      i = j;
+      lastWord = word;
+      lastChar = word[word.length - 1];
+      continue;
+    }
+    out += ch;
+    i += 1;
+    if (!/\s/.test(ch)) {
+      lastChar = ch;
+      lastWord = "";
+    }
+  }
+  return out;
+}