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

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} | _: ..."

invar/core/patterns/p0_literal.py

@@ -0,0 +1,307 @@
+"""
+Literal Pattern Detector (DX-61, P0).
+
+Detects runtime validation for finite value sets that could benefit
+from Literal type for compile-time safety.
+"""
+
+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 LiteralDetector(BaseDetector):
+    """
+    Detect runtime checks for finite value sets.
+
+    These are candidates for Literal type to catch invalid values
+    at type-check time instead of runtime.
+
+    Detection logic:
+    - Find 'if x not in (...)' or 'if x not in [...]' patterns
+    - Look for small sets of string/int literals
+    - Suggest Literal type for the parameter
+
+    >>> import ast
+    >>> detector = LiteralDetector()
+    >>> code = '''
+    ... def set_level(level: str) -> None:
+    ...     if level not in ("debug", "info", "warning", "error"):
+    ...         raise ValueError(f"Invalid level: {level}")
+    ... '''
+    >>> tree = ast.parse(code)
+    >>> suggestions = detector.detect(tree, "test.py")
+    >>> len(suggestions) > 0
+    True
+    """
+
+    MAX_LITERAL_VALUES = 10  # Don't suggest Literal for large sets
+
+    @property
+    @post(lambda result: result == PatternID.LITERAL)
+    def pattern_id(self) -> PatternID:
+        """Unique identifier for this pattern."""
+        return PatternID.LITERAL
+
+    @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 Literal type for finite value sets"
+
+    @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 runtime finite-set validation.
+
+        >>> import ast
+        >>> detector = LiteralDetector()
+        >>> code = '''
+        ... def process(mode: str):
+        ...     if mode not in ["fast", "slow", "auto"]:
+        ...         raise ValueError("Bad mode")
+        ... '''
+        >>> 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)):
+                func_suggestions = self._check_function(node, file_path)
+                suggestions.extend(func_suggestions)
+
+        return suggestions
+
+    @pre(lambda self, node, file_path: len(file_path) > 0)
+    @post(lambda result: all(isinstance(s, PatternSuggestion) for s in result))
+    def _check_function(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: str
+    ) -> list[PatternSuggestion]:
+        """
+        Check if function has finite-set validation patterns.
+
+        >>> import ast
+        >>> detector = LiteralDetector()
+        >>> code = '''
+        ... def f(x):
+        ...     if x not in ("a", "b", "c"):
+        ...         raise ValueError("Bad")
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> suggestions = detector._check_function(func, "test.py")
+        >>> len(suggestions) > 0
+        True
+        """
+        suggestions = []
+        checks = self._find_membership_checks(node)
+
+        for var_name, values, check_line in checks:
+            if len(values) <= self.MAX_LITERAL_VALUES:
+                confidence = self._calculate_confidence(values)
+
+                suggestions.append(
+                    self.make_suggestion(
+                        pattern_id=self.pattern_id,
+                        priority=self.priority,
+                        file_path=file_path,
+                        line=check_line,
+                        message=f"Runtime check for {len(values)} values - consider Literal type",
+                        current_code=self._format_check(var_name, values),
+                        suggested_pattern=self._format_literal(var_name, values),
+                        confidence=confidence,
+                        reference_pattern="Pattern 4: Literal for Finite Value Sets",
+                    )
+                )
+
+        return suggestions
+
+    @post(lambda result: all(len(name) > 0 and len(vals) > 0 and line > 0 for name, vals, line in result))
+    def _find_membership_checks(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef
+    ) -> list[tuple[str, list[str | int], int]]:
+        """
+        Find 'if x not in (...)' patterns.
+
+        Returns list of (var_name, values, line_number).
+        Only checks function-level if statements, not nested functions.
+
+        >>> import ast
+        >>> detector = LiteralDetector()
+        >>> code = '''
+        ... def f(x):
+        ...     if x not in ("a", "b"):
+        ...         raise ValueError("Bad")
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> checks = detector._find_membership_checks(func)
+        >>> len(checks) > 0
+        True
+        >>> checks[0][1]
+        ['a', 'b']
+        """
+        checks: list[tuple[str, list[str | int], int]] = []
+        self._collect_membership_checks(node.body, checks)
+        return checks
+
+    @pre(lambda self, stmts, checks: stmts is not None and checks is not None)
+    def _collect_membership_checks(
+        self,
+        stmts: list[ast.stmt],
+        checks: list[tuple[str, list[str | int], int]],
+    ) -> None:
+        """
+        Recursively collect membership checks, avoiding nested functions.
+
+        >>> import ast
+        >>> detector = LiteralDetector()
+        >>> stmts = ast.parse("if x not in ('a', 'b'): raise ValueError()").body
+        >>> checks: list[tuple[str, list[str | int], int]] = []
+        >>> detector._collect_membership_checks(stmts, checks)
+        >>> len(checks)
+        1
+        """
+        for stmt in stmts:
+            # Skip nested functions
+            if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+
+            if isinstance(stmt, ast.If):
+                result = self._extract_membership_check(stmt.test)
+                if result:
+                    var_name, values = result
+                    checks.append((var_name, values, stmt.lineno))
+                # Recurse into body and else
+                self._collect_membership_checks(stmt.body, checks)
+                self._collect_membership_checks(stmt.orelse, checks)
+
+    @post(lambda result: result is None or (len(result[0]) > 0 and len(result[1]) > 0))
+    def _extract_membership_check(
+        self, test: ast.expr
+    ) -> tuple[str, list[str | int]] | None:
+        """
+        Extract variable and values from membership check.
+
+        Handles:
+        - 'x not in ("a", "b", "c")'
+        - 'x not in ["a", "b", "c"]'
+
+        >>> import ast
+        >>> detector = LiteralDetector()
+        >>> test = ast.parse("x not in ('a', 'b')", mode="eval").body
+        >>> result = detector._extract_membership_check(test)
+        >>> result is not None
+        True
+        >>> result[0]
+        'x'
+        >>> result[1]
+        ['a', 'b']
+        """
+        # Handle 'x not in (...)'
+        if isinstance(test, ast.Compare):
+            if (
+                len(test.ops) == 1
+                and isinstance(test.ops[0], ast.NotIn)
+                and len(test.comparators) == 1
+            ):
+                left = test.left
+                right = test.comparators[0]
+
+                if isinstance(left, ast.Name):
+                    var_name = left.id
+                    values = self._extract_literal_values(right)
+                    if values:
+                        return (var_name, values)
+
+        return None
+
+    @post(lambda result: result is None or len(result) > 0)
+    def _extract_literal_values(self, node: ast.expr) -> list[str | int] | None:
+        """
+        Extract literal values from tuple/list/set.
+
+        >>> import ast
+        >>> detector = LiteralDetector()
+        >>> node = ast.parse("('a', 'b', 'c')", mode="eval").body
+        >>> detector._extract_literal_values(node)
+        ['a', 'b', 'c']
+        """
+        if isinstance(node, (ast.Tuple, ast.List, ast.Set)):
+            values = []
+            for elt in node.elts:
+                if isinstance(elt, ast.Constant) and isinstance(
+                    elt.value, (str, int)
+                ):
+                    values.append(elt.value)
+                else:
+                    return None  # Non-literal value
+            return values
+        return None
+
+    @pre(lambda self, values: len(values) > 0)
+    @post(lambda result: result in Confidence)
+    def _calculate_confidence(self, values: list[str | int]) -> Confidence:
+        """
+        Calculate confidence based on value characteristics.
+
+        >>> detector = LiteralDetector()
+        >>> detector._calculate_confidence(["debug", "info", "warning", "error"])
+        <Confidence.HIGH: 'high'>
+        """
+        # High confidence for small sets of strings
+        if all(isinstance(v, str) for v in values) and len(values) <= 5:
+            return Confidence.HIGH
+
+        # Medium confidence for larger sets or mixed types
+        if len(values) <= 8:
+            return Confidence.MEDIUM
+
+        return Confidence.LOW
+
+    @pre(lambda self, var_name, values: len(var_name) > 0 and len(values) > 0)
+    @post(lambda result: "not in" in result)
+    def _format_check(self, var_name: str, values: list[str | int]) -> str:
+        """
+        Format the membership check for display.
+
+        >>> detector = LiteralDetector()
+        >>> detector._format_check("level", ["debug", "info"])
+        "if level not in ('debug', 'info'): raise"
+        """
+        formatted_values = ", ".join(repr(v) for v in values[:4])
+        if len(values) > 4:
+            formatted_values += ", ..."
+        return f"if {var_name} not in ({formatted_values}): raise"
+
+    @pre(lambda self, _var_name, values: len(_var_name) > 0 and len(values) > 0)
+    @post(lambda result: "Literal[" in result)
+    def _format_literal(self, _var_name: str, values: list[str | int]) -> str:
+        """
+        Format the Literal type suggestion.
+
+        >>> detector = LiteralDetector()
+        >>> detector._format_literal("level", ["debug", "info", "error"])
+        "Literal['debug', 'info', 'error']"
+        """
+        formatted_values = ", ".join(repr(v) for v in values[:5])
+        if len(values) > 5:
+            formatted_values += ", ..."
+        return f"Literal[{formatted_values}]"