invar-tools 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

invar/core/contracts.py

@@ -23,15 +23,19 @@ from invar.core.tautology import check_semantic_tautology as check_semantic_taut
 from invar.core.tautology import is_semantic_tautology as is_semantic_tautology
 
 
-@pre(lambda expression: ("lambda" in expression and ":" in expression) or not expression.strip())
+@pre(lambda expression: isinstance(expression, str))
 def is_empty_contract(expression: str) -> bool:
     """Check if a contract expression is always True (tautological).
 
+    Handles any string input - non-lambda expressions return False.
+
     Examples:
         >>> is_empty_contract("lambda: True"), is_empty_contract("lambda x: True")
         (True, True)
         >>> is_empty_contract("lambda x: x > 0"), is_empty_contract("")
         (False, False)
+        >>> is_empty_contract("not a lambda")  # Non-lambda returns False
+        False
     """
     if not expression.strip():
         return False
@@ -47,7 +51,7 @@ def is_empty_contract(expression: str) -> bool:
         return False
 
 
-@pre(lambda expression, annotations: ("lambda" in expression and ":" in expression) or not expression.strip())
+@pre(lambda expression, annotations: isinstance(expression, str))
 def is_redundant_type_contract(expression: str, annotations: dict[str, str]) -> bool:
     """Check if a contract only checks types already in annotations.
 
@@ -75,7 +79,11 @@ def is_redundant_type_contract(expression: str, annotations: dict[str, str]) ->
 @pre(lambda node: isinstance(node, ast.expr))
 @post(lambda result: result is None or isinstance(result, list))
 def _extract_isinstance_checks(node: ast.expr) -> list[tuple[str, str]] | None:
-    """Extract isinstance checks. Returns None if other logic present."""
+    """Extract isinstance checks. Returns None if other logic present.
+
+    Conservative: returns None for complex expressions (nested BoolOp, etc.)
+    to avoid false positives when detecting redundant type contracts.
+    """
     if isinstance(node, ast.Call) and hasattr(node, 'func'):
         check = _parse_isinstance_call(node)
         return [check] if check else None
@@ -106,9 +114,19 @@ def _parse_isinstance_call(node: ast.Call) -> tuple[str, str] | None:
 def _types_match(annotation: str, type_name: str) -> bool:
     """Check if type annotation matches isinstance check.
 
+    Handles simple cases like 'int' matching 'int' and 'list[int]' matching 'list'.
+
+    MINOR-1 Limitation: Does not handle complex generics:
+    - Optional[T] / Union[T, None] → doesn't match 'T' or 'NoneType'
+    - Union[A, B] → doesn't match 'A' or 'B'
+    - Capitalized builtins → 'List[int]' won't match 'list'
+    This is acceptable for detecting obvious redundant type checks.
+
     Examples:
         >>> _types_match("int", "int"), _types_match("list[int]", "list")
         (True, True)
+        >>> _types_match("Optional[int]", "int")  # Limitation: returns False
+        False
     """
     if annotation == type_name:
         return True
@@ -119,7 +137,7 @@ def _types_match(annotation: str, type_name: str) -> bool:
 # Phase 8.3: Parameter mismatch detection
 
 
-@pre(lambda expression, signature: ("lambda" in expression and ":" in expression) or not expression.strip())
+@pre(lambda expression, signature: isinstance(expression, str) and isinstance(signature, str))
 def has_unused_params(expression: str, signature: str) -> tuple[bool, list[str], list[str]]:
     """
     Check if lambda has params it doesn't use (P28: Partial Contract Detection).
@@ -171,7 +189,7 @@ def has_unused_params(expression: str, signature: str) -> tuple[bool, list[str],
     return (len(unused_params) > 0, unused_params, used_params)
 
 
-@pre(lambda expression, signature: ("lambda" in expression and ":" in expression) or not expression.strip())
+@pre(lambda expression, signature: isinstance(expression, str) and isinstance(signature, str))
 def has_param_mismatch(expression: str, signature: str) -> tuple[bool, str]:
     """
     Check if lambda params don't match function params.
@@ -373,3 +391,55 @@ def check_partial_contract(file_info: FileInfo, config: RuleConfig) -> list[Viol
                     )
                 )
     return violations
+
+
+@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+def check_skip_without_reason(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check that @skip_property_test decorators have a reason.
+
+    DX-28: Prevent abuse of skip by requiring justification.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind, RuleConfig
+        >>> sym = Symbol(name="f", kind=SymbolKind.FUNCTION, line=2, end_line=5)
+        >>> info = FileInfo(path="test.py", lines=10, symbols=[sym], source="@skip_property_test\\ndef f(): pass")
+        >>> vs = check_skip_without_reason(info, RuleConfig())
+        >>> len(vs) > 0
+        True
+        >>> vs[0].rule
+        'skip_without_reason'
+        >>> # MAJOR-10: Also detects empty string reasons
+        >>> info2 = FileInfo(path="t.py", lines=5, symbols=[sym], source='@skip_property_test("")\\ndef f(): pass')
+        >>> len(check_skip_without_reason(info2, RuleConfig())) > 0
+        True
+    """
+    violations: list[Violation] = []
+
+    source = file_info.source or ""
+    if "@skip_property_test" not in source:
+        return violations
+
+    # Pattern matches @skip_property_test at start of line (not in strings)
+    # Uses ^ to ensure we're matching decorator position, not string literals
+    bare_pattern = re.compile(r"^\s*@skip_property_test\s*$")
+    no_reason_pattern = re.compile(r"^\s*@skip_property_test\s*\(\s*\)\s*$")
+    # MAJOR-10: Also detect empty/whitespace-only string reasons
+    empty_string_pattern = re.compile(r"^\s*@skip_property_test\s*\(\s*['\"][\s]*['\"]\s*\)\s*$")
+
+    for line_num, line in enumerate(source.split("\n"), 1):
+        # Check for bare @skip_property_test, empty parens, or empty string reason
+        if bare_pattern.match(line) or no_reason_pattern.match(line) or empty_string_pattern.match(line):
+            violations.append(
+                Violation(
+                    rule="skip_without_reason",
+                    severity=Severity.WARNING,
+                    file=file_info.path,
+                    line=line_num,
+                    message="@skip_property_test used without reason",
+                    suggestion='Add reason: @skip_property_test("category: explanation")\n'
+                    "Valid categories: no_params, strategy_factory, external_io, non_deterministic",
+                )
+            )
+
+    return violations

invar/core/entry_points.py

@@ -0,0 +1,294 @@
+"""
+Entry point detection for framework callbacks.
+
+DX-23: Detects entry points (Flask routes, Typer commands, pytest fixtures, etc.)
+that are exempt from Result[T, E] requirement but must remain thin.
+
+Core module: pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from deal import post, pre
+
+if TYPE_CHECKING:
+    from invar.core.models import Symbol
+
+
+# Decorator patterns that indicate framework entry points
+# These functions interface with external frameworks and cannot return Result
+ENTRY_POINT_DECORATORS: frozenset[str] = frozenset([
+    # Web frameworks - Flask
+    "app.route",
+    "app.get",
+    "app.post",
+    "app.put",
+    "app.delete",
+    "app.patch",
+    "blueprint.route",
+    "bp.route",
+    # Web frameworks - FastAPI
+    "router.get",
+    "router.post",
+    "router.put",
+    "router.delete",
+    "router.patch",
+    "api_router.get",
+    "api_router.post",
+    "api_router.put",
+    "api_router.delete",
+    # CLI frameworks - Typer
+    "app.command",
+    "app.callback",
+    "typer.command",
+    # CLI frameworks - Click
+    "click.command",
+    "click.group",
+    "cli.command",
+    # Testing - pytest
+    "pytest.fixture",
+    "fixture",
+    # Event handlers
+    "on_event",
+    "app.on_event",
+    "middleware",
+    "app.middleware",
+    # Django
+    "admin.register",
+    "receiver",
+])
+
+# Explicit marker comment for edge cases
+ENTRY_MARKER_PATTERN = re.compile(r"#\s*@shell:entry\b")
+
+# DX-22: Unified escape hatch pattern: # @invar:allow <rule>: <reason>
+INVAR_ALLOW_PATTERN = re.compile(r"#\s*@invar:allow\s+(\w+)\s*:\s*(.+)")
+
+
+@pre(lambda source: isinstance(source, str))
+@post(lambda result: isinstance(result, int) and result >= 0)
+def count_escape_hatches(source: str) -> int:
+    """
+    Count @invar:allow markers in source code (DX-31).
+
+    Used by check_review_suggested to trigger review when escape count >= 3.
+
+    Examples:
+        >>> count_escape_hatches("")
+        0
+        >>> count_escape_hatches("# @invar:allow rule: reason")
+        1
+        >>> source = '''
+        ... # @invar:allow rule1: reason1
+        ... def foo(): pass
+        ... # @invar:allow rule2: reason2
+        ... def bar(): pass
+        ... '''
+        >>> count_escape_hatches(source)
+        2
+        >>> count_escape_hatches("regular comment # no marker")
+        0
+    """
+    return len(INVAR_ALLOW_PATTERN.findall(source))
+
+
+@pre(lambda symbol, source: symbol is not None and isinstance(source, str))
+@post(lambda result: isinstance(result, bool))
+def is_entry_point(symbol: Symbol, source: str) -> bool:
+    """
+    Check if a symbol is a framework entry point.
+
+    Entry points are functions decorated with framework-specific decorators
+    (Flask routes, Typer commands, etc.) that cannot return Result[T, E]
+    because the framework expects specific return types.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="index", kind=SymbolKind.FUNCTION, line=5, end_line=10)
+        >>> source = '''
+        ... @app.route("/")
+        ... def index():
+        ...     return "Hello"
+        ... '''
+        >>> is_entry_point(sym, source)
+        True
+
+        >>> sym2 = Symbol(name="load_file", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> source2 = '''
+        ... def load_file(path: str) -> Result[str, str]:
+        ...     return Success(path.read_text())
+        ... '''
+        >>> is_entry_point(sym2, source2)
+        False
+
+        >>> # Explicit marker
+        >>> sym3 = Symbol(name="handler", kind=SymbolKind.FUNCTION, line=3, end_line=8)
+        >>> source3 = '''
+        ... # @shell:entry - Legacy callback
+        ... def handler(data):
+        ...     return process(data)
+        ... '''
+        >>> is_entry_point(sym3, source3)
+        True
+    """
+    # Check decorator patterns
+    if _has_entry_decorator(symbol, source):
+        return True
+
+    # Check explicit marker
+    return _has_entry_marker(symbol, source)
+
+
+@pre(lambda symbol, source: symbol is not None and isinstance(source, str))
+@post(lambda result: isinstance(result, bool))
+def _has_entry_decorator(symbol: Symbol, source: str) -> bool:
+    """
+    Check if symbol has a framework entry point decorator.
+
+    Looks at the source code above the function definition.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="home", kind=SymbolKind.FUNCTION, line=3, end_line=6)
+        >>> source = '''@app.route("/")
+        ... def home():
+        ...     pass
+        ... '''
+        >>> _has_entry_decorator(sym, source)
+        True
+    """
+    # Get source lines
+    lines = source.splitlines()
+    if not lines:
+        return False
+
+    # Look at lines before the function definition (decorators are above)
+    # We check up to 5 lines above the function for decorators
+    start_line = max(0, symbol.line - 6)
+    end_line = symbol.line  # Line numbers are 1-indexed, so line-1 = index
+
+    context_lines = lines[start_line:end_line]
+    context = "\n".join(context_lines)
+
+    # Check each known decorator pattern
+    # Note: String matching may match decorators in string literals (rare edge case).
+    # AST-based detection would be more robust but adds complexity for a heuristic check.
+    for pattern in ENTRY_POINT_DECORATORS:
+        # Match @pattern or @something.pattern
+        if f"@{pattern}" in context:
+            return True
+        # Also match partial patterns (e.g., "route" matches "app.route")
+        if "." in pattern:
+            base = pattern.split(".")[-1]
+            if f".{base}(" in context or f".{base}\n" in context:
+                return True
+
+    return False
+
+
+@pre(lambda symbol, source: symbol is not None and isinstance(source, str))
+@post(lambda result: isinstance(result, bool))
+def _has_entry_marker(symbol: Symbol, source: str) -> bool:
+    """
+    Check if symbol has an explicit entry point marker comment.
+
+    Looks for: # @shell:entry
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="callback", kind=SymbolKind.FUNCTION, line=3, end_line=6)
+        >>> source = '''
+        ... # @shell:entry - Custom framework callback
+        ... def callback():
+        ...     pass
+        ... '''
+        >>> _has_entry_marker(sym, source)
+        True
+
+        >>> sym2 = Symbol(name="regular", kind=SymbolKind.FUNCTION, line=1, end_line=3)
+        >>> source2 = '''def regular(): pass'''
+        >>> _has_entry_marker(sym2, source2)
+        False
+    """
+    lines = source.splitlines()
+    if not lines:
+        return False
+
+    # Look at lines before the function definition
+    start_line = max(0, symbol.line - 4)
+    end_line = symbol.line
+
+    context_lines = lines[start_line:end_line]
+    context = "\n".join(context_lines)
+
+    return bool(ENTRY_MARKER_PATTERN.search(context))
+
+
+@pre(lambda symbol: symbol is not None)
+@post(lambda result: isinstance(result, int) and result >= 0)
+def get_symbol_lines(symbol: Symbol) -> int:
+    """
+    Get the number of lines in a symbol.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=10)
+        >>> get_symbol_lines(sym)
+        10
+        >>> sym2 = Symbol(name="bar", kind=SymbolKind.FUNCTION, line=5, end_line=5)
+        >>> get_symbol_lines(sym2)
+        1
+    """
+    return max(1, symbol.end_line - symbol.line + 1)
+
+
+@pre(lambda symbol, source, rule: symbol is not None and isinstance(rule, str))
+@post(lambda result: isinstance(result, bool))
+def has_allow_marker(symbol: Symbol, source: str, rule: str) -> bool:
+    """
+    Check if symbol has an @invar:allow marker for a specific rule.
+
+    DX-22: Unified escape hatch mechanism. Format:
+        # @invar:allow <rule>: <reason>
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="handler", kind=SymbolKind.FUNCTION, line=3, end_line=20)
+        >>> source = '''
+        ... # @invar:allow entry_point_too_thick: Complex CLI parsing
+        ... def handler():
+        ...     pass
+        ... '''
+        >>> has_allow_marker(sym, source, "entry_point_too_thick")
+        True
+        >>> has_allow_marker(sym, source, "shell_result")
+        False
+
+        >>> sym2 = Symbol(name="api", kind=SymbolKind.FUNCTION, line=3, end_line=10)
+        >>> source2 = '''
+        ... # @invar:allow shell_result: Returns raw JSON for legacy API
+        ... def api():
+        ...     pass
+        ... '''
+        >>> has_allow_marker(sym2, source2, "shell_result")
+        True
+    """
+    lines = source.splitlines()
+    if not lines:
+        return False
+
+    # Look at lines before the function definition (up to 4 lines)
+    start_line = max(0, symbol.line - 5)
+    end_line = symbol.line
+
+    context_lines = lines[start_line:end_line]
+
+    for line in context_lines:
+        match = INVAR_ALLOW_PATTERN.search(line)
+        if match and match.group(1) == rule:
+            return True
+
+    return False

invar/core/format_specs.py

@@ -0,0 +1,196 @@
+"""
+Format-driven property testing specifications.
+
+DX-28: Format specifications for generating realistic test data
+that matches production formats, enabling property tests to catch
+semantic bugs like inverted filter conditions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from deal import post, pre
+
+
+@dataclass
+class FormatSpec:
+    """Base specification for a data format.
+
+    A FormatSpec describes the structure of data used in a function,
+    enabling Hypothesis to generate realistic test cases.
+
+    Examples:
+        >>> spec = FormatSpec(name="simple")
+        >>> spec.name
+        'simple'
+    """
+
+    name: str
+    description: str = ""
+
+
+@dataclass
+class LineFormat(FormatSpec):
+    """Specification for line-based text formats.
+
+    Examples:
+        >>> spec = LineFormat(
+        ...     name="log_line",
+        ...     prefix_pattern="<timestamp>",
+        ...     separator=": ",
+        ...     keywords=["error", "warning", "info"]
+        ... )
+        >>> spec.separator
+        ': '
+    """
+
+    prefix_pattern: str = ""
+    separator: str = ""
+    keywords: list[str] = field(default_factory=list)
+    suffix_pattern: str = ""
+
+
+@dataclass
+class CrossHairOutputSpec(FormatSpec):
+    """Specification for CrossHair verification output format.
+
+    CrossHair outputs counterexamples in a specific format:
+    `file.py:line: error: ErrorType when calling func(args)`
+
+    This spec enables generating realistic CrossHair output for testing
+    counterexample extraction logic.
+
+    Examples:
+        >>> spec = CrossHairOutputSpec()
+        >>> spec.name
+        'crosshair_output'
+        >>> ": error:" in spec.error_marker
+        True
+    """
+
+    name: str = "crosshair_output"
+    description: str = "CrossHair symbolic verification output"
+
+    # Format components
+    file_pattern: str = r"[a-z_]+\.py"
+    line_pattern: str = r"\\d+"
+    error_marker: str = ": error:"
+    error_types: list[str] = field(
+        default_factory=lambda: [
+            "IndexError",
+            "KeyError",
+            "ValueError",
+            "TypeError",
+            "AssertionError",
+            "ZeroDivisionError",
+            "AttributeError",
+        ]
+    )
+
+    @pre(lambda self, filename, line, error_type, function, args: self.error_marker and line > 0)
+    @post(lambda result: isinstance(result, str) and len(result) > 0)
+    def format_counterexample(
+        self,
+        filename: str = "test.py",
+        line: int = 1,
+        error_type: str = "AssertionError",
+        function: str = "func",
+        args: str = "x=0",
+    ) -> str:
+        """
+        Generate a counterexample line in CrossHair format.
+
+        Examples:
+            >>> spec = CrossHairOutputSpec()
+            >>> line = spec.format_counterexample("foo.py", 42, "ValueError", "bar", "x=-1")
+            >>> line
+            'foo.py:42: error: ValueError when calling bar(x=-1)'
+            >>> ": error:" in line
+            True
+        """
+        return f"{filename}:{line}: error: {error_type} when calling {function}({args})"
+
+    @pre(lambda self, count, include_success, include_errors: count >= 0 and (not include_errors or (len(self.error_types) > 0 and bool(self.error_marker))))
+    @post(lambda result: isinstance(result, list))
+    def generate_output(
+        self,
+        count: int = 3,
+        include_success: bool = True,
+        include_errors: bool = True,
+    ) -> list[str]:
+        """
+        Generate sample CrossHair output with counterexamples.
+
+        Examples:
+            >>> spec = CrossHairOutputSpec()
+            >>> output = spec.generate_output(count=2, include_success=False, include_errors=True)
+            >>> len([l for l in output if ": error:" in l])
+            2
+            >>> all(": error:" in line for line in output if line)
+            True
+        """
+        lines: list[str] = []
+
+        if include_success:
+            lines.append("Checking module...")
+
+        if include_errors:
+            for i in range(count):
+                error_type = self.error_types[i % len(self.error_types)]
+                lines.append(
+                    self.format_counterexample(
+                        f"file{i}.py", i + 1, error_type, f"func{i}", f"x={i}"
+                    )
+                )
+
+        if include_success:
+            lines.append("")  # Empty line at end
+
+        return lines
+
+
+@dataclass
+class PytestOutputSpec(FormatSpec):
+    """Specification for pytest output format.
+
+    Examples:
+        >>> spec = PytestOutputSpec()
+        >>> spec.name
+        'pytest_output'
+    """
+
+    name: str = "pytest_output"
+    description: str = "pytest test runner output"
+
+    passed_marker: str = "PASSED"
+    failed_marker: str = "FAILED"
+    error_marker: str = "ERROR"
+    separator: str = "::"
+
+
+# Pre-built specs for common formats
+CROSSHAIR_SPEC = CrossHairOutputSpec()
+PYTEST_SPEC = PytestOutputSpec()
+
+
+@pre(lambda text, spec: isinstance(text, str) and isinstance(spec, CrossHairOutputSpec))
+@post(lambda result: isinstance(result, list))
+def extract_by_format(text: str, spec: CrossHairOutputSpec) -> list[str]:
+    """
+    Extract lines matching a format specification.
+
+    This is a reference implementation showing how FormatSpec
+    can be used to create format-aware extraction.
+
+    Examples:
+        >>> spec = CrossHairOutputSpec()
+        >>> text = "info\\nfile.py:1: error: Bug\\nok"
+        >>> extract_by_format(text, spec)
+        ['file.py:1: error: Bug']
+    """
+    return [
+        line.strip()
+        for line in text.split("\n")
+        if line.strip() and spec.error_marker in line.lower()
+    ]