@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-evidence-engine/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/src/a11y-evidence-engine/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));
+    });
+  });
+});

package/src/a11y-lint/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+        pip install -e .[dev]
+
+    - name: Run tests
+      run: pytest tests/ -v --cov=a11y_lint --cov-report=term-missing
+
+    - name: Type check
+      run: pyright a11y_lint tests
+
+    - name: Test CLI commands
+      run: |
+        a11y-lint --help
+        a11y-lint list-rules
+        a11y-lint list-rules -v
+        a11y-lint schema
+        # Test scan with sample output if fixtures exist
+        if [ -f tests/fixtures/sample_output.txt ]; then
+          a11y-lint scan tests/fixtures/sample_output.txt || true
+        fi

package/src/a11y-lint/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Type check
+        run: pyright
+        continue-on-error: true

package/src/a11y-lint/CODE_OF_CONDUCT.md

@@ -0,0 +1,129 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/src/a11y-lint/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to a11y-lint
+
+Thank you for helping improve accessibility tooling.
+
+Before contributing, please understand the core rule:
+
+> **Accessibility behavior is a public API.**
+
+---
+
+## Non-Negotiables
+
+- Do not change the CLI output contract without discussion
+- Do not weaken accessibility rules for convenience
+- All new rules must include:
+  - a clear problem statement
+  - why it affects accessibility
+  - a concrete fix
+
+---
+
+## Adding a Rule
+
+Rules must be deterministic and testable.
+
+Each rule must:
+- operate on plain text
+- produce actionable output
+- include tests with good and bad fixtures
+
+---
+
+## Rule Categories
+
+When adding a rule, classify it correctly:
+
+- **WCAG**: Mapped to a specific WCAG success criterion (e.g., SC 1.4.1)
+- **Policy**: Best practice for cognitive accessibility, not a WCAG violation
+
+Policy rules are intentional and valuable — but should not be conflated with WCAG requirements.
+
+---
+
+## Tests
+
+All contributions must include tests.
+Behavior without tests will not be merged.
+
+Run tests with:
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Tone
+
+This project is strict, not judgmental.
+
+Output should explain *what*, *why*, and *how to fix* — never shame.
+
+---
+
+## Pull Requests
+
+- Keep PRs focused on a single change
+- Include test coverage for new behavior
+- Update documentation if behavior changes
+- Ensure all tests pass before submitting

package/src/a11y-lint/GOVERNANCE.md

@@ -0,0 +1,57 @@
+# Project Governance
+
+a11y-lint is maintained with a bias toward stability.
+
+---
+
+## Decision Principles
+
+1. Accessibility > aesthetics
+2. Determinism > cleverness
+3. Clarity > terseness
+4. Humans under stress are the primary user
+
+---
+
+## What We Protect
+
+The following are considered stable public interfaces:
+
+- **CLI output contract**: `[OK]/[WARN]/[ERROR]` + `What/Why/Fix` structure
+- **JSON schema**: `cli.error.schema.v0.1.json`
+- **Exit codes**: 0 = clean, 1 = errors found
+
+Changes to these require major version bumps and community discussion.
+
+---
+
+## What May Change
+
+- New rules may be added
+- Rule descriptions may be clarified
+- Internal implementation details
+- Performance optimizations
+
+---
+
+## Versioning
+
+- **Patch** (0.1.x): Bug fixes, rule tuning
+- **Minor** (0.x.0): New rules, new outputs
+- **Major** (x.0.0): Contract or schema changes
+
+---
+
+## Accessibility Regressions
+
+Accessibility regressions are treated as release blockers.
+
+A change that makes output less accessible is a bug, not a feature.
+
+---
+
+## Maintainers
+
+Final authority rests with the project maintainer(s).
+
+Decisions prioritize the needs of users with disabilities over convenience of contributors.