@masup9/a11y-audit 0.1.0

package/dist/schemas/index.js

@@ -0,0 +1,245 @@
+/**
+ * Result types and JSON Schemas for the audit checks.
+ *
+ * The TypeScript types are the source of truth; the JSON Schemas are
+ * hand-written for consumers that validate the result files at runtime
+ * (e.g. an issue creator that reads `*-result.json`). They are intentionally
+ * permissive (no `additionalProperties: false`) so that additive changes to a
+ * result shape do not break downstream validation.
+ */
+const DISCLAIMER_SCHEMA = {
+    type: 'object',
+    properties: {
+        message: { type: 'string' },
+        messageEn: { type: 'string' },
+        coverage: { type: 'string' },
+        moreInfo: { type: 'string' },
+    },
+};
+export const AXE_AUDIT_RESULT_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://masup9.github.io/a11y-audit/schemas/axe-audit-result.json',
+    title: 'AxeAuditResult',
+    type: 'object',
+    required: [
+        'url',
+        'timestamp',
+        'violations',
+        'passes',
+        'incomplete',
+        'inapplicable',
+        'violationCount',
+    ],
+    properties: {
+        url: { type: 'string' },
+        timestamp: { type: 'string' },
+        violations: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id', 'description', 'help', 'helpUrl', 'tags', 'nodes'],
+                properties: {
+                    id: { type: 'string' },
+                    impact: { type: ['string', 'null'] },
+                    description: { type: 'string' },
+                    help: { type: 'string' },
+                    helpUrl: { type: 'string' },
+                    tags: { type: 'array', items: { type: 'string' } },
+                    nodes: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            required: ['html', 'target'],
+                            properties: {
+                                html: { type: 'string' },
+                                target: { type: 'array', items: { type: 'string' } },
+                                failureSummary: { type: ['string', 'null'] },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        passes: { type: 'number' },
+        incomplete: { type: 'number' },
+        inapplicable: { type: 'number' },
+        violationCount: { type: 'number' },
+        disclaimer: DISCLAIMER_SCHEMA,
+    },
+};
+const FOCUS_ELEMENT_REF_SCHEMA = {
+    type: 'object',
+    required: ['tag', 'name', 'selector'],
+    properties: {
+        tag: { type: 'string' },
+        role: { type: ['string', 'null'] },
+        name: { type: 'string' },
+        selector: { type: 'string' },
+    },
+};
+export const FOCUS_CHECK_RESULT_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://masup9.github.io/a11y-audit/schemas/focus-check-result.json',
+    title: 'FocusCheckResult',
+    type: 'object',
+    required: [
+        'url',
+        'totalFocusableElements',
+        'elementsWithFocusStyle',
+        'elementsWithoutFocusStyle',
+        'issues',
+        'onFocusViolations',
+        'focusObscuredIssues',
+        'elementsWithObscuredFocus',
+        'allElements',
+        'interrupted',
+        'screenshotPath',
+    ],
+    properties: {
+        url: { type: 'string' },
+        totalFocusableElements: { type: 'number' },
+        elementsWithFocusStyle: { type: 'number' },
+        elementsWithoutFocusStyle: { type: 'number' },
+        issues: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['tag', 'name'],
+                properties: {
+                    tag: { type: 'string' },
+                    role: { type: ['string', 'null'] },
+                    name: { type: 'string' },
+                },
+            },
+        },
+        onFocusViolations: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['element', 'fromUrl', 'toUrl', 'changeType'],
+                properties: {
+                    element: FOCUS_ELEMENT_REF_SCHEMA,
+                    fromUrl: { type: 'string' },
+                    toUrl: { type: 'string' },
+                    changeType: {
+                        type: 'string',
+                        enum: ['navigation', 'new-window', 'dialog'],
+                    },
+                },
+            },
+        },
+        focusObscuredIssues: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['element', 'elementRect', 'overlaps', 'obscuredRatio'],
+                properties: {
+                    element: FOCUS_ELEMENT_REF_SCHEMA,
+                    elementRect: { type: 'object' },
+                    overlaps: { type: 'array', items: { type: 'object' } },
+                    obscuredRatio: { type: 'number' },
+                },
+            },
+        },
+        elementsWithObscuredFocus: { type: 'number' },
+        allElements: { type: 'array', items: { type: 'object' } },
+        interrupted: { type: 'boolean' },
+        interruptedAt: { type: 'number' },
+        screenshotPath: { type: 'string' },
+        disclaimer: DISCLAIMER_SCHEMA,
+    },
+};
+export const REFLOW_CHECK_RESULT_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://masup9.github.io/a11y-audit/schemas/reflow-check-result.json',
+    title: 'ReflowCheckResult',
+    type: 'object',
+    required: [
+        'url',
+        'viewport',
+        'hasHorizontalScroll',
+        'documentScrollWidth',
+        'documentClientWidth',
+        'overflowingElements',
+        'clippedTextElements',
+    ],
+    properties: {
+        url: { type: 'string' },
+        viewport: {
+            type: 'object',
+            required: ['width', 'height'],
+            properties: {
+                width: { type: 'number' },
+                height: { type: 'number' },
+            },
+        },
+        hasHorizontalScroll: { type: 'boolean' },
+        documentScrollWidth: { type: 'number' },
+        documentClientWidth: { type: 'number' },
+        overflowingElements: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['selector', 'tagName', 'rect', 'viewportWidth', 'reason'],
+                properties: {
+                    selector: { type: 'string' },
+                    tagName: { type: 'string' },
+                    rect: { type: 'object' },
+                    viewportWidth: { type: 'number' },
+                    reason: {
+                        type: 'string',
+                        enum: ['overflow-right', 'overflow-left', 'clipped-text'],
+                    },
+                },
+            },
+        },
+        clippedTextElements: { type: 'array', items: { type: 'object' } },
+        disclaimer: DISCLAIMER_SCHEMA,
+    },
+};
+export const TARGET_SIZE_CHECK_RESULT_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://masup9.github.io/a11y-audit/schemas/target-size-check-result.json',
+    title: 'TargetSizeCheckResult',
+    type: 'object',
+    required: [
+        'url',
+        'totalTargetsChecked',
+        'failAA',
+        'failAAAOnly',
+        'passedTargets',
+        'exceptedTargets',
+        'summary',
+    ],
+    properties: {
+        url: { type: 'string' },
+        totalTargetsChecked: { type: 'number' },
+        failAA: { type: 'array', items: { type: 'object' } },
+        failAAAOnly: { type: 'array', items: { type: 'object' } },
+        passedTargets: { type: 'number' },
+        exceptedTargets: { type: 'array', items: { type: 'object' } },
+        summary: {
+            type: 'object',
+            required: [
+                'failAACount',
+                'failAAAOnlyCount',
+                'passCount',
+                'exceptedCount',
+            ],
+            properties: {
+                failAACount: { type: 'number' },
+                failAAAOnlyCount: { type: 'number' },
+                passCount: { type: 'number' },
+                exceptedCount: { type: 'number' },
+            },
+        },
+        disclaimer: DISCLAIMER_SCHEMA,
+    },
+};
+/** All result schemas keyed by check id. */
+export const RESULT_SCHEMAS = {
+    'axe-audit': AXE_AUDIT_RESULT_SCHEMA,
+    'focus-indicator-check': FOCUS_CHECK_RESULT_SCHEMA,
+    'reflow-check': REFLOW_CHECK_RESULT_SCHEMA,
+    'target-size-check': TARGET_SIZE_CHECK_RESULT_SCHEMA,
+};

package/dist/test-entries/axe-audit.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Compatibility test entry for the axe audit.
+ *
+ * Run it from a one-line local spec (Playwright excludes node_modules from
+ * test collection, so a `testMatch` glob into node_modules finds nothing):
+ *   // tests/a11y/axe.spec.ts
+ *   import "@masup9/a11y-audit/test-entries/axe-audit";
+ *
+ * Target URL comes from the `TEST_PAGE` env var; output dir from
+ * `A11Y_OUTPUT_DIR` (falling back to cwd). This is a thin wrapper around
+ * `runAxeAudit` — all logic lives there.
+ */
+export {};

package/dist/test-entries/axe-audit.js

@@ -0,0 +1,20 @@
+/**
+ * Compatibility test entry for the axe audit.
+ *
+ * Run it from a one-line local spec (Playwright excludes node_modules from
+ * test collection, so a `testMatch` glob into node_modules finds nothing):
+ *   // tests/a11y/axe.spec.ts
+ *   import "@masup9/a11y-audit/test-entries/axe-audit";
+ *
+ * Target URL comes from the `TEST_PAGE` env var; output dir from
+ * `A11Y_OUTPUT_DIR` (falling back to cwd). This is a thin wrapper around
+ * `runAxeAudit` — all logic lives there.
+ */
+import { test } from '@playwright/test';
+import { runAxeAudit } from '../playwright/runAxeAudit.js';
+import { requireTargetUrl } from '../utils/test-harness.js';
+test('axe-core accessibility audit', async ({ page }) => {
+    const targetUrl = requireTargetUrl();
+    await page.goto(targetUrl, { waitUntil: 'networkidle' });
+    await runAxeAudit({ page });
+});

package/dist/test-entries/focus-indicator-check.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compatibility test entry for the focus indicator check
+ * (WCAG 2.4.7 / 2.4.12 / 3.2.1).
+ *
+ * Thin wrapper around `runFocusIndicatorCheck`. Target URL from `TEST_PAGE`,
+ * output dir from `A11Y_OUTPUT_DIR` (falling back to cwd). Captures the legacy
+ * screenshot. This check owns its browser context (see runFocusIndicatorCheck).
+ */
+export {};

package/dist/test-entries/focus-indicator-check.js

@@ -0,0 +1,13 @@
+/**
+ * Compatibility test entry for the focus indicator check
+ * (WCAG 2.4.7 / 2.4.12 / 3.2.1).
+ *
+ * Thin wrapper around `runFocusIndicatorCheck`. Target URL from `TEST_PAGE`,
+ * output dir from `A11Y_OUTPUT_DIR` (falling back to cwd). Captures the legacy
+ * screenshot. This check owns its browser context (see runFocusIndicatorCheck).
+ */
+import { test } from '@playwright/test';
+import { runFocusIndicatorCheck } from '../playwright/runFocusIndicatorCheck.js';
+test('focus indicator visibility', async ({ browser }) => {
+    await runFocusIndicatorCheck({ browser, screenshot: true });
+});

package/dist/test-entries/reflow-check.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compatibility test entry for the reflow check (WCAG 1.4.10).
+ *
+ * Thin wrapper around `runReflowCheck`. Target URL from `TEST_PAGE`,
+ * output dir from `A11Y_OUTPUT_DIR` (falling back to cwd). Sets the narrow
+ * viewport before navigation to match the legacy script behavior, and captures
+ * the legacy screenshot.
+ */
+export {};

package/dist/test-entries/reflow-check.js

@@ -0,0 +1,21 @@
+/**
+ * Compatibility test entry for the reflow check (WCAG 1.4.10).
+ *
+ * Thin wrapper around `runReflowCheck`. Target URL from `TEST_PAGE`,
+ * output dir from `A11Y_OUTPUT_DIR` (falling back to cwd). Sets the narrow
+ * viewport before navigation to match the legacy script behavior, and captures
+ * the legacy screenshot.
+ */
+import { test } from '@playwright/test';
+import { runReflowCheck } from '../playwright/runReflowCheck.js';
+import { requireTargetUrl } from '../utils/test-harness.js';
+import { REFLOW_VIEWPORT } from '../constants.js';
+test('reflow check (WCAG 1.4.10)', async ({ page }) => {
+    await page.setViewportSize({
+        width: REFLOW_VIEWPORT.width,
+        height: REFLOW_VIEWPORT.height,
+    });
+    const targetUrl = requireTargetUrl();
+    await page.goto(targetUrl, { waitUntil: 'networkidle' });
+    await runReflowCheck({ page, screenshot: true });
+});

package/dist/test-entries/target-size-check.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compatibility test entry for the target size check (WCAG 2.5.5 / 2.5.8).
+ *
+ * Thin wrapper around `runTargetSizeCheck`. Target URL from `TEST_PAGE`,
+ * output dir from `A11Y_OUTPUT_DIR` (falling back to cwd). Captures the legacy
+ * annotated screenshot.
+ */
+export {};

package/dist/test-entries/target-size-check.js

@@ -0,0 +1,15 @@
+/**
+ * Compatibility test entry for the target size check (WCAG 2.5.5 / 2.5.8).
+ *
+ * Thin wrapper around `runTargetSizeCheck`. Target URL from `TEST_PAGE`,
+ * output dir from `A11Y_OUTPUT_DIR` (falling back to cwd). Captures the legacy
+ * annotated screenshot.
+ */
+import { test } from '@playwright/test';
+import { runTargetSizeCheck } from '../playwright/runTargetSizeCheck.js';
+import { requireTargetUrl } from '../utils/test-harness.js';
+test('target size check (WCAG 2.5.5 / 2.5.8)', async ({ page }) => {
+    const targetUrl = requireTargetUrl();
+    await page.goto(targetUrl, { waitUntil: 'networkidle' });
+    await runTargetSizeCheck({ page, screenshot: true });
+});

package/dist/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Type definitions for the WCAG audit checks shipped in @masup9/a11y-audit.
+ */
+import type { AUDIT_DISCLAIMER } from './constants.js';
+export interface AxeViolationNode {
+    html: string;
+    target: string[];
+    failureSummary: string | undefined;
+}
+export interface AxeViolation {
+    id: string;
+    impact: string | null;
+    description: string;
+    help: string;
+    helpUrl: string;
+    tags: string[];
+    nodes: AxeViolationNode[];
+}
+export interface AxeAuditResult {
+    url: string;
+    timestamp: string;
+    violations: AxeViolation[];
+    passes: number;
+    incomplete: number;
+    inapplicable: number;
+    violationCount: number;
+    disclaimer: typeof AUDIT_DISCLAIMER;
+}
+export interface FocusRecord {
+    id: number;
+    tag: string;
+    role: string | null;
+    name: string;
+    hasFocusStyle: boolean;
+    diff: Record<string, string>;
+}
+/**
+ * WCAG 3.2.1 On Focus violation - context change triggered by focus
+ */
+export interface OnFocusViolation {
+    /** Element that triggered the navigation */
+    element: {
+        tag: string;
+        role: string | null;
+        name: string;
+        selector: string;
+    };
+    /** URL before focus */
+    fromUrl: string;
+    /** URL after focus (navigation target) */
+    toUrl: string;
+    /** Type of context change */
+    changeType: 'navigation' | 'new-window' | 'dialog';
+}
+export interface FocusCheckResult {
+    url: string;
+    totalFocusableElements: number;
+    elementsWithFocusStyle: number;
+    elementsWithoutFocusStyle: number;
+    /** WCAG 2.4.7 violations */
+    issues: Array<{
+        tag: string;
+        role: string | null;
+        name: string;
+    }>;
+    /** WCAG 3.2.1 violations - focus triggered context change */
+    onFocusViolations: OnFocusViolation[];
+    /** WCAG 2.4.12 violations - focus obscured by fixed/sticky elements */
+    focusObscuredIssues: FocusObscuredIssue[];
+    elementsWithObscuredFocus: number;
+    allElements: FocusRecord[];
+    /** Whether test was interrupted by navigation */
+    interrupted: boolean;
+    interruptedAt?: number;
+    /**
+     * Path the screenshot was (or would be) written to. Empty string when
+     * `screenshot` was disabled and no screenshot file was produced.
+     */
+    screenshotPath: string;
+}
+/**
+ * Bounding rect for overlap calculations
+ */
+export interface BoundingRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Information about an element obscuring the focused element
+ */
+export interface FocusObscuredOverlap {
+    /** The element causing the obscuring */
+    obscuredBy: {
+        tag: string;
+        role: string | null;
+        name: string;
+        selector: string;
+    };
+    /** The overlapping area */
+    overlapRect: BoundingRect;
+    /** Area of overlap in square pixels */
+    overlapArea: number;
+}
+/**
+ * WCAG 2.4.12 violation - focus indicator hidden by fixed/sticky content
+ */
+export interface FocusObscuredIssue {
+    /** The focused element that is obscured */
+    element: {
+        tag: string;
+        role: string | null;
+        name: string;
+        selector: string;
+    };
+    /** Bounding rect of the focused element */
+    elementRect: BoundingRect;
+    /** List of overlapping fixed/sticky elements */
+    overlaps: FocusObscuredOverlap[];
+    /** Ratio of element area that is obscured (0-1) */
+    obscuredRatio: number;
+}
+export interface ReflowIssue {
+    selector: string;
+    tagName: string;
+    rect: {
+        left: number;
+        right: number;
+        width: number;
+    };
+    viewportWidth: number;
+    reason: 'overflow-right' | 'overflow-left' | 'clipped-text';
+}
+export interface ClippedTextElement {
+    selector: string;
+    tagName: string;
+    scrollWidth: number;
+    clientWidth: number;
+    scrollHeight: number;
+    clientHeight: number;
+    overflow: string;
+    overflowX: string;
+}
+export interface ReflowCheckResult {
+    url: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    hasHorizontalScroll: boolean;
+    documentScrollWidth: number;
+    documentClientWidth: number;
+    overflowingElements: ReflowIssue[];
+    clippedTextElements: ClippedTextElement[];
+}
+/**
+ * Exception types for WCAG 2.5.8 Target Size (Minimum)
+ * - inline: Target is in a sentence or text block
+ * - redundant: Another target with same function meets size requirement
+ * - ua-control: Size is determined by user agent (native controls)
+ * - spacing: Target has sufficient spacing from adjacent targets
+ * - essential-review: May be essential exception but requires manual review
+ */
+export type TargetSizeException = 'inline' | 'redundant' | 'ua-control' | 'spacing' | 'essential-review';
+export interface TargetSizeIssue {
+    /** CSS selector for the element */
+    selector: string;
+    /** HTML tag name */
+    tagName: string;
+    /** ARIA role if present */
+    role: string | null;
+    /** Computed accessible name */
+    accessibleName: string | null;
+    /** Element width in CSS pixels */
+    width: number;
+    /** Element height in CSS pixels */
+    height: number;
+    /** Smallest dimension (min of width/height) */
+    minDimension: number;
+    /** Pass/fail level */
+    level: 'fail-aa' | 'fail-aaa-only' | 'pass';
+    /** Exception that may apply */
+    exception: TargetSizeException | null;
+    /** Human-readable exception details */
+    exceptionDetails: string | null;
+    /** Link href for redundancy check */
+    href: string | null;
+}
+export interface TargetSizeSummary {
+    /** Number of targets failing AA (< 24px) */
+    failAACount: number;
+    /** Number of targets failing only AAA (24-43px) */
+    failAAAOnlyCount: number;
+    /** Number of targets passing (>= 44px) */
+    passCount: number;
+    /** Number of targets with possible exceptions */
+    exceptedCount: number;
+}
+export interface TargetSizeCheckResult {
+    /** Page URL */
+    url: string;
+    /** Total interactive elements checked */
+    totalTargetsChecked: number;
+    /** Elements failing AA threshold (< 24px) */
+    failAA: TargetSizeIssue[];
+    /** Elements failing only AAA threshold (24-43px) */
+    failAAAOnly: TargetSizeIssue[];
+    /** Number of elements passing (>= 44px) */
+    passedTargets: number;
+    /** Elements with possible exceptions */
+    exceptedTargets: TargetSizeIssue[];
+    /** Summary counts */
+    summary: TargetSizeSummary;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for the WCAG audit checks shipped in @masup9/a11y-audit.
+ */
+export {};

package/dist/utils/annotations.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Annotation overlay utilities for audit screenshots.
+ *
+ * Adds positioned boxes + labels over elements without modifying the content
+ * DOM. Used by the target size check to highlight pass/fail targets.
+ */
+/**
+ * Standard annotation color schemes.
+ * Colors chosen for sufficient contrast with white text.
+ */
+export declare const ANNOTATION_COLORS: {
+    /** Pass - Dark green with white text */
+    readonly pass: {
+        readonly bg: "#16a34a";
+        readonly border: "#16a34a";
+        readonly text: "#ffffff";
+    };
+    /** Warning - Dark orange with white text */
+    readonly warning: {
+        readonly bg: "#e65100";
+        readonly border: "#e65100";
+        readonly text: "#ffffff";
+    };
+    /** Fail - Dark red with white text */
+    readonly fail: {
+        readonly bg: "#dc2626";
+        readonly border: "#dc2626";
+        readonly text: "#ffffff";
+    };
+    /** Info - Dark blue with white text */
+    readonly info: {
+        readonly bg: "#0d47a1";
+        readonly border: "#0d47a1";
+        readonly text: "#ffffff";
+    };
+    /** Violation - Purple with white text */
+    readonly violation: {
+        readonly bg: "#7c3aed";
+        readonly border: "#7c3aed";
+        readonly text: "#ffffff";
+    };
+};
+export type AnnotationColorScheme = keyof typeof ANNOTATION_COLORS;
+/**
+ * Annotation configuration for browser context.
+ */
+export interface AnnotationConfig {
+    /** CSS selector to annotate */
+    selector: string;
+    /** Label text to display */
+    label: string;
+    /** Color scheme to use */
+    colorScheme: AnnotationColorScheme;
+}
+/**
+ * Add annotations to a page using Playwright.
+ *
+ * Note: this mutates the page DOM (it appends an overlay element). Take any
+ * "clean" screenshot before calling this.
+ *
+ * @example
+ * await addPageAnnotations(page, [
+ *   { selector: '#header', label: 'PASS', colorScheme: 'pass' },
+ *   { selector: '.error', label: 'FAIL', colorScheme: 'fail' },
+ * ]);
+ */
+export declare function addPageAnnotations(page: import('@playwright/test').Page, annotations: AnnotationConfig[]): Promise<void>;