@chappibunny/repolens 1.16.1 → 1.16.3

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.16.3 (2026-11-11)
+
+Fixes found by the 2026-11-11 gap test of 1.16.2 on trpc/trpc, App-vNext/Polly, google/gson, charmbracelet/glow, and pallets/itsdangerous.
+
+### Upgrade notes (read before publishing docs)
+
+- **Monorepo graphs change.** Imports between declared workspace packages are now edges, not external packages. Expect higher edge counts, fewer orphans, new Hub Modules, fewer external packages, and different module roles on the first run after upgrading. On trpc/trpc: 913 → 1,533 edges, orphans 254 → 126, external packages 95 → 89. If you keep an architecture baseline, the next drift report lists these as changes; they are a measurement fix, not a code change.
+- **`repolens badge` can now exit 2 where it used to print a score.** A repository whose product source has no JavaScript/TypeScript, Python, or Go (only a docs script, test helper, or vendored copy) is reported as unsupported; App-vNext/Polly used to get a false "100". A repository where those languages are under 10% of product source files also exits 2, because one number would not stand for it. CI steps that publish the badge should tolerate exit 2 or skip the badge for such repositories. Vue (`.vue`) and Svelte (`.svelte`) component files are not analyzed (no imports, complexity, or health from them), but they do not count toward that 10% share: a component library with a few `.ts` files and many components still gets a badge, scored on its JavaScript/TypeScript only, with a partial-coverage warning on stderr and in the docs naming the component files that were not analyzed.
+- **Empty pages are no longer written.** API Surface (no routes, no external API integrations, no documented exports) and GraphQL Schema (no real GraphQL evidence) are skipped unless `documentation.sections` lists them. Pages published by earlier versions to Notion, Confluence, GitHub Wiki, or Obsidian are not deleted: they stay as last published until you remove them. The Markdown publisher overwrites files but does not delete an old `06-api-surface.md` or `11-graphql-schema.md` in the output directory.
+- **GraphQL detection is narrower.** Libraries count only when imported. A bare mention of "hasura" in code or comments no longer reports Hasura; a `hasura/config.yaml` (or root `config.yaml`) with `metadata_directory`, or an `@hasura/*` / `hasura-*` import, does.
+
+### Dependency graph
+
+- Workspace packages are internal. Members come only from declarations: root `package.json` `workspaces` (array or `{ packages }`, `!` exclusions honoured), `pnpm-workspace.yaml` `packages`, and `lerna.json` `packages`. A stray `package.json` (a test stub named `express`, a fixture) is not a workspace member. An import of `@scope/pkg` or `@scope/pkg/subpath` naming a member resolves to its source through `exports`, `main`, or `src/`, with `dist/`, `lib/`, and `build/` targets mapped back to `src/`. Targets and subpaths that leave the package (`..`, absolute paths, URLs, wildcards) are ignored. A dependency declared as `npm:alias@version` stays external. On trpc/trpc `@trpc/*` is gone from external packages, a Hub Modules section appears, and `packages/server` reads "Shared infrastructure (imported by 7 modules)" instead of "Connector (1 in, 2 out)". The MCP `get_dependency_graph` tool uses the same graph.
+- Flow steps name a package entry `server/src` rather than a bare `src`.
+
+### Language coverage
+
+- The dependency graph and code health cover JavaScript/TypeScript, Python, and Go. Coverage is measured on product source: tests, docs, tooling, examples, and vendored trees (`vendor`, `third_party`, `deps`, `external`, and similar) do not count.
+- No supported product code at all: graph and health pages say the language is not supported yet instead of building a graph or score from a docs script. Polly no longer reports "no circular dependencies" and "Average health 100/100"; gson names Java/Kotlin instead of telling the user to check `scan.include`.
+- Supported product code next to other languages (for example 5 Python files and 80 Rust files): the graph and health are built for the supported files, and the dependency graph, code health, executive summary, system overview, and architecture overview all say "Partial coverage: … covers N of M product source files". Cycle claims read "among analyzed files", and "Acyclic dependency graph" is not listed as a pattern.
+- `repolens badge` counts every source file in one walk (up to 20,000, with a note when that limit is hit) and analyzes up to 2,500, so the coverage ratio is not skewed by the analysis cap.
+- `demo --help`, `init --help`, and the README say detection is not full analysis.
+- The language list is ordered by file count (Polly reads "C#, JavaScript"), and a statically typed primary language is no longer described as "Dynamic typing".
+
+### Output accuracy
+
+- GraphQL libraries are detected from imports. SDL and resolver maps are read after a comment stripper that keeps strings, template literals (including `${}` expressions), and regex literals, so `'src/*.graphql'` or `' // '` in a string no longer erases real SDL. Comments that mention Apollo or urql and React Query `useQuery:` hook maps no longer produce a GraphQL page; trpc/trpc's `11-graphql-schema.md` is skipped.
+- A module whose files are mostly tests says so ("Mostly tests and fixtures (204 of 212 files)") instead of "Application module".
+- When API Surface is written with no routes, it no longer blames `scan.include`.
+
+## 1.16.2
+
+### Branding
+
+- New RepoLens icon: emerald rounded tile with a camera aperture and a white git-branch glyph, transparent background. Replaces `assets/logo-400.png`, `assets/Avatar.png` and the gallery `gallery/assets/logo.png` (512x512).
+- The gallery site adds `favicon.ico` (16 and 32 px) next to the PNG icon.
+- The VS Code extension (0.2.4) uses the same icon.
+
 ## 1.16.1
 
 Fixes three problems found by running 1.16.0 on orval-labs/orval (a TypeScript monorepo whose test snapshots and samples dwarf the packages).

package/README.md

@@ -29,7 +29,7 @@ RepoLens scans your repository, generates living architecture documentation, and
 
 ## 🎬 Demo
 
-> **Try it now** — no installation required. `npx @chappibunny/repolens demo` previews the repository you point it at. It detects common languages (Python, Go, Rust, Java, JavaScript/TypeScript, and others). If the scan matches no source files, demo exits 2 and does not write empty docs. Code health scores JavaScript/TypeScript, Python, and Go.
+> **Try it now** — no installation required. `npx @chappibunny/repolens demo` previews the repository you point it at. It detects common languages (Python, Go, Rust, Java, JavaScript/TypeScript, and others) and maps their modules and file structure. If the scan matches no source files, demo exits 2 and does not write empty docs. The dependency graph and code health cover JavaScript/TypeScript, Python, and Go only; a Java, Kotlin, or C# repository gets a "not supported yet" note on those pages, not a score.
 
 **[See it on real repos](https://chapibunny.github.io/repolens/)** — architecture pages RepoLens generated for Express, FastAPI, Django, Gin, mdBook, and other public projects. Deterministic mode, no API keys.
 
@@ -243,9 +243,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 --force --yes @chappibunny/repolens@1.16.1`). `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`. The action passes `--force` so a repository `devEngines` pin does not stop `npx` on npm versions that enforce `devEngines` (newer npm). Node 20's bundled npm does not enforce that field. From a shell, use the same flag: `npx --force --yes @chappibunny/repolens demo`. `--ignore-engines` does not skip `devEngines`.
+`action.yml` is a composite action named **RepoLens Architecture Docs**. `publish`, `demo`, and `doctor` run the published npm package (`npx --force --yes @chappibunny/repolens@1.16.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`. The action passes `--force` so a repository `devEngines` pin does not stop `npx` on npm versions that enforce `devEngines` (newer npm). Node 20's bundled npm does not enforce that field. From a shell, use the same flag: `npx --force --yes @chappibunny/repolens demo`. `--ignore-engines` does not skip `devEngines`.
 
-Publishing docs (the npm package at tag `v1.16.1`):
+Publishing docs (the npm package at tag `v1.16.3`):
 
 ```yaml
 name: Architecture docs
@@ -261,7 +261,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.16.1
+      - uses: CHAPIBUNNY/repolens@v1.16.3
         with:
           command: publish
           config: .repolens.yml
@@ -269,7 +269,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.16.1` 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.16.3` or a commit SHA in production.
 
 ```yaml
 name: RepoLens architecture comment
@@ -285,7 +285,7 @@ jobs:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
-      - uses: CHAPIBUNNY/repolens@v1.16.1
+      - uses: CHAPIBUNNY/repolens@v1.16.3
         with:
           command: comment
 ```
@@ -294,7 +294,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.16.1` has to exist before `uses: CHAPIBUNNY/repolens@v1.16.1` resolves, and `@chappibunny/repolens@1.16.1` 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.16.3` has to exist before `uses: CHAPIBUNNY/repolens@v1.16.3` resolves, and `@chappibunny/repolens@1.16.3` 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
 
@@ -330,7 +330,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: CHAPIBUNNY/repolens@v1.16.1
+      - uses: CHAPIBUNNY/repolens@v1.16.3
         with:
           command: badge
           badge-url: https://USER.github.io/REPO/repolens-badge.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.16.1",
+  "version": "1.16.3",
   "mcpName": "io.github.CHAPIBUNNY/repolens",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",

package/src/ai/generate-sections.js

@@ -1,5 +1,13 @@
 // Generate documentation sections using AI
 
+import { coverageLine, coverageNotice, coverageScope } from "../analyzers/language-coverage.js";
+
+// Partial language coverage is stated next to every graph-based score, so a Rust or
+// C# majority never inherits "clean boundaries" from the JavaScript/Python/Go part.
+function coverageBanner(depGraph) {
+  const lines = coverageNotice(depGraph?.coverage, "import analysis");
+  return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
 import { generateText, isAIEnabled } from "./provider.js";
 import { 
   SYSTEM_PROMPT, 
@@ -285,6 +293,7 @@ The system is organized around **${context.domains.length} functional domains**,
     const healthEmoji = healthScore >= 80 ? "🟢" : healthScore >= 60 ? "🟡" : "🔴";
     
     output += `**Overall Health: ${healthEmoji} ${healthScore}/100**\n\n`;
+    output += coverageBanner(depGraph);
     output += `| Metric | Value | Status |\n`;
     output += `|--------|-------|--------|\n`;
     output += `| Internal imports | ${stats.totalEdges} edges | ${stats.totalEdges > 0 ? "✅ Connected" : "⚠️ Isolated"} |\n`;
@@ -296,7 +305,7 @@ The system is organized around **${context.domains.length} functional domains**,
     // Key insights
     output += `\n### Key Insights\n\n`;
     if (stats.cycles === 0) {
-      output += `- ✅ **Clean module boundaries** — No circular dependencies detected, enabling safe refactoring and testing.\n`;
+      output += `- ✅ **Clean module boundaries** — No circular dependencies detected${coverageScope(depGraph.coverage)}, enabling safe refactoring and testing.\n`;
     } else {
       output += `- ${cycleInsight(stats)}\n`;
     }
@@ -311,6 +320,8 @@ The system is organized around **${context.domains.length} functional domains**,
     if (orphanRatio(stats) > ORPHAN_WARN_RATIO) {
       output += `- ⚠️ **Potential dead code** — ${stats.orphanFiles} files (${Math.round(stats.orphanFiles / stats.totalFiles * 100)}%) are not imported anywhere.\n`;
     }
+  } else if (depGraph?.coverage?.status === "unsupported") {
+    output += `Import-graph health is not available: ${coverageLine(depGraph.coverage, "import analysis")}\n`;
   }
 
   // Data flows summary
@@ -525,11 +536,12 @@ The system is built on a modern technology foundation:\n\n`;
     
     output += `## Dependency Graph\n\n`;
     output += `**Codebase Health: ${healthEmoji} ${healthScore}/100**\n\n`;
+    output += coverageBanner(depGraph);
     output += `| Metric | Value | Assessment |\n`;
     output += `|--------|-------|------------|\n`;
     output += `| Internal Imports | ${stats.totalEdges} | ${stats.totalEdges > 0 ? "Modules are connected" : "No internal imports"} |\n`;
     output += `| External Packages | ${externalPackagesLabel(stats)} | ${stats.externalDeps < 50 ? "Lean dependencies" : stats.externalDeps < 100 ? "Moderate dependencies" : "Many dependencies"} |\n`;
-    output += `| Circular Dependencies | ${stats.cycles} | ${stats.cycles === 0 ? "✅ Clean" : "⚠️ Needs attention"} |\n`;
+    output += `| Circular Dependencies | ${stats.cycles} | ${stats.cycles === 0 ? `✅ Clean${coverageScope(depGraph.coverage)}` : "⚠️ Needs attention"} |\n`;
     output += `| Orphan Files | ${stats.orphanFiles} | ${orphanStatus(stats)} |\n`;
     
     if (stats.hubs && stats.hubs.length > 0) {
@@ -825,20 +837,21 @@ function getFallbackArchitectureOverview(context, enrichment = {}) {
     
     output += `\n## Dependency Health\n\n`;
     output += `**Architecture Health Score: ${healthEmoji} ${healthScore}/100**\n\n`;
+    output += coverageBanner(depGraph);
     
     output += `| Metric | Value | Status | Recommendation |\n`;
     output += `|--------|-------|--------|----------------|\n`;
     output += `| Import Edges | ${stats.totalEdges} | ${stats.totalEdges > 0 ? "✅" : "⚠️"} | ${stats.totalEdges > 0 ? "Healthy module connectivity" : "Consider connecting modules"} |\n`;
     output += `| External Packages | ${externalPackagesLabel(stats)} | ${stats.externalDeps < 50 ? "✅" : stats.externalDeps < 100 ? "⚠️" : "🔴"} | ${stats.externalDeps >= 100 ? "Audit for unused dependencies" : stats.externalDeps >= 50 ? "Review dependency necessity" : "Lean dependency set"} |\n`;
     const archCycle = cycleStatusCell(stats);
-    output += `| Circular Deps | ${stats.cycles} | ${stats.cycles === 0 ? "✅" : archCycle.mark} | ${stats.cycles === 0 ? "Clean module boundaries" : archCycle.advice} |\n`;
+    output += `| Circular Deps | ${stats.cycles} | ${stats.cycles === 0 ? "✅" : archCycle.mark} | ${stats.cycles === 0 ? `Clean module boundaries${coverageScope(depGraph.coverage)}` : archCycle.advice} |\n`;
     output += `| Orphan Files | ${stats.orphanFiles} | ${orphanRatio(stats) > ORPHAN_WARN_RATIO ? "⚠️" : "✅"} | ${stats.orphanFiles === 0 ? "All code is connected" : orphanRatio(stats) > ORPHAN_WARN_RATIO ? "Review for dead code" : "A few unconnected files (examples, type tests, entry points) are normal"} |\n`;
 
     // Architectural strengths and concerns
     output += `\n### Architectural Strengths\n\n`;
     const strengths = [];
     if (stats.cycles === 0) {
-      strengths.push("**Clean module boundaries** — No circular dependencies detected. This enables safe refactoring, isolated testing, and clear ownership boundaries.");
+      strengths.push(`**Clean module boundaries** — No circular dependencies detected${coverageScope(depGraph.coverage)}. This enables safe refactoring, isolated testing, and clear ownership boundaries.`);
     }
     if (stats.orphanFiles === 0) {
       strengths.push("**Fully connected codebase** — Every file is part of the dependency graph. No dead code or forgotten modules.");
@@ -1780,8 +1793,13 @@ function getFrameworkArchitecturalImplication(frameworks) {
 }
 
 // Helper: architectural implication of languages
+// Languages arrive most-files-first, so the first one is the primary language. A C#
+// repository with one docs script is not "dynamic typing".
+const STATIC_PRIMARY = new Set(["c#", "java", "kotlin", "scala", "swift", "c", "c++"]);
+
 function getLanguageImplication(languages) {
   const langs = (languages || []).map(l => l.toLowerCase());
+  if (STATIC_PRIMARY.has(langs[0])) return "Static typing; compiled language";
   if (langs.includes("typescript")) return "Static typing enables tooling and refactoring confidence";
   if (langs.includes("javascript")) return "Dynamic typing, flexible but requires discipline";
   if (langs.includes("python")) return "Readable syntax, rich ecosystem";
@@ -1892,6 +1910,7 @@ function getFrameworkLearningTip(frameworks) {
 // Helper: language learning tip
 function getLanguageLearningTip(languages) {
   const langs = (languages || []).map(l => l.toLowerCase());
+  if (STATIC_PRIMARY.has(langs[0])) return "Strong typing — let the compiler and IDE guide navigation";
   if (langs.includes("typescript")) return "Strong typing — check types when debugging";
   if (langs.includes("javascript")) return "Dynamic typing — use console.log for runtime inspection";
   if (langs.includes("python")) return "Read docstrings and type hints";

package/src/analyzers/complexity-analyzer.js

@@ -3,6 +3,7 @@
 // (dep graph, JSDoc, security) into a per-module health score.
 
 import fs from "node:fs/promises";
+import { computeLanguageCoverage, coverageLine, filesForAnalysis, unanalyzedLanguageNames } from "./language-coverage.js";
 import path from "node:path";
 import { info } from "../utils/logger.js";
 
@@ -250,8 +251,9 @@ function functionsForLanguage(language, source) {
  * @param {string} repoRoot - Absolute path to repo root
  * @returns {Promise<Object>} Complexity analysis results
  */
-export async function analyzeComplexity(files, repoRoot) {
-  const sourceFiles = files
+export async function analyzeComplexity(files, repoRoot, { coverageFiles = files } = {}) {
+  const coverage = computeLanguageCoverage(coverageFiles || files);
+  const sourceFiles = filesForAnalysis(files, coverage)
     .filter(f => languageForFile(f))
     .filter(f => !shouldSkip(f));
 
@@ -259,6 +261,7 @@ export async function analyzeComplexity(files, repoRoot) {
     files: [],
     functions: [],
     filesAnalyzed: sourceFiles.length,
+    coverage,
   };
 
   for (const file of sourceFiles) {
@@ -411,11 +414,20 @@ export function computeCodeHealth(complexityResult, depGraph, jsdocResult, secur
 
   const hotspots = modules.filter(m => m.score < 60).slice(0, 20);
 
-  const summary = totalFiles > 0
+  const coverage = complexityResult.coverage || null;
+  let summary = totalFiles > 0
     ? `${totalFiles} files analyzed · Average health: ${avgScore}/100 · ${gradeDistribution.A} A, ${gradeDistribution.B} B, ${gradeDistribution.C} C, ${gradeDistribution.D} D, ${gradeDistribution.F} F`
     : "No source files analyzed.";
+  if (totalFiles > 0 && coverage?.status === "partial") {
+    summary += ` · ${unanalyzedLanguageNames(coverage)} not scored`;
+  }
+  if (totalFiles === 0 && coverage?.status === "unsupported") {
+    summary = `Not scored: ${coverageLine(coverage, "code health")}`;
+  }
 
-  if (totalFiles === 0) {
+  if (totalFiles === 0 && coverage?.status === "unsupported") {
+    info(`Code health: not scored — ${coverageLine(coverage, "code health")}`);
+  } else if (totalFiles === 0) {
     info("Code health: no source files analyzed.");
   } else {
     info(`Code health: avg ${avgScore}/100 across ${totalFiles} files (${hotspots.length} hotspots)`);
@@ -424,6 +436,7 @@ export function computeCodeHealth(complexityResult, depGraph, jsdocResult, secur
   return {
     modules,
     summary,
+    coverage,
     stats: {
       totalFiles,
       avgScore,

package/src/analyzers/context-builder.js

@@ -406,7 +406,8 @@ function inferArchitecturalPatterns(modules, depGraph = null, projectKind = null
 
   // Structural patterns from dep graph (not keyword-based)
   if (depGraph?.stats) {
-    if (depGraph.stats.cycles === 0 && depGraph.stats.totalEdges > 10) {
+    // Only a fully analyzed codebase can be called acyclic.
+    if (depGraph.stats.cycles === 0 && depGraph.stats.totalEdges > 10 && depGraph.coverage?.status !== "partial") {
       patterns.push("Acyclic dependency graph — clean layering");
     }
   }

package/src/analyzers/dependency-graph.js

@@ -19,6 +19,8 @@ import {
   parseGoModule,
 } from "./import-parsers.js";
 import { isNonProductPath } from "../utils/path-roles.js";
+import { computeLanguageCoverage, coverageLine } from "./language-coverage.js";
+import { listWorkspacePackages } from "./workspace-packages.js";
 import {
   classifyRuntimeCycles,
   priorityCounts,
@@ -72,6 +74,77 @@ function normalizeFileKey(file) {
   return key;
 }
 
+// Source-tree candidates for `pkg` or `pkg/subpath` inside a workspace package.
+// `exports`/`main` usually point at build output (dist/, lib/, build/), so those
+// paths are mapped back to src/ as well as tried as written.
+function workspaceCandidates(pkg, subpath) {
+  const base = pkg.dir ? `${pkg.dir}/` : "";
+  const out = [];
+  const push = (rel) => {
+    if (typeof rel !== "string" || !rel) return;
+    let clean = rel.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    // exports/main targets must stay inside the package: no absolute paths, no `..`,
+    // no wildcards or URLs.
+    if (clean.startsWith("/") || /^[A-Za-z]:/.test(clean) || clean.includes("*") || clean.includes(":")) return;
+    if (clean.split("/").includes("..")) return;
+    clean = clean.replace(/\.d\.[cm]?ts$/, "").replace(/\.(js|ts|jsx|tsx|mjs|cjs)$/, "");
+    if (!clean || clean === ".") {
+      out.push(pkg.dir || ".");
+      return;
+    }
+    out.push(`${base}${clean}`);
+    const mapped = clean.replace(/^(dist|lib|build|out|esm|cjs)(\/(esm|cjs|es|src))?\//, "src/");
+    if (mapped !== clean) out.push(`${base}${mapped}`);
+  };
+  const manifest = pkg.manifest || {};
+  const exportKey = subpath ? `./${subpath}` : ".";
+  const exportsField = manifest.exports;
+  let target = null;
+  if (typeof exportsField === "string" && !subpath) target = exportsField;
+  else if (exportsField && typeof exportsField === "object") {
+    const entry = exportKey in exportsField ? exportsField[exportKey] : (!subpath && !Object.keys(exportsField).some((k) => k.startsWith(".")) ? exportsField : undefined);
+    target = pickExportTarget(entry);
+  }
+  if (target) push(target);
+  if (subpath) {
+    push(`src/${subpath}`);
+    push(subpath);
+    push(`lib/${subpath}`);
+  } else {
+    for (const field of ["source", "module", "main"]) {
+      if (typeof manifest[field] === "string") push(manifest[field]);
+    }
+    push("src/index");
+    push("index");
+    push("lib/index");
+  }
+  return out;
+}
+
+function pickExportTarget(entry) {
+  if (typeof entry === "string") return entry;
+  if (Array.isArray(entry)) {
+    for (const item of entry) {
+      const found = pickExportTarget(item);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (entry && typeof entry === "object") {
+    for (const condition of ["source", "development", "import", "module", "default", "require", "node", "types"]) {
+      if (condition in entry) {
+        const found = pickExportTarget(entry[condition]);
+        if (found) return found;
+      }
+    }
+    for (const value of Object.values(entry)) {
+      const found = pickExportTarget(value);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
 function emptyResult() {
   return {
     nodes: [],
@@ -151,8 +224,14 @@ function goFilesInDir(goFiles, dir) {
   });
 }
 
-export async function analyzeDependencyGraph(files, repoRoot) {
+export async function analyzeDependencyGraph(files, repoRoot, { coverageFiles = files } = {}) {
   const result = emptyResult();
+  const coverage = computeLanguageCoverage(coverageFiles || files);
+  result.coverage = coverage;
+  if (coverage.status === "unsupported") {
+    info(`Dependency graph: not built — ${coverageLine(coverage, "import analysis")}`);
+    return result;
+  }
 
   const jsFiles = files.filter((file) => JS_EXTENSIONS.has(path.extname(file)));
   const pyFiles = files.filter((file) => PY_EXTENSIONS.has(path.extname(file)));
@@ -191,38 +270,66 @@ export async function analyzeDependencyGraph(files, repoRoot) {
 
   // 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 packageByDir = new Map();
+  async function ownPackage(file) {
+    let dir = path.posix.dirname(String(file).replace(/\\/g, "/"));
     const visited = [];
     for (;;) {
-      if (packageNameByDir.has(dir)) {
-        const cached = packageNameByDir.get(dir);
-        for (const d of visited) packageNameByDir.set(d, cached);
+      if (packageByDir.has(dir)) {
+        const cached = packageByDir.get(dir);
+        for (const d of visited) packageByDir.set(d, cached);
         return cached;
       }
       visited.push(dir);
       const raw = await readFileSafe(path.join(repoRoot, dir, "package.json"));
       if (raw) {
-        let name = null;
+        let found = null;
         try {
           const parsed = JSON.parse(raw);
-          if (typeof parsed?.name === "string") name = parsed.name;
+          if (typeof parsed?.name === "string" && parsed.name) found = { name: parsed.name, manifest: parsed };
         } catch {
           // invalid package.json: keep walking up
         }
-        if (name) {
-          for (const d of visited) packageNameByDir.set(d, name);
-          return name;
+        if (found) {
+          for (const d of visited) packageByDir.set(d, found);
+          return found;
         }
       }
-      if (dir === "." || dir === "" || dir === path.dirname(dir)) break;
-      dir = path.dirname(dir);
+      if (dir === "." || dir === "" || dir === path.posix.dirname(dir)) break;
+      dir = path.posix.dirname(dir);
     }
-    for (const d of visited) packageNameByDir.set(d, null);
+    for (const d of visited) packageByDir.set(d, null);
     return null;
   }
 
+  // Declared workspace members only (package.json workspaces, pnpm-workspace.yaml,
+  // lerna.json). In a monorepo, `@scope/pkg` naming a member is an internal edge.
+  const workspacePackages = new Map();
+  if (jsFiles.length > 0) {
+    const { packages } = await listWorkspacePackages(repoRoot);
+    for (const pkg of packages) workspacePackages.set(pkg.name, pkg);
+  }
+
+  function resolveWorkspaceImport(specifier, importer) {
+    const name = externalPackageName(specifier);
+    if (!name) return null;
+    const pkg = workspacePackages.get(name);
+    if (!pkg) return null;
+    // `"name": "npm:other@1"` (or a registry version of a same-named package installed
+    // under an alias) means the importer uses the registry package, not the member.
+    const manifest = importer?.manifest || {};
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+      const spec = manifest[field]?.[name];
+      if (typeof spec === "string" && spec.startsWith("npm:")) return null;
+    }
+    const subpath = specifier.slice(name.length).replace(/^\/+/, "");
+    for (const candidate of workspaceCandidates(pkg, subpath)) {
+      const key = normalizeFileKey(candidate);
+      if (allFileKeys.has(key)) return { name, key };
+    }
+    return { name, key: null };
+  }
+
   const pyIndex = indexPythonModules(pyFiles);
   const goModulePath = goFiles.length > 0 ? await loadGoModule(repoRoot) : null;
 
@@ -255,17 +362,28 @@ 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);
+    const importer = await ownPackage(file);
+    const selfName = importer ? importer.name : null;
     const grouped = new Map();
     for (const imported of extractJsImports(content)) {
+      let toKey = null;
       if (!isRelativeImport(imported.specifier)) {
-        if (imported.typeOnly) continue;
         const name = externalPackageName(imported.specifier);
         if (name && name === selfName) continue;
-        addExternal(fromKey, name);
-        continue;
+        const workspace = resolveWorkspaceImport(imported.specifier, importer);
+        if (workspace) {
+          // Another package in this repository is internal: an edge when it resolves
+          // to a scanned file, and never an external dependency either way.
+          if (!workspace.key) continue;
+          toKey = workspace.key;
+        } else {
+          if (imported.typeOnly) continue;
+          addExternal(fromKey, name);
+          continue;
+        }
+      } else {
+        toKey = resolveImportPath(file, imported.specifier);
       }
-      const toKey = resolveImportPath(file, imported.specifier);
       if (!toKey) continue;
       const id = `${fromKey}->${toKey}`;
       let slot = grouped.get(id);
@@ -509,7 +627,12 @@ function buildSummary(result) {
   if (result.stats.cycles > 0) {
     parts.push(`⚠️ ${result.stats.cycles} circular dependency cycle(s)`);
   } else {
-    parts.push("✓ no circular dependencies");
+    parts.push(result.coverage?.status === "partial"
+      ? "✓ no circular dependencies among analyzed files"
+      : "✓ no circular dependencies");
+  }
+  if (result.coverage?.status === "partial") {
+    parts.push(`partial coverage: ${result.coverage.analyzedBase} of ${result.coverage.totalBase} source files`);
   }
   if (result.stats.orphanFiles > 0) {
     parts.push(`${result.stats.orphanFiles} orphan file(s)`);

package/src/analyzers/flow-inference.js

@@ -114,7 +114,7 @@ function inferFlowsFromEntryPoints(scanResult, depGraph) {
     // Classify each step in the chain
     const steps = chain.map((nodeKey, i) => {
       const node = depGraph.nodes.find(n => n.key === nodeKey);
-      const name = nodeKey.split("/").pop();
+      const name = stepName(nodeKey);
       const fanIn = node?.importedBy?.length || 0;
       const fanOut = node?.imports?.length || 0;
       
@@ -342,3 +342,12 @@ function inferExternalDependencies(flow) {
   
   return external;
 }
+
+// A package entry is keyed by its folder (`packages/server/src` for src/index.ts), so
+// "src" or "lib" alone says nothing. Name it after the package folder instead.
+function stepName(nodeKey) {
+  const parts = String(nodeKey).split("/");
+  const last = parts.pop();
+  if (/^(src|lib|source)$/i.test(last) && parts.length > 0) return `${parts[parts.length - 1]}/${last}`;
+  return last;
+}