nfunc-mcp 0.3.0 → 0.4.0

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/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":"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"}

package/dist/mappers/webVitalsMapper.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Core Web Vitals field data → priorities and defect prose.
+ *
+ * The lab side of a PSI response goes through the existing
+ * `formatLighthouseFinding` path unchanged. This module handles the CrUX half,
+ * where the inputs are 75th-percentile measurements from real users rather
+ * than audit scores, so neither the impact-weight mapping nor the WCAG
+ * technique table applies.
+ *
+ * Field findings are written to read differently from lab findings on purpose.
+ * A lab finding says the page did something under simulation; a field finding
+ * says a measurable share of real people already experienced it. That
+ * distinction is the whole reason to call PSI, and it should survive into the
+ * defect ticket.
+ */
+import type { Finding, Priority } from "../types.js";
+import type { CruxMetric, WebVital } from "../utils/psiParser.js";
+export type VitalRating = "good" | "needs-improvement" | "poor";
+export declare function vitalLabel(vital: WebVital): string;
+/**
+ * LCP, INP and CLS gate a release and affect ranking; FCP and TTFB explain
+ * them. Exported because the priority cap has to hold everywhere a priority is
+ * decided, not just where one is first assigned.
+ */
+export declare function isCoreVital(vital: WebVital): boolean;
+/**
+ * Rate a p75 value against Google's thresholds.
+ *
+ * PSI also returns its own FAST/AVERAGE/SLOW `category` per metric, and the two
+ * agree in practice. We classify from the published thresholds anyway, so that
+ * the boundary a finding was raised at is a documented number in this file
+ * rather than a verdict from an opaque field — and so origin-level and
+ * URL-level metrics are graded identically.
+ */
+export declare function classifyVital(vital: WebVital, p75: number): VitalRating;
+/**
+ * Poor → P1, needs improvement → P2, good → no finding (never report a passing
+ * check). Non-core diagnostics cap at P2.
+ */
+export declare function fieldVitalToPriority(vital: WebVital, p75: number): Priority | null;
+/** Human-readable measurement. CLS is unitless; everything else is milliseconds. */
+export declare function formatVitalValue(vital: WebVital, value: number): string;
+/**
+ * One field metric → a Finding, or null when real users are having a fine time.
+ *
+ * `source` reaches the evidence deliberately. An origin-level metric describes
+ * the whole site, not this page, and a reader deciding whether to act on the
+ * finding needs to know which they are looking at.
+ */
+export declare function formatFieldFinding(vital: WebVital, metric: CruxMetric): Finding | null;
+/** Every failing field metric in a parsed CrUX block, unsorted. */
+export declare function formatFieldFindings(metrics: Partial<Record<WebVital, CruxMetric>>): Finding[];