@monoes/monograph 1.1.0 → 1.2.0

package/src/health/target-thresholds.ts

@@ -0,0 +1,92 @@
+// Adaptive thresholds derived from the project's own metric distribution,
+// plus extended RecommendationCategory labels.
+
+export type ExtendedRecommendationCategory =
+  | 'UrgentChurnComplexity'
+  | 'BreakCircularDependency'
+  | 'SplitHighImpact'
+  | 'RemoveDeadCode'
+  | 'ExtractComplexFunctions'
+  | 'ExtractDependencies'
+  | 'AddTestCoverage'
+  | 'ReduceFanIn'
+  | 'ReduceFanOut'
+  | 'SplitLargeFile'
+  | 'ExtractModule';
+
+export interface CategoryMeta {
+  label: string;
+  compactLabel: string;
+  priority: number;
+}
+
+export const RECOMMENDATION_CATEGORIES: Record<ExtendedRecommendationCategory, CategoryMeta> = {
+  UrgentChurnComplexity:     { label: 'Urgent: High churn + complexity',   compactLabel: 'urgent',    priority: 1 },
+  BreakCircularDependency:   { label: 'Break circular dependency',          compactLabel: 'circular',  priority: 2 },
+  SplitHighImpact:           { label: 'Split high-impact file',             compactLabel: 'split',     priority: 3 },
+  RemoveDeadCode:            { label: 'Remove dead code',                   compactLabel: 'dead',      priority: 4 },
+  ExtractComplexFunctions:   { label: 'Extract complex functions',          compactLabel: 'complex',   priority: 5 },
+  ExtractDependencies:       { label: 'Extract/decouple dependencies',      compactLabel: 'decouple',  priority: 6 },
+  AddTestCoverage:           { label: 'Add test coverage',                  compactLabel: 'coverage',  priority: 7 },
+  ReduceFanIn:               { label: 'Reduce fan-in (too many importers)', compactLabel: 'fan-in',    priority: 8 },
+  ReduceFanOut:              { label: 'Reduce fan-out (too many imports)',  compactLabel: 'fan-out',   priority: 9 },
+  SplitLargeFile:            { label: 'Split large file',                   compactLabel: 'large',     priority: 10 },
+  ExtractModule:             { label: 'Extract to shared module',           compactLabel: 'extract',   priority: 11 },
+};
+
+export interface TargetThresholds {
+  fanInP95: number;
+  fanInP75: number;
+  fanOutP95: number;
+  fanOutP90: number;
+  complexityP90: number;
+  locP90: number;
+  churnP75: number;
+}
+
+const FLOOR: TargetThresholds = {
+  fanInP95: 5, fanInP75: 3, fanOutP95: 15, fanOutP90: 10,
+  complexityP90: 10, locP90: 200, churnP75: 3,
+};
+
+/** Compute adaptive thresholds from a sorted metric array. */
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.ceil(p * sorted.length) - 1;
+  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))];
+}
+
+export interface MetricSample {
+  fanIn: number[];
+  fanOut: number[];
+  complexity: number[];
+  loc: number[];
+  churnScore: number[];
+}
+
+export function computeTargetThresholds(sample: MetricSample): TargetThresholds {
+  const sort = (a: number[]) => [...a].sort((x, y) => x - y);
+  const fi = sort(sample.fanIn);
+  const fo = sort(sample.fanOut);
+  const cc = sort(sample.complexity);
+  const lc = sort(sample.loc);
+  const ch = sort(sample.churnScore);
+
+  return {
+    fanInP95:      Math.max(FLOOR.fanInP95,     percentile(fi, 0.95)),
+    fanInP75:      Math.max(FLOOR.fanInP75,     percentile(fi, 0.75)),
+    fanOutP95:     Math.max(FLOOR.fanOutP95,    percentile(fo, 0.95)),
+    fanOutP90:     Math.max(FLOOR.fanOutP90,    percentile(fo, 0.90)),
+    complexityP90: Math.max(FLOOR.complexityP90, percentile(cc, 0.90)),
+    locP90:        Math.max(FLOOR.locP90,        percentile(lc, 0.90)),
+    churnP75:      Math.max(FLOOR.churnP75,      percentile(ch, 0.75)),
+  };
+}
+
+export function labelForCategory(cat: ExtendedRecommendationCategory): string {
+  return RECOMMENDATION_CATEGORIES[cat].label;
+}
+
+export function compactLabelForCategory(cat: ExtendedRecommendationCategory): string {
+  return RECOMMENDATION_CATEGORIES[cat].compactLabel;
+}

package/src/health/target-types.ts

@@ -0,0 +1,54 @@
+export interface TargetThresholds {
+  fanInP95: number;
+  fanInP75: number;
+  fanInP25: number;
+  fanOutP95: number;
+  fanOutP90: number;
+}
+
+export type RecommendationCategory =
+  | 'UrgentChurnComplexity'
+  | 'BreakCircularDependency'
+  | 'SplitHighImpact'
+  | 'RemoveDeadCode'
+  | 'ExtractComplexFunctions'
+  | 'ExtractDependencies'
+  | 'AddTestCoverage';
+
+export type ContributingFactor =
+  | 'HighChurn'
+  | 'HighComplexity'
+  | 'HighFanIn'
+  | 'HighFanOut'
+  | 'InCycle'
+  | 'HasDeadCode'
+  | 'LowCoverage'
+  | 'HeavyDependencies';
+
+export type EffortEstimate = 'Low' | 'Medium' | 'High' | 'VeryHigh';
+
+export type Confidence = 'Low' | 'Medium' | 'High';
+
+export interface RefactoringTarget {
+  filePath: string;
+  category: RecommendationCategory;
+  priority: number;
+  confidence: Confidence;
+  effort: EffortEstimate;
+  factors: ContributingFactor[];
+  description: string;
+  estimatedLines?: number;
+}
+
+export function computeEffortFromLines(lines: number): EffortEstimate {
+  if (lines < 50) return 'Low';
+  if (lines < 200) return 'Medium';
+  if (lines < 500) return 'High';
+  return 'VeryHigh';
+}
+
+export function computeConfidenceFromFactors(factorCount: number): Confidence {
+  if (factorCount === 1) return 'Low';
+  if (factorCount <= 3) return 'Medium';
+  return 'High';
+}

package/src/health/targets.ts

@@ -0,0 +1,151 @@
+import {
+  type Confidence,
+  type EffortEstimate,
+  type RecommendationCategory,
+  type RefactoringTarget,
+  type TargetThresholds,
+} from './target-types.js';
+
+export interface FileScoreInput {
+  filePath: string;
+  fanIn: number;
+  fanOut: number;
+  churnScore?: number;
+  complexity?: number;
+  deadCodeRatio?: number;
+  inCycle?: boolean;
+  coveragePct?: number;
+  lineCount?: number;
+}
+
+function percentileFromSorted(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.ceil(sorted.length * p) - 1;
+  return sorted[Math.min(Math.max(idx, 0), sorted.length - 1)];
+}
+
+export function computeThresholds(files: FileScoreInput[]): TargetThresholds {
+  if (files.length === 0) {
+    return { fanInP95: 5, fanInP75: 3, fanInP25: 2, fanOutP95: 8, fanOutP90: 5 };
+  }
+
+  const fanIns = [...files.map(f => f.fanIn)].sort((a, b) => a - b);
+  const fanOuts = [...files.map(f => f.fanOut)].sort((a, b) => a - b);
+
+  return {
+    fanInP95: Math.max(5, percentileFromSorted(fanIns, 0.95)),
+    fanInP75: Math.max(3, percentileFromSorted(fanIns, 0.75)),
+    fanInP25: Math.max(2, percentileFromSorted(fanIns, 0.25)),
+    fanOutP95: Math.max(8, percentileFromSorted(fanOuts, 0.95)),
+    fanOutP90: Math.max(5, percentileFromSorted(fanOuts, 0.90)),
+  };
+}
+
+function computePriority(
+  file: FileScoreInput,
+  thresholds: TargetThresholds,
+): number {
+  const densityNorm = Math.min(file.complexity ?? 0, 1.0);
+  const fanInNorm = Math.min(file.fanIn / thresholds.fanInP95, 1.0);
+  const fanOutNorm = Math.min(file.fanOut / thresholds.fanOutP95, 1.0);
+  const hotspotBoost = file.churnScore != null ? Math.min(file.churnScore / 100, 1.0) : 0;
+  const deadCode = file.deadCodeRatio ?? 0;
+
+  const priority =
+    densityNorm * 30 +
+    hotspotBoost * 25 +
+    deadCode * 20 +
+    fanInNorm * 15 +
+    fanOutNorm * 10;
+
+  return Math.round(Math.min(Math.max(priority, 0), 100) * 10) / 10;
+}
+
+function confidenceForCategory(category: RecommendationCategory): Confidence {
+  switch (category) {
+    case 'RemoveDeadCode':
+    case 'BreakCircularDependency':
+    case 'ExtractComplexFunctions':
+    case 'AddTestCoverage':
+      return 'High';
+    case 'SplitHighImpact':
+    case 'ExtractDependencies':
+      return 'Medium';
+    case 'UrgentChurnComplexity':
+      return 'Low';
+  }
+}
+
+function effortForFile(file: FileScoreInput, thresholds: TargetThresholds): EffortEstimate {
+  const lines = file.lineCount ?? 0;
+  if (lines >= 500 || file.fanIn >= thresholds.fanInP95) return 'High';
+  if (lines < 100 && file.fanIn < thresholds.fanInP25) return 'Low';
+  return 'Medium';
+}
+
+function effortNumeric(effort: EffortEstimate): number {
+  switch (effort) {
+    case 'Low': return 1;
+    case 'Medium': return 2;
+    case 'High': return 3;
+    case 'VeryHigh': return 4;
+  }
+}
+
+function matchRule(
+  file: FileScoreInput,
+  thresholds: TargetThresholds,
+): RecommendationCategory | null {
+  const churn = file.churnScore ?? 0;
+  const complexity = file.complexity ?? 0;
+  const deadCode = file.deadCodeRatio ?? 0;
+  const coverage = file.coveragePct ?? 100;
+
+  if (churn >= 50 && complexity > 0.5) return 'UrgentChurnComplexity';
+  if (file.inCycle && file.fanIn >= 5) return 'BreakCircularDependency';
+  if (complexity > 0.3 && file.fanIn >= thresholds.fanInP95) return 'SplitHighImpact';
+  if (deadCode > 0.3) return 'RemoveDeadCode';
+  if (complexity > 0.3) return 'ExtractComplexFunctions';
+  if (file.fanOut > thresholds.fanOutP95) return 'ExtractDependencies';
+  if (coverage < 50) return 'AddTestCoverage';
+  if (file.inCycle) return 'BreakCircularDependency';
+  return null;
+}
+
+export function computeRefactoringTargets(
+  files: FileScoreInput[],
+  thresholds: TargetThresholds,
+  maxTargets = 20,
+): RefactoringTarget[] {
+  const results: Array<RefactoringTarget & { efficiency: number }> = [];
+
+  for (const file of files) {
+    const category = matchRule(file, thresholds);
+    if (category == null) continue;
+
+    const priority = computePriority(file, thresholds);
+    const effort = effortForFile(file, thresholds);
+    const confidence = confidenceForCategory(category);
+    const efficiency = priority / effortNumeric(effort);
+
+    results.push({
+      filePath: file.filePath,
+      category,
+      priority,
+      confidence,
+      effort,
+      factors: [],
+      description: category,
+      estimatedLines: file.lineCount,
+      efficiency,
+    });
+  }
+
+  results.sort((a, b) => {
+    const diff = b.efficiency - a.efficiency;
+    if (diff !== 0) return diff;
+    return b.priority - a.priority;
+  });
+
+  return results.slice(0, maxTargets).map(({ efficiency: _eff, ...rest }) => rest);
+}

package/src/health/timings.ts

@@ -0,0 +1,86 @@
+export interface HealthTimings {
+  churnMs: number;
+  complexityMs: number;
+  duplicationMs: number;
+  scoringMs: number;
+  renderMs: number;
+  totalMs: number;
+}
+
+export function printPerformanceTable(timings: HealthTimings): string {
+  const rows: Array<{ phase: string; ms: number }> = [
+    { phase: 'Churn', ms: timings.churnMs },
+    { phase: 'Complexity', ms: timings.complexityMs },
+    { phase: 'Duplication', ms: timings.duplicationMs },
+    { phase: 'Scoring', ms: timings.scoringMs },
+    { phase: 'Render', ms: timings.renderMs },
+    { phase: 'TOTAL', ms: timings.totalMs },
+  ];
+
+  const total = timings.totalMs;
+
+  const phaseColWidth = Math.max('Phase'.length, ...rows.map((r) => r.phase.length));
+  const msColWidth = Math.max('Duration (ms)'.length, ...rows.map((r) => String(r.ms).length));
+  const pctColWidth = Math.max('% of Total'.length, 6);
+
+  const sep = `+${'-'.repeat(phaseColWidth + 2)}+${'-'.repeat(msColWidth + 2)}+${'-'.repeat(pctColWidth + 2)}+`;
+  const header = `| ${'Phase'.padEnd(phaseColWidth)} | ${'Duration (ms)'.padStart(msColWidth)} | ${'% of Total'.padStart(pctColWidth)} |`;
+
+  const lines: string[] = [sep, header, sep];
+
+  for (const row of rows) {
+    const pct = total > 0 ? ((row.ms / total) * 100).toFixed(1) : '0.0';
+    const line = `| ${row.phase.padEnd(phaseColWidth)} | ${String(row.ms).padStart(msColWidth)} | ${pct.padStart(pctColWidth)} |`;
+    lines.push(line);
+  }
+
+  lines.push(sep);
+  return lines.join('\n');
+}
+
+// ── Round 8: health pipeline timing breakdown ─────────────────────────────
+
+export interface HealthPipelineTimings {
+  configMs: number;
+  discoverMs: number;
+  parseMs: number;
+  complexityMs: number;
+  fileScoresMs: number;
+  gitChurnMs: number;
+  gitChurnCacheHit: boolean;
+  hotspotsMs: number;
+  duplicationMs: number;
+  targetsMs: number;
+  totalMs: number;
+}
+
+export const ZERO_HEALTH_PIPELINE_TIMINGS: HealthPipelineTimings = {
+  configMs: 0, discoverMs: 0, parseMs: 0, complexityMs: 0,
+  fileScoresMs: 0, gitChurnMs: 0, gitChurnCacheHit: false,
+  hotspotsMs: 0, duplicationMs: 0, targetsMs: 0, totalMs: 0,
+};
+
+export function formatHealthPipelineTimings(t: HealthPipelineTimings): string {
+  const rows: [string, string][] = [
+    ['Config',      `${t.configMs}ms`],
+    ['Discover',    `${t.discoverMs}ms`],
+    ['Parse',       `${t.parseMs}ms`],
+    ['Complexity',  `${t.complexityMs}ms`],
+    ['File scores', `${t.fileScoresMs}ms`],
+    ['Git churn',   `${t.gitChurnMs}ms${t.gitChurnCacheHit ? ' (cached)' : ''}`],
+    ['Hotspots',    `${t.hotspotsMs}ms`],
+    ['Duplication', `${t.duplicationMs}ms`],
+    ['Targets',     `${t.targetsMs}ms`],
+    ['Total',       `${t.totalMs}ms`],
+  ];
+  const labelW = Math.max(...rows.map(r => r[0].length));
+  return rows.map(([l, v]) => `${l.padEnd(labelW)}  ${v}`).join('\n');
+}
+
+export function sumHealthPipelineTimings(phases: Partial<HealthPipelineTimings>): number {
+  const phaseKeys: Array<keyof HealthPipelineTimings> = [
+    'configMs', 'discoverMs', 'parseMs', 'complexityMs',
+    'fileScoresMs', 'gitChurnMs', 'hotspotsMs', 'duplicationMs', 'targetsMs',
+  ];
+  return phaseKeys.reduce((s, k) => s + ((phases[k] as number | undefined) ?? 0), 0);
+}

package/src/health/trend-types.ts

@@ -0,0 +1,57 @@
+export type TrendDirection = 'improving' | 'declining' | 'stable';
+
+export function trendArrow(d: TrendDirection): string {
+  return d === 'improving' ? '↑' : d === 'declining' ? '↓' : '→';
+}
+
+export function trendColor(d: TrendDirection): string {
+  return d === 'improving' ? '\x1b[32m' : d === 'declining' ? '\x1b[31m' : '\x1b[33m';
+}
+
+export interface TrendCount {
+  value: number;
+  total: number;
+}
+
+export interface TrendMetric {
+  name: string;
+  label: string;
+  previous: number;
+  current: number;
+  delta: number;
+  direction: TrendDirection;
+  unit: string;
+  previousCount?: TrendCount;
+  currentCount?: TrendCount;
+}
+
+export interface TrendPoint {
+  timestamp: string;
+  gitSha?: string;
+  score?: number;
+  grade?: string;
+  coverageModel?: string;
+  snapshotSchemaVersion?: number;
+}
+
+export interface HealthTrend {
+  comparedTo: TrendPoint;
+  metrics: TrendMetric[];
+  snapshotsLoaded: number;
+  overallDirection: TrendDirection;
+}
+
+export function computeOverallDirection(metrics: TrendMetric[]): TrendDirection {
+  if (metrics.length === 0) return 'stable';
+  const improving = metrics.filter(m => m.direction === 'improving').length;
+  const declining = metrics.filter(m => m.direction === 'declining').length;
+  if (improving > declining) return 'improving';
+  if (declining > improving) return 'declining';
+  return 'stable';
+}
+
+export function formatTrendMetric(m: TrendMetric): string {
+  const sign = m.delta >= 0 ? '+' : '';
+  const arrow = trendArrow(m.direction);
+  return `${m.label}: ${m.previous}${m.unit} → ${m.current}${m.unit} (${sign}${m.delta.toFixed(1)}${m.unit}) ${arrow}`;
+}

package/src/health/trends.ts

@@ -0,0 +1,86 @@
+import type { HealthScore, VitalSigns, VitalSignsSnapshot } from './vital-signs-snapshot.js';
+
+export type TrendDirection = 'improving' | 'declining' | 'stable';
+export const STABLE_BAND = 0.5;
+
+export interface TrendMetric {
+  current: number;
+  previous: number;
+  delta: number;
+  direction: TrendDirection;
+}
+
+export interface TrendCount {
+  current: number;
+  previous: number;
+  delta: number;
+  direction: TrendDirection;
+}
+
+export interface HealthTrend {
+  healthScore: TrendMetric;
+  deadCodePct: TrendMetric;
+  duplicationPct: TrendMetric;
+  complexityHighPct: TrendMetric;
+  complexityCriticalPct: TrendMetric;
+  hotspotDensity: TrendMetric;
+  busFactor: TrendCount;
+  unusedDepsPct: TrendMetric;
+  maintainabilityIndex: TrendMetric;
+}
+
+export function trendDirection(
+  current: number,
+  previous: number,
+  isHigherBetter = false
+): TrendDirection {
+  const delta = current - previous;
+  if (Math.abs(delta) <= STABLE_BAND) {
+    return 'stable';
+  }
+  if (isHigherBetter) {
+    return delta > 0 ? 'improving' : 'declining';
+  }
+  return delta < 0 ? 'improving' : 'declining';
+}
+
+export function makeTrendMetric(
+  current: number,
+  previous: number,
+  isHigherBetter = false
+): TrendMetric {
+  return {
+    current,
+    previous,
+    delta: current - previous,
+    direction: trendDirection(current, previous, isHigherBetter),
+  };
+}
+
+export function computeTrend(
+  current: VitalSigns,
+  currentScore: HealthScore,
+  previous: VitalSignsSnapshot
+): HealthTrend {
+  const prev = previous.vitalSigns;
+  const prevScore = previous.healthScore;
+  return {
+    healthScore: makeTrendMetric(currentScore.value, prevScore.value, true),
+    deadCodePct: makeTrendMetric(current.deadCodePct, prev.deadCodePct, false),
+    duplicationPct: makeTrendMetric(current.duplicationPct, prev.duplicationPct, false),
+    complexityHighPct: makeTrendMetric(current.complexityHighPct, prev.complexityHighPct, false),
+    complexityCriticalPct: makeTrendMetric(
+      current.complexityCriticalPct,
+      prev.complexityCriticalPct,
+      false
+    ),
+    hotspotDensity: makeTrendMetric(current.hotspotDensity, prev.hotspotDensity, false),
+    busFactor: makeTrendMetric(current.busFactor, prev.busFactor, true),
+    unusedDepsPct: makeTrendMetric(current.unusedDepsPct, prev.unusedDepsPct, false),
+    maintainabilityIndex: makeTrendMetric(
+      current.maintainabilityIndex,
+      prev.maintainabilityIndex,
+      true
+    ),
+  };
+}

package/src/health/vital-signs-compute.ts

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, appendFileSync } from 'fs';
+import type { VitalSigns } from './health-report-types.js';
+
+export interface VitalSignsSnapshot {
+  timestamp: number;
+  score: number;
+  vitals: VitalSigns;
+}
+
+export type TrendDirection = 'improving' | 'degrading' | 'stable';
+
+export interface VitalSignsTrend {
+  direction: TrendDirection;
+  scoreDelta: number;
+  snapshotCount: number;
+}
+
+const TREND_TOLERANCE = 0.5;
+
+const round1 = (v: number): number => Math.round(v * 10) / 10;
+
+export function computeVitalSignsScore(vitals: VitalSigns): number {
+  let score = 100;
+
+  const deadFilePenalty = round1(Math.min(vitals.deadFilePct * 0.2, 15));
+  score -= deadFilePenalty;
+
+  const deadExportPenalty = round1(Math.min(vitals.deadExportPct * 0.2, 15));
+  score -= deadExportPenalty;
+
+  const complexityPenalty = round1(Math.min(Math.max(vitals.avgCyclomatic - 1.5, 0) * 5, 20));
+  score -= complexityPenalty;
+
+  const p90Penalty = round1(Math.min(Math.max(vitals.p90Cyclomatic - 10, 0), 10));
+  score -= p90Penalty;
+
+  const maintPenalty = round1(Math.min(Math.max(70 - vitals.maintainabilityAvg, 0) * 0.5, 15));
+  score -= maintPenalty;
+
+  const hotspotPenalty = round1(Math.min(vitals.hotspotCount * 2, 10));
+  score -= hotspotPenalty;
+
+  const unusedDepPenalty = round1(Math.min(vitals.unusedDepCount, 10));
+  score -= unusedDepPenalty;
+
+  const circularDepPenalty = round1(Math.min(vitals.circularDepCount, 10));
+  score -= circularDepPenalty;
+
+  const dupPenalty = round1(Math.min(Math.max(vitals.duplicationPct - 5, 0), 10));
+  score -= dupPenalty;
+
+  const couplingPenalty = round1(Math.min(Math.max(vitals.couplingHighPct - 5, 0) * 0.5, 5));
+  score -= couplingPenalty;
+
+  return Math.max(0, Math.min(100, round1(score)));
+}
+
+export function computeTrend(snapshots: VitalSignsSnapshot[]): VitalSignsTrend {
+  if (snapshots.length < 2) {
+    return { direction: 'stable', scoreDelta: 0, snapshotCount: snapshots.length };
+  }
+
+  const prev = snapshots[snapshots.length - 2];
+  const last = snapshots[snapshots.length - 1];
+  const delta = round1(last.score - prev.score);
+
+  let direction: TrendDirection;
+  if (Math.abs(delta) <= TREND_TOLERANCE) {
+    direction = 'stable';
+  } else if (delta > 0) {
+    direction = 'improving';
+  } else {
+    direction = 'degrading';
+  }
+
+  return { direction, scoreDelta: delta, snapshotCount: snapshots.length };
+}
+
+export function buildSnapshot(vitals: VitalSigns, score: number): VitalSignsSnapshot {
+  return {
+    timestamp: Date.now(),
+    score,
+    vitals,
+  };
+}
+
+export function saveSnapshot(snapshotPath: string, snapshot: VitalSignsSnapshot): void {
+  appendFileSync(snapshotPath, JSON.stringify(snapshot) + '\n', 'utf-8');
+}
+
+export function loadSnapshots(snapshotPath: string): VitalSignsSnapshot[] {
+  if (!existsSync(snapshotPath)) return [];
+
+  const raw = readFileSync(snapshotPath, 'utf-8');
+  const snapshots: VitalSignsSnapshot[] = [];
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      snapshots.push(JSON.parse(trimmed) as VitalSignsSnapshot);
+    } catch {
+      // skip malformed lines
+    }
+  }
+
+  return snapshots.sort((a, b) => a.timestamp - b.timestamp);
+}