ultra11y 2.22.0

package/src/standards/derive.ts

@@ -0,0 +1,195 @@
+// Project a WCAG-keyed AuditResult DOWN onto a pack's criteria — the inverse of the old
+// presentation-only WCAG view (former src/standard.ts). For each pack criterion, gather
+// the results of the WCAG SCs it maps to and fold them with the same NC-dominates rule.
+// Presentation-only: the canonical, gated verdict lives on the WCAG core.
+import type { AuditResult, CriterionResult, Status, Finding, Severity } from "../types.js";
+import { loadPack } from "./registry.js";
+import { knownScStatus } from "../wcag.js";
+import type { LocaleString, PackCriterion, PackOverride, SecondaryMapping, StandardPack } from "./types.js";
+
+export interface PackCriterionResult {
+  id: string;
+  theme: number;
+  status: Status;
+  findings: Finding[];
+  scs: string[]; // contributing WCAG SCs
+  // Set when EVERY WCAG SC this criterion maps to is outside the engine's WCAG 2.2 AA
+  // core (out-of-core AAA, or removed) — the engine has no core SC to project a verdict
+  // from, so it's neither a genuine C/NC/NA, just permanently out of scope (status
+  // "manual" — see src/report.ts renderPackReport for the dedicated justification).
+  outOfScope?: boolean;
+  // Set when a mapped SC DID fail, but on elements outside this criterion's applicability
+  // scope (per the pack's `appliesTo`) — so the criterion is NOT non-conformant off a
+  // sibling's failure. It derives as `manual` (assess separately) with a dedicated
+  // scoped-out justification (see src/report.ts renderPackReport).
+  scopedOut?: boolean;
+}
+
+// NC dominates (a real failure anywhere fails the criterion); then a decided C; then
+// manual (residual); else NA. Mirrors the core's aggregation.
+function aggregate(statuses: Status[]): Status {
+  if (statuses.includes("NC")) return "NC";
+  if (statuses.includes("C")) return "C";
+  if (statuses.includes("manual")) return "manual";
+  return "NA";
+}
+
+/** Does a finding's ruleId satisfy one of a criterion's applicability patterns?
+ *  Exact match, or a "prefix:*" wildcard (axe:* / dyn-* / agent:*), or a bare "*". */
+function ruleMatches(ruleId: string, patterns: string[]): boolean {
+  for (const p of patterns) {
+    if (p === "*") return true;
+    if (p.endsWith(":*") || p.endsWith("-*")) {
+      if (ruleId.startsWith(p.slice(0, -1))) return true;
+    } else if (p === ruleId) return true;
+  }
+  return false;
+}
+
+/** Which of a pack's criterion ids a single finding maps onto — the same wcag/appliesTo
+ *  projection `derivePackResults` runs per-criterion, exposed per-finding for callers that
+ *  render one finding at a time (e.g. src/report.ts's per-page section) rather than the
+ *  full aggregated view. A criterion's id is included iff its `wcag` list contains the
+ *  finding's SC AND (legacy fan-out when the criterion has no `appliesTo`, or the
+ *  finding's ruleId matches one of its `appliesTo.ruleIds` patterns via `ruleMatches`).
+ *  Usually one id; can be several (e.g. `contrast-literal` → RGAA 3.2 + 10.5); can be
+ *  none when the pack has no criterion mapped to this finding's SC (caller falls back to
+ *  the WCAG SC id). */
+export function packCriteriaForFinding(pack: StandardPack, finding: Finding): string[] {
+  return pack.criteria
+    .filter((pc) => pc.wcag.includes(finding.criteriaId) && (!pc.appliesTo || ruleMatches(finding.ruleId, pc.appliesTo.ruleIds)))
+    .map((pc) => pc.id);
+}
+
+/** The pack-projection pass rate: C ÷ (C + NC) over the pack's own criteria (NOT the core
+ *  WCAG criteria) — the same basis the pack report's per-criterion NC table already uses.
+ *  Mirrors the core denominator-zero convention (src/audit.ts conformancePct): no decided
+ *  criterion ⇒ 100, never a divide-by-zero. `manual`/`NA` criteria don't enter the ratio,
+ *  same as core. Exists so a pack report's header rate can't drift from its own table once
+ *  pack overrides (advisory/severity flips) make the two diverge from core `conformancePct`. */
+export function packConformancePct(derived: PackCriterionResult[]): number {
+  const c = derived.filter((d) => d.status === "C").length;
+  const nc = derived.filter((d) => d.status === "NC").length;
+  return c + nc === 0 ? 100 : Math.round((c / (c + nc)) * 100);
+}
+
+/** Apply a pack's normativity/severity overrides to a finding WITHIN the pack projection.
+ *  Returns a COPY when an override applies (the core finding is never mutated), or the
+ *  original reference when there is nothing to change. */
+function overrideFinding(f: Finding, overrides: Record<string, PackOverride> | undefined): Finding {
+  const o = overrides?.[f.ruleId];
+  if (!o) return f;
+  const patched: Finding = { ...f };
+  if (o.advisory !== undefined) patched.advisory = o.advisory;
+  if (o.severity) patched.severity = o.severity as Severity;
+  return patched;
+}
+
+/** Resolve a mapping's localized note to a single display string at derive time (no lang in
+ *  scope): prefer the pack's default locale, then en/fr, then any present value. */
+function pickLocale(ls: LocaleString | undefined, preferred: string): string | undefined {
+  if (!ls) return undefined;
+  return ls[preferred] ?? ls.en ?? ls.fr ?? Object.values(ls).find((v): v is string => typeof v === "string");
+}
+
+/** Copy-tag a finding as projected via a secondary mapping (copy-on-write — the core
+ *  finding is never mutated, mirroring `overrideFinding`). Carries the resolved deviation
+ *  note so the auditor block can append it. */
+function tagSecondary(f: Finding, note: string | undefined): Finding {
+  return { ...f, secondary: note ? { note } : {} };
+}
+
+/** Apply a pack's ENABLED secondary crosswalk mappings to one criterion's base result. For
+ *  every enabled mapping targeting `pc`, gather source findings whose ruleId matches EXACTLY
+ *  (bypassing both the SC gate and the appliesTo/ruleMatches gate), copy-tag them, attach,
+ *  and let a normative one drive the criterion to NC (re-aggregation: NC dominates). A base
+ *  with no active/matching mapping is returned untouched. */
+function applySecondaryMappings(
+  base: PackCriterionResult,
+  pc: PackCriterion,
+  enabled: SecondaryMapping[],
+  sources: Finding[],
+  defaultLocale: string,
+): PackCriterionResult {
+  const active = enabled.filter((m) => m.criterion === pc.id);
+  if (!active.length) return base;
+  const added: Finding[] = [];
+  for (const m of active) for (const f of sources) if (f.ruleId === m.ruleId) added.push(tagSecondary(f, pickLocale(m.note, defaultLocale)));
+  if (!added.length) return base;
+  const findings = [...base.findings, ...added];
+  // A normative secondary finding drives NC (aggregate: NC dominates), and supersedes an
+  // out-of-scope/scoped-out base verdict; an advisory-only one just rides along for display.
+  if (added.some((f) => !f.advisory)) return { id: pc.id, theme: pc.theme, status: aggregate([base.status, "NC"]), findings, scs: base.scs };
+  return { ...base, findings };
+}
+
+export function derivePackResults(audit: AuditResult, packKey: string): PackCriterionResult[] {
+  const pack = loadPack(packKey);
+  const byScId = new Map(audit.criteria.map((c) => [c.id, c]));
+  // Declarative pack-rule findings belonging to THIS pack (namespaced pack:<key>:). They
+  // ride in the audit's dedicated `packFindings` list (never the core criteria), and are
+  // routed onto a criterion here via the same appliesTo/ruleMatches machinery as engine
+  // findings, keyed by the SC the rule declared.
+  const myPackFindings = (audit.packFindings ?? []).filter((f) => f.ruleId.startsWith(`pack:${packKey}:`));
+  const overrides = pack.overrides;
+  const deriveBase = (pc: PackCriterion): PackCriterionResult => {
+    // A criterion whose WCAG mapping is ENTIRELY outside the engine's core (e.g. RGAA 8.1
+    // → only the removed 4.1.1, or a hypothetical pack criterion citing only an AAA SC)
+    // has no core SC the engine could ever audit — it's out of scope, not a silent NA.
+    const outOfScope = pc.wcag.every((sc) => {
+      const s = knownScStatus(sc);
+      return s === "out-of-core" || s === "removed";
+    });
+    if (outOfScope) {
+      return { id: pc.id, theme: pc.theme, status: "manual" as Status, findings: [], scs: pc.wcag, outOfScope: true };
+    }
+    const scResults = pc.wcag.map((sc) => byScId.get(sc)).filter((x): x is CriterionResult => !!x);
+    // Declarative pack findings whose declared SC this criterion maps to — merged with the
+    // core SC findings, then run through the pack's overrides (advisory/severity flips that
+    // apply ONLY in this projection; the core copies are never mutated).
+    const packFs = myPackFindings.filter((f) => pc.wcag.includes(f.criteriaId));
+    const allFindings = [...scResults.flatMap((r) => r.findings), ...packFs].map((f) => overrideFinding(f, overrides));
+
+    // No applicability data (third-party pack) → legacy fan-out: every mapped SC's
+    // findings attach (advisory ones project too, so a pack view can render the
+    // recommendation) and the SC statuses aggregate directly. The SC status already
+    // excludes advisory findings (src/audit.ts finalize), so the aggregate is NC-clean.
+    if (!pc.appliesTo) {
+      const status: Status = scResults.length ? aggregate(scResults.map((r) => r.status)) : "NA";
+      return { id: pc.id, theme: pc.theme, status, findings: allFindings, scs: pc.wcag };
+    }
+
+    // Applicability-aware projection: a finding attaches ONLY if its rule is one this
+    // criterion can actually be non-conformant on. NC is driven by NON-ADVISORY findings
+    // only; advisory findings still attach (so the pack report/PRD renders the
+    // recommendation) but never flip the criterion to NC.
+    const findings = allFindings.filter((f) => ruleMatches(f.ruleId, pc.appliesTo!.ruleIds));
+    const normativeFindings = findings.filter((f) => !f.advisory);
+    if (normativeFindings.length) {
+      return { id: pc.id, theme: pc.theme, status: "NC" as Status, findings, scs: pc.wcag };
+    }
+    // No NORMATIVE finding attaches. A mapped SC may still be NC, but on out-of-scope
+    // elements (a sibling criterion's failure) — that NC is NOT ours: derive as manual
+    // (assess separately), never a foreign NC. Any advisory findings that DO belong here
+    // still attach for display (a recommendation, never a non-conformity). This ordering
+    // matters: an attached advisory recommendation must not let a scoped-out sibling NC
+    // silently flip us to a foreign verdict.
+    if (scResults.some((r) => r.status === "NC")) {
+      return { id: pc.id, theme: pc.theme, status: "manual" as Status, findings, scs: pc.wcag, scopedOut: true };
+    }
+    // Otherwise the ordinary non-NC aggregate (C / manual / NA) over the mapped SCs, with
+    // any advisory findings kept on the result so the pack view surfaces them.
+    const status: Status = scResults.length ? aggregate(scResults.map((r) => r.status)) : "NA";
+    return { id: pc.id, theme: pc.theme, status, findings, scs: pc.wcag };
+  };
+
+  // Secondary crosswalk projections (opt-in, config-enabled). Sourced from EVERY audit
+  // finding (core SC findings + this pack's declarative pack findings), matched by EXACT
+  // ruleId — so a sibling rule on the same SC is never pulled onto the secondary criterion.
+  const enabledSecondary = (pack.secondaryMappings ?? []).filter((m) => m.enabled === true);
+  const secondarySources = enabledSecondary.length ? [...audit.criteria.flatMap((c) => c.findings), ...myPackFindings] : [];
+  return pack.criteria.map((pc) => {
+    const base = deriveBase(pc);
+    return enabledSecondary.length ? applySecondaryMappings(base, pc, enabledSecondary, secondarySources, pack.defaultLocale) : base;
+  });
+}

package/src/standards/index.ts

@@ -0,0 +1,31 @@
+// Barrel + the `--standard <id>` resolver. `StandardId` is either the reserved core key
+// "wcag" or a registered pack key. The default is the WCAG core; an unknown value throws
+// (never a silent fallback).
+import { CORE_KEY, hasStandard, isCore, listStandards, loadPack } from "./registry.js";
+
+export type StandardId = string;
+export const CORE: StandardId = CORE_KEY;
+
+export function resolveStandard(flag: string | boolean | undefined): StandardId {
+  if (flag === undefined || flag === true || flag === "") return CORE_KEY;
+  const key = String(flag).toLowerCase();
+  if (!hasStandard(key)) {
+    throw new Error(`unknown standard "${key}" (known: ${listStandards().join(", ")})`);
+  }
+  return key;
+}
+
+/** Display label for the active standard: "WCAG 2.2 AA" for the core, "<pack name>
+ *  <baseVersion>" for a pack (e.g. "RGAA 4.1.2"). Was duplicated as `stdLabel()` in both
+ *  auditor.ts and prd.ts. */
+export function standardLabel(standard: StandardId): string {
+  if (isCore(standard)) return "WCAG 2.2 AA";
+  const p = loadPack(standard);
+  return `${p.name} ${p.baseVersion}`;
+}
+
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./pack.js";
+export * from "./derive.js";
+export * from "./vocabulary.js";

package/src/standards/pack-rules.ts

@@ -0,0 +1,111 @@
+// The bounded interpreter for a pack's declarative RULES (src/standards/types.ts
+// `PackRule`). It runs AFTER the core engine rules in the audit pipeline (src/audit.ts
+// foldDoc) over the SAME parsed Doc, and turns each matching element into a namespaced
+// `pack:<packKey>:<id>` Finding. There is NO code path here that executes pack-supplied
+// code — a rule is pure data (tag / attribute / visible-text predicates + bounded
+// descendant conditions), so a `--pack`-loaded pack stays fully validatable (see
+// validatePack) and can never run arbitrary logic.
+import type { El, Doc } from "../parse/html.js";
+import { descendants, visibleText, snippet as sourceSnippet } from "../parse/html.js";
+import { isFullDocument, selectorOf } from "../rules/rule.js";
+import type { Finding } from "../types.js";
+import type { StandardPack, PackRule, MatchNode, MatchAttr, MatchText } from "./types.js";
+
+// Mirrors the validator's depth cap (src/standards/validate.ts MAX_MATCH_DEPTH): a
+// registered pack is already validated, so the interpreter never sees over-deep nesting —
+// this is a defensive belt only.
+const MAX_MATCH_DEPTH = 3;
+
+// Compile the (already ReDoS-validated) regexes case-insensitively, memoized per pattern
+// so a rule's regex is built once, not once per element.
+const regexCache = new Map<string, RegExp>();
+function compile(pattern: string): RegExp {
+  let re = regexCache.get(pattern);
+  if (!re) {
+    re = new RegExp(pattern, "i");
+    regexCache.set(pattern, re);
+  }
+  return re;
+}
+
+function matchAttr(el: El, a: MatchAttr): boolean {
+  const v = el.attribs[a.name.toLowerCase()];
+  switch (a.op) {
+    case "present":
+      return v !== undefined;
+    case "absent":
+      return v === undefined;
+    case "equals":
+      return v !== undefined && v === a.value;
+    case "matches":
+      return v !== undefined && a.value !== undefined && compile(a.value).test(v);
+    default:
+      return false;
+  }
+}
+
+function matchText(el: El, t: MatchText): boolean {
+  const text = visibleText(el);
+  const hit = compile(t.value).test(text);
+  return t.op === "matches" ? hit : !hit;
+}
+
+function matchNode(el: El, node: MatchNode, depth: number): boolean {
+  if (depth > MAX_MATCH_DEPTH) return false;
+  if (node.tag && el.tag.toLowerCase() !== node.tag.toLowerCase()) return false;
+  if (node.attrs && !node.attrs.every((a) => matchAttr(el, a))) return false;
+  if (node.text && !matchText(el, node.text)) return false;
+  // `has`: every listed sub-condition must match SOME descendant.
+  if (node.has || node.lacks) {
+    const desc = descendants(el);
+    if (node.has && !node.has.every((sub) => desc.some((d) => matchNode(d, sub, depth + 1)))) return false;
+    // `lacks`: NO listed sub-condition may match ANY descendant.
+    if (node.lacks && node.lacks.some((sub) => desc.some((d) => matchNode(d, sub, depth + 1)))) return false;
+  }
+  return true;
+}
+
+function toFinding(doc: Doc, el: El, rule: PackRule, packKey: string): Finding {
+  // Canonical English bake per the Finding contract (message = AI-facing English); the
+  // validator guarantees both en + fr are present. The localized {en,fr} pair also rides
+  // on `i18n` so a renderer at `--lang fr` resolves the French text (src/messages.ts
+  // resolveMessage), rather than falling back to this English bake.
+  const message = rule.message.en ?? rule.message.fr ?? rule.id;
+  const remediation = rule.remediation.en ?? rule.remediation.fr ?? "";
+  return {
+    ruleId: `pack:${packKey}:${rule.id}`,
+    criteriaId: rule.wcag[0]!,
+    file: doc.file,
+    line: el.line,
+    col: el.col,
+    selectorHint: selectorOf(el),
+    severity: rule.severity,
+    message,
+    remediation,
+    snippet: sourceSnippet(doc, el),
+    sourceStart: el.start,
+    sourceEnd: el.end,
+    i18n: {
+      message: { en: rule.message.en, fr: rule.message.fr },
+      remediation: { en: rule.remediation.en, fr: rule.remediation.fr },
+    },
+    ...(rule.advisory ? { advisory: true } : {}),
+  };
+}
+
+/** Run every declarative rule of `pack` over `doc`, returning the namespaced findings
+ *  (empty when the pack ships no rules). Standard-agnostic: the audit pass runs this for
+ *  every registered pack; each pack's findings surface only in ITS OWN projection. */
+export function runPackRules(doc: Doc, pack: StandardPack): Finding[] {
+  const rules = pack.rules;
+  if (!rules || rules.length === 0) return [];
+  const out: Finding[] = [];
+  const fullDoc = isFullDocument(doc);
+  for (const rule of rules) {
+    if (rule.match.scope === "page" && !fullDoc) continue;
+    for (const el of doc.elements) {
+      if (matchNode(el, rule.match, 1)) out.push(toFinding(doc, el, rule, pack.key));
+    }
+  }
+  return out;
+}

package/src/standards/pack.ts

@@ -0,0 +1,81 @@
+// Generic pack loader: localized lookups over a StandardPack (the genericized
+// successor of the old src/rgaa.ts criterion/theme/glossary helpers).
+import type { StandardPack, PackCriterion, LocaleString } from "./types.js";
+import type { Lang, GlossaryEntry } from "../types.js";
+import { packGlossary } from "./registry.js";
+
+/** Resolve a localized string: requested lang → pack default → English → first available.
+ *  `lang` is deliberately `string`, not the UI frame's `Lang` — a pack's own locales
+ *  (`LocaleString` keys) are not constrained to "fr"|"en" (see src/standards/types.ts). */
+export function localize(pack: StandardPack, s: LocaleString | undefined, lang: string): string {
+  if (!s) return "";
+  return s[lang] ?? s[pack.defaultLocale] ?? s.en ?? Object.values(s)[0] ?? "";
+}
+
+export function allCriteria(pack: StandardPack): PackCriterion[] {
+  return pack.criteria;
+}
+
+export function getCriterion(pack: StandardPack, id: string): PackCriterion | undefined {
+  return pack.criteria.find((c) => c.id === id);
+}
+
+export function hasId(pack: StandardPack, id: string): boolean {
+  return pack.criteria.some((c) => c.id === id);
+}
+
+export function listTheme(pack: StandardPack, n: number): PackCriterion[] {
+  return pack.criteria.filter((c) => c.theme === n);
+}
+
+export function themeName(pack: StandardPack, n: number, lang: Lang): string | undefined {
+  const t = pack.themes.find((x) => x.number === n);
+  return t ? localize(pack, t.name, lang) : undefined;
+}
+
+export function title(pack: StandardPack, c: PackCriterion, lang: Lang): string {
+  return localize(pack, c.title, lang);
+}
+
+export function titlePlain(pack: StandardPack, c: PackCriterion, lang: Lang): string {
+  return localize(pack, c.titlePlain, lang);
+}
+
+export function resolveGlossary(packKey: string, anchor: string): GlossaryEntry | undefined {
+  return packGlossary(packKey)?.[anchor];
+}
+
+/** 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 (`(?:`, `(?=`,
+ *  `(?!`, `(?<=`, `(?<!`, a named group `(?<name>`…). Used by `idCaptureSource` so a
+ *  pack `idPattern` that itself contains capturing groups (e.g. `^E(\d+)\.(\d+)$`,
+ *  legal and accepted by `validatePack`) can never shift the positional captures of a
+ *  caller (check.ts/verify.ts's NC-header regex reads title/file/line/selector by
+ *  index) — after neutralization, embedding the result as ONE outer group always
+ *  contributes exactly that one capturing group, regardless of pack authoring. */
+export function neutralizeCaptureGroups(pattern: string): string {
+  let out = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]!;
+    if (ch === "\\") {
+      out += ch + (pattern[i + 1] ?? "");
+      i++;
+      continue;
+    }
+    out += ch === "(" && pattern[i + 1] !== "?" ? "(?:" : ch;
+  }
+  return out;
+}
+
+/** The pack's `idPattern` with its full-match anchors (`^`/`$`) stripped and its own
+ *  capturing groups neutralized (see `neutralizeCaptureGroups`), for embedding as a
+ *  SINGLE capture group inside a larger line pattern — the generic seam `check.ts`/
+ *  `verify.ts` use to recognize THIS standard's own criterion-id grammar in a rendered
+ *  report (WCAG's fixed 3-segment "1.4.3", or a pack's own shape: RGAA "8.3", a
+ *  hypothetical Section 508 "E205.4"…). `idPattern` is validated compilable by
+ *  `validatePack` before a pack is ever registered, so this is always a legal regex
+ *  source. */
+export function idCaptureSource(pack: StandardPack): string {
+  return neutralizeCaptureGroups(pack.idPattern.replace(/^\^/, "").replace(/\$$/, ""));
+}

package/src/standards/registry.ts

@@ -0,0 +1,100 @@
+// The standards registry: the WCAG 2.2 core ("wcag", canonical, lives in src/wcag.ts)
+// 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 rgaaPack from "../data/standards/rgaa.json";
+import rgaaGlossary from "../data/standards/rgaa.glossary.json";
+import type { LocaleString, StandardPack } from "./types.js";
+import type { Glossary } from "../types.js";
+import { validatePack, type PackValidation } from "./validate.js";
+
+export const CORE_KEY = "wcag";
+
+interface Registered {
+  pack: StandardPack;
+  glossary: Glossary;
+}
+
+const registry = new Map<string, Registered>();
+
+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 });
+}
+
+register(rgaaPack as unknown as StandardPack, rgaaGlossary as unknown as Glossary);
+
+/**
+ * Register an EXTERNAL pack at runtime (from `--pack` / `.ultra11yrc.json`) — the
+ * pluggable counterpart to the build-time `register` above. It runs the shared
+ * `validatePack` guardrail first; on ANY error-severity issue it does not register and
+ * returns the validation so the caller can fail loudly (never a silent accept). A key
+ * that collides with a built-in/loaded standard is an error unless `opts.override`.
+ */
+export function registerRuntimePack(raw: unknown, glossary: Glossary = {}, opts: { override?: boolean } = {}): PackValidation {
+  const v = validatePack(raw, { knownKeys: new Set(listStandards()), allowOverride: opts.override });
+  if (v.ok && v.pack) registry.set(v.pack.key, { pack: v.pack, glossary });
+  return v;
+}
+
+/**
+ * Activate a SECONDARY crosswalk mapping on an already-registered pack (from
+ * `.ultra11yrc.json` — see src/config.ts `loadRuntimeStandards`). Flips `enabled: true` on
+ * a pack-shipped mapping matching the (ruleId, criterion) pair, or APPENDS a new enabled
+ * one when the pack ships none — the opt-in switch that lets a config activate the
+ * WCAG-crosswalk-bypassing projection out-of-box packs ship DISABLED. Throws on an unknown
+ * 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 list = (pack.secondaryMappings ??= []);
+  const existing = list.find((x) => x.ruleId === m.ruleId && x.criterion === m.criterion);
+  if (existing) {
+    existing.enabled = true;
+    if (m.note) existing.note = m.note;
+  } else {
+    list.push({ ruleId: m.ruleId, criterion: m.criterion, ...(m.note ? { note: m.note } : {}), enabled: true });
+  }
+}
+
+export function isCore(key: string): boolean {
+  return key === CORE_KEY;
+}
+
+export function hasStandard(key: string): boolean {
+  return key === CORE_KEY || registry.has(key);
+}
+
+/** 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"})`);
+  return r.pack;
+}
+
+export function getPack(key: string): StandardPack | undefined {
+  return registry.get(key)?.pack;
+}
+
+export function packGlossary(key: string): Glossary | undefined {
+  return registry.get(key)?.glossary;
+}
+
+/** All standard keys: the core first, then every registered pack. */
+export function listStandards(): string[] {
+  return [CORE_KEY, ...registry.keys()];
+}
+
+export function listPacks(): StandardPack[] {
+  return [...registry.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()) {
+    const ids = pack.criteria.filter((c) => c.wcag.includes(sc)).map((c) => c.id);
+    if (ids.length) out.push({ key: pack.key, ids });
+  }
+  return out;
+}