@monoes/monograph 1.1.0 → 1.2.0

package/src/regression/baseline-deltas.ts

@@ -0,0 +1,215 @@
+import type {
+  FallowAnalysisResults,
+  FallowUnusedFile,
+  FallowUnusedExport,
+  FallowUnusedDependency,
+  FallowUnusedMember,
+  FallowUnresolvedImport,
+} from '../results/fallow-results.js';
+import { makeEmptyFallowResults, totalFallowIssues } from '../results/fallow-results.js';
+
+export interface CategoryDelta {
+  category: string;
+  before: number;
+  after: number;
+  added: number;
+  resolved: number;
+}
+
+export interface BaselineDeltas {
+  unusedFiles: CategoryDelta;
+  unusedExports: CategoryDelta;
+  unusedDeps: CategoryDelta;
+  unusedMembers: CategoryDelta;
+  unresolvedImports: CategoryDelta;
+  cloneGroups: CategoryDelta;
+  overall: CategoryDelta;
+}
+
+function makeDelta(category: string, baselineItems: unknown[], currentItems: unknown[], added: number, resolved: number): CategoryDelta {
+  return {
+    category,
+    before: baselineItems.length,
+    after: currentItems.length,
+    added,
+    resolved,
+  };
+}
+
+function setOf<T>(items: T[], key: (item: T) => string): Set<string> {
+  return new Set(items.map(key));
+}
+
+function unusedFileKey(f: FallowUnusedFile): string {
+  return f.filePath;
+}
+
+function unusedExportKey(e: FallowUnusedExport): string {
+  return `${e.filePath}::${e.exportName}`;
+}
+
+function unusedDepKey(d: FallowUnusedDependency): string {
+  return `${d.name}::${d.location}`;
+}
+
+function unusedMemberKey(m: FallowUnusedMember): string {
+  return `${m.filePath}::${m.parentName}::${m.memberName}`;
+}
+
+function unresolvedImportKey(i: FallowUnresolvedImport): string {
+  return `${i.filePath}::${i.specifier}`;
+}
+
+function computeDelta<T>(
+  category: string,
+  baselineItems: T[],
+  currentItems: T[],
+  key: (item: T) => string,
+): CategoryDelta {
+  const baselineKeys = setOf(baselineItems, key);
+  const currentKeys = setOf(currentItems, key);
+  const added = currentItems.filter(i => !baselineKeys.has(key(i))).length;
+  const resolved = baselineItems.filter(i => !currentKeys.has(key(i))).length;
+  return makeDelta(category, baselineItems, currentItems, added, resolved);
+}
+
+export function computeBaselineDeltas(
+  baseline: FallowAnalysisResults,
+  current: FallowAnalysisResults,
+): BaselineDeltas {
+  const baselineExports = [...baseline.unusedExports, ...baseline.unusedTypes];
+  const currentExports = [...current.unusedExports, ...current.unusedTypes];
+
+  const baselineDeps = [...baseline.unusedDependencies, ...baseline.unusedDevDependencies];
+  const currentDeps = [...current.unusedDependencies, ...current.unusedDevDependencies];
+
+  const baselineMembers = [...baseline.unusedEnumMembers, ...baseline.unusedClassMembers];
+  const currentMembers = [...current.unusedEnumMembers, ...current.unusedClassMembers];
+
+  const unusedFiles = computeDelta('Unused files', baseline.unusedFiles, current.unusedFiles, unusedFileKey);
+  const unusedExports = computeDelta('Unused exports', baselineExports, currentExports, unusedExportKey);
+  const unusedDeps = computeDelta('Unused deps', baselineDeps, currentDeps, unusedDepKey);
+  const unusedMembers = computeDelta('Unused members', baselineMembers, currentMembers, unusedMemberKey);
+  const unresolvedImports = computeDelta('Unresolved imports', baseline.unresolvedImports, current.unresolvedImports, unresolvedImportKey);
+
+  const baselineCloneCount = baseline.duplicateExports.length;
+  const currentCloneCount = current.duplicateExports.length;
+  const cloneGroups: CategoryDelta = {
+    category: 'Clone groups',
+    before: baselineCloneCount,
+    after: currentCloneCount,
+    added: Math.max(0, currentCloneCount - baselineCloneCount),
+    resolved: Math.max(0, baselineCloneCount - currentCloneCount),
+  };
+
+  const beforeTotal = totalFallowIssues(baseline);
+  const afterTotal = totalFallowIssues(current);
+  const overall: CategoryDelta = {
+    category: 'Overall',
+    before: beforeTotal,
+    after: afterTotal,
+    added: unusedFiles.added + unusedExports.added + unusedDeps.added + unusedMembers.added + unresolvedImports.added + cloneGroups.added,
+    resolved: unusedFiles.resolved + unusedExports.resolved + unusedDeps.resolved + unusedMembers.resolved + unresolvedImports.resolved + cloneGroups.resolved,
+  };
+
+  return { unusedFiles, unusedExports, unusedDeps, unusedMembers, unresolvedImports, cloneGroups, overall };
+}
+
+export function filterNewIssues(
+  baseline: FallowAnalysisResults,
+  current: FallowAnalysisResults,
+): FallowAnalysisResults {
+  const baselineFileKeys = setOf(baseline.unusedFiles, unusedFileKey);
+  const baselineExportKeys = setOf([...baseline.unusedExports, ...baseline.unusedTypes], unusedExportKey);
+  const baselineDepKeys = setOf([...baseline.unusedDependencies, ...baseline.unusedDevDependencies], unusedDepKey);
+  const baselineMemberKeys = setOf([...baseline.unusedEnumMembers, ...baseline.unusedClassMembers], unusedMemberKey);
+  const baselineImportKeys = setOf(baseline.unresolvedImports, unresolvedImportKey);
+
+  function circularKey(c: FallowAnalysisResults['circularDependencies'][number]): string {
+    return c.cycle.join('->');
+  }
+  const baselineCircularKeys = setOf(baseline.circularDependencies, circularKey);
+
+  function boundaryKey(b: FallowAnalysisResults['boundaryViolations'][number]): string {
+    return `${b.fromPath}::${b.toPath}::${b.importSpecifier}`;
+  }
+  const baselineBoundaryKeys = setOf(baseline.boundaryViolations, boundaryKey);
+
+  function suppressionKey(s: FallowAnalysisResults['staleSuppressions'][number]): string {
+    return `${s.filePath}::${s.commentLine}`;
+  }
+  const baselineSuppressionKeys = setOf(baseline.staleSuppressions, suppressionKey);
+
+  function flagKey(f: FallowAnalysisResults['featureFlags'][number]): string {
+    return `${f.filePath}::${f.flagName}::${f.line}`;
+  }
+  const baselineFlagKeys = setOf(baseline.featureFlags, flagKey);
+
+  function privateLeakKey(p: FallowAnalysisResults['privateTypeLeaks'][number]): string {
+    return `${p.filePath}::${p.exportName}::${p.privateType}`;
+  }
+  const baselinePrivateLeakKeys = setOf(baseline.privateTypeLeaks, privateLeakKey);
+
+  function unlistedDepKey(u: FallowAnalysisResults['unlistedDependencies'][number]): string {
+    return u.name;
+  }
+  const baselineUnlistedKeys = setOf(baseline.unlistedDependencies, unlistedDepKey);
+
+  function duplicateExportKey(d: FallowAnalysisResults['duplicateExports'][number]): string {
+    return d.exportName;
+  }
+  const baselineDuplicateKeys = setOf(baseline.duplicateExports, duplicateExportKey);
+
+  function typeOnlyDepKey(d: FallowAnalysisResults['typeOnlyDependencies'][number]): string {
+    return `${d.name}::${d.location}`;
+  }
+  const baselineTypeOnlyKeys = setOf(baseline.typeOnlyDependencies, typeOnlyDepKey);
+
+  function testOnlyDepKey(d: FallowAnalysisResults['testOnlyDependencies'][number]): string {
+    return `${d.name}::${d.location}`;
+  }
+  const baselineTestOnlyKeys = setOf(baseline.testOnlyDependencies, testOnlyDepKey);
+
+  const result = makeEmptyFallowResults();
+
+  result.unusedFiles = current.unusedFiles.filter(i => !baselineFileKeys.has(unusedFileKey(i)));
+  result.unusedExports = current.unusedExports.filter(i => !baselineExportKeys.has(unusedExportKey(i)));
+  result.unusedTypes = current.unusedTypes.filter(i => !baselineExportKeys.has(unusedExportKey(i)));
+  result.unusedDependencies = current.unusedDependencies.filter(i => !baselineDepKeys.has(unusedDepKey(i)));
+  result.unusedDevDependencies = current.unusedDevDependencies.filter(i => !baselineDepKeys.has(unusedDepKey(i)));
+  result.unusedEnumMembers = current.unusedEnumMembers.filter(i => !baselineMemberKeys.has(unusedMemberKey(i)));
+  result.unusedClassMembers = current.unusedClassMembers.filter(i => !baselineMemberKeys.has(unusedMemberKey(i)));
+  result.unresolvedImports = current.unresolvedImports.filter(i => !baselineImportKeys.has(unresolvedImportKey(i)));
+  result.circularDependencies = current.circularDependencies.filter(i => !baselineCircularKeys.has(circularKey(i)));
+  result.boundaryViolations = current.boundaryViolations.filter(i => !baselineBoundaryKeys.has(boundaryKey(i)));
+  result.staleSuppressions = current.staleSuppressions.filter(i => !baselineSuppressionKeys.has(suppressionKey(i)));
+  result.featureFlags = current.featureFlags.filter(i => !baselineFlagKeys.has(flagKey(i)));
+  result.privateTypeLeaks = current.privateTypeLeaks.filter(i => !baselinePrivateLeakKeys.has(privateLeakKey(i)));
+  result.unlistedDependencies = current.unlistedDependencies.filter(i => !baselineUnlistedKeys.has(unlistedDepKey(i)));
+  result.duplicateExports = current.duplicateExports.filter(i => !baselineDuplicateKeys.has(duplicateExportKey(i)));
+  result.typeOnlyDependencies = current.typeOnlyDependencies.filter(i => !baselineTypeOnlyKeys.has(typeOnlyDepKey(i)));
+  result.testOnlyDependencies = current.testOnlyDependencies.filter(i => !baselineTestOnlyKeys.has(testOnlyDepKey(i)));
+
+  return result;
+}
+
+export function formatBaselineDeltas(deltas: BaselineDeltas): string[] {
+  const rows: Array<[string, CategoryDelta]> = [
+    ['Unused files', deltas.unusedFiles],
+    ['Unused exports', deltas.unusedExports],
+    ['Unused deps', deltas.unusedDeps],
+    ['Unused members', deltas.unusedMembers],
+    ['Unresolved imports', deltas.unresolvedImports],
+    ['Clone groups', deltas.cloneGroups],
+    ['Overall', deltas.overall],
+  ];
+
+  const labelWidth = Math.max(...rows.map(([label]) => label.length));
+
+  return rows.map(([label, d]) => {
+    const paddedLabel = label.padEnd(labelWidth);
+    const sign = d.after - d.before <= 0 ? '' : '+';
+    const net = d.after - d.before;
+    return `  ${paddedLabel}: ${d.before} → ${d.after} (${sign}${net}, -${d.resolved} resolved, +${d.added} new)`;
+  });
+}

package/src/regression/baseline.ts

@@ -0,0 +1,76 @@
+// File I/O operations for saving, loading, and comparing regression baselines.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export interface RegressionBaselineFile {
+  version: number;
+  createdAt: string;
+  counts: Record<string, number>;
+}
+
+export const REGRESSION_BASELINE_VERSION = 1;
+export const DEFAULT_REGRESSION_BASELINE_PATH = '.monograph/regression-baseline.json';
+
+export type SaveRegressionTarget =
+  | { kind: 'file'; path: string }
+  | { kind: 'config'; configPath: string };
+
+export interface RegressionBaselineOpts {
+  saveTarget: SaveRegressionTarget;
+  tolerance?: number;
+}
+
+export interface RegressionCompareResult {
+  passed: boolean;
+  exceeded: Array<{ metric: string; baseline: number; current: number; delta: number; tolerance: number }>;
+}
+
+export function saveRegressionBaseline(
+  counts: Record<string, number>,
+  target: SaveRegressionTarget = { kind: 'file', path: DEFAULT_REGRESSION_BASELINE_PATH },
+  root = process.cwd(),
+): void {
+  const data: RegressionBaselineFile = {
+    version: REGRESSION_BASELINE_VERSION,
+    createdAt: new Date().toISOString(),
+    counts,
+  };
+  const path = target.kind === 'file'
+    ? resolve(root, target.path)
+    : resolve(root, target.configPath.replace(/\.[^.]+$/, '-baseline.json'));
+  writeFileSync(path, JSON.stringify(data, null, 2), 'utf8');
+}
+
+export function loadRegressionBaseline(
+  path = DEFAULT_REGRESSION_BASELINE_PATH,
+  root = process.cwd(),
+): RegressionBaselineFile | null {
+  const abs = resolve(root, path);
+  if (!existsSync(abs)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(abs, 'utf8')) as unknown;
+    if (typeof raw !== 'object' || raw === null) return null;
+    const parsed = raw as Record<string, unknown>;
+    if (typeof parsed['counts'] !== 'object') return null;
+    return parsed as unknown as RegressionBaselineFile;
+  } catch {
+    return null;
+  }
+}
+
+export function compareWithRegressionBaseline(
+  baseline: RegressionBaselineFile,
+  current: Record<string, number>,
+  tolerance = 0,
+): RegressionCompareResult {
+  const exceeded: Array<{ metric: string; baseline: number; current: number; delta: number; tolerance: number }> = [];
+  for (const [metric, baseVal] of Object.entries(baseline.counts)) {
+    const curVal = current[metric] ?? 0;
+    const delta = curVal - baseVal;
+    if (delta > tolerance) {
+      exceeded.push({ metric, baseline: baseVal, current: curVal, delta, tolerance });
+    }
+  }
+  return { passed: exceeded.length === 0, exceeded };
+}

package/src/regression/counts.ts

@@ -0,0 +1,87 @@
+// Regression baseline that stores per-category issue counts rather than per-issue identity.
+
+export const REGRESSION_SCHEMA_VERSION = 1;
+
+export interface CheckCounts {
+  unusedExports: number;
+  unusedTypes: number;
+  unusedEnums: number;
+  unusedClasses: number;
+  unusedFunctions: number;
+  unusedVariables: number;
+  deadFiles: number;
+  namespaceOnlyExports: number;
+  internalExports: number;
+  duplicateExports: number;
+  reExportOnlyFiles: number;
+  missingEntryPoint: number;
+  privateLeak: number;
+  circularDeps: number;
+  boundaryViolations: number;
+}
+
+export interface DupesCounts {
+  cloneGroups: number;
+  cloneInstances: number;
+  duplicatedLines: number;
+  duplicationPct: number;
+}
+
+export interface RegressionBaseline {
+  schemaVersion: number;
+  createdAt: string;
+  gitSha?: string;
+  checks: CheckCounts;
+  dupes?: DupesCounts;
+}
+
+export const ZERO_CHECK_COUNTS: CheckCounts = {
+  unusedExports: 0, unusedTypes: 0, unusedEnums: 0, unusedClasses: 0,
+  unusedFunctions: 0, unusedVariables: 0, deadFiles: 0, namespaceOnlyExports: 0,
+  internalExports: 0, duplicateExports: 0, reExportOnlyFiles: 0,
+  missingEntryPoint: 0, privateLeak: 0, circularDeps: 0, boundaryViolations: 0,
+};
+
+export function createRegressionBaseline(
+  checks: CheckCounts,
+  gitSha?: string,
+  dupes?: DupesCounts,
+): RegressionBaseline {
+  return {
+    schemaVersion: REGRESSION_SCHEMA_VERSION,
+    createdAt: new Date().toISOString(),
+    gitSha,
+    checks,
+    dupes,
+  };
+}
+
+export type CheckCountsKey = keyof CheckCounts;
+
+export interface CountDelta {
+  key: CheckCountsKey;
+  baseline: number;
+  current: number;
+  delta: number;
+}
+
+/** Compute deltas between two CheckCounts. Returns only changed categories. */
+export function checkCountsDeltas(
+  baseline: CheckCounts,
+  current: CheckCounts,
+): CountDelta[] {
+  const keys = Object.keys(baseline) as CheckCountsKey[];
+  return keys
+    .map(key => ({
+      key,
+      baseline: baseline[key],
+      current: current[key],
+      delta: current[key] - baseline[key],
+    }))
+    .filter(d => d.delta !== 0);
+}
+
+/** Sum all count fields into a single total. */
+export function totalCheckCounts(counts: CheckCounts): number {
+  return Object.values(counts).reduce((s, v) => s + v, 0);
+}

package/src/regression/outcome.ts

@@ -0,0 +1,78 @@
+// Three-variant regression outcome model: Pass, Exceeded, Skipped.
+
+import type { CountDelta } from './counts.js';
+
+export type RegressionOutcomeKind = 'pass' | 'exceeded' | 'skipped';
+
+export interface RegressionOutcomePass {
+  kind: 'pass';
+  delta: number;
+  tolerance: number;
+  toleranceKind: 'absolute' | 'percent';
+}
+
+export interface RegressionOutcomeExceeded {
+  kind: 'exceeded';
+  delta: number;
+  tolerance: number;
+  toleranceKind: 'absolute' | 'percent';
+  exceeded: CountDelta[];
+}
+
+export interface RegressionOutcomeSkipped {
+  kind: 'skipped';
+  reason: string;
+}
+
+export type RegressionOutcome =
+  | RegressionOutcomePass
+  | RegressionOutcomeExceeded
+  | RegressionOutcomeSkipped;
+
+export function regressionOutcomeToJson(outcome: RegressionOutcome): string {
+  if (outcome.kind === 'skipped') {
+    return JSON.stringify({ status: 'skipped', reason: outcome.reason });
+  }
+  return JSON.stringify({
+    status: outcome.kind,
+    delta: outcome.delta,
+    tolerance: outcome.tolerance,
+    tolerance_kind: outcome.toleranceKind,
+    exceeded: outcome.kind === 'exceeded' ? outcome.exceeded : undefined,
+  });
+}
+
+export function printRegressionOutcome(outcome: RegressionOutcome): string {
+  switch (outcome.kind) {
+    case 'pass':
+      return `✓ Regression check passed (delta=${outcome.delta}, tolerance=${outcome.tolerance})`;
+    case 'exceeded':
+      return [
+        `✗ Regression check EXCEEDED (delta=${outcome.delta}, tolerance=${outcome.tolerance})`,
+        ...outcome.exceeded.map(d => `  ${d.key}: ${d.baseline} → ${d.current} (+${d.delta})`),
+      ].join('\n');
+    case 'skipped':
+      return `⚠ Regression check skipped: ${outcome.reason}`;
+  }
+}
+
+export function makePassOutcome(
+  delta: number,
+  tolerance: number,
+  toleranceKind: 'absolute' | 'percent' = 'absolute',
+): RegressionOutcomePass {
+  return { kind: 'pass', delta, tolerance, toleranceKind };
+}
+
+export function makeExceededOutcome(
+  delta: number,
+  tolerance: number,
+  exceeded: CountDelta[],
+  toleranceKind: 'absolute' | 'percent' = 'absolute',
+): RegressionOutcomeExceeded {
+  return { kind: 'exceeded', delta, tolerance, toleranceKind, exceeded };
+}
+
+export function makeSkippedOutcome(reason: string): RegressionOutcomeSkipped {
+  return { kind: 'skipped', reason };
+}

package/src/regression/tolerance.ts

@@ -0,0 +1,35 @@
+export type ToleranceKind = 'percentage' | 'absolute';
+
+export interface Tolerance {
+  kind: ToleranceKind;
+  value: number;
+}
+
+export function parseTolerance(s: string): Tolerance {
+  const t = s.trim();
+  if (!t) return { kind: 'absolute', value: 0 };
+  if (t.endsWith('%')) {
+    const pct = parseFloat(t.slice(0, -1).trim());
+    if (isNaN(pct)) throw new Error(`invalid tolerance percentage: ${s}`);
+    if (pct < 0) throw new Error(`tolerance percentage must be non-negative: ${s}`);
+    return { kind: 'percentage', value: pct };
+  }
+  const abs = parseInt(t, 10);
+  if (isNaN(abs) || abs < 0) throw new Error(`invalid tolerance value: ${s} (use a number or N%)`);
+  return { kind: 'absolute', value: abs };
+}
+
+export function toleranceExceeded(tol: Tolerance, baselineTotal: number, currentTotal: number): boolean {
+  if (currentTotal <= baselineTotal) return false;
+  const delta = currentTotal - baselineTotal;
+  if (tol.kind === 'absolute') return delta > tol.value;
+  if (baselineTotal === 0) return delta > 0;
+  const allowed = Math.floor(baselineTotal * tol.value / 100);
+  return delta > allowed;
+}
+
+export function formatTolerance(tol: Tolerance): string {
+  return tol.kind === 'percentage' ? `${tol.value}%` : `${tol.value}`;
+}
+
+export const ZERO_TOLERANCE: Tolerance = { kind: 'absolute', value: 0 };

package/src/report/attributed-duplication.ts

@@ -0,0 +1,112 @@
+import * as path from 'node:path';
+import type { CloneGroup } from '../graph/clone-families.js';
+
+export interface AttributedInstance {
+  filePath: string;
+  startLine: number;
+  endLine: number;
+  tokenCount?: number;
+  owner: string;
+}
+
+export interface AttributedCloneGroup {
+  primaryOwner: string;
+  tokenCount: number;
+  lineCount: number;
+  instances: AttributedInstance[];
+}
+
+export interface DuplicationGroup {
+  key: string;
+  owner?: string;
+  totalDuplicatedLines: number;
+  totalDuplicatedTokens: number;
+  cloneGroups: AttributedCloneGroup[];
+}
+
+export interface DuplicationGrouping {
+  modeLabel: string;
+  groups: DuplicationGroup[];
+}
+
+export type OwnerResolver = (filePath: string) => string;
+
+export function resolveOwnerFromDirectory(filePath: string, root: string): string {
+  const rel = path.relative(root, filePath).replace(/\\/g, '/');
+  const parts = rel.split('/');
+  return parts.length > 1 ? parts[0] : '(root)';
+}
+
+export function largestOwner(
+  instances: AttributedInstance[],
+  fallback: string,
+): string {
+  const counts = new Map<string, number>();
+  for (const inst of instances) {
+    counts.set(inst.owner, (counts.get(inst.owner) ?? 0) + 1);
+  }
+  let best = fallback;
+  let bestCount = 0;
+  for (const [owner, count] of counts) {
+    if (count > bestCount || (count === bestCount && owner < best)) {
+      best = owner;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+
+export function attributeCloneGroup(
+  group: CloneGroup,
+  resolveOwner: OwnerResolver,
+): AttributedCloneGroup {
+  const instances: AttributedInstance[] = group.instances.map(inst => ({
+    ...inst,
+    owner: resolveOwner(inst.filePath),
+  }));
+  const primaryOwner = largestOwner(instances, instances[0]?.owner ?? '(unknown)');
+  const lineCount = group.instances.reduce((s, i) => s + (i.endLine - i.startLine + 1), 0);
+  const tokenCount = group.instances.reduce((s, i) => s + (i.tokenCount ?? 0), 0);
+  return { primaryOwner, tokenCount, lineCount, instances };
+}
+
+export function buildDuplicationGrouping(
+  groups: CloneGroup[],
+  resolveOwner: OwnerResolver,
+  modeLabel: string,
+): DuplicationGrouping {
+  const attributed = groups.map(g => attributeCloneGroup(g, resolveOwner));
+
+  const byOwner = new Map<string, AttributedCloneGroup[]>();
+  for (const g of attributed) {
+    const existing = byOwner.get(g.primaryOwner);
+    if (existing) existing.push(g);
+    else byOwner.set(g.primaryOwner, [g]);
+  }
+
+  const duplicationGroups: DuplicationGroup[] = [...byOwner.entries()]
+    .map(([owner, cloneGroups]) => ({
+      key: owner,
+      owner,
+      totalDuplicatedLines: cloneGroups.reduce((s, g) => s + g.lineCount, 0),
+      totalDuplicatedTokens: cloneGroups.reduce((s, g) => s + g.tokenCount, 0),
+      cloneGroups,
+    }))
+    .sort((a, b) => b.totalDuplicatedLines - a.totalDuplicatedLines);
+
+  return { modeLabel, groups: duplicationGroups };
+}
+
+export function formatDuplicationGroup(group: DuplicationGroup, root: string): string[] {
+  const lines: string[] = [
+    `${group.owner ?? group.key} — ${group.cloneGroups.length} clone groups, ${group.totalDuplicatedLines} duplicated lines`,
+  ];
+  for (const cg of group.cloneGroups) {
+    lines.push(`  [${cg.primaryOwner}] ${cg.lineCount} lines, ${cg.instances.length} instances`);
+    for (const inst of cg.instances) {
+      const rel = path.relative(root, inst.filePath).replace(/\\/g, '/');
+      lines.push(`    ${rel}:${inst.startLine}-${inst.endLine}`);
+    }
+  }
+  return lines;
+}