reporails-cli 0.0.1__py3-none-any.whl

reporails_cli/.env.example

@@ -0,0 +1 @@
+OPENGREP_VERSION=1.51.1

reporails_cli/__init__.py

@@ -0,0 +1,24 @@
+"""Reporails - Lint and score CLAUDE.md files."""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"
+
+from reporails_cli.core.models import (
+    Category,
+    Level,
+    RuleType,
+    Severity,
+    ValidationResult,
+    Violation,
+)
+
+__all__ = [
+    "Category",
+    "Level",
+    "RuleType",
+    "Severity",
+    "ValidationResult",
+    "Violation",
+    "__version__",
+]

reporails_cli/bundled/.semgrepignore

@@ -0,0 +1,51 @@
+# Default semgrepignore for reporails
+# Reduces scan time by excluding common non-instruction directories
+
+# Package managers
+node_modules/
+vendor/
+bower_components/
+
+# Build outputs
+dist/
+build/
+out/
+target/
+*.min.js
+*.min.css
+*.bundle.js
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+.tox/
+.eggs/
+*.egg-info/
+
+# Version control
+.git/
+
+# Coverage and testing
+coverage/
+.coverage
+htmlcov/
+.pytest_cache/
+.nyc_output/
+
+# IDE and editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Large binary files
+*.wasm
+*.so
+*.dylib
+*.dll

reporails_cli/bundled/__init__.py

@@ -0,0 +1,31 @@
+"""Bundled configuration files for reporails CLI.
+
+This package contains CLI-owned configuration:
+- levels.yml: Level definitions and rule-to-level mapping
+- capability-patterns.yml: OpenGrep patterns for capability detection
+- .semgrepignore: Default ignore patterns for OpenGrep/Semgrep
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def get_bundled_path() -> Path:
+    """Get path to bundled configuration directory."""
+    return Path(__file__).parent
+
+
+def get_levels_path() -> Path:
+    """Get path to bundled levels.yml."""
+    return get_bundled_path() / "levels.yml"
+
+
+def get_capability_patterns_path() -> Path:
+    """Get path to bundled capability-patterns.yml."""
+    return get_bundled_path() / "capability-patterns.yml"
+
+
+def get_semgrepignore_path() -> Path:
+    """Get path to bundled .semgrepignore."""
+    return get_bundled_path() / ".semgrepignore"

reporails_cli/bundled/capability-patterns.yml

@@ -0,0 +1,54 @@
+# OpenGrep patterns for capability detection
+# CLI-owned configuration for content analysis (Phase 2)
+
+rules:
+  - id: capability.has-sections
+    message: "Has markdown sections (H2+)"
+    languages: [generic]
+    severity: INFO
+    pattern-regex: "^##+ "
+    paths:
+      include:
+        - "*.md"
+        - "**/CLAUDE.md"
+        - "**/*.md"
+
+  - id: capability.has-imports
+    message: "Has @imports or file references"
+    languages: [generic]
+    severity: INFO
+    pattern-either:
+      - pattern-regex: "@import"
+      - pattern-regex: "@docs/"
+      - pattern-regex: "@\\.shared/"
+      - pattern-regex: "Read `[^`]+`"
+    paths:
+      include:
+        - "*.md"
+        - "**/CLAUDE.md"
+        - "**/*.md"
+
+  - id: capability.has-explicit-constraints
+    message: "Has MUST/MUST NOT/NEVER constraints"
+    languages: [generic]
+    severity: INFO
+    pattern-either:
+      - pattern-regex: "\\bMUST\\b"
+      - pattern-regex: "\\bMUST NOT\\b"
+      - pattern-regex: "\\bNEVER\\b"
+    paths:
+      include:
+        - "*.md"
+        - "**/CLAUDE.md"
+        - "**/*.md"
+
+  - id: capability.has-path-scoped-rules
+    message: "Has path-scoped rules (paths: in frontmatter)"
+    languages: [generic]
+    severity: INFO
+    pattern-regex: "^paths:\\s*$"
+    paths:
+      include:
+        - ".claude/rules/*.md"
+        - ".cursor/rules/*.md"
+        - ".ai/rules/*.md"

reporails_cli/bundled/levels.yml

@@ -0,0 +1,99 @@
+# Level definitions and rule-to-level mapping
+# CLI-owned configuration for orchestration logic
+
+levels:
+  L1:
+    name: Absent
+    required_rules: []
+
+  L2:
+    name: Basic
+    includes: [L1]
+    required_rules:
+      - S1   # Size limits
+      - C1   # Core sections
+      - C2   # Explicit over implicit
+      - C4   # Anti-pattern documentation
+      - C7   # Emphasis discipline
+      - C8   # Instructions over philosophy
+      - C9   # Has project description
+      - C10  # Has NEVER statements
+      - C12  # Has version/date
+      - M5   # Auto-generated content review
+
+  L3:
+    name: Structured
+    includes: [L2]
+    required_rules:
+      - S2   # Progressive disclosure
+      - S3   # No embedded code snippets
+      - S7   # Clear markdown structure
+      - C3   # Context-specific content
+      - C6   # Single source of truth
+      - C11  # Links are valid
+      - E6   # Code block line limit
+      - E7   # Import count
+      - M1   # Version control
+      - M2   # Review process
+
+  L4:
+    name: Abstracted
+    includes: [L3]
+    required_rules:
+      - S4   # Hierarchical memory
+      - S5   # Path-scoped rules
+      - E1   # Deterministic tools for style
+      - E3   # Purpose-based file reading
+      - E4   # Memory reference
+      - E5   # Grep efficiency
+      - E8   # Context window awareness
+      - M7   # Rule snippet length enforcement
+
+  L5:
+    name: Governed
+    includes: [L4]
+    required_rules:
+      - G1   # Organization-level policies
+      - G2   # Team governance structure
+      - G3   # Security rules ownership
+      - G4   # Ownership assignment
+      - G8   # Metrics and CI/CD checks
+      - M3   # Change management
+      - M4   # No conflicting rules
+
+  L6:
+    name: Adaptive
+    includes: [L5]
+    required_rules:
+      - S6   # YAML backbone
+      - C5   # MUST/MUST NOT with context
+      - E2   # Session start ritual
+      - G5   # Contract registry
+      - G6   # Component-contract binding
+      - G7   # Architecture tests
+      - M6   # Map staleness prevention
+
+# Capability score thresholds
+score_thresholds:
+  L1: 0
+  L2: 1
+  L3: 3
+  L4: 5
+  L5: 7
+  L6: 10
+
+# Feature detection for capability scoring
+detection:
+  L6:
+    - has_backbone
+  L5:
+    - component_count_3plus
+    - has_shared_files
+  L4:
+    - has_rules_dir
+  L3:
+    - has_imports
+    - has_multiple_instruction_files
+  L2:
+    - has_instruction_file
+  L1: []

reporails_cli/core/__init__.py

@@ -0,0 +1,35 @@
+"""Core domain logic for reporails."""
+
+from __future__ import annotations
+
+from reporails_cli.core.models import (
+    Category,
+    Check,
+    JudgmentRequest,
+    JudgmentResponse,
+    Level,
+    Rule,
+    RuleType,
+    Severity,
+    ValidationResult,
+    Violation,
+)
+from reporails_cli.core.scorer import (
+    calculate_score,
+    estimate_friction,
+)
+
+__all__ = [
+    "Category",
+    "Check",
+    "JudgmentRequest",
+    "JudgmentResponse",
+    "Level",
+    "Rule",
+    "RuleType",
+    "Severity",
+    "ValidationResult",
+    "Violation",
+    "calculate_score",
+    "estimate_friction",
+]

reporails_cli/core/agents.py

@@ -0,0 +1,147 @@
+"""Agent definitions - coding agent agnostic discovery.
+
+Supports multiple AI coding assistants:
+- Claude (Anthropic)
+- Cursor
+- Windsurf
+- GitHub Copilot
+- Aider
+- Generic/custom
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AgentType:
+    """Definition of a coding agent's file conventions."""
+
+    id: str
+    name: str
+    instruction_patterns: tuple[str, ...]  # Glob patterns for instruction files
+    config_patterns: tuple[str, ...]  # Glob patterns for config files
+    rule_patterns: tuple[str, ...]  # Glob patterns for rule/snippet files
+
+
+# Known coding agents and their conventions
+KNOWN_AGENTS: dict[str, AgentType] = {
+    "claude": AgentType(
+        id="claude",
+        name="Claude (Anthropic)",
+        instruction_patterns=("CLAUDE.md", "**/CLAUDE.md"),
+        config_patterns=(".claude/settings.json", ".claude/mcp.json"),
+        rule_patterns=(".claude/rules/*.md", ".claude/**/*.md"),
+    ),
+    "cursor": AgentType(
+        id="cursor",
+        name="Cursor",
+        instruction_patterns=(".cursorrules", ".cursor/rules/*.md"),
+        config_patterns=(".cursor/settings.json",),
+        rule_patterns=(".cursor/rules/*.md",),
+    ),
+    "windsurf": AgentType(
+        id="windsurf",
+        name="Windsurf",
+        instruction_patterns=(".windsurfrules",),
+        config_patterns=(),
+        rule_patterns=(),
+    ),
+    "copilot": AgentType(
+        id="copilot",
+        name="GitHub Copilot",
+        instruction_patterns=(".github/copilot-instructions.md",),
+        config_patterns=(),
+        rule_patterns=(),
+    ),
+    "aider": AgentType(
+        id="aider",
+        name="Aider",
+        instruction_patterns=(".aider.conf.yml", "CONVENTIONS.md"),
+        config_patterns=(".aider.conf.yml",),
+        rule_patterns=(),
+    ),
+    "generic": AgentType(
+        id="generic",
+        name="Generic AI Instructions",
+        instruction_patterns=("AGENTS.md", ".ai/instructions.md", ".ai/**/*.md"),
+        config_patterns=(),
+        rule_patterns=(".ai/rules/*.md",),
+    ),
+}
+
+
+@dataclass
+class DetectedAgent:
+    """An agent detected in a project."""
+
+    agent_type: AgentType
+    instruction_files: list[Path] = field(default_factory=list)
+    config_files: list[Path] = field(default_factory=list)
+    rule_files: list[Path] = field(default_factory=list)
+
+
+def detect_agents(target: Path) -> list[DetectedAgent]:
+    """
+    Detect which coding agents are configured in the target directory.
+
+    Scans for known file patterns and returns detected agents with their files.
+
+    Args:
+        target: Project root to scan
+
+    Returns:
+        List of detected agents with their associated files
+    """
+    detected: list[DetectedAgent] = []
+
+    for _agent_id, agent_type in KNOWN_AGENTS.items():
+        instruction_files: list[Path] = []
+        config_files: list[Path] = []
+        rule_files: list[Path] = []
+
+        # Find instruction files
+        for pattern in agent_type.instruction_patterns:
+            instruction_files.extend(target.glob(pattern))
+
+        # Find config files
+        for pattern in agent_type.config_patterns:
+            config_files.extend(target.glob(pattern))
+
+        # Find rule files
+        for pattern in agent_type.rule_patterns:
+            rule_files.extend(target.glob(pattern))
+
+        # Only include if we found at least one instruction file
+        if instruction_files:
+            detected.append(
+                DetectedAgent(
+                    agent_type=agent_type,
+                    instruction_files=sorted(set(instruction_files)),
+                    config_files=sorted(set(config_files)),
+                    rule_files=sorted(set(rule_files)),
+                )
+            )
+
+    return detected
+
+
+def get_all_instruction_files(target: Path) -> list[Path]:
+    """
+    Get all instruction files for all detected agents.
+
+    Args:
+        target: Project root to scan
+
+    Returns:
+        Deduplicated list of all instruction file paths
+    """
+    all_files: set[Path] = set()
+
+    for detected in detect_agents(target):
+        all_files.update(detected.instruction_files)
+        all_files.update(detected.rule_files)
+
+    return sorted(all_files)

reporails_cli/core/applicability.py

@@ -0,0 +1,150 @@
+"""Feature detection (filesystem) and rule applicability.
+
+Phase 1 of capability detection - scans filesystem for features.
+Phase 2 (content detection) is in capability.py.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from reporails_cli.core.levels import get_rules_for_level
+from reporails_cli.core.models import DetectedFeatures, Level, Rule
+
+
+def detect_features_filesystem(target: Path) -> DetectedFeatures:
+    """Detect project features from file structure.
+
+    Phase 1 of capability detection - filesystem only, no content analysis.
+
+    Args:
+        target: Project root path
+
+    Returns:
+        DetectedFeatures with filesystem-based indicators
+    """
+    features = DetectedFeatures()
+
+    # Check for CLAUDE.md at root
+    root_claude = target / "CLAUDE.md"
+    features.has_claude_md = root_claude.exists()
+    features.has_instruction_file = features.has_claude_md
+
+    # Check for .claude/rules/
+    rules_dir = target / ".claude" / "rules"
+    features.has_rules_dir = rules_dir.exists() and any(rules_dir.glob("*.md"))
+
+    # Check for other agent rules directories
+    other_rules = [".cursor/rules", ".ai/rules"]
+    for pattern in other_rules:
+        other_dir = target / pattern
+        if other_dir.exists() and any(other_dir.glob("*.md")):
+            features.has_rules_dir = True
+            break
+
+    # Check for backbone.yml
+    backbone_path = target / ".reporails" / "backbone.yml"
+    features.has_backbone = backbone_path.exists()
+
+    # Count instruction files
+    claude_files = list(target.rglob("CLAUDE.md"))
+    features.instruction_file_count = len(claude_files)
+    features.has_multiple_instruction_files = len(claude_files) > 1
+
+    if features.instruction_file_count > 0:
+        features.has_instruction_file = True
+
+    # Check for hierarchical structure (nested CLAUDE.md)
+    for cf in claude_files:
+        if cf.parent != target:
+            features.has_hierarchical_structure = True
+            break
+
+    # Check for @imports in content (simple check, full check in Phase 2)
+    if features.has_claude_md:
+        try:
+            content = root_claude.read_text(encoding="utf-8")
+            features.has_imports = "@" in content
+        except (OSError, UnicodeDecodeError):
+            pass
+
+    # Check for shared files
+    shared_patterns = [".shared", "shared", ".ai/shared"]
+    for pattern in shared_patterns:
+        if (target / pattern).exists():
+            features.has_shared_files = True
+            break
+
+    # Count components from backbone if present
+    if features.has_backbone:
+        try:
+            backbone_content = backbone_path.read_text(encoding="utf-8")
+            backbone_data = yaml.safe_load(backbone_content)
+            features.component_count = len(backbone_data.get("components", {}))
+        except (yaml.YAMLError, OSError):
+            pass
+
+    return features
+
+
+def get_applicable_rules(rules: dict[str, Rule], level: Level) -> dict[str, Rule]:
+    """Filter rules to those applicable at the given level.
+
+    Rules apply at their minimum level and above.
+
+    Args:
+        rules: Dict of all rules
+        level: Detected capability level
+
+    Returns:
+        Dict of applicable rules
+    """
+    # Get rule IDs for this level from levels.yml
+    applicable_ids = get_rules_for_level(level)
+
+    # Filter rules
+    return {k: v for k, v in rules.items() if k in applicable_ids}
+
+
+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
+    if features.instruction_file_count == 0:
+        parts.append("No instruction files")
+    elif features.instruction_file_count == 1:
+        parts.append("1 instruction file")
+    else:
+        parts.append(f"{features.instruction_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"
+
+
+# Legacy alias for backward compatibility
+def detect_features(target: Path) -> DetectedFeatures:
+    """Legacy alias for detect_features_filesystem()."""
+    return detect_features_filesystem(target)