reporails-cli 0.0.1__py3-none-any.whl

reporails_cli/core/opengrep/templates.py

@@ -0,0 +1,138 @@
+"""Template resolution for OpenGrep rule files.
+
+Handles {{placeholder}} substitution in .yml rule configs.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# Template placeholder pattern
+TEMPLATE_PATTERN = re.compile(r"\{\{(\w+)\}\}")
+
+
+def _glob_to_regex(glob_pattern: str, for_yaml: bool = True) -> str:
+    """Convert a glob pattern to a regex pattern.
+
+    Handles common glob syntax:
+    - ** -> .* (match any path)
+    - * -> [^/]* (match any chars except /)
+    - . -> \\. (escape literal dot)
+    - Other special regex chars are escaped
+
+    Args:
+        glob_pattern: Glob pattern like "**/CLAUDE.md"
+        for_yaml: If True, double-escape backslashes for YAML double-quoted strings
+
+    Returns:
+        Regex pattern like ".*CLAUDE\\.md"
+    """
+    # Remove leading **/ (matches any directory prefix)
+    pattern = glob_pattern
+    if pattern.startswith("**/"):
+        pattern = pattern[3:]
+
+    # Escape regex special chars except * and ?
+    result = ""
+    i = 0
+    while i < len(pattern):
+        c = pattern[i]
+        if c == "*":
+            if i + 1 < len(pattern) and pattern[i + 1] == "*":
+                # ** matches anything including /
+                result += ".*"
+                i += 2
+                # Skip trailing / after **
+                if i < len(pattern) and pattern[i] == "/":
+                    i += 1
+            else:
+                # * matches anything except /
+                result += "[^/]*"
+                i += 1
+        elif c == "?":
+            result += "."
+            i += 1
+        elif c in ".^$+{}[]|()":
+            # Escape for regex, double-escape for YAML if needed
+            escape = "\\\\" if for_yaml else "\\"
+            result += escape + c
+            i += 1
+        else:
+            result += c
+            i += 1
+
+    return result
+
+
+def has_templates(yml_path: Path) -> bool:
+    """Check if yml file contains template placeholders.
+
+    Args:
+        yml_path: Path to yml file
+
+    Returns:
+        True if templates found
+    """
+    try:
+        content = yml_path.read_text(encoding="utf-8")
+        return bool(TEMPLATE_PATTERN.search(content))
+    except OSError:
+        return False
+
+
+def resolve_templates(yml_path: Path, context: dict[str, str | list[str]]) -> str:
+    """Resolve template placeholders in yml content.
+
+    Replaces {{placeholder}} with values from context.
+    Context-aware resolution:
+    - In array context (paths.include), expands list to multiple items
+    - In pattern-regex context, converts globs to regex and joins with |
+    - For string values, does simple substitution
+
+    Args:
+        yml_path: Path to yml file
+        context: Dict mapping placeholder names to string or list values
+
+    Returns:
+        Resolved yml content
+    """
+    content = yml_path.read_text(encoding="utf-8")
+
+    for key, value in context.items():
+        placeholder = "{{" + key + "}}"
+        if placeholder not in content:
+            continue
+
+        if isinstance(value, list):
+            # Find the line with the placeholder and its indentation
+            lines = content.split("\n")
+            new_lines = []
+            for line in lines:
+                if placeholder in line:
+                    stripped = line.lstrip()
+                    indent = len(line) - len(stripped)
+                    indent_str = " " * indent
+
+                    # Check context: array (starts with -) or pattern-regex
+                    if stripped.startswith("- "):
+                        # Array context: expand to multiple list items
+                        for item in value:
+                            new_lines.append(f'{indent_str}- "{item}"')
+                    elif "pattern-regex:" in line or "pattern-not-regex:" in line:
+                        # Regex context: convert globs to regex, join with |
+                        regex_patterns = [_glob_to_regex(g) for g in value]
+                        combined = "(" + "|".join(regex_patterns) + ")"
+                        new_lines.append(line.replace(placeholder, combined))
+                    else:
+                        # Other scalar context: use first item
+                        first_item = value[0] if value else ""
+                        new_lines.append(line.replace(placeholder, first_item))
+                else:
+                    new_lines.append(line)
+            content = "\n".join(new_lines)
+        else:
+            # Simple string substitution
+            content = content.replace(placeholder, str(value))
+
+    return content

reporails_cli/core/registry.py

@@ -0,0 +1,155 @@
+"""Rule loading from markdown frontmatter. Pure functions where possible."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from reporails_cli.core.bootstrap import get_rules_path
+from reporails_cli.core.models import Category, Check, Rule, RuleType, Severity
+from reporails_cli.core.utils import parse_frontmatter
+
+
+def get_rules_dir() -> Path:
+    """Get rules directory (~/.reporails/rules/).
+
+    Returns:
+        Path to rules directory
+    """
+    return get_rules_path()
+
+
+def load_rules(rules_dir: Path | None = None) -> dict[str, Rule]:
+    """Load all rules from rules directory.
+
+    Scans rules/**/*.md, parses frontmatter, links to .yml files.
+
+    Args:
+        rules_dir: Path to rules directory (default: ~/.reporails/rules/)
+
+    Returns:
+        Dict mapping rule ID to Rule object
+    """
+    if rules_dir is None:
+        rules_dir = get_rules_dir()
+
+    if not rules_dir.exists():
+        return {}
+
+    rules: dict[str, Rule] = {}
+
+    for md_path in rules_dir.rglob("*.md"):
+        try:
+            content = md_path.read_text(encoding="utf-8")
+            frontmatter = parse_frontmatter(content)
+
+            if not frontmatter:
+                continue
+
+            # Look for corresponding .yml file
+            yml_path_candidate = md_path.with_suffix(".yml")
+            yml_path: Path | None = yml_path_candidate if yml_path_candidate.exists() else None
+
+            rule = build_rule(frontmatter, md_path, yml_path)
+            rules[rule.id] = rule
+
+        except (ValueError, KeyError):
+            # Skip files without valid frontmatter
+            continue
+
+    return rules
+
+
+def build_rule(frontmatter: dict[str, Any], md_path: Path, yml_path: Path | None) -> Rule:
+    """Build Rule object from parsed frontmatter.
+
+    Pure function — validates and constructs.
+
+    Args:
+        frontmatter: Parsed YAML dict
+        md_path: Path to source .md file
+        yml_path: Path to .yml file (optional)
+
+    Returns:
+        Rule object
+
+    Raises:
+        KeyError: If required fields missing
+        ValueError: If field values invalid
+    """
+    # Parse checks (formerly antipatterns)
+    checks = []
+    # Support both "checks" and legacy "antipatterns" field names
+    check_data = frontmatter.get("checks", frontmatter.get("antipatterns", []))
+    for item in check_data:
+        check = Check(
+            id=item.get("id", ""),
+            name=item.get("name", ""),
+            severity=Severity(item.get("severity", "medium")),
+        )
+        checks.append(check)
+
+    return Rule(
+        id=frontmatter["id"],
+        title=frontmatter["title"],
+        category=Category(frontmatter["category"]),
+        type=RuleType(frontmatter["type"]),
+        level=frontmatter.get("level", "L2"),  # Default to L2 (Basic) if not specified
+        checks=checks,
+        detection=frontmatter.get("detection"),
+        sources=frontmatter.get("sources", []),
+        see_also=frontmatter.get("see_also", []),
+        scoring=frontmatter.get("scoring", 0),
+        validation=frontmatter.get("validation"),
+        question=frontmatter.get("question"),
+        criteria=frontmatter.get("criteria"),
+        choices=frontmatter.get("choices"),
+        pass_value=frontmatter.get("pass_value"),
+        examples=frontmatter.get("examples"),
+        md_path=md_path,
+        yml_path=yml_path,
+    )
+
+
+def get_rules_by_type(rules: dict[str, Rule], rule_type: RuleType) -> dict[str, Rule]:
+    """Filter rules by type.
+
+    Pure function.
+
+    Args:
+        rules: Dict of rules
+        rule_type: Type to filter by
+
+    Returns:
+        Filtered dict of rules
+    """
+    return {k: v for k, v in rules.items() if v.type == rule_type}
+
+
+def get_rules_by_category(rules: dict[str, Rule], category: Category) -> dict[str, Rule]:
+    """Filter rules by category.
+
+    Pure function.
+
+    Args:
+        rules: Dict of rules
+        category: Category to filter by
+
+    Returns:
+        Filtered dict of rules
+    """
+    return {k: v for k, v in rules.items() if v.category == category}
+
+
+def get_rule_yml_paths(rules: dict[str, Rule]) -> list[Path]:
+    """Get list of .yml paths for rules that have them.
+
+    Pure function.
+
+    Args:
+        rules: Dict of rules
+
+    Returns:
+        List of paths to .yml files
+    """
+    return [r.yml_path for r in rules.values() if r.yml_path is not None]

reporails_cli/core/sarif.py

@@ -0,0 +1,181 @@
+"""SARIF parsing - converts OpenGrep output to domain objects.
+
+All functions are pure (no I/O).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from reporails_cli.core.models import Rule, Severity, Violation
+
+# Severity weights for scoring
+SEVERITY_WEIGHTS: dict[Severity, float] = {
+    Severity.CRITICAL: 5.5,
+    Severity.HIGH: 4.0,
+    Severity.MEDIUM: 2.5,
+    Severity.LOW: 1.0,
+}
+
+
+def extract_rule_id(sarif_rule_id: str) -> str:
+    """Extract short rule ID from OpenGrep SARIF ruleId.
+
+    OpenGrep formats rule IDs as: checks.{category}.{id}-{slug}
+    Example: checks.structure.S1-many-h2-headings -> S1
+
+    Args:
+        sarif_rule_id: Full ruleId from SARIF output
+
+    Returns:
+        Short rule ID (e.g., S1, C10, M7)
+    """
+    # Pattern: extract the ID part (letter + digits) from the last segment
+    match = re.search(r"\.([A-Z]\d+)-", sarif_rule_id)
+    if match:
+        return match.group(1)
+    return sarif_rule_id
+
+
+def extract_check_slug(sarif_rule_id: str) -> str | None:
+    """Extract check slug from OpenGrep SARIF ruleId.
+
+    OpenGrep formats rule IDs as: checks.{category}.{id}-{slug}
+    Example: checks.structure.S1-many-sections -> many-sections
+
+    Args:
+        sarif_rule_id: Full ruleId from SARIF output
+
+    Returns:
+        Check slug (e.g., "many-sections") or None
+    """
+    match = re.search(r"\.[A-Z]\d+-(.+)$", sarif_rule_id)
+    if match:
+        return match.group(1)
+    return None
+
+
+def get_location(result: dict[str, Any]) -> str:
+    """Extract location string from SARIF result.
+
+    Args:
+        result: SARIF result object
+
+    Returns:
+        Location string in format "file:line"
+    """
+    locations = result.get("locations", [])
+    if not locations:
+        return "unknown"
+
+    loc = locations[0].get("physicalLocation", {})
+    artifact = loc.get("artifactLocation", {}).get("uri", "unknown")
+    region = loc.get("region", {})
+    line = region.get("startLine", 0)
+    return f"{artifact}:{line}"
+
+
+def get_severity(rule: Rule | None, check_slug: str | None) -> Severity:
+    """Get severity for a violation.
+
+    Looks up severity from rule's checks list, falls back to MEDIUM.
+
+    Args:
+        rule: Rule object (may be None)
+        check_slug: Check slug from SARIF (may be None)
+
+    Returns:
+        Severity level
+    """
+    if rule is None:
+        return Severity.MEDIUM
+
+    # Try to find matching check
+    for check in rule.checks:
+        if check_slug and check_slug in check.id:
+            return check.severity
+        # Return first check's severity as default
+        return check.severity
+
+    return Severity.MEDIUM
+
+
+def parse_sarif(sarif: dict[str, Any], rules: dict[str, Rule]) -> list[Violation]:
+    """Parse OpenGrep SARIF output into Violation objects.
+
+    Pure function — no I/O. Skips INFO/note level findings.
+
+    Args:
+        sarif: Parsed SARIF JSON
+        rules: Dict of rules for metadata lookup
+
+    Returns:
+        List of Violation objects
+    """
+    violations = []
+
+    for run in sarif.get("runs", []):
+        # Build map of rule levels from tool definitions
+        rule_levels: dict[str, str] = {}
+        tool = run.get("tool", {}).get("driver", {})
+        for rule_def in tool.get("rules", []):
+            rule_id = rule_def.get("id", "")
+            level = rule_def.get("defaultConfiguration", {}).get("level", "warning")
+            rule_levels[rule_id] = level
+
+        for result in run.get("results", []):
+            sarif_rule_id = result.get("ruleId", "")
+
+            # Skip INFO/note level findings
+            rule_level = rule_levels.get(sarif_rule_id, "warning")
+            if rule_level in ("note", "none"):
+                continue
+
+            short_rule_id = extract_rule_id(sarif_rule_id)
+            check_slug = extract_check_slug(sarif_rule_id)
+            message = result.get("message", {}).get("text", "")
+            location = get_location(result)
+
+            # Get rule metadata
+            rule = rules.get(short_rule_id)
+            title = rule.title if rule else sarif_rule_id
+            severity = get_severity(rule, check_slug)
+
+            violations.append(
+                Violation(
+                    rule_id=short_rule_id,
+                    rule_title=title,
+                    location=location,
+                    message=message,
+                    severity=severity,
+                    check_id=check_slug,
+                )
+            )
+
+    return violations
+
+
+def dedupe_violations(violations: list[Violation]) -> list[Violation]:
+    """Deduplicate violations by (file, rule_id).
+
+    Keeps first occurrence of each unique (file, rule_id) pair.
+
+    Args:
+        violations: List of violations (may have duplicates)
+
+    Returns:
+        Deduplicated list of violations
+    """
+    seen: set[tuple[str, str]] = set()
+    result: list[Violation] = []
+
+    for v in violations:
+        file_path = v.location.rsplit(":", 1)[0] if ":" in v.location else v.location
+        key = (file_path, v.rule_id)
+
+        if key not in seen:
+            seen.add(key)
+            result.append(v)
+
+    return result

reporails_cli/core/scorer.py

@@ -0,0 +1,178 @@
+"""Scoring functions for reporails. All pure functions."""
+
+from __future__ import annotations
+
+from reporails_cli.core.models import FrictionEstimate, Level, Severity, Violation
+
+# Severity weights for scoring (higher = more impact)
+SEVERITY_WEIGHTS: dict[Severity, float] = {
+    Severity.CRITICAL: 5.5,
+    Severity.HIGH: 4.0,
+    Severity.MEDIUM: 2.5,
+    Severity.LOW: 1.0,
+}
+
+# Default weight for rules (used when calculating total possible points)
+DEFAULT_RULE_WEIGHT: float = 2.5
+
+# Level labels - must match levels.yml
+LEVEL_LABELS: dict[Level, str] = {
+    Level.L1: "Absent",
+    Level.L2: "Basic",
+    Level.L3: "Structured",
+    Level.L4: "Abstracted",
+    Level.L5: "Governed",
+    Level.L6: "Adaptive",
+}
+
+
+def dedupe_violations(violations: list[Violation]) -> list[Violation]:
+    """Deduplicate violations by (file, rule_id).
+
+    Keeps first occurrence of each unique (file, rule_id) pair.
+
+    Args:
+        violations: List of violations (may have duplicates)
+
+    Returns:
+        Deduplicated list of violations
+    """
+    seen: set[tuple[str, str]] = set()
+    result: list[Violation] = []
+
+    for v in violations:
+        file_path = v.location.rsplit(":", 1)[0] if ":" in v.location else v.location
+        key = (file_path, v.rule_id)
+
+        if key not in seen:
+            seen.add(key)
+            result.append(v)
+
+    return result
+
+
+def calculate_score(rules_checked: int, violations: list[Violation]) -> float:
+    """Calculate display score on 0-10 scale.
+
+    Score = (earned_points / possible_points) × 10
+
+    Lost points are capped per rule - multiple violations of the same rule
+    don't deduct more than the rule's weight (DEFAULT_RULE_WEIGHT).
+
+    Args:
+        rules_checked: Total number of rules checked
+        violations: List of violations found
+
+    Returns:
+        Score between 0.0 and 10.0
+    """
+    if rules_checked == 0:
+        return 10.0  # No rules = perfect
+
+    # Total possible points
+    possible = rules_checked * DEFAULT_RULE_WEIGHT
+
+    # Group violations by rule_id, cap lost points per rule
+    unique_violations = dedupe_violations(violations)
+    by_rule: dict[str, float] = {}
+    for v in unique_violations:
+        weight = SEVERITY_WEIGHTS.get(v.severity, DEFAULT_RULE_WEIGHT)
+        # Accumulate but cap at rule weight
+        current = by_rule.get(v.rule_id, 0.0)
+        by_rule[v.rule_id] = min(current + weight, DEFAULT_RULE_WEIGHT)
+
+    lost = sum(by_rule.values())
+
+    # Earned = possible - lost (floor at 0)
+    earned = max(0.0, possible - lost)
+
+    # Score on 0-10 scale
+    score = (earned / possible) * 10
+    return round(score, 1)
+
+
+def get_severity_weight(severity: Severity) -> float:
+    """Get weight for a severity level.
+
+    Args:
+        severity: Severity level
+
+    Returns:
+        Weight value
+    """
+    return SEVERITY_WEIGHTS.get(severity, DEFAULT_RULE_WEIGHT)
+
+
+def estimate_friction(violations: list[Violation]) -> FrictionEstimate:
+    """Estimate friction from violations.
+
+    Friction levels based on violation severity:
+    - extreme: Any critical violation
+    - high: 2+ high severity OR 5+ total violations
+    - medium: 1 high severity OR 3-4 violations
+    - small: 1-2 violations (medium/low severity)
+    - none: No violations
+
+    Args:
+        violations: List of violations
+
+    Returns:
+        FrictionEstimate with level
+    """
+    unique = dedupe_violations(violations)
+
+    if not unique:
+        return FrictionEstimate(level="none")
+
+    # Count by severity
+    critical_count = sum(1 for v in unique if v.severity == Severity.CRITICAL)
+    high_count = sum(1 for v in unique if v.severity == Severity.HIGH)
+    total_count = len(unique)
+
+    # Determine level
+    if critical_count > 0:
+        level = "extreme"
+    elif high_count >= 2 or total_count >= 5:
+        level = "high"
+    elif high_count >= 1 or total_count >= 3:
+        level = "medium"
+    else:
+        level = "small"
+
+    return FrictionEstimate(level=level)
+
+
+def get_level_label(level: Level) -> str:
+    """Get human-readable label for level.
+
+    Args:
+        level: Maturity level
+
+    Returns:
+        Label string (e.g., "Abstracted")
+    """
+    return LEVEL_LABELS.get(level, "Unknown")
+
+
+def has_critical_violations(violations: list[Violation]) -> bool:
+    """Check if any violation is critical.
+
+    Args:
+        violations: List of violations
+
+    Returns:
+        True if any violation has CRITICAL severity
+    """
+    return any(v.severity == Severity.CRITICAL for v in violations)
+
+
+# Legacy compatibility
+def get_severity_points(severity: Severity) -> int:
+    """Legacy: Get point deduction for a severity level."""
+    points_map = {
+        Severity.CRITICAL: -25,
+        Severity.HIGH: -15,
+        Severity.MEDIUM: -10,
+        Severity.LOW: -5,
+    }
+    return points_map.get(severity, -5)