nfunc-mcp 0.3.0 → 0.4.0

package/README.md

@@ -2,38 +2,18 @@
 
 [![npm](https://img.shields.io/npm/v/nfunc-mcp)](https://www.npmjs.com/package/nfunc-mcp)
 
-A local MCP server that gives Claude (or any MCP client) a full non-functional QA toolkit. Run Lighthouse, WCAG accessibility checks, and static code analysis — individually or all at once — and get back structured, prioritised findings you can act on immediately.
+A local MCP server that gives Claude a non-functional QA toolkit. Performance,
+accessibility, SEO, code quality and real-user Core Web Vitals — run
+individually or all at once, returned as prioritised findings you can act on
+rather than raw tool output.
 
----
-
-## Table of contents
-
-1. [What it does](#what-it-does)
-2. [Prerequisites](#prerequisites)
-3. [Install & build](#install--build)
-4. [Register with Claude Code](#register-with-claude-code)
-5. [Tools](#tools)
-6. [run_qa_gate — the main tool](#run_qa_gate--the-main-tool)
-   - [Inputs](#inputs)
-   - [Release readiness tiers](#release-readiness-tiers)
-   - [Composite score](#composite-score)
-   - [Scorecard](#scorecard)
-   - [Cross-tool corroboration](#cross-tool-corroboration)
-   - [HTML report](#html-report)
-   - [Output shape](#output-shape)
-7. [Individual tools](#individual-tools)
-   - [Mobile vs desktop](#mobile-vs-desktop)
-   - [Choosing an accessibility engine](#choosing-an-accessibility-engine)
-8. [Priority system](#priority-system)
-9. [Project layout](#project-layout)
-10. [How to prompt](#how-to-prompt)
+> **[Operating manual →](docs/manual.md)** — installation options, per-tool
+> reference, output shapes, troubleshooting.
 
 ---
 
 ## What it does
 
-`nfunc-mcp` wires four QA tools into Claude's tool-use loop:
-
 | Capability | Tools | What it checks |
 |---|---|---|
 | Performance | Lighthouse | LCP, TTI, TBT, CLS, bundle size, caching |
@@ -42,399 +22,127 @@ A local MCP server that gives Claude (or any MCP client) a full non-functional Q
 | Best practices | Lighthouse | HTTPS, deprecated APIs, third-party cookies |
 | Code quality | ESLint | Dead code, undeclared vars, swallowed errors |
 | Security patterns | Semgrep | OWASP JS/TS patterns |
+| Real-user vitals | PageSpeed Insights + CrUX | What actual visitors experienced, versus what the lab measures |
 
-The `run_qa_gate` orchestrator runs all of them in parallel, cross-correlates findings across tools, and produces a single structured report with a release readiness verdict, a composite health score, a per-tool scorecard, and a browser-openable HTML report.
+Findings arrive prioritised **P1 / P2 / P3**, written as defect-ticket prose
+rather than audit jargon, with passing checks filtered out. Nothing that passes
+is ever reported.
 
 ---
 
-## Prerequisites
-
-`nfunc-mcp` is a thin wrapper around four CLI tools. Install the ones you need before registering the server:
-
-| Tool | Install | Used by |
-|---|---|---|
-| Lighthouse | `npm install -g lighthouse` | `run_lighthouse`, `run_qa_gate` (URL) |
-| pa11y | `npm install -g pa11y` | `run_accessibility_check`, `run_qa_gate` (URL) |
-| ESLint | `npm install -g eslint` | `run_static_analysis`, `run_qa_gate` (path) |
-| Semgrep | `brew install semgrep` or `pip install semgrep` | `run_static_analysis`, `run_qa_gate` (path) |
-
-Verify each is reachable:
-
-```bash
-lighthouse --version
-pa11y --version
-eslint --version
-semgrep --version
-```
-
-**You don't need all four.** If a tool is missing or not installed, the gate still runs — that tool's scorecard entry shows `UNAVAILABLE` and its findings are skipped. URL-only runs only need Lighthouse and pa11y; path-only runs only need ESLint and Semgrep.
-
----
-
-## Install & register
-
-### Option A — npm (recommended, no cloning needed)
+## Quick start
 
 ```bash
 claude mcp add nfunc-mcp -- npx -y nfunc-mcp
 ```
 
-That's it. `npx` downloads and runs the server on your machine automatically. No repo clone, no build step.
-
-### Option B — Manual config (npm)
-
-Add to `~/.claude.json` under `mcpServers`:
-
-```json
-{
-  "mcpServers": {
-    "nfunc-mcp": {
-      "command": "npx",
-      "args": ["-y", "nfunc-mcp"]
-    }
-  }
-}
-```
-
-### Option C — From source (contributors / local dev)
-
-```bash
-git clone https://github.com/Hiddensound/NFunc_MCP.git
-cd NFunc_MCP
-npm install
-npm run build
-claude mcp add nfunc-mcp -- node /absolute/path/to/NFunc_MCP/dist/index.js
-```
-
-### Scripts (source only)
-
-| Script | Purpose |
-|---|---|
-| `npm run build` | Compile TypeScript → `dist/` |
-| `npm start` | Run the compiled server |
-| `npm run dev` | Run from source with hot reload (`tsx watch`) |
+Then install whichever CLIs you need — `lighthouse`, `pa11y`, `eslint`,
+`semgrep`. Missing tools are skipped rather than fatal, so start with what you
+have. For real-user field data, add a
+[PageSpeed Insights key](docs/manual.md#pagespeed-insights-api-key).
 
-### Verify the connection
+Verify with `/mcp`, then ask Claude to *"call the nfunc-mcp ping tool."*
 
-1. Run `/mcp` in Claude Code — `nfunc-mcp` should show as `connected`.
-2. Ask Claude: *"Call the nfunc-mcp ping tool."*
-3. Expected response:
-   ```json
-   { "status": "ok", "timestamp": "2026-05-20T12:00:00.000Z" }
-   ```
+[Other install options →](docs/manual.md#install-and-register)
 
 ---
 
-## Tools
-
-| Tool | Description | Inputs |
-|---|---|---|
-| `ping` | Health check — confirms the server is up | — |
-| `run_lighthouse` | Full Lighthouse audit for a URL | `url`, `form_factor` (optional), `categories` (optional), `thresholds` (optional) |
-| `run_accessibility_check` | pa11y WCAG audit for a URL | `url`, `runner` (optional), `standard` (optional), `ignore` (optional) |
-| `run_static_analysis` | ESLint + Semgrep scan for a local codebase | `path` |
-| `run_qa_gate` | All tools in parallel + correlation + HTML report | `url` and/or `path`, `form_factor` (optional), `a11y_runner` (optional) |
-
----
-
-## run_qa_gate — the main tool
-
-This is the tool to reach for in nearly every QA workflow. It replaces running tools individually and adds cross-tool intelligence on top.
-
-### Inputs
-
-Both inputs are **optional** — provide whichever you have. At least one is required.
+## The tools
 
-| Input | Type | When to provide |
-|---|---|---|
-| `url` | string (URL) | You have a running page — production, staging, preview URL, or localhost. Enables Lighthouse and pa11y. |
-| `path` | string (path) | You have a local codebase. Enables ESLint and Semgrep. |
-| `context` | string | Optional. Free-text description of the project (e.g. `"React e-commerce checkout"`). Helps Claude interpret results. |
-| `form_factor` | `mobile` \| `desktop` \| `both` | Optional, default `mobile`. Lighthouse device profile — see [Mobile vs desktop](#mobile-vs-desktop). |
-| `a11y_runner` | `htmlcs` \| `axe` \| `both` | Optional, default `htmlcs`. pa11y engine — see [Choosing an accessibility engine](#choosing-an-accessibility-engine). |
-
-**URL only** — browser-based checks, static analysis skipped:
-```
-QA snapshot — https://staging.myapp.com
-```
-
-**Path only** — static analysis only, browser checks skipped:
-```
-QA snapshot — /path/to/my-feature-branch
-```
-
-**Both** — full suite:
-```
-QA snapshot — https://staging.myapp.com, code at /path/to/repo
-```
-
-### Release readiness tiers
-
-The `release_readiness` field replaces a binary pass/fail with four actionable tiers:
-
-| Value | Meaning | Condition |
-|---|---|---|
-| `BLOCKED` | Cannot ship — P1 issues exist | Any P1 finding |
-| `CONDITIONAL` | Shippable with caveats — track P2s before merging | P2 findings, no P1s |
-| `ADVISORY` | Safe to ship — P3s are tech debt to log | Only P3 findings |
-| `CLEAR` | No issues detected | Zero findings |
-
-### Composite score
-
-A single `composite_score` (0–100) gives a continuous health measure across all tools.
-
-**Formula:** Start at 100, deduct by finding severity:
-
-| Priority | Deduction |
-|---|---|
-| P1 | −15 per finding |
-| P2 | −7 per finding |
-| P3 | −3 per finding |
-
-Score is floored at 0. Tracks improvement over time — a score trending upward sprint-over-sprint is a healthy signal.
-
-### Scorecard
-
-A compact `scorecard` array gives a one-line status per tool:
-
-```json
-[
-  { "tool": "Lighthouse",       "gate": "WARN", "score": 75,
-    "breakdown": { "performance": 52, "accessibility": 98, "seo": 100, "best-practices": 58 } },
-  { "tool": "pa11y",            "gate": "PASS", "issues": 0 },
-  { "tool": "ESLint / Semgrep", "gate": "SKIPPED" }
-]
-```
-
-Gate values:
-
-| Gate | Meaning |
+| Tool | What it does |
 |---|---|
-| `PASS` | No issues at this tool's threshold |
-| `WARN` | Issues exist but below the FAIL threshold |
-| `FAIL` | Issues at P1 level (or Lighthouse avg < 50) |
-| `SKIPPED` | Input not provided (URL or path not supplied) |
-| `UNAVAILABLE` | Tool was invoked but is not installed or errored |
-
-### Cross-tool corroboration
-
-When Lighthouse and pa11y independently flag the same accessibility gap, those findings are:
+| **`run_qa_gate`** | **The one to reach for.** Runs everything applicable in parallel, correlates findings across tools, and returns a release verdict, a composite score, a per-tool scorecard and an HTML report. |
+| `run_lighthouse` | Lighthouse for a URL. `form_factor: "both"` finds device-specific defects the single profiles miss. |
+| `run_accessibility_check` | pa11y WCAG audit. `runner: "axe"` for ARIA and design systems; `"both"` for the widest sweep. |
+| `run_static_analysis` | ESLint + Semgrep over a local codebase. Uses your ESLint config if it finds one. |
+| `plan_performance_audit` | Plans a PageSpeed Insights audit — finds your URLs, groups them into page templates, costs the run. **Spends no quota.** |
+| `run_performance_audit` | Runs it. Lab scores, real-user field data, and the disagreements between them. |
+| `ping` | Health check. |
+
+### Which one when
+
+- **Shipping something?** `run_qa_gate`. It is the default answer.
+- **One dimension in depth?** The individual tool — `run_lighthouse` for a perf
+  regression, `run_accessibility_check` for an a11y pass.
+- **"Is the site actually fast for real people?"** The PSI pair. This is the
+  only thing here that measures real visitors instead of a simulation, and it
+  routinely disagrees with the lab.
+
+The PSI tools are **opt-in** — `run_qa_gate` never calls them, because they
+spend API quota and take minutes rather than seconds.
 
-1. **Merged** into a single entry in `corroborated_findings`
-2. **Priority-promoted** one tier (P3→P2, P2→P1)
-3. **Annotated** with `confidence: "high"` and `confirmed_by: ["lighthouse", "pa11y"]`
-
-These are the highest-confidence findings in any report — two independent tools agreeing is stronger evidence than either alone. They appear in their own dedicated section above all other findings, and bubble to the top of `top_issues`.
-
-**Corroboration mapping (Rule 1):**
-
-| Lighthouse audit | pa11y technique |
-|---|---|
-| `color-contrast` | `.G18`, `.G145`, `.G174` |
-| `image-alt` | `.H37`, `.H67`, `.F65` |
-| `label` | `.H44`, `.F68`, `.H91.Input` |
-| `link-name` | `.H30`, `.H91.A.` |
-| `html-has-lang` | `.H57` |
-| `button-name` | `.H91.Button` |
-| *(and more)* | |
-
-**Performance ↔ code linkage (Rule 2):** If a Lighthouse performance finding's display value contains a filename that also appears in a static analysis finding, the static finding is added as `related_findings` on the Lighthouse entry. Findings are not merged — they remain linked by reference.
-
-### HTML report
+---
 
-Every `run_qa_gate` call automatically writes a self-contained HTML file to `/tmp` and returns its path as `report_file`:
+## How to ask for it
 
-```json
-{
-  "report_file": "file:///tmp/qa-report-myapp-com-1234567890.html"
-}
 ```
+# Full suite
+QA snapshot — https://myapp.com, code at /path/to/repo
 
-Open the path in any browser to get:
-
-- Release readiness banner (colour-coded)
-- Composite score gauge (SVG arc, 0–100)
-- Per-tool scorecard table
-- Cross-confirmed findings section (highlighted)
-- Collapsible finding cards grouped by P1 / P2 / P3
-- Evidence and selector for each finding
-
-No server required — the file is fully self-contained with inline CSS.
-
-### Output shape
-
-```jsonc
-{
-  "release_readiness": "BLOCKED",        // BLOCKED | CONDITIONAL | ADVISORY | CLEAR
-  "composite_score": 22,                 // 0–100
-  "report_file": "file:///tmp/qa-report-xxx.html",
-  "scorecard": [ ... ],                  // per-tool gate + score/issues
-  "eslint_config_used": "project",       // present only when path was supplied
-  "summary": "110 findings (101 P1, 9 P2) across 2 tools. ...",
-  "corroborated_findings": [ ... ],      // cross-confirmed, confidence: "high"
-  "top_issues": [ ... ],                 // top 3 findings (corroborated first)
-  "all_findings": [ ... ],               // all findings sorted by priority
-  "correlations_found": 1,
-  "errors": [ ... ]                      // present only if a tool errored
-}
-```
+# URL only (Lighthouse + pa11y)
+QA snapshot — https://myapp.com
 
-Each finding:
-
-```jsonc
-{
-  "priority": "P1",                      // P1 | P2 | P3
-  "title": "Largest Contentful Paint",
-  "description": "Users see main content 34s after navigation...",
-  "evidence": { "audit_id": "largest-contentful-paint", "value": "34.3 s" },
-  "source_tool": "lighthouse",
-  // corroborated findings also have:
-  "confirmed_by": ["lighthouse", "pa11y"],
-  "confidence": "high"
-}
+# Local branch only (ESLint + Semgrep)
+QA snapshot — /path/to/my-feature-branch
 ```
 
----
-
-## Individual tools
-
-### run_lighthouse
-
-Runs a full Lighthouse audit against a URL.
+These all work too:
 
 ```
-Run Lighthouse on https://myapp.com
+Health check on https://myapp.com
+Is https://myapp.com ready to ship? Code at /path/to/repo
+Any red flags? /path/to/repo
 Run Lighthouse on https://myapp.com for mobile and desktop
-```
-
-Returns: `url`, `form_factor`, `scores` (per category), `ttfb_ms`, `findings` (priority-ordered).
-
-#### Mobile vs desktop
-
-`form_factor` accepts `desktop` (default), `mobile`, or `both`.
-
-**This default deliberately differs from the Lighthouse CLI's**, which is mobile: a 412×823 screen, a mid-range Android user agent, simulated slow 4G, and a **4× CPU slowdown**. That profile is much harsher and reports substantially lower performance scores for the same page, so passing `mobile` here is not a like-for-like comparison with a default run — check `form_factor` in the response before comparing two reports.
-
-**The two are not interchangeable.** They render different DOM, so they find different defects — not just different performance numbers. Measured against one commerce category page:
-
-| | Mobile | Desktop |
-|---|---|---|
-| performance | 54 | 62 |
-| accessibility | **87** | **73** |
-| seo | 77 | 69 |
-
-Five accessibility audits failed on desktop that mobile never reported — `image-alt`, `aria-required-children`, `aria-required-parent`, `aria-allowed-attr`, `aria-valid-attr-value` — while three others failed only on mobile. Neither profile is a superset of the other.
-
-With `form_factor: "both"`, the two run concurrently (so it costs little more wall time than one), `scores` is keyed by form factor, and each finding carries `affects_form_factors` and `form_factor_specific` so device-only regressions are obvious at a glance.
-
-### run_accessibility_check
-
-Runs pa11y against a URL at WCAG 2 AA by default. Returns only violations (errors) — use the CLI directly with `--include-notices --include-warnings` for the full checklist.
-
-```
-Run an accessibility check on https://myapp.com
-Run accessibility check at AAA standard on https://myapp.com
 Run an accessibility check on https://myapp.com using the axe runner
+Plan a PageSpeed Insights audit for https://myapp.com
 ```
 
-Returns: `url`, `standard`, `runners`, `violation_count`, `raw_violation_count`, `findings`.
-
-#### Choosing an accessibility engine
-
-`runner` accepts `htmlcs` (default), `axe`, or `both`.
-
-| Engine | Strongest at | Severity source |
-|---|---|---|
-| `htmlcs` | WCAG techniques, document structure, form labelling, duplicate ids | WCAG technique class |
-| `axe` | **ARIA** — invalid roles, missing required parent/child relationships, prohibited and unsupported attributes — and computed colour contrast | axe's own `impact` rating |
-
-**Reach for `axe` whenever the work under test involves ARIA, a component library, or a design system.** The overlap between the engines is smaller than you would expect. On the same page:
-
-- htmlcs found unlabelled inputs, forms with no submit mechanism, and ten duplicate ids that axe did not report.
-- axe found `aria-allowed-attr`, `aria-prohibited-attr`, `aria-required-parent`, `aria-required-children` and `image-alt` failures that htmlcs missed entirely.
-
-`both` runs them concurrently and merges the results. Note that an element flagged by both engines appears twice, because they emit different rule codes for the same defect — that is deliberate, since two independent engines agreeing is corroboration worth seeing.
-
-Findings from axe carry `axe_impact` in evidence, and `needs_manual_review: true` where axe wants a human to confirm (those are demoted one priority tier — a maybe should not gate a release as hard as a certainty).
-
-### run_static_analysis
-
-Runs ESLint and Semgrep in parallel against a local directory. Automatically uses the project's own ESLint config if one is found; otherwise falls back to a QA-focused baseline config.
-
-```
-Run static analysis on /path/to/repo
-```
-
-Returns: `path`, `tools_run`, `eslint_config_used`, `issue_count`, `findings`, `warnings`.
+`run_qa_gate` returns a `report_file` path — open it in a browser for the
+visual dashboard.
 
 ---
 
-## Priority system
-
-| Priority | Meaning | Lighthouse threshold | WCAG level | ESLint / Semgrep |
-|---|---|---|---|---|
-| P1 | Blocker — fix before shipping | Score < 50 | Level A | Semgrep security, ESLint error |
-| P2 | Warning — track before merging | Score 50–79 | Level AA | ESLint warning |
-| P3 | Advisory — log as tech debt | Score 80–89 | Level AAA | — |
-| *(suppressed)* | Passing — not reported | Score ≥ 90 | — | — |
+## What makes it different from running the CLIs yourself
 
-Corroborated findings are promoted one tier above where either tool would place them individually.
+**Findings, not output.** Every result is a prioritised defect with QA-native
+prose and traceable evidence, not a wall of audit JSON.
 
----
+**Cross-tool corroboration.** When Lighthouse and pa11y independently flag the
+same accessibility gap, the finding is merged, promoted a tier and marked
+`confidence: "high"`. Two tools agreeing is stronger evidence than either alone.
 
-## Project layout
+**Systemic collapse.** One duplicate-id component failing on eleven elements is
+reported as one defect, not eleven.
+[How that works →](docs/manual.md#run_accessibility_check)
 
-```
-qa-mcp/
-├── src/
-│   ├── index.ts                         # MCP server bootstrap + tool registration
-│   ├── types.ts                         # Shared types (Finding, Priority)
-│   ├── config/
-│   │   └── qa-mcp-baseline.eslint.config.js  # Fallback ESLint config
-│   ├── tools/
-│   │   ├── qaGate.ts                    # Orchestrator — runs all tools, builds report
-│   │   ├── lighthouse.ts                # run_lighthouse tool
-│   │   ├── accessibility.ts             # run_accessibility_check tool
-│   │   └── staticAnalysis.ts            # run_static_analysis tool
-│   ├── mappers/
-│   │   ├── correlator.ts                # Cross-tool correlation engine (Rule 1 + 2)
-│   │   ├── defectFormatter.ts           # Raw tool output → Finding objects
-│   │   └── priorityMapper.ts            # Score/severity → P1/P2/P3
-│   └── utils/
-│       ├── reportGenerator.ts           # HTML report builder
-│       ├── shellRunner.ts               # CLI execution with timeout + error handling
-│       ├── outputParsers.ts             # JSON parsers for each tool's output
-│       ├── eslintConfigDetector.ts      # Detects project ESLint config
-│       └── toolResponse.ts             # MCP error response helpers
-├── dist/                                # Compiled output (gitignored)
-├── package.json
-├── tsconfig.json
-└── README.md
-```
+**Lab versus field.** A metric that passes in the lab but fails for real users
+means your test environment is not reproducing production — and no local tool
+can detect it. On one real homepage the lab reported a perfect CLS of 0 while
+70% of real users were experiencing a rating of poor.
+[More →](docs/manual.md#what-psi-adds-over-run_lighthouse)
 
 ---
 
-## How to prompt
-
-The shortest working prompts:
+## Priority levels
 
-```
-# Full suite
-QA snapshot — https://myapp.com, code at /path/to/repo
+| | Meaning |
+|---|---|
+| **P1** | Blocker — fix before shipping |
+| **P2** | Warning — track before merging |
+| **P3** | Advisory — log as tech debt |
 
-# URL only (Lighthouse + pa11y)
-QA snapshot — https://myapp.com
+Corroborated and field-confirmed findings are promoted a tier; lab-only
+findings that real users don't experience are demoted.
+[Full mapping →](docs/manual.md#priority-system)
 
-# Local branch only (ESLint + Semgrep)
-QA snapshot — /path/to/my-feature-branch
-```
+---
 
-Alternative trigger phrases (all invoke `run_qa_gate`):
+## Docs
 
-```
-Health check on https://myapp.com
-Is https://myapp.com ready to ship? Code at /path/to/repo
-Any red flags? /path/to/repo
-```
+| | |
+|---|---|
+| [Operating manual](docs/manual.md) | Install, per-tool reference, output shapes, troubleshooting |
+| [PSI report spec](docs/psi-report-spec.md) | How to turn a PSI audit into a written report |
 
-After the run, Claude will surface the `report_file` path. Open it in your browser for the full visual dashboard.
+MIT-compatible ISC licence. Issues and PRs welcome at
+[Hiddensound/NFunc_MCP](https://github.com/Hiddensound/NFunc_MCP).

package/dist/index.js

@@ -7,6 +7,8 @@ import { registerLighthouseTool } from "./tools/lighthouse.js";
 import { registerAccessibilityTool } from "./tools/accessibility.js";
 import { registerStaticAnalysisTool } from "./tools/staticAnalysis.js";
 import { registerQaGateTool } from "./tools/qaGate.js";
+import { registerPerformanceAuditPlanTool } from "./tools/performanceAuditPlan.js";
+import { registerPerformanceAuditTool } from "./tools/performanceAudit.js";
 /**
  * Identity comes from package.json rather than being written out here, so the
  * two cannot drift — they already had, declaring qa-mcp/0.1.0 against
@@ -44,6 +46,8 @@ registerLighthouseTool(server);
 registerAccessibilityTool(server);
 registerStaticAnalysisTool(server);
 registerQaGateTool(server);
+registerPerformanceAuditPlanTool(server);
+registerPerformanceAuditTool(server);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CACpB,YAAY,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAC1C,CAAC;QACzC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACjD,CAAC;AACH,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC;AAE7C,MAAM,CAAC,YAAY,CACjB,MAAM,EACN;IACE,WAAW,EAAE,iEAAiE;IAC9E,WAAW,EAAE,EAAE;CAChB,EACD,KAAK,IAAI,EAAE;IACT,MAAM,OAAO,GAAG;QACd,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;KAC3D,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,yBAAyB,CAAC,MAAM,CAAC,CAAC;AAClC,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACnC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAE3B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gCAAgC,EAAE,MAAM,iCAAiC,CAAC;AACnF,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CACpB,YAAY,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAC1C,CAAC;QACzC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACjD,CAAC;AACH,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC;AAE7C,MAAM,CAAC,YAAY,CACjB,MAAM,EACN;IACE,WAAW,EAAE,iEAAiE;IAC9E,WAAW,EAAE,EAAE;CAChB,EACD,KAAK,IAAI,EAAE;IACT,MAAM,OAAO,GAAG;QACd,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;KAC3D,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC/B,yBAAyB,CAAC,MAAM,CAAC,CAAC;AAClC,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACnC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,gCAAgC,CAAC,MAAM,CAAC,CAAC;AACzC,4BAA4B,CAAC,MAAM,CAAC,CAAC;AAErC,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

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;
+};