@a11y-skills/audit 0.2.0 → 0.3.0

package/dist/types.d.ts

@@ -1,50 +1,117 @@
 /**
  * Type definitions for the WCAG audit checks shipped in @a11y-skills/audit.
+ *
+ * Every check returns the same axe-style envelope (`AuditCheckResult`):
+ * findings are normalized into `violations` / `incomplete` / `passes` /
+ * `inapplicable` rule arrays, while the check-specific evidence (measurements,
+ * screenshots, raw element records) lives under `details`.
+ *
+ * Classification policy: a finding is only a `violation` when the detection
+ * has no known blind spots and no WCAG exception could apply. Everything else
+ * (most heuristic detections) lands in `incomplete` — the manual-review queue.
  */
 import type { AUDIT_DISCLAIMER } from './constants.js';
-export interface AxeViolationNode {
-    html: string;
+/** Identifier of the check that produced a result. */
+export type CheckSource = 'axe-audit' | 'focus-indicator-check' | 'reflow-check' | 'target-size-check' | 'text-spacing-check' | 'zoom-200-check' | 'orientation-check' | 'autocomplete-audit' | 'time-limit-detector' | 'auto-play-detection';
+export type NormalizedImpact = 'critical' | 'serious' | 'moderate' | 'minor';
+/** One affected element (or the page itself, `target: ['html']`). */
+export interface NormalizedNode {
+    /** CSS selector path. Page-level findings use `['html']`. */
     target: string[];
-    failureSummary: string | undefined;
-}
-export interface AxeViolation {
+    /**
+     * outerHTML snippet (possibly truncated). When the source element's HTML
+     * could not be captured, a short synthetic representation is generated from
+     * the tag/role/name instead — never an empty string.
+     */
+    html: string;
+    /** Whether `html` was truncated to the snippet length limit. */
+    htmlTruncated: boolean;
+    /** Human-readable description of why this node was flagged. */
+    failureSummary: string;
+}
+/** One rule's outcome, axe-style. */
+export interface NormalizedRuleResult {
+    /** Namespaced rule id, e.g. `a11y-skills/focus-visible` (axe rules keep their own ids). */
     id: string;
-    impact: string | null;
+    impact: NormalizedImpact | null;
     description: string;
     help: string;
+    /** W3C Understanding document (or axe docs for axe rules). */
     helpUrl: string;
+    /** axe-style tags: `a11y-skills`, `wcag2aa` / `wcag21aa` / `wcag22aa`, `wcag247`-style SC tags. */
     tags: string[];
-    nodes: AxeViolationNode[];
+    nodes: NormalizedNode[];
 }
-export interface AxeAuditResult {
+/** Rule-level counts derived from the four buckets (not from `details`). */
+export interface AuditResultSummary {
+    /** Number of rules in `violations`. */
+    violationCount: number;
+    /** Number of rules in `incomplete`. */
+    incompleteCount: number;
+    /** Number of rules in `passes`. */
+    passCount: number;
+    /** Number of elements the check examined, when the check can count them. */
+    checkedNodes?: number;
+}
+/** Common envelope returned (and saved as JSON) by every check. */
+export interface AuditCheckResult<TDetails> {
+    source: CheckSource;
     url: string;
     timestamp: string;
-    violations: AxeViolation[];
-    passes: number;
-    incomplete: number;
-    inapplicable: number;
-    violationCount: number;
+    /** Confirmed findings — detection has no blind spot and no exception can apply. */
+    violations: NormalizedRuleResult[];
+    /** Findings that need manual confirmation (heuristic detections, possible exceptions). */
+    incomplete: NormalizedRuleResult[];
+    /** Rules that ran and found nothing (nodes omitted). */
+    passes: NormalizedRuleResult[];
+    /** Rules that had nothing to examine on this page. */
+    inapplicable: NormalizedRuleResult[];
+    summary: AuditResultSummary;
+    /** Check-specific evidence; sufficient to re-derive the buckets above. */
+    details: TDetails;
     disclaimer: typeof AUDIT_DISCLAIMER;
 }
+/** Execution configuration; rule/node data is fully held in the envelope buckets. */
+export interface AxeAuditDetails {
+    /** axe-core tags the run was filtered by. */
+    tagsRun: string[];
+    /** Rule overrides forwarded to axe, if any. */
+    rulesOverride: Record<string, {
+        enabled: boolean;
+    }> | null;
+    /** Raw axe result counts (rule-level). */
+    violationRuleCount: number;
+    passRuleCount: number;
+    incompleteRuleCount: number;
+    inapplicableRuleCount: number;
+}
+export type AxeAuditResult = AuditCheckResult<AxeAuditDetails>;
 export interface FocusRecord {
     id: number;
     tag: string;
     role: string | null;
     name: string;
+    selector: string;
+    html: string;
+    htmlTruncated: boolean;
     hasFocusStyle: boolean;
     diff: Record<string, string>;
 }
+/** Reference to an element captured in the browser context. */
+export interface FocusElementRef {
+    tag: string;
+    role: string | null;
+    name: string;
+    selector: string;
+    html: string;
+    htmlTruncated: boolean;
+}
 /**
  * WCAG 3.2.1 On Focus violation - context change triggered by focus
  */
 export interface OnFocusViolation {
     /** Element that triggered the navigation */
-    element: {
-        tag: string;
-        role: string | null;
-        name: string;
-        selector: string;
-    };
+    element: FocusElementRef;
     /** URL before focus */
     fromUrl: string;
     /** URL after focus (navigation target) */
@@ -52,20 +119,15 @@ export interface OnFocusViolation {
     /** Type of context change */
     changeType: 'navigation' | 'new-window' | 'dialog';
 }
-export interface FocusCheckResult {
-    url: string;
+export interface FocusCheckDetails {
     totalFocusableElements: number;
     elementsWithFocusStyle: number;
     elementsWithoutFocusStyle: number;
-    /** WCAG 2.4.7 violations */
-    issues: Array<{
-        tag: string;
-        role: string | null;
-        name: string;
-    }>;
+    /** WCAG 2.4.7 findings (no computed-style change on focus) */
+    issues: FocusElementRef[];
     /** WCAG 3.2.1 violations - focus triggered context change */
     onFocusViolations: OnFocusViolation[];
-    /** WCAG 2.4.12 violations - focus obscured by fixed/sticky elements */
+    /** WCAG 2.4.11/2.4.12 findings - focus obscured by fixed/sticky elements */
     focusObscuredIssues: FocusObscuredIssue[];
     elementsWithObscuredFocus: number;
     allElements: FocusRecord[];
@@ -78,6 +140,7 @@ export interface FocusCheckResult {
      */
     screenshotPath: string;
 }
+export type FocusCheckResult = AuditCheckResult<FocusCheckDetails>;
 /**
  * Bounding rect for overlap calculations
  */
@@ -104,16 +167,11 @@ export interface FocusObscuredOverlap {
     overlapArea: number;
 }
 /**
- * WCAG 2.4.12 violation - focus indicator hidden by fixed/sticky content
+ * WCAG 2.4.11/2.4.12 finding - focus indicator hidden by fixed/sticky content
  */
 export interface FocusObscuredIssue {
     /** The focused element that is obscured */
-    element: {
-        tag: string;
-        role: string | null;
-        name: string;
-        selector: string;
-    };
+    element: FocusElementRef;
     /** Bounding rect of the focused element */
     elementRect: BoundingRect;
     /** List of overlapping fixed/sticky elements */
@@ -124,6 +182,8 @@ export interface FocusObscuredIssue {
 export interface ReflowIssue {
     selector: string;
     tagName: string;
+    html: string;
+    htmlTruncated: boolean;
     rect: {
         left: number;
         right: number;
@@ -135,6 +195,8 @@ export interface ReflowIssue {
 export interface ClippedTextElement {
     selector: string;
     tagName: string;
+    html: string;
+    htmlTruncated: boolean;
     scrollWidth: number;
     clientWidth: number;
     scrollHeight: number;
@@ -142,8 +204,7 @@ export interface ClippedTextElement {
     overflow: string;
     overflowX: string;
 }
-export interface ReflowCheckResult {
-    url: string;
+export interface ReflowCheckDetails {
     viewport: {
         width: number;
         height: number;
@@ -154,6 +215,7 @@ export interface ReflowCheckResult {
     overflowingElements: ReflowIssue[];
     clippedTextElements: ClippedTextElement[];
 }
+export type ReflowCheckResult = AuditCheckResult<ReflowCheckDetails>;
 /**
  * Exception types for WCAG 2.5.8 Target Size (Minimum)
  * - inline: Target is in a sentence or text block
@@ -163,11 +225,22 @@ export interface ReflowCheckResult {
  * - essential-review: May be essential exception but requires manual review
  */
 export type TargetSizeException = 'inline' | 'redundant' | 'ua-control' | 'spacing' | 'essential-review';
+/**
+ * How thoroughly the SC 2.5.8 exceptions were assessed for a target.
+ * - ruled-out: every exception was checked and none applies — the finding is a
+ *   confirmed violation
+ * - possible: a heuristic matched an exception; needs manual confirmation
+ * - not-assessed: the heuristics found no exception, but they cannot rule out
+ *   the essential exception — needs manual confirmation
+ */
+export type TargetSizeExceptionAssessment = 'ruled-out' | 'possible' | 'not-assessed';
 export interface TargetSizeIssue {
     /** CSS selector for the element */
     selector: string;
     /** HTML tag name */
     tagName: string;
+    html: string;
+    htmlTruncated: boolean;
     /** ARIA role if present */
     role: string | null;
     /** Computed accessible name */
@@ -184,6 +257,8 @@ export interface TargetSizeIssue {
     exception: TargetSizeException | null;
     /** Human-readable exception details */
     exceptionDetails: string | null;
+    /** Exception-coverage of the assessment (drives violation vs incomplete) */
+    exceptionAssessment: TargetSizeExceptionAssessment;
     /** Link href for redundancy check */
     href: string | null;
 }
@@ -197,9 +272,7 @@ export interface TargetSizeSummary {
     /** Number of targets with possible exceptions */
     exceptedCount: number;
 }
-export interface TargetSizeCheckResult {
-    /** Page URL */
-    url: string;
+export interface TargetSizeCheckDetails {
     /** Total interactive elements checked */
     totalTargetsChecked: number;
     /** Elements failing AA threshold (< 24px) */
@@ -210,12 +283,15 @@ export interface TargetSizeCheckResult {
     passedTargets: number;
     /** Elements with possible exceptions */
     exceptedTargets: TargetSizeIssue[];
-    /** Summary counts */
+    /** Per-target counts */
     summary: TargetSizeSummary;
 }
+export type TargetSizeCheckResult = AuditCheckResult<TargetSizeCheckDetails>;
 export interface TextSpacingIssue {
     selector: string;
     tagName: string;
+    html: string;
+    htmlTruncated: boolean;
     beforeMetrics: {
         scrollWidth: number;
         scrollHeight: number;
@@ -233,22 +309,23 @@ export interface TextSpacingIssue {
     overflowY: string;
     issueType: 'horizontal-clip' | 'vertical-clip' | 'both';
 }
-export interface TextSpacingCheckResult {
-    url: string;
+export interface TextSpacingCheckDetails {
     clippedElements: TextSpacingIssue[];
     totalElementsChecked: number;
 }
+export type TextSpacingCheckResult = AuditCheckResult<TextSpacingCheckDetails>;
 export interface ZoomIssue {
     selector: string;
     tagName: string;
+    html: string;
+    htmlTruncated: boolean;
     scrollWidth: number;
     clientWidth: number;
     scrollHeight: number;
     clientHeight: number;
     issueType: 'horizontal-scroll' | 'clipped-content';
 }
-export interface ZoomCheckResult {
-    url: string;
+export interface ZoomCheckDetails {
     zoomFactor: number;
     viewport: {
         width: number;
@@ -259,6 +336,7 @@ export interface ZoomCheckResult {
     documentClientWidth: number;
     clippedElements: ZoomIssue[];
 }
+export type ZoomCheckResult = AuditCheckResult<ZoomCheckDetails>;
 export interface OrientationState {
     lockMessageFound: boolean;
     lockMessageText: string | null;
@@ -267,16 +345,18 @@ export interface OrientationState {
     bodyHeight: number;
     visibleTextLength: number;
 }
-export interface OrientationCheckResult {
-    url: string;
+export interface OrientationCheckDetails {
     portrait: OrientationState;
     landscape: OrientationState;
     hasOrientationLock: boolean;
     lockDetectedIn: 'portrait' | 'landscape' | 'both' | 'none';
 }
+export type OrientationCheckResult = AuditCheckResult<OrientationCheckDetails>;
 export interface AutocompleteIssue {
     selector: string;
     tagName: string;
+    html: string;
+    htmlTruncated: boolean;
     inputType: string;
     name: string | null;
     id: string | null;
@@ -286,16 +366,18 @@ export interface AutocompleteIssue {
     matchedBy: 'name' | 'id' | 'label' | 'placeholder';
     issueType: 'missing' | 'invalid';
 }
-export interface AutocompleteAuditResult {
-    url: string;
+export interface AutocompleteAuditDetails {
     totalFieldsChecked: number;
     missingAutocomplete: AutocompleteIssue[];
     invalidAutocomplete: AutocompleteIssue[];
 }
+export type AutocompleteAuditResult = AuditCheckResult<AutocompleteAuditDetails>;
 export interface MetaRefreshInfo {
     content: string;
     seconds: number;
     url: string | null;
+    html: string;
+    htmlTruncated: boolean;
 }
 export interface TimerInfo {
     type: 'setTimeout' | 'setInterval';
@@ -306,14 +388,16 @@ export interface CountdownIndicator {
     selector: string;
     text: string;
     tagName: string;
+    html: string;
+    htmlTruncated: boolean;
 }
-export interface TimeLimitDetectorResult {
-    url: string;
+export interface TimeLimitDetectorDetails {
     metaRefresh: MetaRefreshInfo[];
     timers: TimerInfo[];
     countdownIndicators: CountdownIndicator[];
     hasTimeLimits: boolean;
 }
+export type TimeLimitDetectorResult = AuditCheckResult<TimeLimitDetectorDetails>;
 export interface ScreenshotRecord {
     time: string;
     path: string;
@@ -354,8 +438,7 @@ export interface PauseVerificationResult {
     pauseWorked: boolean | null;
     error: string | null;
 }
-export interface AutoPlayDetectionResult {
-    url: string;
+export interface AutoPlayDetectionDetails {
     screenshotRecords: ScreenshotRecord[];
     comparisons: ComparisonResult[];
     hasAutoPlayContent: boolean;
@@ -364,3 +447,4 @@ export interface AutoPlayDetectionResult {
     pauseVerification: PauseVerificationResult;
     recommendation: string;
 }
+export type AutoPlayDetectionResult = AuditCheckResult<AutoPlayDetectionDetails>;

package/dist/types.js

@@ -1,4 +1,13 @@
 /**
  * Type definitions for the WCAG audit checks shipped in @a11y-skills/audit.
+ *
+ * Every check returns the same axe-style envelope (`AuditCheckResult`):
+ * findings are normalized into `violations` / `incomplete` / `passes` /
+ * `inapplicable` rule arrays, while the check-specific evidence (measurements,
+ * screenshots, raw element records) lives under `details`.
+ *
+ * Classification policy: a finding is only a `violation` when the detection
+ * has no known blind spots and no WCAG exception could apply. Everything else
+ * (most heuristic detections) lands in `incomplete` — the manual-review queue.
  */
 export {};

package/dist/utils/axe-format.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Pure mappers from check-specific `details` to the axe-style buckets
+ * (`violations` / `incomplete` / `passes` / `inapplicable`), plus the envelope
+ * assembler and the opt-in cross-check merge.
+ *
+ * Everything here is browser-independent: the runners gather evidence into a
+ * details object, and these functions derive the normalized view from it.
+ * Because the details objects are part of the saved JSON, the buckets can be
+ * re-derived from a result file at any time.
+ */
+import type { AuditCheckResult, AuditResultSummary, AutocompleteAuditDetails, AutoPlayDetectionDetails, CheckSource, FocusCheckDetails, NormalizedRuleResult, OrientationCheckDetails, ReflowCheckDetails, TargetSizeCheckDetails, TextSpacingCheckDetails, TimeLimitDetectorDetails, ZoomCheckDetails } from '../types.js';
+import { AUDIT_DISCLAIMER } from '../constants.js';
+export interface NormalizedBuckets {
+    violations: NormalizedRuleResult[];
+    incomplete: NormalizedRuleResult[];
+    passes: NormalizedRuleResult[];
+    inapplicable: NormalizedRuleResult[];
+    /** Number of elements the check examined, when countable. */
+    checkedNodes?: number;
+}
+/** Assemble the common envelope from a check's details and buckets. */
+export declare function buildAuditResult<TDetails>(args: {
+    source: CheckSource;
+    url: string;
+    details: TDetails;
+    buckets: NormalizedBuckets;
+    timestamp?: string;
+}): AuditCheckResult<TDetails>;
+export declare function normalizeFocusCheck(details: FocusCheckDetails): NormalizedBuckets;
+export declare function normalizeReflowCheck(details: ReflowCheckDetails): NormalizedBuckets;
+export declare function normalizeTargetSizeCheck(details: TargetSizeCheckDetails): NormalizedBuckets;
+export declare function normalizeTextSpacingCheck(details: TextSpacingCheckDetails): NormalizedBuckets;
+export declare function normalizeZoomCheck(details: ZoomCheckDetails): NormalizedBuckets;
+export declare function normalizeOrientationCheck(details: OrientationCheckDetails): NormalizedBuckets;
+export declare function normalizeAutocompleteAudit(details: AutocompleteAuditDetails): NormalizedBuckets;
+export declare function normalizeTimeLimitDetector(details: TimeLimitDetectorDetails): NormalizedBuckets;
+export declare function normalizeAutoPlayDetection(details: AutoPlayDetectionDetails): NormalizedBuckets;
+/** Structural subset of an axe-core rule result (avoids a hard axe dependency). */
+export interface RawAxeRule {
+    id: string;
+    impact?: string | null;
+    description: string;
+    help: string;
+    helpUrl: string;
+    tags: string[];
+    nodes: Array<{
+        html: string;
+        target: unknown[];
+        failureSummary?: string | undefined;
+    }>;
+}
+export interface RawAxeResults {
+    violations: RawAxeRule[];
+    incomplete: RawAxeRule[];
+    passes: RawAxeRule[];
+    inapplicable: RawAxeRule[];
+}
+/**
+ * Normalize raw axe-core results into the common buckets. Must be fed the RAW
+ * `AxeResults` (before any reduction) — pass/incomplete details are not
+ * recoverable afterwards. Node lists are kept for violations and incomplete;
+ * passes/inapplicable carry rule metadata only.
+ */
+export declare function normalizeAxeResults(raw: RawAxeResults): NormalizedBuckets;
+/** Combined view over several checks of the SAME page. */
+export interface MergedAuditResult {
+    url: string;
+    /** Latest timestamp among the merged results. */
+    timestamp: string;
+    sources: CheckSource[];
+    violations: NormalizedRuleResult[];
+    incomplete: NormalizedRuleResult[];
+    passes: NormalizedRuleResult[];
+    inapplicable: NormalizedRuleResult[];
+    summary: AuditResultSummary;
+    disclaimer: typeof AUDIT_DISCLAIMER;
+}
+/**
+ * Merge several check results for the same URL into one normalized view.
+ *
+ * - Results with differing URLs are rejected (throws).
+ * - The same rule id is merged into one entry; nodes are deduplicated by
+ *   `target` + `failureSummary`. Identical selectors inside different frames
+ *   or shadow roots are NOT distinguished.
+ * - A rule appearing in several buckets is placed in the highest-priority one:
+ *   violations > incomplete > passes > inapplicable.
+ */
+export declare function mergeNormalizedResults(results: Array<AuditCheckResult<unknown>>): MergedAuditResult;