reporails-cli 0.0.1__py3-none-any.whl

reporails_cli/formatters/text/chars.py

@@ -0,0 +1,42 @@
+"""Character sets for terminal output.
+
+Provides Unicode and ASCII character sets for box drawing and icons.
+"""
+
+from __future__ import annotations
+
+import os
+
+# ASCII mode: set AILS_ASCII=1 or pass ascii=True to format functions
+ASCII_MODE = os.environ.get("AILS_ASCII", "").lower() in ("1", "true", "yes")
+
+# Character sets for box drawing
+UNICODE_CHARS = {
+    "tl": "╔", "tr": "╗", "bl": "╚", "br": "╝",
+    "h": "═", "v": "║",
+    "filled": "▓", "empty": "░",
+    "check": "✓", "crit": "▲", "high": "!", "med": "○", "low": "·",
+    "up": "↑", "down": "↓", "sep": "─",
+}
+
+ASCII_CHARS = {
+    "tl": "+", "tr": "+", "bl": "+", "br": "+",
+    "h": "-", "v": "|",
+    "filled": "#", "empty": ".",
+    "check": "*", "crit": "!", "high": "!", "med": "o", "low": "-",
+    "up": "^", "down": "v", "sep": "-",
+}
+
+
+def get_chars(ascii_mode: bool | None = None) -> dict[str, str]:
+    """Get character set based on mode.
+
+    Args:
+        ascii_mode: Force ASCII mode. If None, uses AILS_ASCII env var.
+
+    Returns:
+        Character set dictionary
+    """
+    if ascii_mode is None:
+        ascii_mode = ASCII_MODE
+    return ASCII_CHARS if ascii_mode else UNICODE_CHARS

reporails_cli/formatters/text/compact.py

@@ -0,0 +1,119 @@
+"""Compact terminal output formatter.
+
+Provides minimal output for non-TTY contexts and quick checks.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reporails_cli.core.models import ScanDelta, ValidationResult
+from reporails_cli.core.scorer import LEVEL_LABELS
+from reporails_cli.formatters import json as json_formatter
+from reporails_cli.formatters.text.chars import get_chars
+from reporails_cli.formatters.text.components import (
+    format_legend,
+    format_level_delta,
+    format_score_delta,
+    format_violations_delta,
+    get_severity_icons,
+    normalize_path,
+)
+
+
+def format_compact(
+    result: ValidationResult,
+    ascii_mode: bool | None = None,
+    show_legend: bool = True,
+    delta: ScanDelta | None = None,
+) -> str:
+    """Format validation result in compact form for Claude Code / non-TTY."""
+    data = json_formatter.format_result(result, delta)
+    chars = get_chars(ascii_mode)
+    lines = []
+
+    score = data.get("score", 0.0)
+    level = data.get("level", "L1")
+    level_label = LEVEL_LABELS.get(result.level, "Unknown")
+    violations = data.get("violations", [])
+    is_partial = data.get("is_partial", True)
+
+    # Group and dedupe violations
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for v in violations:
+        location = v.get("location", "")
+        file_path = location.rsplit(":", 1)[0] if ":" in location else location
+        if file_path not in grouped:
+            grouped[file_path] = []
+        grouped[file_path].append(v)
+
+    deduped_count = 0
+    deduped_grouped: dict[str, list[dict[str, Any]]] = {}
+    for file_path, file_violations in grouped.items():
+        seen: set[str] = set()
+        unique = [v for v in file_violations if not (v.get("rule_id", "") in seen or seen.add(v.get("rule_id", "")))]  # type: ignore[func-returns-value]
+        deduped_grouped[file_path] = unique
+        deduped_count += len(unique)
+
+    # Header line with delta indicators
+    score_delta_str = format_score_delta(delta, ascii_mode)
+    level_delta_str = format_level_delta(delta, ascii_mode)
+    violations_delta_str = format_violations_delta(delta, ascii_mode) if deduped_count > 0 else ""
+    partial_marker = " (partial)" if is_partial else ""
+    if deduped_count > 0:
+        lines.append(f"Score: {score:.1f}/10{score_delta_str} ({level_label} ({level}){level_delta_str}){partial_marker} - {deduped_count} violations{violations_delta_str}")
+    else:
+        lines.append(f"Score: {score:.1f}/10{score_delta_str} ({level_label} ({level}){level_delta_str}){partial_marker} {chars['check']} clean")
+        return "\n".join(lines)
+
+    lines.append("")
+
+    severity_icons = get_severity_icons(chars)
+
+    for file_path, unique in deduped_grouped.items():
+        display_path = normalize_path(file_path)
+        lines.append(f"{display_path}:")
+        for v in unique:
+            sev = v.get("severity", "medium")
+            icon = severity_icons.get(sev, "?")
+            rule_id = v.get("rule_id", "?")
+            check_id = v.get("check_id")
+            display_id = f"{rule_id}.{check_id}" if check_id else rule_id
+            msg = v.get("message", "")
+            location = v.get("location", "")
+            line_num = location.rsplit(":", 1)[-1] if ":" in location else "?"
+            if len(msg) > 45:
+                msg = msg[:42] + "..."
+            lines.append(f"  {icon} {display_id}:{line_num} {msg}")
+        lines.append("")
+
+    # Pending semantic
+    if result.pending_semantic and result.is_partial:
+        ps = result.pending_semantic
+        lines.append(f"Pending: {ps.rule_count} semantic rules ({', '.join(ps.rules)})")
+        lines.append("")
+
+    # Friction
+    friction = data.get("friction", "none")
+    friction_level = friction if isinstance(friction, str) else friction.get("level", "none")
+    if friction_level != "none":
+        lines.append(f"Friction: {friction_level.title()}")
+        lines.append("")
+
+    # Legend footer
+    if deduped_count > 0 and show_legend:
+        lines.append(format_legend(ascii_mode))
+
+    return "\n".join(lines).rstrip()
+
+
+def format_score(result: ValidationResult, ascii_mode: bool | None = None) -> str:
+    """Format quick score summary for terminal."""
+    level_label = LEVEL_LABELS.get(result.level, "Unknown")
+    violation_count = len(result.violations)
+    partial = " (partial)" if result.is_partial else ""
+
+    if violation_count == 0:
+        return f"ails: {result.score:.1f}/10 {level_label} ({result.level.value}){partial}"
+    else:
+        return f"ails: {result.score:.1f}/10 {level_label} ({result.level.value}){partial} - {violation_count} violations"

reporails_cli/formatters/text/components.py

@@ -0,0 +1,117 @@
+"""Reusable components for terminal output.
+
+Small helper functions used by both full and compact formatters.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+
+from reporails_cli.core.models import ScanDelta
+from reporails_cli.formatters.text.chars import get_chars
+from reporails_cli.templates import render
+
+
+def format_legend(ascii_mode: bool | None = None) -> str:
+    """Format severity legend for display."""
+    chars = get_chars(ascii_mode)
+    return render("cli_legend.txt",
+        crit=chars["crit"],
+        high=chars["high"],
+        med=chars["med"],
+        low=chars["low"],
+    )
+
+
+def normalize_path(file_path: str, max_len: int = 50) -> str:
+    """Normalize file path for display.
+
+    Converts absolute paths to relative and truncates long paths.
+    """
+    if file_path.startswith("/"):
+        with contextlib.suppress(ValueError):
+            file_path = os.path.relpath(file_path)
+
+    if len(file_path) <= max_len:
+        return file_path
+
+    parts = file_path.split("/")
+    if len(parts) > 3:
+        return ".../" + "/".join(parts[-3:])
+    return file_path
+
+
+def build_score_bar(score: float, ascii_mode: bool | None = None) -> str:
+    """Build visual score bar for 0-10 scale."""
+    chars = get_chars(ascii_mode)
+    bar_width = 50
+    filled = int((score / 10) * bar_width)
+    filled = min(filled, bar_width)
+    return chars["filled"] * filled + chars["empty"] * (bar_width - filled)
+
+
+def format_score_delta(delta: ScanDelta | None, ascii_mode: bool | None = None) -> str:
+    """Format score delta indicator."""
+    if delta is None or delta.score_delta is None:
+        return ""
+    chars = get_chars(ascii_mode)
+    if delta.score_delta > 0:
+        return f"  {chars['up']} +{delta.score_delta:.1f}"
+    else:
+        return f"  {chars['down']} {delta.score_delta:.1f}"
+
+
+def format_level_delta(delta: ScanDelta | None, ascii_mode: bool | None = None) -> str:
+    """Format level delta indicator."""
+    if delta is None or delta.level_previous is None:
+        return ""
+    chars = get_chars(ascii_mode)
+    if delta.level_improved:
+        return f"  {chars['up']} from {delta.level_previous}"
+    else:
+        return f"  {chars['down']} from {delta.level_previous}"
+
+
+def format_violations_delta(delta: ScanDelta | None, ascii_mode: bool | None = None) -> str:
+    """Format violations delta indicator."""
+    if delta is None or delta.violations_delta is None:
+        return ""
+    chars = get_chars(ascii_mode)
+    if delta.violations_delta < 0:
+        # Decreased = good
+        return f"  {chars['down']} {delta.violations_delta}"
+    else:
+        # Increased = bad
+        return f"  {chars['up']} +{delta.violations_delta}"
+
+
+def pad_line(content: str, width: int, v_char: str) -> str:
+    """Pad content to fit box width.
+
+    Content goes between vertical bars with padding.
+    """
+    inner = f"   {content}"
+    if len(inner) > width - 3:
+        inner = inner[: width - 6] + "..."
+    return f"{v_char}{inner.ljust(width)}{v_char}"
+
+
+def get_severity_label(severity: str, chars: dict[str, str]) -> str:
+    """Get formatted severity label with icon."""
+    return {
+        "critical": f"{chars['crit']} CRIT",
+        "high": f"{chars['high']} HIGH",
+        "medium": f"{chars['med']} MED",
+        "low": f"{chars['low']} LOW",
+    }.get(severity, "???")
+
+
+def get_severity_icons(chars: dict[str, str]) -> dict[str, str]:
+    """Get severity icon mapping."""
+    return {
+        "critical": chars["crit"],
+        "high": chars["high"],
+        "medium": chars["med"],
+        "low": chars["low"],
+    }

reporails_cli/formatters/text/full.py

@@ -0,0 +1,135 @@
+"""Full terminal output formatter.
+
+Provides rich, detailed output for interactive terminal use.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reporails_cli.core.models import ScanDelta, ValidationResult
+from reporails_cli.formatters import json as json_formatter
+from reporails_cli.formatters.text.box import format_assessment_box
+from reporails_cli.formatters.text.chars import get_chars
+from reporails_cli.formatters.text.components import format_legend
+from reporails_cli.formatters.text.violations import format_violations_section
+from reporails_cli.templates import render
+
+
+def _format_working_section(
+    violations: list[dict[str, Any]],
+    rules_passed: int,
+    ascii_mode: bool | None = None,
+) -> str:
+    """Format 'What's working well' section."""
+    if rules_passed <= 0:
+        return ""
+
+    chars = get_chars(ascii_mode)
+
+    # Find categories with violations
+    violation_categories: set[str] = set()
+    for v in violations:
+        rule_id = v.get("rule_id", "")
+        if rule_id:
+            violation_categories.add(rule_id[0])
+
+    all_categories = {
+        "S": "Structure", "C": "Content", "E": "Efficiency",
+        "M": "Maintenance", "G": "Governance",
+    }
+    passing_categories = [
+        name for code, name in all_categories.items() if code not in violation_categories
+    ]
+
+    if not passing_categories:
+        return ""
+
+    items = "\n".join(f"  {chars['check']} {cat}" for cat in passing_categories)
+    return render("cli_working.txt", items=items)
+
+
+def _format_pending_section(
+    result: ValidationResult,
+    quiet_semantic: bool = False,
+) -> str:
+    """Format pending semantic evaluation section."""
+    if quiet_semantic or not result.pending_semantic:
+        return ""
+
+    ps = result.pending_semantic
+    return render("cli_pending.txt",
+        rule_count=ps.rule_count,
+        file_count=ps.file_count,
+        rule_list=", ".join(ps.rules),
+    )
+
+
+def _format_cta(
+    result: ValidationResult,
+    ascii_mode: bool | None = None,
+) -> str:
+    """Format MCP call-to-action for partial evaluation."""
+    if not result.is_partial:
+        return ""
+
+    chars = get_chars(ascii_mode)
+    separator = chars["sep"] * 64
+    return render("cli_cta.txt", separator=separator)
+
+
+def format_result(
+    result: ValidationResult,
+    ascii_mode: bool | None = None,
+    quiet_semantic: bool = False,
+    show_legend: bool = True,
+    delta: ScanDelta | None = None,
+    show_mcp_cta: bool = True,
+) -> str:
+    """Format validation result for terminal output."""
+    data = json_formatter.format_result(result, delta)
+
+    summary_info = data.get("summary", {})
+    rules_passed = summary_info.get("rules_passed", 0)
+    violations = data.get("violations", [])
+    friction = data.get("friction", {})
+
+    sections = []
+
+    # Assessment box
+    sections.append(format_assessment_box(data, ascii_mode, delta))
+    sections.append("")
+
+    # What's working well
+    working = _format_working_section(violations, rules_passed, ascii_mode)
+    if working:
+        sections.append(working)
+        sections.append("")
+
+    # Violations
+    sections.append(format_violations_section(violations, ascii_mode))
+
+    # Pending semantic
+    pending = _format_pending_section(result, quiet_semantic)
+    if pending:
+        sections.append(pending)
+        sections.append("")
+
+    # Friction estimate
+    friction_level = friction if isinstance(friction, str) else friction.get("level", "none")
+    if friction_level != "none":
+        sections.append(f"Friction: {friction_level.title()}")
+
+    # MCP CTA (only if partial, not quiet, and CTA enabled)
+    if show_mcp_cta and result.is_partial and not quiet_semantic:
+        cta = _format_cta(result, ascii_mode)
+        if cta:
+            sections.append("")
+            sections.append(cta)
+
+    # Legend footer
+    if violations and show_legend:
+        sections.append("")
+        sections.append(format_legend(ascii_mode))
+
+    return "\n".join(sections)

reporails_cli/formatters/text/rules.py

@@ -0,0 +1,50 @@
+"""Rule explanation formatting.
+
+Handles formatting rule details for `ails explain` command.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def format_rule(rule_id: str, rule_data: dict[str, Any]) -> str:
+    """Format rule explanation for terminal."""
+    lines = []
+
+    lines.append(f"Rule: {rule_id}")
+    lines.append("=" * 60)
+    lines.append("")
+
+    if rule_data.get("title"):
+        lines.append(f"Title: {rule_data['title']}")
+    if rule_data.get("category"):
+        lines.append(f"Category: {rule_data['category']}")
+    if rule_data.get("type"):
+        lines.append(f"Type: {rule_data['type']}")
+    if rule_data.get("level"):
+        lines.append(f"Required Level: {rule_data['level']}")
+
+    lines.append("")
+
+    if rule_data.get("description"):
+        lines.append("Description:")
+        lines.append(f"  {rule_data['description']}")
+        lines.append("")
+
+    # Support both checks and legacy antipatterns
+    checks = rule_data.get("checks", rule_data.get("antipatterns", []))
+    if checks:
+        lines.append("Checks:")
+        for check in checks:
+            lines.append(f"  - {check.get('id', '?')}: {check.get('name', 'Unknown')}")
+            lines.append(f"    Severity: {check.get('severity', 'medium')}")
+        lines.append("")
+
+    see_also = rule_data.get("see_also", [])
+    if see_also:
+        lines.append("See Also:")
+        for ref in see_also:
+            lines.append(f"  - {ref}")
+
+    return "\n".join(lines)

reporails_cli/formatters/text/violations.py

@@ -0,0 +1,92 @@
+"""Violations section formatting.
+
+Handles grouping, sorting, and rendering of violations.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reporails_cli.formatters.text.chars import get_chars
+from reporails_cli.formatters.text.components import get_severity_label, normalize_path
+from reporails_cli.templates import render
+
+
+def format_violations_section(
+    violations: list[dict[str, Any]],
+    ascii_mode: bool | None = None,
+) -> str:
+    """Format violations section grouped by file."""
+    if not violations:
+        return "No violations found."
+
+    chars = get_chars(ascii_mode)
+    lines = ["Violations:", "-" * 60]
+
+    # Group by file
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for v in violations:
+        location = v.get("location", "")
+        file_path = location.rsplit(":", 1)[0] if ":" in location else location
+        if file_path not in grouped:
+            grouped[file_path] = []
+        grouped[file_path].append(v)
+
+    # Sort files by worst severity
+    def file_sort_key(item: tuple[str, list[dict[str, Any]]]) -> tuple[int, int]:
+        file_violations = item[1]
+        severity_weights = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+        worst_severity = min(
+            severity_weights.get(v.get("severity", "low"), 3) for v in file_violations
+        )
+        return (worst_severity, -len(file_violations))
+
+    sorted_files = sorted(grouped.items(), key=file_sort_key)
+    severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+
+    for file_path, file_violations in sorted_files:
+        display_path = normalize_path(file_path)
+
+        # Deduplicate by rule_id within file
+        seen_rules: set[str] = set()
+        unique_violations: list[dict[str, Any]] = []
+        for v in file_violations:
+            rule_id = v.get("rule_id", "")
+            if rule_id not in seen_rules:
+                seen_rules.add(rule_id)
+                unique_violations.append(v)
+
+        issue_word = "issue" if len(unique_violations) == 1 else "issues"
+        lines.append(render("cli_file_header.txt",
+            filepath=display_path,
+            count=len(unique_violations),
+            issue_word=issue_word,
+        ))
+
+        sorted_violations = sorted(
+            unique_violations,
+            key=lambda v: (severity_order.get(v.get("severity", ""), 9), v.get("location", "")),
+        )
+
+        for v in sorted_violations:
+            severity_label = get_severity_label(v.get("severity", ""), chars)
+            location = v.get("location", "")
+            line_num = location.rsplit(":", 1)[-1] if ":" in location else "?"
+            msg = v.get("message", "")
+            max_msg_len = 48
+            if len(msg) > max_msg_len:
+                msg = msg[: max_msg_len - 3] + "..."
+            rule_id = v.get("rule_id", "")
+            check_id = v.get("check_id")
+            display_id = f"{rule_id}.{check_id}" if check_id else rule_id
+
+            lines.append(render("cli_violation.txt",
+                icon=severity_label,
+                rule_id=display_id,
+                line=line_num,
+                message=msg,
+            ))
+
+        lines.append("")
+
+    return "\n".join(lines)

reporails_cli/interfaces/__init__.py

@@ -0,0 +1 @@
+"""Interface adapters for reporails (CLI, MCP)."""

reporails_cli/interfaces/cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI interface for reporails."""
+
+from __future__ import annotations
+
+from reporails_cli.interfaces.cli.main import app
+
+__all__ = ["app"]