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

invar/core/formatter.py

@@ -235,7 +235,7 @@ def format_guard_agent(report: GuardReport, combined_status: str | None = None)
     status = combined_status if combined_status else ("passed" if report.passed else "failed")
     static_passed = report.errors == 0
 
-    return {
+    result = {
         "status": status,
         # DX-26: Separate static results from combined status
         "static": {
@@ -252,6 +252,11 @@ def format_guard_agent(report: GuardReport, combined_status: str | None = None)
         },
         "fixes": [_violation_to_fix(v) for v in report.violations],
     }
+    # DX-61: Add suggests count if any pattern suggestions exist
+    if report.suggests > 0:
+        result["static"]["suggests"] = report.suggests
+        result["summary"]["suggests"] = report.suggests
+    return result
 
 
 @post(lambda result: "file" in result and "rule" in result and "severity" in result)

invar/core/models.py

@@ -28,6 +28,7 @@ class Severity(str, Enum):
     ERROR = "error"
     WARNING = "warning"
     INFO = "info"  # Phase 7: For informational issues like redundant type contracts
+    SUGGEST = "suggest"  # DX-61: Functional pattern suggestions
 
 
 class Contract(BaseModel):
@@ -90,6 +91,7 @@ class GuardReport(BaseModel):
     errors: int = 0
     warnings: int = 0
     infos: int = 0  # Phase 7: Track INFO-level issues
+    suggests: int = 0  # DX-61: Track SUGGEST-level pattern suggestions
     # P24: Contract coverage statistics (Core files only)
     core_functions_total: int = 0
     core_functions_with_contracts: int = 0
@@ -106,12 +108,18 @@ class GuardReport(BaseModel):
             >>> report.add_violation(v)
             >>> report.errors
             1
+            >>> v2 = Violation(rule="pattern", severity=Severity.SUGGEST, file="x.py", message="sug")
+            >>> report.add_violation(v2)
+            >>> report.suggests
+            1
         """
         self.violations.append(violation)
         if violation.severity == Severity.ERROR:
             self.errors += 1
         elif violation.severity == Severity.WARNING:
             self.warnings += 1
+        elif violation.severity == Severity.SUGGEST:
+            self.suggests += 1
         else:
             self.infos += 1
 
@@ -263,6 +271,11 @@ class RuleConfig(BaseModel):
     timeout_crosshair: int = Field(default=300, ge=1, le=1800)  # Symbolic verification total
     timeout_crosshair_per_condition: int = Field(default=30, ge=1, le=300)  # Per-contract limit
 
+    # DX-61: Pattern detection configuration
+    pattern_min_confidence: str = Field(default="medium")  # low, medium, high
+    pattern_priorities: list[str] = Field(default_factory=lambda: ["P0"])  # P0, P1
+    pattern_exclude: list[str] = Field(default_factory=list)  # Pattern IDs to exclude
+
 
 # Phase 4: Perception models
 

invar/core/patterns/__init__.py

@@ -0,0 +1,53 @@
+"""
+Functional Pattern Detection (DX-61).
+
+This module provides pattern detection for suggesting functional programming
+improvements in Python code. Guard integrates with this module to provide
+SUGGEST-level feedback when it detects opportunities for patterns like:
+
+P0 (Core Patterns):
+    - NewType: Semantic clarity for multiple same-type parameters
+    - Validation: Error accumulation instead of fail-fast
+    - NonEmpty: Compile-time non-empty guarantees
+    - Literal: Type-safe finite value sets
+    - ExhaustiveMatch: assert_never for enum matching
+
+P1 (Extended Patterns - future):
+    - SmartConstructor: Validation at construction time
+    - StructuredError: Typed errors for programmatic handling
+
+Usage:
+    >>> from invar.core.patterns import detect_patterns
+    >>> source = "def f(a: str, b: str, c: str): pass"
+    >>> result = detect_patterns("test.py", source)
+    >>> result.has_suggestions
+    True
+
+See .invar/examples/functional.py for pattern examples.
+"""
+
+from invar.core.patterns.registry import (
+    PatternRegistry,
+    detect_patterns,
+    get_registry,
+)
+from invar.core.patterns.types import (
+    Confidence,
+    DetectionResult,
+    Location,
+    PatternID,
+    PatternSuggestion,
+    Priority,
+)
+
+__all__ = [
+    "Confidence",
+    "DetectionResult",
+    "Location",
+    "PatternID",
+    "PatternRegistry",
+    "PatternSuggestion",
+    "Priority",
+    "detect_patterns",
+    "get_registry",
+]

invar/core/patterns/detector.py

@@ -0,0 +1,249 @@
+"""
+Pattern Detector Protocol (DX-61).
+
+Base protocol for all pattern detectors.
+"""
+
+import ast
+from abc import abstractmethod
+from typing import Protocol
+
+from deal import post, pre
+
+from invar.core.patterns.types import (
+    Confidence,
+    Location,
+    PatternID,
+    PatternSuggestion,
+    Priority,
+)
+
+
+class PatternDetector(Protocol):
+    """
+    Protocol for pattern detectors.
+
+    Each detector identifies opportunities for a specific functional pattern.
+    Detectors analyze AST nodes and return suggestions with confidence levels.
+    """
+
+    @property
+    @abstractmethod
+    @post(lambda result: result in PatternID)
+    def pattern_id(self) -> PatternID:
+        """Unique identifier for this pattern."""
+        ...
+
+    @property
+    @abstractmethod
+    @post(lambda result: result in Priority)
+    def priority(self) -> Priority:
+        """Priority tier (P0 or P1)."""
+        ...
+
+    @property
+    @abstractmethod
+    @post(lambda result: len(result) > 0)
+    def description(self) -> str:
+        """Human-readable description of the pattern."""
+        ...
+
+    @abstractmethod
+    @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))
+    def detect(self, tree: ast.AST, file_path: str) -> list[PatternSuggestion]:
+        """
+        Analyze AST and return pattern suggestions.
+
+        Args:
+            tree: Parsed AST of the source file
+            file_path: Path to the source file (for location reporting)
+
+        Returns:
+            List of pattern suggestions found in the file
+        """
+        ...
+
+
+class BaseDetector:
+    """
+    Base class with common detection utilities.
+
+    Provides helper methods for AST analysis that can be reused
+    across different pattern detectors.
+    """
+
+    @post(lambda result: all(isinstance(name, str) and name for name, _ in result))
+    def get_function_params(self, node: ast.FunctionDef) -> list[tuple[str, str | None]]:
+        """
+        Extract parameter names and type annotations from a function.
+
+        >>> import ast
+        >>> code = "def f(a: str, b: int, c): pass"
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> detector = BaseDetector()
+        >>> params = detector.get_function_params(func)
+        >>> params[0]
+        ('a', 'str')
+        >>> params[1]
+        ('b', 'int')
+        >>> params[2]
+        ('c', None)
+        """
+        params = []
+        for arg in node.args.args:
+            name = arg.arg
+            type_hint = None
+            if arg.annotation:
+                type_hint = self._annotation_to_str(arg.annotation)
+            params.append((name, type_hint))
+        return params
+
+    @post(lambda result: isinstance(result, str) and len(result) > 0)
+    def _annotation_to_str(self, annotation: ast.expr) -> str:
+        """
+        Convert an annotation AST node to string.
+
+        >>> import ast
+        >>> detector = BaseDetector()
+        >>> detector._annotation_to_str(ast.Name(id="str"))
+        'str'
+        >>> detector._annotation_to_str(ast.Constant(value="str"))
+        'str'
+        """
+        if isinstance(annotation, ast.Name):
+            return annotation.id
+        elif isinstance(annotation, ast.Constant):
+            return str(annotation.value)
+        elif isinstance(annotation, ast.Subscript):
+            # Handle generics like list[str]
+            base = self._annotation_to_str(annotation.value)
+            if isinstance(annotation.slice, ast.Tuple):
+                args = ", ".join(self._annotation_to_str(e) for e in annotation.slice.elts)
+            else:
+                args = self._annotation_to_str(annotation.slice)
+            return f"{base}[{args}]"
+        elif isinstance(annotation, ast.Attribute):
+            # Handle qualified names like typing.List
+            parts = []
+            node = annotation
+            while isinstance(node, ast.Attribute):
+                parts.append(node.attr)
+                node = node.value
+            if isinstance(node, ast.Name):
+                parts.append(node.id)
+            return ".".join(reversed(parts))
+        elif isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
+            # Handle X | Y union syntax
+            left = self._annotation_to_str(annotation.left)
+            right = self._annotation_to_str(annotation.right)
+            return f"{left} | {right}"
+        else:
+            # Python 3.9+ always has ast.unparse (project requires 3.11+)
+            return ast.unparse(annotation)
+
+    @pre(lambda self, params, type_name: len(type_name) > 0)
+    @post(lambda result: result >= 0)
+    def count_type_occurrences(
+        self, params: list[tuple[str, str | None]], type_name: str
+    ) -> int:
+        """
+        Count how many parameters have a specific type.
+
+        >>> detector = BaseDetector()
+        >>> params = [("a", "str"), ("b", "str"), ("c", "int")]
+        >>> detector.count_type_occurrences(params, "str")
+        2
+        """
+        return sum(1 for _, t in params if t == type_name)
+
+    @post(lambda result: isinstance(result, bool))
+    def has_match_statement(self, node: ast.FunctionDef) -> bool:
+        """
+        Check if function contains a match statement.
+
+        >>> import ast
+        >>> code = '''
+        ... def f(x):
+        ...     match x:
+        ...         case 1: pass
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> detector = BaseDetector()
+        >>> detector.has_match_statement(func)
+        True
+        """
+        return any(isinstance(child, ast.Match) for child in ast.walk(node))
+
+    @post(lambda result: all(isinstance(c, str) for c in result))
+    def get_enum_cases(self, match_node: ast.Match) -> list[str]:
+        """
+        Extract case patterns from a match statement.
+
+        >>> import ast
+        >>> code = '''
+        ... match status:
+        ...     case Status.A: pass
+        ...     case Status.B: pass
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> match = tree.body[0]
+        >>> detector = BaseDetector()
+        >>> cases = detector.get_enum_cases(match)
+        >>> "Status.A" in cases
+        True
+        """
+        cases = []
+        for case in match_node.cases:
+            pattern = case.pattern
+            if isinstance(pattern, ast.MatchValue):
+                cases.append(ast.unparse(pattern.value) if hasattr(ast, "unparse") else str(pattern.value))
+            elif isinstance(pattern, ast.MatchAs) and pattern.pattern is None:
+                cases.append("_")  # Wildcard
+        return cases
+
+    @pre(lambda self, pattern_id, priority, file_path, line, message, current_code, suggested_pattern, confidence, reference_pattern: line > 0)
+    @post(lambda result: result.reference_file == ".invar/examples/functional.py")
+    def make_suggestion(
+        self,
+        pattern_id: PatternID,
+        priority: Priority,
+        file_path: str,
+        line: int,
+        message: str,
+        current_code: str,
+        suggested_pattern: str,
+        confidence: Confidence,
+        reference_pattern: str,
+    ) -> PatternSuggestion:
+        """
+        Create a pattern suggestion with standard reference file.
+
+        >>> from invar.core.patterns.types import PatternID, Priority, Confidence
+        >>> detector = BaseDetector()
+        >>> suggestion = detector.make_suggestion(
+        ...     pattern_id=PatternID.NEWTYPE,
+        ...     priority=Priority.P0,
+        ...     file_path="test.py",
+        ...     line=10,
+        ...     message="Test message",
+        ...     current_code="def f(): pass",
+        ...     suggested_pattern="NewType",
+        ...     confidence=Confidence.HIGH,
+        ...     reference_pattern="Pattern 1: NewType",
+        ... )
+        >>> suggestion.reference_file
+        '.invar/examples/functional.py'
+        """
+        return PatternSuggestion(
+            pattern_id=pattern_id,
+            location=Location(file=file_path, line=line),
+            message=message,
+            confidence=confidence,
+            priority=priority,
+            current_code=current_code,
+            suggested_pattern=suggested_pattern,
+            reference_file=".invar/examples/functional.py",
+            reference_pattern=reference_pattern,
+        )

invar/core/patterns/p0_exhaustive.py

@@ -0,0 +1,207 @@
+"""
+Exhaustive Match Pattern Detector (DX-61, P0).
+
+Detects match statements on enums that don't use assert_never
+for exhaustiveness checking.
+"""
+
+import ast
+
+from deal import post, pre
+
+from invar.core.patterns.detector import BaseDetector
+from invar.core.patterns.types import (
+    Confidence,
+    PatternID,
+    PatternSuggestion,
+    Priority,
+)
+
+
+class ExhaustiveMatchDetector(BaseDetector):
+    """
+    Detect non-exhaustive match statements on enums.
+
+    These are candidates for assert_never pattern to ensure
+    all cases are handled at compile time.
+
+    Detection logic:
+    - Find match statements
+    - Check if wildcard case exists but doesn't use assert_never
+    - Suggest adding assert_never for exhaustiveness
+
+    >>> import ast
+    >>> detector = ExhaustiveMatchDetector()
+    >>> code = '''
+    ... def handle(status: Status) -> str:
+    ...     match status:
+    ...         case Status.PENDING:
+    ...             return "pending"
+    ...         case Status.DONE:
+    ...             return "done"
+    ...         case _:
+    ...             return "unknown"
+    ... '''
+    >>> tree = ast.parse(code)
+    >>> suggestions = detector.detect(tree, "test.py")
+    >>> len(suggestions) > 0
+    True
+    """
+
+    @property
+    @post(lambda result: result == PatternID.EXHAUSTIVE)
+    def pattern_id(self) -> PatternID:
+        """Unique identifier for this pattern."""
+        return PatternID.EXHAUSTIVE
+
+    @property
+    @post(lambda result: result == Priority.P0)
+    def priority(self) -> Priority:
+        """Priority tier."""
+        return Priority.P0
+
+    @property
+    @post(lambda result: len(result) > 0)
+    def description(self) -> str:
+        """Human-readable description."""
+        return "Use assert_never for exhaustive enum matching"
+
+    @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))
+    def detect(self, tree: ast.AST, file_path: str) -> list[PatternSuggestion]:
+        """
+        Find match statements with non-exhaustive patterns.
+
+        >>> import ast
+        >>> detector = ExhaustiveMatchDetector()
+        >>> code = '''
+        ... def f(x):
+        ...     match x:
+        ...         case A.ONE: return 1
+        ...         case _: return 0
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> suggestions = detector.detect(tree, "test.py")
+        >>> len(suggestions) > 0
+        True
+        """
+        suggestions = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Match):
+                suggestion = self._check_match(node, file_path)
+                if suggestion:
+                    suggestions.append(suggestion)
+
+        return suggestions
+
+    @pre(lambda self, node, file_path: len(file_path) > 0)
+    def _check_match(
+        self, node: ast.Match, file_path: str
+    ) -> PatternSuggestion | None:
+        """
+        Check if match statement could benefit from assert_never.
+
+        >>> import ast
+        >>> detector = ExhaustiveMatchDetector()
+        >>> code = '''
+        ... match x:
+        ...     case Status.A: pass
+        ...     case _: pass
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> match = tree.body[0]
+        >>> suggestion = detector._check_match(match, "test.py")
+        >>> suggestion is not None
+        True
+        """
+        has_wildcard = False
+        uses_assert_never = False
+        has_enum_patterns = False
+        enum_cases = []
+
+        for case in node.cases:
+            pattern = case.pattern
+
+            # Check for wildcard
+            if isinstance(pattern, ast.MatchAs) and pattern.pattern is None:
+                has_wildcard = True
+                # Check if body uses assert_never
+                uses_assert_never = self._uses_assert_never(case.body)
+
+            # Check for enum-like patterns (e.g., Status.PENDING)
+            elif isinstance(pattern, ast.MatchValue):
+                if isinstance(pattern.value, ast.Attribute):
+                    has_enum_patterns = True
+                    enum_cases.append(ast.unparse(pattern.value) if hasattr(ast, "unparse") else "...")
+
+        # Suggest if: has enum patterns + has wildcard + doesn't use assert_never
+        if has_enum_patterns and has_wildcard and not uses_assert_never:
+            confidence = self._calculate_confidence(enum_cases)
+
+            return self.make_suggestion(
+                pattern_id=self.pattern_id,
+                priority=self.priority,
+                file_path=file_path,
+                line=node.lineno,
+                message="Match has wildcard without assert_never - missing cases won't be caught",
+                current_code=self._format_match_preview(enum_cases),
+                suggested_pattern="case _: assert_never(x)  # Type error if cases missing",
+                confidence=confidence,
+                reference_pattern="Pattern 5: Exhaustive Match",
+            )
+
+        return None
+
+    @post(lambda result: isinstance(result, bool))
+    def _uses_assert_never(self, body: list[ast.stmt]) -> bool:
+        """
+        Check if body contains assert_never call.
+
+        >>> import ast
+        >>> detector = ExhaustiveMatchDetector()
+        >>> body = ast.parse("assert_never(x)").body
+        >>> detector._uses_assert_never(body)
+        True
+        """
+        for stmt in body:
+            if isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
+                func = stmt.value.func
+                if isinstance(func, ast.Name) and func.id == "assert_never":
+                    return True
+        return False
+
+    @post(lambda result: result in Confidence)
+    def _calculate_confidence(self, enum_cases: list[str]) -> Confidence:
+        """
+        Calculate confidence based on context.
+
+        >>> detector = ExhaustiveMatchDetector()
+        >>> detector._calculate_confidence(["Status.A", "Status.B", "Status.C"])
+        <Confidence.HIGH: 'high'>
+        """
+        # High confidence if multiple enum cases from same type
+        if len(enum_cases) >= 2:
+            # Check if all from same enum
+            prefixes = [c.split(".")[0] if "." in c else c for c in enum_cases]
+            if len(set(prefixes)) == 1:
+                return Confidence.HIGH
+
+        # Medium confidence for any enum patterns
+        if enum_cases:
+            return Confidence.MEDIUM
+
+        return Confidence.LOW
+
+    @post(lambda result: "match" in result and "case" in result)
+    def _format_match_preview(self, enum_cases: list[str]) -> str:
+        """
+        Format match statement preview.
+
+        >>> detector = ExhaustiveMatchDetector()
+        >>> detector._format_match_preview(["Status.A", "Status.B"])
+        'match ...: case Status.A | Status.B | _: ...'
+        """
+        cases_str = " | ".join(enum_cases[:3])
+        if len(enum_cases) > 3:
+            cases_str += " | ..."
+        return f"match ...: case {cases_str} | _: ..."