codebase-onboarder 0.1.0

package/shared/analyzer/metrics.js

@@ -0,0 +1,120 @@
+import { blankComments } from './util.js';
+
+const DECISIONS = {
+  javascript: /\b(if|for|while|case|catch|do|else if)\b/g,
+  python: /\b(if|elif|for|while|except)\b/g,
+  go: /\b(if|for|case|go|select)\b/g,
+};
+const GENERIC = /\b(if|elif|for|while|case|catch|except|switch)\b/g;
+
+export function codeStats(source, lang = '') {
+  const lines = String(source).split('\n');
+  let blank = 0;
+  let comment = 0;
+  let code = 0;
+  let inBlock = false;
+  const isHashComment = ['python', 'ruby', 'yaml', 'toml', 'shell', 'bash', 'sh'].includes(lang)
+    || (!lang && (source.includes('#!') || /\b(def|import|class)\b/.test(source)));
+
+  for (const raw of lines) {
+    const l = raw.trim();
+    if (!l) { blank++; continue; }
+    if (inBlock) { comment++; if (l.includes('*/')) inBlock = false; continue; }
+    if (l.startsWith('//') || (isHashComment && l.startsWith('#'))) { comment++; continue; }
+    if (l.startsWith('/*')) { comment++; if (!l.includes('*/')) inBlock = true; continue; }
+    code++;
+  }
+  return { lines: lines.length, code, comment, blank };
+}
+
+export function complexityOf(source, lang) {
+  const isHash = ['python', 'ruby', 'yaml', 'toml', 'shell'].includes(lang);
+  const clean = blankComments(String(source), { lineChar: isHash ? '#' : '//' });
+  const rx = DECISIONS[lang] || GENERIC;
+  let score = 1;
+  const decisions = clean.match(rx);
+  score += decisions ? decisions.length : 0;
+  const bools = clean.match(/&&|\|\||\?/g); // boolean ops + ternaries
+  score += bools ? bools.length : 0;
+  return score;
+}
+
+export function halsteadMetrics(source, lang) {
+  const isHash = ['python', 'ruby', 'yaml', 'toml', 'shell'].includes(lang);
+  const clean = blankComments(String(source), { lineChar: isHash ? '#' : '//' });
+  
+  const ops = ['\+', '-', '\*', '/', '=', '==', '===', '!=', '!==', '<', '>', '<=', '>=', '&&', '\|\|', '!', '%', '\*\*', '\+\+', '--', '\+=', '-=', '\*=', '/=', '=>', '\?\?', '\?\.', '\.\.\.'];
+  const opPattern = new RegExp(ops.map(o => o.replace(/[.*+?^$\\{}()|[\]\\]/g, '\\$&')).join('|'), 'g');
+  
+  const operators = new Set();
+  let N1 = 0;
+  for (const m of clean.matchAll(opPattern)) {
+    operators.add(m[0]);
+    N1++;
+  }
+  const n1 = operators.size;
+
+  const operands = new Set();
+  let N2 = 0;
+  for (const m of clean.matchAll(/\b[a-zA-Z_][a-zA-Z0-9_]*\b|\b\d+\b|['"][^'"]*['"]/g)) {
+    const val = m[0];
+    if (["if", "else", "for", "while", "return", "function", "class", "import", "export", "var", "let", "const", "true", "false", "null"].includes(val)) continue;
+    operands.add(val);
+    N2++;
+  }
+  const n2 = operands.size;
+
+  const vocabulary = n1 + n2;
+  const length = N1 + N2;
+  const volume = vocabulary === 0 ? 0 : length * Math.log2(vocabulary);
+  const difficulty = (n2 === 0 || n1 === 0) ? 0 : (n1 / 2) * (N2 / n2);
+  const effort = difficulty * volume;
+
+  return { n1, n2, N1, N2, vocabulary, length, volume, difficulty, effort };
+}
+
+export function cognitiveComplexity(source, lang) {
+  const isHash = ['python', 'ruby', 'yaml', 'toml', 'shell'].includes(lang);
+  const clean = blankComments(String(source), { lineChar: isHash ? '#' : '//' });
+  
+  let score = 0;
+  let nesting = 0;
+  let inSwitch = false;
+
+  const lines = clean.split('\n');
+  for (const line of lines) {
+    const l = line.trim();
+    if (l.includes('{')) {
+      if (/\b(if|for|while|do|switch|catch)\b/.test(l)) {
+        if (/\bswitch\b/.test(l)) {
+          inSwitch = true;
+          score += (1 + nesting);
+          nesting++;
+        } else {
+          score += (1 + nesting);
+          nesting++;
+        }
+      } else {
+        nesting++;
+      }
+    }
+    if (l.includes('}')) {
+      nesting = Math.max(0, nesting - 1);
+    }
+    if (!l.includes('{') && /\b(if|else if|for|while|do|catch)\b/.test(l)) {
+        score += (1 + nesting);
+    }
+    if (/\belse\b(?!\s+if)/.test(l)) {
+       score += 1;
+    }
+    const ops = l.match(/&&|\|\||\?/g);
+    if (ops) score += ops.length;
+  }
+  return score;
+}
+
+export function maintainabilityIndex(halstead, complexity, loc) {
+  if (halstead.volume === 0 || loc === 0) return 100;
+  let MI = (171 - 5.2 * Math.log(halstead.volume) - 0.23 * complexity - 16.2 * Math.log(loc)) * 100 / 171;
+  return Math.max(0, Math.min(100, MI));
+}

package/shared/analyzer/pathUtil.js

@@ -0,0 +1,69 @@
+// Repo-relative path helpers. Everything here is POSIX-style with forward
+// slashes, no leading slash, no trailing slash. Both file source adapters
+// normalize to this convention before the analyzer sees a path.
+
+export function normalize(path) {
+  const out = [];
+  for (const part of String(path).split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') {
+      out.pop();
+      continue;
+    }
+    out.push(part);
+  }
+  return out.join('/');
+}
+
+export function joinPath(...parts) {
+  return normalize(parts.filter(Boolean).join('/'));
+}
+
+export function dirOf(path) {
+  const i = path.lastIndexOf('/');
+  return i === -1 ? '' : path.slice(0, i);
+}
+
+export function baseName(path) {
+  const i = path.lastIndexOf('/');
+  return path.slice(i + 1);
+}
+
+export function extOf(path) {
+  const base = baseName(path);
+  const i = base.lastIndexOf('.');
+  return i <= 0 ? '' : base.slice(i).toLowerCase();
+}
+
+export function depthOf(path) {
+  if (!path) return 0;
+  return path.split('/').length;
+}
+
+export function topFolderOf(path) {
+  const i = path.indexOf('/');
+  return i === -1 ? '(root)' : path.slice(0, i);
+}
+
+// Does this path look like a test? Naming, not content — there is no reliable
+// way to tell from a path alone, and every repo names them differently. The
+// alternatives are bounded by the separators: `foo.test.js`, `foo_spec.rb`,
+// `tests/foo.py`, `__tests__/foo.jsx`. A word merely *containing* "test"
+// (`contest.js`, `latest.md`, `protester.go`) must not match, which is what the
+// separator groups on either side are for.
+export const TEST_PATH_RE = /(^|[._\-/])(test|tests|spec|specs|__tests__|__test__)([._\-/]|$)/i;
+
+export function isTestPath(path) {
+  return TEST_PATH_RE.test(path);
+}
+
+// The stage filters, as a predicate over paths — or null when nothing is being
+// filtered at all. Null rather than `() => true` on purpose: every diagram
+// builder takes an `include` option and skips the whole filtering pass when it is
+// absent, so the common case costs nothing. Callers must keep treating a missing
+// filter as "everything", not as "nothing".
+export function pathFilter({ text = '', showTests = true } = {}) {
+  const needle = text.trim().toLowerCase();
+  if (!needle && showTests) return null;
+  return (p) => (showTests || !isTestPath(p)) && (!needle || p.toLowerCase().includes(needle));
+}

package/shared/analyzer/patterns.js

@@ -0,0 +1,272 @@
+// 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);
+      }
+    }
+  }
+
+  // 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.`,
+      });
+    }
+  }
+
+  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;
+}
+
+// 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 };
+}