@monoes/monograph 1.1.0 → 1.2.0

package/src/report/human-dupes.ts

@@ -0,0 +1,142 @@
+import type { PipelineDuplicationStats } from '../duplicates/detect/statistics.js';
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+
+function col(c: string, t: string): string { return `${c}${t}${RESET}`; }
+function dim(t: string): string { return col(DIM, t); }
+function bold(t: string): string { return col(BOLD, t); }
+
+const DOCS_DUPLICATION = 'https://docs.fallow.tools/explanations/duplication';
+const MAX_CLONE_GROUPS = 10;
+const MAX_FLAT = 10;
+
+export interface HumanDupesOptions {
+  maxGroups?: number;
+  showSnippets?: boolean;
+}
+
+export interface CloneInstance {
+  filePath: string;
+  startLine: number;
+  endLine: number;
+}
+
+export interface CloneGroup {
+  id: number;
+  instances: CloneInstance[];
+  duplicatedLines: number;
+}
+
+export interface CloneFamily {
+  files: string[];
+  groups: CloneGroup[];
+  totalDuplicatedLines: number;
+  suggestions: Array<{ description: string }>;
+}
+
+function thousands(n: number): string {
+  return n.toLocaleString('en-US');
+}
+
+function splitDirFilename(path: string): [string, string] {
+  const idx = path.lastIndexOf('/');
+  if (idx < 0) return ['', path];
+  return [path.slice(0, idx + 1), path.slice(idx + 1)];
+}
+
+export function formatCloneGroup(group: CloneGroup, idx: number): string[] {
+  const lines: string[] = [];
+  const lc = group.duplicatedLines;
+  const lcStr = thousands(lc).padStart(5);
+  const lcColored = lc > 1000
+    ? col(RED, col(BOLD, lcStr))
+    : lc > 100
+      ? col(YELLOW, lcStr)
+      : dim(lcStr);
+
+  const plural = group.instances.length === 1 ? 'instance' : 'instances';
+  lines.push(`  ${lcColored} lines  ${group.instances.length} ${plural}`);
+
+  for (const inst of group.instances) {
+    const [dir, filename] = splitDirFilename(inst.filePath);
+    lines.push(`    ${dim(dir)}${filename}:${inst.startLine}-${inst.endLine}`);
+  }
+  lines.push('');
+  return lines;
+}
+
+export function buildDuplicationHumanLines(
+  stats: PipelineDuplicationStats,
+  groups: CloneGroup[],
+  opts: HumanDupesOptions = {},
+): string[] {
+  if (groups.length === 0) return [];
+  const lines: string[] = [];
+  const maxGroups = opts.maxGroups ?? MAX_CLONE_GROUPS;
+
+  const sorted = [...groups].sort((a, b) => b.duplicatedLines - a.duplicatedLines);
+  const totalGroups = sorted.length;
+  const shown = sorted.slice(0, maxGroups);
+
+  lines.push(`${col(CYAN, '●')} ${col(CYAN, col(BOLD, `Duplicates (${totalGroups} clone group${totalGroups === 1 ? '' : 's'})`))}`);
+  lines.push('');
+
+  for (let i = 0; i < shown.length; i++) {
+    lines.push(...formatCloneGroup(shown[i]!, i));
+  }
+
+  if (totalGroups > maxGroups) {
+    lines.push(`  ${dim(`... and ${totalGroups - maxGroups} more clone groups`)}`);
+  }
+
+  lines.push(`  ${dim(`Identical code blocks detected via suffix-array analysis — ${DOCS_DUPLICATION}#clone-groups`)}`);
+  lines.push('');
+
+  if (stats.duplicatedLines > 0) {
+    const pct = stats.duplicationPct.toFixed(1);
+    lines.push(`  ${dim(`Duplicated: ${thousands(stats.duplicatedLines)} lines (${pct}%), ${stats.cloneGroups} clone group${stats.cloneGroups === 1 ? '' : 's'}`)}`);
+    lines.push('');
+  }
+
+  if (groups.length > 0) {
+    lines.push(`  ${dim('Run with --output json for machine-readable output')}`);
+  }
+
+  return lines;
+}
+
+export function buildDuplicationFamilyLines(
+  families: CloneFamily[],
+  opts: HumanDupesOptions = {},
+): string[] {
+  const multi = families.filter(f => f.groups.length > 1);
+  if (multi.length === 0) return [];
+  const lines: string[] = [];
+
+  lines.push(`${col(YELLOW, '●')} ${col(YELLOW, col(BOLD, `Clone families (${multi.length} with multiple groups)`))}`);
+  lines.push('');
+
+  const shown = multi.slice(0, MAX_FLAT);
+  for (const family of shown) {
+    const fileList = family.files.join(', ');
+    lines.push(`  ${bold(String(family.groups.length))} groups, ${bold(thousands(family.totalDuplicatedLines))} lines across ${fileList}`);
+    for (const s of family.suggestions) {
+      lines.push(`    ${col(YELLOW, '→')} ${dim(s.description)}`);
+    }
+    lines.push('');
+  }
+
+  if (multi.length > MAX_FLAT) {
+    lines.push(`  ${dim(`... and ${multi.length - MAX_FLAT} more families`)}`);
+    lines.push('');
+  }
+
+  lines.push(`  ${dim(`Groups of related clones across the same files — ${DOCS_DUPLICATION}#clone-families`)}`);
+  lines.push('');
+  return lines;
+}

package/src/report/human-health.ts

@@ -0,0 +1,195 @@
+import type { CoverageGapData } from '../health/scoring-types.js';
+import type { FileScore, VitalSigns } from '../health/health-report-types.js';
+
+export interface HumanHealthOptions {
+  hotspotLimit?: number;
+  coverageGapLimit?: number;
+  noColor?: boolean;
+}
+
+const DEFAULT_HOTSPOT_LIMIT = 20;
+const DEFAULT_COVERAGE_GAP_LIMIT = 20;
+
+type VitalStatus = 'OK' | 'WARNING' | 'CRITICAL';
+
+function vitalStatus(value: number, warnThreshold: number, critThreshold: number, higherIsBetter = false): VitalStatus {
+  if (higherIsBetter) {
+    if (value >= warnThreshold) return 'OK';
+    if (value >= critThreshold) return 'WARNING';
+    return 'CRITICAL';
+  }
+  if (value <= warnThreshold) return 'OK';
+  if (value <= critThreshold) return 'WARNING';
+  return 'CRITICAL';
+}
+
+function statusIcon(status: VitalStatus): string {
+  if (status === 'OK') return '✓';
+  if (status === 'WARNING') return '⚠';
+  return '✗';
+}
+
+function formatVitalLine(label: string, status: VitalStatus, detail?: string): string {
+  const icon = statusIcon(status);
+  const suffix = detail ? ` (${detail})` : '';
+  return `  ${icon} ${label}: ${status}${suffix}`;
+}
+
+export function formatVitalSignsSection(vitals: VitalSigns): string[] {
+  const lines: string[] = [];
+  lines.push('\n── Vital Signs ──');
+
+  const complexityStatus = vitalStatus(vitals.avgCyclomatic, 1.5, 5.5);
+  lines.push(formatVitalLine(
+    'Avg Complexity',
+    complexityStatus,
+    complexityStatus !== 'OK' ? `avg ${vitals.avgCyclomatic.toFixed(1)}, threshold 1.5` : undefined,
+  ));
+
+  const p90Status = vitalStatus(vitals.p90Cyclomatic, 10, 20);
+  lines.push(formatVitalLine(
+    'P90 Complexity',
+    p90Status,
+    p90Status !== 'OK' ? `p90 ${vitals.p90Cyclomatic}, threshold 10` : undefined,
+  ));
+
+  const maintStatus = vitalStatus(vitals.maintainabilityAvg, 70, 40, true);
+  lines.push(formatVitalLine(
+    'Maintainability',
+    maintStatus,
+    maintStatus !== 'OK' ? `avg ${vitals.maintainabilityAvg.toFixed(1)}, threshold 70` : undefined,
+  ));
+
+  const dupStatus = vitalStatus(vitals.duplicationPct, 5, 15);
+  lines.push(formatVitalLine(
+    'Duplication',
+    dupStatus,
+    `${vitals.duplicationPct.toFixed(1)}%`,
+  ));
+
+  const deadFileStatus = vitalStatus(vitals.deadFilePct, 5, 25);
+  lines.push(formatVitalLine(
+    'Dead Files',
+    deadFileStatus,
+    `${vitals.deadFilePct.toFixed(1)}%`,
+  ));
+
+  const deadExportStatus = vitalStatus(vitals.deadExportPct, 5, 25);
+  lines.push(formatVitalLine(
+    'Dead Exports',
+    deadExportStatus,
+    `${vitals.deadExportPct.toFixed(1)}%`,
+  ));
+
+  const hotspotStatus = vitals.hotspotCount > 10 ? 'CRITICAL' : vitals.hotspotCount > 3 ? 'WARNING' : 'OK';
+  lines.push(formatVitalLine(
+    'Hotspots',
+    hotspotStatus,
+    `${vitals.hotspotCount} hotspot${vitals.hotspotCount !== 1 ? 's' : ''}`,
+  ));
+
+  if (vitals.unusedDepCount > 0) {
+    const udStatus = vitalStatus(vitals.unusedDepCount, 0, 5);
+    lines.push(formatVitalLine(
+      'Unused Deps',
+      udStatus,
+      `${vitals.unusedDepCount}`,
+    ));
+  }
+
+  if (vitals.circularDepCount > 0) {
+    const cdStatus = vitalStatus(vitals.circularDepCount, 0, 3);
+    lines.push(formatVitalLine(
+      'Circular Deps',
+      cdStatus,
+      `${vitals.circularDepCount}`,
+    ));
+  }
+
+  const couplingStatus = vitalStatus(vitals.couplingHighPct, 5, 15);
+  lines.push(formatVitalLine(
+    'High Coupling',
+    couplingStatus,
+    `${vitals.couplingHighPct.toFixed(1)}%`,
+  ));
+
+  return lines;
+}
+
+function computeHotspotScore(score: FileScore): number {
+  let s = 0;
+  if (score.complexityDensity !== undefined) s += score.complexityDensity * 30;
+  if (score.crapMax !== undefined) s += Math.min(score.crapMax / 100, 1) * 25;
+  if (score.deadCodeRatio !== undefined) s += score.deadCodeRatio * 20;
+  if (score.fanIn !== undefined) s += Math.min(score.fanIn / 50, 1) * 15;
+  if (score.maintainabilityIndex !== undefined) s += Math.max(0, (100 - score.maintainabilityIndex) / 100) * 10;
+  return Math.min(s, 100);
+}
+
+export function formatHotspotSection(scores: FileScore[], limit = DEFAULT_HOTSPOT_LIMIT): string[] {
+  if (scores.length === 0) return [];
+
+  const sorted = [...scores]
+    .map((s) => ({ score: s, value: computeHotspotScore(s) }))
+    .sort((a, b) => b.value - a.value)
+    .slice(0, limit);
+
+  const lines: string[] = [];
+  lines.push('\n── Hotspots ──');
+
+  for (const { score, value } of sorted) {
+    const scoreStr = value.toFixed(1).padStart(5);
+    lines.push(`  ${scoreStr}  ${score.path}`);
+  }
+
+  if (scores.length > limit) {
+    lines.push(`  ... and ${scores.length - limit} more (use --format json for full list)`);
+  }
+
+  return lines;
+}
+
+export function formatCoverageGapSection(gaps: CoverageGapData[], limit = DEFAULT_COVERAGE_GAP_LIMIT): string[] {
+  if (gaps.length === 0) return [];
+
+  const sorted = [...gaps].sort((a, b) => a.coveragePct - b.coveragePct).slice(0, limit);
+
+  const lines: string[] = [];
+  lines.push('\n── Coverage Gaps ──');
+
+  for (const gap of sorted) {
+    const pctStr = `${gap.coveragePct.toFixed(1)}%`.padStart(6);
+    lines.push(`  ${pctStr}  ${gap.filePath}`);
+    if (gap.uncoveredFunctions.length > 0) {
+      const shown = gap.uncoveredFunctions.slice(0, 3);
+      const extra = gap.uncoveredFunctions.length - shown.length;
+      const fnList = shown.join(', ') + (extra > 0 ? `, +${extra} more` : '');
+      lines.push(`         uncovered: ${fnList}`);
+    }
+  }
+
+  if (gaps.length > limit) {
+    lines.push(`  ... and ${gaps.length - limit} more`);
+  }
+
+  return lines;
+}
+
+export function buildHealthHumanLines(
+  scores: FileScore[],
+  vitals: VitalSigns,
+  opts: HumanHealthOptions = {},
+): string[] {
+  const lines: string[] = [];
+
+  lines.push('\n── Health Report ──');
+
+  const vitalLines = formatVitalSignsSection(vitals);
+  lines.push(...vitalLines);
+
+  const hotspotLimit = opts.hotspotLimit ?? DEFAULT_HOTSPOT_LIMIT;
+  const hotspotLines = formatHotspotSection(scores, hotspotLimit);
+  lines.push(...hotspotLines);
+
+  return lines;
+}

package/src/report/human.ts

@@ -0,0 +1,120 @@
+// ANSI-colored terminal reporters for dead-code, health, and duplication results.
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const MAGENTA = '\x1b[35m';
+
+function col(color: string, text: string): string {
+  return `${color}${text}${RESET}`;
+}
+
+export interface HumanDeadCodeFinding {
+  filePath: string;
+  symbol?: string;
+  kind: string;
+  line?: number;
+}
+
+export interface HumanHealthFinding {
+  filePath: string;
+  functionName: string;
+  startLine: number;
+  cyclomatic: number;
+  cognitive: number;
+  crapScore: number;
+  severity: string;
+}
+
+export interface HumanDuplicationGroup {
+  groupId: number;
+  instances: Array<{ filePath: string; startLine: number; endLine: number }>;
+  duplicatedLines: number;
+}
+
+export interface HumanTraceEntry {
+  from: string;
+  to: string;
+  reason: string;
+}
+
+export function buildDeadCodeHumanLines(findings: HumanDeadCodeFinding[], root = ''): string[] {
+  if (findings.length === 0) return [col(GREEN, '✓ No dead code found.')];
+  const lines: string[] = [col(BOLD, `Found ${findings.length} dead code issue(s):`)];
+  const MAX = 50;
+  for (const f of findings.slice(0, MAX)) {
+    const rel = f.filePath.replace(root, '').replace(/^\//, '');
+    const loc = f.line ? `:${f.line}` : '';
+    const sym = f.symbol ? ` ${col(CYAN, f.symbol)}` : '';
+    lines.push(`  ${col(RED, '●')} ${DIM}${rel}${loc}${RESET}${sym} ${col(DIM, f.kind)}`);
+  }
+  if (findings.length > MAX) lines.push(col(DIM, `  ... and ${findings.length - MAX} more`));
+  return lines;
+}
+
+export function buildHealthHumanLines(findings: HumanHealthFinding[], root = ''): string[] {
+  if (findings.length === 0) return [col(GREEN, '✓ All functions within complexity thresholds.')];
+  const lines: string[] = [col(BOLD, `Found ${findings.length} complex function(s):`)];
+  const MAX = 30;
+  for (const f of findings.slice(0, MAX)) {
+    const rel = f.filePath.replace(root, '').replace(/^\//, '');
+    const sev = f.severity === 'critical' ? col(RED, f.severity) : f.severity === 'high' ? col(YELLOW, f.severity) : col(MAGENTA, f.severity);
+    lines.push(`  ${col(RED, '●')} ${DIM}${rel}:${f.startLine}${RESET} ${col(CYAN, f.functionName)} [cyc=${f.cyclomatic} cog=${f.cognitive} crap=${f.crapScore.toFixed(0)}] ${sev}`);
+  }
+  if (findings.length > MAX) lines.push(col(DIM, `  ... and ${findings.length - MAX} more`));
+  return lines;
+}
+
+export function buildDuplicationHumanLines(groups: HumanDuplicationGroup[], root = ''): string[] {
+  if (groups.length === 0) return [col(GREEN, '✓ No code duplication detected.')];
+  const lines: string[] = [col(BOLD, `Found ${groups.length} clone group(s):`)];
+  for (const g of groups.slice(0, 20)) {
+    lines.push(`  ${col(YELLOW, '●')} Group ${g.groupId} — ${col(BOLD, String(g.duplicatedLines))} duplicated lines`);
+    for (const inst of g.instances.slice(0, 3)) {
+      const rel = inst.filePath.replace(root, '').replace(/^\//, '');
+      lines.push(`    ${DIM}${rel}:${inst.startLine}–${inst.endLine}${RESET}`);
+    }
+    if (g.instances.length > 3) lines.push(col(DIM, `    ... and ${g.instances.length - 3} more instances`));
+  }
+  return lines;
+}
+
+export function buildExportTraceHumanLines(trace: { exportName: string; filePath: string; consumers: HumanTraceEntry[] }): string[] {
+  const lines: string[] = [col(BOLD, `Export trace: ${col(CYAN, trace.exportName)} in ${DIM}${trace.filePath}${RESET}`)];
+  if (trace.consumers.length === 0) {
+    lines.push(col(YELLOW, '  (no consumers — may be dead code)'));
+  } else {
+    for (const c of trace.consumers) {
+      lines.push(`  ${col(GREEN, '→')} ${DIM}${c.to}${RESET} ${col(DIM, c.reason)}`);
+    }
+  }
+  return lines;
+}
+
+export function buildFileTraceHumanLines(trace: { filePath: string; importedBy: HumanTraceEntry[] }): string[] {
+  const lines: string[] = [col(BOLD, `File trace: ${DIM}${trace.filePath}${RESET}`)];
+  if (trace.importedBy.length === 0) {
+    lines.push(col(YELLOW, '  (no importers — may be unused)'));
+  } else {
+    for (const c of trace.importedBy) {
+      lines.push(`  ${col(GREEN, '←')} ${DIM}${c.from}${RESET} ${col(DIM, c.reason)}`);
+    }
+  }
+  return lines;
+}
+
+export function buildDependencyTraceHumanLines(trace: { packageName: string; usedIn: HumanTraceEntry[] }): string[] {
+  const lines: string[] = [col(BOLD, `Dependency trace: ${col(CYAN, trace.packageName)}`)];
+  if (trace.usedIn.length === 0) {
+    lines.push(col(YELLOW, '  (not imported anywhere — likely unused)'));
+  } else {
+    for (const u of trace.usedIn) {
+      lines.push(`  ${col(GREEN, '→')} ${DIM}${u.from}${RESET} ${col(DIM, u.reason)}`);
+    }
+  }
+  return lines;
+}

package/src/report/json-actions.ts

@@ -0,0 +1,91 @@
+export type ActionKind =
+  | 'delete-file'
+  | 'remove-export'
+  | 'remove-export-type'
+  | 'export-type'
+  | 'remove-dependency'
+  | 'remove-dev-dependency'
+  | 'add-suppression'
+  | 'remove-class-member'
+  | 'remove-enum-member';
+
+export interface JsonAction {
+  kind: ActionKind;
+  filePath: string;
+  line?: number;
+  col?: number;
+  symbol?: string;
+  packageName?: string;
+  suppressionKind?: string;
+}
+
+export interface JsonIssueWithActions<T> {
+  issue: T;
+  actions: JsonAction[];
+  docsUrl?: string;
+}
+
+export function makeDeleteFileAction(filePath: string): JsonAction {
+  return { kind: 'delete-file', filePath };
+}
+
+export function makeRemoveExportAction(
+  filePath: string,
+  symbol: string,
+  line: number,
+  col: number,
+): JsonAction {
+  return { kind: 'remove-export', filePath, symbol, line, col };
+}
+
+export function makeExportTypeAction(
+  filePath: string,
+  symbol: string,
+  line: number,
+  col: number,
+): JsonAction {
+  return { kind: 'export-type', filePath, symbol, line, col };
+}
+
+export function makeRemoveDependencyAction(packageName: string, isDev: boolean): JsonAction {
+  return {
+    kind: isDev ? 'remove-dev-dependency' : 'remove-dependency',
+    filePath: 'package.json',
+    packageName,
+  };
+}
+
+export function makeAddSuppressionAction(
+  filePath: string,
+  line: number,
+  suppressionKind: string,
+): JsonAction {
+  return { kind: 'add-suppression', filePath, line, suppressionKind };
+}
+
+export function buildDocsUrl(issueKind: string): string {
+  const slug = issueKind.toLowerCase().replace(/[_\s]+/g, '-');
+  return `https://fallow.dev/docs/configuration#${slug}`;
+}
+
+export function buildActionsForUnusedFile(filePath: string): JsonAction[] {
+  return [makeDeleteFileAction(filePath)];
+}
+
+export function buildActionsForUnusedExport(
+  filePath: string,
+  exportName: string,
+  line: number,
+  col: number,
+  isTypeOnly: boolean,
+): JsonAction[] {
+  const removeAction = makeRemoveExportAction(filePath, exportName, line, col);
+  if (isTypeOnly) {
+    return [removeAction, makeExportTypeAction(filePath, exportName, line, col)];
+  }
+  return [removeAction];
+}
+
+export function buildActionsForUnusedDep(packageName: string, isDev: boolean): JsonAction[] {
+  return [makeRemoveDependencyAction(packageName, isDev)];
+}

package/src/report/json-builders.ts

@@ -0,0 +1,70 @@
+// Serialize grouped health/duplication results and baseline-delta summaries to JSON.
+
+export interface HealthActionOptions {
+  includeRecommendedActions: boolean;
+  includePerFileFindings: boolean;
+}
+
+export const DEFAULT_HEALTH_ACTION_OPTIONS: HealthActionOptions = {
+  includeRecommendedActions: true,
+  includePerFileFindings: true,
+};
+
+export interface GroupedHealthResult {
+  owner: string;
+  fileCount: number;
+  averageScore: number;
+  findings: unknown[];
+}
+
+export interface GroupedDuplicationResult {
+  owner: string;
+  duplicatedLines: number;
+  instances: number;
+  filePaths: string[];
+}
+
+export interface BaselineDelta {
+  metric: string;
+  baseline: number;
+  current: number;
+  delta: number;
+  deltaSign: '+' | '-' | '=';
+}
+
+export function buildGroupedHealthJson(
+  groups: GroupedHealthResult[],
+  opts: HealthActionOptions = DEFAULT_HEALTH_ACTION_OPTIONS,
+): string {
+  const payload = groups.map(g => ({
+    owner: g.owner,
+    fileCount: g.fileCount,
+    averageScore: g.averageScore,
+    ...(opts.includePerFileFindings ? { findings: g.findings } : {}),
+    ...(opts.includeRecommendedActions ? { recommendedAction: g.averageScore < 50 ? 'refactor' : 'monitor' } : {}),
+  }));
+  return JSON.stringify(payload, null, 2);
+}
+
+export function buildGroupedDuplicationJson(groups: GroupedDuplicationResult[]): string {
+  return JSON.stringify(groups, null, 2);
+}
+
+export function buildBaselineDeltasJson(
+  current: Record<string, number>,
+  baseline: Record<string, number>,
+): string {
+  const deltas: BaselineDelta[] = Object.keys({ ...current, ...baseline }).map(metric => {
+    const b = baseline[metric] ?? 0;
+    const c = current[metric] ?? 0;
+    const delta = c - b;
+    return {
+      metric,
+      baseline: b,
+      current: c,
+      delta,
+      deltaSign: delta > 0 ? '+' : delta < 0 ? '-' : '=',
+    };
+  });
+  return JSON.stringify({ deltas, summary: { improved: deltas.filter(d => d.delta < 0).length, regressed: deltas.filter(d => d.delta > 0).length, unchanged: deltas.filter(d => d.delta === 0).length } }, null, 2);
+}

package/src/report/json-schema.ts

@@ -0,0 +1,75 @@
+export const ANALYSIS_SCHEMA_VERSION = 4;
+export const HEALTH_SCHEMA_VERSION = 2;
+export const RUNTIME_COVERAGE_SCHEMA_VERSION = '1';
+export const DUPLICATION_SCHEMA_VERSION = 1;
+
+export interface SchemaEnvelope<T = unknown> {
+  $schema?: string;
+  schemaVersion: number;
+  generatedAt: string;
+  root: string;
+  data: T;
+}
+
+export function makeEnvelope<T>(
+  data: T,
+  schemaVersion: number,
+  root: string,
+  schemaUrl?: string,
+): SchemaEnvelope<T> {
+  return {
+    $schema: schemaUrl,
+    schemaVersion,
+    generatedAt: new Date().toISOString(),
+    root,
+    data,
+  };
+}
+
+export function stripRootPrefix(obj: unknown, root: string): unknown {
+  if (typeof obj === 'string') {
+    const normalized = root.endsWith('/') ? root : root + '/';
+    return obj.startsWith(normalized) ? obj.slice(normalized.length) : obj;
+  }
+  if (Array.isArray(obj)) return obj.map(item => stripRootPrefix(item, root));
+  if (obj && typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+      result[key] = stripRootPrefix(value, root);
+    }
+    return result;
+  }
+  return obj;
+}
+
+export function injectActions(
+  obj: Record<string, unknown>,
+  actions: Record<string, string[]>,
+): Record<string, unknown> {
+  return { ...obj, actions };
+}
+
+export function buildAnalysisJsonEnvelope(
+  results: unknown,
+  root: string,
+  regression?: unknown,
+): SchemaEnvelope {
+  const stripped = stripRootPrefix(results, root);
+  const data: Record<string, unknown> = { results: stripped };
+  if (regression !== undefined) data.regression = regression;
+  return makeEnvelope(data, ANALYSIS_SCHEMA_VERSION, root, `https://monograph.dev/schema/v${ANALYSIS_SCHEMA_VERSION}/analysis.json`);
+}
+
+export function buildHealthJsonEnvelope(
+  healthReport: unknown,
+  root: string,
+): SchemaEnvelope {
+  return makeEnvelope(healthReport, HEALTH_SCHEMA_VERSION, root, `https://monograph.dev/schema/v${HEALTH_SCHEMA_VERSION}/health.json`);
+}
+
+export function buildDuplicationJsonEnvelope(
+  duplication: unknown,
+  root: string,
+): SchemaEnvelope {
+  return makeEnvelope(duplication, DUPLICATION_SCHEMA_VERSION, root, `https://monograph.dev/schema/v${DUPLICATION_SCHEMA_VERSION}/duplication.json`);
+}