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

invar/core/format_strategies.py

@@ -0,0 +1,197 @@
+"""
+Hypothesis strategies for format-driven property testing.
+
+DX-28: Strategies that generate realistic test data matching
+production formats, enabling property tests to catch semantic bugs.
+
+These strategies are optional - they require Hypothesis to be installed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from deal import post, pre
+from invar_runtime import skip_property_test
+
+if TYPE_CHECKING:
+    from hypothesis.strategies import SearchStrategy
+
+try:
+    from hypothesis import strategies as st
+
+    HYPOTHESIS_AVAILABLE = True
+except ImportError:
+    HYPOTHESIS_AVAILABLE = False
+
+
+@skip_property_test("no_params: Zero-parameter function, property testing cannot vary inputs")
+@post(lambda result: result is not None)
+def crosshair_line() -> SearchStrategy[str]:
+    """
+    Generate a CrossHair counterexample line.
+
+    Format: `file.py:line: error: ErrorType when calling func(args)`
+
+    Examples:
+        >>> if HYPOTHESIS_AVAILABLE:
+        ...     line = crosshair_line().example()
+        ...     assert ": error:" in line.lower()
+    """
+    if not HYPOTHESIS_AVAILABLE:
+        raise ImportError("Hypothesis required: pip install hypothesis")
+
+    filenames = st.from_regex(r"[a-z_]{1,20}\.py", fullmatch=True)
+    line_nums = st.integers(min_value=1, max_value=1000)
+    error_types = st.sampled_from(
+        [
+            "IndexError",
+            "KeyError",
+            "ValueError",
+            "TypeError",
+            "AssertionError",
+            "ZeroDivisionError",
+        ]
+    )
+    func_names = st.from_regex(r"[a-z_]{1,15}", fullmatch=True)
+    args = st.from_regex(r"[a-z]=-?\d{1,5}", fullmatch=True)
+
+    return st.builds(
+        lambda f, ln, e, fn, a: f"{f}:{ln}: error: {e} when calling {fn}({a})",
+        filenames,
+        line_nums,
+        error_types,
+        func_names,
+        args,
+    )
+
+
+@pre(lambda min_errors, max_errors: min_errors >= 0 and max_errors >= min_errors)
+@post(lambda result: result is not None)
+def crosshair_output(
+    min_errors: int = 0,
+    max_errors: int = 5,
+) -> SearchStrategy[str]:
+    """
+    Generate complete CrossHair output with multiple lines.
+
+    Args:
+        min_errors: Minimum number of error lines
+        max_errors: Maximum number of error lines
+
+    Examples:
+        >>> if HYPOTHESIS_AVAILABLE:
+        ...     output = crosshair_output(min_errors=1, max_errors=3).example()
+        ...     assert ": error:" in output.lower()
+    """
+    if not HYPOTHESIS_AVAILABLE:
+        raise ImportError("Hypothesis required: pip install hypothesis")
+
+    headers = st.sampled_from(
+        [
+            "Checking module...",
+            "Running crosshair check...",
+            "",
+        ]
+    )
+
+    error_lines = st.lists(crosshair_line(), min_size=min_errors, max_size=max_errors)
+
+    footers = st.sampled_from(
+        [
+            "",
+            "Done.",
+        ]
+    )
+
+    return st.builds(
+        lambda h, errors, f: "\n".join([h, *errors, f]),
+        headers,
+        error_lines,
+        footers,
+    )
+
+
+@pre(lambda pattern, min_occurrences, max_occurrences: len(pattern) > 0 and min_occurrences >= 0)
+@post(lambda result: result is not None)
+def text_with_pattern(
+    pattern: str,
+    min_occurrences: int = 1,
+    max_occurrences: int = 5,
+) -> SearchStrategy[str]:
+    """
+    Generate text that contains a specific pattern.
+
+    Useful for testing extraction functions that should find
+    occurrences of a pattern in text.
+
+    Args:
+        pattern: The pattern that must appear in the output
+        min_occurrences: Minimum times pattern appears
+        max_occurrences: Maximum times pattern appears
+
+    Examples:
+        >>> if HYPOTHESIS_AVAILABLE:
+        ...     text = text_with_pattern(": error:", 2, 5).example()
+        ...     assert text.count(": error:") >= 2
+    """
+    if not HYPOTHESIS_AVAILABLE:
+        raise ImportError("Hypothesis required: pip install hypothesis")
+
+    # Generate lines that contain the pattern
+    prefix = st.from_regex(r"[a-z0-9_.]{1,30}", fullmatch=True)
+    suffix = st.from_regex(r"[a-zA-Z0-9 ]{1,50}", fullmatch=True)
+
+    pattern_line = st.builds(
+        lambda p, s: f"{p}{pattern}{s}",
+        prefix,
+        suffix,
+    )
+
+    # Generate noise lines without the pattern
+    noise_line = st.from_regex(r"[a-zA-Z0-9 ]{1,80}", fullmatch=True).filter(
+        lambda x: pattern not in x
+    )
+
+    # Combine into full output
+    pattern_lines = st.lists(
+        pattern_line, min_size=min_occurrences, max_size=max_occurrences
+    )
+    noise_lines = st.lists(noise_line, min_size=0, max_size=10)
+
+    return st.builds(
+        lambda p, n: "\n".join(p + n),
+        pattern_lines,
+        noise_lines,
+    ).map(lambda x: "\n".join(sorted(x.split("\n"), key=lambda _: __import__("random").random())))
+
+
+@pre(lambda pattern: len(pattern) > 0)
+@post(lambda result: result is not None)
+def extraction_test_case(
+    pattern: str,
+) -> SearchStrategy[tuple[str, int]]:
+    """
+    Generate (text, expected_count) pairs for testing extraction functions.
+
+    The expected_count is the number of lines that should be extracted.
+
+    Examples:
+        >>> if HYPOTHESIS_AVAILABLE:
+        ...     text, count = extraction_test_case(": error:").example()
+        ...     actual = len([l for l in text.split("\\n") if ": error:" in l])
+        ...     assert actual == count
+    """
+    if not HYPOTHESIS_AVAILABLE:
+        raise ImportError("Hypothesis required: pip install hypothesis")
+
+    count = st.integers(min_value=0, max_value=10)
+
+    return count.flatmap(
+        lambda c: st.tuples(
+            text_with_pattern(pattern, min_occurrences=c, max_occurrences=c)
+            if c > 0
+            else st.just("no matches here"),
+            st.just(c),
+        )
+    )

invar/core/formatter.py

@@ -200,12 +200,18 @@ def format_signatures_json(symbols: list[Symbol], file_path: str) -> dict:
 # Phase 8.2: Agent-mode formatting
 
 
-@pre(lambda report: isinstance(report, GuardReport))
-def format_guard_agent(report: GuardReport) -> dict:
+@pre(lambda report, combined_status=None: isinstance(report, GuardReport))
+def format_guard_agent(report: GuardReport, combined_status: str | None = None) -> dict:
     """
-    Format Guard report for Agent consumption (Phase 8.2).
+    Format Guard report for Agent consumption (Phase 8.2 + DX-26).
 
     Provides structured output with actionable fix instructions.
+    DX-26: status now reflects ALL test phases when combined_status is provided.
+
+    Args:
+        report: Guard analysis report
+        combined_status: True guard status including all test phases (DX-26).
+                        If None, uses report.passed (static-only, deprecated).
 
     Examples:
         >>> from invar.core.models import GuardReport, Violation, Severity
@@ -219,9 +225,26 @@ def format_guard_agent(report: GuardReport) -> dict:
         'passed'
         >>> len(d["fixes"])
         1
+        >>> # DX-26: combined_status overrides report.passed
+        >>> d2 = format_guard_agent(report, combined_status="failed")
+        >>> d2["status"]
+        'failed'
+        >>> d2["static"]["passed"]  # Static still shows passed
+        True
     """
+    # DX-26: Use combined status if provided, else fall back to static-only
+    status = combined_status if combined_status else ("passed" if report.passed else "failed")
+    static_passed = report.errors == 0
+
     return {
-        "status": "passed" if report.passed else "failed",
+        "status": status,
+        # DX-26: Separate static results from combined status
+        "static": {
+            "passed": static_passed,
+            "errors": report.errors,
+            "warnings": report.warnings,
+            "infos": report.infos,
+        },
         "summary": {
             "files_checked": report.files_checked,
             "errors": report.errors,

invar/core/hypothesis_strategies.py

@@ -402,6 +402,51 @@ def _get_user_strategies(func: Callable) -> dict[str, StrategySpec]:
     return user_specs
 
 
+@pre(lambda source: isinstance(source, str))
+@post(lambda result: isinstance(result, list))
+def _extract_pre_lambdas_from_source(source: str) -> list[str]:
+    """
+    Extract lambda expressions from @pre decorators with balanced parenthesis.
+
+    >>> _extract_pre_lambdas_from_source("@pre(lambda x: x > 0)")
+    ['lambda x: x > 0']
+    >>> _extract_pre_lambdas_from_source("@pre(lambda x: len(x) > 0)")
+    ['lambda x: len(x) > 0']
+    >>> _extract_pre_lambdas_from_source("@pre(lambda x, y: isinstance(x, str))")
+    ['lambda x, y: isinstance(x, str)']
+    >>> _extract_pre_lambdas_from_source("")
+    []
+    """
+    results = []
+    i = 0
+    while i < len(source):
+        # Find @pre(
+        pre_match = re.search(r"@pre\s*\(", source[i:])
+        if not pre_match:
+            break
+        start = i + pre_match.end()
+
+        # Find matching closing paren with balance counting
+        paren_depth = 1
+        j = start
+        while j < len(source) and paren_depth > 0:
+            if source[j] == "(":
+                paren_depth += 1
+            elif source[j] == ")":
+                paren_depth -= 1
+            j += 1
+
+        if paren_depth == 0:
+            # Extract content between @pre( and matching )
+            content = source[start : j - 1].strip()
+            if content.startswith("lambda"):
+                results.append(content)
+
+        i = j
+
+    return results
+
+
 @pre(lambda func: callable(func))
 @post(lambda result: isinstance(result, list))
 def _extract_pre_sources(func: Callable) -> list[str]:
@@ -413,13 +458,10 @@ def _extract_pre_sources(func: Callable) -> list[str]:
         # deal stores contracts in _deal attribute
         pass
 
-    # Try to extract from source
+    # Try to extract from source using balanced parenthesis matching
     try:
         source = inspect.getsource(func)
-        # Find @pre decorators
-        pre_pattern = r"@pre\s*\(\s*(lambda[^)]+)\s*\)"
-        matches = re.findall(pre_pattern, source)
-        pre_sources.extend(matches)
+        pre_sources.extend(_extract_pre_lambdas_from_source(source))
     except (OSError, TypeError):
         pass
 

invar/core/lambda_helpers.py

@@ -8,6 +8,7 @@ import re
 from deal import post, pre
 
 
+@pre(lambda tree: isinstance(tree, ast.AST))
 @post(lambda result: result is None or isinstance(result, ast.Lambda))
 def find_lambda(tree: ast.Expression) -> ast.Lambda | None:
     """Find the lambda node in an expression tree.

invar/core/models.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from enum import Enum
 from typing import Literal
 
-from deal import pre
+from deal import post, pre
 from pydantic import BaseModel, Field
 
 
@@ -133,7 +133,7 @@ class GuardReport(BaseModel):
         self.core_functions_with_contracts += with_contracts
 
     @property
-    @pre(lambda self: isinstance(self, GuardReport))
+    @post(lambda result: 0 <= result <= 100)
     def contract_coverage_pct(self) -> int:
         """
         Get contract coverage percentage (P24).
@@ -150,7 +150,7 @@ class GuardReport(BaseModel):
         return int(self.core_functions_with_contracts / self.core_functions_total * 100)
 
     @property
-    @pre(lambda self: isinstance(self, GuardReport))
+    @post(lambda result: all(k in result for k in ("tautology", "empty", "partial", "type_only")))
     def contract_issue_counts(self) -> dict[str, int]:
         """
         Count contract quality issues by type (P24).
@@ -178,7 +178,7 @@ class GuardReport(BaseModel):
         return counts
 
     @property
-    @pre(lambda self: isinstance(self, GuardReport))
+    @post(lambda result: isinstance(result, bool))
     def passed(self) -> bool:
         """
         Check if guard passed (no errors).
@@ -218,10 +218,18 @@ class RuleConfig(BaseModel):
         500
         >>> config.strict_pure  # Phase 9 P12: Default ON for agents
         True
+        >>> # MINOR-6: Value ranges validated
+        >>> RuleConfig(max_file_lines=0)  # doctest: +IGNORE_EXCEPTION_DETAIL
+        Traceback (most recent call last):
+        pydantic_core._pydantic_core.ValidationError: ...
     """
 
-    max_file_lines: int = 500  # Phase 9 P1: Raised from 300 for less friction
-    max_function_lines: int = 50
+    # MINOR-6: Added ge=1 constraints for numeric fields
+    max_file_lines: int = Field(default=500, ge=1)  # Phase 9 P1: Raised from 300
+    max_function_lines: int = Field(default=50, ge=1)
+    entry_max_lines: int = Field(default=15, ge=1)  # DX-23: Entry point max lines
+    shell_max_branches: int = Field(default=3, ge=1)  # DX-22: Shell function max branches
+    shell_complexity_debt_limit: int = Field(default=5, ge=0)  # DX-22: 0 = no limit
     forbidden_imports: tuple[str, ...] = (
         "os",
         "sys",
@@ -236,18 +244,15 @@ class RuleConfig(BaseModel):
     require_contracts: bool = True
     require_doctests: bool = True
     strict_pure: bool = True  # Phase 9 P12: Default ON for agent-native
-    use_code_lines: bool = False
-    exclude_doctest_lines: bool = False
+    # DX-22: Removed use_code_lines and exclude_doctest_lines
+    # (merged into default behavior - always exclude doctest lines from size calc)
     # Phase 9 P1: Rule exclusions for specific file patterns
     rule_exclusions: list[RuleExclusion] = Field(default_factory=list)
     # Phase 9 P2: Per-rule severity overrides (off, info, warning, error)
-    severity_overrides: dict[str, str] = Field(
-        default_factory=lambda: {
-            "redundant_type_contract": "off",  # Expected behavior when forcing contracts
-        }
-    )
+    # DX-22: Simplified defaults - most rules have correct severity now
+    severity_overrides: dict[str, str] = Field(default_factory=dict)
     # Phase 9 P8: File size warning threshold (0 to disable, 0.8 = warn at 80%)
-    size_warning_threshold: float = 0.8
+    size_warning_threshold: float = Field(default=0.8, ge=0.0, le=1.0)
     # B4: User-declared purity (override heuristics)
     purity_pure: list[str] = Field(default_factory=list)  # Known pure functions
     purity_impure: list[str] = Field(default_factory=list)  # Known impure functions
@@ -283,7 +288,8 @@ class PerceptionMap(BaseModel):
         5
     """
 
-    project_root: str
-    total_files: int
-    total_symbols: int
+    # MINOR-7: Added field validators
+    project_root: str = Field(min_length=1)
+    total_files: int = Field(ge=0)
+    total_symbols: int = Field(ge=0)
     symbols: list[SymbolRefs] = Field(default_factory=list)

invar/core/parser.py

@@ -21,13 +21,13 @@ from invar.core.purity import (
 )
 
 
-@pre(lambda source, path="<string>": isinstance(source, str) and len(source) > 0)
+@pre(lambda source, path="<string>": isinstance(source, str) and len(source.strip()) > 0)
 def parse_source(source: str, path: str = "<string>") -> FileInfo | None:
     """
     Parse Python source code and extract symbols.
 
     Args:
-        source: Python source code as string
+        source: Python source code as string (must contain non-whitespace)
         path: Path for reporting (not used for I/O)
 
     Returns:
@@ -41,6 +41,10 @@ def parse_source(source: str, path: str = "<string>") -> FileInfo | None:
         1
         >>> info.symbols[0].name
         'foo'
+        >>> parse_source("   \\n\\t  ")  # Whitespace-only returns None via contract
+        Traceback (most recent call last):
+            ...
+        deal.PreContractError: ...
     """
     try:
         tree = ast.parse(source)

invar/core/property_gen.py

@@ -19,13 +19,18 @@ if TYPE_CHECKING:
 
 @dataclass
 class PropertyTestResult:
-    """Result of running a property test."""
+    """Result of running a property test.
+
+    DX-26: Added file_path and seed for actionable failure output.
+    """
 
     function_name: str
     passed: bool
     examples_run: int = 0
     counterexample: dict[str, Any] | None = None
     error: str | None = None
+    file_path: str | None = None  # DX-26: For file::function format
+    seed: int | None = None  # DX-26: Hypothesis seed for reproduction
 
 
 @dataclass
@@ -300,6 +305,10 @@ def build_test_function(
     # Build strategy dict
     strategy_dict = {}
     for param_name, strat_code in strategies.items():
+        # Skip functions with nothing() strategy (untestable types)
+        if "nothing()" in strat_code:
+            return None
+
         # Evaluate the strategy code
         try:
             # strat_code is like "st.integers(min_value=0)"
@@ -322,16 +331,62 @@ def build_test_function(
     return property_test
 
 
-@pre(lambda func, max_examples: callable(func) and max_examples > 0)
+@pre(lambda error_str: isinstance(error_str, str))
+@post(lambda result: result is None or isinstance(result, int))
+def _extract_hypothesis_seed(error_str: str) -> int | None:
+    """Extract Hypothesis seed from error message (DX-26).
+
+    Hypothesis includes seed in output like: @seed(336048909179393285647920446708996038674)
+
+    >>> _extract_hypothesis_seed("@seed(123456)")
+    123456
+    >>> _extract_hypothesis_seed("no seed here") is None
+    True
+    """
+    import re
+
+    match = re.search(r"@seed\((\d+)\)", error_str)
+    if match:
+        try:
+            return int(match.group(1))
+        except ValueError:
+            pass
+    return None
+
+
+@pre(lambda name, reason: isinstance(name, str) and isinstance(reason, str))
+@post(lambda result: isinstance(result, PropertyTestResult) and result.passed)
+def _skip_result(name: str, reason: str) -> PropertyTestResult:
+    """Create a skip result (passed=True, 0 examples)."""
+    return PropertyTestResult(function_name=name, passed=True, examples_run=0, error=reason)
+
+
+# Skip patterns for untestable error detection
+_SKIP_PATTERNS = (
+    "Nothing", "NoSuchExample", "filter_too_much", "Could not resolve",
+    "validation error", "missing", "positional argument", "Unable to satisfy",
+)
+
+
+@pre(lambda err_str, func_name, max_examples: isinstance(err_str, str))
 @post(lambda result: isinstance(result, PropertyTestResult))
-def run_property_test(
-    func: Callable,
-    max_examples: int = 100,
+def _handle_test_exception(
+    err_str: str, func_name: str, max_examples: int
 ) -> PropertyTestResult:
+    """Handle exception from property test, returning skip or failure result."""
+    if any(p in err_str for p in _SKIP_PATTERNS):
+        return _skip_result(func_name, "Skipped: untestable types")
+    seed = _extract_hypothesis_seed(err_str)
+    return PropertyTestResult(func_name, passed=False, examples_run=max_examples, error=err_str, seed=seed)
+
+
+@pre(lambda func, max_examples: callable(func) and max_examples > 0)
+@post(lambda result: isinstance(result, PropertyTestResult))
+def run_property_test(func: Callable, max_examples: int = 100) -> PropertyTestResult:
     """
     Run a property test on a single function.
 
-    Generates strategies from contracts and runs Hypothesis.
+    Uses deal.cases() which respects @pre conditions and generates valid inputs.
 
     >>> from deal import pre, post
     >>> @pre(lambda x: x >= 0)
@@ -344,40 +399,26 @@ def run_property_test(
     """
     func_name = getattr(func, "__name__", "unknown")
 
-    # Generate test
-    generated = generate_property_test(func)
-    if generated is None:
-        return PropertyTestResult(
-            function_name=func_name,
-            passed=True,  # No test generated = skip, not fail
-            examples_run=0,
-            error="Could not generate test (no contracts or unparseable)",
-        )
-
-    # Build executable test
-    test_fn = build_test_function(func, generated.strategies, max_examples)
-    if test_fn is None:
-        return PropertyTestResult(
-            function_name=func_name,
-            passed=True,
-            examples_run=0,
-            error="Could not build test (hypothesis not available or strategy error)",
-        )
-
-    # Run the test
     try:
-        test_fn()
-        return PropertyTestResult(
-            function_name=func_name,
-            passed=True,
-            examples_run=max_examples,
+        import deal
+        from hypothesis import HealthCheck, Verbosity, settings
+
+        # DX-26: Suppress Hypothesis output (seed messages) for clean JSON
+        test_settings = settings(
+            max_examples=max_examples,
+            suppress_health_check=[HealthCheck.filter_too_much, HealthCheck.too_slow],
+            verbosity=Verbosity.quiet,
         )
+        test_case = deal.cases(func, count=max_examples, settings=test_settings)
+        test_case()
+        return PropertyTestResult(func_name, passed=True, examples_run=max_examples)
+    except deal.PreContractError:
+        return _skip_result(func_name, "Skipped: could not generate valid inputs")
+    except deal.PostContractError as e:
+        err_str = str(e)
+        seed = _extract_hypothesis_seed(err_str)
+        return PropertyTestResult(func_name, passed=False, examples_run=max_examples, error=err_str, seed=seed)
+    except ImportError:
+        pass  # Fall through to custom strategy approach
     except Exception as e:
-        # Extract counterexample if available
-        error_str = str(e)
-        return PropertyTestResult(
-            function_name=func_name,
-            passed=False,
-            examples_run=max_examples,
-            error=error_str,
-        )
+        return _handle_test_exception(str(e), func_name, max_examples)

invar/core/purity.py

@@ -18,11 +18,13 @@ from deal import pre
 from invar.core.models import FileInfo, RuleConfig, Severity, SymbolKind, Violation
 
 # Known impure functions and method patterns
+# MINOR-3: "time" matches `from time import time; time()` which IS impure.
+# May false positive on local functions named `time`, but this is rare.
 IMPURE_FUNCTIONS: set[str] = {
     "now",
     "today",
     "utcnow",
-    "time",
+    "time",  # from time import time
     "random",
     "randint",
     "randrange",
@@ -155,7 +157,12 @@ def extract_function_calls(node: ast.FunctionDef | ast.AsyncFunctionDef) -> list
 
 @pre(lambda call: isinstance(call, ast.Call) and hasattr(call, "func"))
 def _get_call_name(call: ast.Call) -> str | None:
-    """Get the name of a function call as a string."""
+    """Get the name of a function call as a string.
+
+    MINOR-4 Limitation: Only handles one level of attribute access (obj.method).
+    Chained access like a.b.method() returns None. This is acceptable since
+    IMPURE_PATTERNS only contains two-level patterns like ("datetime", "now").
+    """
     func = call.func
 
     # Simple name: print(), open()
@@ -268,8 +275,7 @@ def count_doctest_lines(node: ast.FunctionDef | ast.AsyncFunctionDef) -> int:
             count += 1  # Continuation line
         elif in_doctest and stripped and not stripped.startswith(">>>"):
             count += 1  # Expected output line
-            if not stripped:  # Empty line ends output
-                in_doctest = False
+            # Note: Empty line ends doctest, handled by else branch below
         else:
             in_doctest = False
     return count