@a11y-oracle/audit-formatter 1.0.0

package/README.md

@@ -0,0 +1,281 @@
+# @a11y-oracle/audit-formatter
+
+Converts A11y-Oracle findings into axe-core-compatible issue objects (`OracleIssue`). Pure functions with no CDP dependency — works with any `A11yState` or `TraversalResult` regardless of how it was produced.
+
+Output is differentiated from axe-core findings by `resultType: 'oracle'` and `oracle/`-prefixed rule IDs (e.g., `oracle/focus-not-visible`).
+
+## Installation
+
+```bash
+npm install @a11y-oracle/audit-formatter
+```
+
+> **Note:** Most users should use the [`@a11y-oracle/playwright-plugin`](../playwright-plugin/README.md) or [`@a11y-oracle/cypress-plugin`](../cypress-plugin/README.md) instead. The audit-formatter is the underlying library that those plugins use. Install it directly if you need to format issues outside a test framework or build a custom integration.
+
+## Usage
+
+### Pure Formatter Functions
+
+The simplest approach — pass an `A11yState` and get back any issues:
+
+```typescript
+import { formatFocusIssues, formatTrapIssue } from '@a11y-oracle/audit-formatter';
+import type { A11yState } from '@a11y-oracle/core-engine';
+import type { TraversalResult } from '@a11y-oracle/focus-analyzer';
+
+const context = { project: 'my-app', specName: 'nav.spec.ts' };
+
+// Check a focused element for focus indicator issues
+const focusIssues = formatFocusIssues(state, context);
+// Returns: [] if passing, or [OracleIssue] if failing
+
+// Check a traversal result for keyboard traps
+const trapIssues = formatTrapIssue(result, '#modal-container', context);
+// Returns: [] if not trapped, or [OracleIssue] if trapped
+
+// Convenience: run all state-based checks at once
+import { formatAllIssues } from '@a11y-oracle/audit-formatter';
+const allIssues = formatAllIssues(state, context);
+```
+
+### OracleAuditor Class
+
+Wraps an orchestrator and automatically audits every interaction. Issues accumulate across calls:
+
+```typescript
+import { test, expect } from '@a11y-oracle/playwright-plugin';
+import { OracleAuditor } from '@a11y-oracle/audit-formatter';
+
+test('all focus indicators pass oracle rules', async ({ page, a11y }) => {
+  await page.goto('/my-page.html');
+
+  const auditor = new OracleAuditor(a11y, {
+    project: 'my-app',
+    specName: 'navigation.spec.ts',
+  });
+
+  // Each pressKey() automatically runs all state-based checks
+  await auditor.pressKey('Tab');
+  await auditor.pressKey('Tab');
+  await auditor.pressKey('Tab');
+
+  // Check a container for keyboard traps
+  await auditor.checkTrap('#modal-container');
+
+  // Assert no issues found
+  expect(auditor.issueCount).toBe(0);
+  expect(auditor.getIssues()).toHaveLength(0);
+});
+```
+
+The `OracleAuditor` accepts any object matching the `OrchestratorLike` interface, which is satisfied by both `A11yOracle` (Playwright) and `A11yOrchestrator` (core engine).
+
+### Selector Utilities
+
+Generate CSS selectors and HTML snippets from element data:
+
+```typescript
+import {
+  selectorFromFocusedElement,
+  htmlSnippetFromFocusedElement,
+} from '@a11y-oracle/audit-formatter';
+
+const selector = selectorFromFocusedElement(state.focusedElement);
+// "#submit-btn" or "button.primary.large" or "button"
+
+const snippet = htmlSnippetFromFocusedElement(state.focusedElement);
+// '<button id="submit-btn" class="primary">Submit</button>'
+```
+
+## Rules
+
+A11y-Oracle enforces six WCAG rules:
+
+| Rule ID | WCAG Criterion | Since | Level | Tag | Impact | Description |
+|---------|---------------|-------|-------|-----|--------|-------------|
+| `oracle/focus-not-visible` | [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) | 2.0 | AA | `wcag2aa` | `serious` | Focused element has no visible focus indicator |
+| `oracle/focus-low-contrast` | [2.4.12 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) | 2.2 | AA | `wcag22aa` | `moderate` | Focus indicator contrast ratio is below 3:1 |
+| `oracle/keyboard-trap` | [2.1.2 No Keyboard Trap](https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html) | 2.0 | A | `wcag2a` | `critical` | Keyboard focus is trapped within a container |
+| `oracle/focus-missing-name` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | 2.0 | A | `wcag2a` | `serious` | Focused element has no accessible name |
+| `oracle/focus-generic-role` | [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | 2.0 | A | `wcag2a` | `serious` | Focused element has a generic or presentational role |
+| `oracle/positive-tabindex` | [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) | 2.0 | A | `wcag2a` | `serious` | Element uses a positive tabindex value |
+
+`focus-not-visible` takes priority over `focus-low-contrast` — if no indicator exists, only the visibility rule fires (not both). `focus-generic-role` and `focus-missing-name` are mutually exclusive — generic roles trigger only the role check.
+
+For detailed remediation guidance on each rule, see the [Remediation Guide](../../docs/REMEDIATION.md).
+
+## API Reference
+
+### Formatter Functions
+
+#### `formatFocusIssues(state, context)`
+
+Check an `A11yState` for focus indicator issues.
+
+- **Parameters:**
+  - `state: A11yState` — unified accessibility state from `pressKey()` or `getState()`
+  - `context: AuditContext` — `{ project, specName, wcagLevel?, disabledRules? }`
+- **Returns:** `OracleIssue[]` — 0 or 1 issues
+- **Behavior:** Returns `oracle/focus-not-visible` if `isVisible === false`. Returns `oracle/focus-low-contrast` if visible but `meetsWCAG_AA === false`. Returns `[]` if passing or no focused element.
+
+#### `formatTrapIssue(result, containerSelector, context)`
+
+Check a `TraversalResult` for keyboard traps.
+
+- **Parameters:**
+  - `result: TraversalResult` — result from `traverseSubTree()`
+  - `containerSelector: string` — CSS selector for the container (used in the issue)
+  - `context: AuditContext` — `{ project: string, specName: string }`
+- **Returns:** `OracleIssue[]` — 0 or 1 issues
+
+#### `formatNameIssues(state, context)`
+
+Check an `A11yState` for missing accessible name issues.
+
+- **Parameters:** Same as `formatFocusIssues`
+- **Returns:** `OracleIssue[]` — 0 or 1 issues
+- **Behavior:** Returns `oracle/focus-missing-name` if the focused element has no computed name. Skips elements with generic/presentational roles (those fire `formatRoleIssues` instead).
+
+#### `formatRoleIssues(state, context)`
+
+Check an `A11yState` for generic/presentational role issues.
+
+- **Parameters:** Same as `formatFocusIssues`
+- **Returns:** `OracleIssue[]` — 0 or 1 issues
+- **Behavior:** Returns `oracle/focus-generic-role` if the focused element has a `generic`, `none`, or `presentation` role.
+
+#### `formatTabIndexIssues(state, context)`
+
+Check an `A11yState` for positive tabindex issues.
+
+- **Parameters:** Same as `formatFocusIssues`
+- **Returns:** `OracleIssue[]` — 0 or 1 issues
+- **Behavior:** Returns `oracle/positive-tabindex` if the focused element has `tabIndex > 0`.
+
+#### `formatAllIssues(state, context)`
+
+Convenience wrapper that runs all state-based checks: focus indicator, name, role, and tabindex.
+
+- **Parameters:** Same as `formatFocusIssues`
+- **Returns:** `OracleIssue[]`
+- **Behavior:** Applies `wcagLevel` filtering (default `'aa'`) and `disabledRules` suppression from `context`.
+
+#### `matchesWcagLevel(rule, level)`
+
+Check if a rule applies at a given WCAG conformance level.
+
+- **Parameters:**
+  - `rule: OracleRule` — rule metadata object
+  - `level: WcagLevel` — `'a'` or `'aa'`
+- **Returns:** `boolean` — `true` if the rule applies at the given level
+- **Behavior:** `'aa'` includes all rules. `'a'` includes only rules tagged with `wcag2a`.
+
+### OracleAuditor
+
+#### `constructor(orchestrator, context)`
+
+- `orchestrator: OrchestratorLike` — any object with `pressKey()`, `getState()`, and `traverseSubTree()` methods
+- `context: AuditContext` — `{ project, specName, wcagLevel?, disabledRules? }`
+
+#### `pressKey(key, modifiers?): Promise<A11yState>`
+
+Dispatch a key press and automatically audit the resulting state for all state-based rules.
+
+#### `getState(): Promise<A11yState>`
+
+Read the current state and audit it for all state-based rules.
+
+#### `checkTrap(selector, maxTabs?): Promise<TraversalResult>`
+
+Run keyboard trap detection on a container and audit the result.
+
+#### `getIssues(): ReadonlyArray<OracleIssue>`
+
+Return a copy of all accumulated issues.
+
+#### `clear(): void`
+
+Reset the accumulated issues list.
+
+#### `issueCount: number`
+
+The number of accumulated issues (getter).
+
+### OrchestratorLike Interface
+
+```typescript
+interface OrchestratorLike {
+  pressKey(key: string, modifiers?: Record<string, boolean>): Promise<A11yState>;
+  getState(): Promise<A11yState>;
+  traverseSubTree(selector: string, maxTabs?: number): Promise<TraversalResult>;
+}
+```
+
+Satisfied by `A11yOracle` (playwright-plugin) and `A11yOrchestrator` (core-engine).
+
+### Rule Utilities
+
+#### `RULES: Record<string, OracleRule>`
+
+All defined rule objects keyed by rule ID.
+
+#### `RULE_IDS: string[]`
+
+Array of all rule IDs.
+
+#### `getRule(ruleId): OracleRule`
+
+Get a rule by ID, or throw if unknown.
+
+### Selector Utilities
+
+#### `selectorFromFocusedElement(el): string`
+
+Generate a CSS selector from an `A11yFocusedElement`. Priority: `#id` > `tag.class1.class2` > `tag`.
+
+#### `selectorFromTabOrderEntry(entry): string`
+
+Generate a CSS selector from a `TabOrderEntry`. Priority: `#id` > `tag[role="..."]` > `tag`.
+
+#### `htmlSnippetFromFocusedElement(el): string`
+
+Generate a minimal HTML snippet from an `A11yFocusedElement`.
+
+#### `htmlSnippetFromTabOrderEntry(entry): string`
+
+Generate a minimal HTML snippet from a `TabOrderEntry`.
+
+## Types
+
+```typescript
+import type {
+  OracleIssue,         // Main issue object
+  OracleNode,          // Axe-compatible node result
+  OracleCheck,         // Individual check within a node
+  OracleImpact,        // 'minor' | 'moderate' | 'serious' | 'critical'
+  OracleResultType,    // 'violation' | 'incomplete' | 'oracle'
+  OracleRule,          // Rule metadata
+  AuditContext,        // { project, specName, wcagLevel?, disabledRules? }
+  WcagLevel,           // 'wcag2a' | 'wcag2aa' | 'wcag21a' | 'wcag21aa' | 'wcag22a' | 'wcag22aa'
+} from '@a11y-oracle/audit-formatter';
+```
+
+## Exports
+
+```typescript
+// Types
+export type { OracleIssue, OracleNode, OracleCheck, OracleImpact, OracleResultType, OracleRule, AuditContext, WcagLevel };
+
+// Rule definitions
+export { RULES, RULE_IDS, getRule, matchesWcagLevel };
+
+// Pure formatter functions
+export { formatFocusIssues, formatTrapIssue, formatNameIssues, formatRoleIssues, formatTabIndexIssues, formatAllIssues };
+
+// Selector utilities
+export { selectorFromFocusedElement, selectorFromTabOrderEntry, htmlSnippetFromFocusedElement, htmlSnippetFromTabOrderEntry };
+
+// Convenience class
+export { OracleAuditor };
+export type { OrchestratorLike };
+```

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module @a11y-oracle/audit-formatter
+ *
+ * Converts A11y-Oracle findings into axe-core-compatible issues.
+ *
+ * Output is structurally compatible with Beacon's AxeIssue interface,
+ * differentiated by `resultType: 'oracle'` and `oracle/`-prefixed ruleIds.
+ *
+ * @packageDocumentation
+ */
+export type { OracleIssue, OracleNode, OracleCheck, OracleImpact, OracleResultType, OracleRule, AuditContext, WcagLevel, } from './lib/types.js';
+export { RULES, RULE_IDS, getRule, matchesWcagLevel } from './lib/rules.js';
+export { formatFocusIssues, formatTrapIssue, formatNameIssues, formatRoleIssues, formatTabIndexIssues, formatAllIssues, } from './lib/formatters.js';
+export { selectorFromFocusedElement, selectorFromTabOrderEntry, htmlSnippetFromFocusedElement, htmlSnippetFromTabOrderEntry, } from './lib/selector.js';
+export { OracleAuditor } from './lib/oracle-auditor.js';
+export type { OrchestratorLike } from './lib/oracle-auditor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,SAAS,GACV,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAG5E,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @module @a11y-oracle/audit-formatter
+ *
+ * Converts A11y-Oracle findings into axe-core-compatible issues.
+ *
+ * Output is structurally compatible with Beacon's AxeIssue interface,
+ * differentiated by `resultType: 'oracle'` and `oracle/`-prefixed ruleIds.
+ *
+ * @packageDocumentation
+ */
+// Rule definitions
+export { RULES, RULE_IDS, getRule, matchesWcagLevel } from './lib/rules.js';
+// Pure formatter functions
+export { formatFocusIssues, formatTrapIssue, formatNameIssues, formatRoleIssues, formatTabIndexIssues, formatAllIssues, } from './lib/formatters.js';
+// Selector utilities
+export { selectorFromFocusedElement, selectorFromTabOrderEntry, htmlSnippetFromFocusedElement, htmlSnippetFromTabOrderEntry, } from './lib/selector.js';
+// Convenience class
+export { OracleAuditor } from './lib/oracle-auditor.js';

package/dist/lib/formatters.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @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 type { A11yState } from '@a11y-oracle/core-engine';
+import type { TraversalResult } from '@a11y-oracle/focus-analyzer';
+import type { OracleIssue, AuditContext } from './types.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 declare function formatFocusIssues(state: A11yState, context: AuditContext): OracleIssue[];
+/**
+ * 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 declare function formatTrapIssue(result: TraversalResult, containerSelector: string, context: AuditContext): OracleIssue[];
+/**
+ * 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 declare function formatNameIssues(state: A11yState, context: AuditContext): OracleIssue[];
+/**
+ * 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 declare function formatRoleIssues(state: A11yState, context: AuditContext): OracleIssue[];
+/**
+ * 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 declare function formatTabIndexIssues(state: A11yState, context: AuditContext): OracleIssue[];
+/**
+ * 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 declare function formatAllIssues(state: A11yState, context: AuditContext): OracleIssue[];
+//# sourceMappingURL=formatters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/lib/formatters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,SAAS,EAEV,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EACV,WAAW,EAEX,YAAY,EACb,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,GACpB,WAAW,EAAE,CAgCf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,YAAY,GACpB,WAAW,EAAE,CAgEf;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,GACpB,WAAW,EAAE,CAiBf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,GACpB,WAAW,EAAE,CAkBf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,GACpB,WAAW,EAAE,CAiBf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,YAAY,GACpB,WAAW,EAAE,CAiBf"}