ultra11y 2.22.0

package/src/standards/types.ts

@@ -0,0 +1,202 @@
+// Types for a STANDARDS PACK — a pluggable, in-repo country accessibility standard
+// (RGAA, Section 508, EN 301 549, AODA…) that maps its localized criteria onto WCAG
+// success criteria. The WCAG 2.2 core (src/types.ts `Sc` / src/wcag.ts) stays canonical;
+// a pack is a derived view. See CONTRIBUTING.md for the authoring contract.
+// A localized string, keyed by a BCP-47-ish locale tag ("fr", "en", "pt-BR", "de"…) — NOT
+// the UI frame's `Lang` ("fr"|"en", see src/types.ts): a pack may legitimately be
+// authored in any language (e.g. a hypothetical German-only standard), decoupled from
+// the languages the CLI's own tables (`L`) render in. `defaultLocale` (declared on the
+// pack) MUST be present; other locales are optional. English is recommended for
+// worldwide readability but a French-only standard like RGAA legitimately ships fr-only.
+export type LocaleString = Partial<Record<string, string>>;
+
+export interface PackTheme {
+  number: number;
+  name: LocaleString;
+  count: number;
+}
+
+export interface PackCriterion {
+  id: string; // pack-local id, e.g. RGAA "1.1"
+  theme: number;
+  title: LocaleString;
+  titlePlain: LocaleString;
+  tests?: Record<string, string[]>;
+  techniques?: string[];
+  technicalNote?: string[];
+  particularCases?: string[];
+  wcag: string[]; // bare WCAG SC ids this criterion maps to, e.g. ["1.1.1", "4.1.2"]
+  // Per-criterion APPLICABILITY: the engine rule ids whose findings this criterion can
+  // actually be non-conformant on. A single WCAG SC maps to MANY pack criteria (RGAA
+  // 1.1.1 → 19 criteria: informative-image, CAPTCHA, detailed-description, layout
+  // tables, downloadable documents…), so an `img-alt-missing` failure must attach ONLY
+  // to the informative-image criterion, not fan out to CAPTCHA/description/etc. A finding
+  // collected via a mapped SC attaches iff its `ruleId` matches one of these (exact, or a
+  // "prefix:*" wildcard for `axe:*`/`dyn-*`/`agent:*`). An empty list means "no engine
+  // rule can evidence this criterion" (it stays manual/NA, never NC from a sibling's
+  // failure). Optional/additive: a pack WITHOUT `appliesTo` keeps the legacy fan-out
+  // (every mapped SC's findings attach) so third-party packs are unaffected.
+  appliesTo?: { ruleIds: string[] };
+}
+
+// The localized DISPLAY vocabulary a standard uses when its audit is rendered for an
+// AUDITOR (the `prd` auditor block + GitHub issues): the NOUNS the standard gives to a
+// theme, a criterion, a test, and its three conformance verdicts, plus an optional
+// section heading and a bespoke normative note. Every field is optional and localized —
+// missing terms fall back to a generic default and the WCAG core keeps its own set (see
+// src/standards/vocabulary.ts), so a pack that omits `vocabulary` still renders. This is
+// what lets the auditor output speak each country's language rather than hardcoding RGAA
+// ("Thématique / Critère / Test / C-NC-NA") or WCAG ("Principle · Guideline / Success
+// criterion / Technique / Pass-Fail").
+export interface PackVocabulary {
+  theme?: LocaleString; // grouping noun, e.g. RGAA "Thématique"
+  criterion?: LocaleString; // item noun, e.g. "Critère"
+  test?: LocaleString; // sub-item noun, e.g. "Test"
+  conformant?: LocaleString; // verdict, e.g. "Conforme (C)"
+  nonConformant?: LocaleString; // verdict, e.g. "Non conforme (NC)"
+  notApplicable?: LocaleString; // verdict, e.g. "Non applicable (NA)"
+  auditorHeading?: LocaleString; // section/doc title, e.g. "Critère d'accessibilité"
+  normativeNote?: LocaleString; // overrides the composed "Lecture auditeur — …" blockquote
+}
+
+// The NORMATIVE page-sample methodology for a standard — the REQUIRED page KINDS a real
+// audit of it must cover. Standard-agnostic sample MECHANICS live in the core
+// (src/types.ts SampleConfig + src/sample.ts); this pack field carries only the standard's
+// own required-kinds LIST (RGAA: accueil, contact, mentions légales, déclaration
+// d'accessibilité, plan du site, aide, authentification, pages représentatives + éléments
+// transverses). Advisory: `ultra11y sample check` / `scan --sample` report which kinds the
+// configured sample lacks (fuzzy match on a page's name/notes/url) — never a hard gate.
+export interface SampleRequiredKind {
+  id: string; // slug, e.g. "mentions-legales"
+  label: LocaleString; // display label, e.g. { fr: "Mentions légales" }
+  keywords: string[]; // fuzzy-match terms (accent-insensitive) against a page's name/notes/url
+}
+export interface SampleMethodology {
+  requiredKinds: SampleRequiredKind[];
+}
+
+// ---- Declarative pack RULES — a bounded, validatable matcher DSL (NO arbitrary code).
+// A pack ships its OWN detection for genuinely pack-only semantics WITHOUT forking the
+// engine: a rule matches source elements structurally and emits a namespaced finding
+// (`pack:<packKey>:<id>`) that projects onto the pack criterion it reports under. The
+// vocabulary is deliberately CAPPED at what the built-in RGAA pack needs today (tag +
+// attribute predicates + a visible-text predicate + bounded descendant conditions);
+// anything more expressive belongs in a core WCAG-keyed engine rule instead (see
+// skills/ultra11y/references/packs.md). A runtime pack loaded via `--pack` stays FULLY
+// validatable — every regex is ReDoS-guarded, nesting is depth-bounded, JS plugins are
+// rejected by construction (there is nowhere to put code).
+
+// The operators an attribute predicate may use. `equals`/`matches` require `value`;
+// `present`/`absent` ignore it. `matches` compiles the (ReDoS-guarded) value as a
+// case-insensitive regex against the attribute value.
+export type MatchOp = "present" | "absent" | "equals" | "matches";
+
+export interface MatchAttr {
+  name: string; // attribute name (case-insensitive), e.g. "href"
+  op: MatchOp;
+  value?: string; // required for equals/matches; a regex string for matches
+}
+
+// A predicate over an element's VISIBLE TEXT (whitespace-collapsed descendant text).
+// `matches` fires when the text matches the (ReDoS-guarded, case-insensitive) regex;
+// `lacks` fires when it does NOT — the negation the download-link rule needs to flag a
+// link whose visible text omits the file format/weight.
+export interface MatchText {
+  op: "matches" | "lacks";
+  value: string; // a regex string
+}
+
+// One structural condition node. All present sub-conditions must hold (AND). `has`
+// requires that EACH listed node matches SOME descendant; `lacks` requires that NONE of
+// its listed nodes matches ANY descendant. Nesting of has/lacks is depth-bounded by the
+// validator (MAX_MATCH_DEPTH).
+export interface MatchNode {
+  tag?: string; // intrinsic tag to match (case-insensitive), e.g. "a"
+  attrs?: MatchAttr[];
+  text?: MatchText;
+  has?: MatchNode[];
+  lacks?: MatchNode[];
+}
+
+// The top-level match of a rule: a MatchNode plus an optional applicability scope —
+// `page` restricts the rule to a full document (has an <html> element), `fragment`
+// (default) lets it fire on any parsed source.
+export interface PackRuleMatch extends MatchNode {
+  scope?: "page" | "fragment";
+}
+
+export interface PackRule {
+  id: string; // slug (lower-kebab); the emitted finding's ruleId is `pack:<packKey>:<id>`
+  criterion: string; // the pack criterion id this rule reports under (must exist)
+  wcag: string[]; // WCAG SC(s) the finding keys on for the core projection (must exist)
+  severity: "bloquant" | "majeur" | "mineur";
+  advisory?: boolean; // non-normative recommendation — never flips a criterion to NC
+  match: PackRuleMatch;
+  message: LocaleString; // { en, fr } — both required by the validator
+  remediation: LocaleString; // { en, fr } — both required by the validator
+}
+
+// A per-pack normativity/severity OVERRIDE, keyed by a finding's ruleId (a core engine
+// rule id, or a `pack:<key>:<id>` declarative rule). Applied in `derivePackResults`
+// WITHIN THIS PACK'S PROJECTION ONLY — the core WCAG result is untouched. This is the
+// precise "WCAG can differ from RGAA" mechanism: a pack can re-normativize a
+// core-advisory finding (advisory→normative, or the reverse) and re-grade its severity
+// inside its own view.
+export interface PackOverride {
+  advisory?: boolean;
+  severity?: "bloquant" | "majeur" | "mineur";
+}
+
+// A GENERIC secondary crosswalk projection: it declares that a finding raised under
+// `ruleId` ALSO projects onto an ADDITIONAL pack criterion whose official WCAG crosswalk
+// does NOT contain the finding's SC. This is the explicit, opt-in DEVIATION from the
+// SC-faithful projection — the standard-agnostic mechanism a country pack (or a
+// `.ultra11yrc.json`) uses when its own body classifies a defect under a criterion the
+// WCAG mapping alone would never reach. Shipped DISABLED (`enabled` absent/false) so the
+// out-of-box projection stays WCAG-faithful; a config activates it (see src/config.ts +
+// registry.enableSecondaryMapping). Matching is by EXACT `ruleId` in `derivePackResults`,
+// bypassing BOTH the SC gate and the appliesTo/ruleMatches gate — so sibling rules on the
+// same SC are never pulled in. A tagged secondary finding DRIVES status (NC), like any
+// normative finding; there is no annotate-only variant.
+export interface SecondaryMapping {
+  ruleId: string; // an engine rule id (or a `pack:<key>:<id>` declarative rule) — EXACT match
+  criterion: string; // the ADDITIONAL pack criterion id this ruleId also projects onto (must exist)
+  note?: LocaleString; // optional localized note explaining the deviation, rendered on the finding
+  enabled?: boolean; // opt-in switch; absent/false ⇒ inert (WCAG-faithful default)
+}
+
+export interface StandardPack {
+  key: string; // unique slug, e.g. "rgaa" (may not be the reserved core key "wcag")
+  name: string; // short display name, e.g. "RGAA"
+  fullName?: string;
+  org: string; // authoring body, e.g. "DINUM"
+  country: string; // ISO-ish code, e.g. "FR"
+  baseVersion: string; // standard version, e.g. "4.1.2"
+  wcagVersion: string; // the WCAG version the pack maps to, e.g. "2.1"
+  locales: string[]; // BCP-47-ish tags, e.g. ["fr"] or ["de"] — the pack's OWN locales,
+  // independent of the UI frame's `Lang` (see `LocaleString` above)
+  defaultLocale: string;
+  license: string;
+  source: string;
+  attribution: string;
+  idPattern: string; // regex (string) the pack's criterion ids match
+  vocabulary?: PackVocabulary; // localized auditor-display terms (optional; defaults apply)
+  sampleMethodology?: SampleMethodology; // normative required page kinds (optional; advisory lint)
+  // Declarative pack-only detection (optional). Each rule runs AFTER the core engine
+  // rules in the audit pipeline (src/audit.ts) and emits a `pack:<key>:<id>` finding that
+  // projects onto its criterion via the same appliesTo/ruleMatches machinery as engine
+  // findings. Pack findings NEVER contribute to the core WCAG verdict.
+  rules?: PackRule[];
+  // Per-pack normativity/severity overrides keyed by finding ruleId, applied only within
+  // this pack's projection (derivePackResults) — the core result is never mutated.
+  overrides?: Record<string, PackOverride>;
+  // Optional, opt-in secondary crosswalk projections (src/standards/types.ts
+  // SecondaryMapping). Each shipped DISABLED by default; a config flips one on. Applied in
+  // derivePackResults, keying by EXACT ruleId to project a finding onto an ADDITIONAL
+  // criterion whose WCAG mapping does not contain the finding's SC — the standard-agnostic
+  // "differs from the WCAG crosswalk on purpose" mechanism (RGAA 7.4 for live regions is
+  // the first consumer). The core WCAG result is never touched.
+  secondaryMappings?: SecondaryMapping[];
+  themes: PackTheme[];
+  criteria: PackCriterion[];
+}