@qulib/core 0.8.2 → 0.10.0

package/dist/adapters/pr-metadata-adapter.js

@@ -0,0 +1,146 @@
+/**
+ * PR-metadata evidence adapter (P4 — evidence collectors).
+ *
+ * Maps a pull-request review/checks payload (as returned by `gh pr view --json
+ * reviewDecision,statusCheckRollup,mergeable,number,url,additions,deletions`)
+ * into an `EvidenceItem` for `computeReleaseConfidence`, using the
+ * `deploy-metadata` source kind — the closest P3-reserved kind for
+ * PR-level ship-readiness.
+ *
+ * Design:
+ *   - Pure function. The caller fetches the `gh` JSON; this adapter scores it.
+ *   - Applicability:
+ *       `applicable`     — a PR exists and review/check state is readable
+ *       `not_applicable` — no PR for this ref (direct push, script, etc.)
+ *       `unknown`        — PR exists but checks are still pending / state ambiguous
+ *   - Score formula (0..100):
+ *       Base 60 points:  PR is open and merge-ready (no conflicts)
+ *       +20: reviewDecision === 'APPROVED'
+ *       +20: all status checks pass (statusCheckRollup every entry state === 'SUCCESS')
+ *       Deductions:
+ *         -10: any failing status check  (per failing check, capped at 20)
+ *         -15: reviewDecision === 'CHANGES_REQUESTED'
+ *   - The adapter NEVER fabricates a PR number or URL; if absent from the payload
+ *     the evidence strings omit them (WAVE-GUARDRAILS: no fabricated data).
+ */
+const PR_META_WEIGHT = 0.07; // conservative; real weight rebalanced by the aggregator
+/**
+ * Produce a `deploy-metadata` EvidenceItem from a PR metadata payload.
+ * Returns `not_applicable` when `noPr` is true, `unknown` when checks are
+ * pending or state is ambiguous, and `applicable` with a real score otherwise.
+ */
+export function prMetadataToEvidence(input, collectedAt) {
+    const now = collectedAt ?? input.collectedAt ?? new Date().toISOString();
+    const source = 'deploy-metadata';
+    const weight = PR_META_WEIGHT;
+    // Explicit no-PR case.
+    if (input.noPr) {
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'not_applicable',
+            blocking: false,
+            evidence: ['No pull request exists for this ref (direct push or pre-PR state).'],
+            recommendations: [],
+            reason: 'No PR for this ref — PR review and check signal not applicable.',
+            collectedAt: now,
+            collector: { tool: 'qulib.pr-metadata-adapter' },
+        };
+    }
+    const prLabel = input.number != null ? `PR #${input.number}` : 'PR';
+    const prRef = input.url ?? null;
+    // Checks-pending / UNKNOWN mergeable → unknown applicability (cannot score honestly).
+    const allChecks = input.statusCheckRollup ?? [];
+    const pending = allChecks.filter((c) => c.state === 'PENDING');
+    if ((pending.length > 0 && allChecks.length > 0 && pending.length === allChecks.length) ||
+        input.mergeable === 'UNKNOWN') {
+        const evidence = [
+            `${prLabel}: status checks still pending (${pending.length}/${allChecks.length}).`,
+            ...(prRef ? [`${prRef}`] : []),
+        ];
+        return {
+            source,
+            score: 0,
+            weight,
+            applicability: 'unknown',
+            blocking: false,
+            evidence,
+            recommendations: ['Wait for all status checks to complete before shipping.'],
+            reason: `${prLabel} checks are still pending — cannot score PR readiness honestly.`,
+            collectedAt: now,
+            collector: { tool: 'qulib.pr-metadata-adapter', inputRef: prRef ?? undefined },
+        };
+    }
+    // Score computation.
+    let score = 60; // base: a PR exists and is evaluable
+    // Mergeability.
+    if (input.mergeable === 'CONFLICTING') {
+        score -= 30; // merge conflicts are a hard deduction
+    }
+    // Review decision.
+    const rd = input.reviewDecision;
+    if (rd === 'APPROVED') {
+        score += 20;
+    }
+    else if (rd === 'CHANGES_REQUESTED') {
+        score -= 15;
+    }
+    // REVIEW_REQUIRED or null/undefined: no bonus, no deduction (reviewer not yet assigned)
+    // Status checks.
+    const passing = allChecks.filter((c) => c.state === 'SUCCESS' || c.state === 'NEUTRAL' || c.state === 'SKIPPED');
+    const failing = allChecks.filter((c) => c.state === 'FAILURE' || c.state === 'ERROR');
+    if (allChecks.length > 0 && failing.length === 0) {
+        score += 20; // all checks green
+    }
+    // Deduct per failing check (capped at −20).
+    score -= Math.min(20, failing.length * 10);
+    score = Math.max(0, Math.min(100, score));
+    // Build evidence strings — never fabricated.
+    const evidence = [];
+    const reviewStr = rd === 'APPROVED'
+        ? 'APPROVED'
+        : rd === 'CHANGES_REQUESTED'
+            ? 'CHANGES_REQUESTED'
+            : rd === 'REVIEW_REQUIRED'
+                ? 'REVIEW_REQUIRED'
+                : 'no review yet';
+    const mergeStr = input.mergeable === 'MERGEABLE'
+        ? 'mergeable'
+        : input.mergeable === 'CONFLICTING'
+            ? 'CONFLICTING (merge conflicts)'
+            : 'merge state unknown';
+    evidence.push(`${prLabel}: review=${reviewStr}, ${mergeStr}.`);
+    if (allChecks.length > 0) {
+        evidence.push(`Status checks: ${passing.length} passed, ${failing.length} failed, ${pending.length} pending of ${allChecks.length} total.`);
+        for (const f of failing.slice(0, 3)) {
+            evidence.push(`  Check FAILED: ${f.name ?? 'unnamed'}${f.targetUrl ? ` (${f.targetUrl})` : ''}`);
+        }
+    }
+    else {
+        evidence.push('No status checks configured for this PR.');
+    }
+    if (prRef)
+        evidence.push(prRef);
+    // Recommendations.
+    const recommendations = [];
+    if (rd === 'CHANGES_REQUESTED')
+        recommendations.push('Address review comments before shipping.');
+    if (rd === 'REVIEW_REQUIRED' || rd == null)
+        recommendations.push('Request and obtain PR approval before shipping.');
+    if (failing.length > 0)
+        recommendations.push(`Fix ${failing.length} failing status check(s) before merging.`);
+    if (input.mergeable === 'CONFLICTING')
+        recommendations.push('Resolve merge conflicts before shipping.');
+    return {
+        source,
+        score,
+        weight,
+        applicability: 'applicable',
+        blocking: false,
+        evidence,
+        recommendations,
+        collectedAt: now,
+        collector: { tool: 'qulib.pr-metadata-adapter', inputRef: prRef ?? undefined },
+    };
+}

package/dist/adapters/validate-specs.d.ts

@@ -0,0 +1,55 @@
+import type { GeneratedTest } from '../schemas/gap-analysis.schema.js';
+/**
+ * Per-spec validation outcome from the scaffold dry-run.
+ *
+ * `valid: false` means the TypeScript compiler reported one or more *syntactic*
+ * errors when transpiling the generated spec as a standalone module — i.e. the
+ * generator emitted code that will not parse, so it would fail the moment a
+ * developer ran the test suite. `errors` carries the flattened compiler
+ * messages so the failure is actionable, not just a boolean.
+ */
+export interface SpecValidation {
+    scenarioId: string;
+    filename: string;
+    outputPath: string;
+    valid: boolean;
+    errors: string[];
+}
+/** Aggregate result of validating every generated spec in a scaffold run. */
+export interface SpecValidationReport {
+    ok: boolean;
+    total: number;
+    invalidCount: number;
+    results: SpecValidation[];
+}
+/**
+ * Dry-run a single generated spec through the TypeScript compiler.
+ *
+ * `transpileModule` performs single-file syntax transformation only — no type
+ * checking, no module resolution — so it is the right tool to answer the one
+ * question the scaffold must not get wrong: *does the string we are about to
+ * write to disk actually parse as TypeScript?* A clean run (zero error-category
+ * diagnostics AND non-empty output) means the spec is syntactically valid; any
+ * error diagnostic means the generator produced broken code.
+ *
+ * We deliberately do NOT resolve `@playwright/test` / Cypress globals here:
+ * those are type-level concerns that require the consumer's node_modules. The
+ * gap this closes is *parse/compile-shape*, which is generator-local and cheap
+ * to check at scaffold time.
+ */
+export declare function validateSpecCode(code: string): {
+    valid: boolean;
+    errors: string[];
+};
+/** Validate one GeneratedTest, returning a structured per-spec outcome. */
+export declare function validateGeneratedTest(test: GeneratedTest): SpecValidation;
+/**
+ * Validate every generated spec in a scaffold run.
+ *
+ * `ok` is true only when *all* specs parse. This is the gate the CLI consults
+ * to decide its exit code: a scaffold that writes a spec which cannot parse is a
+ * silent correctness failure, and the whole point of the dry-run is to catch it
+ * before the developer does.
+ */
+export declare function validateGeneratedTests(tests: GeneratedTest[]): SpecValidationReport;
+//# sourceMappingURL=validate-specs.d.ts.map

package/dist/adapters/validate-specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-specs.d.ts","sourceRoot":"","sources":["../../src/adapters/validate-specs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA2BnF;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,CASzE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,oBAAoB,CASnF"}

package/dist/adapters/validate-specs.js

@@ -0,0 +1,67 @@
+import ts from 'typescript';
+/**
+ * Dry-run a single generated spec through the TypeScript compiler.
+ *
+ * `transpileModule` performs single-file syntax transformation only — no type
+ * checking, no module resolution — so it is the right tool to answer the one
+ * question the scaffold must not get wrong: *does the string we are about to
+ * write to disk actually parse as TypeScript?* A clean run (zero error-category
+ * diagnostics AND non-empty output) means the spec is syntactically valid; any
+ * error diagnostic means the generator produced broken code.
+ *
+ * We deliberately do NOT resolve `@playwright/test` / Cypress globals here:
+ * those are type-level concerns that require the consumer's node_modules. The
+ * gap this closes is *parse/compile-shape*, which is generator-local and cheap
+ * to check at scaffold time.
+ */
+export function validateSpecCode(code) {
+    const result = ts.transpileModule(code, {
+        compilerOptions: {
+            module: ts.ModuleKind.ESNext,
+            target: ts.ScriptTarget.ES2020,
+            // isolatedModules keeps this a pure syntax pass and surfaces
+            // single-file-illegal constructs, matching how a bundler would see it.
+            isolatedModules: true,
+        },
+        reportDiagnostics: true,
+    });
+    const errorDiagnostics = (result.diagnostics ?? []).filter((d) => d.category === ts.DiagnosticCategory.Error);
+    const errors = errorDiagnostics.map((d) => ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+    // A clean transpile yields output text. Empty output with no diagnostics would
+    // be suspicious, so treat it as invalid too rather than silently passing.
+    const producedOutput = result.outputText.trim().length > 0;
+    const valid = errors.length === 0 && producedOutput;
+    if (!valid && errors.length === 0) {
+        errors.push('transpile produced no output for a non-empty spec');
+    }
+    return { valid, errors };
+}
+/** Validate one GeneratedTest, returning a structured per-spec outcome. */
+export function validateGeneratedTest(test) {
+    const { valid, errors } = validateSpecCode(test.code);
+    return {
+        scenarioId: test.scenarioId,
+        filename: test.filename,
+        outputPath: test.outputPath,
+        valid,
+        errors,
+    };
+}
+/**
+ * Validate every generated spec in a scaffold run.
+ *
+ * `ok` is true only when *all* specs parse. This is the gate the CLI consults
+ * to decide its exit code: a scaffold that writes a spec which cannot parse is a
+ * silent correctness failure, and the whole point of the dry-run is to catch it
+ * before the developer does.
+ */
+export function validateGeneratedTests(tests) {
+    const results = tests.map(validateGeneratedTest);
+    const invalidCount = results.filter((r) => !r.valid).length;
+    return {
+        ok: invalidCount === 0,
+        total: results.length,
+        invalidCount,
+        results,
+    };
+}

package/dist/baseline/baseline.d.ts

@@ -0,0 +1,54 @@
+import type { GapAnalysis } from '../schemas/gap-analysis.schema.js';
+import { type BaselineSnapshot, type BaselineDelta } from './baseline.schema.js';
+/**
+ * Produce a filesystem-safe slug from a URL.
+ * e.g. "https://my-app.vercel.app/admin" → "my-app_vercel_app__admin"
+ */
+export declare function slugifyUrl(url: string): string;
+/**
+ * Return the default root for baseline storage: `<cwd>/.qulib-baselines`.
+ * Callers may supply an explicit `baseDir` to override.
+ */
+export declare function defaultBaselineRoot(): string;
+/**
+ * Save a baseline snapshot derived from the given `GapAnalysis` result.
+ *
+ * @returns The saved snapshot.
+ */
+export declare function saveBaseline(analysis: GapAnalysis, url: string, options?: {
+    baseDir?: string;
+    label?: string;
+}): Promise<BaselineSnapshot>;
+/**
+ * Load a specific baseline snapshot by its `id`.
+ *
+ * @throws If the file does not exist or fails schema validation.
+ */
+export declare function loadBaseline(id: string, options?: {
+    baseDir?: string;
+}): Promise<BaselineSnapshot>;
+/**
+ * List all saved baselines for the given URL, sorted newest-first.
+ *
+ * Returns an empty array if no baselines exist yet.
+ */
+export declare function listBaselines(url: string, options?: {
+    baseDir?: string;
+}): Promise<BaselineSnapshot[]>;
+/**
+ * Delete a specific baseline snapshot by its `id`.
+ *
+ * @throws If the file does not exist.
+ */
+export declare function deleteBaseline(id: string, options?: {
+    baseDir?: string;
+}): Promise<void>;
+/**
+ * Compare two baseline snapshots and return a structured delta report.
+ *
+ * - `newGaps`: problems present in `current` but not in `prior`.
+ * - `resolvedGaps`: problems present in `prior` but no longer in `current`.
+ * - `severityChanges`: same problem (matching key) with a different severity.
+ */
+export declare function compareBaselines(prior: BaselineSnapshot, current: BaselineSnapshot): BaselineDelta;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/baseline/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../../src/baseline/baseline.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAO,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAEnB,MAAM,sBAAsB,CAAC;AAY9B;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAeD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,WAAW,EACrB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACjD,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuB5G;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoC7B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAclG;AAcD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAiFlG"}

package/dist/baseline/baseline.js

@@ -0,0 +1,252 @@
+import { readFile, writeFile, mkdir, readdir, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { BaselineSnapshotSchema, BaselineDeltaSchema, } from './baseline.schema.js';
+const BASELINE_DIR_NAME = '.qulib-baselines';
+/**
+ * Resolve the directory where baselines for the given URL are stored.
+ * Each URL gets its own subdirectory under baseDir, keyed by a stable slug.
+ */
+function resolveBaselineDir(baseDir, urlSlug) {
+    return join(baseDir, urlSlug);
+}
+/**
+ * Produce a filesystem-safe slug from a URL.
+ * e.g. "https://my-app.vercel.app/admin" → "my-app_vercel_app__admin"
+ */
+export function slugifyUrl(url) {
+    return url
+        .replace(/^https?:\/\//, '')
+        .replace(/[^a-zA-Z0-9._-]/g, '_')
+        .replace(/__+/g, '_')
+        .replace(/^_|_$/g, '')
+        .slice(0, 80);
+}
+/**
+ * Return the default root for baseline storage: `<cwd>/.qulib-baselines`.
+ * Callers may supply an explicit `baseDir` to override.
+ */
+export function defaultBaselineRoot() {
+    return join(process.cwd(), BASELINE_DIR_NAME);
+}
+/**
+ * Convert a `GapAnalysis` result into the compact `BaselineGap[]` shape.
+ * Drops fields not needed for delta comparison (id, description, recommendation).
+ */
+function toBaselineGaps(gaps) {
+    return gaps.map((g) => ({
+        path: g.path,
+        severity: g.severity,
+        category: g.category,
+        reason: g.reason,
+    }));
+}
+/**
+ * Save a baseline snapshot derived from the given `GapAnalysis` result.
+ *
+ * @returns The saved snapshot.
+ */
+export async function saveBaseline(analysis, url, options = {}) {
+    const baseDir = options.baseDir ?? defaultBaselineRoot();
+    const urlSlug = slugifyUrl(url);
+    const dir = resolveBaselineDir(baseDir, urlSlug);
+    await mkdir(dir, { recursive: true });
+    const now = new Date();
+    // Include milliseconds (23 chars: "2024-01-01T00-00-00-000") so rapid successive saves
+    // do not collide on the same filename within the same second.
+    const timestamp = now.toISOString().replace(/[:.]/g, '-').slice(0, 23);
+    const id = `${urlSlug}__${timestamp}`;
+    const filename = `${id}.json`;
+    const snapshot = {
+        id,
+        url,
+        savedAt: now.toISOString(),
+        releaseConfidence: analysis.releaseConfidence ?? 0,
+        gapCount: analysis.gaps.length,
+        gaps: toBaselineGaps(analysis.gaps),
+        ...(options.label !== undefined ? { label: options.label } : {}),
+    };
+    const validated = BaselineSnapshotSchema.parse(snapshot);
+    await writeFile(join(dir, filename), JSON.stringify(validated, null, 2), 'utf8');
+    return validated;
+}
+/**
+ * Load a specific baseline snapshot by its `id`.
+ *
+ * @throws If the file does not exist or fails schema validation.
+ */
+export async function loadBaseline(id, options = {}) {
+    const baseDir = options.baseDir ?? defaultBaselineRoot();
+    // id encodes the urlSlug: <urlSlug>__<timestamp>
+    const doubleUnderIndex = id.lastIndexOf('__');
+    if (doubleUnderIndex < 0) {
+        throw new Error(`Invalid baseline id (no __ separator): ${id}`);
+    }
+    const urlSlug = id.slice(0, doubleUnderIndex);
+    const dir = resolveBaselineDir(baseDir, urlSlug);
+    const filepath = join(dir, `${id}.json`);
+    if (!existsSync(filepath)) {
+        throw new Error(`Baseline not found: ${id} (${filepath})`);
+    }
+    const raw = await readFile(filepath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Baseline file is not valid JSON: ${filepath}`);
+    }
+    return BaselineSnapshotSchema.parse(parsed);
+}
+/**
+ * List all saved baselines for the given URL, sorted newest-first.
+ *
+ * Returns an empty array if no baselines exist yet.
+ */
+export async function listBaselines(url, options = {}) {
+    const baseDir = options.baseDir ?? defaultBaselineRoot();
+    const urlSlug = slugifyUrl(url);
+    const dir = resolveBaselineDir(baseDir, urlSlug);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const snapshots = [];
+    for (const entry of entries) {
+        if (extname(entry) !== '.json')
+            continue;
+        const filepath = join(dir, entry);
+        const raw = await readFile(filepath, 'utf8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const result = BaselineSnapshotSchema.safeParse(parsed);
+        if (result.success) {
+            snapshots.push(result.data);
+        }
+    }
+    // Newest first
+    snapshots.sort((a, b) => new Date(b.savedAt).getTime() - new Date(a.savedAt).getTime());
+    return snapshots;
+}
+/**
+ * Delete a specific baseline snapshot by its `id`.
+ *
+ * @throws If the file does not exist.
+ */
+export async function deleteBaseline(id, options = {}) {
+    const baseDir = options.baseDir ?? defaultBaselineRoot();
+    const doubleUnderIndex = id.lastIndexOf('__');
+    if (doubleUnderIndex < 0) {
+        throw new Error(`Invalid baseline id (no __ separator): ${id}`);
+    }
+    const urlSlug = id.slice(0, doubleUnderIndex);
+    const dir = resolveBaselineDir(baseDir, urlSlug);
+    const filepath = join(dir, `${id}.json`);
+    if (!existsSync(filepath)) {
+        throw new Error(`Baseline not found: ${id}`);
+    }
+    await unlink(filepath);
+}
+// ---------------------------------------------------------------------------
+// Delta detection
+// ---------------------------------------------------------------------------
+/**
+ * Stable key used to match gaps across snapshots for delta detection.
+ * Two gaps are "the same problem" when they share path + category.
+ */
+function gapKey(g) {
+    return `${g.path}|||${g.category}`;
+}
+/**
+ * Compare two baseline snapshots and return a structured delta report.
+ *
+ * - `newGaps`: problems present in `current` but not in `prior`.
+ * - `resolvedGaps`: problems present in `prior` but no longer in `current`.
+ * - `severityChanges`: same problem (matching key) with a different severity.
+ */
+export function compareBaselines(prior, current) {
+    const priorMap = new Map();
+    for (const g of prior.gaps) {
+        priorMap.set(gapKey(g), g);
+    }
+    const currentMap = new Map();
+    for (const g of current.gaps) {
+        currentMap.set(gapKey(g), g);
+    }
+    const severityOrder = {
+        critical: 4,
+        high: 3,
+        medium: 2,
+        low: 1,
+    };
+    const newGaps = [];
+    const resolvedGaps = [];
+    const severityChanges = [];
+    // Gaps in current that were not in prior → new
+    for (const [key, g] of currentMap) {
+        if (!priorMap.has(key)) {
+            newGaps.push({ path: g.path, category: g.category, severity: g.severity, reason: g.reason, status: 'new' });
+        }
+        else {
+            const prev = priorMap.get(key);
+            if (prev.severity !== g.severity) {
+                const prevOrd = severityOrder[prev.severity];
+                const currOrd = severityOrder[g.severity];
+                severityChanges.push({
+                    path: g.path,
+                    category: g.category,
+                    severity: g.severity,
+                    reason: g.reason,
+                    status: currOrd > prevOrd ? 'severity-increased' : 'severity-decreased',
+                });
+            }
+        }
+    }
+    // Gaps in prior that are no longer in current → resolved
+    for (const [key, g] of priorMap) {
+        if (!currentMap.has(key)) {
+            resolvedGaps.push({
+                path: g.path,
+                category: g.category,
+                severity: g.severity,
+                reason: g.reason,
+                status: 'resolved',
+            });
+        }
+    }
+    const confidenceDelta = current.releaseConfidence - prior.releaseConfidence;
+    const direction = confidenceDelta > 0 ? 'improved' : confidenceDelta < 0 ? 'regressed' : 'unchanged';
+    const summary = [
+        `Confidence ${direction} (${prior.releaseConfidence} → ${current.releaseConfidence})`,
+        newGaps.length > 0 ? `${newGaps.length} new gap(s)` : '',
+        resolvedGaps.length > 0 ? `${resolvedGaps.length} resolved gap(s)` : '',
+        severityChanges.length > 0 ? `${severityChanges.length} severity change(s)` : '',
+    ]
+        .filter(Boolean)
+        .join(', ');
+    const delta = {
+        fromId: prior.id,
+        toId: current.id,
+        fromSavedAt: prior.savedAt,
+        toSavedAt: current.savedAt,
+        fromReleaseConfidence: prior.releaseConfidence,
+        toReleaseConfidence: current.releaseConfidence,
+        confidenceDelta,
+        newGaps,
+        resolvedGaps,
+        severityChanges,
+        summary,
+    };
+    return BaselineDeltaSchema.parse(delta);
+}