@mcptoolshop/accessibility-suite 0.1.0

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

@@ -0,0 +1,319 @@
+"""CLI entry point for a11y-lint.
+
+Provides command-line interface for accessibility linting of CLI output.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .errors import A11yMessage
+from .render import Renderer, format_for_file
+from .scan_cli_text import Scanner, get_rule_names
+from .scorecard import create_scorecard
+from .report_md import MarkdownReporter, generate_badge_md
+from .validate import validate_json_file, MessageValidator
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="a11y-lint")
+def main() -> None:
+    """Accessibility linter for CLI output.
+
+    Validates that CLI error messages follow accessible patterns
+    with [OK]/[WARN]/[ERROR] + What/Why/Fix structure.
+    """
+    pass
+
+
+@main.command()
+@click.argument("input", type=click.Path(exists=True), required=False)
+@click.option("--stdin", is_flag=True, help="Read from stdin instead of file.")
+@click.option(
+    "--color",
+    type=click.Choice(["auto", "always", "never"]),
+    default="auto",
+    help="Color output mode: auto (respects NO_COLOR), always, or never.",
+)
+@click.option("--json", "json_output", is_flag=True, help="Output results as JSON.")
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["plain", "json", "markdown"]),
+    default="plain",
+    help="Output format.",
+)
+@click.option(
+    "--disable",
+    multiple=True,
+    help="Disable specific rules (can be used multiple times).",
+)
+@click.option(
+    "--enable",
+    multiple=True,
+    help="Enable only specific rules (can be used multiple times).",
+)
+@click.option("--strict", is_flag=True, help="Treat warnings as errors.")
+def scan(
+    input: str | None,
+    stdin: bool,
+    color: str,
+    json_output: bool,
+    output_format: str,
+    disable: tuple[str, ...],
+    enable: tuple[str, ...],
+    strict: bool,
+) -> None:
+    """Scan CLI text for accessibility issues.
+
+    Reads from a file or stdin and checks for common accessibility problems.
+
+    Examples:
+
+        a11y-lint scan output.txt
+
+        echo "ERROR: It failed" | a11y-lint scan --stdin
+
+        a11y-lint scan --format=json output.txt
+    """
+    # Get input text
+    if stdin:
+        text = sys.stdin.read()
+        source = "<stdin>"
+    elif input:
+        path = Path(input)
+        text = path.read_text(encoding="utf-8")
+        source = str(path)
+    else:
+        click.echo("Error: Must specify INPUT file or --stdin.", err=True)
+        sys.exit(1)
+
+    # Configure scanner
+    scanner = Scanner()
+
+    # Handle rule filtering
+    if enable:
+        # Enable only specified rules
+        scanner.rules = []
+        for rule_name in enable:
+            scanner.enable_rule(rule_name)
+    for rule_name in disable:
+        scanner.disable_rule(rule_name)
+
+    # Run scan
+    messages = scanner.scan_text(text, file=source)
+
+    # Handle output format
+    if json_output or output_format == "json":
+        result = {
+            "source": source,
+            "messages": [msg.to_dict() for msg in messages],
+            "summary": {
+                "total": len(messages),
+                "errors": scanner.error_count,
+                "warnings": scanner.warn_count,
+            },
+        }
+        click.echo(json.dumps(result, indent=2))
+    elif output_format == "markdown":
+        reporter = MarkdownReporter(title=f"Accessibility Report: {source}")
+        click.echo(reporter.render(messages))
+    else:
+        # Plain text output
+        # Resolve color mode: auto uses environment detection, always/never are explicit
+        color_enabled: bool | None = None  # None = auto
+        if color == "always":
+            color_enabled = True
+        elif color == "never":
+            color_enabled = False
+        # "auto" leaves it as None, which triggers should_use_color()
+
+        renderer = Renderer(color=color_enabled)
+        renderer.write_batch(messages)
+        renderer.write_summary()
+
+    # Exit with error if issues found
+    exit_code = 0
+    if scanner.error_count > 0:
+        exit_code = 1
+    elif strict and scanner.warn_count > 0:
+        exit_code = 1
+
+    sys.exit(exit_code)
+
+
+@main.command()
+@click.argument("input", type=click.Path(exists=True))
+@click.option("--verbose", "-v", is_flag=True, help="Show detailed validation errors.")
+def validate(input: str, verbose: bool) -> None:
+    """Validate a JSON file against the CLI error schema.
+
+    Checks that JSON messages conform to the ground truth schema.
+
+    Examples:
+
+        a11y-lint validate messages.json
+    """
+    path = Path(input)
+    valid_messages, errors = validate_json_file(path)
+
+    if errors:
+        click.echo(f"[ERROR] {len(errors)} validation error(s) found:", err=True)
+        if verbose:
+            for err in errors:
+                click.echo(f"  - {err}", err=True)
+        sys.exit(1)
+    else:
+        click.echo(f"[OK] {len(valid_messages)} message(s) validated successfully.")
+        sys.exit(0)
+
+
+@main.command()
+@click.argument("input", type=click.Path(exists=True), required=False)
+@click.option("--stdin", is_flag=True, help="Read from stdin instead of file.")
+@click.option("--name", default="CLI Assessment", help="Name for the scorecard.")
+@click.option("--json", "json_output", is_flag=True, help="Output as JSON.")
+@click.option("--badge", is_flag=True, help="Generate a shields.io badge markdown.")
+def scorecard(
+    input: str | None,
+    stdin: bool,
+    name: str,
+    json_output: bool,
+    badge: bool,
+) -> None:
+    """Generate an accessibility scorecard.
+
+    Creates a summary scorecard from scan results.
+
+    Examples:
+
+        a11y-lint scorecard output.txt
+
+        a11y-lint scorecard --badge output.txt
+    """
+    # Get input text
+    if stdin:
+        text = sys.stdin.read()
+        source = "<stdin>"
+    elif input:
+        path = Path(input)
+        text = path.read_text(encoding="utf-8")
+        source = str(path)
+    else:
+        click.echo("Error: Must specify INPUT file or --stdin.", err=True)
+        sys.exit(1)
+
+    # Scan and create scorecard
+    scanner = Scanner()
+    messages = scanner.scan_text(text, file=source)
+    card = create_scorecard(messages, name=name)
+
+    if json_output:
+        click.echo(json.dumps(card.to_dict(), indent=2))
+    elif badge:
+        click.echo(generate_badge_md(card.overall_score))
+    else:
+        click.echo(card.summary())
+
+    # Exit with error if not passing
+    sys.exit(0 if card.is_passing else 1)
+
+
+@main.command()
+@click.argument("input", type=click.Path(exists=True), required=False)
+@click.option("--stdin", is_flag=True, help="Read from stdin instead of file.")
+@click.option("--output", "-o", type=click.Path(), help="Output file path.")
+@click.option("--title", default="Accessibility Report", help="Report title.")
+def report(
+    input: str | None,
+    stdin: bool,
+    output: str | None,
+    title: str,
+) -> None:
+    """Generate a markdown accessibility report.
+
+    Creates a detailed markdown report from scan results.
+
+    Examples:
+
+        a11y-lint report output.txt -o report.md
+
+        a11y-lint report --stdin < cli_output.txt
+    """
+    # Get input text
+    if stdin:
+        text = sys.stdin.read()
+        source = "<stdin>"
+    elif input:
+        path = Path(input)
+        text = path.read_text(encoding="utf-8")
+        source = str(path)
+    else:
+        click.echo("Error: Must specify INPUT file or --stdin.", err=True)
+        sys.exit(1)
+
+    # Scan and generate report
+    scanner = Scanner()
+    messages = scanner.scan_text(text, file=source)
+    reporter = MarkdownReporter(title=title)
+    markdown = reporter.render(messages)
+
+    if output:
+        Path(output).write_text(markdown, encoding="utf-8")
+        click.echo(f"Report written to {output}")
+    else:
+        click.echo(markdown)
+
+    sys.exit(0 if not scanner.has_errors else 1)
+
+
+@main.command("list-rules")
+@click.option("--verbose", "-v", is_flag=True, help="Show rule categories and WCAG refs.")
+def list_rules(verbose: bool) -> None:
+    """List all available accessibility rules.
+
+    Shows the names of all rules that can be enabled/disabled.
+    Rules are categorized as:
+    - WCAG: Mapped to WCAG success criteria (accessibility violations)
+    - Policy: Best practices for cognitive accessibility
+    """
+    from .scan_cli_text import RULES, RuleCategory
+
+    if verbose:
+        click.echo("Available rules:\n")
+        click.echo("WCAG Rules (mapped to WCAG success criteria):")
+        for rule in RULES:
+            if rule.category == RuleCategory.WCAG:
+                wcag = f" [WCAG {rule.wcag_ref}]" if rule.wcag_ref else ""
+                click.echo(f"  - {rule.name}{wcag}: {rule.description}")
+
+        click.echo("\nPolicy Rules (cognitive accessibility best practices):")
+        for rule in RULES:
+            if rule.category == RuleCategory.POLICY:
+                click.echo(f"  - {rule.name}: {rule.description}")
+
+        click.echo("\nNote: Policy rules are not WCAG requirements but improve")
+        click.echo("accessibility for users with cognitive disabilities.")
+    else:
+        click.echo("Available rules:")
+        for rule in RULES:
+            click.echo(f"  - {rule.name}")
+
+
+@main.command()
+def schema() -> None:
+    """Print the CLI error JSON schema.
+
+    Outputs the ground truth schema for CLI error messages.
+    """
+    schema_path = Path(__file__).parent / "schemas" / "cli.error.schema.v0.1.json"
+    click.echo(schema_path.read_text(encoding="utf-8"))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,252 @@
+"""Ground truth error dataclasses for CLI accessibility messages.
+
+All error messages follow the What/Why/Fix structure for maximum accessibility.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class Level(Enum):
+    """Severity level of an accessibility check result."""
+
+    OK = "OK"
+    WARN = "WARN"
+    ERROR = "ERROR"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+# Pattern for valid error codes: 2-4 alphanumeric chars (starting with letter) followed by 3 digits
+# Examples: A11Y001, FMT001, CLI002, TST123
+CODE_PATTERN = re.compile(r"^[A-Z][A-Z0-9]{1,3}[0-9]{3}$")
+
+
+@dataclass(frozen=True)
+class Location:
+    """Location of an issue in the source text."""
+
+    file: str | None = None
+    line: int | None = None
+    column: int | None = None
+    context: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary, omitting None values."""
+        result: dict[str, Any] = {}
+        if self.file is not None:
+            result["file"] = self.file
+        if self.line is not None:
+            result["line"] = self.line
+        if self.column is not None:
+            result["column"] = self.column
+        if self.context is not None:
+            # Truncate context to schema max
+            result["context"] = self.context[:200]
+        return result
+
+    def __str__(self) -> str:
+        parts = []
+        if self.file:
+            parts.append(self.file)
+        if self.line is not None:
+            parts.append(f"line {self.line}")
+        if self.column is not None:
+            parts.append(f"col {self.column}")
+        return ":".join(parts) if parts else "<unknown>"
+
+
+@dataclass(frozen=True)
+class A11yMessage:
+    """An accessibility check result with What/Why/Fix structure.
+
+    Attributes:
+        level: Severity (OK, WARN, ERROR)
+        code: Unique identifier (e.g., A11Y001)
+        what: Brief description of what happened
+        why: Why this matters for accessibility (required for ERROR)
+        fix: How to fix the issue (required for ERROR)
+        location: Where the issue was found
+        rule: Name of the rule that was checked
+        metadata: Additional rule-specific data
+    """
+
+    level: Level
+    code: str
+    what: str
+    why: str | None = None
+    fix: str | None = None
+    location: Location | None = None
+    rule: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Validate the message structure."""
+        # Validate code format
+        if not CODE_PATTERN.match(self.code):
+            raise ValueError(
+                f"Invalid error code '{self.code}': must match pattern [A-Z]{{2,4}}[0-9]{{3}}"
+            )
+
+        # Validate what is not empty
+        if not self.what or not self.what.strip():
+            raise ValueError("'what' field cannot be empty")
+
+        # Truncate what to schema max
+        if len(self.what) > 200:
+            object.__setattr__(self, "what", self.what[:200])
+
+        # ERROR level requires why and fix
+        if self.level == Level.ERROR:
+            if not self.why:
+                raise ValueError("ERROR level messages must include 'why'")
+            if not self.fix:
+                raise ValueError("ERROR level messages must include 'fix'")
+
+        # Truncate why/fix to schema max
+        if self.why and len(self.why) > 500:
+            object.__setattr__(self, "why", self.why[:500])
+        if self.fix and len(self.fix) > 500:
+            object.__setattr__(self, "fix", self.fix[:500])
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary matching the JSON schema."""
+        result: dict[str, Any] = {
+            "level": self.level.value,
+            "code": self.code,
+            "what": self.what,
+        }
+
+        if self.why:
+            result["why"] = self.why
+        if self.fix:
+            result["fix"] = self.fix
+        if self.location:
+            result["location"] = self.location.to_dict()
+        if self.rule:
+            result["rule"] = self.rule
+        if self.metadata:
+            result["metadata"] = self.metadata
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> A11yMessage:
+        """Create from a dictionary (e.g., parsed JSON)."""
+        location = None
+        if "location" in data:
+            loc_data = data["location"]
+            location = Location(
+                file=loc_data.get("file"),
+                line=loc_data.get("line"),
+                column=loc_data.get("column"),
+                context=loc_data.get("context"),
+            )
+
+        return cls(
+            level=Level(data["level"]),
+            code=data["code"],
+            what=data["what"],
+            why=data.get("why"),
+            fix=data.get("fix"),
+            location=location,
+            rule=data.get("rule"),
+            metadata=data.get("metadata", {}),
+        )
+
+    @classmethod
+    def ok(
+        cls,
+        code: str,
+        what: str,
+        *,
+        rule: str | None = None,
+        location: Location | None = None,
+    ) -> A11yMessage:
+        """Create an OK (passing) check result."""
+        return cls(level=Level.OK, code=code, what=what, rule=rule, location=location)
+
+    @classmethod
+    def warn(
+        cls,
+        code: str,
+        what: str,
+        why: str,
+        *,
+        fix: str | None = None,
+        rule: str | None = None,
+        location: Location | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> A11yMessage:
+        """Create a WARN (advisory) check result."""
+        return cls(
+            level=Level.WARN,
+            code=code,
+            what=what,
+            why=why,
+            fix=fix,
+            rule=rule,
+            location=location,
+            metadata=metadata or {},
+        )
+
+    @classmethod
+    def error(
+        cls,
+        code: str,
+        what: str,
+        why: str,
+        fix: str,
+        *,
+        rule: str | None = None,
+        location: Location | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> A11yMessage:
+        """Create an ERROR (failing) check result."""
+        return cls(
+            level=Level.ERROR,
+            code=code,
+            what=what,
+            why=why,
+            fix=fix,
+            rule=rule,
+            location=location,
+            metadata=metadata or {},
+        )
+
+
+# Pre-defined error codes for common accessibility issues
+class ErrorCodes:
+    """Standard error codes for accessibility checks."""
+
+    # Structure errors (A11Y0xx)
+    MISSING_ERROR_CODE = "A11Y001"
+    MISSING_WHAT = "A11Y002"
+    MISSING_WHY = "A11Y003"
+    MISSING_FIX = "A11Y004"
+    INVALID_LEVEL = "A11Y005"
+
+    # Format errors (FMT0xx)
+    LINE_TOO_LONG = "FMT001"
+    NO_NEWLINE_END = "FMT002"
+    INCONSISTENT_INDENT = "FMT003"
+
+    # Language errors (LNG0xx)
+    JARGON_DETECTED = "LNG001"
+    ALL_CAPS_MESSAGE = "LNG002"
+    NO_PUNCTUATION = "LNG003"
+    AMBIGUOUS_PRONOUN = "LNG004"
+
+    # Color/contrast (CLR0xx)
+    COLOR_ONLY_INFO = "CLR001"
+    LOW_CONTRAST = "CLR002"
+
+    # Screen reader (SCR0xx)
+    EMOJI_OVERUSE = "SCR001"
+    UNICODE_ISSUE = "SCR002"
+    MISSING_ALT_TEXT = "SCR003"