invar-tools 1.3.3__py3-none-any.whl → 1.5.0__py3-none-any.whl

invar/shell/contract_coverage.py

@@ -0,0 +1,358 @@
+"""Contract coverage analysis for DX-63 - Shell layer.
+
+I/O operations for checking contract coverage, detecting batch creation,
+and formatting reports. Different from coverage.py which handles branch coverage.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path  # noqa: TC003 - used at runtime
+
+from returns.result import Failure, Result, Success
+
+from invar.core.trivial_detection import (
+    TrivialContract,
+    analyze_contracts_in_source,
+)
+
+
+@dataclass
+class BatchWarning:
+    """Warning for batch file creation without contracts.
+
+    Examples:
+        >>> bw = BatchWarning(
+        ...     file_count=5,
+        ...     files=[("src/a.py", 3, 0), ("src/b.py", 4, 1)],
+        ...     message="Multiple new files with low coverage"
+        ... )
+        >>> bw.file_count
+        5
+    """
+
+    file_count: int
+    files: list[tuple[str, int, int]]  # (file, total_funcs, with_contracts)
+    message: str
+
+
+@dataclass
+class ContractCoverageReport:
+    """Contract coverage check result.
+
+    Examples:
+        >>> report = ContractCoverageReport(
+        ...     files_checked=3,
+        ...     total_functions=10,
+        ...     functions_with_contracts=8,
+        ...     trivial_contracts=[],
+        ...     batch_warning=None
+        ... )
+        >>> report.coverage_pct
+        80
+        >>> report.ready_for_build
+        True
+    """
+
+    files_checked: int = 0
+    total_functions: int = 0
+    functions_with_contracts: int = 0
+    trivial_contracts: list[TrivialContract] = field(default_factory=list)
+    batch_warning: BatchWarning | None = None
+
+    @property
+    def coverage_pct(self) -> int:
+        """Get coverage percentage.
+
+        Examples:
+            >>> ContractCoverageReport(total_functions=10, functions_with_contracts=7).coverage_pct
+            70
+            >>> ContractCoverageReport(total_functions=0, functions_with_contracts=0).coverage_pct
+            100
+        """
+        if self.total_functions == 0:
+            return 100
+        return int(100 * self.functions_with_contracts / self.total_functions)
+
+    @property
+    def trivial_count(self) -> int:
+        """Count of trivial contracts."""
+        return len(self.trivial_contracts)
+
+    @property
+    def ready_for_build(self) -> bool:
+        """Check if ready for BUILD phase.
+
+        Ready when:
+        - Coverage >= 80%
+        - No trivial contracts
+        - No batch warning
+
+        Examples:
+            >>> ContractCoverageReport(total_functions=10, functions_with_contracts=10).ready_for_build
+            True
+            >>> ContractCoverageReport(total_functions=10, functions_with_contracts=5).ready_for_build
+            False
+        """
+        if self.trivial_contracts:
+            return False
+        if self.batch_warning:
+            return False
+        return self.coverage_pct >= 80
+
+
+def count_contracts_in_file(
+    file_path: Path,
+) -> Result[tuple[int, int, list[TrivialContract]], str]:
+    """Count functions and contracts in a file.
+
+    Returns: Result containing (total_functions, functions_with_contracts, trivial_contracts)
+    """
+    if not file_path.exists():
+        return Failure(f"File not found: {file_path}")
+
+    try:
+        source = file_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as e:
+        return Failure(f"Encoding error: {e}")
+
+    result = analyze_contracts_in_source(source, str(file_path))
+    return Success(result)
+
+
+def get_changed_python_files(path: Path) -> Result[list[Path], str]:
+    """Get Python files changed in git."""
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            cwd=path,
+            check=False,
+        )
+        if result.returncode != 0:
+            return Failure(f"Git error: {result.stderr}")
+
+        files = []
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+            # Status is first 2 chars, then space, then filename
+            status = line[:2]
+            filename = line[3:].strip()
+
+            # Include new, modified, or untracked Python files
+            if filename.endswith(".py") and status.strip():
+                file_path = path / filename
+                if file_path.exists():
+                    files.append(file_path)
+
+        return Success(files)
+    except FileNotFoundError:
+        return Failure("Git not found")
+
+
+def calculate_contract_coverage(
+    path: Path, changed_only: bool = False
+) -> Result[ContractCoverageReport, str]:
+    """Calculate contract coverage for a path (file or directory)."""
+    report = ContractCoverageReport()
+
+    if path.is_file():
+        if path.suffix == ".py":
+            result = count_contracts_in_file(path)
+            if isinstance(result, Failure):
+                return result
+            total, with_contracts, trivials = result.unwrap()
+            report.files_checked = 1
+            report.total_functions = total
+            report.functions_with_contracts = with_contracts
+            report.trivial_contracts = trivials
+    else:
+        # Get files to check
+        if changed_only:
+            files_result = get_changed_python_files(path)
+            if isinstance(files_result, Failure):
+                return files_result
+            files = files_result.unwrap()
+        else:
+            files = list(path.rglob("*.py"))
+
+        # Filter out test files, __pycache__, etc.
+        files = [
+            f
+            for f in files
+            if "__pycache__" not in str(f)
+            and "test_" not in f.name
+            and "_test.py" not in f.name
+            and ".venv" not in str(f)
+        ]
+
+        for file_path in files:
+            result = count_contracts_in_file(file_path)
+            if isinstance(result, Failure):
+                continue  # Skip files with errors
+            total, with_contracts, trivials = result.unwrap()
+            report.files_checked += 1
+            report.total_functions += total
+            report.functions_with_contracts += with_contracts
+            report.trivial_contracts.extend(trivials)
+
+        # Check for batch creation
+        batch_result = detect_batch_creation(path)
+        if isinstance(batch_result, Success):
+            report.batch_warning = batch_result.unwrap()
+
+    return Success(report)
+
+
+def detect_batch_creation(
+    path: Path, threshold: int = 3
+) -> Result[BatchWarning | None, str]:
+    """Detect batch file creation without contracts.
+
+    Returns BatchWarning if >= threshold new/untracked files have < 50% coverage.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            cwd=path,
+            check=False,
+        )
+        if result.returncode != 0:
+            return Success(None)
+
+        uncovered_files: list[tuple[str, int, int]] = []
+
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+
+            status = line[:2]
+            filename = line[3:].strip()
+
+            # Check new/untracked Python files (status starts with ? or A)
+            if filename.endswith(".py") and status[0] in ("?", "A"):
+                file_path = path / filename
+                if file_path.exists():
+                    count_result = count_contracts_in_file(file_path)
+                    if isinstance(count_result, Success):
+                        total, with_contracts, _ = count_result.unwrap()
+                        if total > 0:
+                            coverage_pct = int(100 * with_contracts / total)
+                            if coverage_pct < 50:
+                                uncovered_files.append(
+                                    (filename, total, with_contracts)
+                                )
+
+        if len(uncovered_files) >= threshold:
+            return Success(
+                BatchWarning(
+                    file_count=len(uncovered_files),
+                    files=uncovered_files,
+                    message="Multiple new files with low contract coverage",
+                )
+            )
+
+        return Success(None)
+
+    except FileNotFoundError:
+        return Success(None)
+
+
+# @shell_orchestration: Report formatting tightly coupled with CLI output
+def format_contract_coverage_report(report: ContractCoverageReport) -> str:
+    """Format coverage report for human-readable output."""
+    lines = [
+        "Contract Coverage Check",
+        "=" * 40,
+        f"Files: {report.files_checked} | Functions: {report.total_functions}",
+        "",
+    ]
+
+    # Coverage line
+    coverage_pct = report.coverage_pct
+    if coverage_pct >= 80:
+        lines.append(
+            f"Coverage: {report.functions_with_contracts}/{report.total_functions} "
+            f"({coverage_pct}%) \u2713"
+        )
+    else:
+        lines.append(
+            f"Coverage: {report.functions_with_contracts}/{report.total_functions} "
+            f"({coverage_pct}%) \u2717"
+        )
+
+    # Trivial contracts
+    total = max(1, report.total_functions)
+    if report.trivial_contracts:
+        trivial_pct = int(100 * report.trivial_count / total)
+        lines.append(f"Trivial:  {report.trivial_count}/{report.total_functions} ({trivial_pct}%) \u2717")
+        lines.append("")
+        lines.append("\u2717 Trivial contracts detected:")
+        for tc in report.trivial_contracts:
+            lines.append(
+                f"  - {tc.file}:{tc.line} {tc.function_name} "
+                f"@{tc.contract_type}({tc.expression})"
+            )
+    else:
+        lines.append(f"Trivial:  0/{report.total_functions} (0%) \u2713")
+
+    # Batch warning
+    if report.batch_warning:
+        lines.append("")
+        lines.append(
+            f"\u26a0 BATCH WARNING: {report.batch_warning.file_count} "
+            "new files with low coverage"
+        )
+        for filename, total_f, with_c in report.batch_warning.files:
+            lines.append(f"  - {filename} ({with_c}/{total_f})")
+        lines.append("")
+        lines.append("Recommendation: Add contracts incrementally, one file at a time.")
+
+    # Final status
+    lines.append("")
+    if report.ready_for_build:
+        lines.append("Ready for BUILD phase.")
+    else:
+        lines.append("Not ready for BUILD phase.")
+
+    return "\n".join(lines)
+
+
+# @shell_orchestration: Output formatting for CLI integration
+def format_contract_coverage_agent(report: ContractCoverageReport) -> dict:
+    """Format coverage report for agent JSON output."""
+    return {
+        "status": "passed" if report.ready_for_build else "failed",
+        "contract_coverage": {
+            "files_checked": report.files_checked,
+            "total_functions": report.total_functions,
+            "functions_with_contracts": report.functions_with_contracts,
+            "coverage_pct": report.coverage_pct,
+            "trivial_count": report.trivial_count,
+            "trivial_contracts": [
+                {
+                    "file": tc.file,
+                    "line": tc.line,
+                    "function": tc.function_name,
+                    "type": tc.contract_type,
+                    "expression": tc.expression,
+                }
+                for tc in report.trivial_contracts
+            ],
+            "batch_warning": (
+                {
+                    "file_count": report.batch_warning.file_count,
+                    "files": report.batch_warning.files,
+                    "message": report.batch_warning.message,
+                }
+                if report.batch_warning
+                else None
+            ),
+            "ready_for_build": report.ready_for_build,
+        },
+    }

invar/shell/guard_output.py

@@ -151,6 +151,8 @@ def output_rich(
                     icon = "[red]ERROR[/red]"
                 elif v.severity == Severity.WARNING:
                     icon = "[yellow]WARN[/yellow]"
+                elif v.severity == Severity.SUGGEST:
+                    icon = "[magenta]SUGGEST[/magenta]"  # DX-61
                 else:
                     icon = "[blue]INFO[/blue]"
                 ln = f":{v.line}" if v.line else ""
@@ -182,6 +184,9 @@ def output_rich(
     )
     if report.infos > 0:
         summary += f"\nInfos: {report.infos}"
+    # DX-61: Show suggestions count if any
+    if report.suggests > 0:
+        summary += f"\n[magenta]Suggestions: {report.suggests}[/magenta]"
     console.print(summary)
 
     # P24: Contract coverage statistics (only show if core files exist)

invar/shell/pattern_integration.py

@@ -0,0 +1,234 @@
+"""
+Pattern Detection Integration for Guard (DX-61).
+
+Shell module: handles file I/O for pattern detection.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path  # noqa: TC003 - used at runtime (path.exists, rglob, etc)
+
+from deal import post, pre
+from returns.result import Failure, Result, Success
+
+from invar.core.models import RuleConfig, Severity, Violation
+from invar.core.patterns import PatternSuggestion, detect_patterns
+from invar.core.patterns.types import Confidence, Priority
+
+
+# @shell_complexity: File collection and filtering requires multiple conditions
+@pre(lambda path, files: path.exists())
+@post(lambda result: isinstance(result, (Success, Failure)))
+def run_pattern_detection(
+    path: Path,
+    files: list[Path] | None = None,
+) -> Result[list[PatternSuggestion], str]:
+    """
+    Run pattern detection on source files.
+
+    DX-61: Detects opportunities for functional patterns like
+    NewType, Validation, NonEmpty, Literal, and ExhaustiveMatch.
+
+    Args:
+        path: Project root directory
+        files: Optional list of specific files to check (None = all Python files)
+
+    Returns:
+        Success with list of suggestions, or Failure with error message
+
+    @pre: path exists
+    @post: returns Result type
+    """
+    suggestions: list[PatternSuggestion] = []
+
+    try:
+        # Collect Python files
+        if files:
+            python_files = [f for f in files if f.suffix == ".py"]
+        else:
+            python_files = list(path.rglob("*.py"))
+
+        # Filter out test files and hidden directories
+        python_files = [
+            f for f in python_files
+            if not any(part.startswith(".") for part in f.parts)
+            and "test" not in f.name.lower()
+            and "__pycache__" not in str(f)
+        ]
+
+        for file_path in python_files:
+            try:
+                source = file_path.read_text(encoding="utf-8")
+                result = detect_patterns(str(file_path), source)
+                suggestions.extend(result.suggestions)
+            except (OSError, UnicodeDecodeError):
+                # Skip files that can't be read
+                continue
+
+        return Success(suggestions)
+
+    except Exception as e:
+        return Failure(f"Pattern detection failed: {e}")
+
+
+# @shell_orchestration: Converts pattern suggestions to violations for Guard output integration
+@pre(lambda suggestion: suggestion is not None)
+@post(lambda result: result.severity == Severity.SUGGEST)
+def suggestion_to_violation(suggestion: PatternSuggestion) -> Violation:
+    """
+    Convert pattern suggestion to Guard violation format.
+
+    DX-61: Enables pattern suggestions to appear in Guard output
+    alongside other violations.
+
+    Args:
+        suggestion: Pattern suggestion from detector
+
+    Returns:
+        Violation with SUGGEST severity
+
+    @pre: suggestion is not None
+    @post: result has SUGGEST severity
+
+    >>> from invar.core.patterns.types import (
+    ...     PatternSuggestion, PatternID, Confidence, Priority, Location
+    ... )
+    >>> suggestion = PatternSuggestion(
+    ...     pattern_id=PatternID.NEWTYPE,
+    ...     location=Location(file="test.py", line=10),
+    ...     message="3 str params",
+    ...     confidence=Confidence.HIGH,
+    ...     priority=Priority.P0,
+    ...     current_code="def f(a, b, c): pass",
+    ...     suggested_pattern="NewType",
+    ...     reference_file=".invar/examples/functional.py",
+    ...     reference_pattern="Pattern 1",
+    ... )
+    >>> violation = suggestion_to_violation(suggestion)
+    >>> violation.severity == Severity.SUGGEST
+    True
+    >>> "Pattern 1" in violation.suggestion
+    True
+    """
+    # Build suggestion text with reference
+    suggestion_text = (
+        f"{suggestion.suggested_pattern}\n"
+        f"See: {suggestion.reference_file} - {suggestion.reference_pattern}"
+    )
+
+    return Violation(
+        file=suggestion.location.file,
+        line=suggestion.location.line,
+        rule=f"pattern_{suggestion.pattern_id.value}",
+        severity=Severity.SUGGEST,
+        message=f"[{suggestion.confidence.value.upper()}] {suggestion.message}",
+        suggestion=suggestion_text,
+    )
+
+
+# @shell_orchestration: Batch converts pattern suggestions to violations for Guard report
+@pre(lambda suggestions: suggestions is not None)
+@post(lambda result: all(v.severity == Severity.SUGGEST for v in result))
+def suggestions_to_violations(
+    suggestions: list[PatternSuggestion],
+) -> list[Violation]:
+    """
+    Convert all pattern suggestions to violations.
+
+    Args:
+        suggestions: List of pattern suggestions
+
+    Returns:
+        List of violations with SUGGEST severity
+
+    @pre: suggestions is not None
+    @post: all results have SUGGEST severity
+    """
+    return [suggestion_to_violation(s) for s in suggestions]
+
+
+# DX-61: Confidence level ordering for filtering
+_CONFIDENCE_ORDER = {
+    Confidence.LOW: 0,
+    Confidence.MEDIUM: 1,
+    Confidence.HIGH: 2,
+}
+
+
+# @shell_orchestration: Filters suggestions based on RuleConfig settings
+# @shell_complexity: Multiple config filters (confidence, priority, exclusion) require branching
+@pre(lambda suggestions, config: suggestions is not None and config is not None)
+@post(lambda result: isinstance(result, list))
+def filter_suggestions(
+    suggestions: list[PatternSuggestion],
+    config: RuleConfig,
+) -> list[PatternSuggestion]:
+    """
+    Filter suggestions based on configuration.
+
+    DX-61: Applies confidence, priority, and exclusion filters.
+
+    Args:
+        suggestions: List of pattern suggestions
+        config: Rule configuration with pattern settings
+
+    Returns:
+        Filtered list of suggestions
+
+    @pre: suggestions and config are not None
+    @post: returns a list
+
+    >>> from invar.core.patterns.types import (
+    ...     PatternSuggestion, PatternID, Confidence, Priority, Location
+    ... )
+    >>> from invar.core.models import RuleConfig
+    >>> config = RuleConfig(pattern_min_confidence="high")
+    >>> low = PatternSuggestion(
+    ...     pattern_id=PatternID.NEWTYPE,
+    ...     location=Location(file="t.py", line=1),
+    ...     message="msg", confidence=Confidence.LOW, priority=Priority.P0,
+    ...     current_code="x", suggested_pattern="X", reference_file="f.py",
+    ...     reference_pattern="P1"
+    ... )
+    >>> high = PatternSuggestion(
+    ...     pattern_id=PatternID.VALIDATION,
+    ...     location=Location(file="t.py", line=2),
+    ...     message="msg", confidence=Confidence.HIGH, priority=Priority.P0,
+    ...     current_code="x", suggested_pattern="X", reference_file="f.py",
+    ...     reference_pattern="P1"
+    ... )
+    >>> result = filter_suggestions([low, high], config)
+    >>> len(result)
+    1
+    >>> result[0].confidence == Confidence.HIGH
+    True
+    """
+    # Parse minimum confidence level
+    min_conf_str = config.pattern_min_confidence.lower()
+    min_conf_map = {"low": Confidence.LOW, "medium": Confidence.MEDIUM, "high": Confidence.HIGH}
+    min_confidence = min_conf_map.get(min_conf_str, Confidence.MEDIUM)
+    min_conf_order = _CONFIDENCE_ORDER[min_confidence]
+
+    # Parse allowed priorities (only P0 and P1 exist, skip invalid values)
+    priority_map = {"P0": Priority.P0, "P1": Priority.P1}
+    allowed_priorities = {
+        priority_map[p] for p in config.pattern_priorities if p in priority_map
+    }
+
+    # Parse excluded patterns
+    excluded_patterns = set(config.pattern_exclude)
+
+    filtered = []
+    for s in suggestions:
+        # Check confidence threshold
+        if _CONFIDENCE_ORDER[s.confidence] < min_conf_order:
+            continue
+        # Check priority filter
+        if s.priority not in allowed_priorities:
+            continue
+        # Check exclusion list
+        if s.pattern_id.value in excluded_patterns:
+            continue
+        filtered.append(s)
+
+    return filtered

invar/shell/templates.py

@@ -434,7 +434,7 @@ Find your Python path: `python -c "import sys; print(sys.executable)"`
 
 ```bash
 # Recommended: use uvx (no installation needed)
-uvx --from invar-tools invar guard
+uvx invar-tools guard
 
 # Or install globally
 pip install invar-tools
@@ -449,7 +449,7 @@ Run the MCP server directly:
 
 ```bash
 # Using uvx
-uvx --from invar-tools invar mcp
+uvx invar-tools mcp
 
 # Or if installed
 invar mcp

invar/shell/testing.py

@@ -136,13 +136,24 @@ def run_doctests_on_files(
         return Success({"status": "skipped", "reason": "no files", "files": []})
 
     # Filter to Python files only
-    # Exclude: conftest.py (pytest config), templates/examples/ (source templates, not user examples)
+    # Exclude: conftest.py (pytest config), templates/examples/ (source templates),
+    # .invar/examples/ (documentation examples with intentionally "bad" patterns)
+    def is_excluded(f: Path) -> bool:
+        """Check if path matches excluded patterns using path parts (not substring)."""
+        parts = f.parts
+        # Check for consecutive "templates/examples" or ".invar/examples"
+        for i in range(len(parts) - 1):
+            if (parts[i] == "templates" and parts[i + 1] == "examples") or \
+               (parts[i] == ".invar" and parts[i + 1] == "examples"):
+                return True
+        return False
+
     py_files = [
         f for f in files
         if f.suffix == ".py"
         and f.exists()
         and f.name != "conftest.py"
-        and "templates/examples" not in str(f)
+        and not is_excluded(f)
     ]
     if not py_files:
         return Success({"status": "skipped", "reason": "no Python files", "files": []})

invar/templates/config/CLAUDE.md.jinja

@@ -86,6 +86,7 @@ src/{project}/
 | INVAR.md | Invar | No | Protocol (`invar update` to sync) |
 | CLAUDE.md | User | Yes | Project customization (this file) |
 | .invar/context.md | User | Yes | Project state, lessons learned |
+| .invar/project-additions.md | User | Yes | Project rules → injected into CLAUDE.md |
 | .invar/examples/ | Invar | No | **Must read:** Core/Shell patterns, workflow |
 
 ## Visible Workflow (DX-30)