nfunc-mcp 0.2.0 → 0.4.0

package/README.md

@@ -2,36 +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)
-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 |
@@ -40,359 +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`) |
-
-### Verify the connection
-
-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" }
-   ```
-
----
+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).
 
-## Tools
+Verify with `/mcp`, then ask Claude to *"call the nfunc-mcp ping tool."*
 
-| Tool | Description | Inputs |
-|---|---|---|
-| `ping` | Health check — confirms the server is up | — |
-| `run_lighthouse` | Full Lighthouse audit for a URL | `url` |
-| `run_accessibility_check` | pa11y WCAG audit for a URL | `url`, `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` |
+[Other install options →](docs/manual.md#install-and-register)
 
 ---
 
-## 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
+## The tools
 
-Both inputs are **optional** — provide whichever you have. At least one is required.
-
-| 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. |
-
-**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 |
+| Tool | What it does |
 |---|---|
-| 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 |
-|---|---|
-| `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:
-
-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`:
-
-```json
-{
-  "report_file": "file:///tmp/qa-report-myapp-com-1234567890.html"
-}
-```
-
-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
-}
-```
-
-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"
-}
-```
+| **`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.
 
 ---
 
-## Individual tools
+## How to ask for it
 
-### run_lighthouse
-
-Runs a full Lighthouse audit against a URL.
-
-```
-Run Lighthouse on https://myapp.com
 ```
+# Full suite
+QA snapshot — https://myapp.com, code at /path/to/repo
 
-Returns: `url`, `scores` (per category), `ttfb_ms`, `findings` (priority-ordered).
-
-### 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.
+# URL only (Lighthouse + pa11y)
+QA snapshot — https://myapp.com
 
+# Local branch only (ESLint + Semgrep)
+QA snapshot — /path/to/my-feature-branch
 ```
-Run an accessibility check on https://myapp.com
-Run accessibility check at AAA standard on https://myapp.com
-```
-
-Returns: `url`, `standard`, `violation_count`, `findings`.
-
-### 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.
+These all work too:
 
 ```
-Run static analysis on /path/to/repo
+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
+Run an accessibility check on https://myapp.com using the axe runner
+Plan a PageSpeed Insights audit for https://myapp.com
 ```
 
-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
+## What makes it different from running the CLIs yourself
 
-| 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 | — | — |
+**Findings, not output.** Every result is a prioritised defect with QA-native
+prose and traceable evidence, not a wall of audit JSON.
 
-Corroborated findings are promoted one tier above where either tool would place them individually.
+**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
+## Priority levels
 
-The shortest working prompts:
-
-```
-# 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

@@ -1,14 +1,35 @@
 #!/usr/bin/env node
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerLighthouseTool } from "./tools/lighthouse.js";
 import { registerAccessibilityTool } from "./tools/accessibility.js";
 import { registerStaticAnalysisTool } from "./tools/staticAnalysis.js";
 import { registerQaGateTool } from "./tools/qaGate.js";
-const server = new McpServer({
-    name: "qa-mcp",
-    version: "0.1.0",
-});
+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
+ * nfunc-mcp/0.2.0 after the npm rename, and `npm version` would reintroduce
+ * the gap on every release if these were hardcoded.
+ *
+ * "../package.json" resolves to the repo root from both src/index.ts and
+ * dist/index.js, and npm always ships package.json, so the same path works in
+ * dev, in a local build, and in an installed package. Falls back rather than
+ * failing to boot if it is ever unreadable.
+ */
+function readIdentity() {
+    try {
+        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+        return { name: pkg.name ?? "nfunc-mcp", version: pkg.version ?? "0.0.0" };
+    }
+    catch {
+        return { name: "nfunc-mcp", version: "0.0.0" };
+    }
+}
+const server = new McpServer(readIdentity());
 server.registerTool("ping", {
     description: "Health-check tool. Returns ok status and current ISO timestamp.",
     inputSchema: {},
@@ -25,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,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,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,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/a11yDedupe.d.ts

@@ -0,0 +1,25 @@
+import type { Finding } from "../types.js";
+export interface A11yDedupeResult {
+    findings: Finding[];
+    rawCount: number;
+}
+/**
+ * Collapses the two ways pa11y over-reports a single defect.
+ *
+ * Pass 1 — exact repeats. pa11y emits one violation per occurrence, and for
+ * page-wide rules (F77, duplicate id, above all) every occurrence resolves
+ * back to the same selector. A real commerce page produced 70 of 85 findings
+ * from two defects repeated 35 times each, burying the genuine issues and
+ * flooring the qa_gate composite score. Collapsing on (rule_code, selector)
+ * removes those while keeping two different elements failing the same rule
+ * separate, since they are separate fixes.
+ *
+ * Pass 2 — systemic defects. One rule failing across many *different*
+ * elements, which (rule_code, selector) cannot catch. The axe runner produces
+ * these routinely: one mis-authored component reused across a page gave 41
+ * distinct aria-allowed-attr findings. See SYSTEMIC_THRESHOLD.
+ *
+ * Counts survive as evidence.occurrences (written only when > 1), so the
+ * volume signal is preserved without N copies of the finding.
+ */
+export declare function dedupeA11yFindings(findings: Finding[]): A11yDedupeResult;

package/dist/mappers/a11yDedupe.js

@@ -0,0 +1,95 @@
+const PRIORITY_ORDER = { P1: 0, P2: 1, P3: 2 };
+/**
+ * Above this many distinct elements failing one rule, the individual findings
+ * stop being separately actionable and start being one systemic defect — a
+ * component used everywhere, not N unrelated bugs. At or below it, each
+ * element keeps its own line.
+ *
+ * Set at 10 rather than lower because distinct elements failing the same rule
+ * are often still separate fixes: ten duplicate ids on a page are ten ids to
+ * rename, and collapsing them hides the list a developer needs. It takes a
+ * genuine flood — axe reported 41 aria-allowed-attr failures from one reused
+ * component — before the group is more useful than its members.
+ */
+const SYSTEMIC_THRESHOLD = 10;
+/**
+ * Collapses the two ways pa11y over-reports a single defect.
+ *
+ * Pass 1 — exact repeats. pa11y emits one violation per occurrence, and for
+ * page-wide rules (F77, duplicate id, above all) every occurrence resolves
+ * back to the same selector. A real commerce page produced 70 of 85 findings
+ * from two defects repeated 35 times each, burying the genuine issues and
+ * flooring the qa_gate composite score. Collapsing on (rule_code, selector)
+ * removes those while keeping two different elements failing the same rule
+ * separate, since they are separate fixes.
+ *
+ * Pass 2 — systemic defects. One rule failing across many *different*
+ * elements, which (rule_code, selector) cannot catch. The axe runner produces
+ * these routinely: one mis-authored component reused across a page gave 41
+ * distinct aria-allowed-attr findings. See SYSTEMIC_THRESHOLD.
+ *
+ * Counts survive as evidence.occurrences (written only when > 1), so the
+ * volume signal is preserved without N copies of the finding.
+ */
+export function dedupeA11yFindings(findings) {
+    // Pass 1 — exact repeats: same rule on the same selector.
+    const byKey = new Map();
+    for (const f of findings) {
+        const key = `${String(f.evidence["rule_code"] ?? "")}|` +
+            `${String(f.evidence["selector"] ?? "")}`;
+        const existing = byKey.get(key);
+        if (!existing) {
+            byKey.set(key, { finding: f, count: 1 });
+            continue;
+        }
+        existing.count += 1;
+        // pa11y can grade occurrences of one rule differently (error vs warning);
+        // keep the most severe so dedup never downgrades a defect.
+        if (PRIORITY_ORDER[f.priority] < PRIORITY_ORDER[existing.finding.priority]) {
+            existing.finding = f;
+        }
+    }
+    const exact = Array.from(byKey.values()).map(({ finding, count }) => count > 1
+        ? { ...finding, evidence: { ...finding.evidence, occurrences: count } }
+        : finding);
+    // Pass 2 — systemic defects: one rule failing across many *different*
+    // elements. htmlcs rarely does this (its repeats share a selector, which
+    // pass 1 already caught) but axe routinely does: a single mis-authored
+    // component reused across a page produced 41 separate aria-allowed-attr
+    // findings, which drowned everything else and inflated the P1 count.
+    const byRule = new Map();
+    for (const f of exact) {
+        const rule = String(f.evidence["rule_code"] ?? "");
+        const group = byRule.get(rule);
+        if (group)
+            group.push(f);
+        else
+            byRule.set(rule, [f]);
+    }
+    const out = [];
+    for (const [, group] of byRule) {
+        if (group.length <= SYSTEMIC_THRESHOLD) {
+            out.push(...group);
+            continue;
+        }
+        const worst = group.reduce((a, b) => PRIORITY_ORDER[a.priority] <= PRIORITY_ORDER[b.priority] ? a : b);
+        const elements = group.reduce((n, f) => n + Number(f.evidence["occurrences"] ?? 1), 0);
+        out.push({
+            ...worst,
+            description: `${worst.description} This rule fails on ${elements} elements across the page, ` +
+                `which usually means one shared component rather than ${elements} separate defects — ` +
+                `fix the component and all of them clear.`,
+            evidence: {
+                ...worst.evidence,
+                occurrences: elements,
+                distinct_elements: group.length,
+                systemic: true,
+                sample_selectors: group
+                    .slice(0, 10)
+                    .map((f) => String(f.evidence["selector"] ?? "")),
+            },
+        });
+    }
+    return { findings: out, rawCount: findings.length };
+}
+//# sourceMappingURL=a11yDedupe.js.map