@monoes/monobrowse 1.0.12 → 1.0.13

package/dist/src/report/evidence.js

@@ -0,0 +1,279 @@
+/**
+ * Recorded evidence for a bug report (RIG-11).
+ *
+ * When a run breaches its budget, "LCP was 4.1s" is a number; the frames
+ * either side of the moment it went wrong, lined up against the console and
+ * network entries from the same instant, is a bug report. This module records
+ * the frames and assembles that timeline.
+ *
+ * Size is the hard constraint. A screencast is tens of megabytes and a report
+ * is a single self-contained HTML file, so there are three separate bounds:
+ * the recorder's ring buffer (what we hold in memory), the frame selection
+ * (what we attach), and a byte budget applied over the selection. Nothing
+ * here can produce a 200MB report.
+ *
+ * `startEvidenceRecorder` talks to Chrome; everything below it is pure and
+ * unit-tested against fixture frames.
+ */
+const DEFAULT_MAX_BUFFER_FRAMES = 160;
+const DEFAULT_MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+/**
+ * Halve the temporal resolution of the buffer instead of dropping its head.
+ *
+ * A plain ring buffer keeps the end of the run, which is the wrong half: a
+ * page that throws during load has its evidence at the start. Decimating
+ * keeps coverage of the whole run and merely coarsens it, which degrades the
+ * timeline gracefully however long the run turns out to be.
+ */
+function decimate(frames) {
+    const kept = frames.filter((_, i) => i % 2 === 0);
+    return { kept, dropped: frames.length - kept.length };
+}
+export async function startEvidenceRecorder(client, sessionId, startedAtMs, options = {}) {
+    const maxFrames = options.maxFrames ?? DEFAULT_MAX_BUFFER_FRAMES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+    const recorder = {
+        frames: [],
+        droppedFrames: 0,
+        stop: async () => { },
+    };
+    let bytes = 0;
+    const off = client.on('Page.screencastFrame', (params, sid) => {
+        if (sid !== sessionId)
+            return;
+        const p = params;
+        // Ack first and unconditionally: Chrome stops sending frames until the
+        // previous one is acknowledged, so a failure to ack silently ends the
+        // recording.
+        if (p.sessionId !== undefined) {
+            void client
+                .send('Page.screencastFrameAck', { sessionId: p.sessionId }, sessionId)
+                .catch(() => { });
+        }
+        if (!p.data)
+            return;
+        recorder.frames.push({
+            offsetMs: Math.max(0, Date.now() - startedAtMs),
+            data: p.data,
+            bytes: p.data.length,
+        });
+        bytes += p.data.length;
+        if (recorder.frames.length > maxFrames || bytes > maxBytes) {
+            const { kept, dropped } = decimate(recorder.frames);
+            recorder.frames = kept;
+            recorder.droppedFrames += dropped;
+            bytes = kept.reduce((sum, f) => sum + f.bytes, 0);
+        }
+    });
+    // Idempotent: collect() stops the recorder once the interesting part of the
+    // run is over and again in its `finally`, and Chrome errors on stopping a
+    // screencast that is already stopped.
+    let stopped = false;
+    recorder.stop = async () => {
+        if (stopped)
+            return;
+        stopped = true;
+        off();
+        await client.send('Page.stopScreencast', {}, sessionId).catch(() => { });
+    };
+    try {
+        await client.send('Page.startScreencast', {
+            format: 'jpeg',
+            quality: options.quality ?? 60,
+            everyNthFrame: options.everyNthFrame ?? 2,
+            maxWidth: options.maxWidth ?? 900,
+            maxHeight: options.maxHeight ?? 1600,
+        }, sessionId);
+    }
+    catch (err) {
+        off();
+        throw err;
+    }
+    return recorder;
+}
+const DEFAULT_ATTACH_FRAMES = 12;
+const DEFAULT_ATTACH_BYTES = 6 * 1024 * 1024;
+const DEFAULT_WINDOW_MS = 4000;
+/**
+ * Pick the frames to attach.
+ *
+ * With a focus offset, frames nearest it win — that is the moment being
+ * explained. Without one (a vitals-only breach has no instant), the run is
+ * sampled evenly so the reader still sees it load. The byte budget is applied
+ * last, evicting the least relevant frame first, so the cap is never reached
+ * by truncating the interesting end.
+ */
+export function selectFrames(frames, focusOffsetMs, options = {}) {
+    const maxFrames = Math.max(1, options.maxFrames ?? DEFAULT_ATTACH_FRAMES);
+    const maxBytes = options.maxBytes ?? DEFAULT_ATTACH_BYTES;
+    const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+    if (!frames.length)
+        return { frames: [], dropped: 0 };
+    let ranked;
+    if (focusOffsetMs === null) {
+        if (frames.length <= maxFrames) {
+            ranked = [...frames];
+        }
+        else {
+            const step = (frames.length - 1) / (maxFrames - 1 || 1);
+            const picked = new Set();
+            for (let i = 0; i < maxFrames; i++)
+                picked.add(Math.round(i * step));
+            ranked = [...picked].sort((a, b) => a - b).map((i) => frames[i]);
+        }
+    }
+    else {
+        const distance = (f) => Math.abs(f.offsetMs - focusOffsetMs);
+        const inWindow = frames.filter((f) => distance(f) <= windowMs);
+        // Fall back to the nearest frames overall rather than attaching none: a
+        // failure whose frames all fell outside the window still deserves context.
+        const pool = inWindow.length ? inWindow : [...frames];
+        ranked = [...pool].sort((a, b) => distance(a) - distance(b)).slice(0, maxFrames);
+    }
+    let dropped = frames.length - ranked.length;
+    let total = ranked.reduce((sum, f) => sum + f.bytes, 0);
+    if (total > maxBytes) {
+        const order = focusOffsetMs === null
+            ? [...ranked]
+            : [...ranked].sort((a, b) => Math.abs(a.offsetMs - focusOffsetMs) - Math.abs(b.offsetMs - focusOffsetMs));
+        const keep = new Set();
+        let used = 0;
+        for (const frame of order) {
+            if (used + frame.bytes > maxBytes)
+                continue;
+            keep.add(frame);
+            used += frame.bytes;
+        }
+        dropped += ranked.length - keep.size;
+        ranked = ranked.filter((f) => keep.has(f));
+        total = used;
+    }
+    return { frames: ranked.sort((a, b) => a.offsetMs - b.offsetMs), dropped };
+}
+const DEFAULT_MAX_EVENTS = 60;
+function truncate(text, max = 200) {
+    const flat = String(text ?? '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * The instant the run went wrong: the earliest hard error we have a clock
+ * reading for. Returns null when the breach has no moment attached — a slow
+ * LCP is a property of the whole load, not an event.
+ */
+export function findFocusOffset(input) {
+    const candidates = [];
+    for (const e of input.console) {
+        if (e.type === 'error' && Number.isFinite(e.timestamp)) {
+            candidates.push(e.timestamp - input.startedAtMs);
+        }
+    }
+    for (const e of input.pageErrors) {
+        if (Number.isFinite(e.timestamp))
+            candidates.push(e.timestamp - input.startedAtMs);
+    }
+    for (const r of input.requests) {
+        if (r.failed && r.startedAtMs !== undefined)
+            candidates.push(r.startedAtMs - input.startedAtMs);
+    }
+    const usable = candidates.filter((v) => Number.isFinite(v) && v >= 0);
+    return usable.length ? Math.min(...usable) : null;
+}
+export function buildEvidence(input) {
+    const notes = [];
+    const focusOffsetMs = findFocusOffset(input);
+    const picked = selectFrames(input.frames, focusOffsetMs, input.select);
+    const frames = picked.frames.map((f) => ({
+        offsetMs: f.offsetMs,
+        dataUrl: `data:image/jpeg;base64,${f.data}`,
+        bytes: f.bytes,
+    }));
+    const events = [];
+    for (const [i, frame] of picked.frames.entries()) {
+        events.push({
+            offsetMs: frame.offsetMs,
+            kind: 'frame',
+            label: 'frame',
+            severity: 'info',
+            frameIndex: i,
+        });
+    }
+    for (const e of input.console) {
+        if (e.type !== 'error' && e.type !== 'warn' && e.type !== 'warning')
+            continue;
+        events.push({
+            offsetMs: e.timestamp - input.startedAtMs,
+            kind: 'console',
+            label: `console.${e.type}`,
+            detail: truncate(e.text),
+            severity: e.type === 'error' ? 'error' : 'warning',
+        });
+    }
+    for (const e of input.pageErrors) {
+        events.push({
+            offsetMs: e.timestamp - input.startedAtMs,
+            kind: 'pageerror',
+            label: 'uncaught exception',
+            detail: truncate(e.text),
+            severity: 'error',
+        });
+    }
+    for (const r of input.requests) {
+        if (!r.failed)
+            continue;
+        if (r.startedAtMs === undefined)
+            continue;
+        events.push({
+            offsetMs: r.startedAtMs - input.startedAtMs,
+            kind: 'request',
+            label: `${r.status ?? r.errorText ?? 'no response'} ${r.method}`,
+            detail: truncate(r.url),
+            severity: 'error',
+        });
+    }
+    if (focusOffsetMs !== null) {
+        events.push({
+            offsetMs: focusOffsetMs,
+            kind: 'marker',
+            label: 'first failure',
+            detail: input.failures.map((f) => `${f.budget} ${f.actual}`).join(', ') || undefined,
+            severity: 'error',
+        });
+    }
+    // Trim the non-frame rows worst-first, so a page with 400 console warnings
+    // still shows its one uncaught exception.
+    const frameRows = events.filter((e) => e.kind === 'frame');
+    let otherRows = events.filter((e) => e.kind !== 'frame');
+    const maxEvents = input.maxEvents ?? DEFAULT_MAX_EVENTS;
+    if (otherRows.length > maxEvents) {
+        const weight = { error: 0, warning: 1, info: 2 };
+        const kept = [...otherRows]
+            .sort((a, b) => weight[a.severity] - weight[b.severity] ||
+            Math.abs(a.offsetMs - (focusOffsetMs ?? 0)) - Math.abs(b.offsetMs - (focusOffsetMs ?? 0)))
+            .slice(0, maxEvents);
+        notes.push(`Timeline trimmed to the ${maxEvents} most relevant of ${otherRows.length} events.`);
+        otherRows = kept;
+    }
+    const timeline = [...frameRows, ...otherRows].sort((a, b) => a.offsetMs - b.offsetMs || a.kind.localeCompare(b.kind));
+    const droppedFrames = (input.bufferDropped ?? 0) + picked.dropped;
+    if (droppedFrames > 0) {
+        notes.push(`${droppedFrames} recorded frame(s) not attached — the report keeps the ${frames.length} nearest the failure to stay inside its size budget.`);
+    }
+    if (!frames.length && input.frames.length === 0) {
+        notes.push('No screencast frames were captured for this run.');
+    }
+    if (focusOffsetMs === null && input.failures.length) {
+        notes.push('No single moment of failure could be located — the breach is a load-wide metric, so the frames sample the whole run instead.');
+    }
+    return {
+        reason: input.reason,
+        focusOffsetMs,
+        frames,
+        timeline,
+        droppedFrames,
+        totalBytes: frames.reduce((sum, f) => sum + f.bytes, 0),
+        notes,
+    };
+}
+//# sourceMappingURL=evidence.js.map

package/dist/src/report/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../../src/report/evidence.ts"],"names":[],"mappings":"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"}

package/dist/src/report/flake.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Flake detection across repeated runs of the same URL (RIG-14).
+ *
+ * The failure mode this exists to stop: a check that fails two runs in five
+ * gets re-run until it is green and shipped as "passing". So the aggregate
+ * verdict has a third value — `flaky` — and a check that both passed and
+ * failed within the window can only produce that verdict. It is never
+ * rounded down to `pass`.
+ *
+ * The other half is honesty about what N runs can prove. `confidenceNote`
+ * states the failure rate the window actually rules out, because "5 runs
+ * passed" and "this is reliable" are very different claims.
+ *
+ * Pure: the tests feed arrays of Reports.
+ */
+import type { Budget, Report } from './types.js';
+export type FlakeVerdict = 'pass' | 'fail' | 'flaky';
+export interface FlakeCheck {
+    key: keyof Budget;
+    label: string;
+    runs: number;
+    passed: number;
+    failed: number;
+    /** Fraction of runs that failed, 0..1. */
+    flakeRate: number;
+    /** True when the check did the same thing every run. */
+    stable: boolean;
+    /** The measured value for each run, in run order. */
+    actuals: string[];
+}
+export interface FlakeSignal {
+    kind: 'console' | 'pageError' | 'request' | 'a11y';
+    signature: string;
+    /** Runs this signal appeared in. */
+    runs: number;
+    total: number;
+}
+export interface FlakeMetric {
+    key: string;
+    label: string;
+    unit: 'ms' | 'score';
+    /** Runs that reported the metric at all. */
+    measured: number;
+    total: number;
+    min: number;
+    max: number;
+    median: number;
+    spread: number;
+    /** Spread as a fraction of the median. */
+    spreadRatio: number;
+    unstable: boolean;
+}
+export interface FlakeReport {
+    runs: number;
+    verdict: FlakeVerdict;
+    checks: FlakeCheck[];
+    /** Errors and failed requests that did not appear in every run. */
+    signals: FlakeSignal[];
+    metrics: FlakeMetric[];
+    confidence: 'low' | 'moderate' | 'high';
+    confidenceNote: string;
+    headline: string;
+}
+/**
+ * Normalise a message so the same error reported with a different id, line or
+ * timestamp still counts as the same signal. Without this, a flaky error
+ * carrying a request id looks like N distinct one-off errors.
+ */
+export declare function signalSignature(text: string): string;
+/**
+ * What a window of all-passing runs actually rules out.
+ *
+ * If a check truly fails with probability p, N independent passing runs have
+ * probability (1-p)^N. Solving (1-p)^N = 0.05 gives the largest failure rate
+ * consistent with what we saw at 95% confidence — which is a far less
+ * flattering number than "N runs passed" sounds.
+ */
+export declare function ruledOutFailureRate(runs: number): number;
+/**
+ * Aggregate N runs of the same URL.
+ *
+ * `budget` comes from the runs themselves (they all share one), and only
+ * enforced keys become checks: an unenforced budget cannot be flaky.
+ */
+export declare function analyzeFlake(reports: Report[]): FlakeReport;
+/** One line for a CI log / agent transcript. */
+export declare function summarizeFlake(flake: FlakeReport): string;
+//# sourceMappingURL=flake.d.ts.map

package/dist/src/report/flake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flake.d.ts","sourceRoot":"","sources":["../../../src/report/flake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAErD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,mEAAmE;IACnE,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,UAAU,EAAE,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAwCD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUpD;AA0ED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGxD;AAwBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,WAAW,CA0D3D;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEzD"}

package/dist/src/report/flake.js

@@ -0,0 +1,232 @@
+/**
+ * Flake detection across repeated runs of the same URL (RIG-14).
+ *
+ * The failure mode this exists to stop: a check that fails two runs in five
+ * gets re-run until it is green and shipped as "passing". So the aggregate
+ * verdict has a third value — `flaky` — and a check that both passed and
+ * failed within the window can only produce that verdict. It is never
+ * rounded down to `pass`.
+ *
+ * The other half is honesty about what N runs can prove. `confidenceNote`
+ * states the failure rate the window actually rules out, because "5 runs
+ * passed" and "this is reliable" are very different claims.
+ *
+ * Pure: the tests feed arrays of Reports.
+ */
+import { budgetLabel } from './budget.js';
+/** Spread beyond this fraction of the median is worth flagging as unstable. */
+const UNSTABLE_SPREAD_RATIO = 0.3;
+const COUNT_READERS = {
+    maxConsoleErrors: (r) => r.counts.consoleErrors,
+    maxPageErrors: (r) => r.counts.pageErrors,
+    maxFailedRequests: (r) => r.counts.failedRequests,
+    maxA11yErrors: (r) => r.counts.a11yErrors,
+};
+const METRIC_READERS = {
+    lcpMs: (r) => r.vitals.lcp,
+    clsScore: (r) => r.vitals.cls,
+    inpMs: (r) => r.vitals.inp,
+    fcpMs: (r) => r.vitals.fcp,
+    ttfbMs: (r) => r.vitals.ttfb,
+};
+function actualFor(key, report) {
+    const count = COUNT_READERS[key];
+    if (count)
+        return String(count(report));
+    const metric = METRIC_READERS[key];
+    const raw = metric?.(report);
+    if (raw === undefined || !Number.isFinite(raw))
+        return 'not measured';
+    return key === 'clsScore' ? raw.toFixed(3) : `${Math.round(raw)}ms`;
+}
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function truncate(text, max = 140) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Normalise a message so the same error reported with a different id, line or
+ * timestamp still counts as the same signal. Without this, a flaky error
+ * carrying a request id looks like N distinct one-off errors.
+ */
+export function signalSignature(text) {
+    return truncate(text
+        .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, '<uuid>')
+        .replace(/\b0x[0-9a-f]+\b/gi, '<hex>')
+        // 5 digits and up, not 3: request ids, timestamps and byte offsets are
+        // long, while an HTTP status code is part of what makes two errors
+        // different and must survive normalisation.
+        .replace(/\b\d{5,}\b/g, '<n>'));
+}
+function collectSignals(reports) {
+    const total = reports.length;
+    const seen = new Map();
+    const add = (kind, signature, runIndex) => {
+        const id = `${kind}\n${signature}`;
+        let entry = seen.get(id);
+        if (!entry) {
+            entry = { kind, signature, runs: new Set() };
+            seen.set(id, entry);
+        }
+        entry.runs.add(runIndex);
+    };
+    reports.forEach((report, i) => {
+        for (const e of report.console) {
+            if (e.type === 'error')
+                add('console', signalSignature(e.text), i);
+        }
+        for (const e of report.pageErrors)
+            add('pageError', signalSignature(e.text), i);
+        for (const r of report.requests) {
+            if (r.failed)
+                add('request', `${r.status ?? r.errorText ?? 'no response'} ${r.url}`, i);
+        }
+        for (const f of report.a11y) {
+            if (f.impact === 'error')
+                add('a11y', `${f.rule} at ${f.locator}`, i);
+        }
+    });
+    return [...seen.values()]
+        .filter((e) => e.runs.size < total) // present in every run is a bug, not a flake
+        .map((e) => ({ kind: e.kind, signature: e.signature, runs: e.runs.size, total }))
+        .sort((a, b) => b.runs - a.runs || a.signature.localeCompare(b.signature));
+}
+function collectMetrics(reports) {
+    const defs = [
+        ['lcp', 'LCP', 'ms', (r) => r.vitals.lcp],
+        ['fcp', 'FCP', 'ms', (r) => r.vitals.fcp],
+        ['cls', 'CLS', 'score', (r) => r.vitals.cls],
+        ['inp', 'INP', 'ms', (r) => r.vitals.inp],
+        ['ttfb', 'TTFB', 'ms', (r) => r.vitals.ttfb],
+    ];
+    const out = [];
+    for (const [key, label, unit, read] of defs) {
+        const values = reports
+            .map(read)
+            .filter((v) => typeof v === 'number' && Number.isFinite(v));
+        if (!values.length)
+            continue;
+        const min = Math.min(...values);
+        const max = Math.max(...values);
+        const mid = median(values);
+        const spread = max - min;
+        const spreadRatio = mid > 0 ? spread / mid : spread > 0 ? Infinity : 0;
+        out.push({
+            key,
+            label,
+            unit,
+            measured: values.length,
+            total: reports.length,
+            min,
+            max,
+            median: mid,
+            spread,
+            spreadRatio,
+            unstable: values.length > 1 && spreadRatio > UNSTABLE_SPREAD_RATIO,
+        });
+    }
+    return out;
+}
+/**
+ * What a window of all-passing runs actually rules out.
+ *
+ * If a check truly fails with probability p, N independent passing runs have
+ * probability (1-p)^N. Solving (1-p)^N = 0.05 gives the largest failure rate
+ * consistent with what we saw at 95% confidence — which is a far less
+ * flattering number than "N runs passed" sounds.
+ */
+export function ruledOutFailureRate(runs) {
+    if (runs <= 0)
+        return 1;
+    return 1 - 0.05 ** (1 / runs);
+}
+function confidenceFor(runs, verdict) {
+    if (verdict === 'flaky') {
+        return {
+            confidence: 'high',
+            note: `Flakiness is observed, not inferred: both outcomes occurred within ${runs} runs.`,
+        };
+    }
+    const bound = Math.round(ruledOutFailureRate(runs) * 100);
+    const level = runs >= 5 ? 'high' : runs >= 3 ? 'moderate' : 'low';
+    const outcome = verdict === 'pass' ? 'passed' : 'failed';
+    return {
+        confidence: level,
+        note: `${runs} run${runs === 1 ? '' : 's'}, all ${outcome} consistently. That only rules out ` +
+            `intermittent behaviour more frequent than about 1 run in ${Math.max(2, Math.round(100 / bound))} ` +
+            `(${bound}%) at 95% confidence — re-run with a larger --repeat to tighten it.`,
+    };
+}
+/**
+ * Aggregate N runs of the same URL.
+ *
+ * `budget` comes from the runs themselves (they all share one), and only
+ * enforced keys become checks: an unenforced budget cannot be flaky.
+ */
+export function analyzeFlake(reports) {
+    if (!reports.length)
+        throw new Error('analyzeFlake: needs at least one run');
+    const runs = reports.length;
+    const budget = reports[0].budget;
+    const checks = [];
+    for (const key of Object.keys(budget)) {
+        if (budget[key] === null)
+            continue;
+        const failed = reports.filter((r) => r.failures.some((f) => f.budget === key)).length;
+        checks.push({
+            key,
+            label: budgetLabel(key),
+            runs,
+            passed: runs - failed,
+            failed,
+            flakeRate: failed / runs,
+            stable: failed === 0 || failed === runs,
+            actuals: reports.map((r) => actualFor(key, r)),
+        });
+    }
+    const unstableChecks = checks.filter((c) => !c.stable);
+    const alwaysFailing = checks.filter((c) => c.failed === runs);
+    const verdict = unstableChecks.length
+        ? 'flaky'
+        : alwaysFailing.length
+            ? 'fail'
+            : 'pass';
+    const signals = collectSignals(reports);
+    const metrics = collectMetrics(reports);
+    const { confidence, note } = confidenceFor(runs, verdict);
+    let headline;
+    if (verdict === 'flaky') {
+        const worst = [...unstableChecks].sort((a, b) => b.failed - a.failed)[0];
+        headline =
+            `FLAKY — ${unstableChecks.length} check${unstableChecks.length === 1 ? '' : 's'} ` +
+                `changed outcome across ${runs} runs (e.g. ${worst.label} failed ${worst.failed} of ${runs}).`;
+    }
+    else if (verdict === 'fail') {
+        headline = `FAIL — ${alwaysFailing.length} check(s) failed in all ${runs} runs.`;
+    }
+    else {
+        const unstableMetrics = metrics.filter((m) => m.unstable).length;
+        headline =
+            `PASS — every check held across all ${runs} runs` +
+                (unstableMetrics ? `, though ${unstableMetrics} metric(s) varied widely.` : '.');
+    }
+    return {
+        runs,
+        verdict,
+        checks,
+        signals,
+        metrics,
+        confidence,
+        confidenceNote: note,
+        headline,
+    };
+}
+/** One line for a CI log / agent transcript. */
+export function summarizeFlake(flake) {
+    return `${flake.headline} Confidence: ${flake.confidence}.`;
+}
+//# sourceMappingURL=flake.js.map

package/dist/src/report/flake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flake.js","sourceRoot":"","sources":["../../../src/report/flake.ts"],"names":[],"mappings":"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"}