@a11y-skills/audit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,50 @@
 All notable changes to `@a11y-skills/audit` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## 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 */

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) */

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/runAutoPlayDetection.js

@@ -15,6 +15,7 @@
  */
 import * as path from 'node:path';
 import { SCREENSHOT_INTERVALS, CHANGE_THRESHOLD, DEFAULT_AUTO_PLAY_OUTPUT_DIR, DETECTION_RESULT_FILENAME, } from '../constants.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) {
@@ -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,6 +129,12 @@ 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);

package/dist/playwright/runAutocompleteAudit.js

@@ -13,13 +13,31 @@
  * - 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}`;
@@ -51,6 +69,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 +125,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 +145,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 +167,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 +189,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.
  */

package/dist/playwright/runAxeAudit.js

@@ -5,11 +5,16 @@
  * 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.
  */
 import { AxeBuilder } from '@axe-core/playwright';
-import { AUDIT_DISCLAIMER, DEFAULT_AXE_TAGS, DEFAULT_AXE_RESULT_FILE, } from '../constants.js';
+import { DEFAULT_AXE_TAGS, DEFAULT_AXE_RESULT_FILE } from '../constants.js';
+import { buildAuditResult, normalizeAxeResults } from '../utils/axe-format.js';
 import { saveAuditResult, logAuditHeader, logSummary, logOutputPaths, } from '../utils/test-harness.js';
 /**
  * Run an axe-core audit against the current page, write the result JSON, and
@@ -22,36 +27,29 @@ export async function runAxeAudit(options) {
         builder = builder.options({ rules });
     }
     const axeResults = await builder.analyze();
-    const result = {
-        url: page.url(),
-        timestamp: new Date().toISOString(),
-        violations: axeResults.violations.map((v) => ({
-            id: v.id,
-            impact: v.impact ?? null,
-            description: v.description,
-            help: v.help,
-            helpUrl: v.helpUrl,
-            tags: v.tags,
-            nodes: v.nodes.map((n) => ({
-                html: n.html,
-                target: n.target,
-                failureSummary: n.failureSummary,
-            })),
-        })),
-        passes: axeResults.passes.length,
-        incomplete: axeResults.incomplete.length,
-        inapplicable: axeResults.inapplicable.length,
-        violationCount: axeResults.violations.length,
-        disclaimer: AUDIT_DISCLAIMER,
+    const buckets = normalizeAxeResults(axeResults);
+    const details = {
+        tagsRun: [...tags],
+        rulesOverride: rules ?? null,
+        violationRuleCount: axeResults.violations.length,
+        passRuleCount: axeResults.passes.length,
+        incompleteRuleCount: axeResults.incomplete.length,
+        inapplicableRuleCount: axeResults.inapplicable.length,
     };
+    const result = buildAuditResult({
+        source: 'axe-audit',
+        url: page.url(),
+        details,
+        buckets,
+    });
     // Output results
     logAuditHeader('Axe-core Accessibility Audit Results', 'axe-core', result.url);
     logSummary({
         Timestamp: result.timestamp,
-        Violations: result.violationCount,
-        Passes: result.passes,
-        'Incomplete (needs review)': result.incomplete,
-        Inapplicable: result.inapplicable,
+        Violations: result.summary.violationCount,
+        Passes: result.summary.passCount,
+        'Incomplete (needs review)': result.summary.incompleteCount,
+        Inapplicable: result.inapplicable.length,
     });
     if (result.violations.length > 0) {
         console.log('\n--- Violations ---');
@@ -71,18 +69,16 @@ export async function runAxeAudit(options) {
         });
     }
     console.log(`\n--- Summary ---`);
-    if (result.violationCount === 0) {
+    if (result.summary.violationCount === 0) {
         console.log('No violations detected by axe-core');
     }
     else {
         const totalElements = result.violations.reduce((sum, v) => sum + v.nodes.length, 0);
-        console.log(`Found ${result.violationCount} violation type(s) affecting ${totalElements} element(s)`);
+        console.log(`Found ${result.summary.violationCount} violation type(s) affecting ${totalElements} element(s)`);
     }
-    // axe results already carry the disclaimer field; don't append it again.
     const resolvedPath = saveAuditResult(result, {
         ...location,
         defaultFile: DEFAULT_AXE_RESULT_FILE,
-        includeDisclaimer: false,
     });
     logOutputPaths(resolvedPath);
     return result;

package/dist/playwright/runFocusIndicatorCheck.js

@@ -10,7 +10,8 @@
  *
  * The context this function creates is closed before it returns.
  */
-import { FOCUSABLE_SELECTOR, FOCUS_STYLE_PROPERTIES, EXTRA_TAB_ITERATIONS, DEFAULT_FOCUS_RESULT_FILE, DEFAULT_FOCUS_SCREENSHOT_FILE, FOCUS_OBSCURED_MIN_OVERLAP_RATIO, FOCUS_OBSCURED_MIN_OVERLAP_PX, FOCUS_OBSCURED_EXCLUDE_SELECTORS, } from '../constants.js';
+import { FOCUSABLE_SELECTOR, FOCUS_STYLE_PROPERTIES, EXTRA_TAB_ITERATIONS, DEFAULT_FOCUS_RESULT_FILE, DEFAULT_FOCUS_SCREENSHOT_FILE, FOCUS_OBSCURED_MIN_OVERLAP_RATIO, FOCUS_OBSCURED_MIN_OVERLAP_PX, FOCUS_OBSCURED_EXCLUDE_SELECTORS, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeFocusCheck } from '../utils/axe-format.js';
 import { resolveOutputPath, resolveScreenshotPath, saveAuditResult, takeAuditScreenshot, requireTargetUrl, logAuditHeader, logOutputPaths, } from '../utils/test-harness.js';
 // =============================================================================
 // Browser-injected styles for marking elements
@@ -106,6 +107,8 @@ export async function runFocusIndicatorCheck(options) {
                     name: data.name,
                     selector: data.selector ||
                         `${data.tag.toLowerCase()}:nth-of-type(${data.id + 1})`,
+                    html: data.html,
+                    htmlTruncated: data.htmlTruncated,
                 };
             });
             // Expose function to receive focus obscured reports (WCAG 2.4.12)
@@ -118,6 +121,7 @@ export async function runFocusIndicatorCheck(options) {
                 styleProperties: [...FOCUS_STYLE_PROPERTIES],
                 warningStyles: WARNING_STYLES,
                 skipSelectors: [...skipSelectors],
+                htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
                 obscuredConfig: {
                     minOverlapRatio: FOCUS_OBSCURED_MIN_OVERLAP_RATIO,
                     minOverlapPx: FOCUS_OBSCURED_MIN_OVERLAP_PX,
@@ -163,7 +167,7 @@ export async function runFocusIndicatorCheck(options) {
                 // Get currently focused element IMMEDIATELY after Tab
                 let currentFocusedElement = null;
                 try {
-                    currentFocusedElement = await page.evaluate(() => {
+                    currentFocusedElement = await page.evaluate((htmlSnippetMaxLength) => {
                         const el = document.activeElement;
                         if (!el || el === document.body)
                             return null;
@@ -180,6 +184,17 @@ export async function runFocusIndicatorCheck(options) {
                             const index = siblings.indexOf(element) + 1;
                             return `${getSelector(parent)} > ${tag}:nth-of-type(${index})`;
                         };
+                        let html = '';
+                        try {
+                            html = el.outerHTML || '';
+                        }
+                        catch {
+                            html = '';
+                        }
+                        if (!html) {
+                            html = `<${el.tagName.toLowerCase()}>`;
+                        }
+                        const htmlTruncated = html.length > htmlSnippetMaxLength;
                         return {
                             tag: el.tagName,
                             role: el.getAttribute('role'),
@@ -187,8 +202,10 @@ export async function runFocusIndicatorCheck(options) {
                                 el.textContent?.slice(0, 30) ||
                                 '',
                             selector: getSelector(el),
+                            html: htmlTruncated ? html.slice(0, htmlSnippetMaxLength) : html,
+                            htmlTruncated,
                         };
-                    });
+                    }, HTML_SNIPPET_MAX_LENGTH);
                 }
                 catch {
                     // Page might have navigated, use lastFocusedElement as fallback
@@ -248,8 +265,7 @@ export async function runFocusIndicatorCheck(options) {
             console.warn('Elements without visible focus indicator:', elementsWithoutFocusStyle);
         }
         // Build result
-        const result = {
-            url: finalPage.url(),
+        const details = {
             totalFocusableElements: finalFocusHistory.length,
             elementsWithFocusStyle: finalFocusHistory.length - elementsWithoutFocusStyle.length,
             elementsWithoutFocusStyle: elementsWithoutFocusStyle.length,
@@ -257,6 +273,9 @@ export async function runFocusIndicatorCheck(options) {
                 tag: el.tag,
                 role: el.role,
                 name: el.name,
+                selector: el.selector,
+                html: el.html,
+                htmlTruncated: el.htmlTruncated,
             })),
             onFocusViolations,
             focusObscuredIssues,
@@ -265,12 +284,18 @@ export async function runFocusIndicatorCheck(options) {
             interrupted: false,
             screenshotPath: screenshot ? resolvedScreenshotPath : '',
         };
+        const result = buildAuditResult({
+            source: 'focus-indicator-check',
+            url: finalPage.url(),
+            details,
+            buckets: normalizeFocusCheck(details),
+        });
         // Output results
-        logAuditHeader('Focus Indicator Check Results', 'WCAG 2.4.7 / 2.4.12 / 3.2.1', result.url);
-        console.log(`Total focusable elements: ${result.totalFocusableElements}`);
-        console.log(`Elements with focus style: ${result.elementsWithFocusStyle}`);
-        console.log(`Elements WITHOUT focus style: ${result.elementsWithoutFocusStyle}`);
-        console.log(`Elements with OBSCURED focus: ${result.elementsWithObscuredFocus}`);
+        logAuditHeader('Focus Indicator Check Results', 'WCAG 2.4.7 / 2.4.11 / 3.2.1', result.url);
+        console.log(`Total focusable elements: ${details.totalFocusableElements}`);
+        console.log(`Elements with focus style: ${details.elementsWithFocusStyle}`);
+        console.log(`Elements WITHOUT focus style: ${details.elementsWithoutFocusStyle}`);
+        console.log(`Elements with OBSCURED focus: ${details.elementsWithObscuredFocus}`);
         if (retryCount > 0) {
             console.log(`\nTest restarted ${retryCount} time(s) due to navigation violations`);
         }
@@ -328,7 +353,23 @@ export async function runFocusIndicatorCheck(options) {
 // Browser-injected script factory
 // =============================================================================
 function createFocusTrackerScript(args) {
-    const { focusableSelector, styleProperties, warningStyles, skipSelectors, obscuredConfig } = args;
+    const { focusableSelector, styleProperties, warningStyles, skipSelectors, htmlSnippetMaxLength, obscuredConfig, } = args;
+    const getHtmlSnippet = (el) => {
+        let html = '';
+        try {
+            html = el.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return { html: `<${el.tagName.toLowerCase()}>`, htmlTruncated: false };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    };
     // Add warning styles
     const styleSheet = new CSSStyleSheet();
     document.adoptedStyleSheets = [...document.adoptedStyleSheets, styleSheet];
@@ -658,6 +699,7 @@ function createFocusTrackerScript(args) {
                         focusedEl.textContent?.slice(0, 30) ||
                         '',
                     selector: getSelector(focusedEl),
+                    ...getHtmlSnippet(focusedEl),
                 },
                 elementRect: {
                     left: focusedRect.left,
@@ -729,10 +771,11 @@ function createFocusTrackerScript(args) {
             id,
             tag: el.tagName,
             role: el.getAttribute('role'),
-            name: el.getAttribute('aria-label') || el.textContent?.slice(0, 30),
+            name: el.getAttribute('aria-label') || el.textContent?.slice(0, 30) || '',
             hasFocusStyle,
             diff,
             selector: elementSelectors.get(el) || getSelector(el),
+            ...getHtmlSnippet(el),
         });
         // Check for WCAG 2.4.12 - focus obscured by fixed/sticky elements
         checkFocusObscured(el);