@archora/core 1.1.0

package/src/diff/__tests__/diffScans.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import { diffScans } from '../diffScans';
+import type { Cycle, ModuleNode, ScanResult } from '../../analyzer/types';
+
+function mod(id: string, overrides: Partial<ModuleNode> = {}): ModuleNode {
+  return {
+    id,
+    absPath: '/' + id,
+    kind: 'util',
+    language: 'ts',
+    loc: 10,
+    exports: [],
+    isInfra: false,
+    ...overrides,
+  };
+}
+
+function cycle(id: string, modules: string[]): Cycle {
+  return {
+    id,
+    modules,
+    length: modules.length,
+    severity: modules.length <= 2 ? 'direct' : 'indirect',
+  };
+}
+
+function scan(overrides: Partial<ScanResult>): ScanResult {
+  return {
+    project: { id: 'p', name: 'p', rootPath: '/p', detectedFramework: 'unknown' },
+    modules: [],
+    edges: [],
+    cycles: [],
+    metrics: {},
+    hotZones: [],
+    layerViolations: [],
+    archDebt: {
+      score: 0,
+      grade: 'A',
+      breakdown: { cycles: 0, layerViolations: 0, hotZones: 0, coupling: 0 },
+    },
+    recommendations: [],
+    contractViolations: [],
+    scannedAt: '2026-05-07T00:00:00Z',
+    durationMs: 0,
+    warnings: [],
+    ...overrides,
+  };
+}
+
+describe('diffScans', () => {
+  it('reports added and removed modules', () => {
+    const prev = scan({ modules: [mod('a'), mod('b')] });
+    const next = scan({ modules: [mod('a'), mod('c')] });
+    const d = diffScans(prev, next);
+    expect(d.addedModules.map((m) => m.id)).toEqual(['c']);
+    expect(d.removedModules.map((m) => m.id)).toEqual(['b']);
+    expect(d.changedModules).toEqual([]);
+    expect(d.summary).toMatchObject({ addedModules: 1, removedModules: 1, changedModules: 0 });
+  });
+
+  it('reports changed modules only on visible attributes', () => {
+    const prev = scan({ modules: [mod('a', { kind: 'util', loc: 10 })] });
+    const next = scan({ modules: [mod('a', { kind: 'route', loc: 12 })] });
+    const d = diffScans(prev, next);
+    expect(d.changedModules).toHaveLength(1);
+    expect(d.changedModules[0]?.prev.kind).toBe('util');
+    expect(d.changedModules[0]?.next.kind).toBe('route');
+  });
+
+  it('does not flag identical modules as changed', () => {
+    const prev = scan({ modules: [mod('a')] });
+    const next = scan({ modules: [mod('a')] });
+    expect(diffScans(prev, next).changedModules).toEqual([]);
+  });
+
+  it('matches cycles by module-set ignoring analyzer cycle ids and order', () => {
+    const prev = scan({
+      cycles: [cycle('c1', ['a', 'b']), cycle('c2', ['x', 'y', 'z'])],
+    });
+    const next = scan({
+      // same set members, different ids and order
+      cycles: [cycle('c99', ['b', 'a']), cycle('c100', ['n', 'm'])],
+    });
+    const d = diffScans(prev, next);
+    expect(d.newCycles.map((c) => c.modules.sort())).toEqual([['m', 'n']]);
+    expect(d.resolvedCycles.map((c) => c.modules.sort())).toEqual([['x', 'y', 'z']]);
+  });
+
+  it('returns empty diff for identical scans', () => {
+    const s = scan({
+      modules: [mod('a'), mod('b')],
+      cycles: [cycle('c1', ['a', 'b'])],
+    });
+    const d = diffScans(s, s);
+    expect(d.summary).toEqual({
+      addedModules: 0,
+      removedModules: 0,
+      changedModules: 0,
+      newCycles: 0,
+      resolvedCycles: 0,
+    });
+  });
+});

package/src/diff/diffScans.ts

@@ -0,0 +1,61 @@
+import type { Cycle, ScanResult } from '../analyzer/types';
+import type { ChangedModule, ScanDiff } from './types';
+
+// module id = project-relative path; cycle id = sorted member set.
+// module "changed" only when kind/loc/language differ. no edge-level diff.
+export function diffScans(prev: ScanResult, next: ScanResult): ScanDiff {
+  const prevModulesById = new Map(prev.modules.map((m) => [m.id, m]));
+  const nextModulesById = new Map(next.modules.map((m) => [m.id, m]));
+
+  const addedModules = next.modules.filter((m) => !prevModulesById.has(m.id));
+  const removedModules = prev.modules.filter((m) => !nextModulesById.has(m.id));
+
+  const changedModules: ChangedModule[] = [];
+  for (const m of next.modules) {
+    const before = prevModulesById.get(m.id);
+    if (!before) continue;
+    if (before.kind !== m.kind || before.loc !== m.loc || before.language !== m.language) {
+      changedModules.push({
+        id: m.id,
+        prev: { kind: before.kind, loc: before.loc, language: before.language },
+        next: { kind: m.kind, loc: m.loc, language: m.language },
+      });
+    }
+  }
+
+  const prevCyclesByKey = new Map(prev.cycles.map((c) => [canonicalCycleKey(c), c]));
+  const nextCyclesByKey = new Map(next.cycles.map((c) => [canonicalCycleKey(c), c]));
+
+  const newCycles: Cycle[] = [];
+  for (const [key, cycle] of nextCyclesByKey) {
+    if (!prevCyclesByKey.has(key)) newCycles.push(cycle);
+  }
+  const resolvedCycles: Cycle[] = [];
+  for (const [key, cycle] of prevCyclesByKey) {
+    if (!nextCyclesByKey.has(key)) resolvedCycles.push(cycle);
+  }
+
+  return {
+    projectId: next.project.id,
+    projectName: next.project.name,
+    prevScannedAt: prev.scannedAt,
+    nextScannedAt: next.scannedAt,
+    addedModules,
+    removedModules,
+    changedModules,
+    newCycles,
+    resolvedCycles,
+    summary: {
+      addedModules: addedModules.length,
+      removedModules: removedModules.length,
+      changedModules: changedModules.length,
+      newCycles: newCycles.length,
+      resolvedCycles: resolvedCycles.length,
+    },
+  };
+}
+
+/** Stable, order-independent identifier for a cycle's member set. */
+function canonicalCycleKey(cycle: Cycle): string {
+  return [...cycle.modules].sort().join('\u0001');
+}

package/src/diff/index.ts

@@ -0,0 +1,2 @@
+export { diffScans } from './diffScans';
+export type { ScanDiff, ChangedModule, ScanDiffSummary } from './types';

package/src/diff/types.ts

@@ -0,0 +1,39 @@
+import type { Cycle, ModuleId, ModuleNode } from '../analyzer/types';
+
+export interface ScanDiff {
+  /** Project id and name from the *current* (newer) scan, for display. */
+  projectId: string;
+  projectName: string;
+  /** ISO timestamps of the compared scans. */
+  prevScannedAt: string;
+  nextScannedAt: string;
+
+  /** Modules that exist in `next` but not in `prev`. */
+  addedModules: ModuleNode[];
+  /** Modules that existed in `prev` but were dropped in `next`. */
+  removedModules: ModuleNode[];
+  /** Modules whose `kind`, `loc` or `language` changed. */
+  changedModules: ChangedModule[];
+
+  /** Cycles that did not appear in `prev` (matched by sorted module-id set). */
+  newCycles: Cycle[];
+  /** Cycles that disappeared in `next`. */
+  resolvedCycles: Cycle[];
+
+  /** Aggregate counts for quick rendering at the top of a diff view. */
+  summary: ScanDiffSummary;
+}
+
+export interface ChangedModule {
+  id: ModuleId;
+  prev: { kind: ModuleNode['kind']; loc: number; language: ModuleNode['language'] };
+  next: { kind: ModuleNode['kind']; loc: number; language: ModuleNode['language'] };
+}
+
+export interface ScanDiffSummary {
+  addedModules: number;
+  removedModules: number;
+  changedModules: number;
+  newCycles: number;
+  resolvedCycles: number;
+}

package/src/git/__tests__/computeChurn.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { computeChurn } from '../computeChurn';
+import type { GitCommit, GitHistory } from '../types';
+import type { ModuleNode } from '../../analyzer/types';
+
+function mod(id: string): ModuleNode {
+  return {
+    id,
+    absPath: id,
+    kind: 'unknown',
+    language: 'ts',
+    loc: 10,
+    exports: [],
+    isInfra: false,
+  };
+}
+
+function commit(
+  sha: string,
+  email: string,
+  date: string,
+  changes: Array<{ path: string; added: number; removed: number; renamedFrom?: string }>,
+): GitCommit {
+  return {
+    sha,
+    shortSha: sha.slice(0, 7),
+    author: email,
+    authorName: email,
+    authoredAt: date,
+    subject: sha,
+    changes: changes.map((c) => ({
+      path: c.path,
+      added: c.added,
+      removed: c.removed,
+      ...(c.renamedFrom ? { renamedFrom: c.renamedFrom } : {}),
+    })),
+  };
+}
+
+function history(commits: GitCommit[]): GitHistory {
+  return { since: '90d', until: 'now', commits, includesMerges: false };
+}
+
+describe('computeChurn', () => {
+  it('counts commits, lines, authors per module', () => {
+    const modules = [mod('src/a.ts'), mod('src/b.ts')];
+    const h = history([
+      commit('1', 'alice@x.com', '2026-05-01T10:00:00Z', [
+        { path: 'src/a.ts', added: 5, removed: 2 },
+      ]),
+      commit('2', 'bob@x.com', '2026-05-03T10:00:00Z', [
+        { path: 'src/a.ts', added: 1, removed: 0 },
+        { path: 'src/b.ts', added: 3, removed: 1 },
+      ]),
+      commit('3', 'alice@x.com', '2026-05-05T10:00:00Z', [
+        { path: 'src/a.ts', added: 0, removed: 4 },
+      ]),
+    ]);
+    const churn = computeChurn({ modules, history: h });
+    expect(churn['src/a.ts']?.commits).toBe(3);
+    expect(churn['src/a.ts']?.linesChanged).toBe(5 + 2 + 1 + 0 + 4);
+    expect(churn['src/a.ts']?.authorCount).toBe(2);
+    expect(churn['src/a.ts']?.lastTouchedAt).toBe('2026-05-05T10:00:00Z');
+    expect(churn['src/b.ts']?.commits).toBe(1);
+    expect(churn['src/b.ts']?.authorCount).toBe(1);
+  });
+
+  it('sorts authors by commit count desc and collapses past top 5', () => {
+    const modules = [mod('src/a.ts')];
+    const ppl = ['a', 'b', 'c', 'd', 'e', 'f', 'g'];
+    const counts = [10, 5, 5, 3, 2, 2, 1];
+    const commits: GitCommit[] = [];
+    let n = 0;
+    for (let i = 0; i < ppl.length; i++) {
+      for (let j = 0; j < counts[i]!; j++) {
+        commits.push(
+          commit(`${++n}`.padStart(7, '0'), `${ppl[i]}@x.com`, '2026-01-01T00:00:00Z', [
+            { path: 'src/a.ts', added: 1, removed: 0 },
+          ]),
+        );
+      }
+    }
+    const churn = computeChurn({ modules, history: history(commits) });
+    const authors = churn['src/a.ts']?.authors ?? [];
+    expect(authors).toHaveLength(6); // top 5 + __other__
+    expect(authors[0]).toEqual({ author: 'a@x.com', commits: 10 });
+    expect(authors[5]).toEqual({ author: '__other__', commits: 2 + 1 }); // f+g
+  });
+
+  it('charges renames against both old and new paths', () => {
+    const modules = [mod('src/old.ts'), mod('src/new.ts')];
+    const h = history([
+      commit('1', 'a@x', '2026-05-01T10:00:00Z', [
+        { path: 'src/new.ts', renamedFrom: 'src/old.ts', added: 0, removed: 0 },
+      ]),
+    ]);
+    const churn = computeChurn({ modules, history: h });
+    expect(churn['src/old.ts']?.commits).toBe(1);
+    expect(churn['src/new.ts']?.commits).toBe(1);
+  });
+
+  it('skips paths that are not in the modules set', () => {
+    const modules = [mod('src/a.ts')];
+    const h = history([
+      commit('1', 'a@x', '2026-05-01T10:00:00Z', [
+        { path: 'src/a.ts', added: 1, removed: 0 },
+        { path: 'README.md', added: 5, removed: 0 },
+      ]),
+    ]);
+    const churn = computeChurn({ modules, history: h });
+    expect(Object.keys(churn)).toEqual(['src/a.ts']);
+  });
+});

package/src/git/__tests__/computeTemporalCoupling.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { computeTemporalCoupling } from '../computeTemporalCoupling';
+import type { GitCommit, GitHistory } from '../types';
+import type { DependencyEdge, ModuleNode } from '../../analyzer/types';
+
+function mod(id: string): ModuleNode {
+  return {
+    id,
+    absPath: id,
+    kind: 'unknown',
+    language: 'ts',
+    loc: 10,
+    exports: [],
+    isInfra: false,
+  };
+}
+
+function commit(sha: string, paths: string[]): GitCommit {
+  return {
+    sha,
+    shortSha: sha.slice(0, 7),
+    author: 'a@x.com',
+    authorName: 'a',
+    authoredAt: '2026-05-01T10:00:00Z',
+    subject: sha,
+    changes: paths.map((p) => ({ path: p, added: 1, removed: 0 })),
+  };
+}
+
+function history(commits: GitCommit[]): GitHistory {
+  return { since: '90d', until: 'now', commits, includesMerges: false };
+}
+
+const NO_EDGES: DependencyEdge[] = [];
+
+describe('computeTemporalCoupling', () => {
+  it('finds tight pairs above thresholds', () => {
+    const modules = [mod('src/a.ts'), mod('src/b.ts'), mod('src/c.ts')];
+    const h = history([
+      commit('1', ['src/a.ts', 'src/b.ts']),
+      commit('2', ['src/a.ts', 'src/b.ts']),
+      commit('3', ['src/a.ts', 'src/b.ts']),
+      commit('4', ['src/a.ts']),
+      commit('5', ['src/c.ts']),
+    ]);
+    const out = computeTemporalCoupling({ modules, edges: NO_EDGES, history: h });
+    expect(out).toHaveLength(1);
+    expect(out[0]?.a).toBe('src/a.ts');
+    expect(out[0]?.b).toBe('src/b.ts');
+    expect(out[0]?.coOccurrences).toBe(3);
+    // a touched 4 times, b touched 3 times -> min(3/4, 3/3) = 0.75
+    expect(out[0]?.score).toBeCloseTo(0.75);
+    expect(out[0]?.hidden).toBe(true);
+  });
+
+  it('marks pairs with a static edge as not hidden', () => {
+    const modules = [mod('src/a.ts'), mod('src/b.ts')];
+    const edges: DependencyEdge[] = [
+      { from: 'src/a.ts', to: 'src/b.ts', kind: 'static', specifier: './b', resolved: true },
+    ];
+    const h = history([
+      commit('1', ['src/a.ts', 'src/b.ts']),
+      commit('2', ['src/a.ts', 'src/b.ts']),
+      commit('3', ['src/a.ts', 'src/b.ts']),
+    ]);
+    const out = computeTemporalCoupling({ modules, edges, history: h });
+    expect(out[0]?.hidden).toBe(false);
+  });
+
+  it('skips fan-out commits past the cap', () => {
+    const modules = Array.from({ length: 100 }, (_, i) => mod(`src/m${i}.ts`));
+    // One mass-edit commit touching all 100 modules. Without the cap, every
+    // pair would receive a co-occurrence — 4950 false positives.
+    const c = commit(
+      'mass',
+      modules.map((m) => m.id),
+    );
+    const h = history([c, c, c]);
+    const out = computeTemporalCoupling({
+      modules,
+      edges: NO_EDGES,
+      history: h,
+      thresholds: { commitFanOutCap: 50 },
+    });
+    expect(out).toHaveLength(0);
+  });
+
+  it('honours minCoOccurrences', () => {
+    const modules = [mod('src/a.ts'), mod('src/b.ts')];
+    const h = history([
+      commit('1', ['src/a.ts', 'src/b.ts']),
+      commit('2', ['src/a.ts', 'src/b.ts']),
+    ]);
+    const out = computeTemporalCoupling({
+      modules,
+      edges: NO_EDGES,
+      history: h,
+      thresholds: { minCoOccurrences: 3 },
+    });
+    expect(out).toHaveLength(0);
+  });
+
+  it('sorts hidden pairs first then by score desc', () => {
+    const modules = ['src/a.ts', 'src/b.ts', 'src/c.ts', 'src/d.ts'].map(mod);
+    // Pair (a,b): static edge, perfect score. Pair (c,d): no edge, score 0.6.
+    const edges: DependencyEdge[] = [
+      { from: 'src/a.ts', to: 'src/b.ts', kind: 'static', specifier: './b', resolved: true },
+    ];
+    const h = history([
+      commit('1', ['src/a.ts', 'src/b.ts']),
+      commit('2', ['src/a.ts', 'src/b.ts']),
+      commit('3', ['src/a.ts', 'src/b.ts']),
+      commit('4', ['src/c.ts', 'src/d.ts']),
+      commit('5', ['src/c.ts', 'src/d.ts']),
+      commit('6', ['src/c.ts', 'src/d.ts']),
+      commit('7', ['src/c.ts']),
+      commit('8', ['src/d.ts']),
+    ]);
+    const out = computeTemporalCoupling({ modules, edges, history: h });
+    expect(out).toHaveLength(2);
+    expect(out[0]?.hidden).toBe(true); // c,d shown first despite lower score
+    expect(out[0]?.a).toBe('src/c.ts');
+    expect(out[1]?.hidden).toBe(false);
+  });
+});

package/src/git/__tests__/parseGitLog.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import { expandRename, parseGitLog } from '../parseGitLog';
+
+const SOH = '\x01';
+
+function commitHeader(
+  sha: string,
+  short: string,
+  name: string,
+  email: string,
+  date: string,
+  subject: string,
+): string {
+  return `__FS_COMMIT__${SOH}${sha}${SOH}${short}${SOH}${name}${SOH}${email}${SOH}${date}${SOH}${subject}`;
+}
+
+describe('parseGitLog', () => {
+  it('parses a single commit with two file changes', () => {
+    const raw =
+      commitHeader(
+        'a'.repeat(40),
+        'aaaaaaa',
+        'Alice',
+        'alice@example.com',
+        '2026-05-01T10:00:00+03:00',
+        'feat: x',
+      ) + '\n10\t2\tsrc/a.ts\n3\t0\tsrc/b.ts';
+    const commits = parseGitLog(raw);
+    expect(commits).toHaveLength(1);
+    expect(commits[0]?.sha).toBe('a'.repeat(40));
+    expect(commits[0]?.author).toBe('alice@example.com');
+    expect(commits[0]?.subject).toBe('feat: x');
+    expect(commits[0]?.changes).toEqual([
+      { path: 'src/a.ts', added: 10, removed: 2 },
+      { path: 'src/b.ts', added: 3, removed: 0 },
+    ]);
+  });
+
+  it('lowercases author email', () => {
+    const raw =
+      commitHeader(
+        'b'.repeat(40),
+        'bbbbbbb',
+        'Bob',
+        'BOB@Example.COM',
+        '2026-05-02T10:00:00+03:00',
+        'fix',
+      ) + '\n1\t1\tsrc/x.ts';
+    expect(parseGitLog(raw)[0]?.author).toBe('bob@example.com');
+  });
+
+  it('parses two consecutive commits', () => {
+    const raw =
+      commitHeader('a'.repeat(40), 'aaaaaaa', 'A', 'a@x', '2026-05-01T10:00:00+03:00', 's1') +
+      '\n1\t0\tsrc/a.ts' +
+      commitHeader('b'.repeat(40), 'bbbbbbb', 'B', 'b@x', '2026-05-02T10:00:00+03:00', 's2') +
+      '\n2\t3\tsrc/b.ts';
+    const commits = parseGitLog(raw);
+    expect(commits).toHaveLength(2);
+    expect(commits[0]?.subject).toBe('s1');
+    expect(commits[1]?.subject).toBe('s2');
+  });
+
+  it('treats binary-file diffs (-) as null lines', () => {
+    const raw =
+      commitHeader('c'.repeat(40), 'ccccccc', 'C', 'c@x', '2026-05-03T10:00:00+03:00', 'bin') +
+      '\n-\t-\tassets/logo.png';
+    expect(parseGitLog(raw)[0]?.changes).toEqual([
+      { path: 'assets/logo.png', added: null, removed: null },
+    ]);
+  });
+
+  it('handles whole-path rename "old => new"', () => {
+    const raw =
+      commitHeader('d'.repeat(40), 'ddddddd', 'D', 'd@x', '2026-05-04T10:00:00+03:00', 'mv') +
+      '\n5\t5\tsrc/old/x.ts => src/new/x.ts';
+    const c = parseGitLog(raw)[0]?.changes[0];
+    expect(c).toEqual({
+      path: 'src/new/x.ts',
+      renamedFrom: 'src/old/x.ts',
+      added: 5,
+      removed: 5,
+    });
+  });
+
+  it('handles braced rename "src/{old => new}/x.ts"', () => {
+    const raw =
+      commitHeader('e'.repeat(40), 'eeeeeee', 'E', 'e@x', '2026-05-05T10:00:00+03:00', 'mv2') +
+      '\n0\t0\tsrc/{old => new}/x.ts';
+    expect(parseGitLog(raw)[0]?.changes[0]).toEqual({
+      path: 'src/new/x.ts',
+      renamedFrom: 'src/old/x.ts',
+      added: 0,
+      removed: 0,
+    });
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(parseGitLog('')).toEqual([]);
+  });
+
+  it('skips malformed segments without throwing', () => {
+    const raw =
+      '__FS_COMMIT__\x01garbage\nweird stuff\n' +
+      commitHeader('f'.repeat(40), 'fffffff', 'F', 'f@x', '2026-05-06T10:00:00+03:00', 'ok') +
+      '\n1\t1\tsrc/ok.ts';
+    const commits = parseGitLog(raw);
+    expect(commits).toHaveLength(1);
+    expect(commits[0]?.subject).toBe('ok');
+  });
+});
+
+describe('expandRename', () => {
+  it('handles brace expansion with empty old part', () => {
+    expect(expandRename('src/{ => new}/x.ts')).toEqual({ from: 'src/x.ts', to: 'src/new/x.ts' });
+  });
+  it('handles brace expansion with empty new part', () => {
+    expect(expandRename('src/{old => }/x.ts')).toEqual({ from: 'src/old/x.ts', to: 'src/x.ts' });
+  });
+});

package/src/git/computeChurn.ts

@@ -0,0 +1,111 @@
+// Aggregate `GitHistory` into per-module churn metrics.
+//
+// `GitHistory` knows about repo paths, not module ids. The mapping is just
+// "the path equals the moduleId" today (analyzer normalizes both to repo-
+// root-relative POSIX paths), but we keep the indirection in case we ever
+// stop using paths as ids.
+
+import type { ModuleNode } from '../analyzer/types';
+import type { ChurnAuthor, ChurnByModule, ChurnMetric, GitCommit, GitHistory } from './types';
+
+export interface ComputeChurnInput {
+  modules: ModuleNode[];
+  history: GitHistory;
+}
+
+const TOP_AUTHORS = 5;
+
+export function computeChurn(input: ComputeChurnInput): ChurnByModule {
+  const moduleIds = new Set(input.modules.map((m) => m.id));
+  // path -> aggregator. We use a map so we can also collapse renames: when
+  // a commit renames `old -> new`, both paths receive the touch (the same
+  // physical change happened on both names through history).
+  const acc = new Map<string, AccPerModule>();
+
+  for (const commit of input.history.commits) {
+    const touchedPaths = pathsTouched(commit, moduleIds);
+    for (const path of touchedPaths) {
+      let entry = acc.get(path);
+      if (!entry) {
+        entry = makeEntry(path);
+        acc.set(path, entry);
+      }
+      entry.commits += 1;
+      entry.lines += linesIn(commit, path);
+      entry.authorsByEmail.set(commit.author, (entry.authorsByEmail.get(commit.author) ?? 0) + 1);
+      if (entry.lastTouchedAt < commit.authoredAt) {
+        entry.lastTouchedAt = commit.authoredAt;
+      }
+    }
+  }
+
+  const out: ChurnByModule = {};
+  for (const [path, entry] of acc) {
+    out[path] = finalize(entry);
+  }
+  return out;
+}
+
+interface AccPerModule {
+  moduleId: string;
+  commits: number;
+  lines: number;
+  authorsByEmail: Map<string, number>;
+  lastTouchedAt: string;
+}
+
+function makeEntry(moduleId: string): AccPerModule {
+  return {
+    moduleId,
+    commits: 0,
+    lines: 0,
+    authorsByEmail: new Map(),
+    lastTouchedAt: '',
+  };
+}
+
+function pathsTouched(commit: GitCommit, validIds: Set<string>): Set<string> {
+  const out = new Set<string>();
+  for (const change of commit.changes) {
+    if (validIds.has(change.path)) out.add(change.path);
+    // Renames: charge the old name too — its history matters for churn even
+    // if the file no longer exists at HEAD.
+    if (change.renamedFrom && validIds.has(change.renamedFrom)) {
+      out.add(change.renamedFrom);
+    }
+  }
+  return out;
+}
+
+function linesIn(commit: GitCommit, path: string): number {
+  let sum = 0;
+  for (const c of commit.changes) {
+    if (c.path !== path && c.renamedFrom !== path) continue;
+    if (c.added !== null) sum += c.added;
+    if (c.removed !== null) sum += c.removed;
+  }
+  return sum;
+}
+
+function finalize(entry: AccPerModule): ChurnMetric {
+  const authorsAll: ChurnAuthor[] = [...entry.authorsByEmail.entries()]
+    .map(([author, commits]) => ({ author, commits }))
+    .sort((a, b) => b.commits - a.commits || a.author.localeCompare(b.author));
+  let authors: ChurnAuthor[];
+  if (authorsAll.length <= TOP_AUTHORS) {
+    authors = authorsAll;
+  } else {
+    const top = authorsAll.slice(0, TOP_AUTHORS);
+    const rest = authorsAll.slice(TOP_AUTHORS);
+    const otherCommits = rest.reduce((sum, a) => sum + a.commits, 0);
+    authors = [...top, { author: '__other__', commits: otherCommits }];
+  }
+  return {
+    moduleId: entry.moduleId,
+    commits: entry.commits,
+    linesChanged: entry.lines,
+    authorCount: entry.authorsByEmail.size,
+    lastTouchedAt: entry.lastTouchedAt,
+    authors,
+  };
+}