@chappibunny/repolens 1.15.5 → 1.16.1

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/renderers/renderDiff.js

@@ -1,3 +1,5 @@
+import { replaceBracketParams } from "../utils/route-params.js";
+
 function isRouteFile(file) {
   return (
     file.includes("/pages/api/") ||
@@ -15,10 +17,10 @@ function routePathFromFile(file) {
     const appIndex = file.indexOf("/app/");
     const relative = file.slice(appIndex + 5);
 
-    return "/" + relative
+    const cleaned = relative
       .replace(/\/page\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\[(.*?)\]/g, ":$1");
+      .replace(/\/route\.(ts|tsx|js|jsx)$/, "");
+    return `/${replaceBracketParams(cleaned)}`;
   }
 
   if (file.includes("/pages/api/")) {

package/src/renderers/renderMap.js

@@ -1,13 +1,12 @@
+import { replaceLeadingAppGroup, replaceSlashGroups } from "../utils/route-params.js";
+
 function sanitizeNodeId(value) {
   return value.replace(/[^a-zA-Z0-9_]/g, "_");
 }
 
 function normalizeLabel(value) {
-  return value
-    .replace(/^src\//, "")
-    .replace(/^app\/\((.*?)\)/, "app/$1")
-    .replace(/\/\((.*?)\)/g, "/$1")
-    .replace(/\/+/g, "/");
+  const withoutSrc = value.replace(/^src\//, "");
+  return replaceSlashGroups(replaceLeadingAppGroup(withoutSrc)).replace(/\/+/g, "/");
 }
 
 function buildModuleGraph(modules, depGraph) {
@@ -96,9 +95,11 @@ function buildModuleGraph(modules, depGraph) {
  */
 function findModuleForFile(fileKey, modules) {
   const normalized = fileKey.replace(/\\/g, "/");
+  const flat = modules.find((mod) => mod.flat) || modules.find((mod) => mod.key === "root");
   let bestMatch = null;
   for (const mod of modules) {
     const modKey = mod.key;
+    if (flat && modKey === flat.key) continue;
     // Direct match (with or without extension)
     if (normalized === modKey || normalized === modKey.replace(/\.[^/.]+$/, "")) {
       return modKey;
@@ -110,6 +111,7 @@ function findModuleForFile(fileKey, modules) {
       }
     }
   }
+  if (!bestMatch && flat && !normalized.includes("/")) return flat.key;
   return bestMatch;
 }
 

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

package/src/utils/route-params.js

@@ -0,0 +1,50 @@
+/**
+ * Linear replacements for route and label text.
+ *
+ * A lazy `.*?` between two markers is polynomial: on a long string with no
+ * closer, each start position scans to the end (CodeQL js/polynomial-redos).
+ * These walks stop at the first closer and never re-scan, which matches the
+ * old `String.prototype.replace` result.
+ */
+
+function replaceMarked(input, open, close, mapInner) {
+  const value = String(input ?? "");
+  let out = "";
+  let cursor = 0;
+  while (cursor < value.length) {
+    const start = value.indexOf(open, cursor);
+    if (start === -1) {
+      out += value.slice(cursor);
+      break;
+    }
+    const end = value.indexOf(close, start + open.length);
+    if (end === -1) {
+      out += value.slice(cursor);
+      break;
+    }
+    out += value.slice(cursor, start);
+    out += mapInner(value.slice(start + open.length, end));
+    cursor = end + close.length;
+  }
+  return out;
+}
+
+/** `[param]` → `:param`, including the first `]` only. Global, non-overlapping. */
+export function replaceBracketParams(value) {
+  return replaceMarked(value, "[", "]", (inner) => `:${inner}`);
+}
+
+/** `/(group)` → `/group`. Used for Next.js route groups in diagram labels. */
+export function replaceSlashGroups(value) {
+  return replaceMarked(value, "/(", ")", (inner) => `/${inner}`);
+}
+
+/** A leading `app/(group)` → `app/group`. Later groups use {@link replaceSlashGroups}. */
+export function replaceLeadingAppGroup(value) {
+  const input = String(value ?? "");
+  const prefix = "app/(";
+  if (!input.startsWith(prefix)) return input;
+  const end = input.indexOf(")", prefix.length);
+  if (end === -1) return input;
+  return `app/${input.slice(prefix.length, end)}${input.slice(end + 1)}`;
+}

package/src/utils/yaml.js

@@ -1,14 +1,15 @@
-import yaml from "js-yaml";
+import { CORE_SCHEMA, load, mergeTag } from "js-yaml";
 
 const MAX_YAML_CHARS = 1_000_000;
 const MAX_YAML_ALIASES = 2000;
 
 /**
  * Parse YAML without executing custom tags.
- * js-yaml 4 `load` is already safe (no JS types). This adds a size cap and
- * an alias cap so a config cannot expand into a billion-laughs document.
- * The js-yaml 4 default schema is unchanged (`true`/`false` are booleans;
- * the YAML 1.1 spellings `yes` and `no` stay strings).
+ * js-yaml 5 `load` uses the YAML 1.2 Core schema (`true`/`false` are booleans;
+ * the YAML 1.1 spellings `yes` and `no` stay strings). The merge key (`<<`)
+ * is added back so configs that relied on js-yaml 4's merge still parse.
+ * A size cap and `maxAliases` stop a billion-laughs document.
+ * An empty file returns `undefined`, matching the previous loader.
  */
 export function loadYaml(raw) {
   if (typeof raw !== "string") {
@@ -17,11 +18,15 @@ export function loadYaml(raw) {
   if (raw.length > MAX_YAML_CHARS) {
     throw new Error(`YAML document exceeds ${MAX_YAML_CHARS} characters`);
   }
+  if (raw.trim() === "") return undefined;
 
   const aliasUses = raw.match(/(^|[\s\[\{,])\*[A-Za-z_][\w-]*/g);
   if (aliasUses && aliasUses.length > MAX_YAML_ALIASES) {
     throw new Error(`YAML document has too many aliases (${aliasUses.length})`);
   }
 
-  return yaml.load(raw);
+  return load(raw, {
+    schema: CORE_SCHEMA.withTags(mergeTag),
+    maxAliases: MAX_YAML_ALIASES,
+  });
 }