@a11y-skills/audit 0.2.0 → 0.3.1

package/dist/playwright/runTextSpacingCheck.js

@@ -7,11 +7,31 @@
  *
  * The caller is responsible for navigating the page before calling this.
  */
-import { TEXT_SPACING_CSS, TEXT_SPACING_CLIP_TOLERANCE, TEXT_SPACING_CHECK_SELECTOR, DEFAULT_TEXT_SPACING_RESULT_FILE, DEFAULT_TEXT_SPACING_SCREENSHOT_FILE, } from '../constants.js';
+import { TEXT_SPACING_CSS, TEXT_SPACING_CLIP_TOLERANCE, TEXT_SPACING_CHECK_SELECTOR, DEFAULT_TEXT_SPACING_RESULT_FILE, DEFAULT_TEXT_SPACING_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTextSpacingCheck, } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /** Collect metrics for elements with hidden overflow (browser context). */
 function collectElementMetrics(args) {
-    const { checkSelector } = args;
+    const { checkSelector, htmlSnippetMaxLength } = args;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return {
+                html: `<${element.tagName.toLowerCase()}>`,
+                htmlTruncated: false,
+            };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
     function getUniqueSelector(element, elementIndex) {
         if (element.id) {
             return `#${element.id}`;
@@ -28,7 +48,9 @@ function collectElementMetrics(args) {
             path.unshift(selector);
             current = parent;
         }
-        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+        return path.length > 0
+            ? path.join(' > ')
+            : `[data-index="${elementIndex}"]`;
     }
     function isVisible(element) {
         const style = window.getComputedStyle(element);
@@ -56,6 +78,7 @@ function collectElementMetrics(args) {
             metrics.push({
                 selector: getUniqueSelector(element, index),
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 scrollWidth: element.scrollWidth,
                 scrollHeight: element.scrollHeight,
                 clientWidth: element.clientWidth,
@@ -70,13 +93,32 @@ function collectElementMetrics(args) {
 }
 /** Inject text spacing CSS and re-collect metrics (browser context). */
 function injectSpacingAndCollect(args) {
-    const { css, checkSelector } = args;
+    const { css, checkSelector, htmlSnippetMaxLength } = args;
     const styleEl = document.createElement('style');
     styleEl.id = 'wcag-text-spacing-override';
     styleEl.textContent = css;
     document.head.appendChild(styleEl);
     // Force reflow
     void document.body.offsetHeight;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return {
+                html: `<${element.tagName.toLowerCase()}>`,
+                htmlTruncated: false,
+            };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
     function getUniqueSelector(element, elementIndex) {
         if (element.id) {
             return `#${element.id}`;
@@ -93,7 +135,9 @@ function injectSpacingAndCollect(args) {
             path.unshift(selector);
             current = parent;
         }
-        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+        return path.length > 0
+            ? path.join(' > ')
+            : `[data-index="${elementIndex}"]`;
     }
     function isVisible(element) {
         const style = window.getComputedStyle(element);
@@ -121,6 +165,7 @@ function injectSpacingAndCollect(args) {
             metrics.push({
                 selector: getUniqueSelector(element, index),
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 scrollWidth: element.scrollWidth,
                 scrollHeight: element.scrollHeight,
                 clientWidth: element.clientWidth,
@@ -175,6 +220,8 @@ function detectClippingIssues(beforeMetrics, afterMetrics, tolerance) {
             issues.push({
                 selector: after.selector,
                 tagName: after.tagName,
+                html: after.html,
+                htmlTruncated: after.htmlTruncated,
                 beforeMetrics: {
                     scrollWidth: beforeData.scrollWidth,
                     scrollHeight: beforeData.scrollHeight,
@@ -204,23 +251,30 @@ export async function runTextSpacingCheck(options) {
     const { page, tolerance = TEXT_SPACING_CLIP_TOLERANCE, screenshot = false, ...location } = options;
     const beforeMetrics = await page.evaluate(collectElementMetrics, {
         checkSelector: TEXT_SPACING_CHECK_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
     const afterMetrics = await page.evaluate(injectSpacingAndCollect, {
         css: TEXT_SPACING_CSS,
         checkSelector: TEXT_SPACING_CHECK_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
     const clippedElements = detectClippingIssues(beforeMetrics, afterMetrics, tolerance);
-    const result = {
-        url: page.url(),
+    const details = {
         clippedElements,
         totalElementsChecked: afterMetrics.length,
     };
+    const result = buildAuditResult({
+        source: 'text-spacing-check',
+        url: page.url(),
+        details,
+        buckets: normalizeTextSpacingCheck(details),
+    });
     logAuditHeader('Text Spacing Check Results', 'WCAG 1.4.12', result.url);
     logSummary({
-        'Elements with overflow:hidden checked': result.totalElementsChecked,
-        'Elements with clipping issues': result.clippedElements.length,
+        'Elements with overflow:hidden checked': details.totalElementsChecked,
+        'Elements with clipping issues': details.clippedElements.length,
     });
-    logIssueList('Clipped Elements', result.clippedElements, (el, i) => [
+    logIssueList('Clipped Elements', details.clippedElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   Issue: ${el.issueType}`,
         `   Before: ${el.beforeMetrics.scrollWidth}x${el.beforeMetrics.scrollHeight} in ${el.beforeMetrics.clientWidth}x${el.beforeMetrics.clientHeight}`,

package/dist/playwright/runTimeLimitDetector.js

@@ -10,7 +10,8 @@
  * (option → `TEST_PAGE` env → required). Unlike the focus check it does not
  * need a fresh context per attempt, so it stays page-based.
  */
-import { TIME_LIMIT_KEYWORDS, TIME_LIMIT_THRESHOLD_MS, TIME_LIMIT_MIN_MS, DEFAULT_TIME_LIMIT_RESULT_FILE, } from '../constants.js';
+import { TIME_LIMIT_KEYWORDS, TIME_LIMIT_THRESHOLD_MS, TIME_LIMIT_MIN_MS, DEFAULT_TIME_LIMIT_RESULT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTimeLimitDetector, } from '../utils/axe-format.js';
 import { saveAuditResult, requireTargetUrl, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /** Timer hook injected before page load (browser context). */
 function createTimerHookScript(args) {
@@ -29,13 +30,13 @@ function createTimerHookScript(args) {
                 callStack =
                     e.stack?.split('\n').slice(2, 5).join('\n') || null;
             }
-            capturedTimers.push({ type: 'setTimeout', delayMs: actualDelay, callStack });
+            capturedTimers.push({
+                type: 'setTimeout',
+                delayMs: actualDelay,
+                callStack,
+            });
         }
-        return originalSetTimeout.apply(window, [
-            callback,
-            delay,
-            ...rest,
-        ]);
+        return originalSetTimeout.apply(window, [callback, delay, ...rest]);
     };
     window.setInterval = function (callback, delay, ...rest) {
         const actualDelay = delay || 0;
@@ -48,19 +49,39 @@ function createTimerHookScript(args) {
                 callStack =
                     e.stack?.split('\n').slice(2, 5).join('\n') || null;
             }
-            capturedTimers.push({ type: 'setInterval', delayMs: actualDelay, callStack });
+            capturedTimers.push({
+                type: 'setInterval',
+                delayMs: actualDelay,
+                callStack,
+            });
         }
-        return originalSetInterval.apply(window, [
-            callback,
-            delay,
-            ...rest,
-        ]);
+        return originalSetInterval.apply(window, [callback, delay, ...rest]);
     };
-    window.__capturedTimers = capturedTimers;
+    window.__capturedTimers =
+        capturedTimers;
 }
 /** Detect meta refresh + countdown indicators (browser context). */
 function detectTimeLimitIndicators(args) {
-    const { keywords } = args;
+    const { keywords, htmlSnippetMaxLength } = args;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return {
+                html: `<${element.tagName.toLowerCase()}>`,
+                htmlTruncated: false,
+            };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
     function getUniqueSelector(element, elementIndex) {
         if (element.id) {
             return `#${element.id}`;
@@ -77,7 +98,9 @@ function detectTimeLimitIndicators(args) {
             path.unshift(selector);
             current = parent;
         }
-        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+        return path.length > 0
+            ? path.join(' > ')
+            : `[data-index="${elementIndex}"]`;
     }
     const metaRefresh = [];
     const metaTags = document.querySelectorAll('meta[http-equiv="refresh"]');
@@ -91,6 +114,7 @@ function detectTimeLimitIndicators(args) {
                     content,
                     seconds: parseInt(match[1] ?? '0', 10),
                     url: match[2]?.trim() || null,
+                    ...getHtmlSnippet(meta),
                 });
             }
         }
@@ -116,6 +140,7 @@ function detectTimeLimitIndicators(args) {
                             selector: getUniqueSelector(parent, elementIndex),
                             text: fullText,
                             tagName: parent.tagName.toLowerCase(),
+                            ...getHtmlSnippet(parent),
                         });
                     }
                 }
@@ -139,25 +164,31 @@ export async function runTimeLimitDetector(options) {
     });
     const indicators = await page.evaluate(detectTimeLimitIndicators, {
         keywords: [...TIME_LIMIT_KEYWORDS],
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
     const hasTimeLimits = indicators.metaRefresh.length > 0 ||
         timers.length > 0 ||
         indicators.countdownIndicators.length > 0;
-    const result = {
-        url: page.url(),
+    const details = {
         metaRefresh: indicators.metaRefresh,
         timers,
         countdownIndicators: indicators.countdownIndicators,
         hasTimeLimits,
     };
+    const result = buildAuditResult({
+        source: 'time-limit-detector',
+        url: page.url(),
+        details,
+        buckets: normalizeTimeLimitDetector(details),
+    });
     logAuditHeader('Time Limit Detection Results', 'WCAG 2.2.1', result.url);
     logSummary({
-        'Meta refresh tags': result.metaRefresh.length,
-        [`Timers detected (${minMs / 1000}s - ${maxMs / 1000}s)`]: result.timers.length,
-        'Countdown text indicators': result.countdownIndicators.length,
-        'Time limits detected': result.hasTimeLimits,
+        'Meta refresh tags': details.metaRefresh.length,
+        [`Timers detected (${minMs / 1000}s - ${maxMs / 1000}s)`]: details.timers.length,
+        'Countdown text indicators': details.countdownIndicators.length,
+        'Time limits detected': details.hasTimeLimits,
     });
-    logIssueList('Meta Refresh', result.metaRefresh, (meta, i) => {
+    logIssueList('Meta Refresh', details.metaRefresh, (meta, i) => {
         const lines = [
             `${i + 1}. content="${meta.content}"`,
             `   Refresh in ${meta.seconds} seconds`,
@@ -167,7 +198,7 @@ export async function runTimeLimitDetector(options) {
         }
         return lines;
     });
-    logIssueList('Detected Timers', result.timers, (timer, i) => {
+    logIssueList('Detected Timers', details.timers, (timer, i) => {
         const lines = [
             `${i + 1}. ${timer.type} - ${timer.delayMs}ms (${(timer.delayMs / 1000).toFixed(1)}s)`,
         ];
@@ -176,7 +207,7 @@ export async function runTimeLimitDetector(options) {
         }
         return lines;
     });
-    logIssueList('Countdown Indicators', result.countdownIndicators, (indicator, i) => {
+    logIssueList('Countdown Indicators', details.countdownIndicators, (indicator, i) => {
         const truncatedText = indicator.text.length > 80
             ? indicator.text.slice(0, 80) + '...'
             : indicator.text;

package/dist/playwright/runZoomCheck.js

@@ -15,14 +15,33 @@
  * - Does not verify responsive breakpoint behavior
  * - Manual verification needed for complex interactions at zoom
  */
-import { ZOOM_FACTOR, ZOOM_BASE_VIEWPORT, ZOOM_CLIP_TOLERANCE, REFLOW_CHECK_SELECTOR, DEFAULT_ZOOM_RESULT_FILE, DEFAULT_ZOOM_SCREENSHOT_FILE, } from '../constants.js';
+import { ZOOM_FACTOR, ZOOM_BASE_VIEWPORT, ZOOM_CLIP_TOLERANCE, REFLOW_CHECK_SELECTOR, DEFAULT_ZOOM_RESULT_FILE, DEFAULT_ZOOM_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeZoomCheck } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /** Apply zoom and detect issues in browser context. */
 function applyZoomAndCheck(args) {
-    const { checkSelector, tolerance } = args;
+    const { checkSelector, tolerance, htmlSnippetMaxLength } = args;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return {
+                html: `<${element.tagName.toLowerCase()}>`,
+                htmlTruncated: false,
+            };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
     // Apply CSS zoom
-    document.documentElement.style.zoom =
-        '200%';
+    document.documentElement.style.zoom = '200%';
     // Force reflow
     void document.body.offsetHeight;
     function getUniqueSelector(element, elementIndex) {
@@ -41,7 +60,9 @@ function applyZoomAndCheck(args) {
             path.unshift(selector);
             current = parent;
         }
-        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+        return path.length > 0
+            ? path.join(' > ')
+            : `[data-index="${elementIndex}"]`;
     }
     function isVisible(element) {
         const style = window.getComputedStyle(element);
@@ -83,6 +104,7 @@ function applyZoomAndCheck(args) {
             clippedElements.push({
                 selector: getUniqueSelector(element, index),
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 scrollWidth,
                 clientWidth,
                 scrollHeight,
@@ -104,7 +126,10 @@ function applyZoomAndCheck(args) {
  */
 export async function runZoomCheck(options) {
     const { page, targetUrl: targetUrlOption, viewport = ZOOM_BASE_VIEWPORT, screenshot = false, ...location } = options;
-    await page.setViewportSize({ width: viewport.width, height: viewport.height });
+    await page.setViewportSize({
+        width: viewport.width,
+        height: viewport.height,
+    });
     // If a URL is available, navigate at the base viewport (legacy ordering).
     const targetUrl = targetUrlOption ?? process.env.TEST_PAGE;
     if (targetUrl) {
@@ -113,24 +138,30 @@ export async function runZoomCheck(options) {
     const zoomResult = await page.evaluate(applyZoomAndCheck, {
         checkSelector: REFLOW_CHECK_SELECTOR,
         tolerance: ZOOM_CLIP_TOLERANCE,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
-    const result = {
-        url: page.url(),
+    const details = {
         zoomFactor: ZOOM_FACTOR,
         viewport: { width: viewport.width, height: viewport.height },
         ...zoomResult,
     };
+    const result = buildAuditResult({
+        source: 'zoom-200-check',
+        url: page.url(),
+        details,
+        buckets: normalizeZoomCheck(details),
+    });
     // Output results
     logAuditHeader('Zoom 200% Check Results', 'WCAG 1.4.4', result.url);
     logSummary({
-        'Zoom factor': `${result.zoomFactor}x`,
-        'Base viewport': `${result.viewport.width}x${result.viewport.height}`,
-        'Document scroll width': `${result.documentScrollWidth}px`,
-        'Document client width': `${result.documentClientWidth}px`,
-        'Horizontal scroll': result.hasHorizontalScroll,
-        'Clipped elements': result.clippedElements.length,
+        'Zoom factor': `${details.zoomFactor}x`,
+        'Base viewport': `${details.viewport.width}x${details.viewport.height}`,
+        'Document scroll width': `${details.documentScrollWidth}px`,
+        'Document client width': `${details.documentClientWidth}px`,
+        'Horizontal scroll': details.hasHorizontalScroll,
+        'Clipped elements': details.clippedElements.length,
     });
-    logIssueList('Clipped Elements', result.clippedElements, (el, i) => [
+    logIssueList('Clipped Elements', details.clippedElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   scrollWidth: ${el.scrollWidth}px, clientWidth: ${el.clientWidth}px`,
         `   Issue: ${el.issueType}`,

package/dist/schemas/index.d.ts

@@ -6,18 +6,25 @@
  * (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.
+ *
+ * Every check shares the same envelope (`source` / `url` / `timestamp` / the
+ * four normalized buckets / `summary` / `details` / `disclaimer`); the common
+ * pieces live in `$defs` and each check schema defines its own `details`.
  */
-export type { AxeViolationNode, AxeViolation, AxeAuditResult, FocusRecord, OnFocusViolation, FocusCheckResult, BoundingRect, FocusObscuredOverlap, FocusObscuredIssue, ReflowIssue, ClippedTextElement, ReflowCheckResult, TargetSizeException, TargetSizeIssue, TargetSizeSummary, TargetSizeCheckResult, TextSpacingIssue, TextSpacingCheckResult, ZoomIssue, ZoomCheckResult, OrientationState, OrientationCheckResult, AutocompleteIssue, AutocompleteAuditResult, MetaRefreshInfo, TimerInfo, CountdownIndicator, TimeLimitDetectorResult, ScreenshotRecord, ComparisonResult, ImageDiffResult, PauseControl, CarouselIndicator, PauseControlInfo, PauseVerificationResult, AutoPlayDetectionResult, } from '../types.js';
+export type { AuditCheckResult, AuditResultSummary, CheckSource, NormalizedImpact, NormalizedNode, NormalizedRuleResult, AxeAuditDetails, AxeAuditResult, FocusRecord, FocusElementRef, OnFocusViolation, FocusCheckDetails, FocusCheckResult, BoundingRect, FocusObscuredOverlap, FocusObscuredIssue, ReflowIssue, ClippedTextElement, ReflowCheckDetails, ReflowCheckResult, TargetSizeException, TargetSizeExceptionAssessment, TargetSizeIssue, TargetSizeSummary, TargetSizeCheckDetails, TargetSizeCheckResult, TextSpacingIssue, TextSpacingCheckDetails, TextSpacingCheckResult, ZoomIssue, ZoomCheckDetails, ZoomCheckResult, OrientationState, OrientationCheckDetails, OrientationCheckResult, AutocompleteIssue, AutocompleteAuditDetails, AutocompleteAuditResult, MetaRefreshInfo, TimerInfo, CountdownIndicator, TimeLimitDetectorDetails, TimeLimitDetectorResult, ScreenshotRecord, ComparisonResult, ImageDiffResult, PauseControl, CarouselIndicator, PauseControlInfo, PauseVerificationResult, AutoPlayDetectionDetails, AutoPlayDetectionResult, } from '../types.js';
 /** Minimal JSON Schema object shape (Draft 2020-12 compatible subset). */
 export interface JsonSchema {
     $schema?: string;
     $id?: string;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
     title?: string;
     type?: string | string[];
     properties?: Record<string, JsonSchema>;
     items?: JsonSchema;
     required?: string[];
     enum?: unknown[];
+    const?: unknown;
     description?: string;
     [key: string]: unknown;
 }