@a11y-oracle/audit-formatter 1.0.0

package/dist/lib/formatters.js

@@ -0,0 +1,317 @@
+/**
+ * @module formatters
+ *
+ * Pure functions that convert A11y-Oracle data into OracleIssue objects.
+ *
+ * Each function takes A11y-Oracle findings + an AuditContext and returns
+ * an array of OracleIssue objects (empty if no issues found). The functions
+ * have no side effects and do not require a CDP session or orchestrator.
+ *
+ * @example
+ * ```typescript
+ * import { formatFocusIssues } from '@a11y-oracle/audit-formatter';
+ *
+ * const state = await a11y.pressKey('Tab');
+ * const issues = formatFocusIssues(state, { project: 'my-app', specName: 'nav.spec.ts' });
+ * expect(issues).toHaveLength(0); // No focus issues
+ * ```
+ */
+import { RULES, matchesWcagLevel } from './rules.js';
+import { selectorFromFocusedElement, selectorFromTabOrderEntry, htmlSnippetFromFocusedElement, htmlSnippetFromTabOrderEntry, } from './selector.js';
+/**
+ * Analyze an A11yState for focus-related issues.
+ *
+ * Checks two rules (only one fires per state — `focus-not-visible` takes priority):
+ * - `oracle/focus-not-visible` — `focusIndicator.isVisible === false`
+ * - `oracle/focus-low-contrast` — `isVisible` but `meetsWCAG_AA === false`
+ *
+ * Returns an empty array if no element is focused or focus indicator passes.
+ *
+ * @param state - Unified accessibility state from pressKey() or getState()
+ * @param context - Audit context (project, specName)
+ * @returns Array of 0 or 1 OracleIssue
+ */
+export function formatFocusIssues(state, context) {
+    if (!state.focusedElement) {
+        return [];
+    }
+    const el = state.focusedElement;
+    const indicator = state.focusIndicator;
+    // focus-not-visible takes priority over focus-low-contrast
+    if (!indicator.isVisible) {
+        return [
+            buildFocusIssue('oracle/focus-not-visible', el, indicator.contrastRatio, context),
+        ];
+    }
+    if (!indicator.meetsWCAG_AA) {
+        return [
+            buildFocusIssue('oracle/focus-low-contrast', el, indicator.contrastRatio, context),
+        ];
+    }
+    return [];
+}
+/**
+ * Analyze a TraversalResult for keyboard trap issues.
+ *
+ * Checks:
+ * - `oracle/keyboard-trap` — `isTrapped === true`
+ *
+ * @param result - Traversal result from traverseSubTree()
+ * @param containerSelector - The CSS selector of the container tested for trapping
+ * @param context - Audit context
+ * @returns Array of 0 or 1 OracleIssue
+ */
+export function formatTrapIssue(result, containerSelector, context) {
+    if (!result.isTrapped) {
+        return [];
+    }
+    const rule = RULES['oracle/keyboard-trap'];
+    // Build node entries from visited elements
+    const nodeEntries = result.visitedElements.map((entry) => ({
+        impact: rule.impact,
+        html: htmlSnippetFromTabOrderEntry(entry),
+        target: [selectorFromTabOrderEntry(entry)],
+        any: [],
+        all: [],
+        none: [
+            {
+                id: rule.ruleId,
+                data: null,
+                relatedNodes: [],
+                impact: rule.impact,
+                message: `Element is trapped inside ${containerSelector} (${result.tabCount} tabs attempted)`,
+            },
+        ],
+        failureSummary: rule.failureSummary,
+    }));
+    // If no visited elements, create a single node for the container
+    if (nodeEntries.length === 0) {
+        nodeEntries.push({
+            impact: rule.impact,
+            html: `<div><!-- container: ${containerSelector} --></div>`,
+            target: [containerSelector],
+            any: [],
+            all: [],
+            none: [
+                {
+                    id: rule.ruleId,
+                    data: null,
+                    relatedNodes: [],
+                    impact: rule.impact,
+                    message: `Keyboard focus is trapped within ${containerSelector}`,
+                },
+            ],
+            failureSummary: rule.failureSummary,
+        });
+    }
+    return [
+        {
+            ruleId: rule.ruleId,
+            impact: rule.impact,
+            description: rule.description,
+            help: rule.help,
+            failureSummary: rule.failureSummary,
+            htmlSnippet: nodeEntries[0].html,
+            selector: containerSelector,
+            specName: context.specName,
+            project: context.project,
+            helpUrl: rule.helpUrl,
+            tags: [...rule.tags],
+            nodes: nodeEntries,
+            resultType: 'oracle',
+        },
+    ];
+}
+/** Roles that provide no semantic information to assistive technologies. */
+const GENERIC_ROLES = new Set([
+    'generic',
+    'none',
+    'presentation',
+    '',
+]);
+/**
+ * Analyze an A11yState for missing accessible name issues.
+ *
+ * Checks:
+ * - `oracle/focus-missing-name` — focused element has no computed name
+ *
+ * Only fires when an element is focused AND has a meaningful role
+ * (elements with generic/none/presentation roles fire
+ * `oracle/focus-generic-role` instead).
+ *
+ * @param state - Unified accessibility state from pressKey() or getState()
+ * @param context - Audit context (project, specName)
+ * @returns Array of 0 or 1 OracleIssue
+ */
+export function formatNameIssues(state, context) {
+    if (!state.focusedElement || !state.speechResult) {
+        return [];
+    }
+    // Only check elements with meaningful roles — generic/none handled separately
+    const rawRole = state.speechResult.rawNode?.role?.value ?? '';
+    if (GENERIC_ROLES.has(rawRole)) {
+        return [];
+    }
+    // Check if the computed name is empty
+    if (state.speechResult.name && state.speechResult.name.trim() !== '') {
+        return [];
+    }
+    return [buildElementIssue('oracle/focus-missing-name', state.focusedElement, null, context)];
+}
+/**
+ * Analyze an A11yState for generic/presentational role issues.
+ *
+ * Checks:
+ * - `oracle/focus-generic-role` — focused element has generic, none, or
+ *   presentation role
+ *
+ * Only fires when an element is focused AND the AXNode role is one of the
+ * semantically empty roles. This indicates an element that receives keyboard
+ * focus but provides no role information to assistive technologies.
+ *
+ * @param state - Unified accessibility state from pressKey() or getState()
+ * @param context - Audit context (project, specName)
+ * @returns Array of 0 or 1 OracleIssue
+ */
+export function formatRoleIssues(state, context) {
+    if (!state.focusedElement || !state.speechResult) {
+        return [];
+    }
+    const rawRole = state.speechResult.rawNode?.role?.value ?? '';
+    if (rawRole === '' || !GENERIC_ROLES.has(rawRole)) {
+        return [];
+    }
+    return [
+        buildElementIssue('oracle/focus-generic-role', state.focusedElement, { role: rawRole }, context),
+    ];
+}
+/**
+ * Analyze an A11yState for positive tabindex issues.
+ *
+ * Checks:
+ * - `oracle/positive-tabindex` — focused element has `tabIndex > 0`
+ *
+ * Positive tabindex values create an unpredictable focus order that
+ * diverges from the visual reading order.
+ *
+ * @param state - Unified accessibility state from pressKey() or getState()
+ * @param context - Audit context (project, specName)
+ * @returns Array of 0 or 1 OracleIssue
+ */
+export function formatTabIndexIssues(state, context) {
+    if (!state.focusedElement) {
+        return [];
+    }
+    if (state.focusedElement.tabIndex <= 0) {
+        return [];
+    }
+    return [
+        buildElementIssue('oracle/positive-tabindex', state.focusedElement, { tabIndex: state.focusedElement.tabIndex }, context),
+    ];
+}
+/**
+ * Convenience: analyze an A11yState for ALL state-based rules.
+ *
+ * Runs focus indicator checks, name/role checks, and tabindex checks.
+ * Trap detection requires a separate TraversalResult — use
+ * `formatTrapIssue()` for that.
+ *
+ * @param state - Unified accessibility state
+ * @param context - Audit context
+ * @returns Array of OracleIssue objects
+ */
+export function formatAllIssues(state, context) {
+    const level = context.wcagLevel ?? 'wcag22aa';
+    const disabledSet = context.disabledRules
+        ? new Set(context.disabledRules)
+        : null;
+    const allIssues = [
+        ...formatFocusIssues(state, context),
+        ...formatNameIssues(state, context),
+        ...formatRoleIssues(state, context),
+        ...formatTabIndexIssues(state, context),
+    ];
+    return allIssues.filter((issue) => {
+        if (disabledSet?.has(issue.ruleId))
+            return false;
+        return matchesWcagLevel(RULES[issue.ruleId], level);
+    });
+}
+// ---- Internal helpers ----
+function buildElementIssue(ruleId, el, data, context) {
+    const rule = RULES[ruleId];
+    const selector = selectorFromFocusedElement(el);
+    const html = htmlSnippetFromFocusedElement(el);
+    const node = {
+        impact: rule.impact,
+        html,
+        target: [selector],
+        any: [],
+        all: [],
+        none: [
+            {
+                id: ruleId,
+                data,
+                relatedNodes: [],
+                impact: rule.impact,
+                message: rule.help,
+            },
+        ],
+        failureSummary: rule.failureSummary,
+    };
+    return {
+        ruleId,
+        impact: rule.impact,
+        description: rule.description,
+        help: rule.help,
+        failureSummary: rule.failureSummary,
+        htmlSnippet: html,
+        selector,
+        specName: context.specName,
+        project: context.project,
+        helpUrl: rule.helpUrl,
+        tags: [...rule.tags],
+        nodes: [node],
+        resultType: 'oracle',
+    };
+}
+function buildFocusIssue(ruleId, el, contrastRatio, context) {
+    const rule = RULES[ruleId];
+    const selector = selectorFromFocusedElement(el);
+    const html = htmlSnippetFromFocusedElement(el);
+    const contrastInfo = contrastRatio !== null
+        ? ` (contrast ratio: ${contrastRatio.toFixed(2)}:1)`
+        : '';
+    const node = {
+        impact: rule.impact,
+        html,
+        target: [selector],
+        any: [],
+        all: [],
+        none: [
+            {
+                id: ruleId,
+                data: contrastRatio !== null ? { contrastRatio } : null,
+                relatedNodes: [],
+                impact: rule.impact,
+                message: `${rule.help}${contrastInfo}`,
+            },
+        ],
+        failureSummary: rule.failureSummary,
+    };
+    return {
+        ruleId,
+        impact: rule.impact,
+        description: rule.description,
+        help: rule.help,
+        failureSummary: rule.failureSummary,
+        htmlSnippet: html,
+        selector,
+        specName: context.specName,
+        project: context.project,
+        helpUrl: rule.helpUrl,
+        tags: [...rule.tags],
+        nodes: [node],
+        resultType: 'oracle',
+    };
+}

package/dist/lib/oracle-auditor.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @module oracle-auditor
+ *
+ * Convenience wrapper that wraps an orchestrator-like object and
+ * automatically audits each interaction for accessibility issues.
+ *
+ * @example
+ * ```typescript
+ * // Playwright
+ * const auditor = new OracleAuditor(a11y, {
+ *   project: 'my-app',
+ *   specName: 'nav.spec.ts',
+ * });
+ * await auditor.pressKey('Tab');
+ * await auditor.pressKey('Tab');
+ * await auditor.checkTrap('#modal');
+ * const issues = auditor.getIssues();
+ * ```
+ */
+import type { A11yState } from '@a11y-oracle/core-engine';
+import type { TraversalResult } from '@a11y-oracle/focus-analyzer';
+import type { OracleIssue, AuditContext } from './types.js';
+/**
+ * Minimal interface satisfied by A11yOrchestrator and A11yOracle.
+ *
+ * Defined locally so the audit-formatter doesn't require a hard
+ * dependency on any specific orchestrator implementation.
+ */
+export interface OrchestratorLike {
+    pressKey(key: string, modifiers?: Record<string, boolean>): Promise<A11yState>;
+    getState(): Promise<A11yState>;
+    traverseSubTree(selector: string, maxTabs?: number): Promise<TraversalResult>;
+}
+/**
+ * Convenience wrapper that accumulates Oracle issues across multiple
+ * keyboard interactions and trap checks.
+ *
+ * Each call to `pressKey()`, `getState()`, or `checkTrap()` automatically
+ * runs the relevant audit rules and accumulates any issues found. Call
+ * `getIssues()` at the end to retrieve all accumulated issues.
+ */
+export declare class OracleAuditor {
+    private orchestrator;
+    private context;
+    private issues;
+    private previousKeys;
+    constructor(orchestrator: OrchestratorLike, context: AuditContext);
+    /**
+     * Press a key via the orchestrator and analyze the resulting state
+     * for focus issues. Returns the A11yState for further assertions.
+     *
+     * Deduplicates issues that match the previous `pressKey` call
+     * (same ruleId + selector), preventing noise when Tab doesn't
+     * move focus (e.g., end of page, trapped element).
+     */
+    pressKey(key: string, modifiers?: Record<string, boolean>): Promise<A11yState>;
+    /**
+     * Get the current state and analyze it for focus issues.
+     * Useful after programmatic focus changes or click handlers.
+     */
+    getState(): Promise<A11yState>;
+    /**
+     * Check a container for keyboard traps (WCAG 2.1.2).
+     */
+    checkTrap(selector: string, maxTabs?: number): Promise<TraversalResult>;
+    /**
+     * Return all issues accumulated during the session.
+     * Does not clear the internal list — call `clear()` to reset.
+     */
+    getIssues(): ReadonlyArray<OracleIssue>;
+    /**
+     * Clear all accumulated issues.
+     */
+    clear(): void;
+    /**
+     * The number of accumulated issues.
+     */
+    get issueCount(): number;
+}
+//# sourceMappingURL=oracle-auditor.d.ts.map

package/dist/lib/oracle-auditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oracle-auditor.d.ts","sourceRoot":"","sources":["../../src/lib/oracle-auditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG5D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtB,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/B,eAAe,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,YAAY,CAA0B;gBAElC,YAAY,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY;IAKjE;;;;;;;OAOG;IACG,QAAQ,CACZ,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,OAAO,CAAC,SAAS,CAAC;IAiBrB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC;IAMpC;;OAEG;IACG,SAAS,CACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC;IAW3B;;;OAGG;IACH,SAAS,IAAI,aAAa,CAAC,WAAW,CAAC;IAIvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;CACF"}

package/dist/lib/oracle-auditor.js

@@ -0,0 +1,97 @@
+/**
+ * @module oracle-auditor
+ *
+ * Convenience wrapper that wraps an orchestrator-like object and
+ * automatically audits each interaction for accessibility issues.
+ *
+ * @example
+ * ```typescript
+ * // Playwright
+ * const auditor = new OracleAuditor(a11y, {
+ *   project: 'my-app',
+ *   specName: 'nav.spec.ts',
+ * });
+ * await auditor.pressKey('Tab');
+ * await auditor.pressKey('Tab');
+ * await auditor.checkTrap('#modal');
+ * const issues = auditor.getIssues();
+ * ```
+ */
+import { formatAllIssues, formatTrapIssue } from './formatters.js';
+/**
+ * Convenience wrapper that accumulates Oracle issues across multiple
+ * keyboard interactions and trap checks.
+ *
+ * Each call to `pressKey()`, `getState()`, or `checkTrap()` automatically
+ * runs the relevant audit rules and accumulates any issues found. Call
+ * `getIssues()` at the end to retrieve all accumulated issues.
+ */
+export class OracleAuditor {
+    orchestrator;
+    context;
+    issues = [];
+    previousKeys = new Set();
+    constructor(orchestrator, context) {
+        this.orchestrator = orchestrator;
+        this.context = context;
+    }
+    /**
+     * Press a key via the orchestrator and analyze the resulting state
+     * for focus issues. Returns the A11yState for further assertions.
+     *
+     * Deduplicates issues that match the previous `pressKey` call
+     * (same ruleId + selector), preventing noise when Tab doesn't
+     * move focus (e.g., end of page, trapped element).
+     */
+    async pressKey(key, modifiers) {
+        const state = await this.orchestrator.pressKey(key, modifiers);
+        const newIssues = formatAllIssues(state, this.context);
+        const currentKeys = new Set();
+        for (const issue of newIssues) {
+            const dedupKey = `${issue.ruleId}::${issue.selector}`;
+            currentKeys.add(dedupKey);
+            if (!this.previousKeys.has(dedupKey)) {
+                this.issues.push(issue);
+            }
+        }
+        this.previousKeys = currentKeys;
+        return state;
+    }
+    /**
+     * Get the current state and analyze it for focus issues.
+     * Useful after programmatic focus changes or click handlers.
+     */
+    async getState() {
+        const state = await this.orchestrator.getState();
+        this.issues.push(...formatAllIssues(state, this.context));
+        return state;
+    }
+    /**
+     * Check a container for keyboard traps (WCAG 2.1.2).
+     */
+    async checkTrap(selector, maxTabs) {
+        const result = await this.orchestrator.traverseSubTree(selector, maxTabs);
+        this.issues.push(...formatTrapIssue(result, selector, this.context));
+        return result;
+    }
+    /**
+     * Return all issues accumulated during the session.
+     * Does not clear the internal list — call `clear()` to reset.
+     */
+    getIssues() {
+        return [...this.issues];
+    }
+    /**
+     * Clear all accumulated issues.
+     */
+    clear() {
+        this.issues = [];
+        this.previousKeys = new Set();
+    }
+    /**
+     * The number of accumulated issues.
+     */
+    get issueCount() {
+        return this.issues.length;
+    }
+}

package/dist/lib/rules.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @module rules
+ *
+ * Oracle audit rule definitions with WCAG metadata.
+ *
+ * Each rule maps to a specific WCAG criterion and carries all the metadata
+ * needed to produce a fully populated OracleIssue. Rules are keyed by their
+ * `ruleId` (e.g., `oracle/focus-not-visible`).
+ */
+import type { OracleRule, WcagLevel } from './types.js';
+/**
+ * All defined Oracle audit rules.
+ *
+ * Focus indicator rules:
+ * - `oracle/focus-not-visible` — WCAG 2.4.7 Focus Visible (Level AA)
+ * - `oracle/focus-low-contrast` — WCAG 2.4.12 Focus Appearance (Level AA, WCAG 2.2)
+ *
+ * Keyboard navigation rules:
+ * - `oracle/keyboard-trap` — WCAG 2.1.2 No Keyboard Trap (Level A)
+ * - `oracle/focus-missing-name` — WCAG 4.1.2 Name, Role, Value (Level A)
+ * - `oracle/focus-generic-role` — WCAG 4.1.2 Name, Role, Value (Level A)
+ * - `oracle/positive-tabindex` — WCAG 2.4.3 Focus Order (Level A)
+ */
+export declare const RULES: Record<string, OracleRule>;
+/** Get a rule by ID, or throw if unknown. */
+export declare function getRule(ruleId: string): OracleRule;
+/**
+ * Check if a rule applies at the given WCAG standard.
+ *
+ * A rule matches if any of its tags appear in the set of tags
+ * covered by the given standard. For example, a rule tagged
+ * `wcag22aa` matches `'wcag22aa'` but not `'wcag21aa'`.
+ */
+export declare function matchesWcagLevel(rule: OracleRule, level: WcagLevel): boolean;
+/** All defined rule IDs. */
+export declare const RULE_IDS: string[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/lib/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/lib/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAiG5C,CAAC;AAEF,6CAA6C;AAC7C,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAMlD;AAkBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAG5E;AAED,4BAA4B;AAC5B,eAAO,MAAM,QAAQ,UAAqB,CAAC"}

package/dist/lib/rules.js

@@ -0,0 +1,133 @@
+/**
+ * @module rules
+ *
+ * Oracle audit rule definitions with WCAG metadata.
+ *
+ * Each rule maps to a specific WCAG criterion and carries all the metadata
+ * needed to produce a fully populated OracleIssue. Rules are keyed by their
+ * `ruleId` (e.g., `oracle/focus-not-visible`).
+ */
+/**
+ * All defined Oracle audit rules.
+ *
+ * Focus indicator rules:
+ * - `oracle/focus-not-visible` — WCAG 2.4.7 Focus Visible (Level AA)
+ * - `oracle/focus-low-contrast` — WCAG 2.4.12 Focus Appearance (Level AA, WCAG 2.2)
+ *
+ * Keyboard navigation rules:
+ * - `oracle/keyboard-trap` — WCAG 2.1.2 No Keyboard Trap (Level A)
+ * - `oracle/focus-missing-name` — WCAG 4.1.2 Name, Role, Value (Level A)
+ * - `oracle/focus-generic-role` — WCAG 4.1.2 Name, Role, Value (Level A)
+ * - `oracle/positive-tabindex` — WCAG 2.4.3 Focus Order (Level A)
+ */
+export const RULES = {
+    'oracle/focus-not-visible': {
+        ruleId: 'oracle/focus-not-visible',
+        help: 'Focused element must have a visible focus indicator',
+        description: 'Ensures that every interactive element has a visible focus indicator ' +
+            'when focused via the keyboard. A missing focus indicator makes it ' +
+            'impossible for keyboard users to know where they are on the page.',
+        impact: 'serious',
+        tags: ['wcag2aa', 'wcag247', 'cat.keyboard', 'oracle'],
+        helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html',
+        failureSummary: 'Fix any of the following:\n' +
+            '  Element has no visible focus indicator when focused via keyboard.',
+    },
+    'oracle/focus-low-contrast': {
+        ruleId: 'oracle/focus-low-contrast',
+        help: 'Focus indicator must have sufficient contrast (>= 3:1)',
+        description: 'Ensures the visual focus indicator has a contrast ratio of at least ' +
+            '3:1 against the background, meeting WCAG 2.4.12 (Focus Appearance) ' +
+            'AA requirements.',
+        impact: 'moderate',
+        tags: ['wcag22aa', 'wcag2412', 'cat.keyboard', 'oracle'],
+        helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html',
+        failureSummary: 'Fix any of the following:\n' +
+            '  Focus indicator contrast ratio is below the 3:1 minimum.',
+    },
+    'oracle/keyboard-trap': {
+        ruleId: 'oracle/keyboard-trap',
+        help: 'Interactive content must not trap keyboard focus',
+        description: 'Ensures that keyboard focus can be moved away from any interactive ' +
+            'component using the keyboard alone. A keyboard trap prevents users ' +
+            'from navigating the rest of the page.',
+        impact: 'critical',
+        tags: ['wcag2a', 'wcag212', 'cat.keyboard', 'oracle'],
+        helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html',
+        failureSummary: 'Fix any of the following:\n' +
+            '  Keyboard focus is trapped within the container and cannot escape.',
+    },
+    'oracle/focus-missing-name': {
+        ruleId: 'oracle/focus-missing-name',
+        help: 'Focused element must have an accessible name',
+        description: 'Ensures that interactive elements have a non-empty computed accessible ' +
+            'name when focused via the keyboard. Without an accessible name, screen ' +
+            'readers cannot identify the element to users.',
+        impact: 'serious',
+        tags: ['wcag2a', 'wcag412', 'cat.keyboard', 'oracle'],
+        helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+        failureSummary: 'Fix any of the following:\n' +
+            '  Focused element has no accessible name (aria-label, aria-labelledby, or text content).',
+    },
+    'oracle/focus-generic-role': {
+        ruleId: 'oracle/focus-generic-role',
+        help: 'Focused element must have a meaningful role',
+        description: 'Ensures that interactive elements exposed to the keyboard have a ' +
+            'meaningful ARIA role. Elements with generic, presentation, or none ' +
+            'roles provide no semantic information to assistive technologies.',
+        impact: 'serious',
+        tags: ['wcag2a', 'wcag412', 'cat.keyboard', 'oracle'],
+        helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+        failureSummary: 'Fix any of the following:\n' +
+            '  Focused element has a generic or presentational role instead of a semantic role.',
+    },
+    'oracle/positive-tabindex': {
+        ruleId: 'oracle/positive-tabindex',
+        help: 'Elements should not use positive tabindex values',
+        description: 'Ensures that elements in the tab order do not use tabindex values ' +
+            'greater than 0. Positive tabindex creates an unpredictable focus ' +
+            'order that diverges from the visual reading order, making keyboard ' +
+            'navigation confusing for users.',
+        impact: 'serious',
+        tags: ['wcag2a', 'wcag243', 'cat.keyboard', 'oracle'],
+        helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html',
+        failureSummary: 'Fix any of the following:\n' +
+            '  Element uses a positive tabindex value, disrupting the natural focus order.',
+    },
+};
+/** Get a rule by ID, or throw if unknown. */
+export function getRule(ruleId) {
+    const rule = RULES[ruleId];
+    if (!rule) {
+        throw new Error(`Unknown oracle rule: ${ruleId}`);
+    }
+    return rule;
+}
+/**
+ * Map each WCAG standard to the set of rule-level tags it includes.
+ *
+ * Each standard includes all rules from earlier versions at the same
+ * or lower conformance level. For example, `'wcag21aa'` includes
+ * rules tagged `wcag2a`, `wcag2aa`, `wcag21a`, and `wcag21aa`.
+ */
+const STANDARD_TAG_MAP = {
+    'wcag2a': new Set(['wcag2a']),
+    'wcag2aa': new Set(['wcag2a', 'wcag2aa']),
+    'wcag21a': new Set(['wcag2a', 'wcag21a']),
+    'wcag21aa': new Set(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']),
+    'wcag22a': new Set(['wcag2a', 'wcag21a', 'wcag22a']),
+    'wcag22aa': new Set(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22a', 'wcag22aa']),
+};
+/**
+ * Check if a rule applies at the given WCAG standard.
+ *
+ * A rule matches if any of its tags appear in the set of tags
+ * covered by the given standard. For example, a rule tagged
+ * `wcag22aa` matches `'wcag22aa'` but not `'wcag21aa'`.
+ */
+export function matchesWcagLevel(rule, level) {
+    const allowedTags = STANDARD_TAG_MAP[level];
+    return rule.tags.some((tag) => allowedTags.has(tag));
+}
+/** All defined rule IDs. */
+export const RULE_IDS = Object.keys(RULES);