@chappibunny/repolens 1.16.0 → 1.16.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 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).
+
+### Scan defaults
+
+- Snapshot directories (`__snapshots__`, `*.snap`), sample / fixture / example / e2e-fixture directories, and `generated/` trees are dev tooling. They are left out of the file count, orphan detection, and the type graph unless `scan.include_dev_artifacts: true`. Other `scan.ignore` patterns still apply. Orval's second copy of the snapshot tree lives in `tests/generated`, so `**/generated/**` is part of that default (it was already in the `init` ignore list).
+- `repolens badge` skips the same directories. It does not read `.repolens.yml`.
+
+### Cycle priority
+
+- A cycle is no longer always "Priority: High refactor".
+- **Low — mutual recursion, probably intentional; verify** when the cycle stays inside two parent directories that import each other both ways (at least two runtime edges each way) and both directions call the imported bindings (at least two calls each way). Orval's core getters and resolvers are this shape.
+- **Low — type-only imports; verify** when every edge is `import type` or `export type`. Those cycles are not runtime edges and are not counted in `stats.cycles`.
+- **High refactor** is kept for a cycle that touches three or more parent directories.
+- A two-directory cycle with only one import each way is **Medium**.
+- The health score subtracts points for high and medium cycles. Low-priority cycles do not. Stats that do not carry the priority split keep the previous per-cycle penalty.
+- The heuristic is documented in `src/analyzers/cycle-priority.js`, [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), and [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md).
+
+### npx and devEngines
+
+- npm versions that enforce `devEngines` (newer npm) check that field on the package.json in the current directory before `npx` starts the requested package. A repo that pins a Node or package-manager the host does not meet exits `EBADDEVENGINES`. Node 20's bundled npm does not enforce `devEngines`. RepoLens never gets to run when the check fails, so this cannot be fixed inside the CLI.
+- `--ignore-engines` is not an npm flag. On npm versions that enforce `devEngines`, npm warns that it is an unknown config and still errors.
+- `--force` turns that failure into a warning and runs the command. The GitHub Action passes `--force` on its `npx` step. A manual run is `npx --force --yes @chappibunny/repolens demo`. A global install, or `node node_modules/@chappibunny/repolens/bin/repolens.js`, never asks npm to read the scanned repo's `devEngines`.
+- See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
+
 ## 1.16.0
 
 ### GitHub App

package/README.md

@@ -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 --yes @chappibunny/repolens@1.16.0`). `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 --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`.
 
-Publishing docs (the npm package at tag `v1.16.0`):
+Publishing docs (the npm package at tag `v1.16.1`):
 
 ```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.0
+      - uses: CHAPIBUNNY/repolens@v1.16.1
         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.0` 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.1` 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.0
+      - uses: CHAPIBUNNY/repolens@v1.16.1
         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.0` has to exist before `uses: CHAPIBUNNY/repolens@v1.16.0` resolves, and `@chappibunny/repolens@1.16.0` 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.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.
 
 ## 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.0
+      - uses: CHAPIBUNNY/repolens@v1.16.1
         with:
           command: badge
           badge-url: https://USER.github.io/REPO/repolens-badge.json
@@ -359,7 +359,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. 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. 1.15.5 reads a flat `src/` as one module, tells a library from a CLI by its `package.json`, splits runtime from development packages, keeps tests, examples, and build scripts out of hubs and security severity, and skips empty Route Map and GraphQL pages. 1.16.0 adds `repolens app` (a self-hosted GitHub App webhook), names a flat package after its directory, treats a framework description as a library when `main` is absent, and keeps test and example routes out of the product API. 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. 1.15.5 reads a flat `src/` as one module, tells a library from a CLI by its `package.json`, splits runtime from development packages, keeps tests, examples, and build scripts out of hubs and security severity, and skips empty Route Map and GraphQL pages. 1.16.0 adds `repolens app` (a self-hosted GitHub App webhook), names a flat package after its directory, treats a framework description as a library when `main` is absent, and keeps test and example routes out of the product API. 1.16.1 skips snapshot, sample, fixture, example, and generated trees in the file count, orphan list, and type graph, and labels a call-heavy two-folder cycle as mutual recursion rather than a high-priority refactor. Layout and counts are in [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### System Overview (Technical Profile)
 

package/llms-install.md

@@ -22,3 +22,4 @@
 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.
 14. CLI (1.15.5): a flat `src/` is one module. A package with `main`, `module`, or `exports` is a library, not a CLI. Hubs and security severity ignore tests, examples, and build scripts. External packages are split into runtime and development tooling. Route Map and GraphQL Schema are skipped when empty.
 15. CLI (1.16.0): `repolens app` self-hosts a GitHub App webhook (manifest in `app.yml`, check run plus the sticky architecture comment). A framework description is a library even without `main`. A flat package is named after its directory. Test and example routes are not the product API. Test-only imports are dev tooling on Python and Go.
+16. CLI (1.16.1): snapshot, sample, fixture, example, and generated directories are out of the file count, orphan list, and type graph unless `scan.include_dev_artifacts` is true. A two-folder call-heavy cycle is "mutual recursion, probably intentional; verify", not "Priority: High refactor". On npm versions that enforce `devEngines` (newer npm), `npx` inside a repo with `devEngines` needs `--force`. Node 20's bundled npm does not enforce that field. `--ignore-engines` does not skip the check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.16.0",
+  "version": "1.16.1",
   "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

@@ -16,6 +16,7 @@ import { identifyFlowDependencies, filterNoiseFlows } from "../analyzers/flow-in
 import { isCliProject, isLibraryProject } from "../analyzers/context-builder.js";
 import { scoreMaturity } from "../analyzers/maturity.js";
 import { isNonProductPath, isTestPath } from "../utils/path-roles.js";
+import { cycleConcern, cycleHealthPenalty, cycleInsight, cycleStatusCell } from "../analyzers/cycle-priority.js";
 import { info, warn } from "../utils/logger.js";
 
 // Strip conversational patterns that LLMs sometimes inject into documentation
@@ -288,7 +289,8 @@ The system is organized around **${context.domains.length} functional domains**,
     output += `|--------|-------|--------|\n`;
     output += `| Internal imports | ${stats.totalEdges} edges | ${stats.totalEdges > 0 ? "✅ Connected" : "⚠️ Isolated"} |\n`;
     output += `| External Packages | ${externalPackagesLabel(stats)} | ${stats.externalDeps < 50 ? "✅ Manageable" : stats.externalDeps < 100 ? "⚠️ Consider audit" : "🔴 High dependency count"} |\n`;
-    output += `| Circular Dependencies | ${stats.cycles === 0 ? "cycle-free" : stats.cycles} | ${stats.cycles === 0 ? "✅ None" : `🔴 ${stats.cycles} detected`} |\n`;
+    const cycleCell = cycleStatusCell(stats);
+    output += `| Circular Dependencies | ${stats.cycles === 0 ? "cycle-free" : stats.cycles} | ${stats.cycles === 0 ? "✅ None" : `${cycleCell.mark} ${stats.cycles} detected`} |\n`;
     output += `| Orphan Files | ${stats.orphanFiles} | ${orphanStatus(stats)} |\n`;
 
     // Key insights
@@ -296,7 +298,7 @@ The system is organized around **${context.domains.length} functional domains**,
     if (stats.cycles === 0) {
       output += `- ✅ **Clean module boundaries** — No circular dependencies detected, enabling safe refactoring and testing.\n`;
     } else {
-      output += `- 🔴 **Architectural concern** — ${stats.cycles} circular dependenc${stats.cycles === 1 ? "y" : "ies"} detected. These create tight coupling and make testing difficult.\n`;
+      output += `- ${cycleInsight(stats)}\n`;
     }
     if (stats.hubs && stats.hubs.length > 0) {
       const topHub = stats.hubs[0];
@@ -828,7 +830,8 @@ function getFallbackArchitectureOverview(context, enrichment = {}) {
     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`;
-    output += `| Circular Deps | ${stats.cycles} | ${stats.cycles === 0 ? "✅" : "🔴"} | ${stats.cycles === 0 ? "Clean module boundaries" : "Refactor to break cycles"} |\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 += `| 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
@@ -856,9 +859,8 @@ function getFallbackArchitectureOverview(context, enrichment = {}) {
 
     // Concerns
     const concerns = [];
-    if (stats.cycles > 0) {
-      concerns.push(`**Circular dependencies detected** — ${stats.cycles} circular dependenc${stats.cycles === 1 ? 'y' : 'ies'} create tight coupling, complicate testing, and hinder refactoring. Priority: High.`);
-    }
+    const concern = cycleConcern(stats);
+    if (concern) concerns.push(concern);
     if (stats.orphanFiles > stats.totalFiles * 0.2) {
       concerns.push(`**High orphan file ratio** — ${stats.orphanFiles}/${stats.totalFiles} files (${Math.round(stats.orphanFiles / stats.totalFiles * 100)}%) are not imported. Consider removing dead code. Priority: Medium.`);
     }
@@ -1625,8 +1627,9 @@ function externalPackagesLabel(stats) {
 function calculateHealthScore(stats, context) {
   let score = 100;
   
-  // Circular dependencies are a major concern
-  if (stats.cycles > 0) score -= Math.min(30, stats.cycles * 10);
+  // High and medium cycles cost points. Mutual recursion and type-only cycles do not.
+  // A stats object without the priority split keeps the older per-cycle penalty.
+  score -= cycleHealthPenalty(stats);
   
   // Orphan files indicate potential dead code
   const ratio = orphanRatio(stats);

package/src/analyzers/cycle-priority.js

@@ -0,0 +1,169 @@
+// Cycle priority.
+//
+// Not every circular import is a refactor. The heuristic:
+//
+// 1. Type-only. Every edge in the cycle is `import type` or `export type`.
+//    There is no runtime cycle. Priority: Low. Wording: type-only imports; verify.
+//    These stay out of the runtime cycle list (`cycles` / `stats.cycles`).
+//
+// 2. Recursive-descent pair (mutual recursion). The cycle stays inside two parent
+//    directories, and those two directories import each other in both directions
+//    with many edges (at least 2 each way) and both directions are call-heavy
+//    (at least 2 calls of the imported bindings each way). Schema getters calling
+//    resolvers that call getters is this shape. The pair is small: two folders,
+//    not a chain across the repo. Priority: Low. Wording: mutual recursion,
+//    probably intentional; verify.
+//
+// 3. Large multi-module cycle. The cycle touches 3 or more parent directories.
+//    Priority: High refactor.
+//
+// 4. Anything else (a short accidental cycle, one import each way, no real call
+//    traffic) is Medium: review, not a blanket high-priority refactor.
+//
+// "Folder" is the file's parent directory. `index.ts` stays in its own directory
+// after the graph strips the `/index` suffix. Call counts use ESM bindings
+// (`import { fn }` then `fn(` or `ns.fn(`). A `require()` edge has no binding
+// names, so it does not count as call-heavy.
+
+export const MUTUAL_EDGE_MINIMUM = 2;
+export const MUTUAL_CALL_MINIMUM = 2;
+export const HIGH_FOLDER_MINIMUM = 3;
+
+export function folderOfFile(file) {
+  const norm = String(file || "").replace(/\\/g, "/");
+  const slash = norm.lastIndexOf("/");
+  if (slash <= 0) return ".";
+  return norm.slice(0, slash);
+}
+
+function cycleNodes(path) {
+  if (!Array.isArray(path) || path.length < 2) return [];
+  return path[0] === path[path.length - 1] ? path.slice(0, -1) : path.slice();
+}
+
+function report(path, priority, kind, label) {
+  return { path, priority, kind, label, priorityLine: priorityLine(priority, label) };
+}
+
+export function priorityLine(priority, label) {
+  if (priority === "high") return "Priority: High refactor";
+  const text = label || "review";
+  const name = priority === "low" ? "Low" : "Medium";
+  return `Priority: ${name} — ${text}`;
+}
+
+/**
+ * Classify one runtime cycle.
+ * `edges` are runtime import edges: { from, to, fromFile, toFile, calls }.
+ * `fileForKey(key)` returns the source path used for the parent directory.
+ */
+export function classifyRuntimeCycle(path, edges, fileForKey) {
+  const nodes = cycleNodes(path);
+  const folders = nodes.map((key) => folderOfFile(fileForKey(key)));
+  const uniqueFolders = [...new Set(folders)];
+
+  if (uniqueFolders.length >= HIGH_FOLDER_MINIMUM) {
+    return report(path, "high", "multi-module", "large multi-module cycle");
+  }
+
+  if (uniqueFolders.length === 2 && isRecursiveDescentPair(uniqueFolders[0], uniqueFolders[1], edges)) {
+    return report(path, "low", "mutual-recursion", "mutual recursion, probably intentional; verify");
+  }
+
+  return report(path, "medium", "small", "small cycle; review");
+}
+
+export function isRecursiveDescentPair(folderA, folderB, edges) {
+  let ab = 0;
+  let ba = 0;
+  let callsAB = 0;
+  let callsBA = 0;
+  for (const edge of edges || []) {
+    if (edge.typeOnly) continue;
+    const from = folderOfFile(edge.fromFile || edge.from);
+    const to = folderOfFile(edge.toFile || edge.to);
+    if (from === folderA && to === folderB) {
+      ab += 1;
+      callsAB += edge.calls || 0;
+    } else if (from === folderB && to === folderA) {
+      ba += 1;
+      callsBA += edge.calls || 0;
+    }
+  }
+  return ab >= MUTUAL_EDGE_MINIMUM
+    && ba >= MUTUAL_EDGE_MINIMUM
+    && callsAB >= MUTUAL_CALL_MINIMUM
+    && callsBA >= MUTUAL_CALL_MINIMUM;
+}
+
+export function classifyRuntimeCycles(cycles, edges, fileForKey) {
+  return (cycles || []).map((path) => classifyRuntimeCycle(path, edges, fileForKey));
+}
+
+export function typeOnlyReport(path) {
+  return report(path, "low", "type-only", "type-only imports; verify");
+}
+
+export function priorityCounts(reports) {
+  const counts = { high: 0, medium: 0, low: 0 };
+  for (const item of reports || []) {
+    if (item.priority === "high") counts.high += 1;
+    else if (item.priority === "low") counts.low += 1;
+    else counts.medium += 1;
+  }
+  return counts;
+}
+
+export function hasCyclePriorities(stats) {
+  return Boolean(stats) && (stats.highCycles != null || stats.mediumCycles != null || stats.lowCycles != null);
+}
+
+/** Points removed from the architecture health score. Low-priority cycles do not count. */
+export function cycleHealthPenalty(stats) {
+  if (!stats) return 0;
+  if (!hasCyclePriorities(stats)) {
+    return stats.cycles > 0 ? Math.min(30, stats.cycles * 10) : 0;
+  }
+  const high = stats.highCycles || 0;
+  const medium = stats.mediumCycles || 0;
+  return Math.min(30, high * 10 + medium * 5);
+}
+
+export function cycleStatusCell(stats) {
+  if (!stats || stats.cycles === 0) return { mark: "✅", advice: "Clean module boundaries" };
+  if (hasCyclePriorities(stats) && (stats.highCycles || 0) === 0 && (stats.lowCycles || 0) > 0 && !(stats.mediumCycles > 0)) {
+    return { mark: "🟡", advice: "mutual recursion, probably intentional; verify" };
+  }
+  if (hasCyclePriorities(stats) && (stats.highCycles || 0) === 0) {
+    return { mark: "🟡", advice: "Small cycle; review" };
+  }
+  return { mark: "🔴", advice: "Refactor to break cycles" };
+}
+
+export function cycleConcern(stats) {
+  if (!stats || !(stats.cycles > 0)) return null;
+  const noun = `circular dependenc${stats.cycles === 1 ? "y" : "ies"}`;
+  if (!hasCyclePriorities(stats)) {
+    return `**Circular dependencies detected** — ${stats.cycles} ${noun} create tight coupling, complicate testing, and hinder refactoring. Priority: High.`;
+  }
+  if ((stats.highCycles || 0) > 0) {
+    const high = stats.highCycles;
+    const highNoun = `circular dependenc${high === 1 ? "y" : "ies"}`;
+    return `**Circular dependencies detected** — ${high} large multi-module ${highNoun}. Priority: High refactor.`;
+  }
+  if ((stats.lowCycles || 0) > 0 && !(stats.mediumCycles > 0)) {
+    return `**Circular dependencies detected** — ${stats.cycles} ${noun}. mutual recursion, probably intentional; verify. Priority: Low.`;
+  }
+  return `**Circular dependencies detected** — ${stats.cycles} ${noun}. Priority: Medium.`;
+}
+
+export function cycleInsight(stats) {
+  if (!stats || !(stats.cycles > 0)) return null;
+  if (!hasCyclePriorities(stats)) {
+    return `🔴 **Architectural concern** — ${stats.cycles} circular dependenc${stats.cycles === 1 ? "y" : "ies"} detected. These create tight coupling and make testing difficult.`;
+  }
+  if ((stats.highCycles || 0) === 0) {
+    return `🟡 **Circular dependencies** — ${stats.cycles} detected. mutual recursion, probably intentional; verify. Priority: Low.`;
+  }
+  return `🔴 **Architectural concern** — ${stats.highCycles} large multi-module circular dependenc${stats.highCycles === 1 ? "y" : "ies"} detected. Priority: High refactor.`;
+}

package/src/analyzers/dependency-graph.js

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

package/src/analyzers/import-parsers.js

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

package/src/badge.js

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

package/src/core/config-schema.js

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

package/src/core/scan-defaults.js

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

package/src/core/scan.js

@@ -6,6 +6,7 @@ import { trackScan } from "../utils/telemetry.js";
 import { detectMonorepo } from "../analyzers/monorepo-detector.js";
 import { isInsideRoot } from "../utils/safe-path.js";
 import { isNonProductPath, isTestPath } from "../utils/path-roles.js";
+import { resolveScanIgnore } from "./scan-defaults.js";
 import { replaceBracketParams } from "../utils/route-params.js";
 
 const norm = (p) => p.replace(/\\/g, "/");
@@ -559,7 +560,7 @@ export async function listMatchedFiles(cfg) {
   const rootResolved = path.resolve(repoRoot);
   const files = await fg(cfg.scan.include, {
     cwd: rootResolved,
-    ignore: cfg.scan?.ignore || [],
+    ignore: resolveScanIgnore(cfg.scan),
     onlyFiles: true,
     followSymbolicLinks: false,
     absolute: false

package/src/renderers/renderAnalysis.js

@@ -366,15 +366,20 @@ export function renderDependencyGraph(depResult) {
     lines.push("");
   }
 
-  // Circular dependencies
+  // Circular dependencies. Priority comes from the cycle heuristic in cycle-priority.js.
   if (depResult.cycles.length > 0) {
+    const reports = Array.isArray(depResult.cycleReports) ? depResult.cycleReports : [];
     lines.push("## Circular Dependencies");
     lines.push("");
-    lines.push(`**${depResult.cycles.length}** circular dependency chain${depResult.cycles.length === 1 ? " was" : "s were"} detected. Circular imports can cause initialization errors, increase bundle sizes, and make modules harder to test in isolation. Consider refactoring shared logic into a separate module.`);
+    lines.push(`**${depResult.cycles.length}** circular dependency chain${depResult.cycles.length === 1 ? " was" : "s were"} detected. A large cycle across three or more folders is a high-priority refactor. A two-folder recursive-descent pair (many imports and calls both ways) is mutual recursion, probably intentional; verify. A cycle that exists only through type-only imports is not a runtime cycle.`);
     lines.push("");
-    for (let i = 0; i < Math.min(depResult.cycles.length, 20); i++) {
+    const limit = Math.min(depResult.cycles.length, 20);
+    for (let i = 0; i < limit; i++) {
       const cycle = depResult.cycles[i];
-      lines.push(`${i + 1}. \`${cycle.join("` → `")}\``);
+      const report = reports[i];
+      const pathText = Array.isArray(cycle) ? cycle.join("` → `") : String(cycle);
+      lines.push(`${i + 1}. \`${pathText}\``);
+      if (report?.priorityLine) lines.push(`   ${report.priorityLine}`);
     }
     if (depResult.cycles.length > 20) {
       lines.push(`\n*...and ${depResult.cycles.length - 20} more cycles*`);
@@ -382,6 +387,13 @@ export function renderDependencyGraph(depResult) {
     lines.push("");
   }
 
+  if (Array.isArray(depResult.typeOnlyReports) && depResult.typeOnlyReports.length > 0) {
+    lines.push("## Type-only cycles");
+    lines.push("");
+    lines.push(`**${depResult.typeOnlyReports.length}** cycle${depResult.typeOnlyReports.length === 1 ? " exists" : "s exist"} only through \`import type\` / \`export type\`. They are not runtime dependencies. Priority: Low — type-only imports; verify.`);
+    lines.push("");
+  }
+
   // External dependencies
   if (depResult.externalDeps.length > 0) {
     lines.push("## External Dependencies");

package/src/utils/path-roles.js

@@ -3,7 +3,8 @@
 // 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",
+  "test", "tests", "spec", "specs", "__tests__", "__mocks__", "fixtures", "fixture", "__fixtures__",
+  "testdata", "e2e", "e2e-fixture", "e2e-fixtures", "cypress", "__snapshots__",
 ]);
 
 // Directories holding tooling, samples, and docs. Code in here describes a build script
@@ -31,12 +32,39 @@ 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 (base.endsWith(".snap") || base.includes(".snap.")) return true;
   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;
 }
 
+/**
+ * Snapshot, sample, fixture, example, and generated trees.
+ * These are dev tooling, like tests: they describe the suite or a demo, not the product.
+ * Scan ignores them unless `scan.include_dev_artifacts` is true.
+ */
+export const DEV_ARTIFACT_DIRECTORIES = new Set([
+  "__snapshots__",
+  "sample", "samples",
+  "example", "examples",
+  "fixture", "fixtures", "__fixtures__",
+  "e2e-fixture", "e2e-fixtures",
+  "generated",
+]);
+
+export function isSnapshotPath(filePath) {
+  const parts = segments(filePath);
+  if (parts.some((segment) => segment === "__snapshots__")) return true;
+  const base = parts[parts.length - 1] || "";
+  return base.endsWith(".snap") || base.includes(".snap.");
+}
+
+export function isDevArtifactPath(filePath) {
+  if (isSnapshotPath(filePath)) return true;
+  return directorySegments(filePath).some((segment) => DEV_ARTIFACT_DIRECTORIES.has(segment));
+}
+
 /** 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));