@hypoth-ui/a11y-audit 0.1.0

package/dist/chunk-KLSGW6PX.js

@@ -0,0 +1,515 @@
+// src/lib/validator.ts
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+
+// src/schemas/audit-checklist.schema.json
+var audit_checklist_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://ds.hypoth.dev/schemas/audit-checklist.schema.json",
+  title: "AuditChecklist",
+  description: "Template defining manual accessibility tests for a component category",
+  type: "object",
+  required: ["id", "name", "description", "wcagVersion", "conformanceLevel", "items", "version"],
+  properties: {
+    id: {
+      type: "string",
+      pattern: "^[a-z][a-z0-9-]*$",
+      description: "Unique identifier (e.g., 'form-controls')"
+    },
+    name: {
+      type: "string",
+      minLength: 1,
+      description: "Human-readable name"
+    },
+    description: {
+      type: "string",
+      minLength: 1,
+      description: "Purpose of this checklist"
+    },
+    wcagVersion: {
+      type: "string",
+      enum: ["2.0", "2.1", "2.2"],
+      description: "WCAG version"
+    },
+    conformanceLevel: {
+      type: "string",
+      enum: ["A", "AA", "AAA"],
+      description: "Target conformance level"
+    },
+    version: {
+      type: "string",
+      pattern: "^\\d+\\.\\d+\\.\\d+$",
+      description: "Checklist template version (semver)"
+    },
+    items: {
+      type: "array",
+      minItems: 1,
+      items: {
+        $ref: "#/$defs/ChecklistItem"
+      },
+      description: "Array of test items"
+    }
+  },
+  $defs: {
+    ChecklistItem: {
+      type: "object",
+      required: ["id", "criterion", "description", "procedure", "expectedOutcome"],
+      properties: {
+        id: {
+          type: "string",
+          pattern: "^[a-z]{2,3}-\\d{3}$",
+          description: "Unique item ID (e.g., 'fc-001')"
+        },
+        criterion: {
+          type: "string",
+          pattern: "^\\d+\\.\\d+\\.\\d+$",
+          description: "WCAG success criterion (e.g., '1.3.1')"
+        },
+        description: {
+          type: "string",
+          minLength: 1,
+          description: "What to test"
+        },
+        procedure: {
+          type: "string",
+          minLength: 1,
+          description: "How to test"
+        },
+        expectedOutcome: {
+          type: "string",
+          minLength: 1,
+          description: "What passing looks like"
+        },
+        tools: {
+          type: "array",
+          items: { type: "string" },
+          description: "Recommended testing tools"
+        },
+        screenReaders: {
+          type: "array",
+          items: { type: "string" },
+          description: "Screen readers to test with"
+        }
+      }
+    }
+  }
+};
+
+// src/schemas/audit-record.schema.json
+var audit_record_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://ds.hypoth.dev/schemas/audit-record.schema.json",
+  title: "AuditRecord",
+  description: "Completed manual accessibility audit for a specific component version",
+  type: "object",
+  required: [
+    "id",
+    "component",
+    "version",
+    "checklistId",
+    "checklistVersion",
+    "auditor",
+    "auditDate",
+    "items",
+    "overallStatus"
+  ],
+  properties: {
+    id: {
+      type: "string",
+      format: "uuid",
+      description: "Auto-generated UUID"
+    },
+    component: {
+      type: "string",
+      pattern: "^ds-[a-z][a-z0-9-]*$",
+      description: "Component ID (e.g., 'ds-button')"
+    },
+    version: {
+      type: "string",
+      pattern: "^\\d+\\.\\d+\\.\\d+$",
+      description: "Component version audited"
+    },
+    checklistId: {
+      type: "string",
+      description: "Reference to checklist template"
+    },
+    checklistVersion: {
+      type: "string",
+      pattern: "^\\d+\\.\\d+\\.\\d+$",
+      description: "Version of checklist used"
+    },
+    auditor: {
+      type: "string",
+      format: "email",
+      description: "Auditor email/identifier"
+    },
+    auditDate: {
+      type: "string",
+      format: "date-time",
+      description: "Timestamp of audit completion (ISO8601)"
+    },
+    items: {
+      type: "array",
+      minItems: 1,
+      items: {
+        $ref: "#/$defs/AuditItem"
+      },
+      description: "Completed audit items"
+    },
+    overallStatus: {
+      type: "string",
+      enum: ["conformant", "partial", "non-conformant"],
+      description: "Overall conformance status"
+    },
+    notes: {
+      type: "string",
+      description: "General audit notes"
+    },
+    exceptions: {
+      type: "array",
+      items: {
+        $ref: "#/$defs/Exception"
+      },
+      description: "Documented accessibility exceptions"
+    }
+  },
+  $defs: {
+    AuditItem: {
+      type: "object",
+      required: ["itemId", "status"],
+      properties: {
+        itemId: {
+          type: "string",
+          description: "Reference to ChecklistItem.id"
+        },
+        status: {
+          type: "string",
+          enum: ["pass", "fail", "na", "blocked"],
+          description: "Test result status"
+        },
+        notes: {
+          type: "string",
+          description: "Auditor notes"
+        },
+        evidence: {
+          type: "string",
+          description: "Screenshot/recording reference"
+        }
+      }
+    },
+    Exception: {
+      type: "object",
+      required: ["criterion", "rationale"],
+      properties: {
+        criterion: {
+          type: "string",
+          pattern: "^\\d+\\.\\d+\\.\\d+$",
+          description: "WCAG criterion with exception"
+        },
+        rationale: {
+          type: "string",
+          minLength: 10,
+          description: "Why exception is acceptable"
+        },
+        workaround: {
+          type: "string",
+          description: "Alternative approach for users"
+        },
+        plannedFix: {
+          type: "string",
+          description: "Roadmap reference if temporary"
+        }
+      }
+    }
+  }
+};
+
+// src/schemas/conformance-report.schema.json
+var conformance_report_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://ds.hypoth.dev/schemas/conformance-report.schema.json",
+  title: "ConformanceReport",
+  description: "Release-level accessibility conformance summary",
+  type: "object",
+  required: [
+    "id",
+    "version",
+    "generatedAt",
+    "generatedBy",
+    "wcagVersion",
+    "conformanceLevel",
+    "components",
+    "summary",
+    "metadata"
+  ],
+  properties: {
+    id: {
+      type: "string",
+      format: "uuid",
+      description: "Report identifier"
+    },
+    version: {
+      type: "string",
+      pattern: "^\\d+\\.\\d+\\.\\d+$",
+      description: "Release version"
+    },
+    generatedAt: {
+      type: "string",
+      format: "date-time",
+      description: "Report generation timestamp (ISO8601)"
+    },
+    generatedBy: {
+      type: "string",
+      description: "Generator (CI job ID or user)"
+    },
+    wcagVersion: {
+      type: "string",
+      enum: ["2.0", "2.1", "2.2"],
+      description: "Target WCAG version"
+    },
+    conformanceLevel: {
+      type: "string",
+      enum: ["A", "AA", "AAA"],
+      description: "Target conformance level"
+    },
+    components: {
+      type: "array",
+      items: {
+        $ref: "#/$defs/ComponentStatus"
+      },
+      description: "Per-component conformance status"
+    },
+    summary: {
+      $ref: "#/$defs/ConformanceSummary",
+      description: "Aggregate statistics"
+    },
+    metadata: {
+      $ref: "#/$defs/ReportMetadata",
+      description: "Report metadata"
+    }
+  },
+  $defs: {
+    ComponentStatus: {
+      type: "object",
+      required: ["component", "version", "status", "automatedResult", "lastUpdated"],
+      properties: {
+        component: {
+          type: "string",
+          description: "Component ID"
+        },
+        version: {
+          type: "string",
+          pattern: "^\\d+\\.\\d+\\.\\d+$",
+          description: "Component version"
+        },
+        status: {
+          type: "string",
+          enum: ["conformant", "partial", "non-conformant", "pending"],
+          description: "Overall conformance status"
+        },
+        automatedResult: {
+          $ref: "#/$defs/AutomatedSummary",
+          description: "CI test summary"
+        },
+        manualAudit: {
+          $ref: "#/$defs/ManualAuditSummary",
+          description: "Manual audit summary (optional if pending)"
+        },
+        lastUpdated: {
+          type: "string",
+          format: "date-time",
+          description: "Most recent audit date"
+        }
+      }
+    },
+    AutomatedSummary: {
+      type: "object",
+      required: ["passed", "violationCount", "runId"],
+      properties: {
+        passed: {
+          type: "boolean",
+          description: "Whether automated tests passed"
+        },
+        violationCount: {
+          type: "integer",
+          minimum: 0,
+          description: "Number of violations detected"
+        },
+        criticalCount: {
+          type: "integer",
+          minimum: 0,
+          description: "Critical severity violations"
+        },
+        seriousCount: {
+          type: "integer",
+          minimum: 0,
+          description: "Serious severity violations"
+        },
+        runId: {
+          type: "string",
+          description: "CI run identifier"
+        },
+        runDate: {
+          type: "string",
+          format: "date-time",
+          description: "CI run timestamp"
+        }
+      }
+    },
+    ManualAuditSummary: {
+      type: "object",
+      required: ["status", "auditId", "auditor", "auditDate"],
+      properties: {
+        status: {
+          type: "string",
+          enum: ["conformant", "partial", "non-conformant"],
+          description: "Manual audit status"
+        },
+        auditId: {
+          type: "string",
+          format: "uuid",
+          description: "Reference to full audit record"
+        },
+        auditor: {
+          type: "string",
+          description: "Auditor identifier"
+        },
+        auditDate: {
+          type: "string",
+          format: "date-time",
+          description: "Audit completion date"
+        },
+        passCount: {
+          type: "integer",
+          minimum: 0,
+          description: "Passing items"
+        },
+        failCount: {
+          type: "integer",
+          minimum: 0,
+          description: "Failing items"
+        },
+        exceptionCount: {
+          type: "integer",
+          minimum: 0,
+          description: "Documented exceptions"
+        }
+      }
+    },
+    ConformanceSummary: {
+      type: "object",
+      required: [
+        "totalComponents",
+        "conformant",
+        "partial",
+        "nonConformant",
+        "pending",
+        "conformancePercentage"
+      ],
+      properties: {
+        totalComponents: {
+          type: "integer",
+          minimum: 0,
+          description: "Total component count"
+        },
+        conformant: {
+          type: "integer",
+          minimum: 0,
+          description: "Fully conformant count"
+        },
+        partial: {
+          type: "integer",
+          minimum: 0,
+          description: "Partially conformant count"
+        },
+        nonConformant: {
+          type: "integer",
+          minimum: 0,
+          description: "Non-conformant count"
+        },
+        pending: {
+          type: "integer",
+          minimum: 0,
+          description: "Awaiting audit count"
+        },
+        conformancePercentage: {
+          type: "number",
+          minimum: 0,
+          maximum: 100,
+          description: "Percentage of conformant components"
+        }
+      }
+    },
+    ReportMetadata: {
+      type: "object",
+      required: ["schemaVersion", "toolVersion"],
+      properties: {
+        schemaVersion: {
+          type: "string",
+          pattern: "^\\d+\\.\\d+\\.\\d+$",
+          description: "Schema version used"
+        },
+        toolVersion: {
+          type: "string",
+          pattern: "^\\d+\\.\\d+\\.\\d+$",
+          description: "@hypoth-ui/a11y-audit version"
+        },
+        axeCoreVersion: {
+          type: "string",
+          description: "axe-core version used"
+        },
+        gitCommit: {
+          type: "string",
+          pattern: "^[a-f0-9]{40}$",
+          description: "Git SHA at report generation"
+        },
+        ciRunUrl: {
+          type: "string",
+          format: "uri",
+          description: "Link to CI run"
+        }
+      }
+    }
+  }
+};
+
+// src/lib/validator.ts
+var ajv = new Ajv({ allErrors: true, strict: true });
+addFormats(ajv);
+var validateAuditChecklist = ajv.compile(audit_checklist_schema_default);
+var validateAuditRecord = ajv.compile(audit_record_schema_default);
+var validateConformanceReport = ajv.compile(conformance_report_schema_default);
+function formatErrors(errors) {
+  if (!errors) return [];
+  return errors.map((err) => {
+    const path = err.instancePath || "/";
+    return `${path}: ${err.message}`;
+  });
+}
+function validateChecklist(data) {
+  const valid = validateAuditChecklist(data);
+  return {
+    valid,
+    errors: formatErrors(validateAuditChecklist.errors)
+  };
+}
+function validateRecord(data) {
+  const valid = validateAuditRecord(data);
+  return {
+    valid,
+    errors: formatErrors(validateAuditRecord.errors)
+  };
+}
+function validateReport(data) {
+  const valid = validateConformanceReport(data);
+  return {
+    valid,
+    errors: formatErrors(validateConformanceReport.errors)
+  };
+}
+
+export {
+  validateChecklist,
+  validateRecord,
+  validateReport
+};

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import {
+  describeSeverityThreshold,
+  parseSeverityThreshold
+} from "../chunk-AMA6KCPL.js";
+
+// src/cli/index.ts
+import { Command } from "commander";
+var program = new Command();
+program.name("a11y-audit").description(
+  "Accessibility audit tooling for automated checks, manual checklists, and conformance reporting"
+).version("0.0.0");
+program.command("audit").description("Start a manual accessibility audit for a component").requiredOption("-c, --component <id>", "Component ID (e.g., ds-button)").requiredOption(
+  "--category <category>",
+  "Component category (form-controls, overlays, navigation, data-display, feedback)"
+).option("-v, --version <version>", "Component version (default: current)").action(async (options) => {
+  const { audit } = await import("../audit-Q3UXBYIW.js");
+  await audit(options);
+});
+program.command("validate").description("Validate audit records and checklist templates").option("-p, --path <path>", "Path to audit records directory", "a11y-audits/records").option("--strict", "Fail on any validation warning").action(async (options) => {
+  const { validate } = await import("../validate-MQQMU57I.js");
+  await validate(options);
+});
+program.command("report").description("Generate a conformance report for a release").requiredOption("-v, --version <version>", "Release version (e.g., 1.0.0)").option("-o, --output <dir>", "Output directory", "a11y-audits/reports").option("--format <formats>", "Output formats (json,html)", "json,html").action(async (options) => {
+  const { report } = await import("../report-6GBLBDLV.js");
+  await report(options);
+});
+program.command("check").description("Run automated accessibility checks (used by CI)").option(
+  "-s, --severity <levels>",
+  'Severity threshold (critical,serious,moderate,minor or "all")'
+).option("--json", "Output results as JSON").action(async (options) => {
+  const threshold = parseSeverityThreshold(options.severity);
+  console.info(`Running a11y checks, failing on ${describeSeverityThreshold(threshold)}`);
+  console.info("Automated check command - implementation pending");
+});
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+/**
+ * TypeScript types derived from JSON schemas
+ * @see ../schemas/audit-checklist.schema.json
+ * @see ../schemas/audit-record.schema.json
+ * @see ../schemas/conformance-report.schema.json
+ */
+interface ChecklistItem {
+    id: string;
+    criterion: string;
+    description: string;
+    procedure: string;
+    expectedOutcome: string;
+    tools?: string[];
+    screenReaders?: string[];
+}
+interface AuditChecklist {
+    id: string;
+    name: string;
+    description: string;
+    wcagVersion: "2.0" | "2.1" | "2.2";
+    conformanceLevel: "A" | "AA" | "AAA";
+    version: string;
+    items: ChecklistItem[];
+}
+type AuditItemStatus = "pass" | "fail" | "na" | "blocked";
+interface AuditItem {
+    itemId: string;
+    status: AuditItemStatus;
+    notes?: string;
+    evidence?: string;
+}
+interface Exception {
+    criterion: string;
+    rationale: string;
+    workaround?: string;
+    plannedFix?: string;
+}
+type OverallStatus = "conformant" | "partial" | "non-conformant";
+interface AuditRecord {
+    id: string;
+    component: string;
+    version: string;
+    checklistId: string;
+    checklistVersion: string;
+    auditor: string;
+    auditDate: string;
+    items: AuditItem[];
+    overallStatus: OverallStatus;
+    notes?: string;
+    exceptions?: Exception[];
+}
+interface AutomatedSummary {
+    passed: boolean;
+    violationCount: number;
+    criticalCount?: number;
+    seriousCount?: number;
+    runId: string;
+    runDate?: string;
+}
+interface ManualAuditSummary {
+    status: OverallStatus;
+    auditId: string;
+    auditor: string;
+    auditDate: string;
+    passCount?: number;
+    failCount?: number;
+    exceptionCount?: number;
+}
+type ComponentConformanceStatus = "conformant" | "partial" | "non-conformant" | "pending";
+interface ComponentStatus {
+    component: string;
+    version: string;
+    status: ComponentConformanceStatus;
+    automatedResult: AutomatedSummary;
+    manualAudit?: ManualAuditSummary;
+    lastUpdated: string;
+}
+interface ConformanceSummary {
+    totalComponents: number;
+    conformant: number;
+    partial: number;
+    nonConformant: number;
+    pending: number;
+    conformancePercentage: number;
+}
+interface ReportMetadata {
+    schemaVersion: string;
+    toolVersion: string;
+    axeCoreVersion?: string;
+    gitCommit?: string;
+    ciRunUrl?: string;
+}
+interface ConformanceReport {
+    id: string;
+    version: string;
+    generatedAt: string;
+    generatedBy: string;
+    wcagVersion: "2.0" | "2.1" | "2.2";
+    conformanceLevel: "A" | "AA" | "AAA";
+    components: ComponentStatus[];
+    summary: ConformanceSummary;
+    metadata: ReportMetadata;
+}
+type ViolationSeverity = "critical" | "serious" | "moderate" | "minor";
+interface SeverityThreshold {
+    failOn: ViolationSeverity[];
+}
+
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+declare function validateChecklist(data: unknown): ValidationResult;
+declare function validateRecord(data: unknown): ValidationResult;
+declare function validateReport(data: unknown): ValidationResult;
+
+/**
+ * Default severity threshold: fail on Critical + Serious violations
+ * This matches axe-core's default behavior and WCAG compliance requirements
+ */
+declare const DEFAULT_SEVERITY_THRESHOLD: SeverityThreshold;
+/**
+ * All available severity levels in order of importance
+ */
+declare const SEVERITY_LEVELS: ViolationSeverity[];
+/**
+ * Environment variable name for severity threshold override
+ */
+declare const SEVERITY_ENV_VAR = "A11Y_SEVERITY";
+/**
+ * Parse severity threshold from CLI flag or environment variable
+ *
+ * Accepts comma-separated severity levels:
+ * - "critical" - fail only on critical
+ * - "critical,serious" - fail on critical or serious (default)
+ * - "critical,serious,moderate" - fail on critical, serious, or moderate
+ * - "all" - fail on any violation
+ *
+ * @param value - CLI flag value or undefined to check env var
+ * @returns Parsed severity threshold
+ */
+declare function parseSeverityThreshold(value?: string): SeverityThreshold;
+/**
+ * Check if a violation severity should cause a failure
+ *
+ * @param severity - The violation severity to check
+ * @param threshold - The threshold configuration
+ * @returns true if this severity should cause a failure
+ */
+declare function shouldFailOnSeverity(severity: ViolationSeverity, threshold?: SeverityThreshold): boolean;
+/**
+ * Get human-readable description of the severity threshold
+ */
+declare function describeSeverityThreshold(threshold: SeverityThreshold): string;
+
+export { type AuditChecklist, type AuditItem, type AuditItemStatus, type AuditRecord, type AutomatedSummary, type ChecklistItem, type ComponentConformanceStatus, type ComponentStatus, type ConformanceReport, type ConformanceSummary, DEFAULT_SEVERITY_THRESHOLD, type Exception, type ManualAuditSummary, type OverallStatus, type ReportMetadata, SEVERITY_ENV_VAR, SEVERITY_LEVELS, type SeverityThreshold, type ValidationResult, type ViolationSeverity, describeSeverityThreshold, parseSeverityThreshold, shouldFailOnSeverity, validateChecklist, validateRecord, validateReport };