@chappibunny/repolens 1.15.3 → 1.15.5

package/src/analyzers/maturity.js

@@ -0,0 +1,151 @@
+// Project maturity from observable signals (release version, history, tests, CI, docs, dependency health)
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+function exists(root, rel) {
+  try {
+    return fs.existsSync(path.join(root, rel));
+  } catch {
+    return false;
+  }
+}
+
+function readText(root, rel) {
+  try {
+    return fs.readFileSync(path.join(root, rel), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** Declared project version from package.json, Cargo.toml, or pyproject.toml. */
+export function detectDeclaredVersion(root) {
+  const pkg = readText(root, "package.json");
+  if (pkg) {
+    try {
+      const version = JSON.parse(pkg)?.version;
+      if (typeof version === "string") return version;
+    } catch {
+      // ignore invalid JSON
+    }
+  }
+  for (const file of ["Cargo.toml", "pyproject.toml"]) {
+    const text = readText(root, file);
+    const match = text && text.match(/^\s*version\s*=\s*["']([^"']+)["']/m);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+export function majorVersion(version) {
+  const match = String(version || "").match(/^v?(\d+)\./);
+  return match ? Number(match[1]) : null;
+}
+
+function git(root, args) {
+  try {
+    return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Git facts, or null when `root` is not a git checkout. Shallow clones report `shallow: true`. */
+export function detectGitHistory(root) {
+  if (git(root, ["rev-parse", "--is-inside-work-tree"]) !== "true") return null;
+  const shallow = git(root, ["rev-parse", "--is-shallow-repository"]) === "true";
+  const tagOutput = git(root, ["tag", "--list"]);
+  const tags = tagOutput ? tagOutput.split("\n").filter(Boolean).length : 0;
+  let firstCommitMs = null;
+  if (!shallow) {
+    const roots = git(root, ["log", "--max-parents=0", "--format=%ct", "HEAD"]);
+    const stamps = (roots || "").split("\n").map(Number).filter((n) => Number.isFinite(n) && n > 0);
+    if (stamps.length) firstCommitMs = Math.min(...stamps) * 1000;
+  }
+  return { shallow, tags, firstCommitMs };
+}
+
+function detectCI(root) {
+  if (exists(root, ".github/workflows")) {
+    try {
+      if (fs.readdirSync(path.join(root, ".github/workflows")).some((f) => /\.ya?ml$/.test(f))) return true;
+    } catch {
+      // fall through
+    }
+  }
+  return [".gitlab-ci.yml", ".travis.yml", "appveyor.yml", ".circleci/config.yml", "azure-pipelines.yml", "Jenkinsfile", ".drone.yml", "bitbucket-pipelines.yml"]
+    .some((file) => exists(root, file));
+}
+
+function detectDocs(root) {
+  const hasReadme = ["README.md", "README.rst", "README.txt", "README"].some((f) => exists(root, f));
+  const hasDocsDir = ["docs", "doc"].some((d) => exists(root, d));
+  const hasContributing = exists(root, "CONTRIBUTING.md");
+  return hasReadme && (hasDocsDir || hasContributing);
+}
+
+/**
+ * Build maturity signals. A signal with `met: null` could not be measured
+ * (for example commit age in a shallow clone) and is left out of the total.
+ */
+export function collectMaturitySignals(root, { hasTests = false, cycles = null, now = Date.now(), version, git: gitInfo } = {}) {
+  const declared = version === undefined ? detectDeclaredVersion(root) : version;
+  const major = majorVersion(declared);
+  const history = gitInfo === undefined ? detectGitHistory(root) : gitInfo;
+
+  const signals = [];
+  signals.push({
+    key: "version",
+    label: "Stable release version",
+    met: major === null ? null : major >= 1,
+    detail: declared ? `v${declared}` : "no version declared",
+  });
+
+  const tags = history?.tags ?? 0;
+  signals.push({
+    key: "releases",
+    label: "Release history",
+    met: major === null && !history ? null : tags >= 5 || (major !== null && major >= 5),
+    detail: tags ? `${tags} tags` : major !== null ? `major version ${major}` : "no tags",
+  });
+
+  let ageMet = null;
+  let ageDetail = history?.shallow ? "shallow clone, history unavailable" : "no git history";
+  if (history?.firstCommitMs) {
+    const years = (now - history.firstCommitMs) / (365.25 * 24 * 3600 * 1000);
+    ageMet = years >= 1;
+    ageDetail = `${years.toFixed(1)} years of history`;
+  }
+  signals.push({ key: "history", label: "Commit history over a year", met: ageMet, detail: ageDetail });
+
+  signals.push({ key: "tests", label: "Automated tests", met: Boolean(hasTests), detail: hasTests ? "test framework detected" : "none detected" });
+  const ci = detectCI(root);
+  signals.push({ key: "ci", label: "Continuous integration", met: ci, detail: ci ? "CI config found" : "none found" });
+  const docs = detectDocs(root);
+  signals.push({ key: "docs", label: "Documentation", met: docs, detail: docs ? "README plus docs" : "README only or missing" });
+  signals.push({
+    key: "deps",
+    label: "No circular dependencies",
+    met: cycles === null || cycles === undefined ? null : cycles === 0,
+    detail: cycles ? `${cycles} cycle${cycles === 1 ? "" : "s"}` : "none",
+  });
+  return signals;
+}
+
+export function scoreMaturity(signals) {
+  const measured = signals.filter((s) => s.met !== null);
+  const score = measured.filter((s) => s.met).length;
+  const max = measured.length;
+  const ratio = max ? score / max : 0;
+  const declaredVersion = signals.find((s) => s.key === "version");
+  let label = ratio >= 0.7 ? "Production-grade" : ratio >= 0.45 ? "Well-structured" : "Early-stage";
+  // A project with a stable major version and several release signals is never "early-stage".
+  if (label === "Early-stage" && declaredVersion?.met && score >= 3) label = "Well-structured";
+  return { score, max, label, signals };
+}
+
+export function detectMaturity(root, options = {}) {
+  return scoreMaturity(collectMaturitySignals(root, options));
+}

package/src/analyzers/security-patterns.js

@@ -5,6 +5,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { info, warn } from "../utils/logger.js";
+import { isBuildOrExamplePath } from "../utils/path-roles.js";
 
 const JS_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"];
 
@@ -205,6 +206,27 @@ const SKIP_PATTERNS = [
   /\.repolens\//,
 ];
 
+const HTML_ASSIGNMENT_IDS = new Set(["innerhtml-assignment", "outerhtml-assignment"]);
+
+/**
+ * Is the right-hand side of an innerHTML/outerHTML assignment a fixed string?
+ * `el.innerHTML = ''` clears an element and `el.innerHTML = '<b>ok</b>'` writes a constant.
+ * Neither can carry injected markup, so neither is an XSS finding. A template literal
+ * with `${...}` or any concatenation still is.
+ */
+export function isStaticHtmlAssignment(restOfSource) {
+  const rest = String(restOfSource || "");
+  const quoted = rest.match(/^\s*(['"])((?:(?!\1)[^\\\n]|\\.)*)\1\s*(?=[;,)}\n]|$)/);
+  if (quoted) return true;
+  const template = rest.match(/^\s*`([^`]*)`\s*(?=[;,)}\n]|$)/);
+  if (template && !template[1].includes("${")) return true;
+  return false;
+}
+
+// Build scripts and example pages run on a maintainer's machine or in a demo page. They are
+// listed, but never as high severity.
+const SEVERITY_CAPPED_IDS_EXEMPT = new Set(["hardcoded-password"]);
+
 function shouldSkipFile(filePath) {
   return SKIP_PATTERNS.some(pattern => pattern.test(filePath));
 }
@@ -255,7 +277,11 @@ export async function analyzeSecurityPatterns(files, repoRoot) {
       
       while ((match = regex.exec(stripped)) !== null) {
         // Get line number
+        if (HTML_ASSIGNMENT_IDS.has(pattern.id) && isStaticHtmlAssignment(stripped.slice(match.index + match[0].length))) continue;
+
         const lineNumber = stripped.slice(0, match.index).split("\n").length;
+        const capped = isBuildOrExamplePath(file) && !SEVERITY_CAPPED_IDS_EXEMPT.has(pattern.id);
+        const severity = capped ? "low" : pattern.severity;
         
         // Get the surrounding code snippet
         const lines = stripped.split("\n");
@@ -267,8 +293,8 @@ export async function analyzeSecurityPatterns(files, repoRoot) {
         result.findings.push({
           id: pattern.id,
           category: pattern.category,
-          name: pattern.name,
-          severity: pattern.severity,
+          name: capped ? `${pattern.name} (build/example code)` : pattern.name,
+          severity,
           file,
           line: lineNumber,
           snippet: snippet.length > 200 ? snippet.slice(0, 200) + "..." : snippet,
@@ -276,7 +302,7 @@ export async function analyzeSecurityPatterns(files, repoRoot) {
           cwe: pattern.cwe,
         });
 
-        result.bySeverity[pattern.severity]++;
+        result.bySeverity[severity]++;
         result.filesWithFindings.add(file);
         
         if (!result.byCategory[pattern.category]) {

package/src/cli.js

@@ -24,6 +24,8 @@ import { runWatch } from "./watch.js";
 import { info, error, warn, fmt } from "./utils/logger.js";
 import { formatError } from "./utils/errors.js";
 import { checkForUpdates } from "./utils/update-check.js";
+import { detectProjectName } from "./utils/project-name.js";
+import { aiUpgradeSections } from "./utils/ai-notice.js";
 import { generateDocumentSet } from "./docs/generate-doc-set.js";
 import { writeDocumentSet } from "./docs/write-doc-set.js";
 import { loadPlugins } from "./plugins/loader.js";
@@ -139,21 +141,23 @@ async function promptForAI(cfg) {
 /**
  * Show the post-generation AI notice for users without GITHUB_TOKEN
  */
-function showPostGenerationAINotice() {
-  info(`\n${fmt.cyan("┌──────────────────────────────────────────────────────────────────┐")}`);
-  info(`${fmt.cyan("│")} ${fmt.boldYellow("✨ Unlock AI-Enhanced Documentation")}                             ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("├──────────────────────────────────────────────────────────────────┤")}`);
-  info(`${fmt.cyan("│")} Your docs are missing these AI-powered sections:                ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Executive Summary — plain language overview for leadership   ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Business Domains — what the system does for stakeholders    ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Architecture Overview — deeper narrative for architects     ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Data Flows — how information moves through your system      ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Developer Onboarding — getting started guide for new hires  ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}                                                                  ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")} ${fmt.boldGreen("🆓 Enable for FREE with GitHub Models:")}                          ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}   Run: ${fmt.brightCyan("repolens init")} → the wizard will guide you through setup  ${fmt.cyan("│")}`);
-  info(`${fmt.cyan("│")}   Or quick preview: ${fmt.green("export GITHUB_TOKEN=<your-token> && repolens demo")}  ${fmt.cyan("│")}`);  
-  info(`${fmt.cyan("└──────────────────────────────────────────────────────────────────┘")}`);
+function showPostGenerationAINotice(documents) {
+  const sections = aiUpgradeSections(documents);
+  if (sections.length === 0) return;
+  const bar = "─".repeat(66);
+  const row = (text) => `${fmt.cyan("│")}${text.padEnd(66)}${fmt.cyan("│")}`;
+  info(`\n${fmt.cyan(`┌${bar}┐`)}`);
+  info(`${fmt.cyan("│")} ${fmt.boldYellow("✨ Unlock AI-Enhanced Documentation")}${" ".repeat(66 - 36)}${fmt.cyan("│")}`);
+  info(fmt.cyan(`├${bar}┤`));
+  info(row(" These sections used rule-based text. AI can rewrite them as:"));
+  for (const section of sections) {
+    info(row(`   • ${section.title} — ${section.ai}`));
+  }
+  info(row(""));
+  info(`${fmt.cyan("│")} ${fmt.boldGreen("🆓 Enable for FREE with GitHub Models:")}${" ".repeat(66 - 39)}${fmt.cyan("│")}`);
+  info(row("   Run: repolens init → the wizard will guide you through setup"));
+  info(row("   Or preview: export GITHUB_TOKEN=<your-token> && repolens demo"));
+  info(fmt.cyan(`└${bar}┘`));
 }
 
 function printPerformanceSummary() {
@@ -597,7 +601,7 @@ async function main() {
         : "No .repolens.yml found — using multi-language scan patterns");
       cfg = {
         configVersion: 1,
-        project: { name: path.basename(targetDir) },
+        project: { name: detectProjectName(targetDir) },
         publishers: ["markdown"],
         scan: {
           include: detected.include,
@@ -655,7 +659,7 @@ async function main() {
         info("   To keep AI enabled permanently, run: repolens init");
       } else if (aiResult.noToken) {
         // No GITHUB_TOKEN - show instructions
-        showPostGenerationAINotice();
+        showPostGenerationAINotice(docSet.documents);
       }
       
       printPerformanceSummary();

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

@@ -34,6 +34,7 @@ import {
 } from "../renderers/renderAnalysis.js";
 import { info, warn } from "../utils/logger.js";
 import path from "node:path";
+import { detectMaturity } from "../analyzers/maturity.js";
 import { applyBrandingFooter } from "./branding.js";
 
 export async function generateDocumentSet(scanResult, config, diffData = null, pluginManager = null) {
@@ -79,6 +80,12 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   aiContext = buildAIContext(scanResult, config, depGraph);
   moduleContext = buildModuleContext(scanResult.modules, config, depGraph);
   flows = inferDataFlows(scanResult, config, depGraph);
+  try {
+    aiContext.maturity = detectMaturity(repoRoot, {
+      hasTests: (aiContext.techStack?.testFrameworks || []).length > 0 || scanResult.modules.some((m) => /(^|\/)(tests?|__tests__|spec)(\/|$)/i.test(m.key)),
+      cycles: depGraph?.stats?.cycles ?? null,
+    });
+  } catch (e) { warn(`Maturity detection failed: ${e.message}`); }
 
   // CODEOWNERS integration
   const codeowners = await parseCodeowners(repoRoot);
@@ -123,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;
     
@@ -230,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/init.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
 import { info, warn } from "./utils/logger.js";
+import { detectProjectName } from "./utils/project-name.js";
 import { isNonInteractiveEnvironment } from "./utils/interactive.js";
 import { detectRepoLanguages } from "./core/languages.js";
 import { repolensCommand } from "./utils/invocation.js";
@@ -814,9 +815,6 @@ function buildRepoLensConfig(projectName, detected, options = {}) {
   return lines.join("\n");
 }
 
-function detectProjectName(repoRoot) {
-  return path.basename(repoRoot) || "my-project";
-}
 
 async function promptNotionCredentials() {
   if (isNonInteractiveEnvironment()) {
@@ -914,7 +912,7 @@ async function runInteractiveWizard(repoRoot) {
     info("Press Enter to accept defaults shown in parentheses.\n");
 
     // 1. Project name
-    const defaultName = path.basename(repoRoot) || "my-project";
+    const defaultName = detectProjectName(repoRoot);
     const projectName = (await ask(`📦 Project name (${defaultName}): `)).trim() || defaultName;
 
     // 2. Publishers

package/src/mcp/tools.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { loadConfig } from "../core/config.js";
+import { detectProjectName } from "../utils/project-name.js";
 import { scanRepo } from "../core/scan.js";
 import { getGitDiff, isSafeGitRef } from "../core/diff.js";
 import { analyzeDependencyGraph } from "../analyzers/dependency-graph.js";
@@ -41,7 +42,7 @@ function projectRootFromArgs(args) {
 function defaultConfig(root) {
   return {
     configVersion: 1,
-    project: { name: path.basename(root) || "repository" },
+    project: { name: detectProjectName(root, "repository") },
     publishers: ["markdown"],
     scan: {
       include: ["**/*.{js,ts,jsx,tsx,mjs,cjs,py,go,rs,java,rb,php,cs,swift,kt}"],

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/ai-notice.js

@@ -0,0 +1,20 @@
+// The "unlock AI" notice shown after a run without AI
+
+export const AI_SECTIONS = [
+  { key: "executive_summary", title: "Executive Summary", ai: "plain language overview for leadership" },
+  { key: "business_domains", title: "Business Domains", ai: "what the system does for stakeholders" },
+  { key: "architecture_overview", title: "Architecture Overview", ai: "deeper narrative for architects" },
+  { key: "data_flows", title: "Data Flows", ai: "how information moves through your system" },
+  { key: "developer_onboarding", title: "Developer Onboarding", ai: "getting started guide for new hires" },
+];
+
+/**
+ * Sections the notice can offer to upgrade: the ones that were generated in this run.
+ * Their rule-based text exists. The notice never calls a written document "missing".
+ * Without a document list (older callers), every AI-capable section is offered.
+ */
+export function aiUpgradeSections(documents) {
+  if (!Array.isArray(documents)) return AI_SECTIONS;
+  const written = new Set(documents.filter((doc) => doc && !doc.error).map((doc) => doc.key));
+  return AI_SECTIONS.filter((section) => written.has(section.key));
+}

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