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

invar/core/format_specs.py

@@ -0,0 +1,195 @@
+"""
+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()
+
+
+@post(lambda result: all(isinstance(line, str) and line.strip() for line in result))  # Non-empty strings
+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()
+    ]

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

@@ -15,7 +15,7 @@ from invar.core.models import GuardReport, PerceptionMap, Symbol, SymbolRefs, Vi
 from invar.core.rule_meta import get_rule_meta
 
 
-@pre(lambda perception_map, top_n=0: isinstance(perception_map, PerceptionMap))
+@pre(lambda perception_map, top_n=0: top_n >= 0)
 def format_map_text(perception_map: PerceptionMap, top_n: int = 0) -> str:
     """
     Format perception map as plain text.
@@ -121,7 +121,6 @@ def format_map_json(perception_map: PerceptionMap, top_n: int = 0) -> dict:
     }
 
 
-@pre(lambda sr: isinstance(sr, SymbolRefs))
 @post(lambda result: "name" in result and "ref_count" in result)
 def _symbol_refs_to_dict(sr: SymbolRefs) -> dict:
     """Convert SymbolRefs to dict."""
@@ -138,7 +137,7 @@ def _symbol_refs_to_dict(sr: SymbolRefs) -> dict:
     }
 
 
-@pre(lambda symbol, file_path: isinstance(symbol, Symbol))
+@pre(lambda symbol, file_path: len(file_path) > 0)
 def format_signature(symbol: Symbol, file_path: str) -> str:
     """
     Format a single symbol signature.
@@ -154,7 +153,7 @@ def format_signature(symbol: Symbol, file_path: str) -> str:
     return f"{file_path}::{symbol.name}{sig}"
 
 
-@pre(lambda symbols, file_path: isinstance(symbols, list))
+@pre(lambda symbols, file_path: len(file_path) > 0)
 def format_signatures_text(symbols: list[Symbol], file_path: str) -> str:
     """
     Format multiple signatures as text.
@@ -169,7 +168,7 @@ def format_signatures_text(symbols: list[Symbol], file_path: str) -> str:
     return "\n".join(lines)
 
 
-@pre(lambda symbols, file_path: isinstance(symbols, list))
+@pre(lambda symbols, file_path: len(file_path) > 0)
 def format_signatures_json(symbols: list[Symbol], file_path: str) -> dict:
     """
     Format signatures as JSON-serializable dict.
@@ -200,12 +199,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: combined_status is None or combined_status in ("passed", "failed"))
+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 +224,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,
@@ -232,7 +254,7 @@ def format_guard_agent(report: GuardReport) -> dict:
     }
 
 
-@pre(lambda v: isinstance(v, Violation))
+@post(lambda result: "file" in result and "rule" in result and "severity" in result)
 def _violation_to_fix(v: Violation) -> dict:
     """Convert a Violation to an Agent-friendly fix instruction."""
     fix_info = _parse_suggestion(v.suggestion, v.rule) if v.suggestion else None

invar/core/hypothesis_strategies.py

@@ -24,7 +24,7 @@ _hypothesis_available = False
 _numpy_available = False
 
 
-@post(lambda result: isinstance(result, bool))
+# @invar:allow missing_contract: Boolean availability check, no meaningful contract
 def _ensure_hypothesis() -> bool:
     """Check if hypothesis is available."""
     global _hypothesis_available
@@ -37,7 +37,7 @@ def _ensure_hypothesis() -> bool:
         return False
 
 
-@post(lambda result: isinstance(result, bool))
+# @invar:allow missing_contract: Boolean availability check, no meaningful contract
 def _ensure_numpy() -> bool:
     """Check if numpy is available."""
     global _numpy_available
@@ -363,7 +363,7 @@ def _get_user_strategies(func: Callable) -> dict[str, StrategySpec]:
 
     DX-12-B: Supports both strategy objects and string representations.
 
-    >>> from invar.decorators import strategy
+    >>> from invar_runtime import strategy
     >>> @strategy(x="floats(min_value=0)")
     ... def sqrt(x: float) -> float:
     ...     return x ** 0.5
@@ -402,6 +402,50 @@ def _get_user_strategies(func: Callable) -> dict[str, StrategySpec]:
     return user_specs
 
 
+@post(lambda result: all("lambda" in s for s in result))  # Only lambda expressions
+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,21 +457,17 @@ 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
 
     return pre_sources
 
 
-@pre(lambda bounds, strategy_name: isinstance(bounds, dict) and isinstance(strategy_name, str))
-@post(lambda result: isinstance(result, dict))
+@post(lambda result: all(k in ("min_value", "max_value", "min_size", "max_size", "exclude_min", "exclude_max") for k in result))
 def _bounds_to_strategy_kwargs(bounds: dict[str, Any], strategy_name: str) -> dict[str, Any]:
     """Convert bound constraints to Hypothesis strategy kwargs."""
     kwargs = {}

invar/core/inspect.py

@@ -1,5 +1,5 @@
 """
-File inspection for ICIDIV Inspect step (Phase 9.2 P14).
+File inspection for USBV Understand step (Phase 9.2 P14).
 
 Provides context about a file to help agents understand existing patterns
 before making changes.

invar/core/lambda_helpers.py

@@ -8,6 +8,7 @@ import re
 from deal import post, pre
 
 
+@pre(lambda tree: isinstance(tree, ast.AST) and hasattr(tree, '__class__'))
 @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.
@@ -51,8 +52,7 @@ def extract_annotations(signature: str) -> dict[str, str]:
     return annotations
 
 
-@pre(lambda expression: isinstance(expression, str))
-@post(lambda result: result is None or isinstance(result, list))
+@post(lambda result: result is None or all(isinstance(p, str) for p in result))  # Valid params
 def extract_lambda_params(expression: str) -> list[str] | None:
     """Extract parameter names from a lambda expression.
 
@@ -114,6 +114,7 @@ def extract_func_param_names(signature: str) -> list[str] | None:
     return params
 
 
+@pre(lambda node: isinstance(node, ast.expr) and hasattr(node, '__class__'))
 @post(lambda result: isinstance(result, set))
 def extract_used_names(node: ast.expr) -> set[str]:
     """Extract all variable names used in an expression (Load context).