@mcptoolshop/accessibility-suite 0.1.0

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

@@ -0,0 +1,293 @@
+"""Deterministic renderer for CLI accessibility messages.
+
+Renders messages in the canonical [OK]/[WARN]/[ERROR] + What/Why/Fix format.
+All output is deterministic and suitable for comparison/testing.
+
+Color Philosophy:
+- Colors are purely decorative; meaning NEVER depends on color
+- Default: auto (respects NO_COLOR env var and terminal detection)
+- The plain text output is always fully meaningful without colors
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TextIO
+import sys
+
+from .errors import A11yMessage, Level
+
+
+def should_use_color(stream: TextIO | None = None) -> bool:
+    """Determine if color should be used based on environment.
+
+    Respects:
+    - NO_COLOR env var (https://no-color.org/)
+    - FORCE_COLOR env var
+    - Terminal detection (isatty)
+
+    Args:
+        stream: Output stream to check (default: stdout)
+
+    Returns:
+        True if colors should be used
+    """
+    # NO_COLOR takes precedence (https://no-color.org/)
+    if os.environ.get("NO_COLOR"):
+        return False
+
+    # FORCE_COLOR overrides terminal detection
+    if os.environ.get("FORCE_COLOR"):
+        return True
+
+    # Check if stream is a TTY
+    stream = stream or sys.stdout
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+# ANSI color codes for terminal output
+class Colors:
+    """ANSI color codes for terminal rendering."""
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+
+    # Level colors
+    OK = "\033[32m"  # Green
+    WARN = "\033[33m"  # Yellow
+    ERROR = "\033[31m"  # Red
+
+    # Component colors
+    CODE = "\033[36m"  # Cyan
+    LOCATION = "\033[90m"  # Gray
+    LABEL = "\033[1m"  # Bold
+
+
+def get_level_color(level: Level) -> str:
+    """Get the ANSI color code for a level."""
+    return {
+        Level.OK: Colors.OK,
+        Level.WARN: Colors.WARN,
+        Level.ERROR: Colors.ERROR,
+    }[level]
+
+
+def render_plain(message: A11yMessage, indent: int = 0) -> str:
+    """Render a message as plain text (no colors).
+
+    This is the canonical output format that all messages must follow:
+    [LEVEL] CODE: What
+      Why: explanation
+      Fix: suggestion
+
+    Args:
+        message: The message to render
+        indent: Number of spaces to indent
+
+    Returns:
+        Plain text representation
+    """
+    prefix = " " * indent
+    lines = []
+
+    # Main line: [LEVEL] CODE: What
+    lines.append(f"{prefix}[{message.level}] {message.code}: {message.what}")
+
+    # Location (if present)
+    if message.location:
+        lines.append(f"{prefix}  at {message.location}")
+
+    # Why (if present)
+    if message.why:
+        lines.append(f"{prefix}  Why: {message.why}")
+
+    # Fix (if present)
+    if message.fix:
+        lines.append(f"{prefix}  Fix: {message.fix}")
+
+    return "\n".join(lines)
+
+
+def render_colored(message: A11yMessage, indent: int = 0) -> str:
+    """Render a message with ANSI colors for terminal display.
+
+    Args:
+        message: The message to render
+        indent: Number of spaces to indent
+
+    Returns:
+        Colored text representation
+    """
+    prefix = " " * indent
+    lines = []
+    level_color = get_level_color(message.level)
+
+    # Main line: [LEVEL] CODE: What
+    level_str = f"{level_color}{Colors.BOLD}[{message.level}]{Colors.RESET}"
+    code_str = f"{Colors.CODE}{message.code}{Colors.RESET}"
+    lines.append(f"{prefix}{level_str} {code_str}: {message.what}")
+
+    # Location (if present)
+    if message.location:
+        loc_str = f"{Colors.LOCATION}at {message.location}{Colors.RESET}"
+        lines.append(f"{prefix}  {loc_str}")
+
+    # Why (if present)
+    if message.why:
+        lines.append(f"{prefix}  {Colors.LABEL}Why:{Colors.RESET} {message.why}")
+
+    # Fix (if present)
+    if message.fix:
+        lines.append(f"{prefix}  {Colors.LABEL}Fix:{Colors.RESET} {message.fix}")
+
+    return "\n".join(lines)
+
+
+def render(
+    message: A11yMessage,
+    *,
+    color: bool = False,
+    indent: int = 0,
+) -> str:
+    """Render a message to string.
+
+    Args:
+        message: The message to render
+        color: Whether to include ANSI colors
+        indent: Number of spaces to indent
+
+    Returns:
+        String representation
+    """
+    if color:
+        return render_colored(message, indent)
+    return render_plain(message, indent)
+
+
+def render_batch(
+    messages: list[A11yMessage],
+    *,
+    color: bool = False,
+    separator: str = "\n",
+) -> str:
+    """Render multiple messages.
+
+    Args:
+        messages: Messages to render
+        color: Whether to include ANSI colors
+        separator: String between messages
+
+    Returns:
+        Combined string representation
+    """
+    return separator.join(render(msg, color=color) for msg in messages)
+
+
+class Renderer:
+    """Configurable message renderer with output stream support."""
+
+    def __init__(
+        self,
+        *,
+        color: bool | None = None,
+        stream: TextIO | None = None,
+        indent: int = 0,
+    ) -> None:
+        """Initialize the renderer.
+
+        Args:
+            color: Enable colors (None = auto-detect from terminal)
+            stream: Output stream (default: stdout)
+            indent: Base indentation level
+        """
+        self.stream = stream or sys.stdout
+        self.indent = indent
+
+        # Auto-detect color support (respects NO_COLOR env var)
+        if color is None:
+            self.color = should_use_color(self.stream)
+        else:
+            self.color = color
+
+        self._counts = {Level.OK: 0, Level.WARN: 0, Level.ERROR: 0}
+
+    def render(self, message: A11yMessage) -> str:
+        """Render a message to string."""
+        return render(message, color=self.color, indent=self.indent)
+
+    def write(self, message: A11yMessage) -> None:
+        """Render and write a message to the stream."""
+        self._counts[message.level] += 1
+        self.stream.write(self.render(message) + "\n")
+
+    def write_batch(self, messages: list[A11yMessage]) -> None:
+        """Render and write multiple messages."""
+        for msg in messages:
+            self.write(msg)
+
+    @property
+    def ok_count(self) -> int:
+        """Number of OK messages written."""
+        return self._counts[Level.OK]
+
+    @property
+    def warn_count(self) -> int:
+        """Number of WARN messages written."""
+        return self._counts[Level.WARN]
+
+    @property
+    def error_count(self) -> int:
+        """Number of ERROR messages written."""
+        return self._counts[Level.ERROR]
+
+    @property
+    def total_count(self) -> int:
+        """Total number of messages written."""
+        return sum(self._counts.values())
+
+    def summary_line(self) -> str:
+        """Get a summary line of counts."""
+        parts = []
+        if self.ok_count:
+            parts.append(f"{self.ok_count} passed")
+        if self.warn_count:
+            parts.append(f"{self.warn_count} warnings")
+        if self.error_count:
+            parts.append(f"{self.error_count} errors")
+
+        if not parts:
+            return "No issues found"
+
+        return ", ".join(parts)
+
+    def write_summary(self) -> None:
+        """Write a summary line to the stream."""
+        summary = self.summary_line()
+        if self.color:
+            # Color the summary based on worst level
+            if self.error_count:
+                summary = f"{Colors.ERROR}{summary}{Colors.RESET}"
+            elif self.warn_count:
+                summary = f"{Colors.WARN}{summary}{Colors.RESET}"
+            else:
+                summary = f"{Colors.OK}{summary}{Colors.RESET}"
+
+        self.stream.write(f"\n{summary}\n")
+
+
+def format_for_file(messages: list[A11yMessage]) -> str:
+    """Format messages for writing to a file (no colors, consistent format).
+
+    Args:
+        messages: Messages to format
+
+    Returns:
+        File-ready string
+    """
+    lines = []
+    for msg in messages:
+        lines.append(render_plain(msg))
+        lines.append("")  # Blank line between messages
+
+    return "\n".join(lines)

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

@@ -0,0 +1,289 @@
+"""Markdown report renderer for accessibility assessments.
+
+Generates detailed markdown reports from scan results and scorecards.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TextIO
+import io
+
+from .errors import A11yMessage, Level
+from .scorecard import Scorecard
+
+
+def render_message_md(message: A11yMessage) -> str:
+    """Render a single message as markdown.
+
+    Args:
+        message: Message to render
+
+    Returns:
+        Markdown string
+    """
+    # Choose emoji based on level
+    emoji = {"OK": "✅", "WARN": "⚠️", "ERROR": "❌"}[message.level.value]
+
+    lines = [f"### {emoji} [{message.level}] {message.code}: {message.what}"]
+
+    if message.location:
+        loc_parts = []
+        if message.location.file:
+            loc_parts.append(f"`{message.location.file}`")
+        if message.location.line:
+            loc_parts.append(f"line {message.location.line}")
+        if message.location.column:
+            loc_parts.append(f"col {message.location.column}")
+        if loc_parts:
+            lines.append(f"\n**Location:** {' : '.join(loc_parts)}")
+
+    if message.location and message.location.context:
+        lines.append(f"\n```\n{message.location.context}\n```")
+
+    if message.why:
+        lines.append(f"\n**Why:** {message.why}")
+
+    if message.fix:
+        lines.append(f"\n**Fix:** {message.fix}")
+
+    if message.rule:
+        lines.append(f"\n*Rule: `{message.rule}`*")
+
+    return "\n".join(lines)
+
+
+def render_scorecard_md(scorecard: Scorecard) -> str:
+    """Render a scorecard as markdown.
+
+    Args:
+        scorecard: Scorecard to render
+
+    Returns:
+        Markdown string
+    """
+    lines = [
+        f"# {scorecard.name}",
+        "",
+        f"**Overall Score:** {scorecard.overall_score:.1f}% ({scorecard.overall_grade})",
+        "",
+        "## Summary",
+        "",
+        "| Metric | Count |",
+        "|--------|-------|",
+        f"| Total Checks | {scorecard.total_checks} |",
+        f"| Passed | {scorecard.total_passed} |",
+        f"| Warnings | {scorecard.total_warnings} |",
+        f"| Errors | {scorecard.total_errors} |",
+        "",
+    ]
+
+    # Rule breakdown table
+    if scorecard.rule_scores:
+        lines.extend(
+            [
+                "## Rules",
+                "",
+                "| Rule | Score | Grade | Passed | Warnings | Errors |",
+                "|------|-------|-------|--------|----------|--------|",
+            ]
+        )
+
+        for name, score in sorted(scorecard.rule_scores.items()):
+            lines.append(
+                f"| `{name}` | {score.score:.1f}% | {score.grade} | "
+                f"{score.passed} | {score.warnings} | {score.errors} |"
+            )
+
+        lines.append("")
+
+    # Issues by level
+    errors = [m for m in scorecard.messages if m.level == Level.ERROR]
+    warnings = [m for m in scorecard.messages if m.level == Level.WARN]
+
+    if errors:
+        lines.extend(["## Errors", ""])
+        for msg in errors:
+            lines.append(render_message_md(msg))
+            lines.append("")
+
+    if warnings:
+        lines.extend(["## Warnings", ""])
+        for msg in warnings:
+            lines.append(render_message_md(msg))
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def render_report_md(
+    messages: list[A11yMessage],
+    *,
+    title: str = "Accessibility Report",
+    include_timestamp: bool = True,
+    include_summary: bool = True,
+) -> str:
+    """Render a full report as markdown.
+
+    Args:
+        messages: Messages to include
+        title: Report title
+        include_timestamp: Whether to include generation timestamp
+        include_summary: Whether to include a summary section
+
+    Returns:
+        Markdown string
+    """
+    lines = [f"# {title}", ""]
+
+    if include_timestamp:
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        lines.extend([f"*Generated: {now}*", ""])
+
+    if include_summary:
+        error_count = sum(1 for m in messages if m.level == Level.ERROR)
+        warn_count = sum(1 for m in messages if m.level == Level.WARN)
+        ok_count = sum(1 for m in messages if m.level == Level.OK)
+
+        status = "✅ Passing" if error_count == 0 else "❌ Failing"
+        lines.extend(
+            [
+                "## Summary",
+                "",
+                f"**Status:** {status}",
+                "",
+                f"- Errors: {error_count}",
+                f"- Warnings: {warn_count}",
+                f"- Passed: {ok_count}",
+                "",
+            ]
+        )
+
+    # Group messages by level
+    errors = [m for m in messages if m.level == Level.ERROR]
+    warnings = [m for m in messages if m.level == Level.WARN]
+    passed = [m for m in messages if m.level == Level.OK]
+
+    if errors:
+        lines.extend(["## Errors", ""])
+        for msg in errors:
+            lines.append(render_message_md(msg))
+            lines.append("")
+
+    if warnings:
+        lines.extend(["## Warnings", ""])
+        for msg in warnings:
+            lines.append(render_message_md(msg))
+            lines.append("")
+
+    if passed:
+        lines.extend(["## Passed", ""])
+        for msg in passed:
+            lines.append(f"- ✅ `{msg.code}`: {msg.what}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+class MarkdownReporter:
+    """Reporter for generating markdown reports with configuration."""
+
+    def __init__(
+        self,
+        *,
+        title: str = "Accessibility Report",
+        include_timestamp: bool = True,
+        include_passed: bool = False,
+    ) -> None:
+        """Initialize the reporter.
+
+        Args:
+            title: Report title
+            include_timestamp: Include generation timestamp
+            include_passed: Include passed checks in detail
+        """
+        self.title = title
+        self.include_timestamp = include_timestamp
+        self.include_passed = include_passed
+
+    def render(self, messages: list[A11yMessage]) -> str:
+        """Render messages to markdown.
+
+        Args:
+            messages: Messages to render
+
+        Returns:
+            Markdown string
+        """
+        return render_report_md(
+            messages,
+            title=self.title,
+            include_timestamp=self.include_timestamp,
+            include_summary=True,
+        )
+
+    def render_scorecard(self, scorecard: Scorecard) -> str:
+        """Render a scorecard to markdown.
+
+        Args:
+            scorecard: Scorecard to render
+
+        Returns:
+            Markdown string
+        """
+        return render_scorecard_md(scorecard)
+
+    def write(self, messages: list[A11yMessage], stream: TextIO) -> None:
+        """Write markdown report to a stream.
+
+        Args:
+            messages: Messages to render
+            stream: Output stream
+        """
+        stream.write(self.render(messages))
+
+    def write_file(self, messages: list[A11yMessage], path: str) -> None:
+        """Write markdown report to a file.
+
+        Args:
+            messages: Messages to render
+            path: Output file path
+        """
+        with open(path, "w", encoding="utf-8") as f:
+            self.write(messages, f)
+
+
+def generate_badge_md(score: float, label: str = "a11y") -> str:
+    """Generate a markdown badge showing the accessibility score.
+
+    NOTE: Badges are informational only. They do NOT imply WCAG conformance.
+    The score reflects policy compliance, not accessibility certification.
+
+    Args:
+        score: Score percentage (0-100)
+        label: Badge label
+
+    Returns:
+        Markdown image reference for shields.io badge
+    """
+    # Choose color based on score
+    if score >= 90:
+        color = "brightgreen"
+    elif score >= 70:
+        color = "yellow"
+    elif score >= 50:
+        color = "orange"
+    else:
+        color = "red"
+
+    # URL-encode the label and value
+    value = f"{score:.0f}%25"  # %25 is URL-encoded %
+    return f"![{label}](https://img.shields.io/badge/{label}-{value}-{color})"
+
+
+# Disclaimer for badges and scores
+SCORE_DISCLAIMER = (
+    "**Note:** Scores and badges are informational only. They do NOT imply "
+    "WCAG conformance or accessibility certification. This tool checks policy "
+    "rules beyond minimum WCAG requirements."
+)