@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-evidence-engine/src/html_parse.js

@@ -0,0 +1,117 @@
+"use strict";
+
+const { Parser } = require("htmlparser2");
+
+/**
+ * Parse HTML and build a flat nodes[] array in document order.
+ * Each node has a stable index for JSON pointer references.
+ *
+ * @param {string} html - Raw HTML content
+ * @returns {{ nodes: Array, root: Object|null }}
+ */
+function parseHtml(html) {
+  const nodes = [];
+  const stack = [];
+  let root = null;
+
+  const parser = new Parser(
+    {
+      onopentag(name, attrs) {
+        const node = {
+          type: "element",
+          tagName: name.toLowerCase(),
+          attrs: { ...attrs },
+          children: [],
+          parent: stack.length > 0 ? stack[stack.length - 1] : null,
+          index: nodes.length,
+        };
+
+        nodes.push(node);
+
+        if (node.parent) {
+          node.parent.children.push(node);
+        } else {
+          root = node;
+        }
+
+        stack.push(node);
+      },
+
+      ontext(text) {
+        // Only capture non-whitespace text for accessibility analysis
+        const trimmed = text.trim();
+        if (trimmed && stack.length > 0) {
+          const textNode = {
+            type: "text",
+            content: text,
+            trimmed: trimmed,
+            parent: stack[stack.length - 1],
+            index: nodes.length,
+          };
+          nodes.push(textNode);
+          stack[stack.length - 1].children.push(textNode);
+        }
+      },
+
+      onclosetag() {
+        stack.pop();
+      },
+    },
+    {
+      lowerCaseTags: true,
+      lowerCaseAttributeNames: true,
+      decodeEntities: true,
+    }
+  );
+
+  parser.write(html);
+  parser.end();
+
+  return { nodes, root };
+}
+
+/**
+ * Get the text content of an element (concatenated child text nodes).
+ * @param {Object} node - Element node
+ * @returns {string}
+ */
+function getTextContent(node) {
+  if (!node || !node.children) return "";
+
+  let text = "";
+  for (const child of node.children) {
+    if (child.type === "text") {
+      text += child.content;
+    } else if (child.type === "element") {
+      text += getTextContent(child);
+    }
+  }
+  return text.trim();
+}
+
+/**
+ * Find all elements matching a predicate.
+ * @param {Array} nodes - Flat nodes array
+ * @param {Function} predicate - (node) => boolean
+ * @returns {Array}
+ */
+function findElements(nodes, predicate) {
+  return nodes.filter((n) => n.type === "element" && predicate(n));
+}
+
+/**
+ * Find element by ID.
+ * @param {Array} nodes - Flat nodes array
+ * @param {string} id - Element ID
+ * @returns {Object|null}
+ */
+function getElementById(nodes, id) {
+  return nodes.find((n) => n.type === "element" && n.attrs.id === id) || null;
+}
+
+module.exports = {
+  parseHtml,
+  getTextContent,
+  findElements,
+  getElementById,
+};

package/src/a11y-evidence-engine/src/ids.js

@@ -0,0 +1,53 @@
+"use strict";
+
+/**
+ * Generate deterministic finding IDs.
+ * Findings are sorted by (file, rule_id, pointer) then numbered.
+ *
+ * @param {Array} findings - Raw findings array
+ * @returns {Array} Findings with assigned finding_id
+ */
+function assignFindingIds(findings) {
+  // Sort for deterministic ordering
+  const sorted = [...findings].sort((a, b) => {
+    // First by file
+    const fileCompare = a.location.file.localeCompare(b.location.file);
+    if (fileCompare !== 0) return fileCompare;
+
+    // Then by rule_id
+    const ruleCompare = a.rule_id.localeCompare(b.rule_id);
+    if (ruleCompare !== 0) return ruleCompare;
+
+    // Then by pointer (numeric extraction for proper sorting)
+    const aIndex = extractPointerIndex(a.location.json_pointer);
+    const bIndex = extractPointerIndex(b.location.json_pointer);
+    return aIndex - bIndex;
+  });
+
+  // Assign sequential IDs
+  return sorted.map((finding, index) => ({
+    ...finding,
+    finding_id: formatFindingId(index + 1),
+  }));
+}
+
+/**
+ * Extract numeric index from JSON pointer.
+ * @param {string} pointer - e.g., "/nodes/12"
+ * @returns {number}
+ */
+function extractPointerIndex(pointer) {
+  const match = pointer.match(/\/nodes\/(\d+)/);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+/**
+ * Format finding ID with zero-padding.
+ * @param {number} num - Finding number (1-based)
+ * @returns {string} e.g., "finding-0001"
+ */
+function formatFindingId(num) {
+  return `finding-${String(num).padStart(4, "0")}`;
+}
+
+module.exports = { assignFindingIds, formatFindingId };

package/src/a11y-evidence-engine/src/rules/document_missing_lang.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const { findElements } = require("../html_parse.js");
+
+const RULE_ID = "html.document.missing_lang";
+
+/**
+ * Check for <html> element missing lang attribute.
+ * WCAG 3.1.1 - Language of Page (Level A)
+ */
+function run(nodes, context) {
+  const findings = [];
+
+  const htmlElements = findElements(nodes, (n) => n.tagName === "html");
+
+  for (const node of htmlElements) {
+    const lang = node.attrs.lang;
+
+    if (!lang || lang.trim() === "") {
+      findings.push({
+        rule_id: RULE_ID,
+        severity: "error",
+        confidence: 1.0,
+        message: "Document is missing a lang attribute on the <html> element.",
+        location: {
+          file: context.relativePath,
+          json_pointer: `/nodes/${node.index}`,
+        },
+        evidence: {
+          tagName: node.tagName,
+          attrs: filterAttrs(node.attrs, ["lang"]),
+        },
+      });
+    }
+  }
+
+  return findings;
+}
+
+function filterAttrs(attrs, keys) {
+  const filtered = {};
+  for (const key of keys) {
+    if (key in attrs) {
+      filtered[key] = attrs[key];
+    }
+  }
+  return filtered;
+}
+
+module.exports = { id: RULE_ID, run };

package/src/a11y-evidence-engine/src/rules/form_control_missing_label.js

@@ -0,0 +1,105 @@
+"use strict";
+
+const { findElements, getElementById } = require("../html_parse.js");
+
+const RULE_ID = "html.form_control.missing_label";
+
+const FORM_CONTROLS = ["input", "select", "textarea"];
+const EXEMPT_INPUT_TYPES = ["hidden", "submit", "reset", "button", "image"];
+
+/**
+ * Check for form controls missing associated labels.
+ * WCAG 1.3.1 - Info and Relationships (Level A)
+ * WCAG 4.1.2 - Name, Role, Value (Level A)
+ *
+ * A form control needs one of:
+ * - Associated <label for="...">
+ * - aria-label attribute
+ * - aria-labelledby attribute (pointing to existing element)
+ */
+function run(nodes, context) {
+  const findings = [];
+
+  // Find all label elements for lookup
+  const labels = findElements(nodes, (n) => n.tagName === "label");
+  const labelForIds = new Set(
+    labels.map((l) => l.attrs.for).filter((f) => f)
+  );
+
+  // Check form controls
+  const controls = findElements(nodes, (n) => FORM_CONTROLS.includes(n.tagName));
+
+  for (const node of controls) {
+    // Skip exempt input types
+    if (node.tagName === "input") {
+      const type = (node.attrs.type || "text").toLowerCase();
+      if (EXEMPT_INPUT_TYPES.includes(type)) {
+        continue;
+      }
+    }
+
+    if (!hasAccessibleLabel(node, labelForIds, nodes)) {
+      findings.push({
+        rule_id: RULE_ID,
+        severity: "error",
+        confidence: 0.95,
+        message: `Form control <${node.tagName}> is missing an associated label.`,
+        location: {
+          file: context.relativePath,
+          json_pointer: `/nodes/${node.index}`,
+        },
+        evidence: {
+          tagName: node.tagName,
+          attrs: filterAttrs(node.attrs, [
+            "id",
+            "name",
+            "type",
+            "aria-label",
+            "aria-labelledby",
+          ]),
+        },
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Check if a form control has an accessible label.
+ */
+function hasAccessibleLabel(node, labelForIds, nodes) {
+  // Check aria-label
+  if (node.attrs["aria-label"] && node.attrs["aria-label"].trim()) {
+    return true;
+  }
+
+  // Check aria-labelledby (must point to existing element)
+  if (node.attrs["aria-labelledby"]) {
+    const ids = node.attrs["aria-labelledby"].split(/\s+/);
+    for (const id of ids) {
+      if (getElementById(nodes, id)) {
+        return true;
+      }
+    }
+  }
+
+  // Check for associated label via 'for' attribute
+  if (node.attrs.id && labelForIds.has(node.attrs.id)) {
+    return true;
+  }
+
+  return false;
+}
+
+function filterAttrs(attrs, keys) {
+  const filtered = {};
+  for (const key of keys) {
+    if (key in attrs) {
+      filtered[key] = attrs[key];
+    }
+  }
+  return filtered;
+}
+
+module.exports = { id: RULE_ID, run };

package/src/a11y-evidence-engine/src/rules/img_missing_alt.js

@@ -0,0 +1,77 @@
+"use strict";
+
+const { findElements } = require("../html_parse.js");
+
+const RULE_ID = "html.img.missing_alt";
+
+/**
+ * Check for <img> elements missing alt attribute.
+ * WCAG 1.1.1 - Non-text Content (Level A)
+ *
+ * Exceptions:
+ * - role="presentation" or role="none"
+ * - aria-hidden="true"
+ */
+function run(nodes, context) {
+  const findings = [];
+
+  const imgElements = findElements(nodes, (n) => n.tagName === "img");
+
+  for (const node of imgElements) {
+    // Skip decorative images
+    if (isDecorativeImage(node)) {
+      continue;
+    }
+
+    const alt = node.attrs.alt;
+
+    // Missing alt attribute entirely
+    if (alt === undefined) {
+      findings.push({
+        rule_id: RULE_ID,
+        severity: "error",
+        confidence: 0.98,
+        message: "Image element is missing alt text.",
+        location: {
+          file: context.relativePath,
+          json_pointer: `/nodes/${node.index}`,
+        },
+        evidence: {
+          tagName: node.tagName,
+          attrs: filterAttrs(node.attrs, ["src", "alt", "role", "aria-hidden"]),
+        },
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Check if image is marked as decorative.
+ */
+function isDecorativeImage(node) {
+  const role = node.attrs.role;
+  if (role === "presentation" || role === "none") {
+    return true;
+  }
+
+  const ariaHidden = node.attrs["aria-hidden"];
+  if (ariaHidden === "true") {
+    return true;
+  }
+
+  return false;
+}
+
+function filterAttrs(attrs, keys) {
+  const filtered = {};
+  for (const key of keys) {
+    if (key in attrs) {
+      filtered[key] = attrs[key];
+    }
+  }
+  return filtered;
+}
+
+module.exports = { id: RULE_ID, run };

package/src/a11y-evidence-engine/src/rules/index.js

@@ -0,0 +1,37 @@
+"use strict";
+
+const imgMissingAlt = require("./img_missing_alt.js");
+const formControlMissingLabel = require("./form_control_missing_label.js");
+const interactiveMissingName = require("./interactive_missing_name.js");
+const documentMissingLang = require("./document_missing_lang.js");
+
+/**
+ * All available rules.
+ * Each rule exports: { id, run(nodes, context) => findings[] }
+ */
+const rules = [
+  documentMissingLang,
+  imgMissingAlt,
+  formControlMissingLabel,
+  interactiveMissingName,
+];
+
+/**
+ * Run all rules against parsed HTML nodes.
+ *
+ * @param {Array} nodes - Flat nodes array from parseHtml
+ * @param {Object} context - { filePath, relativePath }
+ * @returns {Array} Raw findings (without finding_id assigned)
+ */
+function runRules(nodes, context) {
+  const findings = [];
+
+  for (const rule of rules) {
+    const ruleFindings = rule.run(nodes, context);
+    findings.push(...ruleFindings);
+  }
+
+  return findings;
+}
+
+module.exports = { rules, runRules };

package/src/a11y-evidence-engine/src/rules/interactive_missing_name.js

@@ -0,0 +1,129 @@
+"use strict";
+
+const { findElements, getTextContent, getElementById } = require("../html_parse.js");
+
+const RULE_ID = "html.interactive.missing_name";
+
+/**
+ * Check for interactive elements missing accessible names.
+ * WCAG 4.1.2 - Name, Role, Value (Level A)
+ *
+ * Checks:
+ * - <button> elements
+ * - <a href="..."> elements (links)
+ *
+ * An accessible name can come from:
+ * - Text content
+ * - aria-label
+ * - aria-labelledby
+ * - title attribute (fallback)
+ */
+function run(nodes, context) {
+  const findings = [];
+
+  // Check buttons
+  const buttons = findElements(nodes, (n) => n.tagName === "button");
+  for (const node of buttons) {
+    if (!hasAccessibleName(node, nodes)) {
+      findings.push({
+        rule_id: RULE_ID,
+        severity: "error",
+        confidence: 0.95,
+        message: "Button element is missing an accessible name.",
+        location: {
+          file: context.relativePath,
+          json_pointer: `/nodes/${node.index}`,
+        },
+        evidence: {
+          tagName: node.tagName,
+          attrs: filterAttrs(node.attrs, [
+            "id",
+            "type",
+            "aria-label",
+            "aria-labelledby",
+            "title",
+          ]),
+          textContent: getTextContent(node).substring(0, 50),
+        },
+      });
+    }
+  }
+
+  // Check links (anchors with href)
+  const links = findElements(
+    nodes,
+    (n) => n.tagName === "a" && n.attrs.href !== undefined
+  );
+  for (const node of links) {
+    if (!hasAccessibleName(node, nodes)) {
+      findings.push({
+        rule_id: RULE_ID,
+        severity: "error",
+        confidence: 0.95,
+        message: "Link element is missing an accessible name.",
+        location: {
+          file: context.relativePath,
+          json_pointer: `/nodes/${node.index}`,
+        },
+        evidence: {
+          tagName: node.tagName,
+          attrs: filterAttrs(node.attrs, [
+            "href",
+            "aria-label",
+            "aria-labelledby",
+            "title",
+          ]),
+          textContent: getTextContent(node).substring(0, 50),
+        },
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Check if an element has an accessible name.
+ */
+function hasAccessibleName(node, nodes) {
+  // Check aria-label
+  if (node.attrs["aria-label"] && node.attrs["aria-label"].trim()) {
+    return true;
+  }
+
+  // Check aria-labelledby
+  if (node.attrs["aria-labelledby"]) {
+    const ids = node.attrs["aria-labelledby"].split(/\s+/);
+    for (const id of ids) {
+      const labelElement = getElementById(nodes, id);
+      if (labelElement && getTextContent(labelElement).trim()) {
+        return true;
+      }
+    }
+  }
+
+  // Check text content
+  const textContent = getTextContent(node).trim();
+  if (textContent) {
+    return true;
+  }
+
+  // Check title as fallback
+  if (node.attrs.title && node.attrs.title.trim()) {
+    return true;
+  }
+
+  return false;
+}
+
+function filterAttrs(attrs, keys) {
+  const filtered = {};
+  for (const key of keys) {
+    if (key in attrs) {
+      filtered[key] = attrs[key];
+    }
+  }
+  return filtered;
+}
+
+module.exports = { id: RULE_ID, run };

package/src/a11y-evidence-engine/src/scan.js

@@ -0,0 +1,128 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { walkHtmlFiles } = require("./fswalk.js");
+const { parseHtml } = require("./html_parse.js");
+const { runRules } = require("./rules/index.js");
+const { assignFindingIds } = require("./ids.js");
+const { emitProvenance } = require("./evidence/prov_emit.js");
+
+const ENGINE_NAME = "a11y-evidence-engine";
+const ENGINE_VERSION = "0.1.0";
+
+/**
+ * Scan HTML files and produce findings with provenance.
+ *
+ * @param {string} targetPath - File or directory to scan
+ * @param {string} outDir - Output directory
+ * @returns {Object} Scan result with summary
+ */
+async function scan(targetPath, outDir) {
+  const resolvedTarget = path.resolve(targetPath);
+  const resolvedOut = path.resolve(outDir);
+
+  // Gather HTML files
+  const files = walkHtmlFiles(resolvedTarget);
+
+  if (files.length === 0) {
+    throw new Error(`No HTML files found in: ${resolvedTarget}`);
+  }
+
+  // Collect all findings
+  const allFindings = [];
+  const baseDir = fs.statSync(resolvedTarget).isDirectory()
+    ? resolvedTarget
+    : path.dirname(resolvedTarget);
+
+  for (const filePath of files) {
+    const html = fs.readFileSync(filePath, "utf8");
+    const { nodes } = parseHtml(html);
+
+    const relativePath = path.relative(baseDir, filePath).replace(/\\/g, "/");
+
+    const context = {
+      filePath,
+      relativePath,
+    };
+
+    const findings = runRules(nodes, context);
+    allFindings.push(...findings);
+  }
+
+  // Assign deterministic IDs
+  const numberedFindings = assignFindingIds(allFindings);
+
+  // Create output directory
+  fs.mkdirSync(resolvedOut, { recursive: true });
+
+  // Generate timestamp for all provenance records (deterministic within scan)
+  const timestamp = new Date().toISOString();
+
+  // Emit provenance for each finding
+  const findingsWithRefs = [];
+
+  for (const finding of numberedFindings) {
+    const provDir = path.join(resolvedOut, "provenance", finding.finding_id);
+    fs.mkdirSync(provDir, { recursive: true });
+
+    const { record, digest, envelope } = emitProvenance(finding, {
+      engineVersion: ENGINE_VERSION,
+      timestamp,
+    });
+
+    // Write provenance files
+    fs.writeFileSync(
+      path.join(provDir, "record.json"),
+      JSON.stringify(record, null, 2)
+    );
+    fs.writeFileSync(
+      path.join(provDir, "digest.json"),
+      JSON.stringify(digest, null, 2)
+    );
+    fs.writeFileSync(
+      path.join(provDir, "envelope.json"),
+      JSON.stringify(envelope, null, 2)
+    );
+
+    // Add evidence_ref to finding (without the raw evidence)
+    const { evidence, ...findingWithoutEvidence } = finding;
+    findingsWithRefs.push({
+      ...findingWithoutEvidence,
+      evidence_ref: {
+        record: `provenance/${finding.finding_id}/record.json`,
+        digest: `provenance/${finding.finding_id}/digest.json`,
+        envelope: `provenance/${finding.finding_id}/envelope.json`,
+      },
+    });
+  }
+
+  // Build summary
+  const summary = {
+    files_scanned: files.length,
+    errors: findingsWithRefs.filter((f) => f.severity === "error").length,
+    warnings: findingsWithRefs.filter((f) => f.severity === "warning").length,
+    info: findingsWithRefs.filter((f) => f.severity === "info").length,
+  };
+
+  // Build output
+  const output = {
+    engine: ENGINE_NAME,
+    version: ENGINE_VERSION,
+    target: {
+      path: path.relative(process.cwd(), resolvedTarget).replace(/\\/g, "/") || ".",
+    },
+    summary,
+    findings: findingsWithRefs,
+  };
+
+  // Write findings.json
+  fs.writeFileSync(
+    path.join(resolvedOut, "findings.json"),
+    JSON.stringify(output, null, 2)
+  );
+
+  return output;
+}
+
+module.exports = { scan };