invar-tools 1.4.0__py3-none-any.whl → 1.6.0__py3-none-any.whl

invar/core/trivial_detection.py

@@ -0,0 +1,189 @@
+"""Trivial contract detection for DX-63.
+
+Pure logic module - no I/O. Detects contracts that provide no real constraint.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+
+from deal import post, pre
+
+
+@dataclass
+class TrivialContract:
+    """A trivial contract that provides no real constraint.
+
+    Examples:
+        >>> tc = TrivialContract(
+        ...     file="src/core/calc.py",
+        ...     line=10,
+        ...     function_name="process",
+        ...     contract_type="post",
+        ...     expression="lambda: True"
+        ... )
+        >>> tc.contract_type
+        'post'
+    """
+
+    file: str
+    line: int
+    function_name: str
+    contract_type: str  # "pre" or "post"
+    expression: str
+
+
+# Patterns that match trivial contracts
+TRIVIAL_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"^\s*lambda\s*:\s*True\s*$"),  # lambda: True
+    re.compile(r"^\s*lambda\s+\w+\s*:\s*True\s*$"),  # lambda x: True
+    re.compile(r"^\s*lambda\s+[\w,\s]+:\s*True\s*$"),  # lambda x, y: True
+    re.compile(r"^\s*lambda\s+\*\w+\s*:\s*True\s*$"),  # lambda *args: True
+    re.compile(r"^\s*lambda\s+\*\*\w+\s*:\s*True\s*$"),  # lambda **kwargs: True
+    re.compile(r"^\s*lambda\s+result\s*:\s*True\s*$"),  # lambda result: True
+    re.compile(r"^\s*lambda\s+_\s*:\s*True\s*$"),  # lambda _: True
+]
+
+
+@pre(lambda expression: len(expression.strip()) > 0)
+@post(lambda result: isinstance(result, bool))
+def is_trivial_contract(expression: str) -> bool:
+    """Check if a contract expression is trivial (provides no constraint).
+
+    Trivial contracts always return True regardless of input, providing
+    no actual constraint on the function's behavior.
+
+    Examples:
+        >>> is_trivial_contract("lambda: True")
+        True
+        >>> is_trivial_contract("lambda x: True")
+        True
+        >>> is_trivial_contract("lambda x, y: True")
+        True
+        >>> is_trivial_contract("lambda result: True")
+        True
+        >>> is_trivial_contract("lambda x: x > 0")
+        False
+        >>> is_trivial_contract("lambda items: len(items) > 0")
+        False
+        >>> is_trivial_contract("lambda result: result >= 0")
+        False
+    """
+    expr = expression.strip()
+    return any(pattern.match(expr) for pattern in TRIVIAL_PATTERNS)
+
+
+@pre(lambda node: isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)))
+@post(lambda result: all(t[0] in ("pre", "post") for t in result))
+def extract_contracts_from_decorators(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[tuple[str, str]]:
+    """Extract contract expressions from function decorators.
+
+    Returns list of (contract_type, expression) tuples.
+
+    Examples:
+        >>> import ast
+        >>> code = '''
+        ... @pre(lambda x: x > 0)
+        ... @post(lambda result: result >= 0)
+        ... def calc(x): return x * 2
+        ... '''
+        >>> tree = ast.parse(code)
+        >>> func = tree.body[0]
+        >>> contracts = extract_contracts_from_decorators(func)
+        >>> len(contracts)
+        2
+        >>> contracts[0][0]
+        'pre'
+    """
+    contracts = []
+
+    for decorator in node.decorator_list:
+        if isinstance(decorator, ast.Call):
+            # Get decorator name
+            if isinstance(decorator.func, ast.Name):
+                name = decorator.func.id
+            elif isinstance(decorator.func, ast.Attribute):
+                name = decorator.func.attr
+            else:
+                continue
+
+            # Check if it's a contract decorator
+            if name in ("pre", "post"):
+                # Get the first argument (the lambda or condition)
+                if decorator.args:
+                    arg = decorator.args[0]
+                    if isinstance(arg, ast.Lambda):
+                        # Convert lambda back to source
+                        expr = ast.unparse(arg)
+                        contracts.append((name, expr))
+
+    return contracts
+
+
+@pre(lambda source, file_path: len(source) >= 0 and len(file_path) > 0)
+@post(lambda result: result[0] >= 0 and result[1] >= 0 and result[1] <= result[0])
+def analyze_contracts_in_source(
+    source: str, file_path: str
+) -> tuple[int, int, list[TrivialContract]]:
+    """Analyze contracts in Python source code.
+
+    Pure function - receives source as string, no file I/O.
+
+    Returns: (total_functions, functions_with_contracts, trivial_contracts)
+
+    Examples:
+        >>> source = '''
+        ... from deal import pre, post
+        ... @pre(lambda x: x > 0)
+        ... def good(x): return x
+        ... def no_contract(x): return x
+        ... @post(lambda: True)
+        ... def trivial(x): return x
+        ... '''
+        >>> total, with_c, trivials = analyze_contracts_in_source(source, "test.py")
+        >>> total
+        3
+        >>> with_c
+        2
+        >>> len(trivials)
+        1
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return (0, 0, [])
+
+    total_functions = 0
+    functions_with_contracts = 0
+    trivial_contracts: list[TrivialContract] = []
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # Skip private/dunder methods
+            if node.name.startswith("_"):
+                continue
+
+            total_functions += 1
+            contracts = extract_contracts_from_decorators(node)
+
+            if contracts:
+                functions_with_contracts += 1
+
+                # Check for trivial contracts
+                for contract_type, expr in contracts:
+                    if is_trivial_contract(expr):
+                        trivial_contracts.append(
+                            TrivialContract(
+                                file=file_path,
+                                line=node.lineno,
+                                function_name=node.name,
+                                contract_type=contract_type,
+                                expression=expr,
+                            )
+                        )
+
+    return (total_functions, functions_with_contracts, trivial_contracts)

invar/mcp/server.py

@@ -137,6 +137,7 @@ def _get_guard_tool() -> Tool:
                 "changed": {"type": "boolean", "description": "Only verify git-changed files", "default": True},
                 "strict": {"type": "boolean", "description": "Treat warnings as errors", "default": False},
                 "coverage": {"type": "boolean", "description": "DX-37: Collect branch coverage from doctest + hypothesis", "default": False},
+                "contracts_only": {"type": "boolean", "description": "DX-63: Contract coverage check only (skip tests)", "default": False},
             },
         },
     )
@@ -223,6 +224,9 @@ async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
     # DX-37: Optional coverage collection
     if args.get("coverage", False):
         cmd.append("--coverage")
+    # DX-63: Contract coverage check only
+    if args.get("contracts_only", False):
+        cmd.append("--contracts-only")
 
     # DX-26: TTY auto-detection - MCP runs in non-TTY, so agent JSON output is automatic
     # No explicit flag needed

invar/shell/commands/guard.py

@@ -25,7 +25,7 @@ from invar import __version__
 from invar.core.models import GuardReport, RuleConfig
 from invar.core.rules import check_all_rules
 from invar.core.utils import get_exit_code
-from invar.shell.config import load_config
+from invar.shell.config import find_project_root, load_config
 from invar.shell.fs import scan_project
 from invar.shell.guard_output import output_agent, output_rich
 
@@ -56,13 +56,13 @@ def _count_core_functions(file_info) -> tuple[int, int]:
     return (total, with_contracts)
 
 
-# @shell_complexity: Core orchestration - iterates files, handles failures, aggregates results
 # @shell_complexity: Core orchestration - iterates files, handles failures, aggregates results
 def _scan_and_check(
     path: Path, config: RuleConfig, only_files: set[Path] | None = None
 ) -> Result[GuardReport, str]:
     """Scan project files and check against rules."""
     from invar.core.entry_points import extract_escape_hatches
+    from invar.core.models import EscapeHatchDetail
     from invar.core.review_trigger import check_duplicate_escape_reasons
     from invar.core.shell_architecture import check_complexity_debt
 
@@ -80,10 +80,17 @@ def _scan_and_check(
         report.update_coverage(total, with_contracts)
         for violation in check_all_rules(file_info, config):
             report.add_violation(violation)
-        # DX-33: Collect escape hatches for cross-file analysis
+        # DX-33 + DX-66: Collect escape hatches for cross-file analysis and visibility
         if file_info.source:
-            for rule, reason in extract_escape_hatches(file_info.source):
+            for rule, reason, line in extract_escape_hatches(file_info.source):
                 all_escapes.append((file_info.path, rule, reason))
+                # DX-66: Add to escape hatch summary
+                report.escape_hatches.add(EscapeHatchDetail(
+                    file=file_info.path,
+                    line=line,
+                    rule=rule,
+                    reason=reason,
+                ))
 
     # DX-22: Check project-level complexity debt (Fix-or-Explain enforcement)
     for debt_violation in check_complexity_debt(
@@ -102,7 +109,11 @@ def _scan_and_check(
 @app.command()
 def guard(
     path: Path = typer.Argument(
-        Path(), help="Project root directory", exists=True, file_okay=False, dir_okay=True
+        Path(),
+        help="Project directory or single Python file",
+        exists=True,
+        file_okay=True,
+        dir_okay=True,
     ),
     strict: bool = typer.Option(False, "--strict", help="Treat warnings as errors"),
     changed: bool = typer.Option(
@@ -133,11 +144,19 @@ def guard(
     coverage: bool = typer.Option(
         False, "--coverage", help="DX-37: Collect branch coverage from doctest + hypothesis"
     ),
+    suggest: bool = typer.Option(
+        False, "--suggest", help="DX-61: Show functional pattern suggestions"
+    ),
+    contracts_only: bool = typer.Option(
+        False, "--contracts-only", "-c", help="DX-63: Contract coverage check only"
+    ),
 ) -> None:
     """Check project against Invar architecture rules.
 
     Smart Guard: Runs static analysis + doctests + CrossHair + Hypothesis by default.
     Use --static for quick static-only checks (~0.5s vs ~5s full).
+    Use --suggest to get functional pattern suggestions (NewType, Validation, etc.).
+    Use --contracts-only (-c) to check contract coverage without running tests (DX-63).
     """
     from invar.shell.guard_helpers import (
         collect_files_to_check,
@@ -149,6 +168,16 @@ def guard(
     )
     from invar.shell.testing import VerificationLevel
 
+    # DX-65: Handle single file mode
+    single_file_mode = path.is_file()
+    single_file: Path | None = None
+    if single_file_mode:
+        if path.suffix != ".py":
+            console.print(f"[red]Error:[/red] {path} is not a Python file")
+            raise typer.Exit(1)
+        single_file = path.resolve()
+        path = find_project_root(path)
+
     # Load and configure
     config_result = load_config(path)
     if isinstance(config_result, Failure):
@@ -161,10 +190,41 @@ def guard(
     if pedantic:
         config.severity_overrides = {}
 
-    # Handle --changed mode
+    # DX-63: Contract coverage check only mode
+    if contracts_only:
+        import json
+
+        from invar.shell.contract_coverage import (
+            calculate_contract_coverage,
+            format_contract_coverage_agent,
+            format_contract_coverage_report,
+        )
+
+        # DX-65: Use single file path if in single file mode
+        coverage_path = single_file if single_file else path
+        coverage_result = calculate_contract_coverage(coverage_path, changed_only=changed)
+        if isinstance(coverage_result, Failure):
+            console.print(f"[red]Error:[/red] {coverage_result.failure()}")
+            raise typer.Exit(1)
+
+        report_data = coverage_result.unwrap()
+        use_agent_output = _determine_output_mode(human, agent, json_output)
+
+        if use_agent_output:
+            console.print(json.dumps(format_contract_coverage_agent(report_data)))
+        else:
+            console.print(format_contract_coverage_report(report_data))
+
+        raise typer.Exit(0 if report_data.ready_for_build else 1)
+
+    # Handle --changed mode or single file mode (DX-65)
     only_files: set[Path] | None = None
     checked_files: list[Path] = []
-    if changed:
+    if single_file:
+        # DX-65: Single file mode - only check the specified file
+        only_files = {single_file}
+        checked_files = [single_file]
+    elif changed:
         changed_result = handle_changed_mode(path)
         if isinstance(changed_result, Failure):
             if changed_result.failure() == "NO_CHANGES":
@@ -181,6 +241,25 @@ def guard(
         raise typer.Exit(1)
     report = scan_result.unwrap()
 
+    # DX-61: Run pattern detection if --suggest flag is set
+    pattern_suggestions: list = []
+    if suggest:
+        from invar.shell.pattern_integration import (
+            filter_suggestions,
+            run_pattern_detection,
+            suggestions_to_violations,
+        )
+        # Run pattern detection on checked files
+        files_to_check = list(only_files) if only_files else None
+        pattern_result = run_pattern_detection(path, files_to_check)
+        if isinstance(pattern_result, Success):
+            raw_suggestions = pattern_result.unwrap()
+            # DX-61: Apply config-based filtering
+            pattern_suggestions = filter_suggestions(raw_suggestions, config)
+            # Add suggestions to report as SUGGEST-level violations
+            for violation in suggestions_to_violations(pattern_suggestions):
+                report.add_violation(violation)
+
     # DX-26: Simplified output mode (TTY auto-detect + --human override)
     use_agent_output = _determine_output_mode(human, agent, json_output)
 
@@ -327,7 +406,7 @@ def _show_verification_level(verification_level) -> None:
 @app.command()
 def version() -> None:
     """Show Invar version."""
-    console.print(f"invar {__version__}")
+    console.print(f"invar-tools {__version__}")
 
 
 @app.command("map")
@@ -464,5 +543,18 @@ app.add_typer(dev_app)
 app.command("sync-self", hidden=True)(sync_self)
 
 
+# MCP server command for Claude Code integration
+@app.command()
+def mcp() -> None:
+    """Start Invar MCP server for AI agent integration.
+
+    This runs the MCP server using stdio transport.
+    Used by Claude Code and other MCP-compatible AI agents.
+    """
+    from invar.mcp.server import run_server
+
+    run_server()
+
+
 if __name__ == "__main__":
     app()

invar/shell/config.py

@@ -267,6 +267,52 @@ def _find_config_source(project_root: Path) -> Result[tuple[Path | None, ConfigS
         return Failure(f"Failed to find config: {e}")
 
 
+# @shell_complexity: Project root discovery requires checking multiple markers
+def find_project_root(start_path: "Path") -> "Path":  # noqa: UP037
+    """
+    Find project root by walking up from start_path looking for config files.
+
+    Looks for (in order): pyproject.toml, invar.toml, .invar/, .git/
+
+    Args:
+        start_path: Starting path (file or directory)
+
+    Returns:
+        Project root directory (absolute path), or start_path's parent if no markers found
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.TemporaryDirectory() as tmpdir:
+        ...     root = Path(tmpdir).resolve()
+        ...     (root / "pyproject.toml").touch()
+        ...     subdir = root / "src" / "core"
+        ...     subdir.mkdir(parents=True)
+        ...     found = find_project_root(subdir / "file.py")
+        ...     found == root
+        True
+    """
+    from pathlib import Path
+
+    current = Path(start_path).resolve()  # Resolve to absolute path
+    if current.is_file():
+        current = current.parent
+
+    # Walk up looking for project markers
+    for parent in [current, *current.parents]:
+        if (parent / "pyproject.toml").exists():
+            return parent
+        if (parent / "invar.toml").exists():
+            return parent
+        if (parent / ".invar").is_dir():
+            return parent
+        if (parent / ".git").exists():
+            return parent
+
+    # Fallback to the starting directory
+    return current
+
+
 def _read_toml(path: Path) -> Result[dict[str, Any], str]:
     """Read and parse a TOML file."""
     try: