reporails-cli 0.0.1__py3-none-any.whl

reporails_cli/core/capability.py

@@ -0,0 +1,245 @@
+"""Capability detection - determines project capability level.
+
+Two-phase detection:
+1. Filesystem (applicability.py) - directory/file existence
+2. Content (this module) - OpenGrep pattern matching
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reporails_cli.core.levels import capability_score_to_level, detect_orphan_features
+from reporails_cli.core.models import (
+    CapabilityResult,
+    ContentFeatures,
+    DetectedFeatures,
+    Level,
+)
+
+# Capability weights for scoring
+CAPABILITY_WEIGHTS: dict[str, int] = {
+    "has_instruction_file": 1,
+    "has_sections": 1,
+    "has_imports": 1,
+    "has_explicit_constraints": 1,
+    "has_rules_dir": 2,
+    "has_path_scoped_rules": 1,
+    "has_shared_files": 1,
+    "component_count_3plus": 1,
+    "has_backbone": 2,
+}
+# Max: 12 points
+
+
+def detect_features_content(sarif: dict[str, Any]) -> ContentFeatures:
+    """Parse OpenGrep SARIF output to detect content features.
+
+    Args:
+        sarif: SARIF output from capability pattern detection
+
+    Returns:
+        ContentFeatures with detected flags
+    """
+    has_sections = False
+    has_imports = False
+    has_explicit_constraints = False
+    has_path_scoped_rules = False
+
+    for run in sarif.get("runs", []):
+        for result in run.get("results", []):
+            rule_id = result.get("ruleId", "")
+
+            if "has-sections" in rule_id:
+                has_sections = True
+            elif "has-imports" in rule_id:
+                has_imports = True
+            elif "has-explicit-constraints" in rule_id:
+                has_explicit_constraints = True
+            elif "has-path-scoped-rules" in rule_id:
+                has_path_scoped_rules = True
+
+    return ContentFeatures(
+        has_sections=has_sections,
+        has_imports=has_imports,
+        has_explicit_constraints=has_explicit_constraints,
+        has_path_scoped_rules=has_path_scoped_rules,
+    )
+
+
+def calculate_capability_score(features: DetectedFeatures) -> int:
+    """Calculate capability score from features.
+
+    Args:
+        features: Detected project features
+
+    Returns:
+        Score from 0 to 12
+    """
+    score = 0
+
+    # Phase 1 features (filesystem)
+    if features.has_instruction_file or features.has_claude_md:
+        score += CAPABILITY_WEIGHTS["has_instruction_file"]
+    if features.has_rules_dir:
+        score += CAPABILITY_WEIGHTS["has_rules_dir"]
+    if features.has_shared_files:
+        score += CAPABILITY_WEIGHTS["has_shared_files"]
+    if features.component_count >= 3:
+        score += CAPABILITY_WEIGHTS["component_count_3plus"]
+    if features.has_backbone:
+        score += CAPABILITY_WEIGHTS["has_backbone"]
+
+    # Phase 2 features (content)
+    if features.has_sections:
+        score += CAPABILITY_WEIGHTS["has_sections"]
+    if features.has_imports:
+        score += CAPABILITY_WEIGHTS["has_imports"]
+    if features.has_explicit_constraints:
+        score += CAPABILITY_WEIGHTS["has_explicit_constraints"]
+    if features.has_path_scoped_rules:
+        score += CAPABILITY_WEIGHTS["has_path_scoped_rules"]
+
+    return score
+
+
+def calculate_filesystem_score(features: DetectedFeatures) -> int:
+    """Calculate capability score from filesystem features only.
+
+    Used for early rule filtering before OpenGrep runs.
+    Returns conservative estimate (may be lower than final level).
+
+    Args:
+        features: Detected project features (filesystem only)
+
+    Returns:
+        Score from 0 to 7 (filesystem features max)
+    """
+    score = 0
+
+    if features.has_instruction_file or features.has_claude_md:
+        score += CAPABILITY_WEIGHTS["has_instruction_file"]
+    if features.has_rules_dir:
+        score += CAPABILITY_WEIGHTS["has_rules_dir"]
+    if features.has_shared_files:
+        score += CAPABILITY_WEIGHTS["has_shared_files"]
+    if features.component_count >= 3:
+        score += CAPABILITY_WEIGHTS["component_count_3plus"]
+    if features.has_backbone:
+        score += CAPABILITY_WEIGHTS["has_backbone"]
+
+    return score
+
+
+def estimate_preliminary_level(features: DetectedFeatures) -> Level:
+    """Estimate capability level from filesystem features only.
+
+    Conservative estimate for early rule filtering.
+    Final level is determined after content analysis.
+
+    Args:
+        features: Detected project features (filesystem only)
+
+    Returns:
+        Preliminary Level (may be lower than final)
+    """
+    from reporails_cli.core.levels import capability_score_to_level
+    score = calculate_filesystem_score(features)
+    return capability_score_to_level(score)
+
+
+def merge_content_features(
+    features: DetectedFeatures,
+    content_features: ContentFeatures,
+) -> DetectedFeatures:
+    """Merge content features into main features object.
+
+    Args:
+        features: Base features from filesystem detection
+        content_features: Features from content detection
+
+    Returns:
+        Updated DetectedFeatures
+    """
+    features.has_sections = content_features.has_sections
+    features.has_imports = features.has_imports or content_features.has_imports
+    features.has_explicit_constraints = content_features.has_explicit_constraints
+    features.has_path_scoped_rules = content_features.has_path_scoped_rules
+    return features
+
+
+def determine_capability_level(
+    features: DetectedFeatures,
+    content_features: ContentFeatures | None = None,
+) -> CapabilityResult:
+    """Determine capability level from features.
+
+    Two-phase pipeline:
+    1. Filesystem features (already in features)
+    2. Content features (merged in)
+
+    Args:
+        features: Detected project features
+        content_features: Optional content features to merge
+
+    Returns:
+        CapabilityResult with level, score, and summary
+    """
+    # Merge content features if provided
+    if content_features:
+        merge_content_features(features, content_features)
+
+    # Calculate score and level
+    score = calculate_capability_score(features)
+    level = capability_score_to_level(score)
+
+    # Check for orphan features
+    has_orphan = detect_orphan_features(features, level)
+
+    # Generate summary
+    summary = get_feature_summary(features)
+
+    return CapabilityResult(
+        features=features,
+        capability_score=score,
+        level=level,
+        has_orphan_features=has_orphan,
+        feature_summary=summary,
+    )
+
+
+def get_feature_summary(features: DetectedFeatures) -> str:
+    """Generate human-readable summary of detected features.
+
+    Args:
+        features: Detected project features
+
+    Returns:
+        Summary string for display
+    """
+    parts = []
+
+    # File count
+    file_count = features.instruction_file_count
+    if file_count == 0:
+        parts.append("No instruction files")
+    elif file_count == 1:
+        parts.append("1 instruction file")
+    else:
+        parts.append(f"{file_count} instruction files")
+
+    # Features present
+    feature_list = []
+    if features.has_rules_dir:
+        feature_list.append(".claude/rules/")
+    if features.has_backbone:
+        feature_list.append("backbone.yml")
+    if features.has_shared_files:
+        feature_list.append("shared files")
+    if features.has_hierarchical_structure:
+        feature_list.append("hierarchical")
+
+    if feature_list:
+        parts.append(" + ".join(feature_list))
+
+    return ", ".join(parts) if parts else "No features detected"

reporails_cli/core/discover.py

@@ -0,0 +1,362 @@
+"""Discovery engine - analyze instruction files and generate backbone.
+
+Deterministic discovery of:
+- Component structure (from directory hierarchy)
+- File references (from markdown content)
+- Dependencies (imports between instruction files)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from reporails_cli.core.agents import DetectedAgent, detect_agents, get_all_instruction_files
+
+
+@dataclass
+class FileReference:
+    """A reference to another file found in instruction content."""
+
+    path: str
+    line_number: int
+    context: str  # The line containing the reference
+
+
+@dataclass
+class Component:
+    """A discovered component (directory with instruction files)."""
+
+    id: str  # Dot-separated path: "langgraph.app.agents"
+    root: Path
+    instruction_files: list[Path] = field(default_factory=list)
+    imports: list[str] = field(default_factory=list)  # Referenced files
+    children: list[str] = field(default_factory=list)  # Child component IDs
+    parent: str | None = None
+    content_hash: str | None = None
+
+
+@dataclass
+class DiscoveryResult:
+    """Result of discovery operation."""
+
+    target: Path
+    discovered_at: str
+    agents: list[DetectedAgent]
+    components: dict[str, Component]
+    shared_files: list[str]
+    total_instruction_files: int
+    total_references: int
+
+
+# Patterns for extracting file references from markdown
+REFERENCE_PATTERNS = [
+    # Backtick paths: `path/to/file.ext` or `./path/to/file`
+    re.compile(r"`([./][\w\-./]+\.\w+)`"),
+    re.compile(r"`(\.?\.?/[\w\-./]+)`"),
+    # Markdown links: [text](path/to/file)
+    re.compile(r"\[.*?\]\(([./][\w\-./]+\.?\w*)\)"),
+    # Read/See commands: Read `file` or See "file"
+    re.compile(r"(?:Read|See|Check|Load)\s+[`'\"]([^`'\"]+)[`'\"]", re.IGNORECASE),
+    # Numbered lists with paths: 1. Read `.shared/sys.yml`
+    re.compile(r"^\s*\d+\.\s+.*?[`'\"]([./][\w\-./]+)[`'\"]", re.MULTILINE),
+]
+
+
+def extract_references(content: str) -> list[FileReference]:
+    """
+    Extract file references from instruction file content.
+
+    Deterministic: uses regex patterns to find explicit path references.
+
+    Args:
+        content: Markdown content to analyze
+
+    Returns:
+        List of file references found
+    """
+    references: list[FileReference] = []
+    lines = content.split("\n")
+
+    for line_num, line in enumerate(lines, 1):
+        for pattern in REFERENCE_PATTERNS:
+            for match in pattern.finditer(line):
+                path = match.group(1)
+                # Filter out obvious non-paths
+                if _is_valid_path_reference(path):
+                    references.append(
+                        FileReference(
+                            path=path,
+                            line_number=line_num,
+                            context=line.strip()[:100],
+                        )
+                    )
+
+    return references
+
+
+def _is_valid_path_reference(path: str) -> bool:
+    """Check if a string looks like a valid file 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)
+    # Normalize and check for excessive parent refs
+    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 _is_path_within_bounds(path: str, project_root: Path) -> bool:
+    """Check if resolved path stays within project bounds."""
+    try:
+        resolved = (project_root / path).resolve()
+        return resolved.is_relative_to(project_root)
+    except (ValueError, OSError):
+        return False
+
+
+def compute_content_hash(file_path: Path) -> str:
+    """Compute SHA256 hash of file content."""
+    content = file_path.read_bytes()
+    return f"sha256:{hashlib.sha256(content).hexdigest()[:16]}"
+
+
+def discover_components(target: Path, instruction_files: list[Path]) -> dict[str, Component]:
+    """
+    Discover components from instruction file locations.
+
+    Component = directory containing instruction file(s).
+    Hierarchy derived from directory structure.
+
+    Args:
+        target: Project root
+        instruction_files: All discovered instruction files
+
+    Returns:
+        Dict mapping component ID to Component
+    """
+    components: dict[str, Component] = {}
+
+    for file_path in instruction_files:
+        # Get directory containing the instruction file
+        component_dir = file_path.parent
+        relative_dir = component_dir.relative_to(target)
+
+        # Create component ID from path
+        if relative_dir == Path("."):
+            component_id = "root"
+        else:
+            component_id = str(relative_dir).replace("/", ".").replace("\\", ".")
+
+        # Create or update component
+        if component_id not in components:
+            components[component_id] = Component(
+                id=component_id,
+                root=component_dir,
+            )
+
+        component = components[component_id]
+        component.instruction_files.append(file_path)
+
+        # Extract references from file content
+        content = file_path.read_text(encoding="utf-8")
+        refs = extract_references(content)
+        # Filter: only include references that stay within project bounds
+        valid_refs = [r.path for r in refs if _is_path_within_bounds(r.path, target)]
+        component.imports.extend(valid_refs)
+
+        # Compute content hash
+        if component.content_hash is None:
+            component.content_hash = compute_content_hash(file_path)
+
+    # Deduplicate imports
+    for component in components.values():
+        component.imports = sorted(set(component.imports))
+
+    # Build parent-child relationships
+    _build_hierarchy(components)
+
+    return components
+
+
+def _build_hierarchy(components: dict[str, Component]) -> None:
+    """Build parent-child relationships between components."""
+    component_ids = sorted(components.keys())
+
+    for comp_id in component_ids:
+        component = components[comp_id]
+
+        # Find parent (longest matching prefix)
+        parts = comp_id.split(".")
+        if len(parts) > 1:
+            parent_id = ".".join(parts[:-1])
+            if parent_id in components:
+                component.parent = parent_id
+                components[parent_id].children.append(comp_id)
+
+
+def find_shared_files(components: dict[str, Component], target: Path) -> list[str]:
+    """
+    Identify shared files (referenced by multiple components).
+
+    Args:
+        components: Discovered components
+        target: Project root
+
+    Returns:
+        List of shared file paths
+    """
+    # Count references to each file
+    ref_counts: dict[str, int] = {}
+    for component in components.values():
+        for ref in component.imports:
+            ref_counts[ref] = ref_counts.get(ref, 0) + 1
+
+    # Files referenced by 2+ components are shared
+    shared = [path for path, count in ref_counts.items() if count >= 2]
+
+    # Also include common shared directories
+    for pattern in [".shared/**/*", ".ai/shared/**/*", "shared/**/*"]:
+        for path in target.glob(pattern):
+            if path.is_file():
+                rel_path = str(path.relative_to(target))
+                if rel_path not in shared:
+                    shared.append(rel_path)
+
+    return sorted(set(shared))
+
+
+def run_discovery(target: Path) -> DiscoveryResult:
+    """
+    Run full discovery on target directory.
+
+    Deterministic analysis:
+    1. Detect which coding agents are configured
+    2. Find all instruction files
+    3. Extract references from content
+    4. Build component hierarchy
+    5. Identify shared files
+
+    Args:
+        target: Project root to analyze
+
+    Returns:
+        DiscoveryResult with full analysis
+    """
+    # Detect agents
+    agents = detect_agents(target)
+
+    # Get all instruction files
+    instruction_files = get_all_instruction_files(target)
+
+    # Discover components
+    components = discover_components(target, instruction_files)
+
+    # Find shared files
+    shared_files = find_shared_files(components, target)
+
+    # Count total references
+    total_refs = sum(len(c.imports) for c in components.values())
+
+    return DiscoveryResult(
+        target=target,
+        discovered_at=datetime.now(UTC).isoformat(),
+        agents=agents,
+        components=components,
+        shared_files=shared_files,
+        total_instruction_files=len(instruction_files),
+        total_references=total_refs,
+    )
+
+
+def generate_backbone_yaml(result: DiscoveryResult) -> str:
+    """
+    Generate backbone.yml content from discovery result.
+
+    Args:
+        result: Discovery result
+
+    Returns:
+        YAML string for backbone file
+    """
+    data: dict[str, Any] = {
+        "version": 1,
+        "generated_at": result.discovered_at,
+        "generator": "ails discover",
+        "target": str(result.target),
+        "agents": {},
+        "components": {},
+        "shared": result.shared_files,
+        "stats": {
+            "total_instruction_files": result.total_instruction_files,
+            "total_components": len(result.components),
+            "total_references": result.total_references,
+        },
+    }
+
+    # Add detected agents
+    for agent in result.agents:
+        data["agents"][agent.agent_type.id] = {
+            "name": agent.agent_type.name,
+            "instruction_files": [
+                str(f.relative_to(result.target)) for f in agent.instruction_files
+            ],
+            "config_files": [str(f.relative_to(result.target)) for f in agent.config_files],
+            "rule_files": [str(f.relative_to(result.target)) for f in agent.rule_files],
+        }
+
+    # Add components
+    for comp_id, component in sorted(result.components.items()):
+        comp_data: dict[str, Any] = {
+            "root": str(component.root.relative_to(result.target)),
+            "instruction_files": [
+                str(f.relative_to(result.target)) for f in component.instruction_files
+            ],
+            "content_hash": component.content_hash,
+        }
+        if component.imports:
+            comp_data["imports"] = component.imports
+        if component.parent:
+            comp_data["parent"] = component.parent
+        if component.children:
+            comp_data["children"] = component.children
+
+        data["components"][comp_id] = comp_data
+
+    yaml_output: str = yaml.dump(data, default_flow_style=False, sort_keys=False, allow_unicode=True)
+    return yaml_output
+
+
+def save_backbone(target: Path, content: str) -> Path:
+    """
+    Save backbone.yml to target's .reporails directory.
+
+    Args:
+        target: Project root
+        content: YAML content
+
+    Returns:
+        Path to saved file
+    """
+    backbone_dir = target / ".reporails"
+    backbone_dir.mkdir(parents=True, exist_ok=True)
+
+    backbone_path = backbone_dir / "backbone.yml"
+    backbone_path.write_text(content, encoding="utf-8")
+
+    return backbone_path