nfunc-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,4 +1,6 @@
-# qa-mcp
+# nfunc-mcp
+
+[![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.
 
@@ -20,6 +22,8 @@ A local MCP server that gives Claude (or any MCP client) a full non-functional Q
    - [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)
@@ -28,7 +32,7 @@ A local MCP server that gives Claude (or any MCP client) a full non-functional Q
 
 ## What it does
 
-`qa-mcp` wires four QA tools into Claude's tool-use loop:
+`nfunc-mcp` wires four QA tools into Claude's tool-use loop:
 
 | Capability | Tools | What it checks |
 |---|---|---|
@@ -45,14 +49,14 @@ The `run_qa_gate` orchestrator runs all of them in parallel, cross-correlates fi
 
 ## Prerequisites
 
-The following CLI tools must be available on your PATH:
+`nfunc-mcp` is a thin wrapper around four CLI tools. Install the ones you need before registering the server:
 
-```bash
-npm install -g lighthouse      # Lighthouse
-npm install -g pa11y           # pa11y
-npm install -g eslint          # ESLint
-brew install semgrep           # Semgrep (or pip install semgrep)
-```
+| 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:
 
@@ -63,56 +67,57 @@ eslint --version
 semgrep --version
 ```
 
-If a tool is missing, the gate still runs — that tool's scorecard entry will show `UNAVAILABLE` and its findings are omitted from the report.
+**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 & build
+## Install & register
 
-```bash
-git clone <repo-url>
-cd qa-mcp
-npm install
-npm run build
-```
-
-### Scripts
-
-| 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`) |
-
----
-
-## Register with Claude Code
-
-### Option A — CLI (recommended)
+### Option A — npm (recommended, no cloning needed)
 
 ```bash
-claude mcp add qa-mcp -- node /absolute/path/to/qa-mcp/dist/index.js
+claude mcp add nfunc-mcp -- npx -y nfunc-mcp
 ```
 
-### Option B — Manual config
+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": {
-    "qa-mcp": {
-      "command": "node",
-      "args": ["/absolute/path/to/qa-mcp/dist/index.js"]
+    "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 — `qa-mcp` should show as `connected`.
-2. Ask Claude: *"Call the qa-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" }
@@ -125,10 +130,10 @@ Add to `~/.claude.json` under `mcpServers`:
 | 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_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` |
+| `run_qa_gate` | All tools in parallel + correlation + HTML report | `url` and/or `path`, `form_factor` (optional), `a11y_runner` (optional) |
 
 ---
 
@@ -145,6 +150,8 @@ Both inputs are **optional** — provide whichever you have. At least one is req
 | `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:
 ```
@@ -297,9 +304,28 @@ Runs a full Lighthouse audit against a URL.
 
 ```
 Run Lighthouse on https://myapp.com
+Run Lighthouse on https://myapp.com for mobile and desktop
 ```
 
-Returns: `url`, `scores` (per category), `ttfb_ms`, `findings` (priority-ordered).
+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
 
@@ -308,9 +334,28 @@ Runs pa11y against a URL at WCAG 2 AA by default. Returns only violations (error
 ```
 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
 ```
 
-Returns: `url`, `standard`, `violation_count`, `findings`.
+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
 

package/dist/index.js

@@ -1,14 +1,33 @@
 #!/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",
-});
+/**
+ * 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: {},

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

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

package/dist/mappers/a11yDedupe.js.map

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

package/dist/mappers/compositeScore.d.ts

@@ -0,0 +1,23 @@
+import type { Finding } from "../types.js";
+/**
+ * Lighthouse's own category scores ARE a calibrated 0–100 health signal, with
+ * per-audit weighting Google already tuned. Re-deriving one by counting
+ * findings throws that away and double-counts besides: total-blocking-time,
+ * bootup-time, mainthread-work-breakdown, interactive and max-potential-fid are
+ * five findings describing one overloaded main thread, and the old formula
+ * charged 75 points for it. So use the category scores directly.
+ */
+export declare function lighthouseSubScore(categoryScores: Record<string, number>): number | null;
+export declare function a11ySubScore(findings: Finding[]): number;
+export declare function staticSubScore(findings: Finding[]): number;
+export interface SubScores {
+    lighthouse: number | null;
+    pa11y: number | null;
+    static: number | null;
+}
+/**
+ * Weighted mean over the tools that produced a score. Weights are renormalised
+ * across whatever ran, so a url-only run and a url+path run are on the same
+ * scale. Returns null when nothing scored.
+ */
+export declare function compositeScore(sub: SubScores): number | null;

package/dist/mappers/compositeScore.js

@@ -0,0 +1,107 @@
+/**
+ * Composite health score.
+ *
+ * The previous formula was a single global subtraction — 100 minus 15 per P1,
+ * 7 per P2, 3 per P3 — which had two structural faults:
+ *
+ *  1. No resolution. Seven P1 findings floored it at 0, so a mediocre page and
+ *     a catastrophic one were indistinguishable. Real pages routinely exceed
+ *     that within a single tool.
+ *  2. Running more tools lowered the score, because every tool fed the same
+ *     running subtraction. A url-only run was not comparable to a url+path run,
+ *     which is exactly backwards: broader checking should not look like worse
+ *     health.
+ *
+ * Both are fixed by scoring each tool to its own 0–100 sub-score and taking a
+ * weighted mean over only the tools that actually ran.
+ */
+const SEVERITY_DAMAGE = { P1: 10, P2: 3, P3: 1 };
+/**
+ * Saturating decay. Never reaches 0, always preserves ordering, and each
+ * additional finding costs less than the one before — which matches how the
+ * information actually behaves: the twentieth P1 tells you far less about the
+ * page than the first did.
+ *
+ * K sets where the curve has resolution. At K = 90 a single P1 scores 89, five
+ * P1s score 57, and fifteen P1s score 19 — spread across the range real pages
+ * occupy instead of collapsing onto the floor.
+ */
+function decay(damage, k) {
+    return Math.round(100 * Math.exp(-damage / k));
+}
+function damageOf(findings) {
+    return findings.reduce((sum, f) => sum + SEVERITY_DAMAGE[f.priority], 0);
+}
+// Tuned so a page's sub-score lands where a human triager would put it. Static
+// analysis decays faster because code defects are fewer and more directly
+// actionable than page-level accessibility violations.
+const A11Y_K = 90;
+const STATIC_K = 60;
+/**
+ * Relative weights of the Lighthouse categories inside the Lighthouse
+ * sub-score. Lighthouse publishes per-audit weights but no cross-category
+ * weighting, so this is our judgement: performance and accessibility carry the
+ * most user impact, SEO and best-practices matter but less directly.
+ *
+ * Categories not listed here — currently the experimental "agentic-browsing" —
+ * get UNKNOWN_CATEGORY_WEIGHT so a new or volatile category cannot dominate the
+ * score, while still being visible in the breakdown.
+ */
+const CATEGORY_WEIGHTS = {
+    performance: 0.3,
+    accessibility: 0.3,
+    "best-practices": 0.2,
+    seo: 0.2,
+};
+const UNKNOWN_CATEGORY_WEIGHT = 0.05;
+/**
+ * Lighthouse's own category scores ARE a calibrated 0–100 health signal, with
+ * per-audit weighting Google already tuned. Re-deriving one by counting
+ * findings throws that away and double-counts besides: total-blocking-time,
+ * bootup-time, mainthread-work-breakdown, interactive and max-potential-fid are
+ * five findings describing one overloaded main thread, and the old formula
+ * charged 75 points for it. So use the category scores directly.
+ */
+export function lighthouseSubScore(categoryScores) {
+    const entries = Object.entries(categoryScores);
+    if (entries.length === 0)
+        return null;
+    let weighted = 0;
+    let totalWeight = 0;
+    for (const [name, score] of entries) {
+        const w = CATEGORY_WEIGHTS[name] ?? UNKNOWN_CATEGORY_WEIGHT;
+        weighted += w * score;
+        totalWeight += w;
+    }
+    return totalWeight > 0 ? Math.round(weighted / totalWeight) : null;
+}
+export function a11ySubScore(findings) {
+    return decay(damageOf(findings), A11Y_K);
+}
+export function staticSubScore(findings) {
+    return decay(damageOf(findings), STATIC_K);
+}
+// How much each tool contributes to the composite. Static analysis is weighted
+// lowest because a clean scan of a small directory returns 100 and would
+// otherwise flatter a run whose real problems are all in the browser.
+const TOOL_WEIGHTS = { lighthouse: 0.4, pa11y: 0.4, static: 0.2 };
+/**
+ * Weighted mean over the tools that produced a score. Weights are renormalised
+ * across whatever ran, so a url-only run and a url+path run are on the same
+ * scale. Returns null when nothing scored.
+ */
+export function compositeScore(sub) {
+    const parts = [];
+    if (sub.lighthouse !== null)
+        parts.push([sub.lighthouse, TOOL_WEIGHTS.lighthouse]);
+    if (sub.pa11y !== null)
+        parts.push([sub.pa11y, TOOL_WEIGHTS.pa11y]);
+    if (sub.static !== null)
+        parts.push([sub.static, TOOL_WEIGHTS.static]);
+    if (parts.length === 0)
+        return null;
+    const totalWeight = parts.reduce((s, [, w]) => s + w, 0);
+    const weighted = parts.reduce((s, [v, w]) => s + v * w, 0);
+    return Math.round(weighted / totalWeight);
+}
+//# sourceMappingURL=compositeScore.js.map

package/dist/mappers/compositeScore.js.map

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