@mcptoolshop/accessibility-suite 0.1.0 → 0.2.0

package/src/a11y-ci/tests/test_polish.py

@@ -0,0 +1,83 @@
+
+import json
+import pytest
+from click.testing import CliRunner
+from a11y_ci.cli import main
+from a11y_ci.pr_comment import render_pr_comment
+
+FIXTURES = "tests/fixtures"
+
+def test_gate_top_flag():
+    """Test --top limits the output lines."""
+    runner = CliRunner()
+    result = runner.invoke(main, [
+        "gate",
+        "--current", f"{FIXTURES}/current_failures_many.json",
+        "--fail-on", "minor", # Ensure we have failures
+        "--top", "1"
+    ])
+    assert result.exit_code == 3
+    # Should see the first blocking ID
+    assert "Blocking IDs (Top 1):" in result.output
+    # Should see "and X more"
+    assert "... and 2 more" in result.output
+
+def test_comment_top_flag():
+    """Test --top limits PR comment output."""
+    payload = {
+        "gate": {"decision": "fail"},
+        "blocking": [{"id": f"ID.{i}", "severity": "serious"} for i in range(20)]
+    }
+    
+    # IDs will sort string-wise: ID.0, ID.1, ID.10, ID.11, ID.12 ...
+    # So top 5 are: ID.0, ID.1, ID.10, ID.11, ID.12
+    
+    # Render with top=5
+    md = render_pr_comment(payload, top=5)
+    assert "_Showing first 5 of 20 violations_" in md
+    
+    assert "ID.0" in md
+    assert "ID.12" in md
+    assert "ID.2" not in md # Comes later lexicographically
+
+
+def test_graceful_missing_fields():
+    """Render PR comment with minimal payload should not crash."""
+    minimal = {
+        "gate": {}
+        # Missing blocking, artifacts, counts, etc.
+    }
+    md = render_pr_comment(minimal)
+    assert "# ❌ Accessibility Gate: FAIL" in md # default decision unknown -> fail
+    assert "| Findings | 0 | - |" in md
+
+    # Finding without optional fields
+    payload_partial = {
+        "gate": {"decision": "fail"},
+        "blocking": [{"id": "A"}] # Missing severity, message, location
+    }
+    md = render_pr_comment(payload_partial)
+    assert "### [INFO] A" in md # default severity info
+    assert "No message provided" in md
+    assert "Unknown location" in md
+
+def test_determinism(tmp_path):
+    """Running gate twice on same input should produce identical output."""
+    runner = CliRunner()
+    
+    # Run 1
+    res1 = runner.invoke(main, [
+        "gate",
+        "--current", f"{FIXTURES}/current_fail.json",
+        "--format", "json"
+    ])
+    
+    # Run 2
+    res2 = runner.invoke(main, [
+        "gate",
+        "--current", f"{FIXTURES}/current_fail.json",
+        "--format", "json"
+    ])
+    
+    assert res1.exit_code == res2.exit_code
+    assert res1.output == res2.output

package/src/a11y-ci/tests/test_pr_comment.py

@@ -0,0 +1,103 @@
+
+import json
+import pytest
+from a11y_ci.pr_comment import render_pr_comment
+
+@pytest.fixture
+def sample_payload():
+    return {
+        "tool": "a11y-ci",
+        "tool_version": "1.0.0",
+        "repo": "org/repo",
+        "commit_sha": "abcdef123456",
+        "run_id": "run-xyz-789",
+        "gate": {
+            "decision": "fail",
+            "fail_on": "serious",
+            "counts": {"serious": 2, "minor": 5},
+            "deltas": {"serious": 2}
+        },
+        "blocking": [
+            {
+                "id": "A11Y.IMG.ALT", 
+                "severity": "serious", 
+                "message": "Missing alt text", 
+                "location": "logo.png",
+                "help_hint": "Add alt='logo'",
+                "help_url": "http://docs/img-alt"
+            },
+            {
+                "id": "A11Y.BTN.NAME", 
+                "severity": "critical", 
+                "message": "Button empty", 
+                "location": "btn.js"
+            }
+        ],
+        "artifacts": [
+             {"kind": "scorecard", "sha256": "aabbccddeeff0011223344"}
+        ]
+    }
+
+def test_render_fail_github(sample_payload):
+    """Test standard GitHub failure output."""
+    md = render_pr_comment(sample_payload, platform="github")
+    
+    # Header
+    assert "❌ Accessibility Gate: FAIL" in md
+    
+    # Table summary
+    assert "| Serious | 2 | +2 |" in md
+    assert "| Minor | 5 | - |" in md
+    
+    # Blocking findings section
+    assert "## 🚫 Blocking Findings" in md
+    
+    # Finding 1 (Critical should come first due to sorting)
+    assert "### [CRITICAL] A11Y.BTN.NAME" in md
+    assert "Button empty" in md
+    
+    # Finding 2 (Serious)
+    assert "### [SERIOUS] A11Y.IMG.ALT" in md
+    assert "**Fix**: Add alt='logo'" in md
+    assert "**Docs**: [Read Guidance](http://docs/img-alt)" in md
+    
+    # Artifacts
+    # hash is mock SHA 'aabbccddeeff0011223344', truncated to 12 chars + ...
+    assert "aabbccddeeff..." in md
+    
+    # Footer
+    assert "Generated by **a11y-ci v1.0.0**" in md
+    assert "Commit: `abcdef1`" in md
+
+def test_render_pass(sample_payload):
+    """Test passing state."""
+    sample_payload["gate"]["decision"] = "pass"
+    sample_payload["blocking"] = []
+    
+    md = render_pr_comment(sample_payload, platform="github")
+    
+    assert "✅ Accessibility Gate: PASS" in md
+    assert "🚫 Blocking Findings" not in md
+
+def test_render_ado_flavor(sample_payload):
+    """Test ADO-specific nuances (mostly header changes in this simplified impl)."""
+    md = render_pr_comment(sample_payload, platform="ado")
+    
+    # Check H3 format distinct from GitHub fixture
+    # GH: ### [CRITICAL] ID
+    # ADO: ### CRITICAL: ID
+    assert "### CRITICAL: A11Y.BTN.NAME" in md
+    assert "### [CRITICAL]" not in md
+
+def test_render_missing_optional_fields():
+    """Should handle missing deltas/counts gracefully."""
+    minimal_payload = {
+        "gate": {
+             "decision": "pass",
+             "fail_on": "error"
+        }
+    }
+    md = render_pr_comment(minimal_payload)
+    assert "✅ Accessibility Gate: PASS" in md
+    # Should show 0 findings in table
+    assert "| Findings | 0 | - |" in md

package/src/a11y-ci/tests/test_rule_help.py

@@ -0,0 +1,70 @@
+
+import json
+from dataclasses import dataclass
+from unittest.mock import patch
+import pytest
+
+from a11y_ci.help import get_help, HelpInfo
+from a11y_ci.gate import GateResult
+from a11y_ci.report import print_text_report, print_json_report
+
+def test_registry_lookup():
+    """Verify registry lookups handle case and whitespace."""
+    info = get_help(" a11y.img.alt ")
+    assert info is not None
+    assert info.title == "Missing Image Alt Text"
+    assert "add an 'alt'" in info.hint.lower()
+    
+    # Missing
+    assert get_help("UNKOWN.RULE") is None
+
+def test_report_includes_help_text(capsys):
+    """Text report should include Fix and Docs lines for known rules."""
+    result = GateResult(
+        ok=False,
+        reasons=["Found errors"],
+        current_blocking_ids=["A11Y.IMG.ALT", "UNKNOWN.ID"],
+        new_blocking_ids=[],
+        current_counts={"serious": 1},
+        baseline_counts=None,
+        new_fingerprints=[]
+    )
+    
+    print_text_report(result)
+    captured = capsys.readouterr()
+    
+    # Known rule -> Detailed Help
+    assert "A11Y.IMG.ALT" in captured.out
+    assert "Fix: Add an 'alt' attribute" in captured.out
+    assert "Docs: https://" in captured.out
+    
+    # Unknown rule -> Simple listing
+    assert "UNKNOWN.ID" in captured.out
+    # Ideally should NOT show Fix/Docs for unknown
+    # But simple regex check might be tricky if one rule has it.
+    # We verify that we didn't crash at least.
+
+def test_json_report_includes_help_fields(capsys):
+    """JSON report should include help_url and help_hint."""
+    result = GateResult(
+        ok=False,
+        reasons=["Found errors"],
+        current_blocking_ids=["A11Y.IMG.ALT"],
+        new_blocking_ids=[],
+        current_counts={"serious": 1},
+        baseline_counts=None,
+        new_fingerprints=[]
+    )
+    
+    print_json_report(result)
+    captured = capsys.readouterr()
+    data = json.loads(captured.out)
+    
+    details = data["blocking"]["details"]
+    assert len(details) == 1
+    item = details[0]
+    
+    assert item["id"] == "A11Y.IMG.ALT"
+    assert item["help_hint"] is not None
+    assert "alt" in item["help_hint"]
+    assert item["help_url"] is not None

package/src/a11y-ci/tests/test_schema_validation.py

@@ -0,0 +1,36 @@
+
+import pytest
+import json
+import jsonschema
+from pathlib import Path
+from click.testing import CliRunner
+from a11y_ci.cli import main
+from a11y_ci.scorecard import Scorecard
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+def test_load_scorecard_valid():
+    # Should not raise
+    s = Scorecard.load(str(FIXTURES / "current_ok.json"))
+    assert isinstance(s, Scorecard)
+
+def test_load_scorecard_invalid_schema(tmp_path):
+    # Create invalid file
+    bad_file = tmp_path / "bad.json"
+    bad_file.write_text(json.dumps({"tool": "oops", "findings": []}), encoding="utf-8")
+    
+    with pytest.raises(jsonschema.ValidationError):
+        Scorecard.load(str(bad_file))
+
+def test_cli_schema_validation_error(tmp_path):
+    bad_file = tmp_path / "bad.json"
+    bad_file.write_text(json.dumps({"tool": "oops", "findings": []}), encoding="utf-8")
+    
+    runner = CliRunner()
+    result = runner.invoke(main, ["gate", "--current", str(bad_file)])
+    
+    # Should be exit code 2 (input error)
+    assert result.exit_code == 2
+    # Should contain our specific error message
+    assert "Scorecard format invalid" in result.output
+    assert "required property" in result.output or "is not of type" in result.output

package/src/a11y-ci/tests/test_scorecard_canonical.py

@@ -0,0 +1,88 @@
+
+import json
+from dataclasses import replace
+from pathlib import Path
+
+import pytest
+from a11y_ci.scorecard import Scorecard, compute_fingerprint, normalize_severity
+
+def test_fingerprint_stability():
+    """Fingerprint should be stable for identical content."""
+    f1 = {"id": "A", "message": "msg", "location": {"path": "p"}}
+    f2 = {"id": "A", "message": "msg", "location": {"path": "p"}}
+    # Different ordering in dict shouldn't matter due to sort_keys=True
+    f3 = {"location": {"path": "p"}, "message": "msg", "id": "A"}
+    
+    fp1 = compute_fingerprint(f1)
+    fp2 = compute_fingerprint(f2)
+    fp3 = compute_fingerprint(f3)
+    
+    assert fp1 == fp2 == fp3
+    assert len(fp1) == 64  # SHA256 hex digest
+
+def test_canonical_sort_order():
+    """Findings should be sorted by Severity (desc), then ID, then Fingerprint."""
+    # S: serious, M: minor
+    findings = [
+        {"id": "B", "severity": "minor", "message": "msg1"},
+        {"id": "A", "severity": "serious", "message": "msg2"},
+        {"id": "C", "severity": "minor", "message": "msg3"},
+    ]
+    
+    sc = Scorecard(raw={}, findings=findings).canonicalize()
+    
+    # Expected order:
+    # 1. A (serious)
+    # 2. B (minor)
+    # 3. C (minor)
+    
+    assert sc.findings[0]["id"] == "A"
+    assert sc.findings[1]["id"] == "B"
+    assert sc.findings[2]["id"] == "C"
+
+def test_deduplication():
+    """Duplicate findings (same fingerprint) should collapse to one."""
+    f = {"id": "A", "severity": "serious", "message": "msg", "location": {"path": "p"}}
+    findings = [f, f.copy(), f.copy()]  # 3 identical
+    
+    sc = Scorecard(raw={}, findings=findings).canonicalize()
+    
+    # Should be 1 finding
+    assert len(sc.findings) == 1
+    assert sc.findings[0]["id"] == "A"
+
+def test_dedupe_preserves_highest_severity():
+    """If fingerprints collide (forced), keep highest severity."""
+    # This scenario is unlikely with auto-fingerprinting unless content matches,
+    # but if manually provided or if collision happens:
+    
+    # Manually force same fingerprint but different severity to test conflict resolution logic
+    fp = "same-hash"
+    f1 = {"id": "A", "severity": "minor", "fingerprint": fp}
+    f2 = {"id": "A", "severity": "critical", "fingerprint": fp} # Critical should win
+    
+    findings = [f1, f2]
+    sc = Scorecard(raw={}, findings=findings).canonicalize()
+    
+    assert len(sc.findings) == 1
+    assert sc.findings[0]["severity"] == "critical"
+
+def test_load_canonicalizes_automatically(tmp_path):
+    """Loading a scorecard should automatically canonicalize findings."""
+    data = {
+        "meta": {"tool": "test", "version": "1"},
+        "findings": [
+            {"id": "B", "severity": "minor", "message": "m"},
+            {"id": "A", "severity": "serious", "message": "m"},
+        ]
+    }
+    p = tmp_path / "test.json"
+    p.write_text(json.dumps(data))
+    
+    sc = Scorecard.load(str(p))
+    
+    # Check sort order: A (serious) then B (minor)
+    assert sc.findings[0]["id"] == "A"
+    assert sc.findings[1]["id"] == "B"
+    # Check fingerprint added
+    assert "fingerprint" in sc.findings[0]

package/src/a11y-ci/tests/test_smoke_cli.py

@@ -0,0 +1,41 @@
+"""Smoke tests for a11y-ci CLI."""
+
+from pathlib import Path
+from click.testing import CliRunner
+from a11y_ci.cli import main
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+def test_gate_pass_smoke():
+    """Gate should pass with a clean scorecard (exit 0)."""
+    runner = CliRunner()
+    result = runner.invoke(main, [
+        "gate",
+        "--current", str(FIXTURES / "current_ok.json"),
+        "--fail-on", "serious"
+    ])
+    assert result.exit_code == 0
+    assert "[OK]" in result.output
+
+def test_gate_fail_smoke():
+    """Gate should fail with findings above threshold (exit 3)."""
+    runner = CliRunner()
+    result = runner.invoke(main, [
+        "gate",
+        "--current", str(FIXTURES / "current_fail.json"),
+        "--fail-on", "serious"
+    ])
+    assert result.exit_code == 3
+    assert "[ERROR]" in result.output
+    # Ensure failure reason is clear
+    assert "Current run has" in result.output
+
+def test_gate_malformed_input():
+    """Gate should fail gracefully on malformed/missing input (exit 2)."""
+    runner = CliRunner()
+    result = runner.invoke(main, [
+        "gate",
+        "--current", "non_existent_file.json"
+    ])
+    assert result.exit_code == 2
+    assert "Invalid value for '--current'" in result.output

package/src/a11y-evidence-engine/README.md

@@ -1,3 +1,8 @@
+
+<p align="center">
+  <img src="../../assets/a11y-logo.png" alt="a11y suite logo" width="150"/>
+</p>
+
 # a11y-evidence-engine
 
 Headless accessibility evidence engine that emits [prov-spec](https://github.com/mcp-tool-shop-org/prov-spec) provenance records.

package/src/a11y-lint/README.md

@@ -1,3 +1,8 @@
+
+<p align="center">
+  <img src="../../assets/a11y-logo.png" alt="a11y suite logo" width="150"/>
+</p>
+
 # a11y-lint
 
 ![a11y](https://img.shields.io/badge/a11y-low--vision--first-blue)

package/src/a11y-lint/a11y_lint/cli.py

@@ -59,6 +59,13 @@ def main() -> None:
     help="Enable only specific rules (can be used multiple times).",
 )
 @click.option("--strict", is_flag=True, help="Treat warnings as errors.")
+@click.option(
+    "--artifact-dir",
+    "artifact_dir",
+    type=click.Path(file_okay=False, writable=True),
+    required=False,
+    help="Directory to write unified artifacts (result.json, current.scorecard.json).",
+)
 def scan(
     input: str | None,
     stdin: bool,
@@ -68,6 +75,7 @@ def scan(
     disable: tuple[str, ...],
     enable: tuple[str, ...],
     strict: bool,
+    artifact_dir: str | None,
 ) -> None:
     """Scan CLI text for accessibility issues.
 
@@ -137,6 +145,27 @@ def scan(
         renderer.write_batch(messages)
         renderer.write_summary()
 
+    # Artifact generation
+    if artifact_dir:
+        out_dir = Path(artifact_dir)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        
+        # 1. result.json (full findings)
+        result = {
+            "source": source,
+            "messages": [msg.to_dict() for msg in messages],
+            "summary": {
+                "total": len(messages),
+                "errors": scanner.error_count,
+                "warnings": scanner.warn_count,
+            },
+        }
+        (out_dir / "result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
+        
+        # 2. current.scorecard.json (for a11y-ci gate)
+        card = create_scorecard(messages, name=f"Scan: {Path(source).name}")
+        (out_dir / "current.scorecard.json").write_text(json.dumps(card.to_dict(), indent=2), encoding="utf-8")
+
     # Exit with error if issues found
     exit_code = 0
     if scanner.error_count > 0:

package/src/a11y-mcp-tools/README.md

@@ -1,3 +1,8 @@
+
+<p align="center">
+  <img src="../../assets/a11y-logo.png" alt="a11y suite logo" width="150"/>
+</p>
+
 # a11y-mcp-tools
 
 MCP (Model Context Protocol) tools for accessibility evidence capture and diagnosis.