@a11y-skills/audit 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 All notable changes to `@a11y-skills/audit` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.3.1
+
+### Fixed
+
+- `runFocusIndicatorCheck`: focus-triggered navigations slower than the
+  per-Tab settle window are no longer silently missed. The settle window is
+  now configurable via the new `navigationSettleMs` option (default: 50), and
+  a `framenavigated` listener additionally catches URL changes that commit and
+  revert within a single window. (#26)
+
+## 0.3.0
+
+**Breaking** — every check now returns (and saves) a single axe-style envelope
+instead of its own ad-hoc shape. The public API is not yet stable in `0.x`, so
+this lands as a minor release.
+
+### Changed (breaking)
+
+- All `runXxx()` functions return `AuditCheckResult<TDetails>`: findings are
+  normalized into `violations` / `incomplete` / `passes` / `inapplicable`
+  rule arrays (axe-style `id` / `impact` / `tags` / `helpUrl` / `nodes`), with
+  rule-level counts in `summary`. The former top-level fields (`issues`,
+  `failAA`, `overflowingElements`, `clippedElements`, ...) moved unchanged
+  under `details`.
+- Classification is conservative: only findings whose detection has no blind
+  spot and where no WCAG exception can apply are `violations`
+  (on-focus context change, text-spacing clipping, invalid autocomplete
+  tokens). Everything else — reflow/zoom overflow, meta refresh, orientation
+  lock, missing focus styles, undersized targets — lands in `incomplete`, the
+  manual-review queue.
+- Saved JSON files use the same envelope; the JSON Schemas were rewritten
+  accordingly (`$defs`-based shared envelope + per-check `details` schemas).
+  Pre-0.3.0 result files no longer validate.
+- `saveAuditResult()` no longer appends a disclaimer (the envelope carries it).
+- `runAxeAudit` builds the buckets from the raw axe results: violations and
+  incomplete keep their nodes, passes/inapplicable keep rule metadata only;
+  `details` records the execution configuration.
+
+### Added
+
+- `rule-registry.ts`: per-rule metadata (`sc`, accurate per-SC `wcag*` tags,
+  `impact`, `scope`, classification) — target size split into
+  `a11y-skills/target-size-minimum` (2.5.8 AA) and
+  `a11y-skills/target-size-enhanced` (2.5.5 AAA).
+- Pure normalization mappers (`normalize*`), `buildAuditResult()`, and the
+  opt-in `mergeNormalizedResults()` exported from the package root. The
+  buckets are re-derivable from a saved result's `details`.
+- Element-level evidence: detail records now carry `html` (outerHTML, capped
+  at `HTML_SNIPPET_MAX_LENGTH`) and `htmlTruncated`; focus issues gained
+  `selector`. `TargetSizeIssue.exceptionAssessment`
+  (`ruled-out`/`possible`/`not-assessed`) drives the violation promotion.
+- Tests: mapper unit tests, merge invariants, and ajv (draft 2020-12) schema
+  validation of the produced envelopes.
+
 ## 0.2.0
 
 Phase 2 checks added (additive). Still a `0.x` preview — the function API may

package/README.ja.md

@@ -67,7 +67,7 @@ test("axe audit", async ({ page }, testInfo) => {
     // outputFile: "axe-result.json", // 任意で上書き
     // tags: ["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"],
   });
-  expect(result.violationCount).toBe(0);
+  expect(result.summary.violationCount).toBe(0);
 });
 ```
 
@@ -86,7 +86,7 @@ test("focus indicators", async ({ browser }, testInfo) => {
     screenshot: true,                 // 既定: false
     // contextOptions: { locale: "ja-JP" }, // browser.newContext() に転送
   });
-  expect(result.elementsWithoutFocusStyle).toBe(0);
+  expect(result.details.elementsWithoutFocusStyle).toBe(0);
 });
 ```
 
@@ -135,6 +135,52 @@ TEST_PAGE=https://example.com A11Y_OUTPUT_DIR=./a11y-results npx playwright test
 > を `testMatch` に指定してもテストは見つかりません。上記の 1 行 re-export spec が
 > entry を実行する正式な方法です。
 
+## 結果形式
+
+すべての検査は同じ axe 風の envelope を返し、同じ形式で JSON に保存します:
+
+```ts
+interface AuditCheckResult<TDetails> {
+  source: CheckSource;            // 例: "reflow-check"
+  url: string;
+  timestamp: string;
+  violations: NormalizedRuleResult[];   // 確定した違反
+  incomplete: NormalizedRuleResult[];   // 要手動確認
+  passes: NormalizedRuleResult[];       // 実行して問題が見つからなかったルール
+  inapplicable: NormalizedRuleResult[]; // 検査対象がなかったルール
+  summary: { violationCount; incompleteCount; passCount; checkedNodes? };
+  details: TDetails;              // 検査固有の証跡（測定値・スクリーンショット等）
+  disclaimer: { ... };
+}
+```
+
+各ルール結果は axe と同じ形（`id` / `impact` / `description` / `help` /
+`helpUrl` / `tags` / `nodes[]`、`nodes[].target` / `html` / `htmlTruncated` /
+`failureSummary`）です。独自ルールは名前空間付き
+（`a11y-skills/focus-visible`、`a11y-skills/target-size-minimum` など）で、
+SC ごとに正確な WCAG バージョン・レベルタグ（`wcag2aa`、`wcag21aa`、
+`wcag22aa`、`wcag247` 形式の SC タグ）が付きます。
+
+**分類は保守的です。** 検出に死角がなく WCAG の例外が適用され得ない場合のみ
+`violations` に入ります（フォーカスによる文脈変化、テキストスペーシングの
+クリップ、autocomplete の不正トークン）。それ以外の検出 — reflow/zoom の
+オーバーフロー、meta refresh、画面方向ロック、フォーカススタイル欠如、
+小さすぎるターゲット — は `incomplete` に入ります。`incomplete` はノイズでは
+なく「要手動確認キュー」として扱ってください。
+
+同一ページに対する複数検査の結果を 1 つにまとめるには:
+
+```ts
+import { mergeNormalizedResults } from "@a11y-skills/audit";
+
+const merged = mergeNormalizedResults([axeResult, reflowResult, targetResult]);
+```
+
+`mergeNormalizedResults` は URL 不一致で例外を投げ、ノードを
+`target` + `failureSummary` で重複排除し、複数バケツに現れるルールは
+`violations > incomplete > passes > inapplicable` の優先順位で統合します。
+frame / shadow root 内の同一セレクタは区別しません。
+
 ## 結果型とスキーマ
 
 ```ts
@@ -142,8 +188,10 @@ import type { AxeAuditResult, FocusCheckResult } from "@a11y-skills/audit/schema
 import { RESULT_SCHEMAS } from "@a11y-skills/audit/schemas";
 ```
 
-`RESULT_SCHEMAS` は各検査 id に手書きの JSON Schema を対応付けており、`*-result.json`
-を実行時に検証できます。
+`RESULT_SCHEMAS` は各検査 id に手書きの JSON Schema（draft 2020-12）を
+対応付けており、`*-result.json` を実行時に検証できます。正規化マッパー
+（`normalize*`）と `buildAuditResult` はパッケージルートから export されて
+いるため、保存済み結果の `details` から 4 区分をいつでも再導出できます。
 
 ## ライセンス
 

package/README.md

@@ -69,7 +69,7 @@ test("axe audit", async ({ page }, testInfo) => {
     // outputFile: "axe-result.json", // optional override
     // tags: ["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"],
   });
-  expect(result.violationCount).toBe(0);
+  expect(result.summary.violationCount).toBe(0);
 });
 ```
 
@@ -88,7 +88,7 @@ test("focus indicators", async ({ browser }, testInfo) => {
     screenshot: true,                 // default: false
     // contextOptions: { locale: "ja-JP" }, // forwarded to browser.newContext()
   });
-  expect(result.elementsWithoutFocusStyle).toBe(0);
+  expect(result.details.elementsWithoutFocusStyle).toBe(0);
 });
 ```
 
@@ -138,6 +138,52 @@ TEST_PAGE=https://example.com A11Y_OUTPUT_DIR=./a11y-results npx playwright test
 > `**/node_modules/@a11y-skills/audit/dist/test-entries/*.js` finds no tests.
 > The one-line re-export specs above are the supported way to run the entries.
 
+## Result format
+
+Every check returns — and saves as JSON — the same axe-style envelope:
+
+```ts
+interface AuditCheckResult<TDetails> {
+  source: CheckSource;            // e.g. "reflow-check"
+  url: string;
+  timestamp: string;
+  violations: NormalizedRuleResult[];   // confirmed findings
+  incomplete: NormalizedRuleResult[];   // needs manual review
+  passes: NormalizedRuleResult[];       // rules that ran and found nothing
+  inapplicable: NormalizedRuleResult[]; // nothing to examine
+  summary: { violationCount; incompleteCount; passCount; checkedNodes? };
+  details: TDetails;              // check-specific evidence (measurements, screenshots, ...)
+  disclaimer: { ... };
+}
+```
+
+Each rule result is axe-shaped (`id` / `impact` / `description` / `help` /
+`helpUrl` / `tags` / `nodes[]`, with `nodes[].target` / `html` /
+`htmlTruncated` / `failureSummary`). Custom rules are namespaced
+(`a11y-skills/focus-visible`, `a11y-skills/target-size-minimum`, ...) and
+tagged with accurate WCAG version/level tags (`wcag2aa`, `wcag21aa`,
+`wcag22aa`, `wcag247`-style SC tags).
+
+**Classification is conservative.** A finding lands in `violations` only when
+the detection has no blind spot and no WCAG exception can apply (on-focus
+context change, text-spacing clipping, invalid autocomplete tokens). All other
+detections — reflow/zoom overflow, meta refresh, orientation lock, missing
+focus styles, undersized targets — are `incomplete`: treat that bucket as the
+manual-review queue, not as noise.
+
+To combine several checks for the same page into one view:
+
+```ts
+import { mergeNormalizedResults } from "@a11y-skills/audit";
+
+const merged = mergeNormalizedResults([axeResult, reflowResult, targetResult]);
+```
+
+`mergeNormalizedResults` throws on URL mismatches, deduplicates nodes by
+`target` + `failureSummary`, and resolves a rule appearing in several buckets
+by priority (`violations > incomplete > passes > inapplicable`). Identical
+selectors inside different frames or shadow roots are not distinguished.
+
 ## Result types & schemas
 
 ```ts
@@ -145,8 +191,11 @@ import type { AxeAuditResult, FocusCheckResult } from "@a11y-skills/audit/schema
 import { RESULT_SCHEMAS } from "@a11y-skills/audit/schemas";
 ```
 
-`RESULT_SCHEMAS` maps each check id to a hand-written JSON Schema for validating
-the `*-result.json` files at runtime.
+`RESULT_SCHEMAS` maps each check id to a hand-written JSON Schema
+(draft 2020-12) for validating the `*-result.json` files at runtime. The
+normalization mappers (`normalize*`) and `buildAuditResult` are exported from
+the package root, so the buckets can be re-derived from a saved result's
+`details` at any time.
 
 ## License
 

package/dist/constants.d.ts

@@ -14,6 +14,8 @@ export declare const AUDIT_DISCLAIMER: {
 };
 /** Console disclaimer message */
 export declare const DISCLAIMER_CONSOLE = "\nNote: Automated testing detects only ~30-40% of WCAG issues.\n      Manual testing is required for complete accessibility evaluation.\n";
+/** Maximum length of `NormalizedNode.html` / detail `html` snippets. */
+export declare const HTML_SNIPPET_MAX_LENGTH = 300;
 /** Default axe-core tag set (WCAG 2.0/2.1/2.2 A & AA) */
 export declare const DEFAULT_AXE_TAGS: readonly ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
 /** CSS properties to check for focus style changes */
@@ -22,6 +24,8 @@ export declare const FOCUS_STYLE_PROPERTIES: readonly ["outline", "outlineStyle"
 export declare const FOCUSABLE_SELECTOR: string;
 /** Extra tab iterations for safety margin */
 export declare const EXTRA_TAB_ITERATIONS = 10;
+/** Default ms to wait after each Tab press for a focus-triggered navigation to surface. */
+export declare const DEFAULT_NAVIGATION_SETTLE_MS = 50;
 /**
  * Minimum overlap ratio to report as obscured (0-1)
  * 0.2 means 20% of the focused element must be covered

package/dist/constants.js

@@ -21,6 +21,11 @@ Note: Automated testing detects only ~30-40% of WCAG issues.
       Manual testing is required for complete accessibility evaluation.
 `;
 // =============================================================================
+// Normalized result format
+// =============================================================================
+/** Maximum length of `NormalizedNode.html` / detail `html` snippets. */
+export const HTML_SNIPPET_MAX_LENGTH = 300;
+// =============================================================================
 // Axe Audit defaults (broad WCAG coverage)
 // =============================================================================
 /** Default axe-core tag set (WCAG 2.0/2.1/2.2 A & AA) */
@@ -55,6 +60,8 @@ export const FOCUSABLE_SELECTOR = `
 `.trim();
 /** Extra tab iterations for safety margin */
 export const EXTRA_TAB_ITERATIONS = 10;
+/** Default ms to wait after each Tab press for a focus-triggered navigation to surface. */
+export const DEFAULT_NAVIGATION_SETTLE_MS = 50;
 // =============================================================================
 // Focus Obscured Detection Constants (WCAG 2.4.12)
 // =============================================================================
@@ -315,18 +322,62 @@ export const AUTOCOMPLETE_FIELD_PATTERNS = {
 };
 /** Valid autocomplete token values */
 export const VALID_AUTOCOMPLETE_TOKENS = [
-    'off', 'on',
-    'name', 'honorific-prefix', 'given-name', 'additional-name', 'family-name', 'honorific-suffix', 'nickname',
-    'email', 'username', 'new-password', 'current-password', 'one-time-code',
-    'organization-title', 'organization',
-    'street-address', 'address-line1', 'address-line2', 'address-line3',
-    'address-level1', 'address-level2', 'address-level3', 'address-level4',
-    'country', 'country-name', 'postal-code',
-    'cc-name', 'cc-given-name', 'cc-additional-name', 'cc-family-name', 'cc-number', 'cc-exp', 'cc-exp-month', 'cc-exp-year', 'cc-csc', 'cc-type',
-    'transaction-currency', 'transaction-amount',
-    'language', 'bday', 'bday-day', 'bday-month', 'bday-year', 'sex',
-    'tel', 'tel-country-code', 'tel-national', 'tel-area-code', 'tel-local', 'tel-local-prefix', 'tel-local-suffix', 'tel-extension',
-    'impp', 'url', 'photo',
+    'off',
+    'on',
+    'name',
+    'honorific-prefix',
+    'given-name',
+    'additional-name',
+    'family-name',
+    'honorific-suffix',
+    'nickname',
+    'email',
+    'username',
+    'new-password',
+    'current-password',
+    'one-time-code',
+    'organization-title',
+    'organization',
+    'street-address',
+    'address-line1',
+    'address-line2',
+    'address-line3',
+    'address-level1',
+    'address-level2',
+    'address-level3',
+    'address-level4',
+    'country',
+    'country-name',
+    'postal-code',
+    'cc-name',
+    'cc-given-name',
+    'cc-additional-name',
+    'cc-family-name',
+    'cc-number',
+    'cc-exp',
+    'cc-exp-month',
+    'cc-exp-year',
+    'cc-csc',
+    'cc-type',
+    'transaction-currency',
+    'transaction-amount',
+    'language',
+    'bday',
+    'bday-day',
+    'bday-month',
+    'bday-year',
+    'sex',
+    'tel',
+    'tel-country-code',
+    'tel-national',
+    'tel-area-code',
+    'tel-local',
+    'tel-local-prefix',
+    'tel-local-suffix',
+    'tel-extension',
+    'impp',
+    'url',
+    'photo',
 ];
 export const DEFAULT_AUTOCOMPLETE_RESULT_FILE = 'autocomplete-result.json';
 // =============================================================================
@@ -380,28 +431,60 @@ export const DETECTION_RESULT_FILENAME = 'detection-result.json';
 /** Keywords for pause/stop controls (EN/JP) */
 export const PAUSE_KEYWORDS = [
     // English
-    'pause', 'stop', 'halt', 'freeze', 'play',
+    'pause',
+    'stop',
+    'halt',
+    'freeze',
+    'play',
     // Japanese
-    '一時停止', '停止', 'ポーズ', '止める', '再生',
+    '一時停止',
+    '停止',
+    'ポーズ',
+    '止める',
+    '再生',
 ];
 /** Class name patterns indicating pause/play controls */
 export const CONTROL_CLASS_PATTERNS = [
-    'pause', 'play', 'stop', 'toggle', 'switch',
-    'control', 'btn-pause', 'btn-play', 'btn-stop',
+    'pause',
+    'play',
+    'stop',
+    'toggle',
+    'switch',
+    'control',
+    'btn-pause',
+    'btn-play',
+    'btn-stop',
 ];
 /** Carousel-related class patterns */
 export const CAROUSEL_PATTERNS = [
-    'carousel', 'slider', 'slide', 'swiper', 'slick',
-    'hero', 'banner', 'gallery', 'rotator',
+    'carousel',
+    'slider',
+    'slide',
+    'swiper',
+    'slick',
+    'hero',
+    'banner',
+    'gallery',
+    'rotator',
 ];
 /** Navigation control keywords */
 export const NAV_KEYWORDS = [
-    'prev', 'next', '前', '次', 'arrow', 'dot', 'indicator',
+    'prev',
+    'next',
+    '前',
+    '次',
+    'arrow',
+    'dot',
+    'indicator',
 ];
 /** SVG metadata patterns to exclude from accessible names */
 export const SVG_METADATA_PATTERNS = [
-    'created with', 'made with', 'generated by',
-    'svg', 'icon', 'symbol',
+    'created with',
+    'made with',
+    'generated by',
+    'svg',
+    'icon',
+    'symbol',
 ];
 /** Maximum parent levels to check for carousel context */
 export const MAX_PARENT_LEVELS = 5;

package/dist/index.d.ts

@@ -10,4 +10,6 @@
  * - `@a11y-skills/audit/schemas`: result types & JSON Schemas.
  */
 export * from './types.js';
-export { AUDIT_DISCLAIMER, DEFAULT_AXE_TAGS, REFLOW_VIEWPORT, TARGET_SIZE_AA, TARGET_SIZE_AAA, } from './constants.js';
+export { AUDIT_DISCLAIMER, DEFAULT_AXE_TAGS, HTML_SNIPPET_MAX_LENGTH, REFLOW_VIEWPORT, TARGET_SIZE_AA, TARGET_SIZE_AAA, } from './constants.js';
+export { RULES, getRule, type RuleKey, type RuleMeta, } from './utils/rule-registry.js';
+export { buildAuditResult, mergeNormalizedResults, normalizeAxeResults, normalizeAutocompleteAudit, normalizeAutoPlayDetection, normalizeFocusCheck, normalizeOrientationCheck, normalizeReflowCheck, normalizeTargetSizeCheck, normalizeTextSpacingCheck, normalizeTimeLimitDetector, normalizeZoomCheck, type MergedAuditResult, type NormalizedBuckets, type RawAxeResults, type RawAxeRule, } from './utils/axe-format.js';

package/dist/index.js

@@ -10,4 +10,6 @@
  * - `@a11y-skills/audit/schemas`: result types & JSON Schemas.
  */
 export * from './types.js';
-export { AUDIT_DISCLAIMER, DEFAULT_AXE_TAGS, REFLOW_VIEWPORT, TARGET_SIZE_AA, TARGET_SIZE_AAA, } from './constants.js';
+export { AUDIT_DISCLAIMER, DEFAULT_AXE_TAGS, HTML_SNIPPET_MAX_LENGTH, REFLOW_VIEWPORT, TARGET_SIZE_AA, TARGET_SIZE_AAA, } from './constants.js';
+export { RULES, getRule, } from './utils/rule-registry.js';
+export { buildAuditResult, mergeNormalizedResults, normalizeAxeResults, normalizeAutocompleteAudit, normalizeAutoPlayDetection, normalizeFocusCheck, normalizeOrientationCheck, normalizeReflowCheck, normalizeTargetSizeCheck, normalizeTextSpacingCheck, normalizeTimeLimitDetector, normalizeZoomCheck, } from './utils/axe-format.js';

package/dist/playwright/index.d.ts

@@ -14,7 +14,7 @@
  */
 export { runAxeAudit, type RunAxeAuditOptions } from './runAxeAudit.js';
 export { runFocusIndicatorCheck, type RunFocusIndicatorCheckOptions, } from './runFocusIndicatorCheck.js';
-export { runReflowCheck, type RunReflowCheckOptions } from './runReflowCheck.js';
+export { runReflowCheck, type RunReflowCheckOptions, } from './runReflowCheck.js';
 export { runTargetSizeCheck, type RunTargetSizeCheckOptions, } from './runTargetSizeCheck.js';
 export { runTextSpacingCheck, type RunTextSpacingCheckOptions, } from './runTextSpacingCheck.js';
 export { runZoomCheck, type RunZoomCheckOptions } from './runZoomCheck.js';

package/dist/playwright/index.js

@@ -14,7 +14,7 @@
  */
 export { runAxeAudit } from './runAxeAudit.js';
 export { runFocusIndicatorCheck, } from './runFocusIndicatorCheck.js';
-export { runReflowCheck } from './runReflowCheck.js';
+export { runReflowCheck, } from './runReflowCheck.js';
 export { runTargetSizeCheck, } from './runTargetSizeCheck.js';
 export { runTextSpacingCheck, } from './runTextSpacingCheck.js';
 export { runZoomCheck } from './runZoomCheck.js';

package/dist/playwright/runAutoPlayDetection.js

@@ -15,7 +15,8 @@
  */
 import * as path from 'node:path';
 import { SCREENSHOT_INTERVALS, CHANGE_THRESHOLD, DEFAULT_AUTO_PLAY_OUTPUT_DIR, DETECTION_RESULT_FILENAME, } from '../constants.js';
-import { generateRecommendation, printSummary } from '../utils/recommendations.js';
+import { buildAuditResult, normalizeAutoPlayDetection, } from '../utils/axe-format.js';
+import { generateRecommendation, printSummary, } from '../utils/recommendations.js';
 /** Capture screenshots at configured intervals. */
 async function captureScreenshots(page, outputDir) {
     const screenshots = [];
@@ -114,8 +115,7 @@ export async function runAutoPlayDetection(options) {
         }
         pauseVerification = createSkippedVerification(reason);
     }
-    const result = {
-        url: page.url(),
+    const details = {
         screenshotRecords: screenshots,
         comparisons,
         hasAutoPlayContent: hasAnyChange,
@@ -129,9 +129,20 @@ export async function runAutoPlayDetection(options) {
             pauseVerification,
         }),
     };
+    const result = buildAuditResult({
+        source: 'auto-play-detection',
+        url: page.url(),
+        details,
+        buckets: normalizeAutoPlayDetection(details),
+    });
     console.log('\n=== Auto-play Detection Results ===\n');
     console.log(JSON.stringify(result, null, 2));
     saveJsonResult(path.join(outputDir, DETECTION_RESULT_FILENAME), result);
-    printSummary({ hasAutoPlayContent: hasAnyChange, stopsWithin5Seconds, pauseControls, pauseVerification }, outputDir);
+    printSummary({
+        hasAutoPlayContent: hasAnyChange,
+        stopsWithin5Seconds,
+        pauseControls,
+        pauseVerification,
+    }, outputDir);
     return result;
 }

package/dist/playwright/runAutocompleteAudit.js

@@ -13,13 +13,34 @@
  * - Cannot confirm actual field purpose; pattern matching is heuristic
  * - Manual verification needed for edge cases
  */
-import { AUTOCOMPLETE_FIELD_PATTERNS, VALID_AUTOCOMPLETE_TOKENS, DEFAULT_AUTOCOMPLETE_RESULT_FILE, } from '../constants.js';
+import { AUTOCOMPLETE_FIELD_PATTERNS, VALID_AUTOCOMPLETE_TOKENS, DEFAULT_AUTOCOMPLETE_RESULT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeAutocompleteAudit, } from '../utils/axe-format.js';
 import { saveAuditResult, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /**
  * Collect basic form field information in browser context.
  * Accessible names are retrieved separately via ariaSnapshot().
  */
-function collectBasicFieldInfo() {
+function collectBasicFieldInfo(args) {
+    const { 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}`;
@@ -36,7 +57,9 @@ function collectBasicFieldInfo() {
             path.unshift(selector);
             current = parent;
         }
-        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+        return path.length > 0
+            ? path.join(' > ')
+            : `[data-index="${elementIndex}"]`;
     }
     const skipTypes = ['hidden', 'submit', 'reset', 'button', 'image', 'file'];
     const fields = [];
@@ -51,6 +74,7 @@ function collectBasicFieldInfo() {
         fields.push({
             selector: getUniqueSelector(element, index),
             tagName: el.tagName.toLowerCase(),
+            ...getHtmlSnippet(element),
             inputType,
             name: el.name || null,
             id: el.id || null,
@@ -106,6 +130,8 @@ function analyzeFields(fields, patterns, validTokens) {
             missing.push({
                 selector: field.selector,
                 tagName: field.tagName,
+                html: field.html,
+                htmlTruncated: field.htmlTruncated,
                 inputType: field.inputType,
                 name: field.name,
                 id: field.id,
@@ -124,6 +150,8 @@ function analyzeFields(fields, patterns, validTokens) {
             invalid.push({
                 selector: field.selector,
                 tagName: field.tagName,
+                html: field.html,
+                htmlTruncated: field.htmlTruncated,
                 inputType: field.inputType,
                 name: field.name,
                 id: field.id,
@@ -144,7 +172,9 @@ function analyzeFields(fields, patterns, validTokens) {
 export async function runAutocompleteAudit(options) {
     const { page, ...location } = options;
     // Collect basic field info from DOM
-    const basicFields = await page.evaluate(collectBasicFieldInfo);
+    const basicFields = await page.evaluate(collectBasicFieldInfo, {
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
+    });
     // Enhance with accessible names via ariaSnapshot()
     const fields = [];
     for (const basicField of basicFields) {
@@ -164,26 +194,31 @@ export async function runAutocompleteAudit(options) {
     }
     const patterns = Object.entries(AUTOCOMPLETE_FIELD_PATTERNS);
     const { missing, invalid } = analyzeFields(fields, patterns, VALID_AUTOCOMPLETE_TOKENS);
-    const result = {
-        url: page.url(),
+    const details = {
         totalFieldsChecked: fields.length,
         missingAutocomplete: missing,
         invalidAutocomplete: invalid,
     };
+    const result = buildAuditResult({
+        source: 'autocomplete-audit',
+        url: page.url(),
+        details,
+        buckets: normalizeAutocompleteAudit(details),
+    });
     // Output results
     logAuditHeader('Autocomplete Audit Results', 'WCAG 1.3.5', result.url);
     logSummary({
-        'Total form fields': result.totalFieldsChecked,
-        'Fields missing autocomplete': result.missingAutocomplete.length,
-        'Fields with invalid autocomplete': result.invalidAutocomplete.length,
+        'Total form fields': details.totalFieldsChecked,
+        'Fields missing autocomplete': details.missingAutocomplete.length,
+        'Fields with invalid autocomplete': details.invalidAutocomplete.length,
     });
-    logIssueList('Missing Autocomplete', result.missingAutocomplete, (el, i) => [
+    logIssueList('Missing Autocomplete', details.missingAutocomplete, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   name: ${el.name || 'none'}, id: ${el.id || 'none'}`,
         `   label: "${el.labelText || 'none'}"`,
         `   Expected: autocomplete="${el.expectedToken}" (matched by ${el.matchedBy})`,
     ]);
-    logIssueList('Invalid Autocomplete', result.invalidAutocomplete, (el, i) => [
+    logIssueList('Invalid Autocomplete', details.invalidAutocomplete, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   Current: autocomplete="${el.currentAutocomplete}"`,
         `   Expected: autocomplete="${el.expectedToken}"`,

package/dist/playwright/runAxeAudit.d.ts

@@ -5,6 +5,10 @@
  * caller is responsible for navigating the page (e.g. `await page.goto(url)`)
  * before calling this function.
  *
+ * The normalized buckets are built from the RAW axe results (violations and
+ * incomplete keep their nodes; passes/inapplicable keep rule metadata only),
+ * and `details` records the execution configuration.
+ *
  * Axe-core cannot detect all accessibility issues — manual testing and the
  * other checks in this package are still needed for complete coverage.
  */