nfunc-mcp 0.3.0 → 0.5.0

package/dist/mappers/psiAggregator.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Cross-run arithmetic.
+ *
+ * This module owns every number that describes the audit as a whole, because
+ * that is precisely where reading JSON by hand goes wrong. The manual Five
+ * Below report got "TBT fails on 22/22 pages" right and the direction of the
+ * CrUX CLS disagreement backwards, in the same document — the first is a count
+ * and the second is a comparison, and a human doing 26 files will eventually
+ * miss one. Everything here is computed so the report can quote rather than
+ * derive.
+ *
+ * It also owns the two redundancy rules, because both need the page set in
+ * view. A single-URL audit should still report every failing metric; the
+ * repetition only exists across a set.
+ */
+import type { Finding } from "../types.js";
+import type { LabMetrics, ParsedCrux, WebVital } from "../utils/psiParser.js";
+import type { MetricComparison } from "./labFieldComparator.js";
+export interface RunResult {
+    template: string;
+    label: string;
+    url: string;
+    strategy: string;
+    runs: number;
+    scores: Record<string, number>;
+    lab: LabMetrics;
+    field: ParsedCrux | null;
+    comparisons: MetricComparison[];
+    findings: Finding[];
+    report_file: string;
+}
+/**
+ * Rule 2 — component suppression.
+ *
+ * FCP is a component of LCP: if the largest element paints late, the first one
+ * usually did too. Across the Five Below batch the two co-occurred on 17 of 25
+ * runs and FCP never once reached P1, so an FCP finding alongside an LCP
+ * finding is two tickets describing one defect. The FCP measurement is kept as
+ * evidence on the LCP finding rather than discarded.
+ *
+ * TTFB is deliberately *not* treated this way. It fired on one run out of 25,
+ * which is the signature of a metric carrying independent information.
+ */
+export declare function suppressComponentFindings(findings: Finding[]): Finding[];
+export interface SystemicResult {
+    findings: Finding[];
+    /** Vitals whose per-page findings this replaces. */
+    collapsedVitals: WebVital[];
+}
+/**
+ * Rule 1 — systemic collapse.
+ *
+ * A vital rated below "good" on 80%+ of runs is describing the site, not any
+ * one page. INP failed on 25 of 25 Five Below runs with a 2.1x spread and a
+ * 316 ms median: twenty-five findings that each say "fix this page" when the
+ * true statement is "this site's interaction handling is uniformly mediocre".
+ *
+ * The threshold is deliberately well above a simple majority — a vital failing
+ * on half the pages is discriminating between them, and that is information
+ * worth keeping per page.
+ *
+ * Priority is the worst observed, not an average: a vital that is poor
+ * everywhere is not less urgent for being ubiquitous.
+ */
+export declare function collapseSystemicFindings(runs: RunResult[]): SystemicResult;
+export interface PsiAggregate {
+    run_count: number;
+    pages: number;
+    captured_at: string;
+    by_strategy: Record<string, {
+        performance: {
+            mean: number;
+            min: number;
+            max: number;
+        };
+    }>;
+    by_template: Array<{
+        template: string;
+        label: string;
+        sampled: number;
+        performance_mean: Record<string, number>;
+        worst_url: string;
+    }>;
+    /**
+     * Lab metrics failing across the audited runs. Renamed from
+     * `universal_failures`, which was a lie on any site where a metric failed on
+     * some pages but not others — it reported a 25% failure rate under a name the
+     * report spec told the agent to treat as a headline finding. `universal` now
+     * says explicitly whether the "fails on essentially every page" claim holds.
+     */
+    lab_metric_failures: Array<{
+        metric: string;
+        label: string;
+        failing: number;
+        of: number;
+        pct: number;
+        universal: boolean;
+        range: string;
+        threshold: string;
+    }>;
+    cwv_verdicts: {
+        pass: number;
+        needs_improvement: number;
+        fail: number;
+    };
+    lab_vs_field_summary: {
+        worse_in_field: Array<{
+            metric: string;
+            runs: number;
+        }>;
+        worse_in_lab: Array<{
+            metric: string;
+            runs: number;
+        }>;
+        confirmed: Array<{
+            metric: string;
+            runs: number;
+        }>;
+        no_field_data: number;
+    };
+    outliers: Array<{
+        url: string;
+        strategy: string;
+        metric: string;
+        value: string;
+        vs_median_multiple: number;
+        confidence: string;
+    }>;
+}
+export declare function aggregate(runs: RunResult[]): PsiAggregate;

package/dist/mappers/psiAggregator.js

@@ -0,0 +1,293 @@
+/**
+ * Cross-run arithmetic.
+ *
+ * This module owns every number that describes the audit as a whole, because
+ * that is precisely where reading JSON by hand goes wrong. The manual Five
+ * Below report got "TBT fails on 22/22 pages" right and the direction of the
+ * CrUX CLS disagreement backwards, in the same document — the first is a count
+ * and the second is a comparison, and a human doing 26 files will eventually
+ * miss one. Everything here is computed so the report can quote rather than
+ * derive.
+ *
+ * It also owns the two redundancy rules, because both need the page set in
+ * view. A single-URL audit should still report every failing metric; the
+ * repetition only exists across a set.
+ */
+import { classifyVital, formatVitalValue, vitalLabel } from "./webVitalsMapper.js";
+/** A vital failing on at least this share of runs is a candidate for collapse. */
+const SYSTEMIC_THRESHOLD = 0.8;
+/**
+ * ...but only if it also varies little between pages.
+ *
+ * Ubiquity alone is not enough, and the first implementation of this rule got
+ * it wrong: it collapsed CLS, which fails on 25 of 25 Five Below runs but
+ * ranges 0.18 to 0.85 — a 4.7x spread that is the single most page-specific
+ * signal in the dataset. Collapsing it would have deleted the finding the
+ * whole tool exists to surface.
+ *
+ * A shared-code characteristic looks the same everywhere: INP fails on every
+ * page within a 2.1x band. A per-page defect that happens to be widespread
+ * does not. So collapse requires both — fails nearly everywhere *and* barely
+ * moves between pages.
+ */
+const SYSTEMIC_MAX_SPREAD = 2.5;
+/** Lab-only metrics with no field counterpart, needed for the universal-failure counts. */
+const LAB_THRESHOLDS = {
+    tbtMs: { label: "Total Blocking Time", good: 200, unit: "ms" },
+};
+const PRIORITY_RANK = { P1: 0, P2: 1, P3: 2 };
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function mean(values) {
+    return values.length === 0 ? 0 : Math.round(values.reduce((a, b) => a + b, 0) / values.length);
+}
+/**
+ * Rule 2 — component suppression.
+ *
+ * FCP is a component of LCP: if the largest element paints late, the first one
+ * usually did too. Across the Five Below batch the two co-occurred on 17 of 25
+ * runs and FCP never once reached P1, so an FCP finding alongside an LCP
+ * finding is two tickets describing one defect. The FCP measurement is kept as
+ * evidence on the LCP finding rather than discarded.
+ *
+ * TTFB is deliberately *not* treated this way. It fired on one run out of 25,
+ * which is the signature of a metric carrying independent information.
+ */
+export function suppressComponentFindings(findings) {
+    const lcp = findings.find((f) => f.evidence.audit_id === "crux.lcp");
+    const fcp = findings.find((f) => f.evidence.audit_id === "crux.fcp");
+    if (!lcp || !fcp)
+        return findings;
+    lcp.evidence = {
+        ...lcp.evidence,
+        supporting_fcp: fcp.evidence.value,
+        note: "First Contentful Paint is also below target; it is a component of this metric, not a separate defect.",
+    };
+    return findings.filter((f) => f !== fcp);
+}
+/**
+ * Rule 1 — systemic collapse.
+ *
+ * A vital rated below "good" on 80%+ of runs is describing the site, not any
+ * one page. INP failed on 25 of 25 Five Below runs with a 2.1x spread and a
+ * 316 ms median: twenty-five findings that each say "fix this page" when the
+ * true statement is "this site's interaction handling is uniformly mediocre".
+ *
+ * The threshold is deliberately well above a simple majority — a vital failing
+ * on half the pages is discriminating between them, and that is information
+ * worth keeping per page.
+ *
+ * Priority is the worst observed, not an average: a vital that is poor
+ * everywhere is not less urgent for being ubiquitous.
+ */
+export function collapseSystemicFindings(runs) {
+    const findings = [];
+    const collapsedVitals = [];
+    if (runs.length < 3)
+        return { findings, collapsedVitals };
+    const vitals = ["lcp", "inp", "cls", "fcp", "ttfb"];
+    for (const vital of vitals) {
+        // Only URL-level measurements can support a site-wide conclusion.
+        //
+        // Origin-level CrUX is *the same number* repeated for every page that falls
+        // back to it, so both tests below are guaranteed to pass on it: the failure
+        // rate is 100% and the spread is exactly 1.0x. That manufactured a
+        // "fails everywhere and varies little between pages" finding from what was
+        // literally one measurement copied across three runs. The spread gate is
+        // only meaningful over independent per-page data.
+        const measured = runs.filter((r) => r.field?.metrics[vital]?.source === "url");
+        if (measured.length < 3)
+            continue;
+        // Count runs that still carry a finding for this vital, not runs whose raw
+        // metric is below target. The two rules have to compose: FCP is folded into
+        // LCP by component suppression, and counting raw metrics resurrected it as
+        // a site-wide finding that per-page reporting had deliberately dropped.
+        const failing = measured.filter((r) => r.findings.some((f) => f.evidence.audit_id === `crux.${vital}`));
+        if (failing.length / measured.length < SYSTEMIC_THRESHOLD)
+            continue;
+        const values = failing.map((r) => r.field?.metrics[vital]?.p75 ?? 0);
+        // Spread gate. Guard against a zero floor, which would make any spread
+        // infinite and suppress the collapse for the wrong reason.
+        const low = Math.min(...values);
+        const high = Math.max(...values);
+        if (low > 0 && high / low > SYSTEMIC_MAX_SPREAD)
+            continue;
+        const worst = failing
+            .flatMap((r) => r.findings.filter((f) => f.evidence.audit_id === `crux.${vital}`))
+            .reduce((acc, f) => (PRIORITY_RANK[f.priority] < PRIORITY_RANK[acc] ? f.priority : acc), "P3");
+        const med = median(values);
+        const min = low;
+        const max = high;
+        collapsedVitals.push(vital);
+        findings.push({
+            priority: worst,
+            title: `${vitalLabel(vital)} is below target site-wide (${failing.length}/${measured.length} runs)`,
+            description: `Real users are below Google's ${vitalLabel(vital)} target on ` +
+                `${failing.length} of ${measured.length} audited page/device runs, with a median of ` +
+                `${formatVitalValue(vital, med)} and a range of ${formatVitalValue(vital, min)} to ` +
+                `${formatVitalValue(vital, max)}. Because it fails almost everywhere and varies little ` +
+                `between pages, this is a characteristic of the site's shared code rather than a defect ` +
+                `on any one template — fixing individual pages will not move it. Investigate the common ` +
+                `layer: the shared bundle, the third-party tags loaded on every page, or the base template.`,
+            evidence: {
+                audit_id: `crux.${vital}.systemic`,
+                value: formatVitalValue(vital, med),
+                failing_runs: failing.length,
+                total_runs: measured.length,
+                range: `${formatVitalValue(vital, min)}–${formatVitalValue(vital, max)}`,
+            },
+        });
+    }
+    return { findings, collapsedVitals };
+}
+/** Core Web Vitals verdict per run, field-first, matching the manual report's tiers. */
+function cwvVerdict(run) {
+    const core = ["lcp", "inp", "cls"];
+    let failing = 0;
+    for (const vital of core) {
+        const fieldMetric = run.field?.metrics[vital];
+        if (fieldMetric) {
+            if (classifyVital(vital, fieldMetric.p75) !== "good")
+                failing++;
+            continue;
+        }
+        // INP has no lab fallback, so a run with no field INP is scored on what exists.
+        const labValue = vital === "lcp" ? run.lab.lcpMs : vital === "cls" ? run.lab.cls : null;
+        if (labValue !== null && classifyVital(vital, labValue) !== "good")
+            failing++;
+    }
+    if (failing === 0)
+        return "pass";
+    return failing === 1 ? "needs_improvement" : "fail";
+}
+export function aggregate(runs) {
+    const strategies = [...new Set(runs.map((r) => r.strategy))];
+    const by_strategy = {};
+    for (const strategy of strategies) {
+        const scores = runs
+            .filter((r) => r.strategy === strategy)
+            .map((r) => r.scores.performance)
+            .filter((n) => typeof n === "number");
+        if (scores.length === 0)
+            continue;
+        by_strategy[strategy] = {
+            performance: { mean: mean(scores), min: Math.min(...scores), max: Math.max(...scores) },
+        };
+    }
+    const templateIds = [...new Set(runs.map((r) => r.template))];
+    const by_template = templateIds.map((template) => {
+        const group = runs.filter((r) => r.template === template);
+        const performance_mean = {};
+        for (const strategy of strategies) {
+            const scores = group
+                .filter((r) => r.strategy === strategy)
+                .map((r) => r.scores.performance)
+                .filter((n) => typeof n === "number");
+            if (scores.length > 0)
+                performance_mean[strategy] = mean(scores);
+        }
+        const worst = [...group].sort((a, b) => (a.scores.performance ?? 100) - (b.scores.performance ?? 100))[0];
+        return {
+            template,
+            label: group[0].label,
+            sampled: new Set(group.map((r) => r.url)).size,
+            performance_mean,
+            worst_url: worst?.url ?? "",
+        };
+    });
+    // Lab metrics failing across the runs. At 100% this is the "22/22 fail TBT"
+    // line — the strongest sentence in the manual report, and the one most likely
+    // to be miscounted by hand. Below 80% it is not a headline; `universal` says
+    // which case a reader is looking at.
+    const lab_metric_failures = [];
+    for (const [key, spec] of Object.entries(LAB_THRESHOLDS)) {
+        const values = runs
+            .map((r) => r.lab[key])
+            .filter((v) => typeof v === "number");
+        if (values.length === 0)
+            continue;
+        const failing = values.filter((v) => v > spec.good);
+        if (failing.length === 0)
+            continue;
+        const pct = Math.round((failing.length / values.length) * 100);
+        lab_metric_failures.push({
+            metric: key,
+            label: spec.label,
+            failing: failing.length,
+            of: values.length,
+            pct,
+            universal: pct >= 80,
+            range: `${Math.round(Math.min(...failing))} ms–${Math.round(Math.max(...failing))} ms`,
+            threshold: `${spec.good} ms`,
+        });
+    }
+    const cwv_verdicts = { pass: 0, needs_improvement: 0, fail: 0 };
+    for (const run of runs)
+        cwv_verdicts[cwvVerdict(run)]++;
+    const tally = (verdict) => {
+        const counts = new Map();
+        for (const run of runs) {
+            for (const c of run.comparisons) {
+                if (c.verdict !== verdict)
+                    continue;
+                counts.set(c.metric, (counts.get(c.metric) ?? 0) + 1);
+            }
+        }
+        return [...counts.entries()]
+            .map(([metric, n]) => ({ metric, runs: n }))
+            .sort((a, b) => b.runs - a.runs);
+    };
+    // Outliers: a value far above the median for its own strategy. With
+    // runs_per_url = 1 there is nothing to check it against, so it is reported
+    // as unconfirmed rather than asserted — the manual report had to make this
+    // caveat in prose for its 9.97 s TBT reading.
+    const outliers = [];
+    for (const strategy of strategies) {
+        const group = runs.filter((r) => r.strategy === strategy);
+        for (const key of Object.keys(LAB_THRESHOLDS)) {
+            const values = group
+                .map((r) => r.lab[key])
+                .filter((v) => typeof v === "number");
+            if (values.length < 4)
+                continue;
+            const med = median(values);
+            if (med <= 0)
+                continue;
+            for (const run of group) {
+                const value = run.lab[key];
+                if (typeof value !== "number" || value / med < 3)
+                    continue;
+                outliers.push({
+                    url: run.url,
+                    strategy,
+                    metric: String(key),
+                    value: `${Math.round(value)} ms`,
+                    vs_median_multiple: Number((value / med).toFixed(1)),
+                    confidence: run.runs > 1 ? `median_of_${run.runs}` : "unconfirmed_single_run",
+                });
+            }
+        }
+    }
+    return {
+        run_count: runs.length,
+        pages: new Set(runs.map((r) => r.url)).size,
+        captured_at: new Date().toISOString(),
+        by_strategy,
+        by_template,
+        lab_metric_failures,
+        cwv_verdicts,
+        lab_vs_field_summary: {
+            worse_in_field: tally("worse_in_field"),
+            worse_in_lab: tally("worse_in_lab"),
+            confirmed: tally("confirmed"),
+            no_field_data: runs.filter((r) => !r.field).length,
+        },
+        outliers,
+    };
+}
+//# sourceMappingURL=psiAggregator.js.map

package/dist/mappers/psiAggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"psiAggregator.js","sourceRoot":"","sources":["../../src/mappers/psiAggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAiBnF,kFAAkF;AAClF,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,2FAA2F;AAC3F,MAAM,cAAc,GAA0E;IAC5F,KAAK,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE;CAC/D,CAAC;AAEF,MAAM,aAAa,GAA6B,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AAExE,SAAS,MAAM,CAAC,MAAgB;IAC9B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACrF,CAAC;AAED,SAAS,IAAI,CAAC,MAAgB;IAC5B,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;AACjG,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAmB;IAC3D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,KAAK,UAAU,CAAC,CAAC;IACrE,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAElC,GAAG,CAAC,QAAQ,GAAG;QACb,GAAG,GAAG,CAAC,QAAQ;QACf,cAAc,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK;QAClC,IAAI,EAAE,uGAAuG;KAC9G,CAAC;IACF,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;AAC3C,CAAC;AAQD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAiB;IACxD,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,eAAe,GAAe,EAAE,CAAC;IACvC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAE1D,MAAM,MAAM,GAAe,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAEhE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,kEAAkE;QAClE,EAAE;QACF,4EAA4E;QAC5E,4EAA4E;QAC5E,mEAAmE;QACnE,2EAA2E;QAC3E,yEAAyE;QACzE,kDAAkD;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC;QAC/E,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QAElC,2EAA2E;QAC3E,4EAA4E;QAC5E,2EAA2E;QAC3E,wEAAwE;QACxE,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACpC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,KAAK,QAAQ,KAAK,EAAE,CAAC,CAChE,CAAC;QACF,IAAI,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,kBAAkB;YAAE,SAAS;QAEpE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QAErE,uEAAuE;QACvE,2DAA2D;QAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QACjC,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,GAAG,GAAG,mBAAmB;YAAE,SAAS;QAE1D,MAAM,KAAK,GAAG,OAAO;aAClB,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,KAAK,QAAQ,KAAK,EAAE,CAAC,CAAC;aACjF,MAAM,CACL,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,EAC/E,IAAI,CACL,CAAC;QAEJ,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,GAAG,GAAG,GAAG,CAAC;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC;QAEjB,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,KAAK;YACf,KAAK,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,+BAA+B,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,QAAQ;YACnG,WAAW,EACT,iCAAiC,UAAU,CAAC,KAAK,CAAC,aAAa;gBAC/D,GAAG,OAAO,CAAC,MAAM,OAAO,QAAQ,CAAC,MAAM,8CAA8C;gBACrF,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,mBAAmB,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM;gBACpF,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,yDAAyD;gBACxF,yFAAyF;gBACzF,yFAAyF;gBACzF,4FAA4F;YAC9F,QAAQ,EAAE;gBACR,QAAQ,EAAE,QAAQ,KAAK,WAAW;gBAClC,KAAK,EAAE,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC;gBACnC,YAAY,EAAE,OAAO,CAAC,MAAM;gBAC5B,UAAU,EAAE,QAAQ,CAAC,MAAM;gBAC3B,KAAK,EAAE,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE;aACzE;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;AACvC,CAAC;AAgDD,wFAAwF;AACxF,SAAS,UAAU,CAAC,GAAc;IAChC,MAAM,IAAI,GAAe,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IAC/C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,MAAM,WAAW,GAAG,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,WAAW,EAAE,CAAC;YAChB,IAAI,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,MAAM;gBAAE,OAAO,EAAE,CAAC;YAChE,SAAS;QACX,CAAC;QACD,gFAAgF;QAChF,MAAM,QAAQ,GAAG,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QACxF,IAAI,QAAQ,KAAK,IAAI,IAAI,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,MAAM;YAAE,OAAO,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,OAAO,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACjC,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAiB;IACzC,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE7D,MAAM,WAAW,GAAgC,EAAE,CAAC;IACpD,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI;aAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC;aACtC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;aAChC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;QACrD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClC,WAAW,CAAC,QAAQ,CAAC,GAAG;YACtB,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE;SACxF,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;QAC1D,MAAM,gBAAgB,GAA2B,EAAE,CAAC;QACpD,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,KAAK;iBACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC;iBACtC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;iBAChC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;YACrD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,gBAAgB,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAC3B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC,CACxE,CAAC,CAAC,CAAC,CAAC;QACL,OAAO;YACL,QAAQ;YACR,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK;YACrB,OAAO,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI;YAC9C,gBAAgB;YAChB,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE;SAC5B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,qCAAqC;IACrC,MAAM,mBAAmB,GAAwC,EAAE,CAAC;IACpE,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI;aAChB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAuB,CAAC,CAAC;aAC1C,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;QACrD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC;QAC/D,mBAAmB,CAAC,IAAI,CAAC;YACvB,MAAM,EAAE,GAAG;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,OAAO,CAAC,MAAM;YACvB,EAAE,EAAE,MAAM,CAAC,MAAM;YACjB,GAAG;YACH,SAAS,EAAE,GAAG,IAAI,EAAE;YACpB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,KAAK;YACtF,SAAS,EAAE,GAAG,IAAI,CAAC,IAAI,KAAK;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,YAAY,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAChE,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAExD,MAAM,KAAK,GAAG,CAAC,OAAe,EAA2C,EAAE;QACzE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;gBAChC,IAAI,CAAC,CAAC,OAAO,KAAK,OAAO;oBAAE,SAAS;gBACpC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QACD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;aACzB,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;aAC3C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC,CAAC;IAEF,oEAAoE;IACpE,2EAA2E;IAC3E,2EAA2E;IAC3E,8CAA8C;IAC9C,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAC9C,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;QAC1D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAA4B,EAAE,CAAC;YACzE,MAAM,MAAM,GAAG,KAAK;iBACjB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;iBACtB,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;YACrD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAChC,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;YAC3B,IAAI,GAAG,IAAI,CAAC;gBAAE,SAAS;YACvB,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;gBACxB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,GAAG,GAAG,GAAG,CAAC;oBAAE,SAAS;gBAC3D,QAAQ,CAAC,IAAI,CAAC;oBACZ,GAAG,EAAE,GAAG,CAAC,GAAG;oBACZ,QAAQ;oBACR,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;oBACnB,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK;oBAChC,kBAAkB,EAAE,MAAM,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;oBACpD,UAAU,EAAE,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,wBAAwB;iBAC9E,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,MAAM;QACtB,KAAK,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI;QAC3C,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,WAAW;QACX,WAAW;QACX,mBAAmB;QACnB,YAAY;QACZ,oBAAoB,EAAE;YACpB,cAAc,EAAE,KAAK,CAAC,gBAAgB,CAAC;YACvC,YAAY,EAAE,KAAK,CAAC,cAAc,CAAC;YACnC,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC;YAC7B,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM;SACnD;QACD,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/mappers/runComparator.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Before-and-after comparison of two runs.
+ *
+ * A snapshot answers "what is wrong with this page". A developer about to open
+ * a PR has a different question: "did my fix work, and did I break anything?"
+ * Those are not the same question, and a count cannot distinguish them.
+ *
+ * Measured case, from a page where an `alt` attribute and an `aria-label` were
+ * added to fix a missing-alt-text blocker:
+ *
+ *   before: 2 violations — image-alt (P1), color-contrast (P3)
+ *   after:  2 violations — aria-valid-attr-value (P2), color-contrast (P3)
+ *
+ * Identical totals. The P1 was genuinely fixed, and the fix introduced a new
+ * defect, because the aria-labelledby it added pointed at an id that did not
+ * exist. Anyone reading "2 before, 2 after" concludes the change did nothing.
+ * `newly_introduced` is the half of this module that earns its keep.
+ */
+import type { Priority } from "../types.js";
+/** One defect, identified the same way in both runs. */
+export interface DefectRef {
+    url: string;
+    variant: string;
+    /** Rule code for accessibility, audit id for Lighthouse. */
+    id: string;
+    priority: Priority;
+    title?: string;
+}
+export type ComparisonVerdict = "clean" | "improved" | "mixed" | "regression" | "unchanged";
+export interface ScoreChange {
+    url: string;
+    variant: string;
+    category: string;
+    before: number;
+    after: number;
+    delta: number;
+}
+export interface ComparisonResult {
+    baseline_dir: string;
+    baseline_runs: number;
+    current_runs: number;
+    verdict: ComparisonVerdict;
+    summary: string;
+    fixed: Array<{
+        url: string;
+        variant: string;
+        id: string;
+        was: Priority;
+        title?: string;
+    }>;
+    still_failing: Array<{
+        url: string;
+        variant: string;
+        id: string;
+        priority: Priority;
+        title?: string;
+    }>;
+    newly_introduced: Array<{
+        url: string;
+        variant: string;
+        id: string;
+        priority: Priority;
+        title?: string;
+    }>;
+    score_changes?: ScoreChange[];
+    /** Runs present now but absent from the baseline — not comparable. */
+    not_in_baseline: string[];
+    /** Runs in the baseline that this run did not cover — silently uncompared otherwise. */
+    not_in_current: string[];
+    warnings: string[];
+}
+/**
+ * Compare two defect sets.
+ *
+ * Comparison is per (url, variant, defect id). A defect that moved priority
+ * between runs counts as still failing rather than as fixed-and-reintroduced,
+ * since it is the same defect on the same element — the priority shift shows up
+ * in `still_failing`.
+ */
+export declare function compareRuns(baselineDir: string, baseline: DefectRef[], current: DefectRef[], options?: {
+    baselineRuns?: number;
+    currentRuns?: number;
+    baselineScores?: Map<string, Record<string, number>>;
+    currentScores?: Map<string, Record<string, number>>;
+}): ComparisonResult;