invar-tools 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

invar/core/patterns/p0_validation.py

@@ -0,0 +1,278 @@
+"""
+Validation Pattern Detector (DX-61, P0).
+
+Detects fail-fast validation patterns that could benefit from
+error accumulation for better user experience.
+"""
+
+import ast
+from typing import ClassVar
+
+from deal import post, pre
+
+from invar.core.patterns.detector import BaseDetector
+from invar.core.patterns.types import (
+    Confidence,
+    PatternID,
+    PatternSuggestion,
+    Priority,
+)
+
+
+class ValidationDetector(BaseDetector):
+    """
+    Detect fail-fast validation that returns early on first error.
+
+    These are candidates for error accumulation pattern.
+
+    Detection logic:
+    - Find functions with multiple early returns of error-like values
+    - Look for patterns like: if condition: return Failure/raise
+    - Suggest accumulating all errors before returning
+
+    >>> import ast
+    >>> detector = ValidationDetector()
+    >>> code = '''
+    ... def validate(data):
+    ...     if "name" not in data:
+    ...         return Failure("Missing name")
+    ...     if "email" not in data:
+    ...         return Failure("Missing email")
+    ...     if "age" not in data:
+    ...         return Failure("Missing age")
+    ...     return Success(data)
+    ... '''
+    >>> tree = ast.parse(code)
+    >>> suggestions = detector.detect(tree, "test.py")
+    >>> len(suggestions) > 0
+    True
+    """
+
+    MIN_EARLY_RETURNS: ClassVar[int] = 3
+    ERROR_PATTERNS: ClassVar[set[str]] = {"Failure", "Err", "Error", "Left"}
+    VALIDATION_KEYWORDS: ClassVar[set[str]] = {"validate", "check", "verify", "parse"}
+
+    @property
+    @post(lambda result: result == PatternID.VALIDATION)
+    def pattern_id(self) -> PatternID:
+        """Unique identifier for this pattern."""
+        return PatternID.VALIDATION
+
+    @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 error accumulation instead of fail-fast validation"
+
+    @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))
+    def detect(self, tree: ast.AST, file_path: str) -> list[PatternSuggestion]:
+        """
+        Find functions with fail-fast validation patterns.
+
+        >>> import ast
+        >>> detector = ValidationDetector()
+        >>> code = '''
+        ... def check_config(cfg):
+        ...     if not cfg.get("host"):
+        ...         return Failure("No host")
+        ...     if not cfg.get("port"):
+        ...         return Failure("No port")
+        ...     if not cfg.get("user"):
+        ...         return Failure("No user")
+        ...     return Success(cfg)
+        ... '''
+        >>> 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.FunctionDef, ast.AsyncFunctionDef)):
+                suggestion = self._check_function(node, file_path)
+                if suggestion:
+                    suggestions.append(suggestion)
+
+        return suggestions
+
+    @pre(lambda self, node, file_path: len(file_path) > 0)
+    def _check_function(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: str
+    ) -> PatternSuggestion | None:
+        """
+        Check if function has fail-fast validation pattern.
+
+        >>> import ast
+        >>> detector = ValidationDetector()
+        >>> code = '''
+        ... def validate(x):
+        ...     if not x.a: return Failure("a")
+        ...     if not x.b: return Failure("b")
+        ...     if not x.c: return Failure("c")
+        ...     return Success(x)
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> suggestion = detector._check_function(func, "test.py")
+        >>> suggestion is not None
+        True
+        """
+        early_returns = self._count_early_error_returns(node)
+
+        if early_returns >= self.MIN_EARLY_RETURNS:
+            confidence = self._calculate_confidence(node, early_returns)
+
+            return self.make_suggestion(
+                pattern_id=self.pattern_id,
+                priority=self.priority,
+                file_path=file_path,
+                line=node.lineno,
+                message=f"{early_returns} early error returns - consider error accumulation",
+                current_code=self._format_function_preview(node),
+                suggested_pattern="Collect all errors, return list[Error]",
+                confidence=confidence,
+                reference_pattern="Pattern 2: Validation for Error Accumulation",
+            )
+
+        return None
+
+    @post(lambda result: result >= 0)
+    def _count_early_error_returns(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> int:
+        """
+        Count early returns with error-like values inside if statements.
+
+        Only counts if statements at the top level of the function body,
+        not nested functions or lambdas.
+
+        >>> import ast
+        >>> detector = ValidationDetector()
+        >>> code = '''
+        ... def f(x):
+        ...     if not x.a: return Failure("a")
+        ...     if not x.b: return Failure("b")
+        ...     return Success(x)
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> detector._count_early_error_returns(func)
+        2
+        """
+        count = 0
+
+        # Only iterate direct children, not nested functions
+        for stmt in node.body:
+            count += self._count_if_error_returns(stmt)
+
+        return count
+
+    @post(lambda result: result >= 0)
+    def _count_if_error_returns(self, stmt: ast.stmt) -> int:
+        """
+        Recursively count if statements with error returns, avoiding nested functions.
+
+        >>> import ast
+        >>> detector = ValidationDetector()
+        >>> stmt = ast.parse("if x: return Failure('e')").body[0]
+        >>> detector._count_if_error_returns(stmt)
+        1
+        """
+        count = 0
+
+        if isinstance(stmt, ast.If):
+            # Check if body has early error return
+            for body_stmt in stmt.body:
+                if isinstance(body_stmt, ast.Return) and self._is_error_return(body_stmt):
+                    count += 1
+                    break
+            # Recurse into else/elif but NOT into nested functions
+            for body_stmt in stmt.body:
+                if not isinstance(body_stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    count += self._count_if_error_returns(body_stmt)
+            for else_stmt in stmt.orelse:
+                if not isinstance(else_stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    count += self._count_if_error_returns(else_stmt)
+
+        return count
+
+    @post(lambda result: isinstance(result, bool))
+    def _is_error_return(self, node: ast.Return) -> bool:
+        """
+        Check if return value looks like an error.
+
+        >>> import ast
+        >>> detector = ValidationDetector()
+        >>> ret = ast.parse("return Failure('error')").body[0].value
+        >>> # This tests the return statement's value
+        >>> detector._is_error_return(ast.Return(value=ret))
+        True
+        """
+        if node.value is None:
+            return False
+
+        # Check for Failure(...), Err(...), etc.
+        if isinstance(node.value, ast.Call):
+            if isinstance(node.value.func, ast.Name):
+                return node.value.func.id in self.ERROR_PATTERNS
+            if isinstance(node.value.func, ast.Attribute):
+                return node.value.func.attr in self.ERROR_PATTERNS
+
+        return False
+
+    @pre(lambda self, node, early_returns: early_returns >= 0)
+    @post(lambda result: result in Confidence)
+    def _calculate_confidence(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef, early_returns: int
+    ) -> Confidence:
+        """
+        Calculate confidence based on function characteristics.
+
+        >>> import ast
+        >>> detector = ValidationDetector()
+        >>> func = ast.parse("def validate_config(x): pass").body[0]
+        >>> detector._calculate_confidence(func, 3)
+        <Confidence.HIGH: 'high'>
+        """
+        # High confidence if function name suggests validation
+        func_name = node.name.lower()
+        if any(kw in func_name for kw in self.VALIDATION_KEYWORDS):
+            return Confidence.HIGH
+
+        # High confidence if many early returns
+        if early_returns >= 5:
+            return Confidence.HIGH
+
+        # Medium confidence for moderate early returns
+        if early_returns >= 3:
+            return Confidence.MEDIUM
+
+        return Confidence.LOW
+
+    @post(lambda result: len(result) > 0 and "def " in result)
+    def _format_function_preview(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> str:
+        """
+        Format function preview for display.
+
+        >>> import ast
+        >>> detector = ValidationDetector()
+        >>> func = ast.parse("def validate(data): pass").body[0]
+        >>> preview = detector._format_function_preview(func)
+        >>> "validate" in preview
+        True
+        """
+        prefix = "async def" if isinstance(node, ast.AsyncFunctionDef) else "def"
+        params = self.get_function_params(node)
+        param_str = ", ".join(name for name, _ in params[:3])
+        if len(params) > 3:
+            param_str += ", ..."
+        return f"{prefix} {node.name}({param_str})"

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]