codebase-onboarder 0.1.0

package/shared/analyzer/history.js

@@ -0,0 +1,146 @@
+// Git history analysis: churn, authorship, the hotspot cross-tab, and
+// temporal co-change coupling. Pure — the commits arrive as plain data from an
+// injected provider (the server's `gitLog`), exactly as `scanRepo` takes files
+// through `FileSource`. Nothing here knows git exists.
+//
+// The unit of history is a commit: { hash, author: { name, email }, date, files }.
+// Everything is keyed on file path, which is already the join key the rest of
+// the engine speaks — complexity comes over from scan.files, structural edges
+// from scan.edges, and the two views of "these change together" sit side by side.
+
+import { baseName } from './pathUtil.js';
+
+// Commits touching more files than this are skipped for pair counting, not for
+// churn — a 900-file reformat or a mass rename would otherwise contribute
+// C(900,2) ≈ 400k pairs of noise to co-change while saying nothing about
+// coupling. Churn still counts them; every file in them was really touched.
+const MAX_COMMIT_FILES_FOR_PAIRS = 50;
+
+// Once this many distinct pairs are tracked, new pairs stop being recorded and
+// only existing ones keep counting. A hard bound on memory for repos with long
+// histories of small commits; the top of the list is decided well before this.
+const MAX_TRACKED_PAIRS = 5000;
+
+export function analyzeHistory(scan, commits, opts = {}) {
+  const totalCommits = opts.totalCommits ?? commits.length;
+  const truncated = totalCommits > commits.length;
+
+  // ---- per-file rollup -----------------------------------------------------
+  // One pass over every commit's file list. Authors are identified by email —
+  // names collide and change; the email is what git itself keys identity on.
+  const churn = new Map();     // path -> commit count
+  const authorsOf = new Map(); // path -> Map(email -> display name)
+  const firstSeen = new Map(); // path -> earliest commit date (ISO strings sort)
+  const lastTouched = new Map();
+  const authorCommits = new Map(); // email -> { name, commits }
+  let pathsGone = 0;
+
+  for (const c of commits) {
+    const date = c.date || '';
+    const known = authorCommits.get(c.author?.email);
+    if (known) known.commits++;
+    else if (c.author?.email) authorCommits.set(c.author.email, { name: c.author.name || c.author.email, commits: 1 });
+
+    for (const p of c.files || []) {
+      churn.set(p, (churn.get(p) || 0) + 1);
+      if (!firstSeen.has(p) || date < firstSeen.get(p)) firstSeen.set(p, date);
+      if (!lastTouched.has(p) || date > lastTouched.get(p)) lastTouched.set(p, date);
+      let byEmail = authorsOf.get(p);
+      if (!byEmail) { byEmail = new Map(); authorsOf.set(p, byEmail); }
+      if (!byEmail.has(c.author?.email)) byEmail.set(c.author?.email, c.author?.name || c.author?.email || '?');
+    }
+  }
+
+  // ---- join with the scan ---------------------------------------------------
+  // Complexity lives on scan.files; history paths that are not in the scan are
+  // files deleted or renamed inside the window. They had churn once — counted,
+  // then set aside rather than silently mixed into rankings of files that no
+  // longer exist.
+  const cxOf = new Map(scan.files.map((f) => [f.path, f.complexity || 1]));
+  for (const p of churn.keys()) if (!cxOf.has(p)) pathsGone++;
+
+  const live = [...churn.entries()].filter(([p]) => cxOf.has(p));
+  const maxChurn = Math.max(1, ...live.map(([, n]) => n));
+  const maxCx = Math.max(1, ...live.map(([p]) => cxOf.get(p)));
+
+  const perFile = live.map(([p, n]) => {
+    const authors = authorsOf.get(p).size;
+    return {
+      path: p,
+      name: baseName(p),
+      churn: n,
+      authors,
+      solo: authors === 1,
+      firstSeen: firstSeen.get(p),
+      lastTouched: lastTouched.get(p),
+      complexity: cxOf.get(p),
+      // The cross-tab: both axes normalized against the repo's own worst, so
+      // the score reads "how far up both columns at once" and a file maxing
+      // one axis but not the other cannot outrank one high on both.
+      hotspot: Math.round(100 * (n / maxChurn) * (cxOf.get(p) / maxCx)),
+    };
+  });
+  perFile.sort((a, b) => b.hotspot - a.hotspot || b.churn - a.churn || a.path.localeCompare(b.path));
+
+  const byPath = {};
+  for (const row of perFile) byPath[row.path] = row;
+  const soloFiles = perFile.filter((r) => r.solo && r.churn >= 3).length;
+
+  const dates = commits.map((c) => c.date).filter(Boolean);
+
+  return {
+    available: true,
+    commitCount: commits.length,
+    totalCommits,
+    truncated,
+    // The raw commit list, not just the rollups. The insights view draws a
+    // 52-week heatmap and a punch card from per-commit dates; without the
+    // original array, that view rendered an empty calendar even when history
+    // was fully available. The cost is the same parsed commits we already hold
+    // — `parseGitLog` capped at 2,000 — so duplication here is honest.
+    commits,
+    authors: [...authorCommits.values()].sort((a, b) => b.commits - a.commits),
+    firstCommitAt: dates.length ? dates.reduce((a, b) => (a < b ? a : b)) : null,
+    lastCommitAt: dates.length ? dates.reduce((a, b) => (a > b ? a : b)) : null,
+    perFile,
+    byPath,
+    soloFiles,
+    coChanged: coChangePairs(commits, new Set(scan.edges.map((e) => e.from + '->' + e.to))),
+    pathsGone,
+  };
+}
+
+// Files that keep turning up in the same commit without importing each other.
+// The structural coupling matrix already shows what imports what; this is the
+// contrast — changes that travel together for reasons the import graph does
+// not know about (shared schema, feature pairs, copy-paste siblings).
+function coChangePairs(commits, structuralEdges) {
+  const pairs = new Map(); // 'a|b' (sorted) -> count
+
+  for (const c of commits) {
+    const files = c.files || [];
+    if (files.length < 2 || files.length > MAX_COMMIT_FILES_FOR_PAIRS) continue;
+    for (let i = 0; i < files.length; i++) {
+      for (let j = i + 1; j < files.length; j++) {
+        const a = files[i] < files[j] ? files[i] : files[j];
+        const b = files[i] < files[j] ? files[j] : files[i];
+        if (structuralEdges.has(a + '->' + b) || structuralEdges.has(b + '->' + a)) continue;
+        const key = a + '|' + b;
+        const seen = pairs.get(key);
+        if (seen) seen.count++;
+        else if (pairs.size < MAX_TRACKED_PAIRS) pairs.set(key, { a, b, count: 1 });
+      }
+    }
+  }
+
+  return [...pairs.values()]
+    .filter((p) => p.count >= 2) // once is coincidence; the plan is about habits
+    .sort((x, y) => y.count - x.count || x.a.localeCompare(y.a))
+    .slice(0, 20);
+}
+
+// The shape callers should hold when there is nothing to analyze — same fields,
+// honest reason. Views render this instead of inventing zeros.
+export function unavailableHistory(reason) {
+  return { available: false, reason };
+}

package/shared/analyzer/languages/csharp.js

@@ -0,0 +1,39 @@
+// C# analyzer
+import { blankComments, lineCounter, uniqueBy } from '../util.js';
+
+export const extensions = ['.cs'];
+
+export function analyze(source, path) {
+  const clean = blankComments(source);
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  for (const m of clean.matchAll(/\busing\s+([a-zA-Z0-9_.]+)\s*;/g)) {
+    imports.push({ spec: m[1], line: lineAt(m.index) });
+  }
+
+  const classes = [];
+  for (const m of clean.matchAll(/(\[[^\]]+\]\s*)*\b(?:public\s+|private\s+|protected\s+|internal\s+)*(?:abstract\s+|sealed\s+)?(?:class|interface|struct|record|enum)\s+([a-zA-Z0-9_]+)/g)) {
+    const attributes = [];
+    if (m[1]) {
+      for (const am of m[1].matchAll(/\[([A-Za-z0-9_]+)/g)) {
+        attributes.push(am[1]);
+      }
+    }
+    classes.push({ name: m[2], attributes, line: lineAt(m.index) });
+  }
+
+  const hasMain = /static\s+(?:async\s+Task|void|int|async\s+Task<int>)\s+Main\s*\(/.test(clean);
+
+  return {
+    imports,
+    exports: classes.map(c => ({ name: c.name, kind: 'class' })),
+    functions: [],
+    classes,
+    hasMain
+  };
+}
+
+export function resolveImport(spec, fromPath, has, context = {}) {
+  return { unresolved: spec };
+}

package/shared/analyzer/languages/generic.js

@@ -0,0 +1,131 @@
+// Generic analyzer for C/C++, Ruby, and PHP — the languages that don't have
+// a dedicated module. Java, Rust, and C# each have their own analyzer in this
+// directory and are dispatched first by `languages/index.js`; the blocks for
+// them used to live here, before they had anywhere better to go, and were
+// removed when those files landed so the dispatch table is the only place
+// that decides which family a file belongs to.
+//
+// The work this module does is deliberately cheap: a regex pass for the
+// include/import/require/use lines plus the obvious function and class
+// shapes. It is enough to place these files on the map; treating it as more
+// than that would be lying.
+
+import { blankComments, lineCounter, uniqueBy } from '../util.js';
+import { dirOf, joinPath, baseName } from '../pathUtil.js';
+
+export const extensions = ['.c', '.h', '.cc', '.cpp', '.hpp', '.rb', '.php'];
+
+const BY_EXT = {
+  c: 'c', h: 'c', cc: 'c', cpp: 'c', hpp: 'c',
+  rb: 'ruby', php: 'php',
+};
+
+const CONTROL = new Set(['if', 'for', 'while', 'switch', 'catch', 'return', 'sizeof', 'do', 'else']);
+
+export function analyze(source, path) {
+  const family = BY_EXT[path.slice(path.lastIndexOf('.') + 1)] || 'c';
+  const clean = blankComments(source, { lineChar: family === 'ruby' ? '#' : '//' });
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  const functions = [];
+  const classes = [];
+
+  if (family === 'c') {
+    for (const m of clean.matchAll(/^[ \t]*#[ \t]*include[ \t]*"([^"]+)"/gm)) {
+      imports.push({ spec: m[1], local: true, line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/^[ \t]*#[ \t]*include[ \t]*<([^>]+)>/gm)) {
+      imports.push({ spec: m[1], local: false, line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/^[A-Za-z_][\w\s\*]*?\s+([\w]+)\s*\([^;{}]*\)\s*\{/gm)) {
+      if (!CONTROL.has(m[1])) functions.push({ name: m[1], kind: 'function', line: lineAt(m.index) });
+    }
+  }
+
+  if (family === 'ruby') {
+    for (const m of clean.matchAll(/^[ \t]*require_relative\s+['"]([^'"]+)['"]/gm)) {
+      imports.push({ spec: m[1], kind: 'require_relative', line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/^[ \t]*require\s+['"]([^'"]+)['"]/gm)) {
+      imports.push({ spec: m[1], kind: 'require', line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/^[ \t]*def\s+([\w!?]+)/gm)) {
+      functions.push({ name: m[1], kind: 'function', line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/^[ \t]*(?:class|module)\s+([\w:]+)/gm)) {
+      classes.push({ name: m[1], line: lineAt(m.index) });
+    }
+  }
+
+  if (family === 'php') {
+    for (const m of clean.matchAll(/\b(?:require|include)(?:_once)?\s*\(?\s*['"]([^'"]+)['"]/g)) {
+      imports.push({ spec: m[1], kind: 'require', line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/^[ \t]*use\s+([\w\\]+)\s*;/gm)) {
+      imports.push({ spec: m[1], kind: 'use', line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/\bfunction\s+([\w]+)\s*\(/g)) {
+      functions.push({ name: m[1], kind: 'function', line: lineAt(m.index) });
+    }
+    for (const m of clean.matchAll(/\bclass\s+([\w]+)/g)) {
+      classes.push({ name: m[1], line: lineAt(m.index) });
+    }
+  }
+
+  return {
+    imports: uniqueBy(imports, (i) => i.spec + ':' + (i.kind || '')),
+    exports: [],
+    functions,
+    classes,
+    calls: [],
+    hasMain: family === 'c' && /\bint\s+main\s*\(/.test(clean),
+  };
+}
+
+export function packageNameOf(spec) {
+  if (spec.endsWith('.h') || spec.endsWith('.hpp')) return spec;
+  return spec.split(/[.:/\\]/)[0] || spec;
+}
+
+export function resolveImport(spec, fromPath, has, context = {}, meta = {}) {
+  const fromDir = dirOf(fromPath);
+  const { findByName = () => null } = context;
+
+  // C angle-bracket includes like <stdio.h> are explicitly external
+  if (meta.local === false && meta.kind !== 'mod' && meta.kind !== 'use' && meta.kind !== 'import') {
+    return { external: packageNameOf(spec) };
+  }
+
+  const cleaned = spec.replace(/::/g, '/').replace(/\\/g, '/').replace(/\./g, '/');
+  const lastDot = spec.lastIndexOf('.');
+  const lastSlash = Math.max(spec.lastIndexOf('/'), spec.lastIndexOf('\\'));
+  const lastColon = spec.lastIndexOf('::');
+  const lastSep = Math.max(lastDot, lastSlash, lastColon >= 0 ? lastColon + 1 : -1);
+  const lastSegment = lastSep >= 0 ? spec.slice(lastSep + 1) : spec;
+
+  // Only the extensions this module owns. Java/Rust have their own resolvers.
+  const candidates = [
+    joinPath(fromDir, spec),
+    joinPath(fromDir, spec) + '.rb',
+    joinPath(fromDir, cleaned) + '.rb',
+    joinPath(fromDir, cleaned) + '.php',
+    joinPath(fromDir, spec) + '.php',
+  ];
+  for (const cand of candidates) {
+    if (cand && has(cand)) return { path: cand };
+  }
+
+  // Last resort for quoted includes: match on the file name anywhere.
+  if (lastSegment && lastSegment !== '*') {
+    const hitPhp = findByName(lastSegment + '.php');
+    if (hitPhp) return { path: hitPhp };
+  }
+  const hit = findByName(baseName(spec));
+  if (hit) return { path: hit };
+
+  if (meta.kind === 'use' || meta.kind === 'import' || meta.kind === 'require' || meta.local === false) {
+    return { external: packageNameOf(spec) };
+  }
+  return { unresolved: spec };
+}

package/shared/analyzer/languages/go.js

@@ -0,0 +1,70 @@
+// Go. Package-oriented: imports resolve to directories, and the scanner maps
+// a directory to the Go files inside it.
+
+import { blankComments, lineCounter, uniqueBy } from '../util.js';
+
+export const extensions = ['.go'];
+
+const IMPORT_SINGLE_RE = /^[ \t]*import\s+(?:[\w.]+\s+)?"([^"]+)"/gm;
+const IMPORT_BLOCK_RE = /\bimport\s*\(([\s\S]*?)\)/g;
+const QUOTED_RE = /"([^"]+)"/g;
+const FUNC_RE = /^func\s+(?:\(([^)]*)\)\s*)?([\w]+)\s*\(/gm;
+const PACKAGE_RE = /^package\s+([\w]+)/m;
+
+export function analyze(source, path) {
+  const clean = blankComments(source);
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  for (const m of clean.matchAll(IMPORT_SINGLE_RE)) {
+    imports.push({ spec: m[1], line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(IMPORT_BLOCK_RE)) {
+    for (const q of m[1].matchAll(QUOTED_RE)) {
+      imports.push({ spec: q[1], line: lineAt(m.index) });
+    }
+  }
+
+  const functions = [];
+  for (const m of clean.matchAll(FUNC_RE)) {
+    functions.push({
+      name: m[2],
+      kind: m[1] ? 'method' : 'function',
+      receiver: m[1] ? m[1].replace(/[*]/g, '').trim().split(/\s+/).pop() : undefined,
+      line: lineAt(m.index),
+    });
+  }
+
+  const pkg = (clean.match(PACKAGE_RE) || [])[1] || '';
+  const hasMain = pkg === 'main' && /^func\s+main\s*\(\s*\)/m.test(clean);
+
+  const exports = functions
+    .filter((f) => /^[A-Z]/.test(f.name))
+    .map((f) => ({ name: f.name, kind: f.kind }));
+
+  return {
+    imports: uniqueBy(imports, (i) => i.spec),
+    exports: uniqueBy(exports, (e) => e.name),
+    functions,
+    classes: [],
+    calls: [],
+    hasMain,
+    packageName: pkg,
+  };
+}
+
+export function packageNameOf(spec) {
+  return spec.split('/')[0].includes('.') ? spec.split('/').slice(0, 3).join('/') : spec.split('/')[0];
+}
+
+export function resolveImport(spec, fromPath, has, context = {}) {
+  const { modulePath = '', hasDir = () => false } = context;
+  if (modulePath && (spec === modulePath || spec.startsWith(modulePath + '/'))) {
+    const dir = spec.slice(modulePath.length).replace(/^\//, '');
+    if (hasDir(dir)) return { packageDir: dir };
+    return { unresolved: spec };
+  }
+  // Without a go.mod we guess: no dot in the first segment usually means the
+  // standard library; anything else is treated as an external module.
+  return { external: packageNameOf(spec) };
+}

package/shared/analyzer/languages/index.js

@@ -0,0 +1,43 @@
+// Language registry. Order matters: the first match on extension wins.
+
+import * as typescript from './typescript.js';
+import * as javascript from './javascript.js';
+import * as python from './python.js';
+import * as go from './go.js';
+import * as rust from './rust.js';
+import * as java from './java.js';
+import * as csharp from './csharp.js';
+import * as generic from './generic.js';
+
+export const languages = [
+  { id: 'typescript', label: 'TypeScript', short: 'TS', ...typescript },
+  { id: 'javascript', label: 'JavaScript', short: 'JS', ...javascript },
+  { id: 'python', label: 'Python', short: 'Python', ...python },
+  { id: 'go', label: 'Go', short: 'Go', ...go },
+  { id: 'rust', label: 'Rust', short: 'Rust', ...rust },
+  { id: 'java', label: 'Java', short: 'Java', ...java },
+  { id: 'csharp', label: 'C#', short: 'C#', ...csharp },
+  { id: 'generic', label: 'C / Ruby / PHP', short: 'C/Ruby/…', ...generic },
+];
+
+const byExtension = new Map();
+for (const lang of languages) {
+  for (const ext of lang.extensions) byExtension.set(ext, lang);
+}
+
+export function languageFor(path) {
+  const i = path.lastIndexOf('.');
+  if (i === -1) return null;
+  return byExtension.get(path.slice(i).toLowerCase()) || null;
+}
+
+// Display names for a language id. Both spellings were previously hardcoded in
+// two places that had drifted apart — a `generic` file was labelled "C/Java/…"
+// in one panel and "C/Java/Rust/Ruby/PHP" in another. The registry already knew
+// the answer; now it is the only one that does. An unknown id comes back as
+// itself, so a new language shows up as a lowercase word rather than nothing.
+export function languageLabel(id, { short = false } = {}) {
+  const lang = languages.find((l) => l.id === id);
+  if (!lang) return String(id);
+  return short ? lang.short : lang.label;
+}

package/shared/analyzer/languages/java.js

@@ -0,0 +1,39 @@
+// Java analyzer
+import { blankComments, lineCounter, uniqueBy } from '../util.js';
+
+export const extensions = ['.java'];
+
+export function analyze(source, path) {
+  const clean = blankComments(source);
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  for (const m of clean.matchAll(/\bimport\s+(static\s+)?([a-zA-Z0-9_.]+)/g)) {
+    imports.push({ spec: m[2], static: !!m[1], line: lineAt(m.index) });
+  }
+
+  const classes = [];
+  for (const m of clean.matchAll(/(@[A-Za-z0-9_]+\s*)*\b(?:public\s+|private\s+|protected\s+)?(?:abstract\s+)?(?:class|interface|enum|record|@interface)\s+([a-zA-Z0-9_]+)/g)) {
+    const annotations = [];
+    if (m[1]) {
+      for (const am of m[1].matchAll(/@([A-Za-z0-9_]+)/g)) {
+        annotations.push(am[1]);
+      }
+    }
+    classes.push({ name: m[2], annotations, line: lineAt(m.index) });
+  }
+
+  const hasMain = /public\s+static\s+void\s+main\s*\(/.test(clean);
+
+  return {
+    imports,
+    exports: classes.map(c => ({ name: c.name, kind: 'class' })),
+    functions: [],
+    classes,
+    hasMain
+  };
+}
+
+export function resolveImport(spec, fromPath, has, context = {}) {
+  return { unresolved: spec };
+}