ultra11y 4.2.0 → 4.4.0

package/src/adjudicate.ts

@@ -18,7 +18,7 @@ import { readText } from "./util.js";
 import { parseSource } from "./parse/source.js";
 import { type Doc, type El, elementsByTag, attr, textContent, ancestors, snippet as elSnippet } from "./parse/html.js";
 import { parseInlineStyle } from "./color.js";
-import adjudicationJson from "./data/adjudication.json";
+import { ADJUDICATION } from "./adjudication-data.js";
 import { scTitle, getSC, hasSC, techniquesFor, allSC, guidelineTitle } from "./wcag.js";
 import { groundItems, type GroundingSummary } from "./grounding.js";
 import {
@@ -29,6 +29,7 @@ import {
   hasId,
   getCriterion,
   derivePackResults,
+  glossaryAnchorsOf,
   resolveGlossary,
   titlePlain as packTitlePlain,
   type StandardPack,
@@ -808,8 +809,8 @@ const T = {
 // rule that decides Conforming vs Non-conforming, when NA is legitimate, and the concrete
 // questions that get you there. Rendered per residual item in both languages — a criterion
 // handed to the agent with no stated decision rule is where an audit turns into an opinion.
-type LocaleText = { fr: string; en: string };
-const ADJUDICATION = adjudicationJson as Record<string, { decide: LocaleText; na?: LocaleText; questions: LocaleText[] }>;
+// The dataset itself lives in src/adjudication-data.ts, so a criterion lookup can read the
+// decision protocol without importing this module's engine dependencies.
 
 /** Cap on techniques listed per criterion: 1.1.1 alone carries 52, which would bury the
  *  decision rule under a wall of ids. The full list stays in `criteria <sc>`. */
@@ -866,21 +867,14 @@ export function renderAdjudicationReference(lang: Lang = "en"): string {
 // pack's glossary — 119 entries for RGAA — which nothing used to read. Attaching the ones
 // THIS criterion's tests actually cite makes the item self-sufficient: the agent no longer
 // has to guess what the standard means by "image porteuse d'information".
-const GLOSSARY_REF = /\[[^\]]+\]\(#([^)]+)\)/g;
 const MAX_GLOSSARY_TERMS = 8;
 const MAX_GLOSSARY_CHARS = 600;
 
-/** 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];
-}
+// `glossaryAnchorsOf` now lives in src/standards/pack.ts, next to the glossary it reads —
+// the criteria lookup and the MCP reference tools need it too, and none of them should
+// have to import the adjudication engine to get at a pure function over a criterion.
+// Re-exported here because it was part of this module's surface.
+export { glossaryAnchorsOf };
 
 function glossaryBlock(pack: StandardPack, crit: PackCriterion | undefined, lang: Lang): string[] {
   const anchors = glossaryAnchorsOf(crit).slice(0, MAX_GLOSSARY_TERMS);

package/src/adjudication-data.ts

@@ -0,0 +1,38 @@
+// The SC-keyed adjudication protocol, on its own.
+//
+// `src/data/adjudication.json` (built by scripts/build-adjudication.mjs) states, for every
+// criterion the static engine cannot settle, the rule that decides Conforming vs
+// Non-conforming, when NA is legitimate, and the questions that get you there. It is the
+// substitute for W3C's Understanding prose, which this repo deliberately does not vendor.
+//
+// It used to be reachable only through src/adjudicate.ts — which imports the discovery
+// walker, the HTML parser and the PRD renderer. A criterion LOOKUP needs the protocol and
+// none of that, so the dataset and its accessor live here and adjudicate.ts imports them.
+import adjudicationJson from "./data/adjudication.json";
+import type { Lang } from "./types.js";
+
+export type LocaleText = { fr: string; en: string };
+
+export interface AdjudicationProtocol {
+  decide: LocaleText;
+  na?: LocaleText;
+  questions: LocaleText[];
+}
+
+export const ADJUDICATION = adjudicationJson as Record<string, AdjudicationProtocol>;
+
+/** The protocol for a WCAG success criterion, or undefined when the engine settles it. */
+export function adjudicationFor(sc: string): AdjudicationProtocol | undefined {
+  return ADJUDICATION[sc];
+}
+
+/** The protocol in one language — the shape a reference lookup hands back. */
+export function adjudicationText(sc: string, lang: Lang): { decide: string; na?: string; questions: string[] } | undefined {
+  const p = ADJUDICATION[sc];
+  if (!p) return undefined;
+  return {
+    decide: p.decide[lang],
+    ...(p.na ? { na: p.na[lang] } : {}),
+    questions: p.questions.map((q) => q[lang]),
+  };
+}

package/src/check.ts

@@ -9,7 +9,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import type { AuditResult, Lang } from "./types.js";
 import { hasSC } from "./wcag.js";
-import { type StandardId, isCore, loadPack, hasId, idCaptureSource, derivePackResults } from "./standards/index.js";
+import { type StandardId, criterionCoverage, isCore, loadPack, hasId, idCaptureSource, derivePackResults } from "./standards/index.js";
 import { buildWorklist, applyVerdicts, type VerifyItem } from "./verify.js";
 import { groundItems } from "./grounding.js";
 import { isPagesReport } from "./pages-report.js";
@@ -36,6 +36,8 @@ const M = {
     semanticUnreadable: (p: string) => `Gate sémantique : artefact de verdicts illisible ou JSON invalide : ${p}.`,
     semanticGate: (failed: number, total: number) => `Gate sémantique : ${failed}/${total} verdict(s) en échec (non statué, réfuté, non étayé ou non couvert).`,
     semanticGround: (issue: string) => `Gate sémantique : ${issue}`,
+    unevidenced: (id: string, tier: string, tool: string) =>
+      `Conformité non étayée : ${id} est déclaré conforme, mais ce critère se tranche au ${tier} et cet audit n'a produit aucune preuve de ce type. Lancez ${tool}, puis ré-auditez — ou laissez le critère « à évaluer ».`,
   },
   en: {
     section: (n: number) => `Section ${n} missing from the report.`,
@@ -53,6 +55,8 @@ const M = {
     semanticUnreadable: (p: string) => `Semantic gate: verdicts artifact unreadable or invalid JSON: ${p}.`,
     semanticGate: (failed: number, total: number) => `Semantic gate: ${failed}/${total} verdict(s) failing (unadjudicated, refuted, unsupported or uncovered).`,
     semanticGround: (issue: string) => `Semantic gate: ${issue}`,
+    unevidenced: (id: string, tier: string, tool: string) =>
+      `Unevidenced conformity: ${id} is declared conformant, but this criterion is decided on the ${tier} and this audit produced no evidence of that kind. Run ${tool}, then re-audit — or leave the criterion "to assess".`,
   },
 } as const;
 
@@ -167,9 +171,55 @@ export function checkReport(md: string, standard: StandardId = "wcag", lang: Lan
     for (const id of derivedNc) if (!reportNc.has(id)) issues.push(s.underProject(id));
   }
 
+  // 6. evidence gate: a criterion the report declares CONFORMANT whose verdict can only
+  // come from a tier this audit never ran.
+  //
+  // Contrast, focus visibility and reflow are not decided by reading source — they are
+  // measured on a render. An audit that never rendered anything and still publishes them
+  // as conformant is making the one claim this tool must never make: a pass nobody tested.
+  //
+  // Scoped deliberately tight, so it refuses only what is unambiguously wrong:
+  //   · needs `opts.audit` — without it there is no way to know what evidence exists;
+  //   · reads only the ENGINE-decided half of section 3. An agent that rules a rendering
+  //     criterion conformant has looked at something this audit cannot see, and section 3
+  //     already separates that claim under its own heading;
+  //   · treats an ABSENT `pagesAudited` as unknown, never as zero — an audit written
+  //     before that field existed must not start failing.
+  if (opts.audit) {
+    const engineC = sectionBody(md, 3).split(/^###\s/m)[0] ?? "";
+    const cItem = new RegExp(`^-\\s+(?:[A-Za-z]+\\s+)?(${idGrammar})\\s*—`, "gm");
+    const scanned = hasScanEvidence(opts.audit);
+    const rendered = hasRenderedEvidence(opts.audit);
+    const claimed = new Set<string>();
+    let m: RegExpExecArray | null;
+    while ((m = cItem.exec(engineC))) claimed.add(m[1]!);
+    for (const id of claimed) {
+      const tier = criterionCoverage(standard, id)?.tier;
+      if (tier === "browser" && !scanned) issues.push(s.unevidenced(id, core ? "browser" : "navigateur", "`ultra11y scan <target> --merge`"));
+      else if (tier === "rendered-page" && rendered === false && !scanned) {
+        issues.push(s.unevidenced(id, core ? "rendered page" : "rendu de page", "`ultra11y render` (or an E2E capture)"));
+      }
+    }
+  }
+
   return { ok: issues.length === 0, issues };
 }
 
+/** Did a dynamic scan actually run? Either it recorded which SCs it measured, or its
+ *  engines left findings behind. Same signal `untestedNeedsRendering` reads. */
+function hasScanEvidence(r: AuditResult): boolean {
+  if ((r.scope.scan?.testedScs ?? []).length > 0) return true;
+  return r.findings.some((f) => f.ruleId.startsWith("dyn-") || f.ruleId.startsWith("axe:"));
+}
+
+/** Was a page snapshot audited? `undefined` means UNKNOWN (an audit predating the field),
+ *  and unknown must never be read as "no" — that would fail an old report on a technicality. */
+function hasRenderedEvidence(r: AuditResult): boolean | undefined {
+  if (r.findings.some((f) => f.ruleId.startsWith("rendered-"))) return true;
+  const audited = r.scope.pagesAudited;
+  return audited === undefined ? undefined : audited.length > 0;
+}
+
 /** The set of criterion ids the report presents as non-conformant — parsed from the
  *  section-2 auditor blocks' "**<criterion>** : <id> — …" lines (the theme line "8." can't
  *  match the 2-segment id grammar, so it's never mistaken for a criterion). */

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { realpathSync, writeFileSync, mkdirSync, existsSync, readFileSync, appendFileSync, copyFileSync } from "node:fs";
-import { join, relative, sep, dirname } from "node:path";
+import { join, relative, resolve, sep, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import {
   VERSION,
@@ -3720,7 +3720,11 @@ export async function main(argv: string[]): Promise<number> {
           .map((s) => s.trim())
           .filter(Boolean)
       : [];
-  const loaded = loadRuntimeStandards(process.cwd(), packList, (m) => console.error(m), p.flags.override === true);
+  // `mcp --cwd <dir>` dedicates the server to another project, and a standards pack is
+  // that project's configuration — read it from THERE, not from whichever directory node
+  // happened to be started in. Every other command works on the process cwd.
+  const configRoot = p.command === "mcp" && typeof p.flags.cwd === "string" && p.flags.cwd ? resolve(p.flags.cwd) : process.cwd();
+  const loaded = loadRuntimeStandards(configRoot, packList, (m) => console.error(m), p.flags.override === true);
   if (loaded.errors.length) {
     for (const e of loaded.errors) console.error(`ultra11y: ${e}`);
     return 2;

package/src/config.ts

@@ -9,7 +9,7 @@
 import { existsSync, statSync } from "node:fs";
 import { join, isAbsolute } from "node:path";
 import { readText } from "./util.js";
-import { registerRuntimePack, getPack, enableSecondaryMapping } from "./standards/registry.js";
+import { registerRuntimePack, registerScoped, ensureScope, withScope, getPack, enableSecondaryMapping } from "./standards/registry.js";
 import { formatIssues } from "./standards/validate.js";
 import { checkGuidance } from "./pack.js";
 import { registerRuntimeGuidance, hasGuidance } from "./guidance/index.js";
@@ -90,8 +90,31 @@ function packPaths(path: string): { pack: string; glossary?: string; guidance?:
 }
 
 /** Load + register every configured/flagged pack (and its guidance) into the registries.
- *  Must run BEFORE any `resolveStandard`/`loadPack` so a runtime pack is resolvable. */
-export function loadRuntimeStandards(cwd: string, packFlags: string[], onWarn: (m: string) => void, override = false): LoadResult {
+ *  Must run BEFORE any `resolveStandard`/`loadPack` so a runtime pack is resolvable.
+ *
+ *  `opts.scope` confines the packs to one project root instead of the process-wide
+ *  registry — what a long-lived MCP server needs, since it serves many projects and two
+ *  of them may each declare a different pack under the same key. Guidance datasets stay
+ *  process-wide: they are keyed by pack key and only ever ADD examples, so a stray one
+ *  cannot change a verdict. */
+export function loadRuntimeStandards(
+  cwd: string,
+  packFlags: string[],
+  onWarn: (m: string) => void,
+  override = false,
+  opts: { scope?: string } = {},
+): LoadResult {
+  // Every READ below (`getPack` for a secondary mapping, for a guidance dataset's target
+  // pack) must see the packs this call just registered — which, under a scope, live in
+  // that scope's overlay and nowhere else.
+  return withScope(opts.scope, () => loadStandardsInto(cwd, packFlags, onWarn, override, opts));
+}
+
+function loadStandardsInto(cwd: string, packFlags: string[], onWarn: (m: string) => void, override: boolean, opts: { scope?: string }): LoadResult {
+  // Materialize the overlay up front, even when this project declares no pack of its own:
+  // a config that only enables a `secondaryMappings` entry still needs somewhere to put
+  // its copy-on-write clone of the built-in it edits.
+  if (opts.scope) ensureScope(opts.scope);
   const result: LoadResult = { errors: [], loadedPacks: [], loadedGuidance: [] };
   let config: Ultra11yConfig | null = null;
   try {
@@ -125,7 +148,7 @@ export function loadRuntimeStandards(cwd: string, packFlags: string[], onWarn: (
         onWarn(`ultra11y: ${paths.glossary} is not valid JSON — ignoring glossary.`);
       }
     }
-    const v = registerRuntimePack(packObj, glossary, { override });
+    const v = opts.scope ? registerScoped(opts.scope, packObj, glossary, { override }) : registerRuntimePack(packObj, glossary, { override });
     for (const issue of v.issues) if (issue.severity === "warn") onWarn(`ultra11y: ${raw}: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`);
     if (!v.ok || !v.pack) {
       result.errors.push(`--pack ${paths.pack}: invalid pack\n${formatIssues(v.issues).join("\n")}`);