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

invar/core/shell_analysis.py

@@ -0,0 +1,252 @@
+"""
+Shell source analysis helpers for DX-22.
+
+Helper functions for analyzing Shell layer code:
+- I/O operation detection
+- Marker pattern detection
+- Branch counting
+- Symbol source extraction
+
+Core module: pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING
+
+from deal import post, pre
+
+if TYPE_CHECKING:
+    from invar.core.models import Symbol
+
+# I/O indicators that mark a function as legitimately in Shell
+IO_INDICATORS: frozenset[str] = frozenset([
+    # File operations
+    ".read(",
+    ".write(",
+    ".read_text(",
+    ".write_text(",
+    ".read_bytes(",
+    ".write_bytes(",
+    "open(",
+    "Path(",
+    ".exists()",
+    ".is_file()",
+    ".is_dir()",
+    ".rglob(",
+    ".glob(",
+    ".iterdir(",
+    ".mkdir(",
+    ".unlink(",
+    "shutil.",
+    "tempfile.",
+    # Process operations
+    "subprocess.",
+    "os.system(",
+    "os.popen(",
+    "os.getenv(",
+    "os.environ",
+    # Terminal/System
+    "sys.stdout",
+    "sys.stderr",
+    "sys.stdin",
+    ".isatty()",
+    # Module loading
+    "importlib.",
+    "exec_module(",
+    # Network operations
+    "requests.",
+    "aiohttp.",
+    "httpx.",
+    "urllib.",
+    # Console output
+    "print(",
+    "console.",
+    "Console(",
+    "typer.",
+    "click.",
+    "rich.",
+    # Result wrapping (Shell's primary job)
+    "Success(",
+    "Failure(",
+    "Result[",
+    # Database
+    "cursor.",
+    "connection.",
+    "session.",
+    # Logging
+    "logger.",
+    "logging.",
+    # Serialization (often to files)
+    "json.dump(",
+    "json.load(",
+    "toml.load(",
+    "yaml.load(",
+])
+
+# Marker pattern to exempt functions from complexity check
+COMPLEXITY_MARKER_PATTERN = re.compile(r"#\s*@shell_complexity\s*:")
+
+# Marker pattern to exempt functions from pure logic check (for orchestration functions)
+ORCHESTRATION_MARKER_PATTERN = re.compile(r"#\s*@shell_orchestration\s*:")
+
+
+@pre(lambda source: isinstance(source, str))
+@post(lambda result: isinstance(result, bool))
+def has_io_operations(source: str) -> bool:
+    """
+    Check if source code contains I/O operations.
+
+    Examples:
+        >>> has_io_operations("x = Success(value)")
+        True
+        >>> has_io_operations("return x + y")
+        False
+        >>> has_io_operations("path.read_text()")
+        True
+        >>> has_io_operations("print('hello')")
+        True
+    """
+    return any(indicator in source for indicator in IO_INDICATORS)
+
+
+@pre(lambda symbol, source: symbol is not None and isinstance(source, str))
+@post(lambda result: isinstance(result, bool))
+def has_orchestration_marker(symbol: Symbol, source: str) -> bool:
+    """
+    Check if symbol has @shell_orchestration marker comment.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="run_phase", kind=SymbolKind.FUNCTION, line=3, end_line=10)
+        >>> source = '''
+        ... # @shell_orchestration: Coordinates shell modules
+        ... def run_phase():
+        ...     pass
+        ... '''
+        >>> has_orchestration_marker(sym, source)
+        True
+
+        >>> sym2 = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=3)
+        >>> has_orchestration_marker(sym2, "def calc(): pass")
+        False
+    """
+    lines = source.splitlines()
+    if not lines:
+        return False
+
+    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(ORCHESTRATION_MARKER_PATTERN.search(context))
+
+
+@pre(lambda symbol, source: symbol is not None and isinstance(source, str))
+@post(lambda result: isinstance(result, bool))
+def has_complexity_marker(symbol: Symbol, source: str) -> bool:
+    """
+    Check if symbol has @shell_complexity marker comment.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="load", kind=SymbolKind.FUNCTION, line=3, end_line=10)
+        >>> source = '''
+        ... # @shell_complexity: Config cascade with fallbacks
+        ... def load():
+        ...     pass
+        ... '''
+        >>> has_complexity_marker(sym, source)
+        True
+
+        >>> sym2 = Symbol(name="simple", kind=SymbolKind.FUNCTION, line=1, end_line=3)
+        >>> has_complexity_marker(sym2, "def simple(): pass")
+        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(COMPLEXITY_MARKER_PATTERN.search(context))
+
+
+@pre(lambda source: isinstance(source, str))
+@post(lambda result: isinstance(result, int) and result >= 0)
+def count_branches(source: str) -> int:
+    """
+    Count the number of branches in source code.
+
+    Counts: if, elif, except, for, while, match case, ternary
+
+    Examples:
+        >>> count_branches("if x: pass")
+        1
+        >>> count_branches("if x: pass\\nelif y: pass")
+        2
+        >>> count_branches("for x in y: pass")
+        1
+        >>> count_branches("x = a if b else c")
+        1
+        >>> count_branches("pass")
+        0
+        >>> count_branches("")
+        0
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return 0
+
+    count = 0
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If):
+            # ast.walk visits all If nodes including elifs
+            count += 1
+        elif isinstance(node, ast.For | ast.While | ast.ExceptHandler):
+            count += 1
+        elif isinstance(node, ast.Match):
+            # Count match cases
+            count += len(node.cases)
+        elif isinstance(node, ast.IfExp):
+            # Ternary expression
+            count += 1
+
+    return count
+
+
+@pre(lambda symbol, file_source: symbol is not None and isinstance(file_source, str))
+@post(lambda result: isinstance(result, str))
+def get_symbol_source(symbol: Symbol, file_source: str) -> str:
+    """
+    Extract the source code for a specific symbol.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=2, end_line=4)
+        >>> source = '''# comment
+        ... def foo():
+        ...     return 1
+        ... '''
+        >>> 'def foo' in get_symbol_source(sym, source)
+        True
+    """
+    lines = file_source.splitlines()
+    if not lines:
+        return ""
+
+    # Line numbers are 1-indexed
+    start = max(0, symbol.line - 1)
+    end = min(len(lines), symbol.end_line)
+
+    return "\n".join(lines[start:end])

invar/core/shell_architecture.py

@@ -0,0 +1,171 @@
+"""
+Shell architecture rules for DX-22.
+
+Detects architectural issues in Shell layer:
+- shell_pure_logic: Pure logic that belongs in Core
+- shell_too_complex: Excessive branching complexity
+- shell_complexity_debt: Accumulated complexity warnings
+
+Core module: pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+from deal import post, pre
+
+from invar.core.entry_points import get_symbol_lines, is_entry_point
+from invar.core.models import FileInfo, RuleConfig, Severity, SymbolKind, Violation
+from invar.core.shell_analysis import (
+    count_branches,
+    get_symbol_source,
+    has_complexity_marker,
+    has_io_operations,
+    has_orchestration_marker,
+)
+
+
+@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+def check_shell_pure_logic(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check that Shell functions contain I/O operations (DX-22).
+
+    Pure logic belongs in Core where it can be tested with contracts.
+    Functions > 5 lines without I/O indicators are flagged as WARNING.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind, RuleConfig
+        >>> sym = Symbol(name="calc", kind=SymbolKind.FUNCTION, line=1, end_line=10)
+        >>> source = "def calc(x, y):\\n    return x + y"
+        >>> info = FileInfo(path="shell/util.py", lines=10, symbols=[sym], is_shell=True, source=source)
+        >>> violations = check_shell_pure_logic(info, RuleConfig())
+        >>> len(violations) >= 0  # May or may not flag based on line count
+        True
+    """
+    violations: list[Violation] = []
+    if not file_info.is_shell:
+        return violations
+
+    for symbol in file_info.symbols:
+        if symbol.kind != SymbolKind.FUNCTION:
+            continue
+
+        # Skip small functions (wrappers are fine)
+        lines = get_symbol_lines(symbol)
+        if lines <= 5:
+            continue
+
+        # Skip entry points (they're handled by DX-23)
+        if is_entry_point(symbol, file_info.source):
+            continue
+
+        # Skip if marked with @shell_orchestration (coordinates other shell modules)
+        if has_orchestration_marker(symbol, file_info.source):
+            continue
+
+        # Get symbol source and check for I/O
+        symbol_source = get_symbol_source(symbol, file_info.source)
+        if not has_io_operations(symbol_source):
+            violations.append(
+                Violation(
+                    rule="shell_pure_logic",
+                    severity=Severity.WARNING,
+                    file=file_info.path,
+                    line=symbol.line,
+                    message=f"Shell function '{symbol.name}' has no I/O operations - pure logic belongs in Core",
+                    suggestion="Move to src/*/core/ and add @pre/@post contracts, or add: # @shell_orchestration: <reason>",
+                )
+            )
+
+    return violations
+
+
+@pre(lambda file_info, config: isinstance(file_info, FileInfo))
+def check_shell_too_complex(file_info: FileInfo, config: RuleConfig) -> list[Violation]:
+    """
+    Check that Shell functions don't have excessive branching (DX-22).
+
+    Complex logic should be in Core where it can be tested.
+    Functions exceeding shell_max_branches are flagged as INFO.
+
+    Use @shell_complexity marker to exempt justified complexity.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind, RuleConfig
+        >>> sym = Symbol(name="process", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> source = "def process(x):\\n    return x"
+        >>> info = FileInfo(path="shell/cli.py", lines=5, symbols=[sym], is_shell=True, source=source)
+        >>> check_shell_too_complex(info, RuleConfig())
+        []
+    """
+    violations: list[Violation] = []
+    if not file_info.is_shell:
+        return violations
+
+    max_branches = config.shell_max_branches
+
+    for symbol in file_info.symbols:
+        if symbol.kind != SymbolKind.FUNCTION:
+            continue
+
+        # Skip if marked with @shell_complexity
+        if has_complexity_marker(symbol, file_info.source):
+            continue
+
+        # Skip entry points
+        if is_entry_point(symbol, file_info.source):
+            continue
+
+        # Count branches in symbol source
+        symbol_source = get_symbol_source(symbol, file_info.source)
+        branches = count_branches(symbol_source)
+
+        if branches > max_branches:
+            violations.append(
+                Violation(
+                    rule="shell_too_complex",
+                    severity=Severity.INFO,
+                    file=file_info.path,
+                    line=symbol.line,
+                    message=f"Shell function '{symbol.name}' has {branches} branches (max: {max_branches})",
+                    suggestion="Extract logic to Core, or add: # @shell_complexity: <reason>",
+                )
+            )
+
+    return violations
+
+
+@pre(lambda violations, limit: isinstance(violations, list) and limit > 0)
+@post(lambda result: isinstance(result, list))
+def check_complexity_debt(violations: list[Violation], limit: int = 5) -> list[Violation]:
+    """
+    Check project-level complexity debt (DX-22 Fix-or-Explain).
+
+    When the project has too many unaddressed shell_too_complex warnings,
+    escalate to ERROR to force resolution.
+
+    Examples:
+        >>> from invar.core.models import Violation, Severity
+        >>> v1 = Violation(rule="shell_too_complex", severity=Severity.INFO, file="a.py", message="m")
+        >>> v2 = Violation(rule="shell_too_complex", severity=Severity.INFO, file="b.py", message="m")
+        >>> check_complexity_debt([v1, v2], limit=5)
+        []
+        >>> many = [Violation(rule="shell_too_complex", severity=Severity.INFO, file=f"{i}.py", message="m") for i in range(6)]
+        >>> result = check_complexity_debt(many, limit=5)
+        >>> len(result)
+        1
+        >>> result[0].severity == Severity.ERROR
+        True
+    """
+    unaddressed = [v for v in violations if v.rule == "shell_too_complex"]
+    if len(unaddressed) >= limit:
+        return [
+            Violation(
+                rule="shell_complexity_debt",
+                severity=Severity.ERROR,
+                file="<project>",
+                line=None,
+                message=f"Project has {len(unaddressed)} unaddressed complexity warnings (limit: {limit})",
+                suggestion="You must address these before proceeding:\n1. Refactor to reduce branches, OR\n2. Add @shell_complexity: markers with justification",
+            )
+        ]
+    return []

invar/core/suggestions.py

@@ -65,6 +65,8 @@ def generate_contract_suggestion(signature: str) -> str:
     for name, type_hint in params:
         if not name:  # Skip empty names from malformed signatures
             continue
+        if name in ("self", "cls"):  # Skip method receiver parameters
+            continue
         param_names.append(name)
         if not type_hint:
             continue
@@ -86,6 +88,10 @@ def _extract_params(signature: str) -> list[tuple[str, str | None]]:
     """
     Extract parameters and their types from a signature.
 
+    MINOR-2 Limitation: Uses naive comma splitting which breaks for complex types
+    like Callable[[int, str], bool] where commas appear inside nested brackets.
+    This is acceptable since suggestions are advisory, not strict validation.
+
     Examples:
         >>> _extract_params("(x: int, y: str) -> bool")
         [('x', 'int'), ('y', 'str')]

invar/core/tautology.py

@@ -48,6 +48,7 @@ def is_semantic_tautology(expression: str) -> tuple[bool, str]:
         return (False, "")
 
 
+@pre(lambda node: isinstance(node, ast.expr))
 @post(lambda result: isinstance(result, tuple) and len(result) == 2)
 def _check_tautology_patterns(node: ast.expr) -> tuple[bool, str]:
     """Check for common tautology patterns in AST node."""

invar/core/utils.py

@@ -37,6 +37,52 @@ def get_exit_code(report: GuardReport, strict: bool) -> int:
     return 0
 
 
+@pre(lambda report, strict, doctest_passed=True, crosshair_passed=True, property_passed=True: isinstance(report, GuardReport))
+@post(lambda result: result in ("passed", "failed"))
+def get_combined_status(
+    report: GuardReport,
+    strict: bool,
+    doctest_passed: bool = True,
+    crosshair_passed: bool = True,
+    property_passed: bool = True,
+) -> str:
+    """
+    Calculate true guard status including all test phases (DX-26).
+
+    Unlike GuardReport.passed which only checks static errors,
+    this function combines static analysis with runtime test results.
+
+    Examples:
+        >>> from invar.core.models import GuardReport
+        >>> report = GuardReport(files_checked=1)
+        >>> get_combined_status(report, strict=False)
+        'passed'
+        >>> get_combined_status(report, strict=False, doctest_passed=False)
+        'failed'
+        >>> report.errors = 1
+        >>> get_combined_status(report, strict=False)
+        'failed'
+        >>> report2 = GuardReport(files_checked=1, warnings=1)
+        >>> get_combined_status(report2, strict=True)
+        'failed'
+        >>> get_combined_status(report2, strict=False)
+        'passed'
+    """
+    # Static analysis failures
+    if report.errors > 0:
+        return "failed"
+    if strict and report.warnings > 0:
+        return "failed"
+    # Runtime test failures
+    if not doctest_passed:
+        return "failed"
+    if not crosshair_passed:
+        return "failed"
+    if not property_passed:
+        return "failed"
+    return "passed"
+
+
 @pre(lambda data, source: isinstance(data, dict) and isinstance(source, str))
 @post(lambda result: isinstance(result, dict))
 def extract_guard_section(data: dict[str, Any], source: str) -> dict[str, Any]:
@@ -188,6 +234,9 @@ def parse_guard_config(guard_config: dict[str, Any]) -> RuleConfig:
     """
     Parse configuration from guard section.
 
+    DX-22: Removed deprecated options (use_code_lines, exclude_doctest_lines).
+    These are now always enabled by default.
+
     Examples:
         >>> cfg = parse_guard_config({"max_file_lines": 400})
         >>> cfg.max_file_lines
@@ -200,9 +249,6 @@ def parse_guard_config(guard_config: dict[str, Any]) -> RuleConfig:
         1
         >>> cfg.rule_exclusions[0].pattern
         '**/gen/**'
-        >>> cfg = parse_guard_config({"use_code_lines": "invalid"})  # Invalid type ignored
-        >>> cfg.use_code_lines  # Falls back to model default (False)
-        False
     """
     kwargs: dict[str, Any] = {}
 
@@ -212,7 +258,8 @@ def parse_guard_config(guard_config: dict[str, Any]) -> RuleConfig:
             kwargs[key] = val
 
     # Bool fields
-    for key in ("require_contracts", "require_doctests", "strict_pure", "use_code_lines", "exclude_doctest_lines"):
+    # DX-22: Removed use_code_lines, exclude_doctest_lines (deprecated)
+    for key in ("require_contracts", "require_doctests", "strict_pure"):
         if (val := _get_bool(guard_config, key)) is not None:
             kwargs[key] = val
 

invar/core/verification_routing.py

@@ -0,0 +1,158 @@
+"""
+Verification routing logic for smart tool selection.
+
+DX-22: Automatically routes code to CrossHair or Hypothesis based on imports.
+Core module: Pure logic, no I/O.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+from deal import post, pre
+
+
+class VerificationTool(Enum):
+    """Verification tool selection."""
+
+    CROSSHAIR = "crosshair"
+    HYPOTHESIS = "hypothesis"
+    SKIP = "skip"
+
+
+# C extensions that CrossHair cannot symbolically execute
+# These libraries use native code that breaks symbolic execution
+CROSSHAIR_INCOMPATIBLE_LIBS = frozenset(
+    [
+        # Scientific computing (C/Fortran extensions)
+        "numpy",
+        "pandas",
+        "scipy",
+        "sklearn",
+        "scikit-learn",
+        # Deep learning (CUDA/C++ backends)
+        "torch",
+        "tensorflow",
+        "keras",
+        "jax",
+        # Image processing (C extensions)
+        "cv2",
+        "PIL",
+        "pillow",
+        "skimage",
+        # Network I/O (non-deterministic)
+        "requests",
+        "aiohttp",
+        "httpx",
+        "urllib3",
+        # System calls (side effects)
+        "subprocess",
+        "multiprocessing",
+        # Database I/O
+        "sqlalchemy",
+        "psycopg2",
+        "pymongo",
+    ]
+)
+
+# Regex pattern to detect imports
+# Matches: import numpy, from numpy import, import numpy as np
+_IMPORT_PATTERN = re.compile(
+    r"^\s*(?:import\s+(\w+)|from\s+(\w+)(?:\.\w+)*\s+import)",
+    re.MULTILINE,
+)
+
+
+@pre(lambda source: isinstance(source, str))
+@post(lambda result: isinstance(result, bool))
+def has_incompatible_imports(source: str) -> bool:
+    """
+    Check if source contains imports incompatible with CrossHair.
+
+    DX-22: Detects C extension libraries that cannot be symbolically executed.
+    Used to route code directly to Hypothesis instead of wasting time on CrossHair.
+
+    Examples:
+        >>> has_incompatible_imports("import numpy as np")
+        True
+        >>> has_incompatible_imports("from pandas import DataFrame")
+        True
+        >>> has_incompatible_imports("from pathlib import Path")
+        False
+        >>> has_incompatible_imports("import json")
+        False
+        >>> has_incompatible_imports("from sklearn.model_selection import train_test_split")
+        True
+        >>> has_incompatible_imports("import torch.nn as nn")
+        True
+        >>> has_incompatible_imports("")
+        False
+    """
+    # Early return for empty/whitespace-only strings (avoids regex edge cases)
+    if not source or not source.strip():
+        return False
+    for match in _IMPORT_PATTERN.finditer(source):
+        lib = match.group(1) or match.group(2)
+        if lib and lib.lower() in CROSSHAIR_INCOMPATIBLE_LIBS:
+            return True
+    return False
+
+
+@pre(lambda source: isinstance(source, str))
+@post(lambda result: isinstance(result, set))
+def get_incompatible_imports(source: str) -> set[str]:
+    """
+    Get the set of incompatible libraries imported in source.
+
+    Examples:
+        >>> sorted(get_incompatible_imports("import numpy\\nfrom pandas import DataFrame"))
+        ['numpy', 'pandas']
+        >>> get_incompatible_imports("import json")
+        set()
+        >>> sorted(get_incompatible_imports("import torch\\nimport tensorflow"))
+        ['tensorflow', 'torch']
+        >>> get_incompatible_imports("")
+        set()
+    """
+    # Early return for empty/whitespace-only strings (avoids regex edge cases)
+    if not source or not source.strip():
+        return set()
+    incompatible: set[str] = set()
+    for match in _IMPORT_PATTERN.finditer(source):
+        lib = match.group(1) or match.group(2)
+        if lib and lib.lower() in CROSSHAIR_INCOMPATIBLE_LIBS:
+            incompatible.add(lib.lower())
+    return incompatible
+
+
+@pre(lambda source, has_contracts: isinstance(source, str) and isinstance(has_contracts, bool))
+@post(lambda result: isinstance(result, VerificationTool))
+def select_verification_tool(source: str, has_contracts: bool) -> VerificationTool:
+    """
+    Select the appropriate verification tool for a source file.
+
+    DX-22 Smart Routing:
+    - No contracts -> SKIP (nothing to verify)
+    - Has C extensions -> HYPOTHESIS (CrossHair will fail)
+    - Pure Python with contracts -> CROSSHAIR (can prove correctness)
+
+    Examples:
+        >>> select_verification_tool("def foo(): pass", has_contracts=False)
+        <VerificationTool.SKIP: 'skip'>
+        >>> select_verification_tool("import numpy\\n@pre(lambda x: x > 0)\\ndef foo(x): pass", has_contracts=True)
+        <VerificationTool.HYPOTHESIS: 'hypothesis'>
+        >>> select_verification_tool("@pre(lambda x: x > 0)\\ndef foo(x): pass", has_contracts=True)
+        <VerificationTool.CROSSHAIR: 'crosshair'>
+        >>> select_verification_tool("", has_contracts=False)
+        <VerificationTool.SKIP: 'skip'>
+        >>> select_verification_tool("", has_contracts=True)
+        <VerificationTool.CROSSHAIR: 'crosshair'>
+    """
+    if not has_contracts:
+        return VerificationTool.SKIP
+
+    if has_incompatible_imports(source):
+        return VerificationTool.HYPOTHESIS
+
+    return VerificationTool.CROSSHAIR

invar/invariant.py

@@ -20,6 +20,7 @@ class InvariantViolation(Exception):
 _INVAR_CHECK = os.environ.get("INVAR_CHECK", "1") == "1"
 
 
+# @invar:allow entry_point_too_thick: False positive - .get() matches router.get pattern
 def invariant(condition: bool, message: str = "") -> None:
     """
     Assert loop invariant. Checked at runtime when INVAR_CHECK=1.