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

invar/core/patterns/registry.py

@@ -0,0 +1,234 @@
+"""
+Pattern Detector Registry (DX-61).
+
+Central registry for all pattern detectors. Provides unified API
+for running detection across multiple patterns.
+"""
+
+import ast
+from functools import lru_cache
+
+from deal import post, pre
+
+from invar.core.patterns.detector import PatternDetector
+from invar.core.patterns.p0_exhaustive import ExhaustiveMatchDetector
+from invar.core.patterns.p0_literal import LiteralDetector
+from invar.core.patterns.p0_newtype import NewTypeDetector
+from invar.core.patterns.p0_nonempty import NonEmptyDetector
+from invar.core.patterns.p0_validation import ValidationDetector
+from invar.core.patterns.types import (
+    Confidence,
+    DetectionResult,
+    PatternID,
+    PatternSuggestion,
+    Priority,
+)
+
+
+class PatternRegistry:
+    """
+    Registry for pattern detectors.
+
+    Manages registration and execution of all pattern detectors.
+    Provides filtering by priority and confidence levels.
+
+    >>> registry = PatternRegistry()
+    >>> len(registry.detectors) > 0
+    True
+    >>> PatternID.NEWTYPE in [d.pattern_id for d in registry.detectors]
+    True
+    """
+
+    # @invar:allow missing_contract: __init__ takes only self, no inputs to validate
+    def __init__(self) -> None:
+        """Initialize with all P0 detectors."""
+        self._detectors: list[PatternDetector] = [
+            NewTypeDetector(),
+            ValidationDetector(),
+            NonEmptyDetector(),
+            LiteralDetector(),
+            ExhaustiveMatchDetector(),
+        ]
+
+    @property
+    @post(lambda result: len(result) > 0)
+    def detectors(self) -> list[PatternDetector]:
+        """Get all registered detectors."""
+        return self._detectors
+
+    @post(lambda result: result is not None)
+    def get_detectors_by_priority(self, priority: Priority) -> list[PatternDetector]:
+        """
+        Get detectors filtered by priority.
+
+        >>> registry = PatternRegistry()
+        >>> p0_detectors = registry.get_detectors_by_priority(Priority.P0)
+        >>> len(p0_detectors) >= 5
+        True
+        """
+        return [d for d in self._detectors if d.priority == priority]
+
+    @pre(lambda self, file_path, source, min_confidence=None, priority_filter=None: len(file_path) > 0)
+    @post(lambda result: result is not None)
+    def detect_file(
+        self,
+        file_path: str,
+        source: str,
+        min_confidence: Confidence = Confidence.LOW,
+        priority_filter: Priority | None = None,
+    ) -> DetectionResult:
+        """
+        Run all detectors on a file's source code.
+
+        Args:
+            file_path: Path to the Python file (for location reporting)
+            source: Source code to analyze
+            min_confidence: Minimum confidence level to include
+            priority_filter: Optional priority filter (None = all priorities)
+
+        Returns:
+            DetectionResult with all suggestions
+
+        >>> registry = PatternRegistry()
+        >>> code = '''
+        ... def process(user_id: str, order_id: str, product_id: str):
+        ...     pass
+        ... '''
+        >>> result = registry.detect_file("test.py", source=code)
+        >>> result.has_suggestions
+        True
+        """
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            # Skip files with syntax errors
+            return DetectionResult(
+                file=file_path,
+                suggestions=[],
+                patterns_checked=[],
+            )
+
+        detectors = self._detectors
+        if priority_filter is not None:
+            detectors = self.get_detectors_by_priority(priority_filter)
+
+        all_suggestions: list[PatternSuggestion] = []
+        patterns_checked: list[PatternID] = []
+
+        for detector in detectors:
+            patterns_checked.append(detector.pattern_id)
+            suggestions = detector.detect(tree, file_path)
+            all_suggestions.extend(suggestions)
+
+        # Filter by confidence
+        result = DetectionResult(
+            file=file_path,
+            suggestions=all_suggestions,
+            patterns_checked=patterns_checked,
+        )
+
+        filtered_suggestions = result.filter_by_confidence(min_confidence)
+
+        return DetectionResult(
+            file=file_path,
+            suggestions=filtered_suggestions,
+            patterns_checked=patterns_checked,
+        )
+
+    @post(lambda result: result is not None)
+    def detect_sources(
+        self,
+        sources: list[tuple[str, str]],
+        min_confidence: Confidence = Confidence.LOW,
+        priority_filter: Priority | None = None,
+    ) -> list[DetectionResult]:
+        """
+        Run detection on multiple sources.
+
+        Args:
+            sources: List of (file_path, source_code) tuples
+
+        >>> registry = PatternRegistry()
+        >>> results = registry.detect_sources([])
+        >>> len(results)
+        0
+        """
+        results = []
+        for file_path, source in sources:
+            result = self.detect_file(
+                file_path,
+                source,
+                min_confidence=min_confidence,
+                priority_filter=priority_filter,
+            )
+            results.append(result)
+        return results
+
+    @post(lambda result: result is not None)
+    def format_suggestions(
+        self, suggestions: list[PatternSuggestion], verbose: bool = False
+    ) -> str:
+        """
+        Format suggestions for display.
+
+        >>> from invar.core.patterns.types import PatternSuggestion, PatternID, Confidence, Priority, Location
+        >>> registry = PatternRegistry()
+        >>> suggestions = [
+        ...     PatternSuggestion(
+        ...         pattern_id=PatternID.NEWTYPE,
+        ...         location=Location(file="test.py", line=10),
+        ...         message="Test",
+        ...         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",
+        ...     )
+        ... ]
+        >>> output = registry.format_suggestions(suggestions)
+        >>> "SUGGEST" in output
+        True
+        """
+        if not suggestions:
+            return ""
+
+        if verbose:
+            return "\n\n".join(s.format_for_guard() for s in suggestions)
+        else:
+            # Compact format
+            lines = []
+            for s in suggestions:
+                lines.append(f"[{s.severity}] {s.location}: {s.message}")
+            return "\n".join(lines)
+
+
+@lru_cache(maxsize=1)
+@post(lambda result: result is not None)
+def get_registry() -> PatternRegistry:
+    """
+    Get the global pattern registry (thread-safe via lru_cache).
+
+    >>> registry = get_registry()
+    >>> isinstance(registry, PatternRegistry)
+    True
+    """
+    return PatternRegistry()
+
+
+@pre(lambda file_path, source, min_confidence=None: len(file_path) > 0)
+@post(lambda result: result is not None)
+def detect_patterns(
+    file_path: str,
+    source: str,
+    min_confidence: Confidence = Confidence.LOW,
+) -> DetectionResult:
+    """
+    Convenience function for pattern detection.
+
+    >>> code = "def f(a: str, b: str, c: str): pass"
+    >>> result = detect_patterns("test.py", source=code)
+    >>> isinstance(result, DetectionResult)
+    True
+    """
+    return get_registry().detect_file(file_path, source, min_confidence)

invar/core/patterns/types.py

@@ -0,0 +1,167 @@
+"""
+Pattern Detection Types (DX-61).
+
+Core types for the functional pattern guidance system.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from deal import post, pre
+
+
+class PatternID(str, Enum):
+    """Unique identifier for each pattern."""
+
+    # P0 - Core patterns
+    NEWTYPE = "newtype"
+    VALIDATION = "validation"
+    NONEMPTY = "nonempty"
+    LITERAL = "literal"
+    EXHAUSTIVE = "exhaustive"
+
+    # P1 - Extended patterns (future)
+    SMART_CONSTRUCTOR = "smart_constructor"
+    STRUCTURED_ERROR = "structured_error"
+
+
+class Confidence(str, Enum):
+    """Confidence level for pattern suggestions."""
+
+    HIGH = "high"  # Strong signal, very likely applicable
+    MEDIUM = "medium"  # Moderate signal, likely applicable
+    LOW = "low"  # Weak signal, possibly applicable
+
+
+class Priority(str, Enum):
+    """Pattern priority tier."""
+
+    P0 = "P0"  # Core patterns, always suggested
+    P1 = "P1"  # Extended patterns, suggested when relevant
+
+
+# Severity for Guard output
+Severity = Literal["SUGGEST"]  # Pattern suggestions are always SUGGEST level
+
+
+@dataclass(frozen=True)
+class Location:
+    """Source code location for a pattern opportunity."""
+
+    file: str
+    line: int
+    column: int = 0
+    end_line: int | None = None
+    end_column: int | None = None
+
+    @post(lambda result: ":" in result)  # Contains file:line separator
+    def __str__(self) -> str:
+        """Format as file:line for display."""
+        return f"{self.file}:{self.line}"
+
+
+@dataclass(frozen=True)
+class PatternSuggestion:
+    """
+    A suggestion to apply a functional pattern.
+
+    >>> from invar.core.patterns.types import PatternSuggestion, PatternID, Confidence, Priority, Location
+    >>> suggestion = PatternSuggestion(
+    ...     pattern_id=PatternID.NEWTYPE,
+    ...     location=Location(file="src/api.py", line=42),
+    ...     message="Consider using NewType for semantic clarity",
+    ...     confidence=Confidence.HIGH,
+    ...     priority=Priority.P0,
+    ...     current_code="def process(user_id: str, order_id: str)",
+    ...     suggested_pattern="NewType('UserId', str), NewType('OrderId', str)",
+    ...     reference_file=".invar/examples/functional.py",
+    ...     reference_pattern="Pattern 1: NewType for Semantic Clarity",
+    ... )
+    >>> suggestion.severity
+    'SUGGEST'
+    >>> "NewType" in suggestion.message
+    True
+    """
+
+    pattern_id: PatternID
+    location: Location
+    message: str
+    confidence: Confidence
+    priority: Priority
+    current_code: str
+    suggested_pattern: str
+    reference_file: str
+    reference_pattern: str
+    severity: Severity = "SUGGEST"
+
+    @post(lambda result: "[SUGGEST]" in result and "Pattern:" in result)
+    def format_for_guard(self) -> str:
+        """
+        Format suggestion for Guard output.
+
+        >>> suggestion = PatternSuggestion(
+        ...     pattern_id=PatternID.NEWTYPE,
+        ...     location=Location(file="src/api.py", line=42),
+        ...     message="3+ str params - consider NewType",
+        ...     confidence=Confidence.HIGH,
+        ...     priority=Priority.P0,
+        ...     current_code="def f(a: str, b: str, c: str)",
+        ...     suggested_pattern="NewType",
+        ...     reference_file=".invar/examples/functional.py",
+        ...     reference_pattern="Pattern 1",
+        ... )
+        >>> "SUGGEST" in suggestion.format_for_guard()
+        True
+        >>> "src/api.py:42" in suggestion.format_for_guard()
+        True
+        """
+        return (
+            f"[{self.severity}] {self.location}: {self.message}\n"
+            f"  Pattern: {self.pattern_id.value} ({self.priority.value})\n"
+            f"  Current: {self.current_code[:60]}{'...' if len(self.current_code) > 60 else ''}\n"
+            f"  Suggest: {self.suggested_pattern}\n"
+            f"  See: {self.reference_file} - {self.reference_pattern}"
+        )
+
+
+@dataclass(frozen=True)
+class DetectionResult:
+    """
+    Result of running pattern detection on a file.
+
+    >>> from invar.core.patterns.types import DetectionResult, PatternSuggestion, PatternID, Confidence, Priority, Location
+    >>> result = DetectionResult(
+    ...     file="src/api.py",
+    ...     suggestions=[],
+    ...     patterns_checked=[PatternID.NEWTYPE, PatternID.LITERAL],
+    ... )
+    >>> len(result.suggestions)
+    0
+    >>> PatternID.NEWTYPE in result.patterns_checked
+    True
+    """
+
+    file: str
+    suggestions: list[PatternSuggestion]
+    patterns_checked: list[PatternID]
+
+    @property
+    @post(lambda result: isinstance(result, bool))
+    def has_suggestions(self) -> bool:
+        """Check if any suggestions were found."""
+        return len(self.suggestions) > 0
+
+    @pre(lambda self, min_confidence: min_confidence in Confidence)
+    @post(lambda result: isinstance(result, list))
+    def filter_by_confidence(self, min_confidence: Confidence) -> list[PatternSuggestion]:
+        """
+        Filter suggestions by minimum confidence level.
+
+        >>> result = DetectionResult(file="test.py", suggestions=[], patterns_checked=[])
+        >>> result.filter_by_confidence(Confidence.HIGH)
+        []
+        """
+        confidence_order = {Confidence.HIGH: 2, Confidence.MEDIUM: 1, Confidence.LOW: 0}
+        min_level = confidence_order[min_confidence]
+        return [s for s in self.suggestions if confidence_order[s.confidence] >= min_level]

invar/core/trivial_detection.py

@@ -0,0 +1,189 @@
+"""Trivial contract detection for DX-63.
+
+Pure logic module - no I/O. Detects contracts that provide no real constraint.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+
+from deal import post, pre
+
+
+@dataclass
+class TrivialContract:
+    """A trivial contract that provides no real constraint.
+
+    Examples:
+        >>> tc = TrivialContract(
+        ...     file="src/core/calc.py",
+        ...     line=10,
+        ...     function_name="process",
+        ...     contract_type="post",
+        ...     expression="lambda: True"
+        ... )
+        >>> tc.contract_type
+        'post'
+    """
+
+    file: str
+    line: int
+    function_name: str
+    contract_type: str  # "pre" or "post"
+    expression: str
+
+
+# Patterns that match trivial contracts
+TRIVIAL_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"^\s*lambda\s*:\s*True\s*$"),  # lambda: True
+    re.compile(r"^\s*lambda\s+\w+\s*:\s*True\s*$"),  # lambda x: True
+    re.compile(r"^\s*lambda\s+[\w,\s]+:\s*True\s*$"),  # lambda x, y: True
+    re.compile(r"^\s*lambda\s+\*\w+\s*:\s*True\s*$"),  # lambda *args: True
+    re.compile(r"^\s*lambda\s+\*\*\w+\s*:\s*True\s*$"),  # lambda **kwargs: True
+    re.compile(r"^\s*lambda\s+result\s*:\s*True\s*$"),  # lambda result: True
+    re.compile(r"^\s*lambda\s+_\s*:\s*True\s*$"),  # lambda _: True
+]
+
+
+@pre(lambda expression: len(expression.strip()) > 0)
+@post(lambda result: isinstance(result, bool))
+def is_trivial_contract(expression: str) -> bool:
+    """Check if a contract expression is trivial (provides no constraint).
+
+    Trivial contracts always return True regardless of input, providing
+    no actual constraint on the function's behavior.
+
+    Examples:
+        >>> is_trivial_contract("lambda: True")
+        True
+        >>> is_trivial_contract("lambda x: True")
+        True
+        >>> is_trivial_contract("lambda x, y: True")
+        True
+        >>> is_trivial_contract("lambda result: True")
+        True
+        >>> is_trivial_contract("lambda x: x > 0")
+        False
+        >>> is_trivial_contract("lambda items: len(items) > 0")
+        False
+        >>> is_trivial_contract("lambda result: result >= 0")
+        False
+    """
+    expr = expression.strip()
+    return any(pattern.match(expr) for pattern in TRIVIAL_PATTERNS)
+
+
+@pre(lambda node: isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)))
+@post(lambda result: all(t[0] in ("pre", "post") for t in result))
+def extract_contracts_from_decorators(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[tuple[str, str]]:
+    """Extract contract expressions from function decorators.
+
+    Returns list of (contract_type, expression) tuples.
+
+    Examples:
+        >>> import ast
+        >>> code = '''
+        ... @pre(lambda x: x > 0)
+        ... @post(lambda result: result >= 0)
+        ... def calc(x): return x * 2
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> contracts = extract_contracts_from_decorators(func)
+        >>> len(contracts)
+        2
+        >>> contracts[0][0]
+        'pre'
+    """
+    contracts = []
+
+    for decorator in node.decorator_list:
+        if isinstance(decorator, ast.Call):
+            # Get decorator name
+            if isinstance(decorator.func, ast.Name):
+                name = decorator.func.id
+            elif isinstance(decorator.func, ast.Attribute):
+                name = decorator.func.attr
+            else:
+                continue
+
+            # Check if it's a contract decorator
+            if name in ("pre", "post"):
+                # Get the first argument (the lambda or condition)
+                if decorator.args:
+                    arg = decorator.args[0]
+                    if isinstance(arg, ast.Lambda):
+                        # Convert lambda back to source
+                        expr = ast.unparse(arg)
+                        contracts.append((name, expr))
+
+    return contracts
+
+
+@pre(lambda source, file_path: len(source) >= 0 and len(file_path) > 0)
+@post(lambda result: result[0] >= 0 and result[1] >= 0 and result[1] <= result[0])
+def analyze_contracts_in_source(
+    source: str, file_path: str
+) -> tuple[int, int, list[TrivialContract]]:
+    """Analyze contracts in Python source code.
+
+    Pure function - receives source as string, no file I/O.
+
+    Returns: (total_functions, functions_with_contracts, trivial_contracts)
+
+    Examples:
+        >>> source = '''
+        ... from deal import pre, post
+        ... @pre(lambda x: x > 0)
+        ... def good(x): return x
+        ... def no_contract(x): return x
+        ... @post(lambda: True)
+        ... def trivial(x): return x
+        ... '''
+        >>> total, with_c, trivials = analyze_contracts_in_source(source, "test.py")
+        >>> total
+        3
+        >>> with_c
+        2
+        >>> len(trivials)
+        1
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return (0, 0, [])
+
+    total_functions = 0
+    functions_with_contracts = 0
+    trivial_contracts: list[TrivialContract] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # Skip private/dunder methods
+            if node.name.startswith("_"):
+                continue
+
+            total_functions += 1
+            contracts = extract_contracts_from_decorators(node)
+
+            if contracts:
+                functions_with_contracts += 1
+
+                # Check for trivial contracts
+                for contract_type, expr in contracts:
+                    if is_trivial_contract(expr):
+                        trivial_contracts.append(
+                            TrivialContract(
+                                file=file_path,
+                                line=node.lineno,
+                                function_name=node.name,
+                                contract_type=contract_type,
+                                expression=expr,
+                            )
+                        )
+
+    return (total_functions, functions_with_contracts, trivial_contracts)

invar/mcp/server.py

@@ -137,6 +137,7 @@ def _get_guard_tool() -> Tool:
                 "changed": {"type": "boolean", "description": "Only verify git-changed files", "default": True},
                 "strict": {"type": "boolean", "description": "Treat warnings as errors", "default": False},
                 "coverage": {"type": "boolean", "description": "DX-37: Collect branch coverage from doctest + hypothesis", "default": False},
+                "contracts_only": {"type": "boolean", "description": "DX-63: Contract coverage check only (skip tests)", "default": False},
             },
         },
     )
@@ -223,6 +224,9 @@ async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
     # DX-37: Optional coverage collection
     if args.get("coverage", False):
         cmd.append("--coverage")
+    # DX-63: Contract coverage check only
+    if args.get("contracts_only", False):
+        cmd.append("--contracts-only")
 
     # DX-26: TTY auto-detection - MCP runs in non-TTY, so agent JSON output is automatic
     # No explicit flag needed

invar/shell/commands/guard.py

@@ -133,11 +133,19 @@ def guard(
     coverage: bool = typer.Option(
         False, "--coverage", help="DX-37: Collect branch coverage from doctest + hypothesis"
     ),
+    suggest: bool = typer.Option(
+        False, "--suggest", help="DX-61: Show functional pattern suggestions"
+    ),
+    contracts_only: bool = typer.Option(
+        False, "--contracts-only", "-c", help="DX-63: Contract coverage check only"
+    ),
 ) -> None:
     """Check project against Invar architecture rules.
 
     Smart Guard: Runs static analysis + doctests + CrossHair + Hypothesis by default.
     Use --static for quick static-only checks (~0.5s vs ~5s full).
+    Use --suggest to get functional pattern suggestions (NewType, Validation, etc.).
+    Use --contracts-only (-c) to check contract coverage without running tests (DX-63).
     """
     from invar.shell.guard_helpers import (
         collect_files_to_check,
@@ -161,6 +169,31 @@ def guard(
     if pedantic:
         config.severity_overrides = {}
 
+    # DX-63: Contract coverage check only mode
+    if contracts_only:
+        import json
+
+        from invar.shell.contract_coverage import (
+            calculate_contract_coverage,
+            format_contract_coverage_agent,
+            format_contract_coverage_report,
+        )
+
+        coverage_result = calculate_contract_coverage(path, changed_only=changed)
+        if isinstance(coverage_result, Failure):
+            console.print(f"[red]Error:[/red] {coverage_result.failure()}")
+            raise typer.Exit(1)
+
+        report_data = coverage_result.unwrap()
+        use_agent_output = _determine_output_mode(human, agent, json_output)
+
+        if use_agent_output:
+            console.print(json.dumps(format_contract_coverage_agent(report_data)))
+        else:
+            console.print(format_contract_coverage_report(report_data))
+
+        raise typer.Exit(0 if report_data.ready_for_build else 1)
+
     # Handle --changed mode
     only_files: set[Path] | None = None
     checked_files: list[Path] = []
@@ -181,6 +214,25 @@ def guard(
         raise typer.Exit(1)
     report = scan_result.unwrap()
 
+    # DX-61: Run pattern detection if --suggest flag is set
+    pattern_suggestions: list = []
+    if suggest:
+        from invar.shell.pattern_integration import (
+            filter_suggestions,
+            run_pattern_detection,
+            suggestions_to_violations,
+        )
+        # Run pattern detection on checked files
+        files_to_check = list(only_files) if only_files else None
+        pattern_result = run_pattern_detection(path, files_to_check)
+        if isinstance(pattern_result, Success):
+            raw_suggestions = pattern_result.unwrap()
+            # DX-61: Apply config-based filtering
+            pattern_suggestions = filter_suggestions(raw_suggestions, config)
+            # Add suggestions to report as SUGGEST-level violations
+            for violation in suggestions_to_violations(pattern_suggestions):
+                report.add_violation(violation)
+
     # DX-26: Simplified output mode (TTY auto-detect + --human override)
     use_agent_output = _determine_output_mode(human, agent, json_output)
 
@@ -464,5 +516,18 @@ app.add_typer(dev_app)
 app.command("sync-self", hidden=True)(sync_self)
 
 
+# MCP server command for Claude Code integration
+@app.command()
+def mcp() -> None:
+    """Start Invar MCP server for AI agent integration.
+
+    This runs the MCP server using stdio transport.
+    Used by Claude Code and other MCP-compatible AI agents.
+    """
+    from invar.mcp.server import run_server
+
+    run_server()
+
+
 if __name__ == "__main__":
     app()