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

invar/__init__.py

@@ -9,6 +9,7 @@ For runtime contracts only, use invar-runtime instead.
 """
 
 __version__ = "1.0.0"
+__protocol_version__ = "5.0"  # Protocol/spec version (separate from package version)
 
 # Re-export from invar-runtime for backwards compatibility
 from invar_runtime import (

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())
+@post(lambda result: isinstance(result, bool))
 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())
+@post(lambda result: isinstance(result, bool))
 def is_redundant_type_contract(expression: str, annotations: dict[str, str]) -> bool:
     """Check if a contract only checks types already in annotations.
 
@@ -72,10 +76,14 @@ def is_redundant_type_contract(expression: str, annotations: dict[str, str]) ->
         return False
 
 
-@pre(lambda node: isinstance(node, ast.expr))
+@pre(lambda node: isinstance(node, ast.expr) and hasattr(node, '__class__'))
 @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())
+@post(lambda result: len(result) == 3 and isinstance(result[0], bool))
 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())
+@post(lambda result: len(result) == 2 and isinstance(result[0], bool))
 def has_param_mismatch(expression: str, signature: str) -> tuple[bool, str]:
     """
     Check if lambda params don't match function params.
@@ -209,7 +227,7 @@ def has_param_mismatch(expression: str, signature: str) -> tuple[bool, str]:
 # Rule checking functions
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "empty_contract" for v in result))
 def check_empty_contracts(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """Check for empty/tautological contracts. Core files only.
 
@@ -242,7 +260,7 @@ def check_empty_contracts(file_info: FileInfo, config: RuleConfig) -> list[Viola
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "redundant_type_contract" for v in result))
 def check_redundant_type_contracts(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """Check for contracts that only check types in annotations. Core files only. INFO severity.
 
@@ -280,7 +298,7 @@ def check_redundant_type_contracts(file_info: FileInfo, config: RuleConfig) -> l
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "param_mismatch" for v in result))
 def check_param_mismatch(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """Check @pre lambda params match function params. Core files only. ERROR severity.
 
@@ -324,7 +342,7 @@ def check_param_mismatch(file_info: FileInfo, config: RuleConfig) -> list[Violat
     return violations
 
 
-@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+@post(lambda result: all(v.rule == "partial_contract" for v in result))
 def check_partial_contract(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
     """Check @pre contracts that don't use all declared params (P28). Core files only. WARN severity.
 
@@ -373,3 +391,55 @@ def check_partial_contract(file_info: FileInfo, config: RuleConfig) -> list[Viol
                     )
                 )
     return violations
+
+
+@post(lambda result: all(v.rule == "skip_without_reason" for v in result))
+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,367 @@
+"""
+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 ast
+import re
+import tokenize
+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*(.+)")
+
+
+@post(lambda result: result >= 0)  # Escape hatch count is non-negative
+def count_escape_hatches(source: str) -> int:
+    """
+    Count @invar:allow markers in source code (DX-31).
+
+    Uses tokenize to only match real comments, not strings/docstrings (DX-33 Option C).
+    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
+        >>> # DX-33 Option C: Strings containing the pattern should NOT match
+        >>> count_escape_hatches('s = "# @invar:allow rule: reason"')
+        0
+    """
+    return len(extract_escape_hatches(source))
+
+
+@post(lambda result: all(len(t) == 2 for t in result))  # Returns (rule, reason) tuples
+def extract_escape_hatches(source: str) -> list[tuple[str, str]]:
+    """
+    Extract @invar:allow markers with their reasons (DX-33 Option E).
+
+    Uses tokenize to only match real comments, not strings/docstrings.
+    Returns list of (rule, reason) tuples for cross-file analysis.
+
+    Examples:
+        >>> extract_escape_hatches("")
+        []
+        >>> extract_escape_hatches("# @invar:allow shell_result: API boundary")
+        [('shell_result', 'API boundary')]
+        >>> source = '''
+        ... # @invar:allow rule1: same reason
+        ... # @invar:allow rule2: different reason
+        ... '''
+        >>> extract_escape_hatches(source)
+        [('rule1', 'same reason'), ('rule2', 'different reason')]
+        >>> # DX-33 Option C: Strings containing the pattern should NOT match
+        >>> extract_escape_hatches('suggestion = "# @invar:allow rule: reason"')
+        []
+    """
+    results: list[tuple[str, str]] = []
+    try:
+        # Use iterator-based readline to avoid io.StringIO (forbidden in Core)
+        lines = iter(source.splitlines(keepends=True))
+        tokens = tokenize.generate_tokens(lambda: next(lines, ""))
+        for tok in tokens:
+            if tok.type == tokenize.COMMENT:
+                match = INVAR_ALLOW_PATTERN.search(tok.string)
+                if match:
+                    results.append((match.group(1), match.group(2)))
+    except Exception:
+        # Fall back to regex if tokenization fails (invalid syntax, non-printable chars, etc.)
+        return INVAR_ALLOW_PATTERN.findall(source)
+    return results
+
+
+@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=3, end_line=5)
+        >>> source = '''
+        ... @app.route("/")
+        ... def index():
+        ...     return "Hello"
+        ... '''
+        >>> is_entry_point(sym, source)
+        True
+
+        >>> sym2 = Symbol(name="load_file", kind=SymbolKind.FUNCTION, line=2, end_line=4)
+        >>> 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=5)
+        >>> 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)
+
+
+
+@post(lambda result: isinstance(result, str))
+def _decorator_to_string(decorator: ast.AST) -> str:
+    """
+    Convert AST decorator node to string representation for matching.
+
+    Examples:
+        >>> import ast
+        >>> tree = ast.parse("@app.route('/')\\ndef f(): pass")
+        >>> func = tree.body[0]
+        >>> _decorator_to_string(func.decorator_list[0])
+        'app.route'
+    """
+    if isinstance(decorator, ast.Name):
+        return decorator.id
+    elif isinstance(decorator, ast.Attribute):
+        parts = []
+        node = decorator
+        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(decorator, ast.Call):
+        return _decorator_to_string(decorator.func)
+    return ""
+
+@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.
+
+    Uses AST to check decorator nodes, avoiding false matches in strings.
+    DX-33 Option C: Migrated from string matching to AST-based detection.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="home", kind=SymbolKind.FUNCTION, line=2, end_line=4)
+        >>> source = '''@app.route("/")
+        ... def home():
+        ...     pass
+        ... '''
+        >>> _has_entry_decorator(sym, source)
+        True
+        >>> # DX-33: Decorators in strings should NOT match
+        >>> sym2 = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=2, end_line=4)
+        >>> source2 = '''x = "@app.route('/')"
+        ... def foo():
+        ...     pass
+        ... '''
+        >>> _has_entry_decorator(sym2, source2)
+        False
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return False
+
+    # Find the function definition at the symbol's line
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.lineno == symbol.line and node.name == symbol.name:
+                # Check decorators
+                for decorator in node.decorator_list:
+                    decorator_str = _decorator_to_string(decorator)
+                    if decorator_str:
+                        for pattern in ENTRY_POINT_DECORATORS:
+                            if pattern in decorator_str or decorator_str.endswith(
+                                "." + pattern.split(".")[-1]
+                            ):
+                                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/extraction.py

@@ -11,8 +11,7 @@ from deal import post, pre
 from invar.core.models import FileInfo, Symbol, SymbolKind
 
 
-@pre(lambda funcs: isinstance(funcs, dict))
-@post(lambda result: isinstance(result, dict))
+@post(lambda result: all(k in result for k in result))  # Bidirectional graph
 def _build_call_graph(funcs: dict[str, Symbol]) -> dict[str, set[str]]:
     """Build bidirectional call graph for function grouping.
 
@@ -33,8 +32,8 @@ def _build_call_graph(funcs: dict[str, Symbol]) -> dict[str, set[str]]:
     return graph
 
 
-@pre(lambda start, graph, visited: start and isinstance(graph, dict) and start in graph)
-@post(lambda result: isinstance(result, list))
+@pre(lambda start, graph, visited: start and start in graph)  # Start must exist in graph
+@post(lambda result: len(result) >= 1 or not result)  # At least 1 if found, else empty
 def _find_connected_component(start: str, graph: dict[str, set[str]], visited: set[str]) -> list[str]:
     """BFS to find all functions connected to start.
 
@@ -55,7 +54,7 @@ def _find_connected_component(start: str, graph: dict[str, set[str]], visited: s
     return component
 
 
-@pre(lambda file_info: isinstance(file_info, FileInfo))
+@post(lambda result: all("functions" in g and "lines" in g for g in result))
 def find_extractable_groups(file_info: FileInfo) -> list[dict]:
     """
     Find groups of related functions that could be extracted together.
@@ -136,7 +135,7 @@ def _get_group_dependencies(
     return deps.intersection(set(file_imports)) if file_imports else deps
 
 
-@pre(lambda file_info, max_groups=3: isinstance(file_info, FileInfo))
+@pre(lambda file_info, max_groups=3: max_groups >= 1)  # At least 1 group
 def format_extraction_hint(file_info: FileInfo, max_groups: int = 3) -> str:
     """
     Format extraction suggestions for file_size_warning.