@diegovelasquezweb/a11y-engine 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@diegovelasquezweb/a11y-engine",
+  "version": "0.1.0",
+  "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/diegovelasquezweb/a11y-engine.git"
+  },
+  "homepage": "https://github.com/diegovelasquezweb/a11y-engine#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "a11y-audit": "./scripts/audit.mjs"
+  },
+  "files": [
+    "scripts/**",
+    "assets/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "prepublishOnly": "node -e \"console.log('Publishing @diegovelasquezweb/a11y-engine...')\""
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.11.1",
+    "axe-core": "^4.11.1",
+    "pa11y": "^9.1.1",
+    "playwright": "^1.58.2"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}

package/scripts/audit.mjs

@@ -0,0 +1,326 @@
+/**
+ * @file audit.mjs
+ * @description Orchestrator for the accessibility audit pipeline.
+ * Coordinates the multi-stage process including dependency verification,
+ * site discovery/crawling, automated analysis, and final report generation.
+ */
+
+import { spawn, execSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import { log, DEFAULTS, SKILL_ROOT, getInternalPath } from "./core/utils.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Prints the CLI usage instructions and available command-line options.
+ * This is displayed when the user runs the script with --help or provides invalid arguments.
+ */
+function printUsage() {
+  log.info(`Usage:
+  node scripts/audit.mjs --base-url <url> [options]
+
+Targeting & Scope:
+  --base-url <url>        (Required) The target website to audit.
+  --max-routes <num>      Max routes to discover and scan (default: 10).
+  --crawl-depth <num>     How deep to follow links during discovery (1-3, default: 2).
+  --routes <csv>          Custom list of paths to scan.
+  --project-dir <path>    Path to the audited project (for stack auto-detection).
+
+Audit Intelligence:
+  --target <text>         Compliance target label (default: "WCAG 2.2 AA").
+  --only-rule <id>        Only check for this specific rule ID.
+  --ignore-findings <csv> Ignore specific rule IDs.
+  --exclude-selectors <csv> Exclude CSS selectors from scan.
+
+Execution & Emulation:
+  --color-scheme <val>    Emulate color scheme: "light" or "dark".
+  --wait-until <val>      Page load strategy: domcontentloaded|load|networkidle (default: domcontentloaded).
+  --framework <val>       Override auto-detected stack (nextjs|gatsby|react|nuxt|vue|angular|astro|svelte|shopify|wordpress|drupal).
+  --viewport <WxH>        Viewport dimensions as WIDTHxHEIGHT (e.g., 375x812 for mobile).
+  --headed                Run browser in visible mode (overrides headless).
+  --with-reports          Generate HTML and PDF reports (requires --output).
+  --skip-reports          Omit HTML and PDF report generation (default).
+  --skip-patterns         Skip source code pattern scanning even if --project-dir is set.
+  --affected-only         Re-scan only routes that had violations in the previous scan (faster re-audits).
+  --wait-ms <num>         Time to wait after page load (default: 2000).
+  --timeout-ms <num>      Network timeout (default: 30000).
+  -h, --help              Show this help.
+`);
+}
+
+/** @const {number} Execution timeout for child processes (15 minutes). */
+const SCRIPT_TIMEOUT_MS = 15 * 60 * 1000;
+
+/**
+ * Helper function to run a Node.js script as a child process.
+ * @param {string} scriptName - File name of the script located in the same directory.
+ * @param {string[]} [args=[]] - Command line arguments to pass to the script.
+ * @param {Object} [env={}] - Optional environment variables for the child process.
+ * @returns {Promise<void>} Resolves when the script finishes successfully.
+ * @throws {Error} If the process exits with a non-zero code or times out.
+ */
+async function runScript(scriptName, args = [], env = {}) {
+  return new Promise((resolve, reject) => {
+    const scriptPath = path.join(__dirname, scriptName);
+    log.info(`Running: ${scriptName} ${args.join(" ")}`);
+
+    const proc = spawn("node", [scriptPath, ...args], {
+      stdio: "inherit",
+      cwd: SKILL_ROOT,
+      env: { ...process.env, ...env },
+    });
+
+    const timer = setTimeout(() => {
+      proc.kill("SIGTERM");
+      reject(
+        new Error(
+          `Script ${scriptName} timed out after ${SCRIPT_TIMEOUT_MS / 1000}s`,
+        ),
+      );
+    }, SCRIPT_TIMEOUT_MS);
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      reject(new Error(`Failed to start ${scriptName}: ${err.message}`));
+    });
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Script ${scriptName} failed with exit code ${code}`));
+      }
+    });
+  });
+}
+
+/**
+ * The main application entry point for the accessibility audit orchestrator.
+ * Orchestrates the entire audit flow:
+ * 1. Validates inputs and environment
+ * 2. Ensures dependencies and toolchain are ready
+ * 3. Executes site discovery and scanning
+ * 4. Runs findings analysis and enrichment
+ * 5. Generates the final audit reports (Markdown, HTML, PDF)
+ * @throws {Error} If any stage of the audit pipeline fails.
+ */
+async function main() {
+  const argv = process.argv.slice(2);
+
+  /**
+   * Internal helper to extract values from command line flags.
+   * Supports both --flag=value and --flag value formats.
+   * @param {string} name - The flag name without the leading dashes.
+   * @returns {string|null} The value of the flag.
+   */
+  function getArgValue(name) {
+    const entry = argv.find((a) => a.startsWith(`--${name}=`));
+    if (entry) return entry.split("=")[1];
+    const index = argv.indexOf(`--${name}`);
+    if (index !== -1 && argv[index + 1]) return argv[index + 1];
+    return null;
+  }
+
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const baseUrl = getArgValue("base-url");
+  const maxRoutes = getArgValue("max-routes") || DEFAULTS.maxRoutes;
+  const crawlDepth = getArgValue("crawl-depth") || DEFAULTS.crawlDepth;
+  const routes = getArgValue("routes");
+  const waitMs = getArgValue("wait-ms") || DEFAULTS.waitMs;
+  const timeoutMs = getArgValue("timeout-ms") || DEFAULTS.timeoutMs;
+
+  const sessionFile = getInternalPath("a11y-session.json");
+  let projectDir = getArgValue("project-dir");
+  if (projectDir) {
+    fs.mkdirSync(path.dirname(sessionFile), { recursive: true });
+    fs.writeFileSync(sessionFile, JSON.stringify({ project_dir: path.resolve(projectDir) }), "utf-8");
+  } else if (fs.existsSync(sessionFile)) {
+    try {
+      const session = JSON.parse(fs.readFileSync(sessionFile, "utf-8"));
+      if (session.project_dir) projectDir = session.project_dir;
+    } catch { /* ignore malformed session file */ }
+  }
+
+  const colorScheme = getArgValue("color-scheme");
+  const target = getArgValue("target");
+  const headless = !argv.includes("--headed");
+
+  const onlyRule = getArgValue("only-rule");
+  const skipReports = argv.includes("--skip-reports") || !argv.includes("--with-reports");
+  const skipPatterns = argv.includes("--skip-patterns");
+  const affectedOnly = argv.includes("--affected-only");
+  const ignoreFindings = getArgValue("ignore-findings");
+  const excludeSelectors = getArgValue("exclude-selectors");
+
+  const waitUntil = getArgValue("wait-until");
+  const framework = getArgValue("framework");
+  const viewportArg = getArgValue("viewport");
+  let viewport = null;
+  if (viewportArg) {
+    const [w, h] = viewportArg.split("x").map(Number);
+    if (w && h) viewport = { width: w, height: h };
+  }
+
+  if (!baseUrl) {
+    log.error("Missing required argument: --base-url");
+    log.info("Usage: node scripts/audit.mjs --base-url <url> [options]");
+    process.exit(1);
+  }
+
+  try {
+    new URL(baseUrl);
+  } catch {
+    log.error(
+      `Invalid URL: "${baseUrl}". Provide a full URL including protocol (e.g., https://example.com).`,
+    );
+    process.exit(1);
+  }
+
+  const childEnv = {};
+  if (projectDir) childEnv.A11Y_PROJECT_DIR = path.resolve(projectDir);
+
+  try {
+    log.info("Starting accessibility audit pipeline...");
+
+    const nodeModulesPath = path.join(SKILL_ROOT, "node_modules");
+    if (!fs.existsSync(nodeModulesPath)) {
+      log.info(
+        "First run detected — installing skill dependencies (one-time setup)...",
+      );
+      try {
+        execSync("pnpm install", { cwd: SKILL_ROOT, stdio: "ignore" });
+      } catch {
+        execSync("npm install", { cwd: SKILL_ROOT, stdio: "ignore" });
+      }
+      log.success("Dependencies ready.");
+    }
+
+    await runScript("core/toolchain.mjs");
+
+    const screenshotsDir = getInternalPath("screenshots");
+    fs.rmSync(screenshotsDir, { recursive: true, force: true });
+
+    let effectiveRoutes = routes;
+    if (affectedOnly && !routes) {
+      const prevScanPath = getInternalPath("a11y-scan-results.json");
+      if (fs.existsSync(prevScanPath)) {
+        try {
+          const prevScan = JSON.parse(fs.readFileSync(prevScanPath, "utf-8"));
+          const affected = (prevScan.routes ?? [])
+            .filter((r) => Array.isArray(r.violations) && r.violations.length > 0)
+            .map((r) => r.path);
+          if (affected.length > 0) {
+            effectiveRoutes = affected.join(",");
+            log.info(`--affected-only: re-scanning ${affected.length} route(s) with previous violations.`);
+          } else {
+            log.info("--affected-only: no previous violations found — running full scan.");
+          }
+        } catch { /* fallback to full scan */ }
+      } else {
+        log.info("--affected-only: no previous scan found — running full scan.");
+      }
+    }
+
+    const scanArgs = [
+      "--base-url",
+      baseUrl,
+      "--max-routes",
+      maxRoutes.toString(),
+      "--wait-ms",
+      waitMs.toString(),
+      "--timeout-ms",
+      timeoutMs.toString(),
+      "--headless",
+      headless.toString(),
+      "--screenshots-dir",
+      screenshotsDir,
+      "--crawl-depth",
+      crawlDepth.toString(),
+    ];
+    if (onlyRule) scanArgs.push("--only-rule", onlyRule);
+    if (excludeSelectors)
+      scanArgs.push("--exclude-selectors", excludeSelectors);
+    if (effectiveRoutes) scanArgs.push("--routes", effectiveRoutes);
+    if (colorScheme) scanArgs.push("--color-scheme", colorScheme);
+    if (waitUntil) scanArgs.push("--wait-until", waitUntil);
+    if (viewport) {
+      scanArgs.push("--viewport", `${viewport.width}x${viewport.height}`);
+    }
+
+    await runScript("engine/dom-scanner.mjs", scanArgs, childEnv);
+
+    const analyzerArgs = [];
+    if (ignoreFindings) analyzerArgs.push("--ignore-findings", ignoreFindings);
+    if (framework) analyzerArgs.push("--framework", framework);
+    await runScript("engine/analyzer.mjs", analyzerArgs);
+
+    if (projectDir && !skipPatterns) {
+      const patternArgs = ["--project-dir", path.resolve(projectDir)];
+      let resolvedFramework = framework;
+      if (!resolvedFramework) {
+        try {
+          const findings = JSON.parse(fs.readFileSync(getInternalPath("a11y-findings.json"), "utf-8"));
+          resolvedFramework = findings?.metadata?.projectContext?.framework ?? null;
+        } catch { /* ignore */ }
+      }
+      if (resolvedFramework) patternArgs.push("--framework", resolvedFramework);
+      await runScript("engine/source-scanner.mjs", patternArgs);
+    }
+
+    const mdOutput = getInternalPath("remediation.md");
+    const mdArgs = ["--output", mdOutput, "--base-url", baseUrl];
+    if (target) mdArgs.push("--target", target);
+
+    if (skipReports) {
+      await runScript("reports/builders/md.mjs", mdArgs);
+    } else {
+      const output = getArgValue("output");
+      if (!output) {
+        log.error(
+          "When using --with-reports, you must specify --output <path> for the HTML report location.",
+        );
+        process.exit(1);
+      }
+      const absoluteOutputPath = path.isAbsolute(output)
+        ? output
+        : path.resolve(output);
+
+      const buildArgs = ["--output", absoluteOutputPath, "--base-url", baseUrl];
+      if (target) buildArgs.push("--target", target);
+
+      const pdfOutput = absoluteOutputPath.replace(/\.html$/, ".pdf");
+      const pdfArgs = ["--output", pdfOutput, "--base-url", baseUrl];
+      if (target) pdfArgs.push("--target", target);
+
+      const checklistOutput = path.join(path.dirname(absoluteOutputPath), "checklist.html");
+      const checklistArgs = ["--output", checklistOutput, "--base-url", baseUrl];
+
+      await Promise.all([
+        runScript("reports/builders/html.mjs", buildArgs),
+        runScript("reports/builders/checklist.mjs", checklistArgs),
+        runScript("reports/builders/md.mjs", mdArgs),
+        runScript("reports/builders/pdf.mjs", pdfArgs),
+      ]);
+
+      console.log(`REPORT_PATH=${absoluteOutputPath}`);
+    }
+
+    log.success("Audit complete! Remediation roadmap ready.");
+    console.log(`REMEDIATION_PATH=${mdOutput}`);
+  } catch (error) {
+    log.error(error.message);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  log.error(`Critical Audit Failure: ${error.message}`);
+  process.exit(1);
+});

package/scripts/core/asset-loader.mjs

@@ -0,0 +1,54 @@
+/**
+ * @file assets.mjs
+ * @description Centralized asset paths and JSON loaders for the a11y skill.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ASSET_ROOT = path.join(__dirname, "..", "..", "assets");
+
+export const ASSET_PATHS = {
+  discovery: {
+    crawlerConfig: path.join(ASSET_ROOT, "discovery", "crawler-config.json"),
+    stackDetection: path.join(
+      ASSET_ROOT,
+      "discovery",
+      "stack-detection.json",
+    ),
+  },
+  remediation: {
+    intelligence: path.join(ASSET_ROOT, "remediation", "intelligence.json"),
+    axeCheckMaps: path.join(
+      ASSET_ROOT,
+      "remediation",
+      "axe-check-maps.json",
+    ),
+    guardrails: path.join(ASSET_ROOT, "remediation", "guardrails.json"),
+    sourceBoundaries: path.join(
+      ASSET_ROOT,
+      "remediation",
+      "source-boundaries.json",
+    ),
+    codePatterns: path.join(ASSET_ROOT, "remediation", "code-patterns.json"),
+  },
+  reporting: {
+    wcagReference: path.join(ASSET_ROOT, "reporting", "wcag-reference.json"),
+    complianceConfig: path.join(
+      ASSET_ROOT,
+      "reporting",
+      "compliance-config.json",
+    ),
+    manualChecks: path.join(ASSET_ROOT, "reporting", "manual-checks.json"),
+  },
+};
+
+export function loadAssetJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    throw new Error(`Missing or invalid ${label} — reinstall the skill.`);
+  }
+}

package/scripts/core/toolchain.mjs

@@ -0,0 +1,102 @@
+/**
+ * @file toolchain.mjs
+ * @description Validates the development environment and required dependencies for the a11y skill.
+ * Checks for the presence of node_modules and installed Playwright browsers.
+ */
+
+import { SKILL_ROOT, log } from "./utils.mjs";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Prints the CLI usage instructions and available options for the toolchain checker.
+ */
+function printUsage() {
+  log.info(`Usage:
+  node toolchain.mjs [options]
+
+Options:
+  -h, --help               Show this help
+`);
+}
+
+/**
+ * Parses command-line arguments to handle the help flag.
+ * @param {string[]} argv - Array of command-line arguments.
+ */
+function parseArgs(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    printUsage();
+    process.exit(0);
+  }
+}
+
+/**
+ * Verifies if the local node_modules directory exists.
+ * @returns {boolean} True if the directory exists, false otherwise.
+ */
+function checkNodeModules() {
+  const nodeModulesPath = path.join(SKILL_ROOT, "node_modules");
+  return fs.existsSync(nodeModulesPath);
+}
+
+/**
+ * Verifies if Playwright browsers are properly installed and accessible.
+ * @returns {Promise<boolean>} True if the Chromium executable exists, false otherwise.
+ */
+async function checkPlaywrightBrowsers() {
+  try {
+    const { chromium } = await import("playwright");
+    const executablePath = chromium.executablePath();
+    return fs.existsSync(executablePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The main execution function for the toolchain validation.
+ * Performs all checks and logs results to the console.
+ * @throws {Error} If any critical dependency is missing.
+ */
+async function main() {
+  parseArgs(process.argv.slice(2));
+  const checks = [];
+
+  const modulesOk = checkNodeModules();
+  checks.push({
+    tool: "Local dependencies (node_modules)",
+    required: true,
+    ok: modulesOk,
+    fix: "Run 'pnpm install' to initialize the skill dependencies.",
+  });
+
+  const pwOk = await checkPlaywrightBrowsers();
+  checks.push({
+    tool: "Playwright installed",
+    required: true,
+    ok: pwOk,
+    fix: "Run 'pnpm install' (browsers should install automatically via postinstall or verify with 'npx playwright install').",
+  });
+
+  const blockers = checks.filter((c) => c.required && !c.ok);
+  const result = {
+    checked_at: new Date().toISOString(),
+    checks,
+    blockers: blockers.map((b) => ({ tool: b.tool, fix: b.fix })),
+    ok: blockers.length === 0,
+  };
+
+  if (result.ok) {
+    log.success("Toolchain is ready.");
+  } else {
+    log.error(`Toolchain has ${blockers.length} blockers.`);
+    blockers.forEach((b) => log.warn(`Missing: ${b.tool}. Fix: ${b.fix}`));
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  log.error(`Toolchain Check Failure: ${error.message}`);
+  process.exit(1);
+});

package/scripts/core/utils.mjs

@@ -0,0 +1,105 @@
+/**
+ * @file utils.mjs
+ * @description Core utility functions and shared configuration for the a11y skill.
+ * Provides logging, file I/O operations, and path management used throughout the audit pipeline.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * The absolute root directory of the a11y skill project.
+ * @type {string}
+ */
+export const SKILL_ROOT = path.join(__dirname, "..", "..");
+
+/**
+ * Default configuration values for the accessibility audit scanner.
+ * Used when specific options are not provided via CLI or config file.
+ * @type {Object}
+ */
+export const DEFAULTS = {
+  maxRoutes: 10,
+  crawlDepth: 2,
+  complianceTarget: "WCAG 2.2 AA",
+  colorScheme: "light",
+  viewports: [{ width: 1280, height: 800, name: "Desktop" }],
+  headless: true,
+  waitMs: 2000,
+  timeoutMs: 30000,
+  waitUntil: "domcontentloaded",
+};
+
+/**
+ * Standardized logging utility for consistent terminal output across scripts.
+ * Supports info, success, warning, and error levels with ANSI color coding.
+ */
+export const log = {
+  /**
+   * Logs an informational message in cyan.
+   * @param {string} msg - The message to log.
+   */
+  info: (msg) => console.log(`\x1b[36m[INFO]\x1b[0m ${msg}`),
+  /**
+   * Logs a success message in green.
+   * @param {string} msg - The message to log.
+   */
+  success: (msg) => console.log(`\x1b[32m[SUCCESS]\x1b[0m ${msg}`),
+  /**
+   * Logs a warning message in yellow.
+   * @param {string} msg - The message to log.
+   */
+  warn: (msg) => console.log(`\x1b[33m[WARN]\x1b[0m ${msg}`),
+  /**
+   * Logs an error message in red, optionally including a troubleshooting hint.
+   * @param {string} msg - The error message.
+   * @param {string} [hint=""] - An optional hint or troubleshooting suggestion.
+   */
+  error: (msg, hint = "") => {
+    console.error(`\x1b[31m[ERROR]\x1b[0m ${msg}`);
+    if (hint) {
+      console.log(`\x1b[35m[TROUBLESHOOTING]\x1b[0m ${hint}`);
+    }
+  },
+};
+
+/**
+ * Writes data to a JSON file, creating parent directories if they don't exist.
+ * @param {string} filePath - Absolute path to the destination file.
+ * @param {any} data - The data to serialize (will be formatted with 2-space indentation).
+ */
+export function writeJson(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+/**
+ * Reads and parses a JSON file.
+ * @param {string} filePath - Absolute path to the JSON file.
+ * @returns {any|null} The parsed data or null if the file doesn't exist or is invalid.
+ */
+export function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (e) {
+    log.error(`Failed to read JSON from ${filePath}: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Constructs an absolute path to a file within the internal audit directory.
+ * @param {string} filename - The name of the file.
+ * @returns {string} The resolved absolute path.
+ */
+export function getInternalPath(filename) {
+  return path.join(SKILL_ROOT, ".audit", filename);
+}