@masup9/a11y-audit 0.1.0

package/dist/utils/annotations.js

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+// =============================================================================
+// Annotation Styles
+// =============================================================================
+/**
+ * Standard annotation color schemes.
+ * Colors chosen for sufficient contrast with white text.
+ */
+export const ANNOTATION_COLORS = {
+    /** Pass - Dark green with white text */
+    pass: { bg: '#16a34a', border: '#16a34a', text: '#ffffff' },
+    /** Warning - Dark orange with white text */
+    warning: { bg: '#e65100', border: '#e65100', text: '#ffffff' },
+    /** Fail - Dark red with white text */
+    fail: { bg: '#dc2626', border: '#dc2626', text: '#ffffff' },
+    /** Info - Dark blue with white text */
+    info: { bg: '#0d47a1', border: '#0d47a1', text: '#ffffff' },
+    /** Violation - Purple with white text */
+    violation: { bg: '#7c3aed', border: '#7c3aed', text: '#ffffff' },
+};
+// =============================================================================
+// Playwright Helper
+// =============================================================================
+/**
+ * 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 async function addPageAnnotations(page, annotations) {
+    await page.evaluate((configs) => {
+        // Inline the colors to avoid serialization issues
+        const colors = {
+            pass: { bg: '#16a34a', border: '#16a34a', text: '#ffffff' },
+            warning: { bg: '#e65100', border: '#e65100', text: '#ffffff' },
+            fail: { bg: '#dc2626', border: '#dc2626', text: '#ffffff' },
+            info: { bg: '#0d47a1', border: '#0d47a1', text: '#ffffff' },
+            violation: { bg: '#7c3aed', border: '#7c3aed', text: '#ffffff' },
+        };
+        // Create overlay
+        let overlay = document.getElementById('wcag-audit-overlay');
+        if (!overlay) {
+            overlay = document.createElement('div');
+            overlay.id = 'wcag-audit-overlay';
+            overlay.style.cssText = `
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        pointer-events: none;
+        z-index: 99999;
+      `;
+            document.body.appendChild(overlay);
+        }
+        // Add annotations
+        for (const config of configs) {
+            try {
+                const element = document.querySelector(config.selector);
+                if (!element) {
+                    continue;
+                }
+                const rect = element.getBoundingClientRect();
+                const color = colors[config.colorScheme];
+                const box = document.createElement('div');
+                box.style.cssText = `
+          position: absolute;
+          left: ${rect.left + window.scrollX}px;
+          top: ${rect.top + window.scrollY}px;
+          width: ${rect.width}px;
+          height: ${rect.height}px;
+          border: 3px solid ${color.border};
+          box-sizing: border-box;
+          pointer-events: none;
+        `;
+                const labelEl = document.createElement('span');
+                labelEl.textContent = config.label;
+                labelEl.style.cssText = `
+          position: absolute;
+          top: -22px;
+          left: -3px;
+          background: ${color.bg};
+          color: ${color.text};
+          font-size: 11px;
+          font-weight: bold;
+          padding: 2px 6px;
+          border-radius: 3px;
+          white-space: nowrap;
+          font-family: system-ui, sans-serif;
+        `;
+                box.appendChild(labelEl);
+                overlay.appendChild(box);
+            }
+            catch {
+                // Ignore selector errors
+            }
+        }
+    }, annotations);
+}

package/dist/utils/layout.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Layout utilities for overflow and clipping detection.
+ * Used by the reflow check (and, in the future, zoom / text-spacing checks).
+ */
+import type { ReflowIssue, ClippedTextElement } from '../types.js';
+export interface LayoutCheckOptions {
+    viewportWidth: number;
+    overflowTolerance: number;
+    checkSelector: string;
+    allowedOverflowSelectors: readonly string[];
+}
+export interface LayoutCheckResult {
+    hasHorizontalScroll: boolean;
+    documentScrollWidth: number;
+    documentClientWidth: number;
+    overflowingElements: ReflowIssue[];
+    clippedTextElements: ClippedTextElement[];
+}
+/**
+ * Create the browser-side layout check function.
+ * This is serialized and executed in the browser context.
+ */
+export declare function createLayoutChecker(options: LayoutCheckOptions): LayoutCheckResult;

package/dist/utils/layout.js

@@ -0,0 +1,144 @@
+/**
+ * Layout utilities for overflow and clipping detection.
+ * Used by the reflow check (and, in the future, zoom / text-spacing checks).
+ */
+/**
+ * Create the browser-side layout check function.
+ * This is serialized and executed in the browser context.
+ */
+export function createLayoutChecker(options) {
+    const { viewportWidth, overflowTolerance, checkSelector, allowedOverflowSelectors, } = options;
+    // Helper functions (must be defined inside for browser context)
+    /**
+     * Generate a unique CSS selector for an element using index-based approach
+     * to avoid collisions with repeated components
+     */
+    function getUniqueSelector(element, elementIndex) {
+        if (element.id) {
+            return `#${element.id}`;
+        }
+        const path = [];
+        let current = element;
+        while (current && current !== document.body) {
+            let selector = current.tagName.toLowerCase();
+            // Always use nth-child for uniqueness
+            const parent = current.parentElement;
+            if (parent) {
+                const childIndex = Array.from(parent.children).indexOf(current) + 1;
+                selector += `:nth-child(${childIndex})`;
+            }
+            path.unshift(selector);
+            current = parent;
+        }
+        // Append element index as fallback for guaranteed uniqueness
+        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+    }
+    function isAllowedOverflow(element) {
+        return allowedOverflowSelectors.some((selector) => {
+            try {
+                return element.matches(selector) || element.closest(selector) !== null;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    function isVisible(element) {
+        const style = window.getComputedStyle(element);
+        return (style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            parseFloat(style.opacity) > 0);
+    }
+    // Check document-level horizontal scroll
+    const scrollEl = document.scrollingElement || document.documentElement;
+    const documentScrollWidth = scrollEl.scrollWidth;
+    const documentClientWidth = scrollEl.clientWidth;
+    const hasHorizontalScroll = documentScrollWidth > documentClientWidth + overflowTolerance;
+    // Find overflowing elements
+    const overflowingElements = [];
+    const clippedTextElements = [];
+    // Use WeakSet to track elements by identity, not selector string
+    const seenElements = new WeakSet();
+    const elements = document.querySelectorAll(checkSelector);
+    elements.forEach((element, elementIndex) => {
+        if (!isVisible(element) || isAllowedOverflow(element)) {
+            return;
+        }
+        // Skip if we've already reported this element (by identity)
+        if (seenElements.has(element)) {
+            return;
+        }
+        const rect = element.getBoundingClientRect();
+        const selector = getUniqueSelector(element, elementIndex);
+        // Check for right overflow (element extends beyond viewport)
+        if (rect.right > viewportWidth + overflowTolerance) {
+            seenElements.add(element);
+            overflowingElements.push({
+                selector,
+                tagName: element.tagName.toLowerCase(),
+                rect: {
+                    left: Math.round(rect.left),
+                    right: Math.round(rect.right),
+                    width: Math.round(rect.width),
+                },
+                viewportWidth,
+                reason: 'overflow-right',
+            });
+        }
+        // Check for left overflow (negative rect.left)
+        else if (rect.left < -overflowTolerance) {
+            seenElements.add(element);
+            overflowingElements.push({
+                selector,
+                tagName: element.tagName.toLowerCase(),
+                rect: {
+                    left: Math.round(rect.left),
+                    right: Math.round(rect.right),
+                    width: Math.round(rect.width),
+                },
+                viewportWidth,
+                reason: 'overflow-left',
+            });
+        }
+        // Check for clipped text (element has overflow hidden and content is clipped)
+        const style = window.getComputedStyle(element);
+        const overflow = style.overflow;
+        const overflowX = style.overflowX;
+        const isClipped = overflow === 'hidden' ||
+            overflow === 'clip' ||
+            overflowX === 'hidden' ||
+            overflowX === 'clip';
+        if (isClipped && !seenElements.has(element)) {
+            const scrollWidth = element.scrollWidth;
+            const clientWidth = element.clientWidth;
+            const scrollHeight = element.scrollHeight;
+            const clientHeight = element.clientHeight;
+            const hasHorizontalClip = scrollWidth > clientWidth + overflowTolerance;
+            const hasVerticalClip = scrollHeight > clientHeight + overflowTolerance;
+            if (hasHorizontalClip || hasVerticalClip) {
+                // Only report if element has text content
+                const hasText = element.textContent && element.textContent.trim().length > 0;
+                if (hasText) {
+                    seenElements.add(element);
+                    clippedTextElements.push({
+                        selector,
+                        tagName: element.tagName.toLowerCase(),
+                        scrollWidth,
+                        clientWidth,
+                        scrollHeight,
+                        clientHeight,
+                        overflow,
+                        overflowX,
+                    });
+                }
+            }
+        }
+    });
+    return {
+        hasHorizontalScroll,
+        documentScrollWidth,
+        documentClientWidth,
+        overflowingElements,
+        clippedTextElements,
+    };
+}

package/dist/utils/test-harness.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Test harness utilities for the audit checks.
+ *
+ * Provides output-path resolution (options → env → cwd), result writing, and
+ * console logging helpers shared by the four checks.
+ */
+import type { Page } from '@playwright/test';
+/**
+ * Shared options for controlling where a check writes its result file.
+ *
+ * Resolution order:
+ *   1. `outputPath` (absolute or relative full path) — mutually exclusive with
+ *      `outputDir` / `outputFile`.
+ *   2. `outputDir` option → `A11Y_OUTPUT_DIR` env → `process.cwd()`, joined with
+ *      `outputFile` option → the check's default filename.
+ */
+export interface OutputLocationOptions {
+    /** Directory to write result/screenshot into. Falls back to `A11Y_OUTPUT_DIR`, then cwd. */
+    outputDir?: string;
+    /** Result file name (basename only). Falls back to the check's default. */
+    outputFile?: string;
+    /** Full path for the result file. Mutually exclusive with `outputDir`/`outputFile`. */
+    outputPath?: string;
+}
+/**
+ * Resolve the absolute path a check should write its result to.
+ *
+ * @throws if `outputPath` is combined with `outputDir`/`outputFile`, or if
+ *   `outputFile` is an absolute path.
+ */
+export declare function resolveOutputPath(options: OutputLocationOptions & {
+    defaultFile: string;
+}): string;
+export interface SaveResultOptions extends OutputLocationOptions {
+    /** Default file name when none is provided via options. */
+    defaultFile: string;
+    /** Whether to append the disclaimer to the written JSON (default: true). */
+    includeDisclaimer?: boolean;
+}
+/**
+ * Save an audit result to a JSON file, creating parent directories as needed.
+ *
+ * @returns the absolute path the result was written to.
+ */
+export declare function saveAuditResult<T extends object>(result: T, options: SaveResultOptions): string;
+export interface TakeScreenshotOptions {
+    /** Absolute or relative path to write the screenshot to. */
+    path: string;
+    /** Whether to capture the full page (default: true). */
+    fullPage?: boolean;
+}
+/**
+ * Take a screenshot with standard audit settings, creating parent dirs.
+ *
+ * @returns the absolute path the screenshot was written to.
+ */
+export declare function takeAuditScreenshot(page: Page, options: TakeScreenshotOptions): Promise<string>;
+/**
+ * Resolve the screenshot path so it sits next to the resolved result file,
+ * using the given default screenshot filename when no explicit path is set.
+ */
+export declare function resolveScreenshotPath(resolvedResultPath: string, defaultScreenshotFile: string): string;
+/**
+ * Resolve the target URL from an explicit value or the `TEST_PAGE` env var.
+ *
+ * @throws if neither is provided.
+ */
+export declare function requireTargetUrl(explicit?: string): string;
+/** Log the header for audit results to console. */
+export declare function logAuditHeader(title: string, wcagRef: string, url: string): void;
+/** Log a summary section with key-value pairs. */
+export declare function logSummary(items: Record<string, string | number | boolean>): void;
+/** Log a list of issues with truncation. */
+export declare function logIssueList<T>(title: string, items: T[], formatter: (item: T, index: number) => string[], maxItems?: number): void;
+/** Log the output file paths and disclaimer. */
+export declare function logOutputPaths(outputPath: string, screenshotPath?: string): void;

package/dist/utils/test-harness.js

@@ -0,0 +1,119 @@
+/**
+ * Test harness utilities for the audit checks.
+ *
+ * Provides output-path resolution (options → env → cwd), result writing, and
+ * console logging helpers shared by the four checks.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { AUDIT_DISCLAIMER, DISCLAIMER_CONSOLE } from '../constants.js';
+/**
+ * Resolve the absolute path a check should write its result to.
+ *
+ * @throws if `outputPath` is combined with `outputDir`/`outputFile`, or if
+ *   `outputFile` is an absolute path.
+ */
+export function resolveOutputPath(options) {
+    const { outputDir, outputFile, outputPath, defaultFile } = options;
+    if (outputPath !== undefined &&
+        (outputDir !== undefined || outputFile !== undefined)) {
+        throw new Error('`outputPath` cannot be combined with `outputDir` / `outputFile`. ' +
+            'Specify either `outputPath`, or `outputDir` + `outputFile`.');
+    }
+    if (outputPath !== undefined) {
+        return path.resolve(outputPath);
+    }
+    if (outputFile !== undefined && path.basename(outputFile) !== outputFile) {
+        throw new Error('`outputFile` must be a bare file name (no path separators or `..`). ' +
+            'Use `outputDir` for the directory, or `outputPath` for a full path.');
+    }
+    const dir = outputDir ?? process.env.A11Y_OUTPUT_DIR ?? process.cwd();
+    const file = outputFile ?? defaultFile;
+    return path.resolve(dir, file);
+}
+/**
+ * Save an audit result to a JSON file, creating parent directories as needed.
+ *
+ * @returns the absolute path the result was written to.
+ */
+export function saveAuditResult(result, options) {
+    const { defaultFile, includeDisclaimer = true, ...location } = options;
+    const resolvedPath = resolveOutputPath({ ...location, defaultFile });
+    const outputData = includeDisclaimer
+        ? { ...result, disclaimer: AUDIT_DISCLAIMER }
+        : result;
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    fs.writeFileSync(resolvedPath, JSON.stringify(outputData, null, 2));
+    return resolvedPath;
+}
+/**
+ * Take a screenshot with standard audit settings, creating parent dirs.
+ *
+ * @returns the absolute path the screenshot was written to.
+ */
+export async function takeAuditScreenshot(page, options) {
+    const { path: screenshotPath, fullPage = true } = options;
+    const resolvedPath = path.resolve(screenshotPath);
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    await page.screenshot({ path: resolvedPath, fullPage });
+    return resolvedPath;
+}
+/**
+ * Resolve the screenshot path so it sits next to the resolved result file,
+ * using the given default screenshot filename when no explicit path is set.
+ */
+export function resolveScreenshotPath(resolvedResultPath, defaultScreenshotFile) {
+    return path.join(path.dirname(resolvedResultPath), defaultScreenshotFile);
+}
+// =============================================================================
+// URL resolution (used by compatibility test-entries)
+// =============================================================================
+/**
+ * Resolve the target URL from an explicit value or the `TEST_PAGE` env var.
+ *
+ * @throws if neither is provided.
+ */
+export function requireTargetUrl(explicit) {
+    const url = explicit ?? process.env.TEST_PAGE;
+    if (!url) {
+        throw new Error('No target URL provided. Pass `targetUrl` or set the TEST_PAGE environment variable.');
+    }
+    return url;
+}
+// =============================================================================
+// Console Logging
+// =============================================================================
+/** Log the header for audit results to console. */
+export function logAuditHeader(title, wcagRef, url) {
+    console.log(`\n=== ${title} (${wcagRef}) ===`);
+    console.log(`URL: ${url}`);
+}
+/** Log a summary section with key-value pairs. */
+export function logSummary(items) {
+    for (const [label, value] of Object.entries(items)) {
+        const displayValue = typeof value === 'boolean' ? (value ? 'YES' : 'No') : value;
+        console.log(`${label}: ${displayValue}`);
+    }
+}
+/** Log a list of issues with truncation. */
+export function logIssueList(title, items, formatter, maxItems = 10) {
+    if (items.length === 0) {
+        return;
+    }
+    console.log(`\n--- ${title} ---`);
+    items.slice(0, maxItems).forEach((item, index) => {
+        const lines = formatter(item, index);
+        lines.forEach((line) => console.log(`  ${line}`));
+    });
+    if (items.length > maxItems) {
+        console.log(`  ... and ${items.length - maxItems} more`);
+    }
+}
+/** Log the output file paths and disclaimer. */
+export function logOutputPaths(outputPath, screenshotPath) {
+    console.log(`\nResults saved to: ${outputPath}`);
+    if (screenshotPath) {
+        console.log(`Screenshot saved to: ${screenshotPath}`);
+    }
+    console.log(DISCLAIMER_CONSOLE);
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@masup9/a11y-audit",
+  "version": "0.1.0",
+  "description": "Playwright + axe-core based WCAG 2.2 accessibility audit functions (axe, focus indicator, reflow, target size).",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "masuP9",
+    "url": "https://github.com/masuP9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/masuP9/a11y-specialist-skills",
+    "directory": "packages/a11y-audit"
+  },
+  "homepage": "https://github.com/masuP9/a11y-specialist-skills/tree/main/packages/a11y-audit",
+  "bugs": {
+    "url": "https://github.com/masuP9/a11y-specialist-skills/issues"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "wcag22",
+    "playwright",
+    "axe-core",
+    "audit",
+    "focus-indicator",
+    "reflow",
+    "target-size"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./playwright": {
+      "types": "./dist/playwright/index.d.ts",
+      "import": "./dist/playwright/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./test-entries/axe-audit": {
+      "types": "./dist/test-entries/axe-audit.d.ts",
+      "import": "./dist/test-entries/axe-audit.js"
+    },
+    "./test-entries/focus-indicator-check": {
+      "types": "./dist/test-entries/focus-indicator-check.d.ts",
+      "import": "./dist/test-entries/focus-indicator-check.js"
+    },
+    "./test-entries/reflow-check": {
+      "types": "./dist/test-entries/reflow-check.d.ts",
+      "import": "./dist/test-entries/reflow-check.js"
+    },
+    "./test-entries/target-size-check": {
+      "types": "./dist/test-entries/target-size-check.d.ts",
+      "import": "./dist/test-entries/target-size-check.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.ja.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "npm run build",
+    "test": "playwright test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "peerDependencies": {
+    "@axe-core/playwright": "^4.10.0",
+    "@playwright/test": "^1.50.0"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.10.0",
+    "@playwright/test": "^1.50.0",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}