nfunc-mcp 0.3.0 → 0.5.0

package/dist/mappers/webVitalsMapper.js

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+/** Google's official p75 boundaries. */
+const VITALS = {
+    lcp: { label: "Largest Contentful Paint", good: 2500, needsImprovement: 4000, isCoreVital: true },
+    inp: { label: "Interaction to Next Paint", good: 200, needsImprovement: 500, isCoreVital: true },
+    cls: { label: "Cumulative Layout Shift", good: 0.1, needsImprovement: 0.25, isCoreVital: true },
+    fcp: { label: "First Contentful Paint", good: 1800, needsImprovement: 3000, isCoreVital: false },
+    ttfb: { label: "Time to First Byte", good: 800, needsImprovement: 1800, isCoreVital: false },
+};
+export function vitalLabel(vital) {
+    return VITALS[vital].label;
+}
+/**
+ * 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 function isCoreVital(vital) {
+    return VITALS[vital].isCoreVital;
+}
+/**
+ * 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 function classifyVital(vital, p75) {
+    const spec = VITALS[vital];
+    if (p75 <= spec.good)
+        return "good";
+    if (p75 <= spec.needsImprovement)
+        return "needs-improvement";
+    return "poor";
+}
+/**
+ * Poor → P1, needs improvement → P2, good → no finding (never report a passing
+ * check). Non-core diagnostics cap at P2.
+ */
+export function fieldVitalToPriority(vital, p75) {
+    const rating = classifyVital(vital, p75);
+    if (rating === "good")
+        return null;
+    if (rating === "needs-improvement")
+        return "P2";
+    return VITALS[vital].isCoreVital ? "P1" : "P2";
+}
+/** Human-readable measurement. CLS is unitless; everything else is milliseconds. */
+export function formatVitalValue(vital, value) {
+    if (vital === "cls")
+        return value.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+    return value >= 1000 ? `${(value / 1000).toFixed(1)} s` : `${Math.round(value)} ms`;
+}
+/** "7 in 10 users" reads more concretely in a ticket than "0.7019". */
+function shareOfUsers(proportion) {
+    const pct = Math.round(proportion * 100);
+    return `${pct}% of real users`;
+}
+/**
+ * Defect prose for each vital, in the register `defectFormatter.ts` established:
+ * what the user experiences, not what the metric is called.
+ *
+ * Every template states the share of real users in the poor bucket. A p75 alone
+ * invites the reply "that's just the tail" — naming the proportion answers it
+ * before it is asked, and the number is already in the response.
+ */
+const FIELD_DESCRIPTIONS = {
+    lcp: (_m, value, poor) => `Real users wait ${value} for the main page content to appear (75th percentile, trailing 28 days). ${poor} experience a load slow enough to be rated poor, well past the point where visitors begin abandoning the page.`,
+    inp: (_m, value, poor) => `The page takes ${value} to respond visibly after a real user taps or clicks (75th percentile, trailing 28 days). ${poor} experience responsiveness rated poor — taps appear to do nothing, so users tap again and trigger duplicate actions.`,
+    cls: (_m, value, poor) => `Real users see the layout shift by ${value} while the page loads (75th percentile, trailing 28 days). ${poor} experience shifting rated poor, which causes mis-taps on the wrong control and loss of reading position.`,
+    fcp: (_m, value, poor) => `Real users stare at a blank screen for ${value} before anything paints (75th percentile, trailing 28 days). ${poor} experience a first paint rated poor. This is a diagnostic for the slow Largest Contentful Paint rather than a defect to fix on its own.`,
+    ttfb: (_m, value, poor) => `The server takes ${value} to return the first byte for real users (75th percentile, trailing 28 days). ${poor} experience a response rated poor; every downstream resource waits on this, so it caps how fast the rest of the page can possibly be.`,
+};
+/**
+ * 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 function formatFieldFinding(vital, metric) {
+    const priority = fieldVitalToPriority(vital, metric.p75);
+    if (!priority)
+        return null;
+    const value = formatVitalValue(vital, metric.p75);
+    const poor = shareOfUsers(metric.distribution.poor);
+    const spec = VITALS[vital];
+    const scope = metric.source === "origin" ? " (site-wide data)" : "";
+    return {
+        priority,
+        title: `${spec.label} is ${classifyVital(vital, metric.p75) === "poor" ? "poor" : "below target"} for real users${scope}`,
+        description: FIELD_DESCRIPTIONS[vital](metric, value, poor) +
+            (metric.source === "origin"
+                ? " This URL has too little traffic for its own field data, so these figures describe the whole origin and may not reflect this page."
+                : ""),
+        evidence: {
+            audit_id: `crux.${vital}`,
+            value,
+            threshold: formatVitalValue(vital, spec.good),
+            field_source: metric.source,
+            users_affected_pct: Math.round(metric.distribution.poor * 100),
+        },
+    };
+}
+/** Every failing field metric in a parsed CrUX block, unsorted. */
+export function formatFieldFindings(metrics) {
+    const findings = [];
+    for (const [vital, metric] of Object.entries(metrics)) {
+        const finding = formatFieldFinding(vital, metric);
+        if (finding)
+            findings.push(finding);
+    }
+    return findings;
+}
+//# sourceMappingURL=webVitalsMapper.js.map

package/dist/mappers/webVitalsMapper.js.map

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

package/dist/tools/accessibility.d.ts

@@ -1,2 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type A11yFormFactor = "desktop" | "mobile";
 export declare function registerAccessibilityTool(server: McpServer): void;