@monoes/monograph 1.1.0 → 1.2.0

package/src/analysis/changed-files.ts

@@ -0,0 +1,68 @@
+import { execSync } from 'child_process';
+import * as path from 'path';
+
+export class ChangedFilesError extends Error {
+  constructor(message: string, public readonly kind: 'invalid_ref' | 'git_failed' | 'parse_error') {
+    super(message);
+    this.name = 'ChangedFilesError';
+  }
+}
+
+const VALID_REF_RE = /^[a-zA-Z0-9\-_./@~^]+$/;
+
+export function validateGitRef(ref: string): string {
+  if (VALID_REF_RE.test(ref)) {
+    return ref;
+  }
+  throw new ChangedFilesError(
+    `Invalid git ref: "${ref}". Must match ${VALID_REF_RE.source}`,
+    'invalid_ref',
+  );
+}
+
+export async function getChangedFiles(root: string, sinceRef: string): Promise<Set<string>> {
+  validateGitRef(sinceRef);
+
+  let output: string;
+  try {
+    output = execSync(`git diff --name-only -z ${sinceRef} HEAD`, {
+      cwd: root,
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    throw new ChangedFilesError(
+      `git diff failed: ${err instanceof Error ? err.message : String(err)}`,
+      'git_failed',
+    );
+  }
+
+  try {
+    // Use NUL delimiter (-z) to handle non-ASCII filenames and paths with spaces;
+    // git's default core.quotePath=true wraps such names in quotes with octal escapes.
+    const files = output
+      .split('\0')
+      .filter((line) => line.length > 0)
+      .map((relative) => path.resolve(root, relative));
+    return new Set(files);
+  } catch (err) {
+    throw new ChangedFilesError(
+      `Failed to parse git diff output: ${err instanceof Error ? err.message : String(err)}`,
+      'parse_error',
+    );
+  }
+}
+
+export function filterResultsByChangedFiles<T extends { filePath?: string | null }>(
+  results: T[],
+  changedPaths: Set<string>,
+): T[] {
+  return results.filter((item) => item.filePath != null && changedPaths.has(item.filePath));
+}
+
+export function filterDuplicationByChangedFiles<
+  T extends { instances: Array<{ filePath: string }> },
+>(groups: T[], changedPaths: Set<string>): T[] {
+  return groups.filter((group) =>
+    group.instances.some((instance) => changedPaths.has(instance.filePath)),
+  );
+}

package/src/analysis/changed-workspaces.ts

@@ -0,0 +1,85 @@
+import { execSync } from 'child_process';
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, relative, resolve } from 'path';
+
+export interface WorkspacePackage {
+  name: string;
+  root: string;
+  hasChanges: boolean;
+}
+
+function findWorkspaceRoots(projectRoot: string): string[] {
+  // Detect pnpm/npm/yarn workspaces
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(
+      readFileSync(join(projectRoot, 'package.json'), 'utf8'),
+    );
+  } catch { return []; }
+
+  const workspaceGlobs: string[] =
+    (pkg['workspaces'] as string[] | { packages: string[] } | undefined) instanceof Array
+      ? pkg['workspaces'] as string[]
+      : (pkg['workspaces'] as { packages?: string[] } | undefined)?.packages ?? [];
+
+  if (workspaceGlobs.length === 0) return [];
+
+  const roots: string[] = [];
+  for (const glob of workspaceGlobs) {
+    // Simple glob: support "packages/*" and "apps/*"
+    if (glob.endsWith('/*')) {
+      const dir = join(projectRoot, glob.slice(0, -2));
+      try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isDirectory()) roots.push(join(dir, e.name));
+        }
+      } catch { /* ignore */ }
+    } else {
+      const absPath = join(projectRoot, glob);
+      if (existsSync(absPath)) roots.push(absPath);
+    }
+  }
+  return roots;
+}
+
+export function getChangedWorkspaces(
+  projectRoot: string,
+  sinceRef: string,
+  workspaceRoots?: string[],
+): WorkspacePackage[] {
+  // Validate git ref (same allowlist as changed-files.ts)
+  if (!/^[a-zA-Z0-9\-_./@~^]+$/.test(sinceRef)) {
+    throw new Error(`Invalid git ref: "${sinceRef}"`);
+  }
+
+  let changedFiles: Set<string>;
+  try {
+    const raw = execSync(
+      `git -C "${projectRoot}" diff --name-only "${sinceRef}"...HEAD`,
+      { encoding: 'utf8' }
+    );
+    changedFiles = new Set(raw.split('\n').map(l => l.trim()).filter(Boolean));
+  } catch {
+    changedFiles = new Set();
+  }
+
+  const roots = workspaceRoots ?? findWorkspaceRoots(projectRoot);
+
+  return roots.map(root => {
+    const relRoot = relative(projectRoot, root).replace(/\\/g, '/') + '/';
+    const hasChanges = [...changedFiles].some(f => f.startsWith(relRoot));
+    const pkgName = root.split(/[\\/]/).pop() ?? root;
+    return { name: pkgName, root: resolve(root), hasChanges };
+  });
+}
+
+export function resolveChangedWorkspaceRoots(
+  projectRoot: string,
+  sinceRef: string,
+  workspaceRoots?: string[],
+): string[] {
+  return getChangedWorkspaces(projectRoot, sinceRef, workspaceRoots)
+    .filter(w => w.hasChanges)
+    .map(w => w.root);
+}

package/src/analysis/churn-cache.ts

@@ -0,0 +1,168 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const CHURN_CACHE_VERSION = 3;
+const MAX_CHURN_CACHE_BYTES = 64 * 1024 * 1024;
+
+export interface CachedCommitEvent {
+  timestamp: number;
+  linesAdded: number;
+  linesDeleted: number;
+  authorIdx: number | null;
+}
+
+export interface CachedFileChurn {
+  path: string;
+  events: CachedCommitEvent[];
+}
+
+export interface ChurnCache {
+  version: number;
+  lastIndexedSha: string;
+  gitAfter: string;
+  files: CachedFileChurn[];
+  shallowClone: boolean;
+  authorPool: string[];
+}
+
+export interface CachedChurnResult {
+  files: Map<string, { commits: number; linesAdded: number; linesDeleted: number; weightedCommits: number }>;
+  shallowClone: boolean;
+  authorPool: string[];
+  cacheHit: boolean;
+}
+
+function loadChurnCache(cacheDir: string, gitAfter: string): ChurnCache | null {
+  const file = join(cacheDir, 'churn.json');
+  if (!existsSync(file)) return null;
+  try {
+    const raw = readFileSync(file, 'utf8');
+    if (raw.length > MAX_CHURN_CACHE_BYTES) return null;
+    const cache: ChurnCache = JSON.parse(raw);
+    if (cache.version !== CHURN_CACHE_VERSION) return null;
+    if (cache.gitAfter !== gitAfter) return null;
+    return cache;
+  } catch { return null; }
+}
+
+function saveChurnCache(cacheDir: string, sha: string, gitAfter: string, cache: ChurnCache): void {
+  mkdirSync(cacheDir, { recursive: true });
+  const tmp = join(cacheDir, 'churn.json.tmp');
+  writeFileSync(tmp, JSON.stringify({ ...cache, version: CHURN_CACHE_VERSION, lastIndexedSha: sha, gitAfter }));
+  renameSync(tmp, join(cacheDir, 'churn.json'));
+}
+
+function getHeadSha(root: string): string | null {
+  try {
+    return execSync('git rev-parse HEAD', { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  } catch { return null; }
+}
+
+function isAncestor(root: string, ancestor: string, descendant: string): boolean {
+  try {
+    execSync(`git merge-base --is-ancestor ${ancestor} ${descendant}`, { cwd: root, stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+function runGitLog(root: string, gitAfter: string, range: string | null): ChurnCache | null {
+  try {
+    const rangeArg = range ? [range] : [];
+    const stdout = execSync(
+      ['git', 'log', ...rangeArg, '--numstat', '--no-merges', '--no-renames',
+       '--use-mailmap', '--format=format:%at|%ae', `--after=${gitAfter}`].join(' '),
+      { cwd: root, maxBuffer: 256 * 1024 * 1024 }
+    ).toString();
+    return parseGitLog(stdout);
+  } catch { return null; }
+}
+
+function parseGitLog(stdout: string): ChurnCache {
+  const files: Map<string, CachedCommitEvent[]> = new Map();
+  const authorPool: string[] = [];
+  const authorIndex: Map<string, number> = new Map();
+  let currentTs = Math.floor(Date.now() / 1000);
+  let currentAuthorIdx: number | null = null;
+
+  for (const rawLine of stdout.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const headerMatch = line.match(/^(\d+)\|(.+)$/);
+    if (headerMatch) {
+      currentTs = parseInt(headerMatch[1], 10);
+      const email = headerMatch[2];
+      if (!authorIndex.has(email)) { authorIndex.set(email, authorPool.length); authorPool.push(email); }
+      currentAuthorIdx = authorIndex.get(email)!;
+      continue;
+    }
+    const parts = line.split('\t');
+    if (parts.length < 3) continue;
+    const added = parseInt(parts[0], 10);
+    const deleted = parseInt(parts[1], 10);
+    if (isNaN(added) || isNaN(deleted)) continue;
+    const path = parts[2];
+    if (!files.has(path)) files.set(path, []);
+    files.get(path)!.push({ timestamp: currentTs, linesAdded: added, linesDeleted: deleted, authorIdx: currentAuthorIdx });
+  }
+
+  return { version: CHURN_CACHE_VERSION, lastIndexedSha: '', gitAfter: '', shallowClone: false, authorPool, files: Array.from(files.entries()).map(([path, events]) => ({ path, events })) };
+}
+
+function mergeChurnCaches(base: ChurnCache, delta: ChurnCache): ChurnCache {
+  const authorMap = new Map<number, number>();
+  const baseIndex = new Map(base.authorPool.map((e, i) => [e, i]));
+  for (let i = 0; i < delta.authorPool.length; i++) {
+    const email = delta.authorPool[i];
+    if (!baseIndex.has(email)) { baseIndex.set(email, base.authorPool.length); base.authorPool.push(email); }
+    authorMap.set(i, baseIndex.get(email)!);
+  }
+  const fileMap = new Map(base.files.map(f => [f.path, f]));
+  for (const df of delta.files) {
+    const remapped = df.events.map(e => ({ ...e, authorIdx: e.authorIdx !== null ? (authorMap.get(e.authorIdx) ?? null) : null }));
+    if (fileMap.has(df.path)) fileMap.get(df.path)!.events.push(...remapped);
+    else fileMap.set(df.path, { path: df.path, events: remapped });
+  }
+  return { ...base, files: Array.from(fileMap.values()) };
+}
+
+function buildChurnResult(cache: ChurnCache): Omit<CachedChurnResult, 'cacheHit'> {
+  const HALF_LIFE_DAYS = 90;
+  const SECS_PER_DAY = 86400;
+  const now = Math.floor(Date.now() / 1000);
+  const files = new Map<string, { commits: number; linesAdded: number; linesDeleted: number; weightedCommits: number }>();
+  for (const { path, events } of cache.files) {
+    let commits = 0, linesAdded = 0, linesDeleted = 0, weightedCommits = 0;
+    for (const e of events) {
+      const ageDays = (now - e.timestamp) / SECS_PER_DAY;
+      weightedCommits += Math.pow(0.5, ageDays / HALF_LIFE_DAYS);
+      commits++; linesAdded += e.linesAdded; linesDeleted += e.linesDeleted;
+    }
+    files.set(path, { commits, linesAdded, linesDeleted, weightedCommits: Math.round(weightedCommits * 100) / 100 });
+  }
+  return { files, shallowClone: cache.shallowClone, authorPool: cache.authorPool };
+}
+
+export function analyzeChurnCached(root: string, gitAfter: string, cacheDir: string, noCache = false): CachedChurnResult | null {
+  const headSha = getHeadSha(root);
+  if (!headSha) return null;
+  if (!noCache) {
+    const cached = loadChurnCache(cacheDir, gitAfter);
+    if (cached) {
+      if (cached.lastIndexedSha === headSha) return { ...buildChurnResult(cached), cacheHit: true };
+      if (isAncestor(root, cached.lastIndexedSha, headSha)) {
+        const delta = runGitLog(root, gitAfter, `${cached.lastIndexedSha}..HEAD`);
+        if (delta) {
+          const merged = mergeChurnCaches(cached, delta);
+          saveChurnCache(cacheDir, headSha, gitAfter, merged);
+          return { ...buildChurnResult(merged), cacheHit: true };
+        }
+      }
+    }
+  }
+  const fresh = runGitLog(root, gitAfter, null);
+  if (!fresh) return null;
+  if (!noCache) saveChurnCache(cacheDir, headSha, gitAfter, fresh);
+  return { ...buildChurnResult(fresh), cacheHit: false };
+}

package/src/analysis/churn-trend.ts

@@ -0,0 +1,28 @@
+export type ChurnTrend = 'accelerating' | 'stable' | 'cooling';
+
+const ACCELERATING_RATIO = 1.5;
+const COOLING_RATIO = 0.67;
+
+export function computeChurnTrend(timestampsEpochSec: number[]): ChurnTrend {
+  if (timestampsEpochSec.length < 2) return 'stable';
+  const minTs = timestampsEpochSec.reduce((a, b) => (b < a ? b : a));
+  const maxTs = timestampsEpochSec.reduce((a, b) => (b > a ? b : a));
+  if (maxTs === minTs) return 'stable';
+  const midpoint = minTs + (maxTs - minTs) / 2;
+  const recent = timestampsEpochSec.filter(ts => ts > midpoint).length;
+  const older  = timestampsEpochSec.filter(ts => ts <= midpoint).length;
+  if (older < 1) return 'stable';
+  const ratio = recent / older;
+  if (ratio > ACCELERATING_RATIO) return 'accelerating';
+  if (ratio < COOLING_RATIO) return 'cooling';
+  return 'stable';
+}
+
+export function churnTrendLabel(trend: ChurnTrend): string {
+  return trend === 'accelerating' ? '↑ accelerating' : trend === 'cooling' ? '↓ cooling' : '→ stable';
+}
+
+export function churnTrendFromFileSeries(fileTimestamps: number[][]): ChurnTrend {
+  const all = fileTimestamps.flat();
+  return computeChurnTrend(all);
+}

package/src/analysis/churn.ts

@@ -0,0 +1,216 @@
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, relative } from 'path';
+
+export type ChurnTrend = 'accelerating' | 'stable' | 'cooling';
+
+export interface SinceDuration {
+  raw: string;
+  days: number;
+}
+
+export interface AuthorContribution {
+  authorIdx: number;
+  weightedCommits: number;
+}
+
+export interface FileChurn {
+  path: string;
+  totalCommits: number;
+  weightedCommits: number;
+  authors: AuthorContribution[];
+  trend: ChurnTrend;
+}
+
+export interface ChurnResult {
+  files: FileChurn[];
+  authorPool: string[];
+  since: SinceDuration;
+}
+
+export function parseSince(s: string): SinceDuration {
+  const dMatch = s.match(/^(\d+)d$/);
+  if (dMatch) return { raw: s, days: parseInt(dMatch[1], 10) };
+
+  const wMatch = s.match(/^(\d+)w$/);
+  if (wMatch) return { raw: s, days: parseInt(wMatch[1], 10) * 7 };
+
+  const mMatch = s.match(/^(\d+)m$/);
+  if (mMatch) return { raw: s, days: parseInt(mMatch[1], 10) * 30 };
+
+  const yMatch = s.match(/^(\d+)y$/);
+  if (yMatch) return { raw: s, days: parseInt(yMatch[1], 10) * 365 };
+
+  // ISO date string
+  const parsed = Date.parse(s);
+  if (!isNaN(parsed)) {
+    const days = Math.ceil((Date.now() - parsed) / 86400000);
+    return { raw: s, days };
+  }
+
+  // Fallback: try to parse as plain number of days
+  const num = parseInt(s, 10);
+  if (!isNaN(num)) return { raw: s, days: num };
+
+  return { raw: s, days: 30 };
+}
+
+export function computeRecencyWeight(ageDays: number): number {
+  return Math.exp(-Math.LN2 * ageDays / 90);
+}
+
+export function classifyChurnTrend(recentWeighted: number, olderWeighted: number): ChurnTrend {
+  if (olderWeighted === 0) {
+    return recentWeighted > 0 ? 'accelerating' : 'stable';
+  }
+  const ratio = recentWeighted / olderWeighted;
+  if (ratio > 1.5) return 'accelerating';
+  if (ratio < 0.67) return 'cooling';
+  return 'stable';
+}
+
+export async function analyzeChurn(
+  root: string,
+  since: SinceDuration | string,
+): Promise<ChurnResult> {
+  const sinceDuration: SinceDuration =
+    typeof since === 'string' ? parseSince(since) : since;
+
+  // Cache lookup
+  const cacheDir = join(root, '.monograph', 'cache');
+  let treeHash = '';
+  try {
+    treeHash = execSync('git rev-parse HEAD', { cwd: root }).toString().trim();
+    const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}.json`);
+    if (existsSync(cacheFile)) {
+      try {
+        const cached = JSON.parse(readFileSync(cacheFile, 'utf8'));
+        return cached as ChurnResult;
+      } catch {
+        // cache corrupt, recompute
+      }
+    }
+  } catch {
+    // git not available or no commits
+  }
+
+  // Build since date string for git log
+  const sinceDate = new Date(Date.now() - sinceDuration.days * 86400000);
+  const sinceDateStr = sinceDate.toISOString().slice(0, 10);
+
+  // Get all commits with file paths
+  let logOutput = '';
+  try {
+    logOutput = execSync(
+      `git log --after="${sinceDateStr}" --name-only --format="%ae|%ai"`,
+      { cwd: root, maxBuffer: 50 * 1024 * 1024 },
+    ).toString();
+  } catch {
+    return { files: [], authorPool: [], since: sinceDuration };
+  }
+
+  const now = Date.now();
+
+  // Parse log output into per-file commit lists: { email, dateStr }[]
+  const fileCommits = new Map<string, Array<{ email: string; dateStr: string }>>();
+  const authorIndexMap = new Map<string, number>();
+  const authorPool: string[] = [];
+
+  const lines = logOutput.split('\n');
+  let currentEmail = '';
+  let currentDateStr = '';
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.includes('|')) {
+      // Header line: email|date
+      const pipeIdx = trimmed.indexOf('|');
+      currentEmail = trimmed.slice(0, pipeIdx).trim();
+      currentDateStr = trimmed.slice(pipeIdx + 1).trim();
+    } else {
+      // File path line
+      const filePath = trimmed;
+      if (!fileCommits.has(filePath)) {
+        fileCommits.set(filePath, []);
+      }
+      fileCommits.get(filePath)!.push({ email: currentEmail, dateStr: currentDateStr });
+    }
+  }
+
+  // Build FileChurn entries
+  const files: FileChurn[] = [];
+
+  for (const [path, commits] of fileCommits) {
+    if (commits.length === 0) continue;
+
+    // Sort commits by date descending (newest first)
+    const sortedCommits = commits.slice().sort((a, b) => {
+      return Date.parse(b.dateStr) - Date.parse(a.dateStr);
+    });
+
+    // Compute weighted commits per author and trend
+    const authorWeights = new Map<number, number>();
+    let totalWeighted = 0;
+
+    // Split into two halves for trend analysis
+    const midpoint = Math.floor(sortedCommits.length / 2);
+    let recentWeighted = 0;
+    let olderWeighted = 0;
+
+    for (let i = 0; i < sortedCommits.length; i++) {
+      const commit = sortedCommits[i];
+      const commitDate = Date.parse(commit.dateStr);
+      const ageDays = (now - commitDate) / 86400000;
+      const weight = computeRecencyWeight(ageDays);
+
+      // Author index
+      if (!authorIndexMap.has(commit.email)) {
+        authorIndexMap.set(commit.email, authorPool.length);
+        authorPool.push(commit.email);
+      }
+      const authorIdx = authorIndexMap.get(commit.email)!;
+
+      const existing = authorWeights.get(authorIdx) ?? 0;
+      authorWeights.set(authorIdx, existing + weight);
+      totalWeighted += weight;
+
+      // recent = first half (newest), older = second half
+      if (i < midpoint) {
+        recentWeighted += weight;
+      } else {
+        olderWeighted += weight;
+      }
+    }
+
+    const trend = classifyChurnTrend(recentWeighted, olderWeighted);
+
+    const authors: AuthorContribution[] = Array.from(authorWeights.entries()).map(
+      ([authorIdx, weightedCommits]) => ({ authorIdx, weightedCommits }),
+    );
+
+    files.push({
+      path,
+      totalCommits: commits.length,
+      weightedCommits: totalWeighted,
+      authors,
+      trend,
+    });
+  }
+
+  const result: ChurnResult = { files, authorPool, since: sinceDuration };
+
+  // Write cache
+  if (treeHash) {
+    try {
+      mkdirSync(cacheDir, { recursive: true });
+      const cacheFile = join(cacheDir, `churn-${treeHash}-${sinceDuration.days}.json`);
+      writeFileSync(cacheFile, JSON.stringify(result), 'utf8');
+    } catch {
+      // cache write failure is non-fatal
+    }
+  }
+
+  return result;
+}

package/src/analysis/cluster-quality.ts

@@ -0,0 +1,134 @@
+/**
+ * Cluster quality metrics: silhouette score and modularity score.
+ *
+ * References:
+ *  - Silhouette: Rousseeuw (1987) — (b-a)/max(a,b) averaged over all nodes
+ *  - Modularity: Newman & Girvan (2004) — Q = Σ[e_ii - a_i²]
+ */
+
+export type Edge = { sourceId: string; targetId: string };
+
+/**
+ * Build an adjacency map from an edge list (undirected).
+ */
+function buildAdjacency(edges: Edge[]): Map<string, Set<string>> {
+  const adj = new Map<string, Set<string>>();
+  for (const { sourceId, targetId } of edges) {
+    if (!adj.has(sourceId)) adj.set(sourceId, new Set());
+    if (!adj.has(targetId)) adj.set(targetId, new Set());
+    adj.get(sourceId)!.add(targetId);
+    adj.get(targetId)!.add(sourceId);
+  }
+  return adj;
+}
+
+/**
+ * Average hop-distance proxy: fraction of community members NOT adjacent to node.
+ * For graph-based silhouette we use the complement of the adjacency fraction
+ * as a distance (0 = neighbor, 1 = no edge).
+ *
+ * a(i) = mean distance to other nodes in same community
+ * b(i) = min mean distance to any other community
+ * silhouette(i) = (b(i) - a(i)) / max(a(i), b(i))
+ */
+function nodeSilhouette(
+  nodeId: string,
+  community: number,
+  memberships: Map<string, number>,
+  adj: Map<string, Set<string>>,
+): number {
+  const neighbors = adj.get(nodeId) ?? new Set<string>();
+
+  // Group all other nodes by community
+  const communityMembers = new Map<number, string[]>();
+  for (const [nid, cid] of memberships) {
+    if (nid === nodeId) continue;
+    if (!communityMembers.has(cid)) communityMembers.set(cid, []);
+    communityMembers.get(cid)!.push(nid);
+  }
+
+  const sameMembers = communityMembers.get(community) ?? [];
+  if (sameMembers.length === 0) return 0; // singleton community
+
+  // a(i): mean distance to same community (1 = not neighbor, 0 = neighbor)
+  const a =
+    sameMembers.reduce((sum, nid) => sum + (neighbors.has(nid) ? 0 : 1), 0) /
+    sameMembers.length;
+
+  // b(i): minimum mean distance to any other community
+  let b = Infinity;
+  for (const [cid, members] of communityMembers) {
+    if (cid === community || members.length === 0) continue;
+    const meanDist =
+      members.reduce((sum, nid) => sum + (neighbors.has(nid) ? 0 : 1), 0) /
+      members.length;
+    if (meanDist < b) b = meanDist;
+  }
+
+  if (!isFinite(b)) return 0; // only one community exists
+  const denom = Math.max(a, b);
+  if (denom === 0) return 0;
+  return (b - a) / denom;
+}
+
+/**
+ * Compute the average silhouette score for the partitioning.
+ * Returns a value in [-1, 1] where higher is better.
+ */
+export function silhouetteScore(
+  memberships: Map<string, number>,
+  edges: Edge[],
+): number {
+  if (memberships.size === 0) return 0;
+  const adj = buildAdjacency(edges);
+  let total = 0;
+  for (const [nodeId, community] of memberships) {
+    total += nodeSilhouette(nodeId, community, memberships, adj);
+  }
+  return total / memberships.size;
+}
+
+/**
+ * Compute Newman–Girvan modularity Q.
+ *
+ * Q = (1/2m) * Σ_{ij} [A_ij - k_i*k_j/(2m)] * δ(c_i, c_j)
+ *
+ * where m = total edge count, k_i = degree of node i, A_ij = adjacency.
+ * Returns a value in (-0.5, 1].
+ */
+export function modularityScore(
+  memberships: Map<string, number>,
+  edges: Edge[],
+): number {
+  const adj = buildAdjacency(edges);
+
+  // Degree map (undirected) — use adj to count undirected edges correctly
+  const degree = new Map<string, number>();
+  for (const [nodeId, neighbors] of adj) {
+    degree.set(nodeId, neighbors.size);
+  }
+
+  // m_undirected: each undirected edge is counted once in adj (both directions added)
+  // so sum of degrees = 2 * m_undirected
+  const totalDegree = [...degree.values()].reduce((s, d) => s + d, 0);
+  const m = totalDegree / 2;
+  if (m === 0) return 0;
+
+  const twoM = 2 * m;
+  let Q = 0;
+
+  const nodes = [...memberships.keys()];
+  for (let i = 0; i < nodes.length; i++) {
+    const u = nodes[i]!;
+    for (let j = i + 1; j < nodes.length; j++) {
+      const v = nodes[j]!;
+      if (memberships.get(u) !== memberships.get(v)) continue;
+      const aij = adj.get(u)?.has(v) ? 1 : 0;
+      const ki = degree.get(u) ?? 0;
+      const kj = degree.get(v) ?? 0;
+      Q += aij - (ki * kj) / twoM;
+    }
+  }
+
+  return Q / m; // normalise by m (equivalent to 1/(2m) summed both directions)
+}