@chappibunny/repolens 1.15.5 → 1.16.1

package/src/analyzers/dependency-graph.js

@@ -1,6 +1,8 @@
 // Dependency graph analysis with cycle detection.
 // JavaScript, TypeScript, Python, and Go imports become edges.
-// Comments and strings are ignored. Type-only TypeScript imports are not edges.
+// Comments and strings are ignored. Type-only TypeScript imports are not runtime edges.
+// Cycle priority is in cycle-priority.js: mutual recursion and type-only cycles are
+// not "Priority: High refactor". Large multi-module cycles stay high.
 
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -17,6 +19,11 @@ import {
   parseGoModule,
 } from "./import-parsers.js";
 import { isNonProductPath } from "../utils/path-roles.js";
+import {
+  classifyRuntimeCycles,
+  priorityCounts,
+  typeOnlyReport,
+} from "./cycle-priority.js";
 
 const JS_EXTENSIONS = new Set([".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"]);
 const PY_EXTENSIONS = new Set([".py", ".pyw"]);
@@ -70,6 +77,8 @@ function emptyResult() {
     nodes: [],
     edges: [],
     cycles: [],
+    cycleReports: [],
+    typeOnlyReports: [],
     externalDeps: [],
     externalRuntime: [],
     externalDev: [],
@@ -78,6 +87,23 @@ function emptyResult() {
   };
 }
 
+/** How many times imported bindings are called. `foo(`, `foo.bar(`, `ns?.method(`. */
+export function countBindingCalls(source, names) {
+  if (!names || names.length === 0) return 0;
+  const stripped = String(source)
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/(^|[^:\\])\/\/.*$/gm, "$1");
+  let total = 0;
+  for (const name of names) {
+    if (!/^[A-Za-z_$][\w$]*$/.test(name)) continue;
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const direct = stripped.match(new RegExp(`\\b${escaped}\\s*(?:\\?\\.\\s*)?\\(`, "g"));
+    const member = stripped.match(new RegExp(`\\b${escaped}\\s*(?:\\?\\.|\\.)\\s*[A-Za-z_$][\\w$]*\\s*\\(`, "g"));
+    total += (direct ? direct.length : 0) + (member ? member.length : 0);
+  }
+  return total;
+}
+
 async function loadGoModule(repoRoot) {
   const text = await readFileSafe(path.join(repoRoot, "go.mod"));
   return parseGoModule(text);
@@ -200,21 +226,66 @@ export async function analyzeDependencyGraph(files, repoRoot) {
   const pyIndex = indexPythonModules(pyFiles);
   const goModulePath = goFiles.length > 0 ? await loadGoModule(repoRoot) : null;
 
+  // Runtime edges carry call counts. Type-only edges stay off the runtime graph
+  // and are classified on their own so they are never "Priority: High refactor".
+  const edgeRecords = new Map();
+
+  function rememberEdge(fromKey, toKey, fromFile, typeOnly, calls) {
+    if (!toKey || toKey === fromKey || !allFileKeys.has(toKey)) return;
+    const id = `${fromKey}->${toKey}`;
+    let record = edgeRecords.get(id);
+    if (!record) {
+      record = {
+        from: fromKey,
+        to: toKey,
+        fromFile,
+        toFile: fileKeyToFile.get(toKey) || toKey,
+        typeOnly: true,
+        calls: 0,
+      };
+      edgeRecords.set(id, record);
+    }
+    if (!typeOnly) {
+      record.typeOnly = false;
+      record.calls += calls;
+    }
+  }
+
   for (const file of jsFiles) {
     const content = await readFileSafe(path.join(repoRoot, file));
     if (!content) continue;
     const fromKey = normalizeFileKey(file);
     const selfName = await ownPackageName(file);
+    const grouped = new Map();
     for (const imported of extractJsImports(content)) {
-      if (imported.typeOnly) continue;
-      if (isRelativeImport(imported.specifier)) {
-        addEdge(fromKey, resolveImportPath(file, imported.specifier));
-      } else {
+      if (!isRelativeImport(imported.specifier)) {
+        if (imported.typeOnly) continue;
         const name = externalPackageName(imported.specifier);
         if (name && name === selfName) continue;
         addExternal(fromKey, name);
+        continue;
+      }
+      const toKey = resolveImportPath(file, imported.specifier);
+      if (!toKey) continue;
+      const id = `${fromKey}->${toKey}`;
+      let slot = grouped.get(id);
+      if (!slot) {
+        slot = { toKey, typeOnly: true, names: new Set() };
+        grouped.set(id, slot);
+      }
+      if (!imported.typeOnly) {
+        slot.typeOnly = false;
+        for (const binding of imported.names || []) slot.names.add(binding);
       }
     }
+    for (const slot of grouped.values()) {
+      const calls = slot.typeOnly ? 0 : countBindingCalls(content, [...slot.names]);
+      rememberEdge(fromKey, slot.toKey, file, slot.typeOnly, calls);
+    }
+  }
+
+  for (const record of edgeRecords.values()) {
+    if (!record.typeOnly) addEdge(record.from, record.to);
   }
 
   for (const file of pyFiles) {
@@ -275,6 +346,21 @@ export async function analyzeDependencyGraph(files, repoRoot) {
   // Detect cycles using iterative DFS (Tarjan-lite / coloring)
   result.cycles = detectCycles(adjacency);
 
+  const fileForKey = (key) => fileKeyToFile.get(key) || key;
+  const runtimeEdgeList = [...edgeRecords.values()].filter((edge) => !edge.typeOnly);
+  result.cycleReports = classifyRuntimeCycles(result.cycles, runtimeEdgeList, fileForKey);
+
+  const typeOnlyAdj = new Map();
+  for (const edge of edgeRecords.values()) {
+    if (!edge.typeOnly) continue;
+    if (!typeOnlyAdj.has(edge.from)) typeOnlyAdj.set(edge.from, new Set());
+    if (!typeOnlyAdj.has(edge.to)) typeOnlyAdj.set(edge.to, new Set());
+    typeOnlyAdj.get(edge.from).add(edge.to);
+  }
+  result.typeOnlyReports = detectCycles(typeOnlyAdj).map((path) => typeOnlyReport(path));
+
+  const priorities = priorityCounts(result.cycleReports);
+
   // Stats
   const totalImports = result.edges.length;
   const orphans = result.nodes.filter(n => n.imports.length === 0 && n.importedBy.length === 0);
@@ -295,6 +381,9 @@ export async function analyzeDependencyGraph(files, repoRoot) {
     externalRuntime: externalRuntime.length,
     externalDev: externalDev.length,
     cycles: result.cycles.length,
+    highCycles: priorities.high,
+    mediumCycles: priorities.medium,
+    lowCycles: priorities.low,
     orphanFiles: orphans.length,
     hubs,
   };
@@ -314,21 +403,21 @@ export async function analyzeDependencyGraph(files, repoRoot) {
  * 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.
+ * package is runtime when a product file (not a test, example, or build script) imports it,
+ * and development tooling when only tests or examples import it. Python and Go have no
+ * package.json, so that import split is the whole decision.
  */
 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([
+  const declaredRuntime = new Set(pkg ? [
     ...Object.keys(pkg.dependencies || {}),
     ...Object.keys(pkg.optionalDependencies || {}),
     ...Object.keys(pkg.peerDependencies || {}),
-  ]);
-  const declaredDev = new Set(Object.keys(pkg.devDependencies || {}));
+  ] : []);
+  const declaredDev = new Set(pkg ? Object.keys(pkg.devDependencies || {}) : []);
 
   const productImports = new Set();
   for (const node of result.nodes) {

package/src/analyzers/import-parsers.js

@@ -147,6 +147,33 @@ function braceIsTypeOnly(inner) {
   return parts.every((part) => /^type\s+/.test(part) && !/^type\s+as\b/.test(part));
 }
 
+/** Local bindings in an import brace. `type Foo` is skipped. `foo as bar` yields `bar`. */
+function localNames(inner) {
+  const names = [];
+  for (const part of splitTopCommas(inner)) {
+    const trimmed = part.trim().replace(/\s+/g, " ");
+    if (!trimmed || /^type\s+/.test(trimmed)) continue;
+    const asMatch = trimmed.match(/^[A-Za-z_$][\w$]*\s+as\s+([A-Za-z_$][\w$]*)$/);
+    if (asMatch) {
+      names.push(asMatch[1]);
+      continue;
+    }
+    const id = trimmed.match(/^([A-Za-z_$][\w$]*)$/);
+    if (id) names.push(id[1]);
+  }
+  return names;
+}
+
+function readAlias(source, i) {
+  let j = skipWs(source, i);
+  const word = readWord(source, j);
+  if (word.word !== "as") return { name: null, next: i };
+  j = skipWs(source, word.next);
+  const name = readWord(source, j);
+  if (!name.word) return { name: null, next: j };
+  return { name: name.word, next: name.next };
+}
+
 function findMatchingBrace(source, openIndex) {
   let depth = 0;
   for (let i = openIndex; i < source.length; i += 1) {
@@ -179,16 +206,25 @@ function readFromClause(source, i) {
 }
 
 /**
- * @returns {{ specifier: string, typeOnly: boolean }[]}
+ * @returns {{ specifier: string, typeOnly: boolean, names: string[] }[]}
+ * `names` are the local bindings (`import { a as b }` → `b`) so callers can
+ * count `b(` as a use of this import. Type-only imports still list names.
  */
 export function extractJsImports(source) {
   const imports = [];
   const n = source.length;
   let i = 0;
 
-  function add(specifier, typeOnly) {
+  function add(specifier, typeOnly, names = []) {
     if (typeof specifier !== "string") return;
-    imports.push({ specifier, typeOnly: Boolean(typeOnly) });
+    const locals = [];
+    const seen = new Set();
+    for (const name of names) {
+      if (typeof name !== "string" || !name || seen.has(name)) continue;
+      seen.add(name);
+      locals.push(name);
+    }
+    imports.push({ specifier, typeOnly: Boolean(typeOnly), names: locals });
   }
 
   function parseRequire(at) {
@@ -228,7 +264,7 @@ export function extractJsImports(source) {
       const clause = readFromClause(source, close + 1);
       if (!clause) return close + 1;
       const onlyTypes = typeOnly || braceIsTypeOnly(inner);
-      add(clause.value, onlyTypes);
+      add(clause.value, onlyTypes, typeOnly ? [] : localNames(inner));
       return clause.next;
     }
 
@@ -240,8 +276,10 @@ export function extractJsImports(source) {
       }
       // default binding, namespace, or `name, { ... }`
       let sawValue = !typeOnly;
+      const names = [];
       if (source[j] !== "*") {
         const binding = readWord(source, j);
+        if (binding.word && !typeOnly) names.push(binding.word);
         j = skipWs(source, binding.next);
         if (source[j] === ",") {
           sawValue = !typeOnly;
@@ -249,8 +287,9 @@ export function extractJsImports(source) {
         }
       } else {
         j = skipWs(source, j + 1);
-        j = skipAsBinding(source, j);
-        j = skipWs(source, j);
+        const alias = readAlias(source, j);
+        if (alias.name && !typeOnly) names.push(alias.name);
+        j = skipWs(source, alias.next);
       }
       if (source[j] === "{") {
         const close = findMatchingBrace(source, j);
@@ -259,12 +298,13 @@ export function extractJsImports(source) {
         const clause = readFromClause(source, close + 1);
         if (!clause) return close + 1;
         const onlyTypes = typeOnly || (!sawValue && braceIsTypeOnly(inner));
-        add(clause.value, onlyTypes);
+        if (!onlyTypes) names.push(...localNames(inner));
+        add(clause.value, onlyTypes, names);
         return clause.next;
       }
       const clause = readFromClause(source, j);
       if (!clause) return at;
-      add(clause.value, typeOnly);
+      add(clause.value, typeOnly, typeOnly ? [] : names);
       return clause.next;
     }
 

package/src/badge.js

@@ -10,6 +10,8 @@ const SOURCE_EXT = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py",
 const SKIP_DIR = new Set([
   "node_modules", ".git", "dist", "build", "vendor", "target", "coverage",
   ".repolens", "__pycache__", ".cache",
+  "__snapshots__", "samples", "sample", "examples", "example",
+  "fixtures", "fixture", "__fixtures__", "e2e-fixtures", "e2e-fixture", "generated",
 ]);
 
 const COLOR_HEX = {
@@ -143,6 +145,7 @@ export async function listScoreFiles(root, { maxFiles = 2500 } = {}) {
         continue;
       }
       if (!entry.isFile()) continue;
+      if (entry.name.endsWith(".snap")) continue;
       if (!SOURCE_EXT.has(path.extname(entry.name))) continue;
       if (out.length >= maxFiles) {
         capped = true;

package/src/cli-args.js

@@ -8,6 +8,9 @@ const FLAGS_WITH_VALUE = new Set([
   "--url",
   "--link",
   "--label",
+  "--port",
+  "--host",
+  "--webhook-path",
 ]);
 const BOOLEAN_FLAGS = new Set([
   "--quick",
@@ -16,6 +19,7 @@ const BOOLEAN_FLAGS = new Set([
   "--force",
   "--strict",
   "--verbose",
+  "--manifest",
   "--help",
   "-h",
   "--version",

package/src/cli.js

@@ -311,6 +311,17 @@ async function main() {
     process.exit(code);
   }
 
+  if (command === "app") {
+    const { runGitHubApp } = await import("./github-app/run.js");
+    const code = await runGitHubApp({
+      manifest: Boolean(parsed.flags["--manifest"]),
+      port: parsed.flags["--port"],
+      host: parsed.flags["--host"],
+      webhookPath: parsed.flags["--webhook-path"],
+    });
+    process.exit(code);
+  }
+
   if (command === "mcp") {
     process.env.REPOLENS_LOG_STDERR = "1";
     const { startMcpServer } = await import("./mcp/server.js");

package/src/core/config-schema.js

@@ -107,6 +107,10 @@ export function validateConfig(config) {
     if (!config.scan.ignore || !Array.isArray(config.scan.ignore)) {
       errors.push("scan.ignore is required and must be an array");
     }
+
+    if (config.scan.include_dev_artifacts !== undefined && typeof config.scan.include_dev_artifacts !== "boolean") {
+      errors.push("scan.include_dev_artifacts must be a boolean");
+    }
   }
 
   // Validate module_roots (optional but must be array if present)

package/src/core/scan-defaults.js

@@ -0,0 +1,36 @@
+// Directories the scan skips unless scan.include_dev_artifacts is true.
+// Snapshots, samples, fixtures, examples, and generated output are dev tooling.
+// A project's own scan.ignore is still applied. The flag turns off only this list.
+
+export const DEV_ARTIFACT_IGNORE = [
+  "**/__snapshots__/**",
+  "**/*.snap",
+  "**/samples/**",
+  "**/sample/**",
+  "**/examples/**",
+  "**/example/**",
+  "**/fixtures/**",
+  "**/fixture/**",
+  "**/__fixtures__/**",
+  "**/e2e-fixtures/**",
+  "**/e2e-fixture/**",
+  "**/generated/**",
+];
+
+/**
+ * Ignore globs for one scan.
+ * `include_dev_artifacts: true` keeps the caller's list and does not add the defaults,
+ * so a config can scan samples or snapshots on purpose. Other ignore entries always apply.
+ */
+export function resolveScanIgnore(scan = {}) {
+  const user = Array.isArray(scan.ignore) ? scan.ignore.filter((pattern) => typeof pattern === "string") : [];
+  if (scan.include_dev_artifacts === true) return user;
+  const seen = new Set(user);
+  const merged = [...user];
+  for (const pattern of DEV_ARTIFACT_IGNORE) {
+    if (seen.has(pattern)) continue;
+    seen.add(pattern);
+    merged.push(pattern);
+  }
+  return merged;
+}

package/src/core/scan.js

@@ -5,7 +5,9 @@ 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";
+import { isNonProductPath, isTestPath } from "../utils/path-roles.js";
+import { resolveScanIgnore } from "./scan-defaults.js";
+import { replaceBracketParams } from "../utils/route-params.js";
 
 const norm = (p) => p.replace(/\\/g, "/");
 
@@ -93,7 +95,13 @@ async function readFileSafe(file) {
   }
 }
 
-function moduleKeyForFile(file, moduleRoots) {
+function rootModuleLabel(repoRoot) {
+  const base = path.basename(path.resolve(repoRoot || ""));
+  if (!base || base === "." || base === "..") return "root";
+  return base;
+}
+
+function moduleKeyForFile(file, moduleRoots, rootLabel = "root") {
   const normalized = norm(file);
 
   const sortedRoots = [...moduleRoots].sort((a, b) => b.length - a.length);
@@ -111,7 +119,9 @@ function moduleKeyForFile(file, moduleRoots) {
   }
 
   const parts = normalized.split("/");
-  return parts.length > 1 ? parts[0] : "root";
+  // A file next to go.mod or package.json is one module, named for the directory.
+  // Calling it "root" hid that package on the system map.
+  return parts.length > 1 ? parts[0] : rootLabel;
 }
 
 function routePathFromFile(file) {
@@ -121,10 +131,9 @@ function routePathFromFile(file) {
     const appIndex = f.indexOf("/app/");
     const relative = f.slice(appIndex + 5);
 
-    const cleaned = relative
+    const cleaned = replaceBracketParams(relative
       .replace(/\/page\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/route\.(ts|tsx|js|jsx)$/, ""))
       .replace(/\/$/, "");
 
     return cleaned ? `/${cleaned}` : "/";
@@ -141,10 +150,9 @@ function routePathFromFile(file) {
     const pagesIndex = f.indexOf("/pages/");
     const relative = f.slice(pagesIndex + 7);
 
-    const cleaned = relative
+    const cleaned = replaceBracketParams(relative
       .replace(/\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/index$/, "")
-      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/index$/, ""))
       .replace(/\/$/, "");
 
     return cleaned ? `/${cleaned}` : "/";
@@ -316,11 +324,13 @@ async function extractRepoMetadata(repoRoot, files = []) {
     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}`);
+    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} ${keywords}`);
+    const saysCli = /\bcli\b|command[- ]line/i.test(`${description} ${keywords}`);
+    // Express 5 publishes index.js with no `main` field. A description that says
+    // library or framework is enough; Node's default entry is that index.js.
+    if ((hasLibraryEntry || saysLibrary) && !isShippedApp) {
       metadata.projectKind = hasBin && !saysLibrary && saysCli ? "cli" : "library";
     } else if (hasBin && !hasLibraryEntry) {
       metadata.projectKind = "cli";
@@ -408,16 +418,37 @@ async function extractRepoMetadata(repoRoot, files = []) {
   return metadata;
 }
 
+function isCommentLine(line) {
+  const trimmed = String(line || "").trim();
+  return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
+}
+
+function lineAt(content, index) {
+  const start = content.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+  const end = content.indexOf("\n", index);
+  return content.slice(start, end === -1 ? content.length : end);
+}
+
+/** Express route paths start with `/`. `app.get('query parser fn')` is a setting. */
+function isExpressPath(routePath) {
+  return typeof routePath === "string"
+    && routePath.length > 0
+    && routePath.length <= 200
+    && (routePath.startsWith("/") || routePath === "*");
+}
+
 function extractExpressRoutes(content) {
   const routes = [];
   const seenRoutes = new Set();
 
-  // Match app.METHOD(path) or router.METHOD(path)
+  // Match app.METHOD(path) or router.METHOD(path). Skip comments and setting lookups.
   const methodPattern = /(?:app|router)\.(get|post|put|patch|delete|all)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
   let match;
 
   while ((match = methodPattern.exec(content)) !== null) {
+    if (isCommentLine(lineAt(content, match.index))) continue;
     const [, method, path] = match;
+    if (!isExpressPath(path)) continue;
     const routeKey = `${method.toUpperCase()}:${path}`;
     
     if (!seenRoutes.has(routeKey)) {
@@ -440,7 +471,9 @@ function extractExpressRoutes(content) {
   // Match app.route(path).METHOD()
   const routePattern = /(?:app|router)\.route\s*\(\s*['"`]([^'"`]+)['"`]\s*\)([.\s\w()]*)/gi;
   while ((match = routePattern.exec(content)) !== null) {
+    if (isCommentLine(lineAt(content, match.index))) continue;
     const [, path, chain] = match;
+    if (!isExpressPath(path)) continue;
     const methods = [];
     
     if (chain.includes(".get(")) methods.push("GET");
@@ -527,7 +560,7 @@ export async function listMatchedFiles(cfg) {
   const rootResolved = path.resolve(repoRoot);
   const files = await fg(cfg.scan.include, {
     cwd: rootResolved,
-    ignore: cfg.scan?.ignore || [],
+    ignore: resolveScanIgnore(cfg.scan),
     onlyFiles: true,
     followSymbolicLinks: false,
     absolute: false
@@ -556,21 +589,28 @@ export async function scanRepo(cfg) {
   }
 
   const moduleCounts = new Map();
+  const flatKeys = new Set();
+  const rootLabel = rootModuleLabel(repoRoot);
 
   for (const file of files) {
     // Go test files belong to the package they exercise. Counting each
     // *_test.go as its own module (the filename under module_roots) splits
     // one package into a source module and a test module.
     if (/_test\.go$/.test(norm(file))) continue;
-    const key = moduleKeyForFile(file, cfg.module_roots || []);
+    const key = moduleKeyForFile(file, cfg.module_roots || [], rootLabel);
+    if (!norm(file).includes("/")) flatKeys.add(key);
     moduleCounts.set(key, (moduleCounts.get(key) || 0) + 1);
   }
 
   const modules = [...moduleCounts.entries()]
-    .map(([key, fileCount]) => ({ key, fileCount }))
+    .map(([key, fileCount]) => ({
+      key,
+      fileCount,
+      ...(flatKeys.has(key) ? { flat: true } : {}),
+    }))
     .sort((a, b) => b.fileCount - a.fileCount);
 
-  const apiFiles = files.filter(isNextRoute);
+  const apiFiles = files.filter((file) => isNextRoute(file) && !isNonProductPath(file));
   const api = [];
 
   // Extract Next.js API routes
@@ -593,8 +633,9 @@ export async function scanRepo(cfg) {
     });
   }
 
-  // Extract Express.js routes
+  // Extract Express.js routes. Tests and examples are not the product API.
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".ts") || file.endsWith(".js")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);
@@ -613,7 +654,7 @@ export async function scanRepo(cfg) {
     }
   }
 
-  const pageFiles = files.filter(isNextPage);
+  const pageFiles = files.filter((file) => isNextPage(file) && !isNonProductPath(file));
   const pages = pageFiles.map((file) => ({
     file,
     path: routePathFromFile(file),
@@ -622,6 +663,7 @@ export async function scanRepo(cfg) {
 
   // Extract React Router routes
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".tsx") || file.endsWith(".jsx")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);
@@ -635,6 +677,7 @@ export async function scanRepo(cfg) {
 
   // Extract Vue Router routes
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".ts") || file.endsWith(".js") || file.endsWith(".vue")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);

package/src/docs/llms-text.js

@@ -34,6 +34,7 @@ RepoLens is the npm package \`@chappibunny/repolens\` (Node.js 18+). It is a CLI
 - [publish](${REPO_URL}/blob/main/docs/INSTALLATION.md): \`npx @chappibunny/repolens publish\` scans and publishes
 - [badge](${REPO_URL}/blob/main/README.md): \`npx @chappibunny/repolens badge\` prints shields.io code-health JSON, SVG, or markdown
 - [comment](${REPO_URL}/blob/main/README.md): \`npx @chappibunny/repolens comment --base <ref> --head <ref>\` prints an architecture diff
+- [app](${REPO_URL}/blob/main/docs/GITHUB_APP.md): \`npx @chappibunny/repolens app\` self-hosts the GitHub App webhook. \`--manifest\` prints the manifest. No credentials are required to print it
 - [doctor](${REPO_URL}/blob/main/docs/INSTALLATION.md): \`npx @chappibunny/repolens doctor\` validates setup
 - [mcp](${REPO_URL}/blob/main/docs/MCP.md): \`npx -y @chappibunny/repolens mcp\` starts the stdio server
 
@@ -95,6 +96,7 @@ Agent-oriented install steps, including the Cline MCP snippet, are in llms-insta
 - \`repolens watch\` regenerates docs on change and exits 2 when nothing matches.
 - \`repolens badge\` prints a shields.io endpoint JSON document for the code-health score (0–100). \`--format svg\` prints a square SVG. \`--format markdown --url https://host/repolens-badge.json\` prints a README snippet. \`--format all --out repolens-badge.json\` writes JSON and SVG. Exit 2 when no JavaScript, TypeScript, Python, or Go files were scored. The score is not reported as 100 when zero files match.
 - \`repolens comment --base <ref> --head <ref>\` compares those commits. It prints markdown locally. In GitHub Actions, with \`GITHUB_TOKEN\`, \`GITHUB_REPOSITORY\`, and a pull_request event, it creates or updates one comment.
+- \`repolens app\` self-hosts a GitHub App webhook. It verifies \`X-Hub-Signature-256\`, posts a Check Run named RepoLens, and updates the sticky architecture comment. \`repolens app --manifest\` prints the manifest and needs no secrets. Listening needs \`REPOLENS_APP_ID\`, \`REPOLENS_WEBHOOK_SECRET\`, and a private key. See docs/GITHUB_APP.md.
 - \`repolens mcp\` starts the stdio MCP server. \`repolens-mcp\` is the same entry.
 
 Exit codes: 0 success, 1 runtime error or unknown command, 2 validation failure (bad flags, missing config, empty scan, and the other cases in the README).