reporails-cli 0.0.1__py3-none-any.whl

reporails_cli/core/models.py

@@ -0,0 +1,329 @@
+"""Data models for reporails. All models are frozen (immutable) where possible."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from reporails_cli.core.cache import AnalyticsEntry
+
+
+class Category(str, Enum):
+    """Rule categories matching framework."""
+
+    STRUCTURE = "structure"
+    CONTENT = "content"
+    MAINTENANCE = "maintenance"
+    GOVERNANCE = "governance"
+    EFFICIENCY = "efficiency"
+
+
+class RuleType(str, Enum):
+    """How the rule is detected. Two types only."""
+
+    DETERMINISTIC = "deterministic"  # OpenGrep pattern → direct violation
+    SEMANTIC = "semantic"  # LLM judgment required
+
+
+class Severity(str, Enum):
+    """Violation severity levels."""
+
+    CRITICAL = "critical"  # Weight: 5.5
+    HIGH = "high"  # Weight: 4.0
+    MEDIUM = "medium"  # Weight: 2.5
+    LOW = "low"  # Weight: 1.0
+
+
+class Level(str, Enum):
+    """Capability levels from framework."""
+
+    L1 = "L1"  # Absent
+    L2 = "L2"  # Basic
+    L3 = "L3"  # Structured
+    L4 = "L4"  # Abstracted
+    L5 = "L5"  # Governed
+    L6 = "L6"  # Adaptive
+
+
+@dataclass(frozen=True)
+class Check:
+    """A specific check within a rule. Maps to OpenGrep pattern."""
+
+    id: str  # e.g., "S1-root-too-long"
+    name: str  # e.g., "Root file exceeds 200 lines"
+    severity: Severity
+
+
+@dataclass
+class Rule:
+    """A rule definition loaded from framework frontmatter."""
+
+    # Required (from frontmatter)
+    id: str  # e.g., "S1"
+    title: str  # e.g., "Size Limits"
+    category: Category
+    type: RuleType
+    level: str  # e.g., "L2" - minimum level this rule applies to
+
+    # Checks (deterministic rules)
+    checks: list[Check] = field(default_factory=list)
+
+    # Semantic fields (semantic rules)
+    question: str | None = None
+    criteria: list[dict[str, str]] | str | None = None  # [{key, check}, ...] or string
+    choices: list[dict[str, str]] | list[str] | None = None  # [{value, label}, ...]
+    pass_value: str | None = None
+    examples: dict[str, list[str]] | None = None  # {good: [...], bad: [...]}
+
+    # References
+    sources: list[int] = field(default_factory=list)
+    see_also: list[str] = field(default_factory=list)
+
+    # Legacy field names (for backward compatibility during transition)
+    detection: str | None = None
+    scoring: int = 0
+    validation: str | None = None
+
+    # Paths (set after loading)
+    md_path: Path | None = None
+    yml_path: Path | None = None
+
+
+@dataclass(frozen=True)
+class Violation:
+    """A rule violation found during analysis."""
+
+    rule_id: str  # e.g., "S1"
+    rule_title: str  # e.g., "Size Limits"
+    location: str  # e.g., "CLAUDE.md:45"
+    message: str  # From OpenGrep
+    severity: Severity
+    check_id: str | None = None  # e.g., "S1-root-too-long"
+
+
+@dataclass(frozen=True)
+class JudgmentRequest:
+    """Request for host LLM to evaluate semantic rule."""
+
+    rule_id: str
+    rule_title: str
+    content: str  # Text to evaluate
+    location: str  # e.g., "CLAUDE.md"
+    question: str  # What to evaluate
+    criteria: dict[str, str]  # {key: check, ...}
+    examples: dict[str, list[str]]  # {good: [...], bad: [...]}
+    choices: list[str]  # [value, ...]
+    pass_value: str  # Which choice means "pass"
+    severity: Severity
+    points_if_fail: int
+
+
+@dataclass(frozen=True)
+class JudgmentResponse:
+    """Response from host LLM after evaluation."""
+
+    rule_id: str
+    verdict: str  # One of the choice values
+    reason: str  # Explanation
+    passed: bool  # verdict == pass_value
+
+
+# =============================================================================
+# Feature Detection Models
+# =============================================================================
+
+
+@dataclass
+class DetectedFeatures:
+    """Features detected in a project for capability scoring.
+
+    Populated in two phases:
+    - Phase 1: Filesystem detection (applicability.py)
+    - Phase 2: Content detection (capability.py via OpenGrep)
+    """
+
+    # === Phase 1: Filesystem detection ===
+
+    # Base existence
+    has_instruction_file: bool = False  # Any instruction file found
+    has_claude_md: bool = False  # CLAUDE.md at root (legacy compat)
+
+    # Directory structure
+    has_rules_dir: bool = False  # .claude/rules/, .cursor/rules/, etc.
+    has_shared_files: bool = False  # .shared/, shared/, cross-refs
+    has_backbone: bool = False  # .reporails/backbone.yml
+
+    # Discovery
+    component_count: int = 0  # Components from discovery
+    instruction_file_count: int = 0
+    has_multiple_instruction_files: bool = False
+    has_hierarchical_structure: bool = False  # nested CLAUDE.md files
+    detected_agents: list[str] = field(default_factory=list)
+
+    # === Phase 2: Content detection (OpenGrep) ===
+
+    # Content analysis
+    has_sections: bool = False  # Has H2+ headers
+    has_imports: bool = False  # @imports or file references
+    has_explicit_constraints: bool = False  # MUST/NEVER keywords
+    has_path_scoped_rules: bool = False  # Rules with paths: frontmatter
+
+
+@dataclass(frozen=True)
+class ContentFeatures:
+    """Intermediate result from OpenGrep content analysis."""
+
+    has_sections: bool = False
+    has_imports: bool = False
+    has_explicit_constraints: bool = False
+    has_path_scoped_rules: bool = False
+
+
+@dataclass(frozen=True)
+class CapabilityResult:
+    """Result of capability detection pipeline."""
+
+    features: DetectedFeatures
+    capability_score: int  # 0-12
+    level: Level  # Base level (L1-L6)
+    has_orphan_features: bool  # Has features above base level (display as L3+)
+    feature_summary: str  # Human-readable
+
+
+@dataclass(frozen=True)
+class FrictionEstimate:
+    """Friction estimate from violations."""
+
+    level: str  # "extreme", "high", "medium", "small", "none"
+
+
+# =============================================================================
+# Configuration Models
+# =============================================================================
+
+
+@dataclass
+class GlobalConfig:
+    """Global user configuration (~/.reporails/config.yml)."""
+
+    framework_path: Path | None = None  # Local override (dev)
+    auto_update_check: bool = True
+
+
+@dataclass
+class ProjectConfig:
+    """Project-level configuration (.reporails/config.yml)."""
+
+    framework_version: str | None = None  # Pin version
+    disabled_rules: list[str] = field(default_factory=list)
+    overrides: dict[str, dict[str, str]] = field(default_factory=dict)
+
+
+# =============================================================================
+# Result Models
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class ScanDelta:
+    """Comparison between current and previous scan."""
+
+    score_delta: float | None  # None if no previous or unchanged
+    level_previous: str | None  # None if unchanged or no previous
+    level_improved: bool | None  # True=up, False=down, None=unchanged/no previous
+    violations_delta: int | None  # Negative=improvement, positive=regression, None if unchanged
+
+    @classmethod
+    def compute(
+        cls,
+        current_score: float,
+        current_level: str,
+        current_violations: int,
+        previous: AnalyticsEntry | None,
+    ) -> ScanDelta:
+        """Compute delta from current values and previous scan entry.
+
+        Args:
+            current_score: Current scan score
+            current_level: Current level (e.g., "L3")
+            current_violations: Current violation count
+            previous: Previous AnalyticsEntry or None
+
+        Returns:
+            ScanDelta with computed differences
+        """
+        if previous is None:
+            return cls(None, None, None, None)
+
+        # Score delta (round to 1 decimal, None if unchanged)
+        raw_score_delta = round(current_score - previous.score, 1)
+        score_delta = raw_score_delta if raw_score_delta != 0 else None
+
+        # Level comparison (extract number from "L3" etc)
+        curr_num = int(current_level[1]) if current_level.startswith("L") else 0
+        prev_num = int(previous.level[1]) if previous.level.startswith("L") else 0
+        if curr_num != prev_num:
+            level_previous = previous.level
+            level_improved = curr_num > prev_num
+        else:
+            level_previous = None
+            level_improved = None
+
+        # Violations delta (None if unchanged)
+        viol_delta = current_violations - previous.violations_count
+        violations_delta = viol_delta if viol_delta != 0 else None
+
+        return cls(score_delta, level_previous, level_improved, violations_delta)
+
+
+@dataclass(frozen=True)
+class PendingSemantic:
+    """Summary of pending semantic rules for partial evaluation."""
+
+    rule_count: int  # Number of semantic rules pending
+    file_count: int  # Files with pending semantic checks
+    rules: tuple[str, ...]  # Rule IDs (e.g., "C6", "C10")
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Complete validation output."""
+
+    score: float  # 0.0-10.0 scale
+    level: Level  # Capability level
+    violations: tuple[Violation, ...]  # Immutable
+    judgment_requests: tuple[JudgmentRequest, ...]
+    rules_checked: int  # Deterministic rules checked
+    rules_passed: int
+    rules_failed: int
+    feature_summary: str  # Human-readable
+    friction: FrictionEstimate
+    # Evaluation completeness
+    is_partial: bool = True  # True for CLI (pattern-only), False for MCP (includes semantic)
+    pending_semantic: PendingSemantic | None = None  # Summary of pending semantic rules
+
+
+@dataclass(frozen=True)
+class InitResult:
+    """Result of initialization."""
+
+    success: bool
+    opengrep_path: Path | None
+    rules_path: Path | None
+    framework_version: str | None
+    errors: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class UpdateResult:
+    """Result of framework update."""
+
+    success: bool
+    message: str
+    old_version: str | None = None
+    new_version: str | None = None
+    rules_path: Path | None = None
+    rules_count: int = 0

reporails_cli/core/opengrep/__init__.py

@@ -0,0 +1,34 @@
+"""OpenGrep integration module.
+
+Public API for running OpenGrep and processing results.
+"""
+
+from reporails_cli.core.opengrep.runner import (
+    get_rule_yml_paths,
+    run_capability_detection,
+    run_opengrep,
+    run_rule_validation,
+    set_debug_timing,
+)
+from reporails_cli.core.opengrep.templates import (
+    TEMPLATE_PATTERN,
+    has_templates,
+    resolve_templates,
+)
+
+# Backward-compatible alias
+resolve_yml_templates = resolve_templates
+
+__all__ = [
+    # Runner functions
+    "run_opengrep",
+    "run_capability_detection",
+    "run_rule_validation",
+    "get_rule_yml_paths",
+    "set_debug_timing",
+    # Template functions
+    "has_templates",
+    "resolve_templates",
+    "resolve_yml_templates",  # Backward-compatible alias
+    "TEMPLATE_PATTERN",
+]

reporails_cli/core/opengrep/runner.py

@@ -0,0 +1,203 @@
+"""OpenGrep binary execution.
+
+Runs OpenGrep and returns parsed SARIF output.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import subprocess
+import sys
+import time
+from pathlib import Path
+from tempfile import NamedTemporaryFile, TemporaryDirectory
+from typing import Any
+
+from reporails_cli.bundled import get_capability_patterns_path
+from reporails_cli.core.bootstrap import get_opengrep_bin
+from reporails_cli.core.models import Rule
+from reporails_cli.core.opengrep.semgrepignore import ensure_semgrepignore
+from reporails_cli.core.opengrep.templates import has_templates, resolve_templates
+
+logger = logging.getLogger(__name__)
+
+# Module-level debug flag (set by CLI)
+_debug_timing = False
+
+
+def set_debug_timing(enabled: bool) -> None:
+    """Enable/disable timing output to stderr."""
+    global _debug_timing
+    _debug_timing = enabled
+
+
+def _log_timing(label: str, elapsed_ms: float) -> None:
+    """Log timing info to stderr if debug enabled."""
+    if _debug_timing:
+        print(f"[perf] {label}: {elapsed_ms:.0f}ms", file=sys.stderr)
+
+
+def run_opengrep(
+    yml_paths: list[Path],
+    target: Path,
+    opengrep_path: Path | None = None,
+    template_context: dict[str, str | list[str]] | None = None,
+) -> dict[str, Any]:
+    """Execute OpenGrep with specified rule configs.
+
+    Shells out to OpenGrep, returns parsed SARIF.
+
+    Args:
+        yml_paths: List of .yml rule config files (must exist)
+        target: Directory to scan
+        opengrep_path: Path to OpenGrep binary (optional, auto-detects)
+        template_context: Optional dict for resolving {{placeholder}} in yml files
+
+    Returns:
+        Parsed SARIF JSON output
+    """
+    start_time = time.perf_counter()
+
+    # Filter to only existing yml files - don't call OpenGrep with nothing to run
+    valid_paths = [p for p in yml_paths if p and p.exists()]
+    if not valid_paths:
+        return {"runs": []}
+
+    if opengrep_path is None:
+        opengrep_path = get_opengrep_bin()
+
+    if not opengrep_path.exists():
+        logger.warning("OpenGrep binary not found: %s", opengrep_path)
+        return {"runs": []}
+
+    # Create temp file for SARIF output
+    with NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        sarif_path = Path(f.name)
+
+    # Use temp directory for resolved yml files if context provided
+    temp_dir = TemporaryDirectory() if template_context else None
+
+    # Ensure .semgrepignore exists for performance
+    created_semgrepignore = ensure_semgrepignore(target)
+
+    try:
+        # Resolve templates if context provided
+        if template_context and temp_dir:
+            resolved_paths: list[Path] = []
+            for yml_path in valid_paths:
+                if has_templates(yml_path):
+                    # Resolve and write to temp file
+                    resolved_content = resolve_templates(yml_path, template_context)
+                    temp_yml = Path(temp_dir.name) / yml_path.name
+                    temp_yml.write_text(resolved_content, encoding="utf-8")
+                    resolved_paths.append(temp_yml)
+                else:
+                    # No templates, use original
+                    resolved_paths.append(yml_path)
+            config_paths = resolved_paths
+        else:
+            config_paths = valid_paths
+
+        # Build command
+        cmd = [
+            str(opengrep_path),
+            "scan",
+            "--sarif",
+            f"--output={sarif_path}",
+        ]
+
+        # Add rule files
+        for yml_path in config_paths:
+            cmd.extend(["--config", str(yml_path)])
+
+        # Add target
+        cmd.append(str(target))
+
+        # Run OpenGrep
+        proc = subprocess.run(cmd, capture_output=True, check=False)
+
+        elapsed_ms = (time.perf_counter() - start_time) * 1000
+        _log_timing(f"opengrep ({len(config_paths)} rules)", elapsed_ms)
+
+        # Check for errors (0 = no findings, 1 = findings found)
+        if proc.returncode not in (0, 1):
+            logger.warning(
+                "OpenGrep failed with code %d: %s",
+                proc.returncode,
+                proc.stderr.decode("utf-8", errors="replace")[:500],
+            )
+            return {"runs": []}
+
+        # Parse SARIF output
+        if sarif_path.exists():
+            try:
+                result: dict[str, Any] = json.loads(sarif_path.read_text(encoding="utf-8"))
+                return result
+            except json.JSONDecodeError as e:
+                logger.warning("Invalid SARIF output from OpenGrep: %s", e)
+                return {"runs": []}
+        return {"runs": []}
+
+    finally:
+        if sarif_path.exists():
+            sarif_path.unlink()
+        if temp_dir:
+            temp_dir.cleanup()
+        # Clean up created .semgrepignore
+        if created_semgrepignore and created_semgrepignore.exists():
+            with contextlib.suppress(OSError):
+                created_semgrepignore.unlink()
+
+
+def run_capability_detection(target: Path) -> dict[str, Any]:
+    """Run capability detection using bundled patterns.
+
+    Uses bundled capability-patterns.yml for content analysis.
+
+    Args:
+        target: Directory to scan
+
+    Returns:
+        Parsed SARIF JSON output
+    """
+    patterns_path = get_capability_patterns_path()
+    if not patterns_path.exists():
+        logger.warning("Capability patterns not found: %s", patterns_path)
+        return {"runs": []}
+
+    return run_opengrep([patterns_path], target)
+
+
+def run_rule_validation(rules: dict[str, Rule], target: Path) -> dict[str, Any]:
+    """Run rule validation using rule .yml files.
+
+    Args:
+        rules: Dict of rules with yml_path set
+        target: Directory to scan
+
+    Returns:
+        Parsed SARIF JSON output
+    """
+    yml_paths = get_rule_yml_paths(rules)
+    if not yml_paths:
+        # No patterns to run - this is normal, not an error
+        return {"runs": []}
+
+    return run_opengrep(yml_paths, target)
+
+
+def get_rule_yml_paths(rules: dict[str, Rule]) -> list[Path]:
+    """Get list of .yml paths for rules that have them and exist.
+
+    Args:
+        rules: Dict of rules
+
+    Returns:
+        List of paths to existing .yml files
+    """
+    return [
+        r.yml_path for r in rules.values()
+        if r.yml_path is not None and r.yml_path.exists()
+    ]

reporails_cli/core/opengrep/semgrepignore.py

@@ -0,0 +1,39 @@
+"""Semgrepignore file handling.
+
+Manages .semgrepignore files for OpenGrep performance.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from reporails_cli.bundled import get_semgrepignore_path
+
+
+def ensure_semgrepignore(target: Path) -> Path | None:
+    """Ensure .semgrepignore exists in target directory.
+
+    If no .semgrepignore exists, copies the bundled default.
+    Returns path to created file if created, None if already exists.
+
+    Args:
+        target: Target directory to scan
+
+    Returns:
+        Path to created .semgrepignore if created, None otherwise
+    """
+    target_dir = target if target.is_dir() else target.parent
+    existing = target_dir / ".semgrepignore"
+    if existing.exists():
+        return None
+
+    # Copy bundled .semgrepignore to target directory
+    bundled = get_semgrepignore_path()
+    if bundled.exists():
+        try:
+            shutil.copy(bundled, existing)
+            return existing  # Return so caller can clean up
+        except OSError:
+            pass
+    return None