reporails-cli 0.0.1__py3-none-any.whl

reporails_cli/core/semantic.py

@@ -0,0 +1,193 @@
+"""Semantic rule request building - creates JudgmentRequests for LLM evaluation.
+
+Semantic rules require OpenGrep pattern matches before LLM evaluation.
+No match = rule passes (nothing to evaluate).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from reporails_cli.core.models import JudgmentRequest, Rule, RuleType, Severity
+from reporails_cli.core.sarif import extract_rule_id, get_location
+
+
+def build_semantic_requests(
+    sarif: dict[str, Any],
+    rules: dict[str, Rule],
+    target: Path,
+) -> list[JudgmentRequest]:
+    requests: list[JudgmentRequest] = []
+    semantic_rules = {k: v for k, v in rules.items() if v.type == RuleType.SEMANTIC}
+
+    if not semantic_rules:
+        return requests
+
+    for run in sarif.get("runs", []):
+        for result in run.get("results", []):
+            sarif_rule_id = result.get("ruleId", "")
+            rule_id = extract_rule_id(sarif_rule_id)
+            location = get_location(result)
+
+            rule = semantic_rules.get(rule_id)
+            if not rule:
+                continue
+
+            # Extract snippet from SARIF (not whole file!)
+            snippet = extract_snippet(result, target)
+            if not snippet:
+                continue
+
+            request = build_request(rule, snippet, location)
+            if request:
+                requests.append(request)
+
+    return requests
+
+
+def extract_snippet(result: dict[str, Any], target: Path) -> str | None:
+    """Extract matched content snippet from SARIF result.
+
+    SARIF provides the matched region. Use that instead of reading whole file.
+    Falls back to context lines around match if snippet not in SARIF.
+    """
+    # Try to get snippet from SARIF
+    locations = result.get("locations", [])
+    if locations:
+        physical = locations[0].get("physicalLocation", {})
+        region = physical.get("region", {})
+
+        # SARIF may include the snippet directly
+        snippet = region.get("snippet", {}).get("text")
+        if snippet:
+            return snippet
+
+    # Fallback: read lines around the match
+    location = get_location(result)
+    if ":" not in location:
+        return None
+
+    file_path, line_str = location.rsplit(":", 1)
+    try:
+        line_num = int(line_str)
+    except ValueError:
+        return None
+
+    full_path = target / file_path
+    try:
+        lines = full_path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+    # Get 5 lines of context (2 before, match, 2 after)
+    start = max(0, line_num - 3)
+    end = min(len(lines), line_num + 2)
+    context_lines = lines[start:end]
+
+    return "\n".join(context_lines)
+
+
+def build_request(
+    rule: Rule,
+    content: str,
+    location: str,
+) -> JudgmentRequest | None:
+    """Build a single JudgmentRequest from a rule.
+
+    Args:
+        rule: Semantic rule definition
+        content: File content to evaluate
+        location: File path for location
+
+    Returns:
+        JudgmentRequest, or None if rule lacks required fields
+    """
+    if not rule.question:
+        return None
+
+    # Parse criteria
+    criteria = _parse_criteria(rule.criteria)
+
+    # Parse choices
+    choices = _parse_choices(rule.choices)
+
+    # Get examples
+    examples = rule.examples or {"good": [], "bad": []}
+    if not isinstance(examples, dict):
+        examples = {"good": [], "bad": []}
+
+    # Get pass value
+    pass_value = rule.pass_value or "pass"
+
+    # Get severity from first check, or default
+    severity = Severity.MEDIUM
+    if rule.checks:
+        severity = rule.checks[0].severity
+
+    return JudgmentRequest(
+        rule_id=rule.id,
+        rule_title=rule.title,
+        content=content,
+        location=location,
+        question=rule.question,
+        criteria=criteria,
+        examples=examples,
+        choices=choices,
+        pass_value=pass_value,
+        severity=severity,
+        points_if_fail=-10,  # Default penalty
+    )
+
+
+def _parse_criteria(criteria: list[dict[str, str]] | str | None) -> dict[str, str]:
+    """Parse criteria field to dict format.
+
+    Args:
+        criteria: Criteria in various formats
+
+    Returns:
+        Dict mapping criterion key to check description
+    """
+    if criteria is None:
+        return {"pass_condition": "Evaluate based on context"}
+
+    if isinstance(criteria, str):
+        return {"pass_condition": criteria}
+
+    if isinstance(criteria, list):
+        result: dict[str, str] = {}
+        for item in criteria:
+            if isinstance(item, dict):
+                key = item.get("key", f"criterion_{len(result)}")
+                check = item.get("check", str(item))
+                result[key] = check
+        return result if result else {"pass_condition": "Evaluate based on context"}
+
+    return {"pass_condition": "Evaluate based on context"}
+
+
+def _parse_choices(choices: list[dict[str, str]] | list[str] | None) -> list[str]:
+    """Parse choices field to list format.
+
+    Args:
+        choices: Choices in various formats
+
+    Returns:
+        List of choice values
+    """
+    if choices is None:
+        return ["pass", "fail"]
+
+    if not choices:
+        return ["pass", "fail"]
+
+    result: list[str] = []
+    for choice in choices:
+        if isinstance(choice, dict):
+            value = choice.get("value", str(choice))
+            result.append(str(value))
+        else:
+            result.append(str(choice))
+
+    return result if result else ["pass", "fail"]

reporails_cli/core/utils.py

@@ -0,0 +1,139 @@
+"""Shared utility functions used across modules.
+
+All functions are pure (no I/O) except where noted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def parse_frontmatter(content: str) -> dict[str, Any]:
+    """Parse YAML frontmatter from markdown content.
+
+    Pure function — no I/O.
+
+    Args:
+        content: Markdown file content
+
+    Returns:
+        Parsed frontmatter dict
+
+    Raises:
+        ValueError: If frontmatter missing or invalid
+    """
+    # Match YAML frontmatter between --- delimiters
+    pattern = r"^---\s*\n(.*?)---\s*\n"
+    match = re.match(pattern, content, re.DOTALL)
+
+    if not match:
+        msg = "No frontmatter found"
+        raise ValueError(msg)
+
+    yaml_content = match.group(1)
+    try:
+        return yaml.safe_load(yaml_content) or {}
+    except yaml.YAMLError as e:
+        msg = f"Invalid YAML in frontmatter: {e}"
+        raise ValueError(msg) from e
+
+
+def compute_content_hash(file_path: Path) -> str:
+    """Compute SHA256 hash of file content.
+
+    I/O function — reads file.
+
+    Args:
+        file_path: Path to file
+
+    Returns:
+        Hash string in format "sha256:{hash16}"
+    """
+    content = file_path.read_bytes()
+    return f"sha256:{hashlib.sha256(content).hexdigest()[:16]}"
+
+
+def is_valid_path_reference(path: str) -> bool:
+    """Check if a string looks like a valid file path reference.
+
+    Pure function.
+
+    Args:
+        path: Potential path string
+
+    Returns:
+        True if it looks like a valid path reference
+    """
+    # Must have at least one slash or dot
+    if "/" not in path and "." not in path:
+        return False
+
+    # Filter out URLs
+    if path.startswith("http://") or path.startswith("https://"):
+        return False
+
+    # Reject path traversal attempts (../../../etc)
+    if path.count("..") > 2:
+        return False
+
+    # Reject absolute paths outside project
+    if path.startswith("/") and not path.startswith("./"):
+        return False
+
+    # Filter out common false positives
+    false_positives = {"e.g.", "i.e.", "etc.", "vs.", "v1", "v2"}
+    return path.lower() not in false_positives
+
+
+def relative_to_safe(path: Path, base: Path) -> str:
+    """Get relative path safely, with fallback to absolute.
+
+    Pure function.
+
+    Args:
+        path: Path to convert
+        base: Base directory
+
+    Returns:
+        Relative path string, or absolute if not relative to base
+    """
+    try:
+        return str(path.relative_to(base))
+    except ValueError:
+        return str(path)
+
+
+def normalize_rule_id(rule_id: str) -> str:
+    """Normalize rule ID to uppercase.
+
+    Pure function.
+
+    Args:
+        rule_id: Raw rule ID
+
+    Returns:
+        Uppercase rule ID
+    """
+    return rule_id.upper()
+
+
+def extract_body_content(markdown: str) -> str:
+    """Extract content after frontmatter from markdown.
+
+    Pure function.
+
+    Args:
+        markdown: Full markdown content
+
+    Returns:
+        Content after frontmatter (or full content if no frontmatter)
+    """
+    parts = markdown.split("---", 2)
+    if len(parts) >= 3:
+        return parts[2].strip()
+    return markdown.strip()

reporails_cli/formatters/__init__.py

@@ -0,0 +1,19 @@
+"""Output formatters for reporails.
+
+Each formatter implements the same interface:
+- format_result(result: ValidationResult) -> T
+- format_score(result: ValidationResult) -> T
+- format_rule(rule_id: str, rule_data: dict) -> T
+
+Where T is dict for json/mcp, str for text.
+"""
+
+from __future__ import annotations
+
+from reporails_cli.formatters import json, mcp, text
+
+__all__ = [
+    "json",
+    "mcp",
+    "text",
+]

reporails_cli/formatters/json.py

@@ -0,0 +1,137 @@
+"""Canonical JSON serialization for ValidationResult.
+
+This is the single source of truth for serializing validation results.
+All other formatters consume this format internally.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reporails_cli.core.models import PendingSemantic, ScanDelta, ValidationResult
+from reporails_cli.core.scorer import LEVEL_LABELS
+
+
+def _format_pending_semantic(pending: PendingSemantic | None) -> dict[str, Any] | None:
+    """Format pending semantic rules for JSON output."""
+    if pending is None:
+        return None
+    return {
+        "rule_count": pending.rule_count,
+        "file_count": pending.file_count,
+        "rules": list(pending.rules),
+    }
+
+
+def format_result(
+    result: ValidationResult,
+    delta: ScanDelta | None = None,
+) -> dict[str, Any]:
+    """Convert ValidationResult to canonical dict format.
+
+    This is the single source of truth for result serialization.
+
+    Args:
+        result: ValidationResult from engine
+        delta: Optional ScanDelta for comparison with previous run
+
+    Returns:
+        Canonical dict representation
+    """
+    data: dict[str, Any] = {
+        "score": result.score,
+        "level": result.level.value,
+        "capability": LEVEL_LABELS.get(result.level, "Unknown"),
+        "feature_summary": result.feature_summary,
+        "summary": {
+            "rules_checked": result.rules_checked,
+            "rules_passed": result.rules_passed,
+            "rules_failed": result.rules_failed,
+        },
+        "violations": [
+            {
+                "rule_id": v.rule_id,
+                "rule_title": v.rule_title,
+                "location": v.location,
+                "message": v.message,
+                "severity": v.severity.value,
+                "check_id": v.check_id,
+            }
+            for v in result.violations
+        ],
+        "judgment_requests": [
+            {
+                "rule_id": jr.rule_id,
+                "rule_title": jr.rule_title,
+                "question": jr.question,
+                "location": jr.location,
+                "criteria": jr.criteria,
+                "examples": jr.examples,
+                "choices": jr.choices,
+                "pass_value": jr.pass_value,
+            }
+            for jr in result.judgment_requests
+        ],
+        "friction": result.friction.level if result.friction else "none",
+        # Evaluation completeness
+        "evaluation": "partial" if result.is_partial else "complete",
+        "is_partial": result.is_partial,
+        "pending_semantic": _format_pending_semantic(result.pending_semantic),
+    }
+
+    # Add delta fields (null if no previous run or unchanged)
+    if delta is not None:
+        data["score_delta"] = delta.score_delta
+        data["level_previous"] = delta.level_previous
+        data["level_improved"] = delta.level_improved
+        data["violations_delta"] = delta.violations_delta
+    else:
+        data["score_delta"] = None
+        data["level_previous"] = None
+        data["level_improved"] = None
+        data["violations_delta"] = None
+
+    return data
+
+
+def format_score(result: ValidationResult) -> dict[str, Any]:
+    """Convert ValidationResult to minimal score dict.
+
+    Args:
+        result: ValidationResult from engine
+
+    Returns:
+        Simplified dict with just score info
+    """
+    return {
+        "score": result.score,
+        "level": result.level.value,
+        "capability": LEVEL_LABELS.get(result.level, "Unknown"),
+        "feature_summary": result.feature_summary,
+        "rules_checked": result.rules_checked,
+        "violations_count": len(result.violations),
+        "has_critical": any(v.severity.value == "critical" for v in result.violations),
+        "friction": result.friction.level if result.friction else "none",
+    }
+
+
+def format_rule(rule_id: str, rule_data: dict[str, Any]) -> dict[str, Any]:
+    """Format rule explanation as dict.
+
+    Args:
+        rule_id: Rule identifier
+        rule_data: Rule metadata
+
+    Returns:
+        Dict with rule details
+    """
+    return {
+        "id": rule_id,
+        "title": rule_data.get("title", ""),
+        "category": rule_data.get("category", ""),
+        "type": rule_data.get("type", ""),
+        "level": rule_data.get("level", ""),
+        "description": rule_data.get("description", ""),
+        "checks": rule_data.get("checks", rule_data.get("antipatterns", [])),
+        "see_also": rule_data.get("see_also", []),
+    }

reporails_cli/formatters/mcp.py

@@ -0,0 +1,68 @@
+"""MCP output formatter.
+
+Wraps canonical JSON format with MCP-specific transformations if needed.
+"""
+
+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
+
+
+def format_result(
+    result: ValidationResult,
+    delta: ScanDelta | None = None,
+) -> dict[str, Any]:
+    """
+    Format validation result for MCP response.
+
+    Adds instructions for Claude to evaluate JudgmentRequests inline.
+
+    Args:
+        result: ValidationResult from engine
+        delta: Optional ScanDelta for comparison with previous run
+
+    Returns:
+        Dict suitable for MCP tool response
+    """
+    data = json_formatter.format_result(result, delta)
+
+    # Add evaluation instructions if there are judgment requests
+    if data.get("judgment_requests"):
+        data["_instructions"] = (
+            "SEMANTIC RULE EVALUATION REQUIRED: "
+            "For each judgment_request, read the file content and evaluate "
+            "against the question and criteria provided. Report violations "
+            "where criteria are not met. Include these in your response to the user."
+        )
+
+    return data
+
+
+def format_score(result: ValidationResult) -> dict[str, Any]:
+    """
+    Format quick score response for MCP.
+
+    Args:
+        result: ValidationResult from engine
+
+    Returns:
+        Simplified dict with just score info
+    """
+    return json_formatter.format_score(result)
+
+
+def format_rule(rule_id: str, rule_data: dict[str, Any]) -> dict[str, Any]:
+    """
+    Format rule explanation for MCP.
+
+    Args:
+        rule_id: Rule identifier
+        rule_data: Rule metadata
+
+    Returns:
+        Dict with rule details
+    """
+    return json_formatter.format_rule(rule_id, rule_data)

reporails_cli/formatters/text/__init__.py

@@ -0,0 +1,32 @@
+"""Terminal text output formatters.
+
+Public API for formatting validation results as terminal text.
+"""
+
+from reporails_cli.formatters.text.compact import format_compact, format_score
+from reporails_cli.formatters.text.components import format_legend
+
+# Re-export internal functions used by tests
+from reporails_cli.formatters.text.components import (
+    format_level_delta as _format_level_delta,
+)
+from reporails_cli.formatters.text.components import (
+    format_score_delta as _format_score_delta,
+)
+from reporails_cli.formatters.text.components import (
+    format_violations_delta as _format_violations_delta,
+)
+from reporails_cli.formatters.text.full import format_result
+from reporails_cli.formatters.text.rules import format_rule
+
+__all__ = [
+    "format_result",
+    "format_compact",
+    "format_score",
+    "format_rule",
+    "format_legend",
+    # Internal helpers exposed for tests
+    "_format_score_delta",
+    "_format_level_delta",
+    "_format_violations_delta",
+]

reporails_cli/formatters/text/box.py

@@ -0,0 +1,89 @@
+"""Assessment box formatting.
+
+Handles the main score/capability box at the top of output.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reporails_cli.core.models import ScanDelta
+from reporails_cli.core.scorer import LEVEL_LABELS
+from reporails_cli.formatters.text.chars import get_chars
+from reporails_cli.formatters.text.components import (
+    build_score_bar,
+    format_level_delta,
+    format_score_delta,
+    format_violations_delta,
+    pad_line,
+)
+from reporails_cli.templates import render
+
+
+def format_assessment_box(
+    data: dict[str, Any],
+    ascii_mode: bool | None = None,
+    delta: ScanDelta | None = None,
+) -> str:
+    """Format the visual assessment box using templates."""
+    chars = get_chars(ascii_mode)
+    box_width = 62
+
+    score = data.get("score", 0.0)
+    level = data.get("level", "L1")
+    feature_summary = data.get("feature_summary", "")
+    summary_info = data.get("summary", {})
+    rules_checked = summary_info.get("rules_checked", 0)
+    violations = data.get("violations", [])
+    is_partial = data.get("is_partial", True)
+
+    level_label = LEVEL_LABELS.get(level, level)
+
+    # 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)
+
+    # Partial marker
+    partial_marker = "(partial)" if is_partial else ""
+
+    # Build individual lines
+    top_border = chars["tl"] + chars["h"] * box_width + chars["tr"]
+    bottom_border = chars["bl"] + chars["h"] * box_width + chars["br"]
+    empty_line = chars["v"] + " " * box_width + chars["v"]
+
+    # Score line with capability and delta
+    score_text = f"SCORE: {score:.1f} / 10 {partial_marker}{score_delta_str}  |  CAPABILITY: {level_label} ({level}){level_delta_str}"
+    score_line = pad_line(score_text, box_width, chars["v"])
+
+    # Progress bar
+    bar = build_score_bar(score, ascii_mode)
+    bar_line = pad_line(bar, box_width, chars["v"])
+
+    # Setup line
+    setup_text = f"Setup: {feature_summary}"
+    setup_line = pad_line(setup_text, box_width, chars["v"])
+
+    # Summary line - count deduplicated violations
+    seen_violations: set[tuple[str, str]] = set()
+    for v in violations:
+        location = v.get("location", "")
+        file_path = location.rsplit(":", 1)[0] if ":" in location else location
+        rule_id = v.get("rule_id", "")
+        seen_violations.add((file_path, rule_id))
+    violation_count = len(seen_violations)
+    if violation_count == 0:
+        summary = f"No violations · {rules_checked} rules checked"
+    else:
+        summary = f"{violation_count} violation(s){violations_delta_str} · {rules_checked} rules checked"
+    summary_line = pad_line(summary, box_width, chars["v"])
+
+    return render("cli_box.txt",
+        top_border=top_border,
+        bottom_border=bottom_border,
+        empty_line=empty_line,
+        score_line=score_line,
+        bar_line=bar_line,
+        setup_line=setup_line,
+        summary_line=summary_line,
+    )