@mcptoolshop/accessibility-suite 0.1.0 → 0.2.0

package/.a11y_artifacts_test/evidence.json

@@ -0,0 +1,52 @@
+{
+  "tool": "a11y-ci",
+  "tool_version": "0.1.0",
+  "run_id": "56a4a7ea-f8e8-40a9-a27b-aec92f9c96aa",
+  "timestamp": "2026-02-15T02:15:35.804358+00:00",
+  "repo": null,
+  "commit_sha": null,
+  "workflow": null,
+  "gate": {
+    "decision": "fail",
+    "exit_code": 3,
+    "fail_on": "serious",
+    "counts": {
+      "info": 0,
+      "minor": 0,
+      "moderate": 0,
+      "serious": 3,
+      "critical": 0
+    },
+    "deltas": {}
+  },
+  "blocking": [
+    {
+      "id": "TEST.001",
+      "fingerprint": "7c61e0b75cae921316221a4e5c756285e3e8837086df60a627332fbdf53c7196",
+      "severity": "serious",
+      "message": "msg",
+      "location": null
+    },
+    {
+      "id": "TEST.002",
+      "fingerprint": "ed70b4e75a112074812a72be997ffe074ff9d0eec48fe4b0a7d00fc15d546782",
+      "severity": "serious",
+      "message": "msg",
+      "location": null
+    },
+    {
+      "id": "TEST.003",
+      "fingerprint": "1fb34777b302157e998e8db92c9be20c9e1316649c2edfb825151dcaca45df56",
+      "severity": "serious",
+      "message": "msg",
+      "location": null
+    }
+  ],
+  "artifacts": [
+    {
+      "kind": "scorecard",
+      "path": "tests/fixtures/current_failures_many.json",
+      "sha256": "93d6c211476cb614b30e30256c9644d7b7694d0a67ca72bfc0a872cb4fb57196"
+    }
+  ]
+}

package/.a11y_artifacts_test/gate-result.json

@@ -0,0 +1,41 @@
+{
+  "gate": "FAIL",
+  "timestamp": "ISO8601-TODO",
+  "counts": {
+    "info": 0,
+    "minor": 0,
+    "moderate": 0,
+    "serious": 3,
+    "critical": 0
+  },
+  "baseline_counts": null,
+  "reasons": [
+    "Current run has 3 finding(s) at or above 'serious'."
+  ],
+  "blocking": {
+    "current_ids": [
+      "TEST.001",
+      "TEST.002",
+      "TEST.003"
+    ],
+    "details": [
+      {
+        "id": "TEST.001",
+        "help_url": null,
+        "help_hint": null
+      },
+      {
+        "id": "TEST.002",
+        "help_url": null,
+        "help_hint": null
+      },
+      {
+        "id": "TEST.003",
+        "help_url": null,
+        "help_hint": null
+      }
+    ],
+    "new_ids": [],
+    "new_fingerprints": []
+  }
+}

package/.a11y_artifacts_test/report.txt

@@ -0,0 +1,19 @@
+[ERROR] Accessibility gate failed (ID: A11Y.CI.GATE.FAIL)
+
+What:
+  Accessibility policy violations were detected.
+  
+  Summary:
+    Serious: 3
+
+Why:
+  Current run has 3 finding(s) at or above 'serious'.
+
+Fix:
+  Address the listed findings or update the baseline.
+  Run local check: a11y-ci gate --current <path>
+  
+  Blocking IDs (Top 10):
+  - TEST.001
+  - TEST.002
+  - TEST.003

package/.github/actions/a11y-ci/action.yml

@@ -0,0 +1,106 @@
+name: 'Accessibility Gate (a11y-ci)'
+description: 'Runs a11y-ci policy gate with unified artifact handling.'
+inputs:
+  artifact-dir:
+    description: 'Directory to store artifacts'
+    required: false
+    default: '.a11y_artifacts'
+  current:
+    description: 'Path to current scorecard JSON (optional if in artifact-dir)'
+    required: false
+  baseline:
+    description: 'Path to baseline scorecard JSON (optional if in artifact-dir)'
+    required: false
+  allowlist:
+    description: 'Path to allowlist JSON (optional if in artifact-dir)'
+    required: false
+  fail-on:
+    description: 'Minimum severity to fail on (info, minor, moderate, serious, critical)'
+    required: false
+    default: 'serious'
+  top:
+    description: 'Limit N blocking findings in output'
+    required: false
+    default: '10'
+  platform:
+    description: 'Markdown flavor for PR comments (github or ado)'
+    required: false
+    default: 'github'
+  post-comment:
+    description: 'Whether to prepare a PR comment file'
+    required: false
+    default: 'true'
+
+outputs:
+  exit_code:
+    description: 'Exit code of the gate'
+    value: ${{ steps.gate.outputs.exit_code }}
+  evidence_path:
+    description: 'Path to the generated evidence JSON'
+    value: ${{ steps.gate.outputs.evidence_path }}
+  comment_path:
+    description: 'Path to the generated PR comment markdown'
+    value: ${{ steps.gate.outputs.comment_path }}
+  gate_result_path:
+    description: 'Path to the generated gate result JSON'
+    value: ${{ steps.gate.outputs.gate_result_path }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Run Accessibility Gate
+      id: gate
+      shell: bash
+      run: |
+        # 1. Setup Artifacts
+        ARTIFACT_DIR="${{ inputs.artifact-dir }}"
+        mkdir -p "$ARTIFACT_DIR"
+        echo "Using artifact directory: $ARTIFACT_DIR"
+        
+        # 2. Construct Arguments
+        ARGS="gate --artifact-dir $ARTIFACT_DIR"
+        
+        if [ -n "${{ inputs.current }}" ]; then
+          ARGS="$ARGS --current ${{ inputs.current }}"
+        fi
+        
+        if [ -n "${{ inputs.baseline }}" ]; then
+          ARGS="$ARGS --baseline ${{ inputs.baseline }}"
+        fi
+        
+        if [ -n "${{ inputs.allowlist }}" ]; then
+          ARGS="$ARGS --allowlist ${{ inputs.allowlist }}"
+        fi
+        
+        ARGS="$ARGS --fail-on ${{ inputs.fail-on }}"
+        ARGS="$ARGS --top ${{ inputs.top }}"
+        
+        # 3. Run Gate
+        echo "Running: a11y-ci $ARGS"
+        
+        # Run and capture exit code, but don't fail immediately so we can process artifacts
+        set +e
+        a11y-ci $ARGS
+        EXIT_CODE=$?
+        set -e
+        
+        echo "Gate Exit Code: $EXIT_CODE"
+        echo "exit_code=$EXIT_CODE" >> $GITHUB_OUTPUT
+        
+        # 4. Generate Comment (if requested and evidence exists)
+        EVIDENCE_JSON="$ARTIFACT_DIR/evidence.json"
+        COMMENT_MD="$ARTIFACT_DIR/comment.md"
+        GATE_RESULT="$ARTIFACT_DIR/gate-result.json"
+        
+        if [ "${{ inputs.post-comment }}" = "true" ] && [ -f "$EVIDENCE_JSON" ]; then
+           echo "Generating PR Comment..."
+           a11y-ci comment --mcp "$EVIDENCE_JSON" --platform "${{ inputs.platform }}" --top "${{ inputs.top }}" > "$COMMENT_MD"
+           echo "comment_path=$COMMENT_MD" >> $GITHUB_OUTPUT
+        fi
+        
+        # 5. Set Outputs
+        echo "evidence_path=$EVIDENCE_JSON" >> $GITHUB_OUTPUT
+        echo "gate_result_path=$GATE_RESULT" >> $GITHUB_OUTPUT
+        
+        # 6. Exit with code
+        exit $EXIT_CODE

package/.github/workflows/a11y-gate.yml

@@ -0,0 +1,112 @@
+name: Accessibility Gate
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**/*.md'
+      - '**/*.html'
+      - 'src/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - '**/*.md'
+      - '**/*.html'
+      - 'src/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  checks: write
+  pull-requests: write # For posting comments (later step)
+
+jobs:
+  accessibility-gate:
+    name: Accessibility Compliance
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # In a real repo, you'd pip install a11y-lint a11y-ci
+      # Here we install from local source for dogfooding
+      - name: Install Tools (Local)
+        run: |
+          pip install ./src/a11y-lint
+          pip install ./src/a11y-ci
+
+      - name: Generate Scorecard (Scan)
+        run: |
+          mkdir -p .a11y_artifacts
+          # Scanning docs for demonstration
+          # Uses --artifact-dir to automatically write current.scorecard.json
+          a11y-lint scan docs --artifact-dir .a11y_artifacts
+          echo "Generated scorecard in .a11y_artifacts/"
+
+      # The reusable Action
+      - name: Run Accessibility Gate
+        id: gate
+        uses: ./.github/actions/a11y-ci
+        with:
+          artifact-dir: .a11y_artifacts
+          baseline: docs/baselines/a11y.scorecard.json
+          fail-on: serious
+          platform: github
+
+      - name: Post PR Comment
+        if: github.event_name == 'pull_request' && (success() || failure())
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            // Read the generated comment file
+            const commentPath = '${{ steps.gate.outputs.comment_path }}';
+            if (!commentPath || !fs.existsSync(commentPath)) {
+              console.log('No comment file to post.');
+              return;
+            }
+            const body = fs.readFileSync(commentPath, 'utf8');
+            const marker = '<!-- a11y-ci-sticky-comment -->';
+            const fullBody = `${marker}\n${body}`;
+            
+            const { owner, repo } = context.repo;
+            const issue_number = context.issue.number;
+            
+            // Find existing comment
+            const comments = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number,
+            });
+            
+            const existing = comments.data.find(c => c.body.includes(marker));
+            
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existing.id,
+                body: fullBody,
+              });
+              console.log(`Updated comment ${existing.id}`);
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body: fullBody,
+              });
+              console.log('Created new comment');
+            }
+
+      - name: Upload Artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: accessibility-artifacts
+          path: .a11y_artifacts/**

package/.github/workflows/ci.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   # Python projects: a11y-assist, a11y-ci, a11y-lint
   python:
@@ -25,6 +29,7 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+          cache: 'pip'
 
       - name: Install dependencies
         working-directory: src/${{ matrix.project }}
@@ -34,7 +39,18 @@ jobs:
 
       - name: Run tests
         working-directory: src/${{ matrix.project }}
-        run: pytest -v || echo "No tests or tests failed"
+        # Check if tests exist (exit code 5 = no tests). If they exist, run them and fail on error.
+        run: |
+          pytest --collect-only > /dev/null 2>&1
+          EXIT_CODE=$?
+          if [ $EXIT_CODE -eq 5 ]; then
+            echo "::warning::No tests found for ${{ matrix.project }}."
+            exit 0
+          elif [ $EXIT_CODE -ne 0 ]; then
+            echo "::error::Error collecting tests."
+            exit 1
+          fi
+          pytest -v
 
   # Node.js projects: a11y-evidence-engine, a11y-mcp-tools
   nodejs:
@@ -53,11 +69,60 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: '20'
+          cache: 'npm'
 
       - name: Install dependencies
         working-directory: src/${{ matrix.project }}
         run: npm ci
 
-      - name: Run tests
+      - name: Run tests (CI Must Fail)
         working-directory: src/${{ matrix.project }}
-        run: npm test || echo "No tests or tests failed"
+        # If npm test script exits non-zero, fail the build.
+        # This prevents accidental regressions from being swallowed.
+        run: npm test
+
+  # Integration fixture verification for a11y-ci
+  gate-verification:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install a11y-ci
+        working-directory: src/a11y-ci
+        run: pip install .
+        
+      - name: Gate Pass Check
+        working-directory: src/a11y-ci
+        run: a11y-ci gate --current tests/fixtures/current_ok.json
+        
+      - name: Gate Fail Check (JSON Report)
+        id: fail_check
+        working-directory: src/a11y-ci
+        # We expect failure (exit code 3), so we use || true to prevent job failure, 
+        # but capture output. In a real pipeline, we'd want to fail if it DOESN'T fail.
+        run: |
+          set +e
+          a11y-ci gate --current tests/fixtures/current_fail.json --format json > report.json
+          EXIT_CODE=$?
+          set -e
+          
+          echo "Exit Code: $EXIT_CODE"
+          if [ $EXIT_CODE -ne 3 ]; then
+            echo "::error::Expected exit code 3 for partial failure, got $EXIT_CODE"
+            exit 1
+          fi
+          
+          echo "::group::JSON Report"
+          cat report.json
+          echo "::endgroup::"
+          
+      - name: Upload Gate Artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: a11y-gate-report
+          path: src/a11y-ci/report.json

package/.github/workflows/test-a11y-action.yml

@@ -0,0 +1,93 @@
+name: Test Accessibility Action (Integration)
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.github/actions/a11y-ci/**'
+      - '.github/workflows/test-a11y-action.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - '.github/actions/a11y-ci/**'
+      - '.github/workflows/test-a11y-action.yml'
+
+jobs:
+  test-pass:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install a11y-ci
+        run: pip install ./src/a11y-ci
+
+      - name: Create Passing Scorecard
+        run: |
+          echo '{"meta": {"tool": "test", "version": "1"}, "findings": []}' > pass.json
+
+      - name: Run Action (Pass)
+        id: gate
+        uses: ./.github/actions/a11y-ci
+        with:
+          current: pass.json
+          fail-on: serious
+          # Use console output for testing
+          post-comment: true 
+
+      - name: Assert Outcomes
+        if: steps.gate.outputs.exit_code != '0'
+        run: |
+          echo "Expected exit code 0, got ${{ steps.gate.outputs.exit_code }}"
+          exit 1
+      
+      - name: Assert Artifacts
+        run: |
+          if [ ! -f "${{ steps.gate.outputs.report_json_path }}" ]; then exit 1; fi
+          if [ ! -f "${{ steps.gate.outputs.mcp_payload_path }}" ]; then exit 1; fi
+          if [ ! -f "${{ steps.gate.outputs.comment_md_path }}" ]; then exit 1; fi
+          
+          # Check comment content
+          if ! grep -q "Accessibility Gate: PASS" "${{ steps.gate.outputs.comment_md_path }}"; then
+            echo "Comment does not indicate PASS"
+            cat "${{ steps.gate.outputs.comment_md_path }}"
+            exit 1
+          fi
+
+  test-fail:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install a11y-ci
+        run: pip install ./src/a11y-ci
+
+      - name: Create Failing Scorecard
+        run: |
+          echo '{"meta": {"tool": "test", "version": "1"}, "findings": [{"id": "FAIL", "severity": "serious", "message": "fail"}]}' > fail.json
+
+      - name: Run Action (Fail)
+        id: gate
+        continue-on-error: true
+        uses: ./.github/actions/a11y-ci
+        with:
+          current: fail.json
+          fail-on: serious
+
+      - name: Assert Outcomes
+        if: steps.gate.outputs.exit_code != '3'
+        run: |
+          echo "Expected exit code 3, got ${{ steps.gate.outputs.exit_code }}"
+          exit 1
+
+      - name: Assert Comment Content
+        run: |
+           if ! grep -q "Accessibility Gate: FAIL" "${{ steps.gate.outputs.comment_md_path }}"; then
+             echo "Comment does not indicate FAIL"
+             exit 1
+           fi

package/.github/workflows/update-baseline.yml

@@ -0,0 +1,49 @@
+name: Update Baseline
+
+on:
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: 'Reason for updating baseline (e.g., new feature, temporary failure)'
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  update-baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # Install Tools
+      - name: Install Tools (Local)
+        run: |
+          pip install ./src/a11y-lint
+          pip install ./src/a11y-ci
+          
+      # Scan
+      - name: Generate Scorecard (Scan)
+        run: |
+          a11y-lint scan docs --format json > docs/baselines/a11y.scorecard.json
+          
+      # Detect changes and commit
+      - name: Commit Baseline
+        run: |
+          git config --global user.name 'a11y-ci-bot'
+          git config --global user.email 'a11y-ci-bot@users.noreply.github.com'
+          
+          if git diff --quiet docs/baselines/a11y.scorecard.json; then
+            echo "No changes in baseline."
+          else
+            git add docs/baselines/a11y.scorecard.json
+            git commit -m "chore(baseline): update a11y baseline" -m "${{ github.event.inputs.reason }}"
+            git push
+            echo "Baseline updated."
+          fi

package/.github/workflows/verify-docs.yml

@@ -0,0 +1,26 @@
+name: Verify Documentation
+
+on:
+  push:
+    paths:
+      - 'docs/handbooks/**'
+      - 'scripts/verify_handbooks.py'
+  pull_request:
+    paths:
+      - 'docs/handbooks/**'
+      - 'scripts/verify_handbooks.py'
+  workflow_dispatch:
+
+jobs:
+  verify-handbooks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          
+      - name: Verify Handbooks
+        run: python scripts/verify_handbooks.py

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-17
+
+### Added
+
+- Product-focused README.md replacing the migration notice with suite value proposition, architecture overview, project table, quick start guides, MCP client configuration, and documentation links.
+- HANDBOOK.md with comprehensive documentation covering the accessibility testing problem space, architecture deep dives for all six sub-projects, evidence-based testing with prov-spec provenance, CI integration patterns (GitHub Actions and Azure DevOps), MCP integration guide, development setup for the multi-language monorepo, and FAQ.
+- CHANGELOG.md in Keep a Changelog format.
+- MIT license badge in README.md.
+
+## [0.1.0] - 2026-02-12
+
+### Added
+
+- Initial monorepo structure consolidating six accessibility tools.
+- a11y-lint: accessibility linter for CLI output with WCAG and policy rules.
+- a11y-ci: CI gate for accessibility scorecards with regression detection and allowlists.
+- a11y-assist: low-vision-first CLI assistant with five accessibility profiles (lowvision, cognitive-load, screen-reader, dyslexia, plain-language).
+- a11y-evidence-engine: headless HTML scanner with prov-spec provenance records.
+- a11y-mcp-tools: MCP server exposing evidence capture and diagnosis tools.
+- a11y-demo-site: demo site with intentional violations for end-to-end testing.
+- Unified artifact strategy with `.a11y_artifacts/` directory convention.
+- GETTING_STARTED.md with three-command local setup and CI templates.
+- prov-spec documentation in `docs/prov-spec/`.
+
+[0.2.0]: https://github.com/mcp-tool-shop-org/accessibility-suite/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/mcp-tool-shop-org/accessibility-suite/releases/tag/v0.1.0