nfunc-mcp 0.2.0 → 0.4.0

package/dist/mappers/labFieldComparator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Lab versus field disagreement — the reason this tool exists.
+ *
+ * A Lighthouse run is a simulation on one machine under one throttling
+ * profile. CrUX is what actually happened to real people. When the two agree,
+ * confidence is high. When they disagree, the direction of the disagreement is
+ * itself the finding, and it is not available from any other tool in this MCP.
+ *
+ * The Five Below homepage is the canonical case: lab CLS 0 against field CLS
+ * 0.55, and lab LCP 11.6 s against field LCP 2.8 s — both metrics inverted, in
+ * opposite directions, on one page. A report built on the lab numbers alone
+ * led with an LCP emergency real users were not experiencing and missed a
+ * layout-shift failure that 70% of them were.
+ */
+import type { Priority } from "../types.js";
+import type { CruxMetric, LabMetrics, ParsedCrux, WebVital } from "../utils/psiParser.js";
+export type LabFieldVerdict = "confirmed" | "worse_in_field" | "worse_in_lab" | "both_pass";
+export interface MetricComparison {
+    metric: WebVital;
+    label: string;
+    lab: number | null;
+    lab_display: string | null;
+    field_p75: number;
+    field_display: string;
+    field_source: CruxMetric["source"];
+    verdict: LabFieldVerdict;
+    note: string;
+}
+/** Lighthouse audit ids, for matching a lab finding back to the vital it measures. */
+export declare const AUDIT_TO_VITAL: Record<string, WebVital>;
+/**
+ * Compare every field metric that has a lab counterpart.
+ *
+ * `both_pass` rows are returned rather than filtered, because the comparison
+ * table in the report is a statement about coverage — a reader needs to see
+ * that LCP was checked and agreed, not infer it from an absence.
+ */
+export declare function compareLabField(lab: LabMetrics, field: ParsedCrux | null): MetricComparison[];
+/**
+ * Promote, but never past a diagnostic's ceiling.
+ *
+ * `webVitalsMapper` caps FCP and TTFB at P2 because they explain a Core Web
+ * Vital rather than being one. Field confirmation makes a finding more
+ * certain, not more important, so an unguarded promotion quietly defeated that
+ * cap and put FCP at P1 above the LCP it was describing.
+ */
+export declare function promote(priority: Priority, vital?: WebVital): Priority;
+export declare function demote(priority: Priority): Priority;
+/**
+ * How a verdict should move a finding's priority.
+ *
+ * Field observation outranks simulation, so the two adjustments are not
+ * symmetric in what they mean: a promotion says "real users confirm this", a
+ * demotion says "only the simulation saw this". A demoted finding is tagged
+ * rather than dropped — the lab number is still true, it just is not evidence
+ * of user harm, and silently deleting it would hide a genuine regression
+ * signal from anyone comparing runs over time.
+ */
+export declare function adjustmentFor(verdict: LabFieldVerdict): {
+    direction: "promote" | "demote" | "none";
+    tag?: string;
+};

package/dist/mappers/labFieldComparator.js

@@ -0,0 +1,134 @@
+/**
+ * Lab versus field disagreement — the reason this tool exists.
+ *
+ * A Lighthouse run is a simulation on one machine under one throttling
+ * profile. CrUX is what actually happened to real people. When the two agree,
+ * confidence is high. When they disagree, the direction of the disagreement is
+ * itself the finding, and it is not available from any other tool in this MCP.
+ *
+ * The Five Below homepage is the canonical case: lab CLS 0 against field CLS
+ * 0.55, and lab LCP 11.6 s against field LCP 2.8 s — both metrics inverted, in
+ * opposite directions, on one page. A report built on the lab numbers alone
+ * led with an LCP emergency real users were not experiencing and missed a
+ * layout-shift failure that 70% of them were.
+ */
+import { classifyVital, formatVitalValue, isCoreVital, vitalLabel } from "./webVitalsMapper.js";
+/**
+ * Lab audits that measure the same thing as a field metric.
+ *
+ * INP is deliberately absent, and its absence is load-bearing. Lighthouse
+ * cannot produce an INP value at all — INP requires a real interaction, and a
+ * lab run never interacts with the page. Total Blocking Time is a *proxy* for
+ * responsiveness, not the same measurement, so comparing them would manufacture
+ * agreement or disagreement out of two different quantities. INP field findings
+ * therefore pass through the comparator untouched, which is why the systemic
+ * collapse rule in the aggregator has to exist.
+ */
+const LAB_EQUIVALENT = {
+    lcp: "lcpMs",
+    cls: "cls",
+    fcp: "fcpMs",
+    ttfb: "ttfbMs",
+};
+/** Lighthouse audit ids, for matching a lab finding back to the vital it measures. */
+export const AUDIT_TO_VITAL = {
+    "largest-contentful-paint": "lcp",
+    "cumulative-layout-shift": "cls",
+    "first-contentful-paint": "fcp",
+    "server-response-time": "ttfb",
+};
+function noteFor(verdict, vital, labDisplay, fieldDisplay) {
+    const name = vitalLabel(vital);
+    switch (verdict) {
+        case "confirmed":
+            return `${name} fails in the lab (${labDisplay}) and for real users (${fieldDisplay}). Confirmed by two independent measurements — treat as real and fix.`;
+        case "worse_in_field":
+            return `The lab run passed ${name} at ${labDisplay}, but real users are at ${fieldDisplay}. The test environment is not reproducing what people actually experience — a real-world network, device class, geography or a third-party script that only loads in production. This is the highest-value finding type here, because no local tool can surface it.`;
+        case "worse_in_lab":
+            return `${name} fails in the lab (${labDisplay}) but real users are at ${fieldDisplay}, which passes. The lab profile is harsher than this page's actual audience. Treat the lab number as a stress signal rather than a user-experienced defect, and prioritise accordingly.`;
+        case "both_pass":
+            return `${name} is within target in both the lab (${labDisplay}) and the field (${fieldDisplay}).`;
+    }
+}
+/**
+ * Compare every field metric that has a lab counterpart.
+ *
+ * `both_pass` rows are returned rather than filtered, because the comparison
+ * table in the report is a statement about coverage — a reader needs to see
+ * that LCP was checked and agreed, not infer it from an absence.
+ */
+export function compareLabField(lab, field) {
+    if (!field)
+        return [];
+    const comparisons = [];
+    for (const [vital, labKey] of Object.entries(LAB_EQUIVALENT)) {
+        const fieldMetric = field.metrics[vital];
+        if (!fieldMetric)
+            continue;
+        const labValue = lab[labKey];
+        const fieldFails = classifyVital(vital, fieldMetric.p75) !== "good";
+        // No lab reading is not a pass; it is an unknown, and the field number
+        // stands on its own.
+        const labFails = labValue === null ? fieldFails : classifyVital(vital, labValue) !== "good";
+        const verdict = labFails && fieldFails ? "confirmed"
+            : !labFails && fieldFails ? "worse_in_field"
+                : labFails && !fieldFails ? "worse_in_lab"
+                    : "both_pass";
+        const labDisplay = labValue === null ? null : formatVitalValue(vital, labValue);
+        const fieldDisplay = formatVitalValue(vital, fieldMetric.p75);
+        comparisons.push({
+            metric: vital,
+            label: vitalLabel(vital),
+            lab: labValue,
+            lab_display: labDisplay,
+            field_p75: fieldMetric.p75,
+            field_display: fieldDisplay,
+            field_source: fieldMetric.source,
+            verdict,
+            note: noteFor(verdict, vital, labDisplay, fieldDisplay),
+        });
+    }
+    return comparisons;
+}
+const UP = { P1: "P1", P2: "P1", P3: "P2" };
+const DOWN = { P1: "P2", P2: "P3", P3: "P3" };
+/**
+ * Promote, but never past a diagnostic's ceiling.
+ *
+ * `webVitalsMapper` caps FCP and TTFB at P2 because they explain a Core Web
+ * Vital rather than being one. Field confirmation makes a finding more
+ * certain, not more important, so an unguarded promotion quietly defeated that
+ * cap and put FCP at P1 above the LCP it was describing.
+ */
+export function promote(priority, vital) {
+    const promoted = UP[priority];
+    if (vital && !isCoreVital(vital) && promoted === "P1")
+        return "P2";
+    return promoted;
+}
+export function demote(priority) {
+    return DOWN[priority];
+}
+/**
+ * How a verdict should move a finding's priority.
+ *
+ * Field observation outranks simulation, so the two adjustments are not
+ * symmetric in what they mean: a promotion says "real users confirm this", a
+ * demotion says "only the simulation saw this". A demoted finding is tagged
+ * rather than dropped — the lab number is still true, it just is not evidence
+ * of user harm, and silently deleting it would hide a genuine regression
+ * signal from anyone comparing runs over time.
+ */
+export function adjustmentFor(verdict) {
+    switch (verdict) {
+        case "confirmed":
+            return { direction: "promote", tag: "field_confirmed" };
+        case "worse_in_field":
+            return { direction: "promote", tag: "field_only" };
+        case "worse_in_lab":
+            return { direction: "demote", tag: "lab_only" };
+        default:
+            return { direction: "none" };
+    }
+}
+//# sourceMappingURL=labFieldComparator.js.map

package/dist/mappers/labFieldComparator.js.map

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

package/dist/mappers/priorityMapper.d.ts

@@ -1,6 +1,44 @@
 import type { Finding, Priority } from "../types.js";
 export type { Priority };
 export declare function lighthouseScoreToPriority(score: number): Priority | null;
+/**
+ * Priority from an audit's actual impact on its Lighthouse category score.
+ *
+ * Scoring on `score` alone made every failing binary audit a P1: binary audits
+ * score exactly 0 when they fail, so a missing llms.txt ranked level with a
+ * 30-second Time to Interactive. On a real commerce page that produced 24
+ * Lighthouse P1s, 18 of them binary — and 19 of the 35 failing audits carried
+ * weight 0, meaning Lighthouse itself counts them toward no category score at
+ * all.
+ *
+ * `weight * (1 - score)` is the number of category points the audit actually
+ * costs — the same quantity Lighthouse uses to compute the category score. It
+ * ranks a weight-30 metric failing outright (30) above a weight-25 metric
+ * scoring 78 (5.5) above a weight-1 SEO check (1), which is the ordering a
+ * human triager would pick.
+ *
+ * Weight-0 diagnostics stay reportable but never block: they are supporting
+ * detail for the weighted metrics, and counting them again is double-counting
+ * (unused-javascript, bootup-time and mainthread-work-breakdown all describe
+ * the same overloaded main thread that total-blocking-time already charges for).
+ *
+ * `weight` undefined means the audit belongs to no category, which is not the
+ * same as weight 0 — fall back to the score-only mapping there.
+ */
+export declare function lighthouseImpactToPriority(score: number, weight: number | undefined): Priority | null;
 export declare function wcagLevelToPriority(level: string): Priority | null;
+/**
+ * Priority for an axe finding, from axe's own impact rating.
+ *
+ * Same principle as using Lighthouse's audit weight: the tool has already
+ * graded severity, so grade with it rather than inventing a parallel scheme.
+ * axe's ladder is critical > serious > moderate > minor.
+ *
+ * `needsFurtherReview` marks a rule that could not decide on its own and wants
+ * a human to confirm. Those are demoted one tier — a maybe should not gate a
+ * release with the same force as a definite.
+ */
+export declare function axeImpactToPriority(impact: string | undefined, needsReview: boolean | undefined): Priority | null;
+export declare function a11yTechniqueToPriority(technique: string, wcagLevel: string): Priority | null;
 export declare function staticAnalysisToPriority(source: "eslint" | "semgrep", severity: number | string, category?: string): Priority | null;
 export declare function sortFindingsByPriority<T extends Finding>(findings: T[]): T[];

package/dist/mappers/priorityMapper.js

@@ -8,6 +8,42 @@ export function lighthouseScoreToPriority(score) {
         return "P3";
     return null;
 }
+/**
+ * Priority from an audit's actual impact on its Lighthouse category score.
+ *
+ * Scoring on `score` alone made every failing binary audit a P1: binary audits
+ * score exactly 0 when they fail, so a missing llms.txt ranked level with a
+ * 30-second Time to Interactive. On a real commerce page that produced 24
+ * Lighthouse P1s, 18 of them binary — and 19 of the 35 failing audits carried
+ * weight 0, meaning Lighthouse itself counts them toward no category score at
+ * all.
+ *
+ * `weight * (1 - score)` is the number of category points the audit actually
+ * costs — the same quantity Lighthouse uses to compute the category score. It
+ * ranks a weight-30 metric failing outright (30) above a weight-25 metric
+ * scoring 78 (5.5) above a weight-1 SEO check (1), which is the ordering a
+ * human triager would pick.
+ *
+ * Weight-0 diagnostics stay reportable but never block: they are supporting
+ * detail for the weighted metrics, and counting them again is double-counting
+ * (unused-javascript, bootup-time and mainthread-work-breakdown all describe
+ * the same overloaded main thread that total-blocking-time already charges for).
+ *
+ * `weight` undefined means the audit belongs to no category, which is not the
+ * same as weight 0 — fall back to the score-only mapping there.
+ */
+export function lighthouseImpactToPriority(score, weight) {
+    if (score >= 90)
+        return null;
+    if (weight === undefined)
+        return lighthouseScoreToPriority(score);
+    const impact = weight * (1 - score / 100);
+    if (impact >= 10)
+        return "P1";
+    if (impact >= 3)
+        return "P2";
+    return "P3";
+}
 // Pass "notice" (or "warning" / "unknown") to suppress the finding.
 export function wcagLevelToPriority(level) {
     if (level === "A")
@@ -18,6 +54,96 @@ export function wcagLevelToPriority(level) {
         return "P3";
     return null;
 }
+/**
+ * Priority for a pa11y violation, keyed on the WCAG technique rather than the
+ * conformance level.
+ *
+ * Level is not impact. Almost everything a WCAG2AA scan detects is Level A, so
+ * mapping A→P1 made all 17 pa11y findings on a real page P1 and left the tier
+ * doing no discrimination. Technique says what actually breaks: an unlabelled
+ * input stops a screen-reader user completing a form, while a duplicate id
+ * degrades an experience that still works.
+ *
+ * Keys are matched by the progressive-narrowing rule used for descriptions —
+ * "H91.InputText.Name" falls back to "H91" — and anything unlisted falls back
+ * to the conformance-level mapping.
+ */
+const TECHNIQUE_PRIORITY = {
+    // P1 — blocks a user from completing a task.
+    H91: "P1", // no accessible name on an interactive element
+    F68: "P1", // form control with no label
+    H44: "P1", // label not associated with its control
+    ARIA6: "P1", // empty/invalid aria-label
+    ARIA9: "P1", // aria-labelledby pointing at missing ids
+    H32: "P1", // form with no submit mechanism
+    H37: "P1", // img with no alt
+    F65: "P1", // img with neither alt nor title
+    H30: "P1", // link whose only content is an unlabelled image
+    H36: "P1", // image submit button with no alt
+    H53: "P1", // object with no fallback content
+    G202: "P1", // keyboard focus trapped or invisible
+    F54: "P1", // mouse-only interaction
+    F55: "P1", // focus stolen on hover
+    G18: "P1", // body text below 4.5:1 contrast
+    G145: "P1", // large text below 3:1 contrast
+    // P2 — degrades the experience without blocking it.
+    F77: "P2", // duplicate id
+    H93: "P2", // duplicate id (label/for variant)
+    G141: "P2", // heading levels skipped
+    H42: "P2", // text styled as a heading but not marked up
+    H25: "P2", // missing page title
+    F89: "P2", // empty page title
+    H57: "P2", // missing lang on <html>
+    H58: "P2", // unmarked language change
+    H64: "P2", // iframe with no title
+    H67: "P2", // decorative img carrying meaning
+    G94: "P2", // inaccurate alt text
+    "G1,G123,G124": "P2", // link to a named anchor that does not exist
+    H85: "P2", // ungrouped select options
+    G174: "P2", // no higher-contrast alternative
+    F40: "P2", // meta refresh with delay
+    F41: "P2", // auto-refresh with no user control
+    // P3 — advisory.
+    F92: "P3", // role="presentation" hiding real semantics
+    ARIA4: "P3", // role inappropriate for the content
+    H49: "P3", // emphasis conveyed only visually
+    F2: "P3", // meaning conveyed by formatting alone
+    G14: "P3", // meaning conveyed by colour alone
+};
+/**
+ * Priority for an axe finding, from axe's own impact rating.
+ *
+ * Same principle as using Lighthouse's audit weight: the tool has already
+ * graded severity, so grade with it rather than inventing a parallel scheme.
+ * axe's ladder is critical > serious > moderate > minor.
+ *
+ * `needsFurtherReview` marks a rule that could not decide on its own and wants
+ * a human to confirm. Those are demoted one tier — a maybe should not gate a
+ * release with the same force as a definite.
+ */
+export function axeImpactToPriority(impact, needsReview) {
+    const base = impact === "critical" ? "P1"
+        : impact === "serious" ? "P2"
+            : impact === "moderate" ? "P3"
+                : impact === "minor" ? "P3"
+                    : "P3"; // unrated: report, never block
+    if (!needsReview)
+        return base;
+    return base === "P1" ? "P2" : "P3";
+}
+export function a11yTechniqueToPriority(technique, wcagLevel) {
+    let key = technique;
+    while (key) {
+        const p = TECHNIQUE_PRIORITY[key];
+        if (p)
+            return p;
+        const lastDot = key.lastIndexOf(".");
+        if (lastDot < 0)
+            break;
+        key = key.slice(0, lastDot);
+    }
+    return wcagLevelToPriority(wcagLevel);
+}
 export function staticAnalysisToPriority(source, severity, category) {
     // Security findings always win regardless of severity level.
     if (source === "semgrep" && category === "security")

package/dist/mappers/priorityMapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"priorityMapper.js","sourceRoot":"","sources":["../../src/mappers/priorityMapper.ts"],"names":[],"mappings":"AAIA,MAAM,cAAc,GAA6B,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AAEzE,MAAM,UAAU,yBAAyB,CAAC,KAAa;IACrD,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,KAAK,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,MAA4B,EAC5B,QAAyB,EACzB,QAAiB;IAEjB,6DAA6D;IAC7D,IAAI,MAAM,KAAK,SAAS,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACjE,IAAI,MAAM,KAAK,QAAQ,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1F,IAAI,MAAM,KAAK,QAAQ,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvD,6CAA6C;IAC7C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAoB,QAAa;IACrE,OAAO,QAAQ,CAAC,IAAI,CAClB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,CAClE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"priorityMapper.js","sourceRoot":"","sources":["../../src/mappers/priorityMapper.ts"],"names":[],"mappings":"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"}

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;