ultra11y 4.2.0 → 4.4.0

package/src/standards/coverage.ts

@@ -0,0 +1,237 @@
+// What it actually takes to decide a criterion — derived, never guessed.
+//
+// Before auditing anything, an auditor needs the plan: which criteria the static engine
+// settles from source alone, which need a captured page or a real browser, and which are
+// judgment calls no tool can make. Getting that wrong in either direction is expensive — a
+// criterion wrongly filed as "the engine has it" becomes a conformance claim nobody tested.
+//
+// So every classification here is a LOOKUP over data the repo already ships:
+//
+//   - `automatability` per WCAG success criterion (src/data/wcag.json): 3 static,
+//     14 needs-rendering, 38 judgment — the 3/14/38 arithmetic quoted across the tool.
+//   - `appliesTo.ruleIds` per pack criterion: which engine rules can evidence it. EMPTY is
+//     a statement, not a gap — 58 of RGAA's 106 criteria say "no engine rule can attest
+//     this", and that fact is the single most useful thing in an audit plan.
+//   - `judgment: true` per pack criterion: the criterion asks more than its mapped SCs, so
+//     `judgmentGuard` in derive.ts refuses to let it inherit a Conforming verdict.
+//   - which registry a rule id belongs to, for the tier that produces it.
+//
+// Nothing here reads the WORDING of a test.
+import { ALL_RULES } from "../rules/registry.js";
+import { CROSS_RULES } from "../rules/cross-registry.js";
+import { allSC, getSC, knownScStatus } from "../wcag.js";
+import { allCriteria, getCriterion } from "./pack.js";
+import { isCore, loadPack } from "./registry.js";
+import type { StandardId } from "./index.js";
+import type { PackCriterion, StandardPack } from "./types.js";
+
+/** The evidence source a verdict rests on, cheapest first. */
+export type Tier = "source" | "cross-file" | "rendered-page" | "browser" | "judgment" | "out-of-scope";
+
+/** Tiers ordered by cost. `judgment` and `out-of-scope` are terminal, not cheaper/dearer. */
+const TIER_ORDER: Tier[] = ["source", "cross-file", "rendered-page", "browser"];
+
+export interface Coverage {
+  /** The cheapest tier that can prove this criterion CONFORMANT. */
+  tier: Tier;
+  /** True only when the source tree alone settles it. */
+  sourceIsEnough: boolean;
+  /**
+   * The tiers that can raise a NON-conformity on it — deliberately a separate axis.
+   * RGAA 4.10 and 8.4 are `judgment: true` (so no tool may declare them conformant) and
+   * still carry real engine rules that can fail them. Collapsing the two axes into one
+   * boolean, as a wording-heuristic must, throws that coverage away.
+   */
+  canFailFrom: Tier[];
+  /** Tiers beyond `tier` that also carry evidence. */
+  alsoNeeds: Tier[];
+  /** The engine rules declared applicable to this criterion. */
+  engineRules: string[];
+  /** False when the pack declares no applicability at all — the plan is then coarser. */
+  applicabilityDeclared: boolean;
+  /** One English sentence naming the datum that decided this. */
+  why: string;
+}
+
+const STATIC_RULE_IDS = new Set(ALL_RULES.map((r) => r.id));
+const CROSS_RULE_IDS = new Set(CROSS_RULES.map((r) => r.id));
+
+/**
+ * The tier that produces a finding with this rule id. Namespace dispatch — no regex over
+ * prose, no per-id special cases.
+ */
+export function ruleTier(ruleId: string, pack?: StandardPack): Tier {
+  // A pack's own declarative rule runs inside the static pipeline.
+  if (ruleId.startsWith("pack:")) return "source";
+  // Agent findings are the model's ruling, by construction.
+  if (ruleId.startsWith("agent:")) return "judgment";
+  // axe checks and the dynamic probes only ever come back from `scan`.
+  if (ruleId.startsWith("axe:") || ruleId.startsWith("dyn-")) return "browser";
+  // A rendered rule reads a snapshot's computed styles, boxes and screenshot — a captured
+  // page, but no live browser.
+  if (ruleId.startsWith("rendered-")) return "rendered-page";
+  if (CROSS_RULE_IDS.has(ruleId)) return "cross-file";
+  if (STATIC_RULE_IDS.has(ruleId)) return "source";
+  // A wildcard (`*`) is the legacy fan-out: it matches every engine finding, so the static
+  // tier is the honest floor. Anything else is an id no registry claims.
+  if (pack && ruleId.endsWith("*")) return "source";
+  return "source";
+}
+
+function cheapest(tiers: Tier[]): Tier | undefined {
+  for (const t of TIER_ORDER) if (tiers.includes(t)) return t;
+  return undefined;
+}
+
+function dedupe(tiers: Tier[]): Tier[] {
+  return TIER_ORDER.filter((t) => tiers.includes(t));
+}
+
+/** Coverage for one WCAG success criterion. */
+function coreCoverage(sc: string): Coverage | undefined {
+  const c = getSC(sc);
+  if (!c) return undefined;
+  const engineRules = [...c.ruleIds];
+  const tiers = engineRules.map((r) => ruleTier(r));
+
+  if (c.automatability === "judgment") {
+    return {
+      tier: "judgment",
+      sourceIsEnough: false,
+      canFailFrom: dedupe(tiers),
+      alsoNeeds: [],
+      engineRules,
+      applicabilityDeclared: true,
+      why: "WCAG automatability class `judgment`: the evidence can be gathered, but the verdict is a reading of meaning.",
+    };
+  }
+  if (c.automatability === "needs-rendering") {
+    const tier: Tier = tiers.includes("rendered-page") ? "rendered-page" : "browser";
+    return {
+      tier,
+      sourceIsEnough: false,
+      canFailFrom: dedupe(tiers),
+      alsoNeeds: dedupe(tiers).filter((t) => t !== tier),
+      engineRules,
+      applicabilityDeclared: true,
+      why:
+        tier === "rendered-page"
+          ? "WCAG automatability class `needs-rendering`, and a rendered-* rule covers it: a captured page snapshot is enough, no live browser."
+          : "WCAG automatability class `needs-rendering`: only a real browser produces this evidence.",
+    };
+  }
+  const tier = cheapest(tiers) ?? "source";
+  return {
+    tier,
+    sourceIsEnough: tier === "source",
+    canFailFrom: dedupe(tiers),
+    alsoNeeds: dedupe(tiers).filter((t) => t !== tier),
+    engineRules,
+    applicabilityDeclared: true,
+    why: "WCAG automatability class `static`: an engine rule decides it from the source tree.",
+  };
+}
+
+/**
+ * Every mapped SC sits outside the engine's WCAG 2.2 AA core (AAA, or removed).
+ *
+ * Deliberately the SAME predicate as `derivePackResults` in derive.ts — a criterion the
+ * projection files as out of scope must be the one the plan files as out of scope, or the
+ * plan is telling the auditor to gather evidence for a verdict that can never be rendered.
+ */
+function outOfCore(pc: PackCriterion): boolean {
+  return pc.wcag.every((sc) => {
+    const s = knownScStatus(sc);
+    return s === "out-of-core" || s === "removed";
+  });
+}
+
+function packCoverage(pack: StandardPack, pc: PackCriterion): Coverage {
+  if (outOfCore(pc)) {
+    return {
+      tier: "out-of-scope",
+      sourceIsEnough: false,
+      canFailFrom: [],
+      alsoNeeds: [],
+      engineRules: [],
+      applicabilityDeclared: true,
+      why: `every WCAG success criterion this maps to (${pc.wcag.join(", ")}) is outside the engine's 2.2 AA core — AAA or removed. Declare it out of scope; never claim conformity.`,
+    };
+  }
+
+  const declared = pc.appliesTo?.ruleIds;
+  if (declared === undefined) {
+    // No applicability at all: classify from the mapped SCs alone, and say the plan is
+    // coarser than it would be for a pack that declares one.
+    const tiers = pc.wcag.map((sc) => coreCoverage(sc)?.tier).filter((t): t is Tier => t !== undefined);
+    const tier = tiers.includes("judgment") ? "judgment" : (cheapest(tiers) ?? "judgment");
+    return {
+      tier,
+      sourceIsEnough: tier === "source",
+      canFailFrom: dedupe(tiers),
+      alsoNeeds: dedupe(tiers).filter((t) => t !== tier),
+      engineRules: [],
+      applicabilityDeclared: false,
+      why: "the pack declares no rule applicability, so this is inferred from the WCAG success criteria it maps to.",
+    };
+  }
+
+  const engineRules = [...declared];
+  const tiers = engineRules.map((r) => ruleTier(r, pack));
+
+  if (pc.judgment) {
+    return {
+      tier: "judgment",
+      sourceIsEnough: false,
+      canFailFrom: dedupe(tiers),
+      alsoNeeds: [],
+      engineRules,
+      applicabilityDeclared: true,
+      why: "the standard flags this criterion as judgment: it asks more than its mapped success criteria, so it never inherits a Conforming verdict — though an engine rule can still fail it.",
+    };
+  }
+  if (!engineRules.length) {
+    return {
+      tier: "judgment",
+      sourceIsEnough: false,
+      canFailFrom: [],
+      alsoNeeds: [],
+      engineRules,
+      applicabilityDeclared: true,
+      why: "the standard declares that no engine rule can evidence this criterion — it is yours to rule on.",
+    };
+  }
+  const tier = cheapest(tiers) ?? "judgment";
+  return {
+    tier,
+    sourceIsEnough: tier === "source",
+    canFailFrom: dedupe(tiers),
+    alsoNeeds: dedupe(tiers).filter((t) => t !== tier),
+    engineRules,
+    applicabilityDeclared: true,
+    why: `the standard declares ${engineRules.length} applicable engine rule${engineRules.length === 1 ? "" : "s"}; the cheapest evidence tier among them is \`${tier}\`.`,
+  };
+}
+
+/** Coverage for one criterion of any standard. Undefined when the id does not exist. */
+export function criterionCoverage(standard: StandardId, id: string): Coverage | undefined {
+  if (isCore(standard)) return coreCoverage(id);
+  const pack = loadPack(standard);
+  const pc = getCriterion(pack, id);
+  return pc ? packCoverage(pack, pc) : undefined;
+}
+
+/** Coverage for every criterion of a standard, keyed by criterion id. */
+export function standardCoverage(standard: StandardId): Map<string, Coverage> {
+  const out = new Map<string, Coverage>();
+  if (isCore(standard)) {
+    for (const c of allSC()) {
+      const cov = coreCoverage(c.sc);
+      if (cov) out.set(c.sc, cov);
+    }
+    return out;
+  }
+  const pack = loadPack(standard);
+  for (const pc of allCriteria(pack)) out.set(pc.id, packCoverage(pack, pc));
+  return out;
+}

package/src/standards/index.ts

@@ -29,3 +29,4 @@ export * from "./registry.js";
 export * from "./pack.js";
 export * from "./derive.js";
 export * from "./vocabulary.js";
+export * from "./coverage.js";

package/src/standards/pack.ts

@@ -58,6 +58,25 @@ export function resolveGlossary(packKey: string, anchor: string): GlossaryEntry
   return packGlossary(packKey)?.[anchor];
 }
 
+// A criterion's tests refer constantly to normatively-defined terms
+// (`[alternative textuelle](#alternative-textuelle-image)`). The definitions live in the
+// pack's glossary — 119 entries for RGAA — and they are normative: "relevant" and "if
+// necessary" mean what the glossary says they mean. Attaching the ones THIS criterion's
+// tests actually cite makes a criterion lookup self-sufficient.
+const GLOSSARY_REF = /\[[^\]]+\]\(#([^)]+)\)/g;
+
+/** The glossary anchors a criterion's tests / notes / particular cases refer to, in order. */
+export function glossaryAnchorsOf(crit: { tests?: Record<string, string[]>; technicalNote?: string[]; particularCases?: string[] } | undefined): string[] {
+  if (!crit) return [];
+  const texts = [...Object.values(crit.tests ?? {}).flat(), ...(crit.technicalNote ?? []), ...(crit.particularCases ?? [])];
+  const seen = new Set<string>();
+  for (const t of texts) {
+    GLOSSARY_REF.lastIndex = 0;
+    for (let m = GLOSSARY_REF.exec(t); m; m = GLOSSARY_REF.exec(t)) if (m[1]) seen.add(m[1]);
+  }
+  return [...seen];
+}
+
 /** Replace every unescaped `(` that does NOT open a special construct with a
  *  non-capturing `(?:` — i.e. neutralize the pattern's OWN capturing groups.
  *  Leaves alone: an escaped literal (`\(`) and any `(?...` construct (`(?:`, `(?=`,

package/src/standards/registry.ts

@@ -2,6 +2,7 @@
 // plus the statically-imported country PACKS. Adding a country = drop a pack JSON under
 // src/data/standards/ and add one `register(...)` line here (static imports are required
 // so tsup inlines every pack into the single zero-dependency bundle — no runtime fs/glob).
+import { AsyncLocalStorage } from "node:async_hooks";
 import rgaaPack from "../data/standards/rgaa.json";
 import rgaaGlossary from "../data/standards/rgaa.glossary.json";
 import type { LocaleString, StandardPack } from "./types.js";
@@ -17,6 +18,111 @@ interface Registered {
 
 const registry = new Map<string, Registered>();
 
+// ---- project scopes -------------------------------------------------------
+//
+// The registry above is process-wide, which is right for a CLI run: one process,
+// one project, packs resolved once at startup. A long-lived MCP server is the
+// other shape — it takes a `cwd` PER CALL, so two projects can each declare a
+// pack under the same key, and the second must not overwrite the first.
+//
+// So a scope is an OVERLAY: packs registered for one project root, consulted
+// before the global registry and invisible to every other root. Nothing that
+// runs outside a scope changes behaviour.
+//
+// The ambient scope travels in an AsyncLocalStorage rather than a module-level
+// variable, and that is load-bearing. The `audit()` helper in src/mcp/handlers.ts
+// gets away with a process-global `process.chdir` only because `runAudit` is
+// synchronous — no await point between the chdir and its `finally`, so the event
+// loop cannot interleave another project. The MCP dispatch IS async: a plain
+// "current scope" variable would race across concurrent project roots.
+const overlays = new Map<string, Map<string, Registered>>();
+const scopeStore = new AsyncLocalStorage<string>();
+
+function currentOverlay(): Map<string, Registered> | undefined {
+  const scope = scopeStore.getStore();
+  return scope === undefined ? undefined : overlays.get(scope);
+}
+
+/** The overlay's entry for `key`, else the global one. */
+function lookup(key: string): Registered | undefined {
+  return currentOverlay()?.get(key) ?? registry.get(key);
+}
+
+/** Global registrations, with the current scope's overlay laid on top. */
+function visible(): Map<string, Registered> {
+  const overlay = currentOverlay();
+  if (!overlay?.size) return registry;
+  const merged = new Map(registry);
+  for (const [key, entry] of overlay) merged.set(key, entry);
+  return merged;
+}
+
+/** Run `fn` with `scope`'s packs laid over the global registry. No scope ⇒ unchanged. */
+export function withScope<T>(scope: string | undefined, fn: () => T): T {
+  return scope === undefined ? fn() : scopeStore.run(scope, fn);
+}
+
+/**
+ * Register an external pack INTO one project scope — `registerRuntimePack`'s per-project
+ * counterpart, with the same validation guardrail. Collisions are judged against what THIS
+ * scope can see (the core, the built-ins, and packs already in this overlay), so two
+ * projects may each ship a different `section508` without either shadowing the other.
+ */
+export function registerScoped(scope: string, raw: unknown, glossary: Glossary = {}, opts: { override?: boolean } = {}): PackValidation {
+  const overlay = ensureScope(scope);
+  const known = new Set([CORE_KEY, ...registry.keys(), ...overlay.keys()]);
+  const v = validatePack(raw, { knownKeys: known, allowOverride: opts.override });
+  if (v.ok && v.pack) overlay.set(v.pack.key, { pack: v.pack, glossary });
+  return v;
+}
+
+/**
+ * The pack object to MUTATE — `enableSecondaryMapping`'s copy-on-write guard.
+ *
+ * Inside a project scope, a built-in resolves from the shared global registry, and
+ * `enableSecondaryMapping` edits its `secondaryMappings` in place. One project's
+ * `.ultra11yrc.json` would then re-key the built-in RGAA pack for every OTHER project the
+ * same server is serving — a silently different projection, which is precisely the failure
+ * this tool must never produce. So a global pack is cloned into the overlay first, and the
+ * project edits its own copy.
+ */
+function packForMutation(key: string): StandardPack {
+  const overlay = currentOverlay();
+  if (!overlay) return loadPack(key);
+  const own = overlay.get(key);
+  if (own) return own.pack;
+  const shared = registry.get(key);
+  if (!shared) return loadPack(key); // throws, with the known-packs list
+  const copy: Registered = { pack: structuredClone(shared.pack), glossary: shared.glossary };
+  overlay.set(key, copy);
+  return copy.pack;
+}
+
+/** Create the scope's (possibly empty) overlay and return it. */
+export function ensureScope(scope: string): Map<string, Registered> {
+  let overlay = overlays.get(scope);
+  if (!overlay) {
+    overlay = new Map();
+    overlays.set(scope, overlay);
+  }
+  return overlay;
+}
+
+/** Whether this scope's packs have already been resolved — the memo the MCP server reads. */
+export function scopeLoaded(scope: string): boolean {
+  return overlays.has(scope);
+}
+
+/** Forget one scope, so a failed load is retried rather than memoized as "done". */
+export function dropScope(scope: string): void {
+  overlays.delete(scope);
+}
+
+/** Test seam: forget every project scope. Never call this from product code. */
+export function resetScopes(): void {
+  overlays.clear();
+}
+
 function register(pack: StandardPack, glossary: Glossary): void {
   if (pack.key === CORE_KEY) throw new Error(`pack key "${CORE_KEY}" is reserved for the WCAG core`);
   registry.set(pack.key, { pack, glossary });
@@ -46,7 +152,7 @@ export function registerRuntimePack(raw: unknown, glossary: Glossary = {}, opts:
  * pack key (never a silent no-op). Mutates the registered pack in place, by design.
  */
 export function enableSecondaryMapping(packKey: string, m: { ruleId: string; criterion: string; note?: LocaleString }): void {
-  const pack = loadPack(packKey); // throws on unknown key
+  const pack = packForMutation(packKey); // throws on unknown key
   const list = (pack.secondaryMappings ??= []);
   const existing = list.find((x) => x.ruleId === m.ruleId && x.criterion === m.criterion);
   if (existing) {
@@ -62,37 +168,37 @@ export function isCore(key: string): boolean {
 }
 
 export function hasStandard(key: string): boolean {
-  return key === CORE_KEY || registry.has(key);
+  return key === CORE_KEY || lookup(key) !== undefined;
 }
 
 /** Resolve a pack by key; throws on unknown (never silently falls back to the core). */
 export function loadPack(key: string): StandardPack {
-  const r = registry.get(key);
-  if (!r) throw new Error(`unknown standards pack "${key}" (known packs: ${[...registry.keys()].join(", ") || "none"})`);
+  const r = lookup(key);
+  if (!r) throw new Error(`unknown standards pack "${key}" (known packs: ${[...visible().keys()].join(", ") || "none"})`);
   return r.pack;
 }
 
 export function getPack(key: string): StandardPack | undefined {
-  return registry.get(key)?.pack;
+  return lookup(key)?.pack;
 }
 
 export function packGlossary(key: string): Glossary | undefined {
-  return registry.get(key)?.glossary;
+  return lookup(key)?.glossary;
 }
 
 /** All standard keys: the core first, then every registered pack. */
 export function listStandards(): string[] {
-  return [CORE_KEY, ...registry.keys()];
+  return [CORE_KEY, ...visible().keys()];
 }
 
 export function listPacks(): StandardPack[] {
-  return [...registry.values()].map((r) => r.pack);
+  return [...visible().values()].map((r) => r.pack);
 }
 
 /** Reverse cross-reference: which packs (and their criterion ids) map to a WCAG SC. */
 export function packsForSc(sc: string): { key: string; ids: string[] }[] {
   const out: { key: string; ids: string[] }[] = [];
-  for (const { pack } of registry.values()) {
+  for (const { pack } of visible().values()) {
     const ids = pack.criteria.filter((c) => c.wcag.includes(sc)).map((c) => c.id);
     if (ids.length) out.push({ key: pack.key, ids });
   }

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "4.2.0";
+export const VERSION = "4.4.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,
@@ -69,6 +69,23 @@ export interface Sc {
   ruleIds: string[]; // engine rules contributing to this SC
   understanding: string; // W3C Understanding doc URL (manual-check grounding)
   techniques?: string[]; // language-neutral W3C technique codes
+  // The criterion's NORMATIVE wording, verbatim from the W3C source, with its exceptions
+  // and notes as labelled lines. Optional only so an older wcag.json snapshot still
+  // parses — a freshly built dataset carries it for every criterion or the build fails.
+  text?: string;
+  // The same wording from the W3C AUTHORIZED French translation. Held to the same
+  // completeness rule as `titleFr`: the build fails rather than let `--lang fr` render a
+  // French heading over English requirement prose.
+  textFr?: string;
+  // The glossary slugs this criterion's wording LINKS to in the W3C source — the defined
+  // terms it actually cites, not words that happen to appear in it.
+  terms?: string[];
+  // The same, for the French translation. The two pages do NOT share slugs — the FR page
+  // names several definitions in the plural ("user-agents" where the English source file is
+  // "user-agent") and a few differently outright ("purpose-of-each-link" for "link-purpose").
+  // Mapping one onto the other would be a guess, so each language keeps its own list and
+  // resolves against its own glossary.
+  termsFr?: string[];
   tests?: string[]; // optional manual-check lines
   notes?: string;
 }
@@ -93,6 +110,12 @@ export interface WcagData {
   principles: WcagPrinciple[];
   guidelines: WcagGuideline[];
   criteria: Sc[];
+  // The terms WCAG itself normatively defines ("text alternative", "programmatically
+  // determined"…), keyed by the W3C's own dfn slug. Optional so an older wcag.json
+  // snapshot still parses; see src/wcag.ts `coreGlossary`.
+  glossary?: Glossary;
+  // The same terms from the W3C authorized French translation, under the SAME slugs.
+  glossaryFr?: Glossary;
 }
 
 // ---- WCAG SC universe (src/data/wcag-universe.json, produced by