@hypoth-ui/a11y-audit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hypoth-org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# @hypoth-ui/a11y-audit
+
+![Alpha](https://img.shields.io/badge/status-alpha-orange)
+
+Accessibility audit and conformance reporting tools for the hypoth-ui design system. Provides automated CI checks, manual audit checklists, and WCAG conformance report generation.
+
+## Installation
+
+```bash
+npm install @hypoth-ui/a11y-audit
+```
+
+## Usage
+
+### Run Automated Accessibility Tests
+
+```bash
+pnpm test:a11y
+```
+
+### Start a Manual Audit
+
+```bash
+pnpm a11y:audit -- --component ds-button --category form-controls
+```
+
+Available categories: `form-controls`, `overlays`, `navigation`, `data-display`, `feedback`.
+
+### Generate a Conformance Report
+
+```bash
+pnpm a11y:report -- --version 1.0.0
+```
+
+### Validate Audit Records
+
+```bash
+pnpm a11y:validate
+```
+
+## Documentation
+
+See the [main README](../../README.md) for full documentation and architecture overview.
+
+## License
+
+MIT

package/dist/audit-Q3UXBYIW.js

@@ -0,0 +1,266 @@
+import {
+  validateRecord
+} from "./chunk-KLSGW6PX.js";
+
+// src/cli/audit.ts
+import * as os from "os";
+import * as path3 from "path";
+
+// src/lib/artifact.ts
+import { randomUUID } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+function calculateOverallStatus(items) {
+  const hasBlocked = items.some((i) => i.status === "blocked");
+  const hasFail = items.some((i) => i.status === "fail");
+  const allPass = items.every((i) => i.status === "pass" || i.status === "na");
+  if (hasBlocked) {
+    return "partial";
+  }
+  if (hasFail) {
+    const failCount = items.filter((i) => i.status === "fail").length;
+    const passCount = items.filter((i) => i.status === "pass").length;
+    if (failCount > passCount) {
+      return "non-conformant";
+    }
+    return "partial";
+  }
+  if (allPass) {
+    return "conformant";
+  }
+  return "partial";
+}
+function validateCompleteness(checklist, items) {
+  const completedIds = new Set(items.map((i) => i.itemId));
+  const missing = checklist.items.filter((item) => !completedIds.has(item.id)).map((item) => item.id);
+  return {
+    complete: missing.length === 0,
+    missing
+  };
+}
+function generateArtifact(options) {
+  const completeness = validateCompleteness(options.checklist, options.items);
+  if (!completeness.complete) {
+    throw new Error(`Incomplete audit: missing items ${completeness.missing.join(", ")}`);
+  }
+  const record = {
+    id: randomUUID(),
+    component: options.component,
+    version: options.version,
+    checklistId: options.checklist.id,
+    checklistVersion: options.checklist.version,
+    auditor: options.auditor,
+    auditDate: (/* @__PURE__ */ new Date()).toISOString(),
+    items: options.items,
+    overallStatus: calculateOverallStatus(options.items),
+    notes: options.notes
+  };
+  const validation = validateRecord(record);
+  if (!validation.valid) {
+    throw new Error(`Invalid audit record: ${validation.errors.join(", ")}`);
+  }
+  return record;
+}
+function saveArtifact(record, outputDir) {
+  const componentDir = path.join(outputDir, record.component);
+  if (!fs.existsSync(componentDir)) {
+    fs.mkdirSync(componentDir, { recursive: true });
+  }
+  const filename = `${record.version}.json`;
+  const filepath = path.join(componentDir, filename);
+  if (fs.existsSync(filepath)) {
+    const backupPath = filepath.replace(".json", `.backup-${Date.now()}.json`);
+    fs.renameSync(filepath, backupPath);
+    console.info(`Existing record backed up to: ${backupPath}`);
+  }
+  fs.writeFileSync(filepath, JSON.stringify(record, null, 2));
+  return filepath;
+}
+
+// src/lib/checklist-runner.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import * as readline from "readline";
+function loadChecklist(category, templatesDir) {
+  const templatePath = path2.join(templatesDir, `${category}.json`);
+  if (!fs2.existsSync(templatePath)) {
+    throw new Error(`Checklist template not found: ${category}`);
+  }
+  const content = fs2.readFileSync(templatePath, "utf-8");
+  return JSON.parse(content);
+}
+function getAvailableCategories(templatesDir) {
+  if (!fs2.existsSync(templatesDir)) {
+    return [];
+  }
+  return fs2.readdirSync(templatesDir).filter((f) => f.endsWith(".json")).map((f) => f.replace(".json", ""));
+}
+function createSession(options) {
+  const checklist = loadChecklist(options.category, options.templatesDir);
+  return {
+    checklist,
+    component: options.component,
+    version: options.version ?? "0.0.0",
+    items: [],
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function parseStatus(input) {
+  const normalized = input.toLowerCase().trim();
+  switch (normalized) {
+    case "p":
+    case "pass":
+      return "pass";
+    case "f":
+    case "fail":
+      return "fail";
+    case "n":
+    case "na":
+    case "n/a":
+      return "na";
+    case "b":
+    case "blocked":
+      return "blocked";
+    case "s":
+    case "skip":
+      return "skip";
+    default:
+      return null;
+  }
+}
+async function runInteractiveSession(session) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  const question = (prompt) => new Promise((resolve2) => rl.question(prompt, resolve2));
+  const results = [];
+  for (const item of session.checklist.items) {
+    let status = null;
+    while (!status) {
+      const input = await question("Enter status: ");
+      const parsed = parseStatus(input);
+      if (parsed === "skip") {
+        break;
+      }
+      if (parsed === null) {
+        continue;
+      }
+      status = parsed;
+    }
+    if (status) {
+      let notes = "";
+      if (status === "fail" || status === "blocked") {
+        notes = await question("Enter notes (required for fail/blocked): ");
+        while (!notes.trim()) {
+          notes = await question("Notes are required. Please enter notes: ");
+        }
+      } else {
+        const notesInput = await question("Enter notes (optional, press Enter to skip): ");
+        notes = notesInput.trim();
+      }
+      results.push({
+        itemId: item.id,
+        status,
+        notes: notes || void 0
+      });
+    }
+  }
+  rl.close();
+  return results;
+}
+
+// src/cli/audit.ts
+var VALID_CATEGORIES = ["form-controls", "overlays", "navigation", "data-display", "feedback"];
+async function audit(options) {
+  const { component, category, version = "0.0.0" } = options;
+  if (!component.match(/^ds-[a-z][a-z0-9-]*$/)) {
+    console.error(`\u274C Invalid component ID: ${component}`);
+    console.error("   Component ID must match pattern: ds-<name> (e.g., ds-button)");
+    process.exit(1);
+  }
+  if (!VALID_CATEGORIES.includes(category)) {
+    console.error(`\u274C Invalid category: ${category}`);
+    console.error(`   Valid categories: ${VALID_CATEGORIES.join(", ")}`);
+    process.exit(1);
+  }
+  const templatesDir = path3.resolve(process.cwd(), "packages/a11y-audit/src/templates");
+  const outputDir = path3.resolve(process.cwd(), "a11y-audits/records");
+  const categories = getAvailableCategories(templatesDir);
+  if (categories.length === 0) {
+    console.error(`\u274C No checklist templates found in: ${templatesDir}`);
+    process.exit(1);
+  }
+  if (!categories.includes(category)) {
+    console.error(`\u274C Checklist template not found: ${category}`);
+    console.error(`   Available: ${categories.join(", ")}`);
+    process.exit(1);
+  }
+  console.info(`
+\u{1F50D} Starting accessibility audit
+   Component: ${component}
+   Category:  ${category}
+   Version:   ${version}
+`);
+  try {
+    const session = createSession({
+      component,
+      category,
+      version,
+      templatesDir
+    });
+    const items = await runInteractiveSession(session);
+    if (items.length === 0) {
+      console.info("\n\u26A0\uFE0F  No items completed. Audit cancelled.");
+      process.exit(0);
+    }
+    if (items.length < session.checklist.items.length) {
+      console.info(
+        `
+\u26A0\uFE0F  Audit incomplete: ${items.length}/${session.checklist.items.length} items completed`
+      );
+      console.info("   Run the audit again to complete remaining items.");
+      process.exit(1);
+    }
+    const auditor = process.env.USER || os.userInfo().username || "unknown@example.com";
+    const record = generateArtifact({
+      component,
+      version,
+      checklist: session.checklist,
+      items,
+      auditor: `${auditor}@example.com`,
+      outputDir
+    });
+    const filepath = saveArtifact(record, outputDir);
+    const passCount = items.filter((i) => i.status === "pass").length;
+    const failCount = items.filter((i) => i.status === "fail").length;
+    const naCount = items.filter((i) => i.status === "na").length;
+    const blockedCount = items.filter((i) => i.status === "blocked").length;
+    console.info(`
+\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+\u2551                     AUDIT COMPLETE                             \u2551
+\u2560\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2563
+\u2551  Overall Status: ${record.overallStatus.toUpperCase().padEnd(44)}\u2551
+\u2551                                                               \u2551
+\u2551  Results:                                                      \u2551
+\u2551    \u2705 Pass:    ${String(passCount).padEnd(48)}\u2551
+\u2551    \u274C Fail:    ${String(failCount).padEnd(48)}\u2551
+\u2551    \u2796 N/A:     ${String(naCount).padEnd(48)}\u2551
+\u2551    \u{1F6AB} Blocked: ${String(blockedCount).padEnd(48)}\u2551
+\u2551                                                               \u2551
+\u2551  Artifact saved to:                                            \u2551
+\u2551    ${filepath.slice(0, 59).padEnd(60)}\u2551
+\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D
+`);
+    console.info("\u{1F4DD} Remember to commit this audit record to version control:");
+    console.info(`   git add ${filepath}`);
+    console.info(`   git commit -m "Add a11y audit for ${component} v${version}"`);
+  } catch (error) {
+    console.error(`
+\u274C Audit failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+export {
+  audit
+};

package/dist/chunk-AMA6KCPL.js

@@ -0,0 +1,39 @@
+// src/lib/config.ts
+var DEFAULT_SEVERITY_THRESHOLD = {
+  failOn: ["critical", "serious"]
+};
+var SEVERITY_LEVELS = ["critical", "serious", "moderate", "minor"];
+var SEVERITY_ENV_VAR = "A11Y_SEVERITY";
+function parseSeverityThreshold(value) {
+  const input = value ?? process.env[SEVERITY_ENV_VAR];
+  if (!input) {
+    return DEFAULT_SEVERITY_THRESHOLD;
+  }
+  if (input.toLowerCase() === "all") {
+    return { failOn: [...SEVERITY_LEVELS] };
+  }
+  const levels = input.toLowerCase().split(",").map((s) => s.trim()).filter((s) => SEVERITY_LEVELS.includes(s));
+  if (levels.length === 0) {
+    console.warn(`Invalid severity threshold: "${input}". Using default.`);
+    return DEFAULT_SEVERITY_THRESHOLD;
+  }
+  return { failOn: levels };
+}
+function shouldFailOnSeverity(severity, threshold = DEFAULT_SEVERITY_THRESHOLD) {
+  return threshold.failOn.includes(severity);
+}
+function describeSeverityThreshold(threshold) {
+  if (threshold.failOn.length === SEVERITY_LEVELS.length) {
+    return "all violations";
+  }
+  return `${threshold.failOn.join(" or ")} violations`;
+}
+
+export {
+  DEFAULT_SEVERITY_THRESHOLD,
+  SEVERITY_LEVELS,
+  SEVERITY_ENV_VAR,
+  parseSeverityThreshold,
+  shouldFailOnSeverity,
+  describeSeverityThreshold
+};