codebase-onboarder 0.6.0 → 1.0.0

package/shared/analyzer/patterns.js

@@ -1,272 +1,250 @@
 // Pattern reading: turns the raw import graph into observations about the
 // repo's shape — its depth layers, its load-bearing files, its smells.
 // Everything here is pure functions over scan + facts.
-
 // Assigns every reachable file a depth: the length of the longest import
 // chain from an entry point. Files no entry can reach land in `unreachable`.
 // Cycles are survived by capping how often a file may be relaxed.
 export function computeLayers(scan, facts) {
-  let seeds = facts.entries.slice();
-  if (!seeds.length) {
-    // No recognized entry points — start from the tops of the import chains:
-    // files that pull others in but are pulled in by nothing.
-    seeds = scan.files
-      .filter((f) => (facts.fanOut[f.path] || 0) > 0 && (facts.fanIn[f.path] || 0) === 0)
-      .map((f) => f.path)
-      .slice(0, 5);
-  }
-  if (!seeds.length) {
-    // Last resort: the most depended-upon files.
-    seeds = facts.hubs.slice(0, 3).map((h) => h.path);
-  }
-
-  const depth = new Map();
-  const visits = new Map();
-  const queue = [];
-  for (const s of seeds) {
-    depth.set(s, 0);
-    queue.push(s);
-  }
-
-  while (queue.length) {
-    const cur = queue.shift();
-    const d = depth.get(cur);
-    visits.set(cur, (visits.get(cur) || 0) + 1);
-    if (visits.get(cur) > 4) continue; // circular chains give up here
-    const next = d + 1;
-    if (next > MAX_DEPTH) continue; // and nobody sinks past the basement
-    for (const nxt of facts.importsOf[cur] || []) {
-      if ((depth.get(nxt) ?? -1) < next) {
-        depth.set(nxt, next);
-        queue.push(nxt);
-      }
+    let seeds = facts.entries.slice();
+    if (!seeds.length) {
+        // No recognized entry points — start from the tops of the import chains:
+        // files that pull others in but are pulled in by nothing.
+        seeds = scan.files
+            .filter((f) => (facts.fanOut[f.path] || 0) > 0 && (facts.fanIn[f.path] || 0) === 0)
+            .map((f) => f.path)
+            .slice(0, 5);
     }
-  }
-
-  // Depths can skip values (cycle members sink several floors at once), and
-  // for..of over a sparse array hands holes to sort() — compact first.
-  const sparse = [];
-  for (const [path, d] of depth) {
-    (sparse[d] ||= []).push(path);
-  }
-  const layers = sparse.filter(Boolean);
-  for (const l of layers) l.sort((a, b) => a.localeCompare(b));
-
-  const unreachable = scan.files
-    .map((f) => f.path)
-    .filter((p) => !depth.has(p))
-    .sort();
-
-  return { layers, unreachable, seeds };
+    if (!seeds.length) {
+        // Last resort: the most depended-upon files.
+        seeds = facts.hubs.slice(0, 3).map((h) => h.path);
+    }
+    const depth = new Map();
+    const visits = new Map();
+    const queue = [];
+    for (const s of seeds) {
+        depth.set(s, 0);
+        queue.push(s);
+    }
+    while (queue.length) {
+        const cur = queue.shift();
+        const d = depth.get(cur);
+        visits.set(cur, (visits.get(cur) || 0) + 1);
+        if (visits.get(cur) > 4)
+            continue; // circular chains give up here
+        const next = d + 1;
+        if (next > MAX_DEPTH)
+            continue; // and nobody sinks past the basement
+        for (const nxt of facts.importsOf[cur] || []) {
+            if ((depth.get(nxt) ?? -1) < next) {
+                depth.set(nxt, next);
+                queue.push(nxt);
+            }
+        }
+    }
+    // Depths can skip values (cycle members sink several floors at once), and
+    // for..of over a sparse array hands holes to sort() — compact first.
+    const sparse = [];
+    for (const [path, d] of depth) {
+        (sparse[d] ||= []).push(path);
+    }
+    const layers = sparse.filter(Boolean);
+    for (const l of layers)
+        l.sort((a, b) => a.localeCompare(b));
+    const unreachable = scan.files
+        .map((f) => f.path)
+        .filter((p) => !depth.has(p))
+        .sort();
+    return { layers, unreachable, seeds };
 }
-
 const MAX_DEPTH = 12;
-
 // Written observations, in the order a senior dev would mention them.
 // Each: { id, tone: 'good' | 'note' | 'warn', severity: 'info' | 'low' | 'medium' | 'high', paths: string[], title, detail }.
 export function detectPatterns(scan, facts, manifest, layersInfo) {
-  const out = [];
-  const topHub = facts.hubs[0];
-
-  if (topHub && topHub.fanIn >= 5) {
-    out.push({
-      id: 'hub-and-spoke',
-      tone: 'note',
-      severity: 'info',
-      paths: [topHub.path],
-      title: 'Hub and spoke',
-      detail: `\`${topHub.path}\` holds ${topHub.fanIn} dependents — this repo orbits a core. Learn that file and most of the rest makes sense.`,
-    });
-  }
-
-  const god = scan.files
-    .filter((f) => (facts.fanIn[f.path] || 0) + (facts.fanOut[f.path] || 0) >= 12)
-    .sort((a, b) => ((facts.fanIn[b.path] || 0) + (facts.fanOut[b.path] || 0)) - ((facts.fanIn[a.path] || 0) + (facts.fanOut[a.path] || 0)));
-
-  if (god.length) {
-    out.push({
-      id: 'god-files',
-      tone: 'warn',
-      severity: 'medium',
-      paths: god.map((f) => f.path),
-      title: god.length > 1 ? 'God files' : 'God file',
-      detail: `${god.slice(0, 3).map((f) => `\`${f.path}\``).join(', ')} — heavily connected in both directions. Everyone's problem, nobody's owner. Touch gently.`,
-    });
-  }
-
-  if (layersInfo && layersInfo.layers.length >= 3) {
-    out.push({
-      id: 'layered-shape',
-      tone: 'good',
-      severity: 'info',
-      paths: [],
-      title: 'A layered shape',
-      detail: `The code reads in ${layersInfo.layers.length} strata from the door to the deepest leaf. That is an architecture someone can draw — always a good sign.`,
-    });
-    if (layersInfo.unreachable.length) {
-      out.push({
-        id: 'unreachable',
-        tone: 'note',
-        severity: 'info',
-        paths: layersInfo.unreachable,
-        title: 'Off the beaten path',
-        detail: `${layersInfo.unreachable.length} files can't be reached from any entry point — utilities awaiting adoption, or furniture from an older layout.`,
-      });
+    const out = [];
+    const topHub = facts.hubs[0];
+    if (topHub && topHub.fanIn >= 5) {
+        out.push({
+            id: 'hub-and-spoke',
+            tone: 'note',
+            severity: 'info',
+            paths: [topHub.path],
+            title: 'Hub and spoke',
+            detail: `\`${topHub.path}\` holds ${topHub.fanIn} dependents — this repo orbits a core. Learn that file and most of the rest makes sense.`,
+        });
+    }
+    const god = scan.files
+        .filter((f) => (facts.fanIn[f.path] || 0) + (facts.fanOut[f.path] || 0) >= 12)
+        .sort((a, b) => ((facts.fanIn[b.path] || 0) + (facts.fanOut[b.path] || 0)) - ((facts.fanIn[a.path] || 0) + (facts.fanOut[a.path] || 0)));
+    if (god.length) {
+        out.push({
+            id: 'god-files',
+            tone: 'warn',
+            severity: 'medium',
+            paths: god.map((f) => f.path),
+            title: god.length > 1 ? 'God files' : 'God file',
+            detail: `${god.slice(0, 3).map((f) => `\`${f.path}\``).join(', ')} — heavily connected in both directions. Everyone's problem, nobody's owner. Touch gently.`,
+        });
+    }
+    if (layersInfo && layersInfo.layers.length >= 3) {
+        out.push({
+            id: 'layered-shape',
+            tone: 'good',
+            severity: 'info',
+            paths: [],
+            title: 'A layered shape',
+            detail: `The code reads in ${layersInfo.layers.length} strata from the door to the deepest leaf. That is an architecture someone can draw — always a good sign.`,
+        });
+        if (layersInfo.unreachable.length) {
+            out.push({
+                id: 'unreachable',
+                tone: 'note',
+                severity: 'info',
+                paths: layersInfo.unreachable,
+                title: 'Off the beaten path',
+                detail: `${layersInfo.unreachable.length} files can't be reached from any entry point — utilities awaiting adoption, or furniture from an older layout.`,
+            });
+        }
+    }
+    if (facts.cycles.length) {
+        out.push({
+            id: 'cycles',
+            tone: 'warn',
+            severity: 'high',
+            paths: Array.from(new Set(facts.cycles.flat())),
+            title: 'Circular dependencies',
+            detail: `${facts.cycles.length} ${facts.cycles.length === 1 ? 'loop' : 'loops'} where files import each other; the biggest tangles ${facts.cycles[0].length} files. Untangle before a big refactor.`,
+        });
+    }
+    const barrels = scan.files.filter((f) => /^index\.[jt]sx?$/.test(f.name) &&
+        f.functions.length === 0 &&
+        (facts.fanIn[f.path] || 0) >= 2 &&
+        (facts.fanOut[f.path] || 0) >= 2);
+    if (barrels.length) {
+        out.push({
+            id: 'barrels',
+            tone: 'note',
+            severity: 'info',
+            paths: barrels.map((f) => f.path),
+            title: 'Barrel files',
+            detail: `${barrels.slice(0, 3).map((f) => `\`${f.path}\``).join(', ')} mostly re-export other modules. Convenient for imports, one extra hop when you're hunting a definition.`,
+        });
+    }
+    const testCount = scan.files.filter((f) => /(^|[._-])(test|spec|tests|__tests__)([._-]|\/|$)/i.test(f.path)).length;
+    if (testCount > 0) {
+        const pct = Math.round((testCount / Math.max(1, scan.stats.filesParsed)) * 100);
+        out.push({
+            id: 'test-shadow',
+            tone: 'good',
+            severity: 'info',
+            paths: [],
+            title: 'A test shadow',
+            detail: `${testCount} test ${testCount === 1 ? 'file' : 'files'} against ${scan.stats.filesParsed} code files (~${pct}%). Read tests to learn intended behavior, code to learn actual behavior.`,
+        });
+    }
+    else {
+        out.push({
+            id: 'no-tests',
+            tone: 'warn',
+            severity: 'medium',
+            paths: [],
+            title: 'No tests in sight',
+            detail: 'Nothing matches the usual test/spec naming. Onboarding risk: intended behavior lives only inside the code.',
+        });
     }
-  }
-
-  if (facts.cycles.length) {
-    out.push({
-      id: 'cycles',
-      tone: 'warn',
-      severity: 'high',
-      paths: Array.from(new Set(facts.cycles.flat())),
-      title: 'Circular dependencies',
-      detail: `${facts.cycles.length} ${facts.cycles.length === 1 ? 'loop' : 'loops'} where files import each other; the biggest tangles ${facts.cycles[0].length} files. Untangle before a big refactor.`,
-    });
-  }
-
-  const barrels = scan.files.filter(
-    (f) =>
-      /^index\.[jt]sx?$/.test(f.name) &&
-      f.functions.length === 0 &&
-      (facts.fanIn[f.path] || 0) >= 2 &&
-      (facts.fanOut[f.path] || 0) >= 2
-  );
-  if (barrels.length) {
-    out.push({
-      id: 'barrels',
-      tone: 'note',
-      severity: 'info',
-      paths: barrels.map((f) => f.path),
-      title: 'Barrel files',
-      detail: `${barrels.slice(0, 3).map((f) => `\`${f.path}\``).join(', ')} mostly re-export other modules. Convenient for imports, one extra hop when you're hunting a definition.`,
-    });
-  }
-
-  const testCount = scan.files.filter((f) => /(^|[._-])(test|spec|tests|__tests__)([._-]|\/|$)/i.test(f.path)).length;
-  if (testCount > 0) {
-    const pct = Math.round((testCount / Math.max(1, scan.stats.filesParsed)) * 100);
-    out.push({
-      id: 'test-shadow',
-      tone: 'good',
-      severity: 'info',
-      paths: [],
-      title: 'A test shadow',
-      detail: `${testCount} test ${testCount === 1 ? 'file' : 'files'} against ${scan.stats.filesParsed} code files (~${pct}%). Read tests to learn intended behavior, code to learn actual behavior.`,
-    });
-  } else {
-    out.push({
-      id: 'no-tests',
-      tone: 'warn',
-      severity: 'medium',
-      paths: [],
-      title: 'No tests in sight',
-      detail: 'Nothing matches the usual test/spec naming. Onboarding risk: intended behavior lives only inside the code.',
-    });
-  }
-
-  if (facts.untestedHubs?.length) {
-    out.push({
-      id: 'untested-hubs',
-      tone: 'warn',
-      severity: 'high',
-      paths: facts.untestedHubs.map((h) => h.path),
-      title: 'Untested hubs',
-      detail: `${facts.untestedHubs.length} load-bearing ${facts.untestedHubs.length === 1 ? 'file is' : 'files are'} not reached by any test. Changing them has wide blast radius with no test safety net.`,
-    });
-  }
-
-  if (facts.deadExports?.length) {
-    const deadFiles = Array.from(new Set(facts.deadExports.map((d) => d.file)));
-    out.push({
-      id: 'dead-exports',
-      tone: 'note',
-      severity: 'low',
-      paths: deadFiles,
-      title: 'Unused exports',
-      detail: `${facts.deadExports.length} exported ${facts.deadExports.length === 1 ? 'symbol is' : 'symbols are'} never imported anywhere in the project. Potential dead code or unexposed public API.`,
-    });
-  }
-
-  if (facts.depsDrift?.undeclaredImported?.length) {
-    out.push({
-      id: 'undeclared-deps',
-      tone: 'warn',
-      severity: 'high',
-      paths: [],
-      title: 'Undeclared dependencies',
-      detail: `Imported packages not listed in package manifest: ${facts.depsDrift.undeclaredImported.slice(0, 4).map((d) => `\`${d}\``).join(', ')}. Risk of build failure in CI/clean environments.`,
-    });
-  }
-
-  if (facts.depsDrift?.unusedDeclared?.length) {
-    out.push({
-      id: 'unused-deps',
-      tone: 'note',
-      severity: 'low',
-      paths: [],
-      title: 'Unused dependencies',
-      detail: `Declared dependencies not directly imported in source: ${facts.depsDrift.unusedDeclared.slice(0, 5).map((d) => `\`${d}\``).join(', ')}.`,
-    });
-  }
-
-  if (facts.orphans.length) {
-    out.push({
-      id: 'orphans',
-      tone: 'note',
-      severity: 'info',
-      paths: facts.orphans,
-      title: 'Unclaimed territory',
-      detail: `${facts.orphans.length} ${facts.orphans.length === 1 ? 'file is' : 'files are'} imported by nothing. Dead code, or doors the naming rules didn't recognize.`,
-    });
-  }
-
-  const topExt = scan.externals[0];
-  if (topExt && topExt.usedBy.length >= 3) {
-    out.push({
-      id: 'top-external',
-      tone: 'note',
-      severity: 'info',
-      paths: topExt.usedBy,
-      title: 'Heaviest outside anchor',
-      detail: `\`${topExt.name}\` is pulled in by ${topExt.usedBy.length} files — the external dependency this repo would miss most.`,
-    });
-  }
-
-  if (manifest?.services?.length) {
-    out.push({
-      id: 'services',
-      tone: 'note',
-      severity: 'info',
-      paths: [],
-      title: 'Runs as services',
-      detail: `${manifest.services.length} ${manifest.services.length === 1 ? 'service' : 'services'} declared: ${manifest.services.map((s) => s.name).join(', ')}.`,
-    });
-  }
-
-  return out;
+    if (facts.untestedHubs?.length) {
+        out.push({
+            id: 'untested-hubs',
+            tone: 'warn',
+            severity: 'high',
+            paths: facts.untestedHubs.map((h) => h.path),
+            title: 'Untested hubs',
+            detail: `${facts.untestedHubs.length} load-bearing ${facts.untestedHubs.length === 1 ? 'file is' : 'files are'} not reachable through test imports. Check whether tests exercise these files before changing them.`,
+        });
+    }
+    if (facts.deadExports?.length) {
+        const deadFiles = Array.from(new Set(facts.deadExports.map((d) => d.file)));
+        out.push({
+            id: 'dead-exports',
+            tone: 'note',
+            severity: 'low',
+            paths: deadFiles,
+            title: 'Unused exports',
+            detail: `${facts.deadExports.length} exported ${facts.deadExports.length === 1 ? 'symbol is' : 'symbols are'} never imported anywhere in the project. Potential dead code or unexposed public API.`,
+        });
+    }
+    if (facts.depsDrift?.undeclaredImported?.length) {
+        out.push({
+            id: 'undeclared-deps',
+            tone: 'warn',
+            severity: 'high',
+            paths: [],
+            title: 'Undeclared dependencies',
+            detail: `Imported packages not listed in package manifest: ${facts.depsDrift.undeclaredImported.slice(0, 4).map((d) => `\`${d}\``).join(', ')}. Risk of build failure in CI/clean environments.`,
+        });
+    }
+    if (facts.depsDrift?.unusedDeclared?.length) {
+        out.push({
+            id: 'unused-deps',
+            tone: 'note',
+            severity: 'low',
+            paths: [],
+            title: 'Unused dependencies',
+            detail: `Declared dependencies not directly imported in source: ${facts.depsDrift.unusedDeclared.slice(0, 5).map((d) => `\`${d}\``).join(', ')}.`,
+        });
+    }
+    if (facts.orphans.length) {
+        out.push({
+            id: 'orphans',
+            tone: 'note',
+            severity: 'info',
+            paths: facts.orphans,
+            title: 'Unclaimed territory',
+            detail: `${facts.orphans.length} ${facts.orphans.length === 1 ? 'file is' : 'files are'} imported by nothing. Dead code, or doors the naming rules didn't recognize.`,
+        });
+    }
+    const topExt = scan.externals[0];
+    if (topExt && topExt.usedBy.length >= 3) {
+        out.push({
+            id: 'top-external',
+            tone: 'note',
+            severity: 'info',
+            paths: topExt.usedBy,
+            title: 'Heaviest outside anchor',
+            detail: `\`${topExt.name}\` is pulled in by ${topExt.usedBy.length} files — the external dependency this repo would miss most.`,
+        });
+    }
+    if (manifest?.services?.length) {
+        out.push({
+            id: 'services',
+            tone: 'note',
+            severity: 'info',
+            paths: [],
+            title: 'Runs as services',
+            detail: `${manifest.services.length} ${manifest.services.length === 1 ? 'service' : 'services'} declared: ${manifest.services.map((s) => s.name).join(', ')}.`,
+        });
+    }
+    return out;
 }
-
 // Folder-to-folder traffic as a matrix for the heat grid. Folders are the
 // top-level ones, ordered by how much traffic they see in total.
 export function couplingMatrix(scan, facts, maxFolders = 8) {
-  const traffic = new Map();
-  for (const fe of facts.folderEdges) {
-    traffic.set(fe.from, (traffic.get(fe.from) || 0) + fe.count);
-    traffic.set(fe.to, (traffic.get(fe.to) || 0) + fe.count);
-  }
-  const folders = [...traffic.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, maxFolders)
-    .map(([name]) => name);
-
-  const counts = new Map();
-  let max = 1;
-  for (const fe of facts.folderEdges) {
-    if (!folders.includes(fe.from) || !folders.includes(fe.to)) continue;
-    counts.set(fe.from + '->' + fe.to, fe.count);
-    max = Math.max(max, fe.count);
-  }
-  return { folders, counts, max };
+    const traffic = new Map();
+    for (const fe of facts.folderEdges) {
+        traffic.set(fe.from, (traffic.get(fe.from) || 0) + fe.count);
+        traffic.set(fe.to, (traffic.get(fe.to) || 0) + fe.count);
+    }
+    const folders = [...traffic.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, maxFolders)
+        .map(([name]) => name);
+    const counts = new Map();
+    let max = 1;
+    for (const fe of facts.folderEdges) {
+        if (!folders.includes(fe.from) || !folders.includes(fe.to))
+            continue;
+        counts.set(fe.from + '->' + fe.to, fe.count);
+        max = Math.max(max, fe.count);
+    }
+    return { folders, counts, max };
 }
+//# sourceMappingURL=patterns.js.map

package/shared/analyzer/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../src/shared/analyzer/patterns.ts"],"names":[],"mappings":"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","sourcesContent":["// Pattern reading: turns the raw import graph into observations about the\n// repo's shape — its depth layers, its load-bearing files, its smells.\n// Everything here is pure functions over scan + facts.\n\n// Assigns every reachable file a depth: the length of the longest import\n// chain from an entry point. Files no entry can reach land in `unreachable`.\n// Cycles are survived by capping how often a file may be relaxed.\nexport function computeLayers(scan, facts) {\n  let seeds = facts.entries.slice();\n  if (!seeds.length) {\n    // No recognized entry points — start from the tops of the import chains:\n    // files that pull others in but are pulled in by nothing.\n    seeds = scan.files\n      .filter((f) => (facts.fanOut[f.path] || 0) > 0 && (facts.fanIn[f.path] || 0) === 0)\n      .map((f) => f.path)\n      .slice(0, 5);\n  }\n  if (!seeds.length) {\n    // Last resort: the most depended-upon files.\n    seeds = facts.hubs.slice(0, 3).map((h) => h.path);\n  }\n\n  const depth = new Map();\n  const visits = new Map();\n  const queue = [];\n  for (const s of seeds) {\n    depth.set(s, 0);\n    queue.push(s);\n  }\n\n  while (queue.length) {\n    const cur = queue.shift();\n    const d = depth.get(cur);\n    visits.set(cur, (visits.get(cur) || 0) + 1);\n    if (visits.get(cur) > 4) continue; // circular chains give up here\n    const next = d + 1;\n    if (next > MAX_DEPTH) continue; // and nobody sinks past the basement\n    for (const nxt of facts.importsOf[cur] || []) {\n      if ((depth.get(nxt) ?? -1) < next) {\n        depth.set(nxt, next);\n        queue.push(nxt);\n      }\n    }\n  }\n\n  // Depths can skip values (cycle members sink several floors at once), and\n  // for..of over a sparse array hands holes to sort() — compact first.\n  const sparse = [];\n  for (const [path, d] of depth) {\n    (sparse[d] ||= []).push(path);\n  }\n  const layers = sparse.filter(Boolean);\n  for (const l of layers) l.sort((a, b) => a.localeCompare(b));\n\n  const unreachable = scan.files\n    .map((f) => f.path)\n    .filter((p) => !depth.has(p))\n    .sort();\n\n  return { layers, unreachable, seeds };\n}\n\nconst MAX_DEPTH = 12;\n\n// Written observations, in the order a senior dev would mention them.\n// Each: { id, tone: 'good' | 'note' | 'warn', severity: 'info' | 'low' | 'medium' | 'high', paths: string[], title, detail }.\nexport function detectPatterns(scan, facts, manifest, layersInfo) {\n  const out = [];\n  const topHub = facts.hubs[0];\n\n  if (topHub && topHub.fanIn >= 5) {\n    out.push({\n      id: 'hub-and-spoke',\n      tone: 'note',\n      severity: 'info',\n      paths: [topHub.path],\n      title: 'Hub and spoke',\n      detail: `\\`${topHub.path}\\` holds ${topHub.fanIn} dependents — this repo orbits a core. Learn that file and most of the rest makes sense.`,\n    });\n  }\n\n  const god = scan.files\n    .filter((f) => (facts.fanIn[f.path] || 0) + (facts.fanOut[f.path] || 0) >= 12)\n    .sort((a, b) => ((facts.fanIn[b.path] || 0) + (facts.fanOut[b.path] || 0)) - ((facts.fanIn[a.path] || 0) + (facts.fanOut[a.path] || 0)));\n\n  if (god.length) {\n    out.push({\n      id: 'god-files',\n      tone: 'warn',\n      severity: 'medium',\n      paths: god.map((f) => f.path),\n      title: god.length > 1 ? 'God files' : 'God file',\n      detail: `${god.slice(0, 3).map((f) => `\\`${f.path}\\``).join(', ')} — heavily connected in both directions. Everyone's problem, nobody's owner. Touch gently.`,\n    });\n  }\n\n  if (layersInfo && layersInfo.layers.length >= 3) {\n    out.push({\n      id: 'layered-shape',\n      tone: 'good',\n      severity: 'info',\n      paths: [],\n      title: 'A layered shape',\n      detail: `The code reads in ${layersInfo.layers.length} strata from the door to the deepest leaf. That is an architecture someone can draw — always a good sign.`,\n    });\n    if (layersInfo.unreachable.length) {\n      out.push({\n        id: 'unreachable',\n        tone: 'note',\n        severity: 'info',\n        paths: layersInfo.unreachable,\n        title: 'Off the beaten path',\n        detail: `${layersInfo.unreachable.length} files can't be reached from any entry point — utilities awaiting adoption, or furniture from an older layout.`,\n      });\n    }\n  }\n\n  if (facts.cycles.length) {\n    out.push({\n      id: 'cycles',\n      tone: 'warn',\n      severity: 'high',\n      paths: Array.from(new Set(facts.cycles.flat())),\n      title: 'Circular dependencies',\n      detail: `${facts.cycles.length} ${facts.cycles.length === 1 ? 'loop' : 'loops'} where files import each other; the biggest tangles ${facts.cycles[0].length} files. Untangle before a big refactor.`,\n    });\n  }\n\n  const barrels = scan.files.filter(\n    (f) =>\n      /^index\\.[jt]sx?$/.test(f.name) &&\n      f.functions.length === 0 &&\n      (facts.fanIn[f.path] || 0) >= 2 &&\n      (facts.fanOut[f.path] || 0) >= 2\n  );\n  if (barrels.length) {\n    out.push({\n      id: 'barrels',\n      tone: 'note',\n      severity: 'info',\n      paths: barrels.map((f) => f.path),\n      title: 'Barrel files',\n      detail: `${barrels.slice(0, 3).map((f) => `\\`${f.path}\\``).join(', ')} mostly re-export other modules. Convenient for imports, one extra hop when you're hunting a definition.`,\n    });\n  }\n\n  const testCount = scan.files.filter((f) => /(^|[._-])(test|spec|tests|__tests__)([._-]|\\/|$)/i.test(f.path)).length;\n  if (testCount > 0) {\n    const pct = Math.round((testCount / Math.max(1, scan.stats.filesParsed)) * 100);\n    out.push({\n      id: 'test-shadow',\n      tone: 'good',\n      severity: 'info',\n      paths: [],\n      title: 'A test shadow',\n      detail: `${testCount} test ${testCount === 1 ? 'file' : 'files'} against ${scan.stats.filesParsed} code files (~${pct}%). Read tests to learn intended behavior, code to learn actual behavior.`,\n    });\n  } else {\n    out.push({\n      id: 'no-tests',\n      tone: 'warn',\n      severity: 'medium',\n      paths: [],\n      title: 'No tests in sight',\n      detail: 'Nothing matches the usual test/spec naming. Onboarding risk: intended behavior lives only inside the code.',\n    });\n  }\n\n  if (facts.untestedHubs?.length) {\n    out.push({\n      id: 'untested-hubs',\n      tone: 'warn',\n      severity: 'high',\n      paths: facts.untestedHubs.map((h) => h.path),\n      title: 'Untested hubs',\n      detail: `${facts.untestedHubs.length} load-bearing ${facts.untestedHubs.length === 1 ? 'file is' : 'files are'} not reachable through test imports. Check whether tests exercise these files before changing them.`,\n    });\n  }\n\n  if (facts.deadExports?.length) {\n    const deadFiles = Array.from(new Set(facts.deadExports.map((d) => d.file)));\n    out.push({\n      id: 'dead-exports',\n      tone: 'note',\n      severity: 'low',\n      paths: deadFiles,\n      title: 'Unused exports',\n      detail: `${facts.deadExports.length} exported ${facts.deadExports.length === 1 ? 'symbol is' : 'symbols are'} never imported anywhere in the project. Potential dead code or unexposed public API.`,\n    });\n  }\n\n  if (facts.depsDrift?.undeclaredImported?.length) {\n    out.push({\n      id: 'undeclared-deps',\n      tone: 'warn',\n      severity: 'high',\n      paths: [],\n      title: 'Undeclared dependencies',\n      detail: `Imported packages not listed in package manifest: ${facts.depsDrift.undeclaredImported.slice(0, 4).map((d) => `\\`${d}\\``).join(', ')}. Risk of build failure in CI/clean environments.`,\n    });\n  }\n\n  if (facts.depsDrift?.unusedDeclared?.length) {\n    out.push({\n      id: 'unused-deps',\n      tone: 'note',\n      severity: 'low',\n      paths: [],\n      title: 'Unused dependencies',\n      detail: `Declared dependencies not directly imported in source: ${facts.depsDrift.unusedDeclared.slice(0, 5).map((d) => `\\`${d}\\``).join(', ')}.`,\n    });\n  }\n\n  if (facts.orphans.length) {\n    out.push({\n      id: 'orphans',\n      tone: 'note',\n      severity: 'info',\n      paths: facts.orphans,\n      title: 'Unclaimed territory',\n      detail: `${facts.orphans.length} ${facts.orphans.length === 1 ? 'file is' : 'files are'} imported by nothing. Dead code, or doors the naming rules didn't recognize.`,\n    });\n  }\n\n  const topExt = scan.externals[0];\n  if (topExt && topExt.usedBy.length >= 3) {\n    out.push({\n      id: 'top-external',\n      tone: 'note',\n      severity: 'info',\n      paths: topExt.usedBy,\n      title: 'Heaviest outside anchor',\n      detail: `\\`${topExt.name}\\` is pulled in by ${topExt.usedBy.length} files — the external dependency this repo would miss most.`,\n    });\n  }\n\n  if (manifest?.services?.length) {\n    out.push({\n      id: 'services',\n      tone: 'note',\n      severity: 'info',\n      paths: [],\n      title: 'Runs as services',\n      detail: `${manifest.services.length} ${manifest.services.length === 1 ? 'service' : 'services'} declared: ${manifest.services.map((s) => s.name).join(', ')}.`,\n    });\n  }\n\n  return out;\n}\n\n// Folder-to-folder traffic as a matrix for the heat grid. Folders are the\n// top-level ones, ordered by how much traffic they see in total.\nexport function couplingMatrix(scan, facts, maxFolders = 8) {\n  const traffic = new Map();\n  for (const fe of facts.folderEdges) {\n    traffic.set(fe.from, (traffic.get(fe.from) || 0) + fe.count);\n    traffic.set(fe.to, (traffic.get(fe.to) || 0) + fe.count);\n  }\n  const folders = [...traffic.entries()]\n    .sort((a, b) => b[1] - a[1])\n    .slice(0, maxFolders)\n    .map(([name]) => name);\n\n  const counts = new Map();\n  let max = 1;\n  for (const fe of facts.folderEdges) {\n    if (!folders.includes(fe.from) || !folders.includes(fe.to)) continue;\n    counts.set(fe.from + '->' + fe.to, fe.count);\n    max = Math.max(max, fe.count);\n  }\n  return { folders, counts, max };\n}\n"]}

package/shared/analyzer/scan.d.ts

@@ -0,0 +1,62 @@
+import type { FileSource, ScanOptions, ImportEdge, ScannedFile } from '../contracts.js';
+export { DEFAULT_LIMITS } from './scanControl.js';
+export declare function scanRepo(source: FileSource, options?: ScanOptions): Promise<{
+    root: string;
+    name: any;
+    scannedAt: string;
+    stats: {
+        filesTotal: number;
+        filesParsed: number;
+        skipped: number;
+        skips: {
+            ignored: number;
+            vendorDir: number;
+            notSource: number;
+            listFailed: number;
+            notCode: number;
+            readFailed: number;
+            tooLarge: number;
+            analyzeFailed: number;
+        };
+        truncated: any;
+        edgeCount: number;
+        imports: {
+            total: number;
+            internal: number;
+            external: number;
+            unresolved: number;
+            confidence: number;
+            worst: any[];
+        };
+        tookMs: number;
+        languages: Record<string, number>;
+        languageLoc: Record<string, number>;
+    };
+    allFiles: string[];
+    files: ScannedFile[];
+    edges: ImportEdge[];
+    externals: {
+        name: any;
+        usedBy: any[];
+    }[];
+    folders: {
+        path: string;
+        name: string;
+        depth: number;
+        fileCount: number;
+        loc: number;
+        comment: number;
+        blank: number;
+        size: number;
+        langs: Record<string, number>;
+        hasReadme: boolean;
+        docRatio: number;
+    }[];
+    workflows: any[];
+    sbom: any;
+    license: any;
+    licenseReport: any;
+} & {
+    tempId?: string;
+    gitUrl?: string;
+}>;