@chappibunny/repolens 1.15.3 → 1.15.4

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.15.4
+
+Fixes nine output problems found by running 1.15.3 on Borewit/music-metadata (a v12 TypeScript library).
+
+### Output accuracy
+
+- The project name is the `package.json` name, or the real directory name. `demo --target .`, `init`, and the MCP default config no longer name the project `.`
+- Maturity uses release version, release history (tags, or a major version of 5 or more), commit history over a year, tests, CI, documentation, and circular dependencies. A signal that cannot be measured, such as commit age in a shallow clone, is left out of the total (`Production-grade (5/6 indicators)`). The old score counted only tests, build tools, and cycles, so a 10-year-old v12 library read as "Early-stage (1/3)". The summary also says "an early-stage", not "a early-stage"
+- Entry and barrel file names (`index`, `main`, `mod`, `__init__`) are not domain evidence. `lib/index.ts` is no longer "Search & Discovery". A `domains` hint in `.repolens.yml` still sees the full path
+- "Core/kernel architecture" needs a directory named `core` or `kernel`. A file called `core.ts` does not make it
+- Module descriptions use the module's own name. `lib/ogg` is no longer "Utility and helper functions" because it sits under `lib/`. Unknown folders read "<Name> module", and `common` and `shared` read "Code shared by the other modules"
+- Circular dependencies are listed as a **Finding** in the Architecture Overview (`context.findings`), not as an architectural pattern
+- A package importing its own name (for example `example/*.js` importing `music-metadata`) is not an external dependency. The nearest `package.json` decides, so a nested package still reports the root package as external
+- The "unlock AI" notice lists the sections that were written with rule-based text and says AI can rewrite them. It no longer says written documents, such as Developer Onboarding, are missing
+- Data flows with fewer than 2 steps, chains that start in `doc-gen`, `scripts`, `examples`, `docs`, or `fixtures`, and generic names (`gen`, `util`, `helper`) are dropped
+
+### Dependencies
+
+- `zod` 3.25.76 → 4.6.7 (GHSA-mrhx-c7xc-m3w5) and `npm audit fix` for `body-parser` (GHSA-27r3-jxmh-p828) and `fast-uri`, so the release audit passes again. The MCP server tests pass on zod 4
+- `tests/audit-runtime.test.js` no longer requires the `braces` advisory to be printed. The registry stopped reporting it, and the waiver stays in `scripts/audit-waivers.json`
+
+### Docs
+
+- Added [AI_POLICY.md](AI_POLICY.md) and a pull request template with an AI-assistance disclosure. CONTRIBUTING.md and README.md link to both
+- Roadmap: added Java and C# language support and grounded AI explanations and Q&A as items 2 and 3 of What's Next (docs/ROADMAP.md, README.md, docs/KNOWN_ISSUES.md)
+
 ## 1.15.3
 
 ### Dependency graph

package/README.md

@@ -241,9 +241,9 @@ If `npx` reports `Unknown command: mcp`, an `.npmrc` with `min-release-age` (or
 
 ## GitHub Action
 
-`action.yml` is a composite action named **RepoLens Architecture Docs**. `publish`, `demo`, and `doctor` run the published npm package (`npx --yes @chappibunny/repolens@1.15.3`). `comment` and `badge` run from the action checkout. Inputs are `command` (`publish`, `demo`, `doctor`, `comment`, or `badge`), `config`, `node-version`, `pr-comment`, `version`, `badge-out`, `badge-url`, and `badge-link`.
+`action.yml` is a composite action named **RepoLens Architecture Docs**. `publish`, `demo`, and `doctor` run the published npm package (`npx --yes @chappibunny/repolens@1.15.4`). `comment` and `badge` run from the action checkout. Inputs are `command` (`publish`, `demo`, `doctor`, `comment`, or `badge`), `config`, `node-version`, `pr-comment`, `version`, `badge-out`, `badge-url`, and `badge-link`.
 
-Publishing docs (the npm package at tag `v1.15.3`):
+Publishing docs (the npm package at tag `v1.15.4`):
 
 ```yaml
 name: Architecture docs
@@ -259,7 +259,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.15.3
+      - uses: CHAPIBUNNY/repolens@v1.15.4
         with:
           command: publish
           config: .repolens.yml
@@ -267,7 +267,7 @@ jobs:
           pr-comment: ${{ github.event_name == 'pull_request' && 'true' || 'false' }}
 ```
 
-On `v1.15.2`, `pr-comment: true` runs the architecture diff from the action checkout and turns the published package's older short summary off. The diff lists modules, files, dependencies, the code-health delta, and new hotspots. It edits one sticky comment (`<!-- repolens:architecture-diff -->`) instead of adding a new comment each push. The footer is "Generated by RepoLens" and links to this repository and the [gallery](https://chapibunny.github.io/repolens/). Tag `v1.15.1` does not contain `command: comment`. Pin `v1.15.3` or a commit SHA in production.
+On `v1.15.2`, `pr-comment: true` runs the architecture diff from the action checkout and turns the published package's older short summary off. The diff lists modules, files, dependencies, the code-health delta, and new hotspots. It edits one sticky comment (`<!-- repolens:architecture-diff -->`) instead of adding a new comment each push. The footer is "Generated by RepoLens" and links to this repository and the [gallery](https://chapibunny.github.io/repolens/). Tag `v1.15.1` does not contain `command: comment`. Pin `v1.15.4` or a commit SHA in production.
 
 ```yaml
 name: RepoLens architecture comment
@@ -283,7 +283,7 @@ jobs:
       - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
         with:
           fetch-depth: 0
-      - uses: CHAPIBUNNY/repolens@v1.15.3
+      - uses: CHAPIBUNNY/repolens@v1.15.4
         with:
           command: comment
 ```
@@ -292,7 +292,7 @@ jobs:
 
 `pr-comment: true` on `publish`, `demo`, or `doctor` (when the action ref contains this change) runs the same comment after the package and turns the package's older comment off, so the pull request still gets one comment.
 
-The action is listed on the GitHub Marketplace only after a release is published with **Publish this Action to the GitHub Marketplace** checked. Those steps are in [docs/RELEASE.md](docs/RELEASE.md). The tag `v1.15.3` has to exist before `uses: CHAPIBUNNY/repolens@v1.15.3` resolves, and `@chappibunny/repolens@1.15.3` has to be on npm before `publish` can install it. `command: comment` and `command: badge` do not install that package.
+The action is listed on the GitHub Marketplace only after a release is published with **Publish this Action to the GitHub Marketplace** checked. Those steps are in [docs/RELEASE.md](docs/RELEASE.md). The tag `v1.15.4` has to exist before `uses: CHAPIBUNNY/repolens@v1.15.4` resolves, and `@chappibunny/repolens@1.15.4` has to be on npm before `publish` can install it. `command: comment` and `command: badge` do not install that package.
 
 ## Add the badge to your repo
 
@@ -328,7 +328,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.15.3
+      - uses: CHAPIBUNNY/repolens@v1.15.4
         with:
           command: badge
           badge-url: https://USER.github.io/REPO/repolens-badge.json
@@ -357,7 +357,7 @@ Gallery repositories already publish this. Each one has a [score page](https://c
 
 Published system maps are Unicode diagrams drawn from import edges. RepoLens does not emit Mermaid.
 
-The publisher set is Notion, Confluence, GitHub Wiki, Obsidian, and Markdown (`src/publishers`, 7 files). 1.14.0 adds the MCP server, the Marketplace action, and the docs badge. 1.14.1 sets the registry name to `io.github.CHAPIBUNNY/repolens`. 1.14.2 adds the gallery link to the badge line, `glama.json`, and `CITATION.cff`. 1.14.3 adds Cline setup docs and `llms-install.md`. 1.15.0 detects repository languages in `init --quick`, refuses empty scans, and adds per-command help. 1.15.1 makes `watch` exit 2 when those globs match nothing, and scores code health for Python and Go as well as JavaScript and TypeScript. 1.15.2 reads Python and Go imports in the dependency graph, skips comment and type-only imports, adds `repolens badge` and `repolens comment`, and adds gallery explained pages plus `llms.txt`. 1.15.3 skips Python `TYPE_CHECKING` imports, omits Node.js built-ins from external packages, groups Go hubs by package, and ignores test files as architecture-pattern evidence. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
+The publisher set is Notion, Confluence, GitHub Wiki, Obsidian, and Markdown (`src/publishers`, 7 files). 1.14.0 adds the MCP server, the Marketplace action, and the docs badge. 1.14.1 sets the registry name to `io.github.CHAPIBUNNY/repolens`. 1.14.2 adds the gallery link to the badge line, `glama.json`, and `CITATION.cff`. 1.14.3 adds Cline setup docs and `llms-install.md`. 1.15.0 detects repository languages in `init --quick`, refuses empty scans, and adds per-command help. 1.15.1 makes `watch` exit 2 when those globs match nothing, and scores code health for Python and Go as well as JavaScript and TypeScript. 1.15.2 reads Python and Go imports in the dependency graph, skips comment and type-only imports, adds `repolens badge` and `repolens comment`, and adds gallery explained pages plus `llms.txt`. 1.15.3 skips Python `TYPE_CHECKING` imports, omits Node.js built-ins from external packages, groups Go hubs by package, and ignores test files as architecture-pattern evidence. 1.15.4 names the project from `package.json`, scores maturity from version, history, tests, CI, and docs, reports circular dependencies as findings, drops self-imports and noise data flows, and stops classifying `index` and `core` files by name. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### System Overview (Technical Profile)
 
@@ -431,6 +431,8 @@ When you open a pull request, RepoLens posts:
 - **Build plugins**: Extend RepoLens with custom renderers and publishers
 - **Share feedback**: `npx @chappibunny/repolens feedback`
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) and the [AI Policy](AI_POLICY.md). AI-assisted PRs are welcome when disclosed, reviewed, and tested.
+
 ---
 
 ## 🗺️ Roadmap
@@ -446,6 +448,8 @@ v1.0+ features complete — CLI, config schema, and plugin interface are frozen.
 
 **Next:**
 - [ ] GitHub App for automated setup and status checks
+- [ ] Java and C# language support
+- [ ] Grounded AI explanations and Q&A (`repolens ask`, PR comment, MCP, VS Code hover)
 - [ ] Slack notifications
 - [ ] Custom webhook support
 - [ ] Cross-repository architecture analysis

package/llms-install.md

@@ -19,3 +19,4 @@
 10. `repolens badge` prints a shields.io code-health endpoint. `repolens comment --base <ref> --head <ref>` prints an architecture diff. On GitHub, `command: comment` in `action.yml` posts one sticky pull request comment (`pull-requests: write` only). Fork pull requests get a job summary instead of a comment. These two action modes run from the action checkout. Both CLI commands ship in 1.15.2.
 11. CLI (1.15.2): the dependency graph includes Python and Go imports. Comments, strings, and TypeScript type-only imports are not edges. Go `*_test.go` files are not separate modules. Pattern text cites the matching path or import. "Custom React hooks" requires a `react` import.
 12. CLI (1.15.3): Python imports under `if TYPE_CHECKING:` (including `typing.TYPE_CHECKING` and `import typing as t`) are not cycle edges. Node.js built-ins are not external packages. Go hub rows are packages. Test files are not architecture-pattern evidence, and "API route pattern" requires a route directory.
+13. CLI (1.15.4): the project name comes from `package.json` or the real directory (never `.`). Maturity uses version, history, tests, CI, and docs. Circular dependencies are findings, not architectural patterns. A package's own name is not an external dependency. `index` and `main` files are not classified by name. Noise data flows are dropped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.15.3",
+  "version": "1.15.4",
   "mcpName": "io.github.CHAPIBUNNY/repolens",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
@@ -90,7 +90,7 @@
     "dotenv": "^18.0.8",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.3.2",
-    "zod": "3.25.76"
+    "zod": "4.6.7"
   },
   "optionalDependencies": {
     "@sentry/node": "^10.42.0"

package/src/ai/generate-sections.js

@@ -12,7 +12,8 @@ import {
   AI_SCHEMAS,
   renderStructuredToMarkdown,
 } from "./prompts.js";
-import { identifyFlowDependencies } from "../analyzers/flow-inference.js";
+import { identifyFlowDependencies, filterNoiseFlows } from "../analyzers/flow-inference.js";
+import { scoreMaturity } from "../analyzers/maturity.js";
 import { info, warn } from "../utils/logger.js";
 
 // Strip conversational patterns that LLMs sometimes inject into documentation
@@ -152,6 +153,10 @@ export async function generateDeveloperOnboarding(context, enrichment = {}, conf
 
 // Fallback generators (deterministic, no AI)
 
+function withArticle(word) {
+  return `${/^[aeiou]/i.test(word) ? "an" : "a"} ${word}`;
+}
+
 function getFallbackExecutiveSummary(context, enrichment = {}) {
   const { depGraph, flows } = enrichment;
   const frameworkList = context.techStack.frameworks.join(", ") || "general-purpose";
@@ -160,12 +165,17 @@ function getFallbackExecutiveSummary(context, enrichment = {}) {
   const isCLI = (context.patterns || []).some(p => p.toLowerCase().includes("cli"));
   const projectName = context.project.name || "This system";
 
-  // Calculate maturity indicators
+  // Maturity comes from repo signals (version, history, tests, CI, docs, dependency health)
+  const maturity = context.maturity || scoreMaturity([
+    { key: "tests", met: testFrameworks.length > 0 },
+    { key: "build", met: context.techStack.buildTools.length > 0 },
+    { key: "deps", met: depGraph?.stats?.cycles === undefined ? null : depGraph.stats.cycles === 0 },
+  ]);
   const hasTests = testFrameworks.length > 0;
-  const hasBuildTools = context.techStack.buildTools.length > 0;
   const hasCleanDeps = depGraph?.stats?.cycles === 0;
-  const maturityScore = [hasTests, hasBuildTools, hasCleanDeps].filter(Boolean).length;
-  const maturityLabel = maturityScore >= 3 ? "Production-grade" : maturityScore >= 2 ? "Well-structured" : "Early-stage";
+  const maturityLabel = maturity.label;
+  const maturityScore = maturity.score;
+  const maturityMax = maturity.max;
 
   // Determine project type for better descriptions
   const projectType = isCLI ? "command-line tool" : 
@@ -179,10 +189,10 @@ function getFallbackExecutiveSummary(context, enrichment = {}) {
 
 | Aspect | Summary |
 |--------|---------|
-| **What** | ${projectName} is a ${maturityLabel.toLowerCase()} ${projectType} |
+| **What** | ${projectName} is ${withArticle(maturityLabel.toLowerCase())} ${projectType} |
 | **Built With** | ${frameworkList} + ${languageList} |
 | **Scale** | ${context.project.modulesDetected} modules across ${context.project.filesScanned} files |
-| **Maturity** | ${maturityLabel} (${maturityScore}/3 indicators) |
+| **Maturity** | ${maturityLabel} (${maturityScore}/${maturityMax} indicators) |
 
 ---
 
@@ -296,7 +306,7 @@ The system is organized around **${context.domains.length} functional domains**,
   }
 
   // Data flows summary
-  const summaryFlows = (flows || []).filter(f => !f.name?.toLowerCase().includes('test'));
+  const summaryFlows = filterNoiseFlows(flows).filter(f => !f.name?.toLowerCase().includes('test'));
   if (summaryFlows.length > 0) {
     output += `\n## Key Data Flows\n\n`;
     output += `The system processes information through **${summaryFlows.length} identified flow${summaryFlows.length === 1 ? "" : "s"}**:\n\n`;
@@ -705,6 +715,14 @@ function getFallbackArchitectureOverview(context, enrichment = {}) {
     output += `- Flexibility for rapid development\n\n`;
   }
 
+  // Findings are warnings about the code, not architectural patterns
+  const findings = context.findings || [];
+  if (findings.length > 0) {
+    output += `### Findings\n\n`;
+    for (const finding of findings) output += `- ${finding}\n`;
+    output += `\n`;
+  }
+
   // System layers with rich descriptions
   output += `## System Layers\n\n`;
   output += `The system is organized into **${context.domains.length} functional layer${context.domains.length === 1 ? '' : 's'}**, each encapsulating a distinct area of responsibility:\n\n`;
@@ -914,11 +932,11 @@ Data flows describe how information moves through **${projectName}** — from ex
 `;
 
   // Combine heuristic flows with dep-graph-derived flows, filtering out test file flows
-  const allFlows = [...(flows || [])].filter(f => !f.name?.toLowerCase().includes('test'));
+  const allFlows = filterNoiseFlows(flows).filter(f => !f.name?.toLowerCase().includes('test'));
 
   // Generate additional flows from dependency graph hub chains
   if (depGraph?.nodes && depGraph.nodes.length > 0 && allFlows.length < 3) {
-    const hubFlows = inferFlowsFromDepGraph(depGraph);
+    const hubFlows = filterNoiseFlows(inferFlowsFromDepGraph(depGraph));
     for (const hf of hubFlows) {
       if (!allFlows.some(f => f.name === hf.name)) {
         allFlows.push(hf);
@@ -1274,7 +1292,7 @@ ${context.repoRoots.map(root => {
   }
 
   // Data flows for understanding behavior
-  const onboardingFlows = (flows || []).filter(f => !f.name?.toLowerCase().includes('test'));
+  const onboardingFlows = filterNoiseFlows(flows).filter(f => !f.name?.toLowerCase().includes('test'));
   if (onboardingFlows.length > 0) {
     output += `---\n\n## How Data Flows\n\n`;
     output += `Understanding these flows helps you see how the system processes information end-to-end:\n\n`;
@@ -1459,27 +1477,53 @@ function describeRoot(root) {
   return "Project files";
 }
 
+// Folder names that only say "code lives here". They never describe a module on their own.
+const GENERIC_CONTAINER_SEGMENTS = new Set(["src", "lib", "libs", "source", "sources", "app", "packages", "pkg", "internal"]);
+
+const MODULE_DESCRIPTION_RULES = [
+  [/auth/, "Authentication and authorization logic"],
+  [/api|route|endpoint/, "API layer and route handlers"],
+  [/component|widget|^ui$/, "User interface components"],
+  [/hook/, "Custom hooks and shared state logic"],
+  [/util|helper/, "Utility and helper functions"],
+  [/^(common|shared)$/, "Code shared by the other modules"],
+  [/service/, "Service layer / business logic"],
+  [/model|schema|entity/, "Data models and schemas"],
+  [/config|setting/, "Configuration management"],
+  [/test|spec/, "Test infrastructure"],
+  [/style|css|theme/, "Styling and theming"],
+  [/page|view|screen/, "Application pages and views"],
+  [/store|state|redux/, "State management"],
+  [/middleware/, "Request/response middleware"],
+  [/database|^db$|migration/, "Database layer"],
+  [/render/, "Rendering and template logic"],
+  [/publish/, "Publishing and output delivery"],
+  [/scan/, "File and repository scanning"],
+  [/analyz/, "Code analysis and inference"],
+];
+
+function titleizeSegment(segment) {
+  const clean = String(segment).replace(/\.[a-z0-9]+$/i, "").replace(/[-_]+/g, " ").trim();
+  return clean ? clean.charAt(0).toUpperCase() + clean.slice(1) : "Project";
+}
+
 function describeOnboardingModule(key) {
-  const lower = key.toLowerCase();
-  if (/auth/.test(lower)) return "Authentication and authorization logic";
-  if (/api|route|endpoint/.test(lower)) return "API layer and route handlers";
-  if (/component|widget|ui/.test(lower)) return "User interface components";
-  if (/hook/.test(lower)) return "Custom hooks and shared state logic";
-  if (/util|helper|lib/.test(lower)) return "Utility and helper functions";
-  if (/service/.test(lower)) return "Service layer / business logic";
-  if (/model|schema|entity/.test(lower)) return "Data models and schemas";
-  if (/config|setting/.test(lower)) return "Configuration management";
-  if (/test|spec/.test(lower)) return "Test infrastructure";
-  if (/style|css|theme/.test(lower)) return "Styling and theming";
-  if (/page|view|screen/.test(lower)) return "Application pages and views";
-  if (/store|state|redux/.test(lower)) return "State management";
-  if (/middleware/.test(lower)) return "Request/response middleware";
-  if (/database|db|migration/.test(lower)) return "Database layer";
-  if (/render/.test(lower)) return "Rendering and template logic";
-  if (/publish/.test(lower)) return "Publishing and output delivery";
-  if (/scan/.test(lower)) return "File and repository scanning";
-  if (/analyz/.test(lower)) return "Code analysis and inference";
-  return "Core application module";
+  const segments = String(key).replace(/\\/g, "/").toLowerCase().split("/").filter(Boolean);
+  const last = (segments[segments.length - 1] || "").replace(/\.[a-z0-9]+$/i, "");
+  const parents = segments.slice(0, -1).filter((segment) => !GENERIC_CONTAINER_SEGMENTS.has(segment));
+
+  // The module's own name decides first. A parent folder like `lib/` is only a container,
+  // so `lib/ogg` is not "utility functions" just because it lives under lib.
+  for (const [pattern, description] of MODULE_DESCRIPTION_RULES) {
+    if (pattern.test(last)) return description;
+  }
+  if (GENERIC_CONTAINER_SEGMENTS.has(last) && segments.length === 1) return "Application source code";
+  for (const segment of parents) {
+    for (const [pattern, description] of MODULE_DESCRIPTION_RULES) {
+      if (pattern.test(segment)) return description;
+    }
+  }
+  return `${titleizeSegment(last || key)} module`;
 }
 
 // Helper: infer business capability from domain name

package/src/analyzers/context-builder.js

@@ -159,6 +159,8 @@ export function buildAIContext(scanResult, config, depGraph = null) {
     techStack,
     
     patterns,
+
+    findings: inferFindings(depGraph),
     
     repoRoots: config.module_roots || [],
 
@@ -271,7 +273,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 +310,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")) {
@@ -354,14 +362,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

@@ -156,6 +156,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 +197,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);
       }
     }
   }

package/src/analyzers/domain-inference.js

@@ -171,13 +171,33 @@ 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("/");
+}
+
 export function inferDomain(modulePath, customHints = [], evidence = {}) {
+  const customSet = new Set(customHints);
   const hints = [...customHints, ...DEFAULT_DOMAIN_HINTS];
+  const defaultPath = stripEntryFileName(modulePath);
 
   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),

package/src/analyzers/flow-inference.js

@@ -4,6 +4,41 @@
  * Primary flow inference: uses dep graph when available for real import-chain flows,
  * falls back to keyword heuristics for repos without dep graph data.
  */
+// Directories holding tooling, samples, and docs. An import chain from a file in
+// here describes a build script or an example, not how data moves through the product.
+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",
+]);
+
+// 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",
+]);
+
+function isToolingPath(key) {
+  const parts = String(key || "").replace(/\\/g, "/").toLowerCase().split("/");
+  return parts.slice(0, -1).some((segment) => TOOLING_DIRECTORIES.has(segment));
+}
+
+/**
+ * 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 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)) 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 +63,7 @@ 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);
 }
 
 /**

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/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/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);

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/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/project-name.js

@@ -0,0 +1,24 @@
+// Resolve a human project name for a directory (never "." or "..")
+
+import fs from "node:fs";
+import path from "node:path";
+
+function packageJsonName(dir) {
+  try {
+    const raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+    const name = JSON.parse(raw)?.name;
+    if (typeof name === "string" && name.trim() && name.length <= 214) return name.trim();
+  } catch {
+    // no package.json or not valid JSON
+  }
+  return null;
+}
+
+/**
+ * Name for a project directory. `--target .` resolves to the real directory,
+ * and a package.json name wins over the folder name when there is one.
+ */
+export function detectProjectName(dir, fallback = "my-project") {
+  const resolved = path.resolve(dir || ".");
+  return packageJsonName(resolved) || path.basename(resolved) || fallback;
+}