@mcptoolshop/a11y-evidence-engine 0.2.0

package/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/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/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 };

package/test/scan.test.js

@@ -0,0 +1,149 @@
+"use strict";
+
+const { describe, it, before, after } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const path = require("path");
+const { scan } = require("../src/scan.js");
+
+const FIXTURES_DIR = path.join(__dirname, "..", "fixtures");
+const TEST_OUT_DIR = path.join(__dirname, "..", "test-output");
+
+describe("scan", () => {
+  before(() => {
+    // Clean up test output
+    if (fs.existsSync(TEST_OUT_DIR)) {
+      fs.rmSync(TEST_OUT_DIR, { recursive: true });
+    }
+  });
+
+  after(() => {
+    // Clean up test output
+    if (fs.existsSync(TEST_OUT_DIR)) {
+      fs.rmSync(TEST_OUT_DIR, { recursive: true });
+    }
+  });
+
+  describe("good fixtures", () => {
+    it("should find no errors in accessible HTML", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "good");
+      const result = await scan(path.join(FIXTURES_DIR, "good"), outDir);
+
+      assert.strictEqual(result.summary.errors, 0);
+      assert.strictEqual(result.findings.length, 0);
+    });
+  });
+
+  describe("bad fixtures", () => {
+    it("should detect missing alt text", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "img-missing-alt");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      assert.strictEqual(result.summary.errors, 2);
+
+      const altFindings = result.findings.filter(
+        (f) => f.rule_id === "html.img.missing_alt"
+      );
+      assert.strictEqual(altFindings.length, 2);
+
+      // Check evidence_ref exists
+      for (const finding of altFindings) {
+        assert.ok(finding.evidence_ref);
+        assert.ok(finding.evidence_ref.record);
+        assert.ok(finding.evidence_ref.digest);
+        assert.ok(finding.evidence_ref.envelope);
+      }
+    });
+
+    it("should detect missing labels", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "input-missing-label");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "input-missing-label.html"),
+        outDir
+      );
+
+      const labelFindings = result.findings.filter(
+        (f) => f.rule_id === "html.form_control.missing_label"
+      );
+      assert.strictEqual(labelFindings.length, 2);
+    });
+
+    it("should detect missing accessible names", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "button-no-name");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "button-no-name.html"),
+        outDir
+      );
+
+      const nameFindings = result.findings.filter(
+        (f) => f.rule_id === "html.interactive.missing_name"
+      );
+      // 2 empty buttons + 1 empty link = 3
+      assert.strictEqual(nameFindings.length, 3);
+    });
+
+    it("should detect missing lang attribute", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "missing-lang");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "missing-lang.html"),
+        outDir
+      );
+
+      const langFindings = result.findings.filter(
+        (f) => f.rule_id === "html.document.missing_lang"
+      );
+      assert.strictEqual(langFindings.length, 1);
+    });
+  });
+
+  describe("output structure", () => {
+    it("should produce findings.json with correct structure", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "structure");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      // Check top-level structure
+      assert.strictEqual(result.engine, "a11y-evidence-engine");
+      assert.strictEqual(result.version, "0.1.0");
+      assert.ok(result.target);
+      assert.ok(result.summary);
+      assert.ok(Array.isArray(result.findings));
+
+      // Check findings.json was written
+      const findingsPath = path.join(outDir, "findings.json");
+      assert.ok(fs.existsSync(findingsPath));
+
+      const written = JSON.parse(fs.readFileSync(findingsPath, "utf8"));
+      assert.deepStrictEqual(written, result);
+    });
+
+    it("should assign deterministic finding IDs", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "deterministic");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      assert.strictEqual(result.findings[0].finding_id, "finding-0001");
+      assert.strictEqual(result.findings[1].finding_id, "finding-0002");
+    });
+  });
+
+  describe("directory scanning", () => {
+    it("should scan all HTML files in a directory", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "all-bad");
+      const result = await scan(path.join(FIXTURES_DIR, "bad"), outDir);
+
+      // Should scan all 4 bad fixture files
+      assert.strictEqual(result.summary.files_scanned, 4);
+
+      // Should find issues from all files
+      assert.ok(result.summary.errors > 0);
+    });
+  });
+});

package/test/vectors.test.js

@@ -0,0 +1,200 @@
+"use strict";
+
+const { describe, it, before, after } = require("node:test");
+const assert = require("node:assert");
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { scan } = require("../src/scan.js");
+const { canonicalize } = require("../src/evidence/canonicalize.js");
+
+const FIXTURES_DIR = path.join(__dirname, "..", "fixtures");
+const TEST_OUT_DIR = path.join(__dirname, "..", "test-output-vectors");
+
+describe("provenance vectors", () => {
+  before(() => {
+    if (fs.existsSync(TEST_OUT_DIR)) {
+      fs.rmSync(TEST_OUT_DIR, { recursive: true });
+    }
+  });
+
+  after(() => {
+    if (fs.existsSync(TEST_OUT_DIR)) {
+      fs.rmSync(TEST_OUT_DIR, { recursive: true });
+    }
+  });
+
+  describe("provenance file emission", () => {
+    it("should emit record.json, digest.json, envelope.json for each finding", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "prov-files");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      for (const finding of result.findings) {
+        const provDir = path.join(outDir, "provenance", finding.finding_id);
+
+        assert.ok(fs.existsSync(path.join(provDir, "record.json")));
+        assert.ok(fs.existsSync(path.join(provDir, "digest.json")));
+        assert.ok(fs.existsSync(path.join(provDir, "envelope.json")));
+      }
+    });
+  });
+
+  describe("digest verification", () => {
+    it("should produce verifiable SHA-256 digests", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "digest-verify");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      for (const finding of result.findings) {
+        const provDir = path.join(outDir, "provenance", finding.finding_id);
+
+        // Read the record and digest
+        const record = JSON.parse(
+          fs.readFileSync(path.join(provDir, "record.json"), "utf8")
+        );
+        const digest = JSON.parse(
+          fs.readFileSync(path.join(provDir, "digest.json"), "utf8")
+        );
+
+        // Extract evidence from record
+        const evidence =
+          record["prov.record.v0.1"].outputs[0]["artifact.v0.1"].content;
+
+        // Extract expected digest
+        const expectedDigest =
+          digest["prov.record.v0.1"].outputs[0]["artifact.v0.1"].digest.value;
+
+        // Compute actual digest
+        const canonical = canonicalize(evidence);
+        const actualDigest = crypto
+          .createHash("sha256")
+          .update(canonical, "utf8")
+          .digest("hex");
+
+        assert.strictEqual(
+          actualDigest,
+          expectedDigest,
+          `Digest mismatch for ${finding.finding_id}`
+        );
+      }
+    });
+  });
+
+  describe("record structure", () => {
+    it("should emit valid engine.extract.evidence.json_pointer records", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "record-structure");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      const provDir = path.join(
+        outDir,
+        "provenance",
+        result.findings[0].finding_id
+      );
+      const record = JSON.parse(
+        fs.readFileSync(path.join(provDir, "record.json"), "utf8")
+      );
+
+      const prov = record["prov.record.v0.1"];
+
+      assert.strictEqual(prov.method_id, "engine.extract.evidence.json_pointer");
+      assert.ok(prov.timestamp);
+      assert.ok(prov.inputs);
+      assert.ok(prov.outputs);
+      assert.ok(prov.agent);
+      assert.strictEqual(prov.agent.name, "a11y-evidence-engine");
+    });
+
+    it("should emit valid integrity.digest.sha256 records", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "digest-structure");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      const provDir = path.join(
+        outDir,
+        "provenance",
+        result.findings[0].finding_id
+      );
+      const digest = JSON.parse(
+        fs.readFileSync(path.join(provDir, "digest.json"), "utf8")
+      );
+
+      const prov = digest["prov.record.v0.1"];
+
+      assert.strictEqual(prov.method_id, "integrity.digest.sha256");
+      assert.ok(prov.outputs[0]["artifact.v0.1"].digest);
+      assert.strictEqual(
+        prov.outputs[0]["artifact.v0.1"].digest.algorithm,
+        "sha256"
+      );
+
+      // Digest value should be 64 hex chars
+      const digestValue = prov.outputs[0]["artifact.v0.1"].digest.value;
+      assert.strictEqual(digestValue.length, 64);
+      assert.match(digestValue, /^[a-f0-9]+$/);
+    });
+
+    it("should emit valid adapter.wrap.envelope_v0_1 records", async () => {
+      const outDir = path.join(TEST_OUT_DIR, "envelope-structure");
+      const result = await scan(
+        path.join(FIXTURES_DIR, "bad", "img-missing-alt.html"),
+        outDir
+      );
+
+      const provDir = path.join(
+        outDir,
+        "provenance",
+        result.findings[0].finding_id
+      );
+      const envelope = JSON.parse(
+        fs.readFileSync(path.join(provDir, "envelope.json"), "utf8")
+      );
+
+      assert.ok(envelope["mcp.envelope.v0.1"]);
+      assert.ok(envelope["mcp.envelope.v0.1"].result);
+      assert.ok(envelope["mcp.envelope.v0.1"].provenance);
+
+      const prov = envelope["mcp.envelope.v0.1"].provenance["prov.record.v0.1"];
+      assert.strictEqual(prov.method_id, "adapter.wrap.envelope_v0_1");
+    });
+  });
+
+  describe("canonicalization", () => {
+    it("should canonicalize JSON correctly", () => {
+      // Test sorted keys
+      const obj = { z: 1, a: 2, m: 3 };
+      assert.strictEqual(canonicalize(obj), '{"a":2,"m":3,"z":1}');
+
+      // Test nested objects
+      const nested = { b: { d: 1, c: 2 }, a: 1 };
+      assert.strictEqual(canonicalize(nested), '{"a":1,"b":{"c":2,"d":1}}');
+
+      // Test arrays (preserve order)
+      const arr = [3, 1, 2];
+      assert.strictEqual(canonicalize(arr), "[3,1,2]");
+
+      // Test strings with escaping
+      assert.strictEqual(canonicalize('hello "world"'), '"hello \\"world\\""');
+
+      // Test null and booleans
+      assert.strictEqual(canonicalize(null), "null");
+      assert.strictEqual(canonicalize(true), "true");
+      assert.strictEqual(canonicalize(false), "false");
+    });
+
+    it("should reject non-finite numbers", () => {
+      assert.throws(() => canonicalize(Infinity));
+      assert.throws(() => canonicalize(-Infinity));
+      assert.throws(() => canonicalize(NaN));
+    });
+  });
+});