@mcptoolshop/accessibility-suite 0.1.0

package/src/a11y-ci/README.md

@@ -0,0 +1,105 @@
+# a11y-ci
+
+![gate](https://img.shields.io/badge/gate-strict-blue)
+![contract](https://img.shields.io/badge/output-low--vision--first-green)
+![license](https://img.shields.io/badge/license-MIT-black)
+
+CI gate for `a11y-lint` scorecards. Low-vision-first output.
+
+## What it does
+
+- Fails if current run has findings at/above `--fail-on` (default: `serious`)
+- Optional baseline comparison:
+  - fails on serious+ count regression
+  - fails if new serious+ finding IDs appear
+- Optional allowlist with required reason + expiry
+
+## Install
+
+```bash
+pip install a11y-ci
+```
+
+## Usage
+
+### Gate (typical CI)
+
+```bash
+a11y-ci gate --current a11y.scorecard.json --baseline baseline/a11y.scorecard.json
+```
+
+### Allowlist
+
+```bash
+a11y-ci gate --current a11y.scorecard.json --baseline baseline/a11y.scorecard.json --allowlist a11y-ci.allowlist.json
+```
+
+### Fail severity
+
+```bash
+a11y-ci gate --current a11y.scorecard.json --fail-on moderate
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Pass |
+| 2 | Input/validation error |
+| 3 | Policy gate failed |
+
+## Output Contract
+
+All output follows the low-vision-first contract:
+
+```
+[OK] Title (ID: NAMESPACE.CATEGORY.DETAIL)
+
+What:
+  What happened.
+
+Why:
+  Why it happened.
+
+Fix:
+  How to fix it.
+```
+
+## Allowlist Format
+
+Allowlist entries require:
+- `finding_id`: The rule/finding ID to suppress
+- `expires`: ISO date (yyyy-mm-dd) — expired entries fail the gate
+- `reason`: Minimum 10 chars explaining the suppression
+
+```json
+{
+  "version": "1",
+  "allow": [
+    {
+      "finding_id": "CLI.COLOR.ONLY",
+      "expires": "2026-12-31",
+      "reason": "Temporary suppression for legacy output. Tracked in issue #12."
+    }
+  ]
+}
+```
+
+## GitHub Actions Example
+
+```yaml
+- name: a11y gate
+  run: |
+    a11y-lint scan output.txt --json > a11y.scorecard.json
+    a11y-ci gate --current a11y.scorecard.json --baseline baseline/a11y.scorecard.json
+```
+
+## Notes
+
+- This tool is deterministic. It does not call network services.
+- Expired allowlist entries fail the gate (no permanent exceptions).
+- Scorecards are format-tolerant: reads `summary` when present, otherwise computes from `findings`.
+
+## License
+
+MIT

package/src/a11y-ci/a11y_ci/__init__.py

@@ -0,0 +1,3 @@
+"""a11y-ci: CI gate for a11y-lint scorecards (low-vision-first)."""
+
+__version__ = "0.1.0"

package/src/a11y-ci/a11y_ci/allowlist.py

@@ -0,0 +1,83 @@
+"""Allowlist handling with schema validation and expiry checking."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import date
+from importlib import resources
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+from jsonschema import Draft202012Validator
+
+
+def _load_schema() -> Dict[str, Any]:
+    """Load the allowlist JSON schema."""
+    with resources.files("a11y_ci.schemas").joinpath("allowlist.schema.json").open("rb") as f:
+        return json.load(f)
+
+
+_SCHEMA = _load_schema()
+_VALIDATOR = Draft202012Validator(_SCHEMA)
+
+
+class AllowlistError(Exception):
+    """Raised when allowlist validation fails."""
+
+    pass
+
+
+@dataclass(frozen=True)
+class AllowlistEntry:
+    """A single allowlist entry with required fields."""
+
+    finding_id: str
+    expires: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class Allowlist:
+    """Parsed allowlist with entries."""
+
+    entries: List[AllowlistEntry]
+
+    @staticmethod
+    def load(path: str) -> "Allowlist":
+        """Load and validate an allowlist from a JSON file."""
+        obj = json.loads(Path(path).read_text(encoding="utf-8"))
+        errors = []
+        for e in sorted(_VALIDATOR.iter_errors(obj), key=lambda x: x.path):
+            loc = ".".join([str(p) for p in e.path]) or "(root)"
+            errors.append(f"{loc}: {e.message}")
+        if errors:
+            raise AllowlistError("allowlist validation failed:\n" + "\n".join(errors))
+
+        allow = obj.get("allow", [])
+        entries: List[AllowlistEntry] = []
+        for item in allow:
+            entries.append(
+                AllowlistEntry(
+                    finding_id=item["finding_id"].strip(),
+                    expires=item["expires"].strip(),
+                    reason=item["reason"].strip(),
+                )
+            )
+        return Allowlist(entries=entries)
+
+    def suppressed_ids(self) -> Set[str]:
+        """Get set of finding IDs that are suppressed."""
+        return {e.finding_id for e in self.entries}
+
+    def expired_entries(self, today: Optional[date] = None) -> List[AllowlistEntry]:
+        """Get list of entries that have expired."""
+        today = today or date.today()
+        expired: List[AllowlistEntry] = []
+        for e in self.entries:
+            # expires is ISO date yyyy-mm-dd
+            y, m, d = e.expires.split("-")
+            exp = date(int(y), int(m), int(d))
+            if exp < today:
+                expired.append(e)
+        return expired

package/src/a11y-ci/a11y_ci/cli.py

@@ -0,0 +1,145 @@
+"""CLI entry point for a11y-ci."""
+
+from __future__ import annotations
+
+import click
+
+from . import __version__
+from .allowlist import Allowlist, AllowlistError
+from .gate import gate
+from .render import CliMessage, render
+from .scorecard import Scorecard
+
+EXIT_PASS = 0
+EXIT_INPUT_ERROR = 2
+EXIT_FAIL = 3
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__)
+def main():
+    """a11y-ci: CI gate for a11y-lint scorecards."""
+    pass
+
+
+@main.command("gate")
+@click.option(
+    "--current",
+    "current_path",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False),
+    help="Path to current scorecard JSON.",
+)
+@click.option(
+    "--baseline",
+    "baseline_path",
+    required=False,
+    type=click.Path(exists=True, dir_okay=False),
+    help="Path to baseline scorecard JSON (optional).",
+)
+@click.option(
+    "--fail-on",
+    "fail_on",
+    default="serious",
+    show_default=True,
+    type=click.Choice(["info", "minor", "moderate", "serious", "critical"], case_sensitive=False),
+    help="Minimum severity to fail on.",
+)
+@click.option(
+    "--allowlist",
+    "allowlist_path",
+    required=False,
+    type=click.Path(exists=True, dir_okay=False),
+    help="Path to allowlist JSON (optional).",
+)
+def gate_cmd(
+    current_path: str,
+    baseline_path: str | None,
+    fail_on: str,
+    allowlist_path: str | None,
+):
+    """Evaluate policy gate against scorecards."""
+    try:
+        current = Scorecard.load(current_path)
+        baseline = Scorecard.load(baseline_path) if baseline_path else None
+        allowlist = Allowlist.load(allowlist_path) if allowlist_path else None
+    except AllowlistError as e:
+        msg = CliMessage(
+            status="ERROR",
+            id="A11Y.CI.ALLOWLIST.INVALID",
+            title="Allowlist is invalid",
+            what=["The allowlist file failed schema validation."],
+            why=[
+                "The allowlist must include finding_id, expires, and reason for each entry."
+            ],
+            fix=[
+                "Fix the allowlist JSON and re-run the gate.",
+                f"Details: {str(e).splitlines()[0]}",
+            ],
+        )
+        click.echo(render(msg), nl=False)
+        raise SystemExit(EXIT_INPUT_ERROR)
+    except Exception as e:
+        msg = CliMessage(
+            status="ERROR",
+            id="A11Y.CI.INPUT.INVALID",
+            title="Could not read inputs",
+            what=["One or more input files could not be parsed."],
+            why=["The scorecard JSON may be malformed or missing required fields."],
+            fix=[
+                "Verify the JSON files exist and are valid.",
+                f"Error: {type(e).__name__}: {e}",
+            ],
+        )
+        click.echo(render(msg), nl=False)
+        raise SystemExit(EXIT_INPUT_ERROR)
+
+    result = gate(current=current, baseline=baseline, fail_on=fail_on, allowlist=allowlist)
+
+    if result.ok:
+        msg = CliMessage(
+            status="OK",
+            id="A11Y.CI.GATE.PASS",
+            title="Accessibility gate passed",
+            what=["No policy violations were detected."],
+            why=["Current findings meet the configured threshold and baseline policy."],
+            fix=["Proceed with merge/release."],
+        )
+        click.echo(render(msg), nl=False)
+        raise SystemExit(EXIT_PASS)
+
+    # fail message (low-vision friendly, actionable)
+    what_lines = ["Accessibility policy violations were detected."]
+    why_lines = result.reasons[:]
+    fix_lines = [
+        "Review the current scorecard and address the listed findings.",
+        "If this is intentional, add a time-bounded allowlist entry with justification.",
+        f"Re-run: a11y-ci gate --current {current_path}"
+        + (f" --baseline {baseline_path}" if baseline_path else "")
+        + (f" --allowlist {allowlist_path}" if allowlist_path else ""),
+    ]
+
+    # Include a short list of blocking IDs in Fix for immediate control
+    if result.current_blocking_ids:
+        fix_lines.append(
+            "Blocking IDs (current): "
+            + ", ".join(result.current_blocking_ids[:12])
+            + (" ..." if len(result.current_blocking_ids) > 12 else "")
+        )
+    if result.new_blocking_ids:
+        fix_lines.append(
+            "New blocking IDs (regression): "
+            + ", ".join(result.new_blocking_ids[:12])
+            + (" ..." if len(result.new_blocking_ids) > 12 else "")
+        )
+
+    msg = CliMessage(
+        status="ERROR",
+        id="A11Y.CI.GATE.FAIL",
+        title="Accessibility gate failed",
+        what=what_lines,
+        why=why_lines if why_lines else ["Gate policy was not satisfied."],
+        fix=fix_lines,
+    )
+    click.echo(render(msg), nl=False)
+    raise SystemExit(EXIT_FAIL)

package/src/a11y-ci/a11y_ci/gate.py

@@ -0,0 +1,131 @@
+"""Core policy gate logic.
+
+Rules:
+1. Current has any findings at/above fail_on threshold -> FAIL
+2. If baseline provided, regression in count at/above threshold -> FAIL
+3. If baseline provided, new finding IDs at/above threshold -> FAIL
+4. Expired allowlist entries -> FAIL (no permanent exceptions)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Set
+
+from .allowlist import Allowlist
+from .scorecard import (
+    SEVERITY_ORDER,
+    Scorecard,
+    finding_id,
+    normalize_severity,
+    severity_ge,
+)
+
+
+@dataclass(frozen=True)
+class GateResult:
+    """Result of a gate evaluation."""
+
+    ok: bool
+    reasons: List[str]
+    current_blocking_ids: List[str]
+    new_blocking_ids: List[str]
+    current_counts: Dict[str, int]
+    baseline_counts: Optional[Dict[str, int]]
+
+
+def apply_allowlist(scorecard: Scorecard, suppressed: Set[str]) -> Scorecard:
+    """Return a new scorecard with suppressed findings removed."""
+    if not suppressed:
+        return scorecard
+    filtered = [f for f in scorecard.findings if finding_id(f) not in suppressed]
+    raw = dict(scorecard.raw)
+    raw["findings"] = filtered
+    # keep summary if present but it's now stale; recompute counts from findings downstream
+    raw.pop("summary", None)
+    return Scorecard(raw=raw, findings=filtered)
+
+
+def gate(
+    current: Scorecard,
+    baseline: Optional[Scorecard],
+    fail_on: str = "serious",
+    allowlist: Optional[Allowlist] = None,
+) -> GateResult:
+    """Evaluate the policy gate.
+
+    Args:
+        current: Current scorecard to evaluate
+        baseline: Optional baseline scorecard for regression detection
+        fail_on: Severity threshold (default: serious)
+        allowlist: Optional allowlist for suppressions
+
+    Returns:
+        GateResult with pass/fail status and reasons
+    """
+    fail_on = normalize_severity(fail_on)
+
+    suppressed: Set[str] = set()
+    reasons: List[str] = []
+
+    if allowlist:
+        suppressed = allowlist.suppressed_ids()
+        expired = allowlist.expired_entries()
+        if expired:
+            reasons.append(
+                "Allowlist contains expired entries (must be renewed or removed): "
+                + ", ".join([e.finding_id for e in expired])
+            )
+
+    cur = apply_allowlist(current, suppressed)
+    base = apply_allowlist(baseline, suppressed) if baseline else None
+
+    cur_counts = cur.counts()
+    base_counts = base.counts() if base else None
+
+    # Rule 1: current has any at/above fail_on
+    cur_blocking = cur.ids_at_or_above(fail_on)
+    if cur_blocking:
+        reasons.append(
+            f"Current run has {len(cur_blocking)} finding(s) at or above '{fail_on}'."
+        )
+
+    new_blocking: List[str] = []
+    if base:
+        # Rule 2: serious+ regression count
+        # We treat fail_on as the regression threshold too (default serious)
+        def count_at_or_above(counts: Dict[str, int], thr: str) -> int:
+            total = 0
+            for sev, n in counts.items():
+                if severity_ge(sev, thr):
+                    total += int(n)
+            return total
+
+        cur_n = count_at_or_above(cur_counts, fail_on)
+        base_n = count_at_or_above(base_counts or {}, fail_on)
+        if cur_n > base_n:
+            reasons.append(
+                f"Regression: current has {cur_n} finding(s) at/above '{fail_on}' "
+                f"vs baseline {base_n}."
+            )
+
+        # Rule 3: new blocking IDs at/above threshold
+        base_ids = set(base.ids_at_or_above(fail_on))
+        cur_ids = set(cur.ids_at_or_above(fail_on))
+        new_blocking = sorted(cur_ids - base_ids)
+        if new_blocking:
+            reasons.append(
+                f"New finding(s) at/above '{fail_on}' not present in baseline: "
+                + ", ".join(new_blocking[:20])
+                + (" ..." if len(new_blocking) > 20 else "")
+            )
+
+    ok = len([r for r in reasons if r]) == 0
+    return GateResult(
+        ok=ok,
+        reasons=reasons,
+        current_blocking_ids=cur_blocking,
+        new_blocking_ids=new_blocking,
+        current_counts=cur_counts,
+        baseline_counts=base_counts,
+    )

package/src/a11y-ci/a11y_ci/render.py

@@ -0,0 +1,48 @@
+"""Low-vision-first CLI message rendering."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Literal
+
+Status = Literal["OK", "WARN", "ERROR"]
+
+
+@dataclass(frozen=True)
+class CliMessage:
+    """Structured CLI message following the What/Why/Fix contract."""
+
+    status: Status
+    id: str
+    title: str
+    what: List[str]
+    why: List[str]
+    fix: List[str]
+
+
+def render(msg: CliMessage) -> str:
+    """Render a CLI message to the low-vision-first format.
+
+    Format:
+        [STATUS] Title (ID: NAMESPACE.CATEGORY.DETAIL)
+
+        What:
+          What happened.
+
+        Why:
+          Why it happened.
+
+        Fix:
+          How to fix it.
+    """
+    head = f"[{msg.status}] {msg.title} (ID: {msg.id})"
+    parts = [head, ""]
+    parts.append("What:")
+    parts.extend([f"  {x}" for x in msg.what])
+    parts.append("")
+    parts.append("Why:")
+    parts.extend([f"  {x}" for x in msg.why])
+    parts.append("")
+    parts.append("Fix:")
+    parts.extend([f"  {x}" for x in msg.fix])
+    return "\n".join(parts) + "\n"

package/src/a11y-ci/a11y_ci/schemas/allowlist.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mcp-tool-shop.dev/schemas/a11y-ci.allowlist.schema.json",
+  "title": "a11y-ci Allowlist",
+  "type": "object",
+  "required": ["version", "allow"],
+  "properties": {
+    "version": { "type": "string", "enum": ["1"] },
+    "allow": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["finding_id", "expires", "reason"],
+        "properties": {
+          "finding_id": { "type": "string", "minLength": 3 },
+          "expires": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
+          "reason": { "type": "string", "minLength": 10 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/a11y-ci/a11y_ci/scorecard.py

@@ -0,0 +1,99 @@
+"""Scorecard loading and severity handling.
+
+This reads a11y-lint scorecards but is defensive: it supports either:
+- summary bucket counts, and/or
+- findings[] with severity and an ID (id, rule_id, or finding_id)
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List
+
+SEVERITY_ORDER = ["info", "minor", "moderate", "serious", "critical"]
+
+
+def severity_ge(a: str, threshold: str) -> bool:
+    """Check if severity `a` is >= `threshold`."""
+    try:
+        return SEVERITY_ORDER.index(a) >= SEVERITY_ORDER.index(threshold)
+    except ValueError:
+        return False
+
+
+def normalize_severity(s: str) -> str:
+    """Normalize severity string to canonical form."""
+    s = (s or "").strip().lower()
+    if s in SEVERITY_ORDER:
+        return s
+    # tolerate common alternates
+    if s == "warning":
+        return "moderate"
+    if s == "error":
+        return "serious"
+    return "info"
+
+
+def finding_id(f: Dict[str, Any]) -> str:
+    """Extract finding ID from a finding dict, tolerating different key names."""
+    for k in ("id", "rule_id", "finding_id", "code"):
+        v = f.get(k)
+        if isinstance(v, str) and v.strip():
+            return v.strip()
+    # fallback: deterministic-ish
+    title = f.get("title") or f.get("message") or "unknown"
+    return f"UNKNOWN:{str(title)[:80]}"
+
+
+@dataclass(frozen=True)
+class Scorecard:
+    """Parsed scorecard with findings and computed counts."""
+
+    raw: Dict[str, Any]
+    findings: List[Dict[str, Any]]
+
+    @staticmethod
+    def load(path: str) -> "Scorecard":
+        """Load a scorecard from a JSON file."""
+        p = Path(path)
+        obj = json.loads(p.read_text(encoding="utf-8"))
+        findings = obj.get("findings") or []
+        if not isinstance(findings, list):
+            findings = []
+        # normalize severities
+        for f in findings:
+            if isinstance(f, dict):
+                f["severity"] = normalize_severity(str(f.get("severity", "info")))
+        return Scorecard(raw=obj, findings=[f for f in findings if isinstance(f, dict)])
+
+    def counts(self) -> Dict[str, int]:
+        """Get severity counts. Prefers summary if present; otherwise computes from findings."""
+        s = self.raw.get("summary")
+        if isinstance(s, dict) and all(k in s for k in SEVERITY_ORDER):
+            out = {k: int(s.get(k, 0) or 0) for k in SEVERITY_ORDER}
+            return out
+        out = {k: 0 for k in SEVERITY_ORDER}
+        for f in self.findings:
+            out[normalize_severity(str(f.get("severity")))] += 1
+        return out
+
+    def ids_at_or_above(self, threshold: str) -> List[str]:
+        """Get sorted list of finding IDs at or above severity threshold."""
+        thr = normalize_severity(threshold)
+        ids = []
+        for f in self.findings:
+            sev = normalize_severity(str(f.get("severity")))
+            if severity_ge(sev, thr):
+                ids.append(finding_id(f))
+        return sorted(set(ids))
+
+    def findings_at_or_above(self, threshold: str) -> List[Dict[str, Any]]:
+        """Get findings at or above severity threshold."""
+        thr = normalize_severity(threshold)
+        return [
+            f
+            for f in self.findings
+            if severity_ge(normalize_severity(str(f.get("severity"))), thr)
+        ]

package/src/a11y-ci/npm/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mcptoolshop/a11y-ci",
+  "version": "0.2.1",
+  "description": "npm wrapper for a11y-ci - CI gate for accessibility scorecards",
+  "bin": {
+    "a11y-ci": "./bin/a11y-ci.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "ci",
+    "testing",
+    "wcag",
+    "python",
+    "wrapper"
+  ],
+  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcp-tool-shop-org/accessibility-suite.git",
+    "directory": "src/a11y-ci/npm"
+  },
+  "homepage": "https://github.com/mcp-tool-shop-org/accessibility-suite#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}