@a11y-oracle/audit-formatter 1.0.0

package/dist/lib/selector.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module selector
+ *
+ * Utilities for generating CSS selectors and HTML snippets from
+ * A11y-Oracle element data structures.
+ *
+ * Selector priority: `#id` > `tag.class1.class2` > `tag[role="..."]` > `tag`
+ */
+import type { A11yFocusedElement } from '@a11y-oracle/core-engine';
+import type { TabOrderEntry } from '@a11y-oracle/focus-analyzer';
+/**
+ * Build a CSS selector from an A11yFocusedElement.
+ * Priority: `#id` > `tag.class1.class2` > `tag`
+ */
+export declare function selectorFromFocusedElement(el: A11yFocusedElement): string;
+/**
+ * Build a CSS selector from a TabOrderEntry.
+ * Priority: `#id` > `tag[role="..."]` > `tag`
+ *
+ * TabOrderEntry does not have `className`, so we use `role` as a fallback
+ * to produce a more specific selector when no id is present.
+ */
+export declare function selectorFromTabOrderEntry(entry: TabOrderEntry): string;
+/**
+ * Build a minimal HTML snippet from an A11yFocusedElement.
+ *
+ * @example
+ * ```typescript
+ * htmlSnippetFromFocusedElement(el)
+ * // => '<button id="submit" class="btn primary">Submit</button>'
+ * ```
+ */
+export declare function htmlSnippetFromFocusedElement(el: A11yFocusedElement): string;
+/**
+ * Build a minimal HTML snippet from a TabOrderEntry.
+ */
+export declare function htmlSnippetFromTabOrderEntry(entry: TabOrderEntry): string;
+//# sourceMappingURL=selector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/lib/selector.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAsBjE;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,EAAE,EAAE,kBAAkB,GACrB,MAAM,CAcR;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,aAAa,GACnB,MAAM,CASR;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,kBAAkB,GACrB,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,aAAa,GACnB,MAAM,CASR"}

package/dist/lib/selector.js

@@ -0,0 +1,99 @@
+/**
+ * @module selector
+ *
+ * Utilities for generating CSS selectors and HTML snippets from
+ * A11y-Oracle element data structures.
+ *
+ * Selector priority: `#id` > `tag.class1.class2` > `tag[role="..."]` > `tag`
+ */
+/** Escape HTML special characters in attribute values and text content. */
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/** Escape characters that break CSS attribute selectors. */
+function escapeCssAttr(str) {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** Escape an ID for use in a CSS `#id` selector. */
+function escapeCssId(id) {
+    return id.replace(/([^\w-])/g, '\\$1');
+}
+/**
+ * Build a CSS selector from an A11yFocusedElement.
+ * Priority: `#id` > `tag.class1.class2` > `tag`
+ */
+export function selectorFromFocusedElement(el) {
+    if (el.id) {
+        return `#${escapeCssId(el.id)}`;
+    }
+    const tag = el.tag.toLowerCase();
+    if (el.className) {
+        const classes = el.className
+            .trim()
+            .split(/\s+/)
+            .map((c) => `.${c}`)
+            .join('');
+        return `${tag}${classes}`;
+    }
+    return tag;
+}
+/**
+ * Build a CSS selector from a TabOrderEntry.
+ * Priority: `#id` > `tag[role="..."]` > `tag`
+ *
+ * TabOrderEntry does not have `className`, so we use `role` as a fallback
+ * to produce a more specific selector when no id is present.
+ */
+export function selectorFromTabOrderEntry(entry) {
+    if (entry.id) {
+        return `#${escapeCssId(entry.id)}`;
+    }
+    const tag = entry.tag.toLowerCase();
+    if (entry.role) {
+        return `${tag}[role="${escapeCssAttr(entry.role)}"]`;
+    }
+    return tag;
+}
+/**
+ * Build a minimal HTML snippet from an A11yFocusedElement.
+ *
+ * @example
+ * ```typescript
+ * htmlSnippetFromFocusedElement(el)
+ * // => '<button id="submit" class="btn primary">Submit</button>'
+ * ```
+ */
+export function htmlSnippetFromFocusedElement(el) {
+    const tag = el.tag.toLowerCase();
+    const attrs = [];
+    if (el.id)
+        attrs.push(`id="${escapeHtml(el.id)}"`);
+    if (el.className)
+        attrs.push(`class="${escapeHtml(el.className)}"`);
+    if (el.role)
+        attrs.push(`role="${escapeHtml(el.role)}"`);
+    if (el.ariaLabel)
+        attrs.push(`aria-label="${escapeHtml(el.ariaLabel)}"`);
+    const attrStr = attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
+    const content = el.textContent ? escapeHtml(el.textContent.slice(0, 80)) : '';
+    return `<${tag}${attrStr}>${content}</${tag}>`;
+}
+/**
+ * Build a minimal HTML snippet from a TabOrderEntry.
+ */
+export function htmlSnippetFromTabOrderEntry(entry) {
+    const tag = entry.tag.toLowerCase();
+    const attrs = [];
+    if (entry.id)
+        attrs.push(`id="${escapeHtml(entry.id)}"`);
+    if (entry.role)
+        attrs.push(`role="${escapeHtml(entry.role)}"`);
+    const attrStr = attrs.length > 0 ? ` ${attrs.join(' ')}` : '';
+    const content = entry.textContent ? escapeHtml(entry.textContent.slice(0, 80)) : '';
+    return `<${tag}${attrStr}>${content}</${tag}>`;
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @module types
+ *
+ * Axe-core-compatible issue types for A11y-Oracle findings.
+ *
+ * These types are structurally compatible with Beacon's AxeIssue interface
+ * but defined locally so audit-formatter has zero dependencies on Beacon.
+ *
+ * Fields that Beacon assigns during ingestion (id, testRunId, fingerprint,
+ * status, triageNotes) are omitted — the formatter only outputs the issue
+ * data itself.
+ */
+/** Impact levels matching axe-core severity. */
+export type OracleImpact = 'minor' | 'moderate' | 'serious' | 'critical';
+/**
+ * Result type discriminator.
+ * - `'violation'` / `'incomplete'` match axe-core conventions.
+ * - `'oracle'` identifies findings from A11y-Oracle analysis.
+ */
+export type OracleResultType = 'violation' | 'incomplete' | 'oracle';
+/**
+ * A single check within an axe-core node result.
+ * Simplified for Oracle findings — `data` carries rule-specific context
+ * (e.g., `{ contrastRatio: 2.1 }` for focus contrast issues).
+ */
+export interface OracleCheck {
+    /** Check identifier (typically the ruleId). */
+    id: string;
+    /** Check-specific data, e.g. `{ contrastRatio: 2.1 }`. */
+    data: unknown;
+    /** Related DOM nodes (empty for Oracle findings). */
+    relatedNodes: unknown[];
+    /** Impact level of this check. */
+    impact: string;
+    /** Human-readable description of the check result. */
+    message: string;
+}
+/**
+ * A single DOM node result, compatible with axe-core's AxeNode shape.
+ */
+export interface OracleNode {
+    /** Node-level impact override. */
+    impact?: string;
+    /** HTML snippet of the problematic element. */
+    html: string;
+    /** CSS selector path for the element. */
+    target: string[];
+    /** Checks where any one passing would fix the issue. */
+    any: OracleCheck[];
+    /** Checks where all must pass. */
+    all: OracleCheck[];
+    /** Checks where none should be present. */
+    none: OracleCheck[];
+    /** Human-readable summary of the failure. */
+    failureSummary: string;
+}
+/**
+ * An accessibility issue in axe-core-compatible format.
+ *
+ * Structurally compatible with Beacon's `AxeIssue` interface for the
+ * fields that the formatter is responsible for producing. Fields assigned
+ * by the consumer (id, testRunId, fingerprint, status, triageNotes)
+ * are omitted.
+ *
+ * `resultType` is always `'oracle'` to distinguish from axe-core findings.
+ * `ruleId` is prefixed with `oracle/` (e.g., `oracle/focus-not-visible`).
+ */
+export interface OracleIssue {
+    /** Rule identifier, e.g. `oracle/focus-not-visible`. */
+    ruleId: string;
+    /** Severity: minor | moderate | serious | critical. */
+    impact: OracleImpact;
+    /** Human-readable description of what the rule checks. */
+    description: string;
+    /** Short help text for the issue. */
+    help: string;
+    /** Summary of the failure for remediation. */
+    failureSummary: string;
+    /** HTML snippet of the offending element. */
+    htmlSnippet: string;
+    /** CSS selector targeting the element. */
+    selector: string;
+    /** Name of the test spec that produced this finding. */
+    specName: string;
+    /** Project name for issue attribution. */
+    project: string;
+    /** URL to WCAG documentation. */
+    helpUrl: string;
+    /** WCAG tags, e.g. `['wcag2a', 'wcag212', 'cat.keyboard', 'oracle']`. */
+    tags: string[];
+    /** Axe-compatible node results. */
+    nodes: OracleNode[];
+    /** Result type discriminator. Always `'oracle'` for formatter output. */
+    resultType: OracleResultType;
+}
+/**
+ * WCAG conformance standard for filtering rules.
+ *
+ * Values follow axe-core's tag convention (no decimals).
+ * Each standard includes all rules from earlier versions at the same
+ * or lower level. For example, `'wcag21aa'` includes WCAG 2.0 Level A,
+ * WCAG 2.0 Level AA, WCAG 2.1 Level A, and WCAG 2.1 Level AA rules.
+ */
+export type WcagLevel = 'wcag2a' | 'wcag2aa' | 'wcag21a' | 'wcag21aa' | 'wcag22a' | 'wcag22aa';
+/**
+ * Context required by all formatter functions.
+ * Provided by the test runner or OracleAuditor.
+ */
+export interface AuditContext {
+    /** Project name for issue attribution. */
+    project: string;
+    /** Name of the spec/test file producing these findings. */
+    specName: string;
+    /** Target WCAG standard. Default 'wcag22aa' (all rules). */
+    wcagLevel?: WcagLevel;
+    /** Rule IDs to suppress (e.g. ['oracle/positive-tabindex']). */
+    disabledRules?: string[];
+}
+/**
+ * Metadata for a single Oracle audit rule.
+ */
+export interface OracleRule {
+    /** Rule ID, e.g. `oracle/focus-not-visible`. */
+    ruleId: string;
+    /** Short help text, used as the issue `help` field. */
+    help: string;
+    /** Longer description, used as the issue `description` field. */
+    description: string;
+    /** Impact severity. */
+    impact: OracleImpact;
+    /** WCAG tags. */
+    tags: string[];
+    /** URL to WCAG criterion documentation. */
+    helpUrl: string;
+    /** Failure summary template. */
+    failureSummary: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,IAAI,EAAE,OAAO,CAAC;IACd,qDAAqD;IACrD,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wDAAwD;IACxD,GAAG,EAAE,WAAW,EAAE,CAAC;IACnB,kCAAkC;IAClC,GAAG,EAAE,WAAW,EAAE,CAAC;IACnB,2CAA2C;IAC3C,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,EAAE,YAAY,CAAC;IACrB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mCAAmC;IACnC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,yEAAyE;IACzE,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,SAAS,GACT,UAAU,GACV,SAAS,GACT,UAAU,CAAC;AAEf;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,iBAAiB;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/lib/types.js

@@ -0,0 +1,13 @@
+/**
+ * @module types
+ *
+ * Axe-core-compatible issue types for A11y-Oracle findings.
+ *
+ * These types are structurally compatible with Beacon's AxeIssue interface
+ * but defined locally so audit-formatter has zero dependencies on Beacon.
+ *
+ * Fields that Beacon assigns during ingestion (id, testRunId, fingerprint,
+ * status, triageNotes) are omitted — the formatter only outputs the issue
+ * data itself.
+ */
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@a11y-oracle/audit-formatter",
+  "version": "1.0.0",
+  "description": "Converts accessibility findings to axe-core-compatible OracleIssue objects with WCAG rule metadata",
+  "license": "MIT",
+  "author": "a11y-oracle",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a11y-oracle/a11y-oracle.git",
+    "directory": "libs/audit-formatter"
+  },
+  "bugs": {
+    "url": "https://github.com/a11y-oracle/a11y-oracle/issues"
+  },
+  "homepage": "https://github.com/a11y-oracle/a11y-oracle/tree/main/libs/audit-formatter",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "audit",
+    "wcag",
+    "axe-core",
+    "testing",
+    "formatter"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@a11y-oracle/core-engine": "1.0.0",
+    "@a11y-oracle/focus-analyzer": "1.0.0",
+    "tslib": "^2.3.0"
+  }
+}