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

invar/shell/config.py

@@ -8,11 +8,15 @@ Configuration sources (priority order):
 2. invar.toml [guard]
 3. .invar/config.toml [guard]
 4. Built-in defaults
+
+DX-22: Added content-based auto-detection for Core/Shell classification.
 """
 
 from __future__ import annotations
 
+import ast
 import tomllib
+from enum import Enum
 from typing import TYPE_CHECKING, Any, Literal
 
 from returns.result import Failure, Result, Success
@@ -25,12 +29,210 @@ from invar.core.utils import (
     parse_guard_config,
 )
 
+
+class ModuleType(Enum):
+    """DX-22: Module type for auto-detection."""
+
+    CORE = "core"
+    SHELL = "shell"
+    UNKNOWN = "unknown"
+
+
+# I/O libraries that indicate Shell module (for AST import checking)
+_IO_LIBRARIES = frozenset([
+    "os", "sys", "subprocess", "pathlib", "shutil", "io", "socket",
+    "requests", "aiohttp", "httpx", "urllib", "sqlite3", "psycopg2",
+    "pymongo", "sqlalchemy", "typer", "click",
+])
+
+# Contract decorator names
+_CONTRACT_DECORATORS = frozenset(["pre", "post", "invariant"])
+
+# Result monad types
+_RESULT_TYPES = frozenset(["Result", "Success", "Failure"])
+
+
+# @shell_orchestration: AST analysis
+# @shell_complexity: AST branches
+def _has_contract_decorators(tree: ast.Module) -> bool:
+    """
+    Check if AST contains @pre/@post contract decorators.
+
+    Uses AST to only detect real decorators, not strings in docstrings.
+
+    Examples:
+        >>> import ast
+        >>> tree = ast.parse("@pre(lambda x: x > 0)\\ndef foo(x): pass")
+        >>> _has_contract_decorators(tree)
+        True
+        >>> tree = ast.parse("def foo():\\n    '''>>> @pre(x)'''\\n    pass")
+        >>> _has_contract_decorators(tree)
+        False
+    """
+    for node in ast.walk(tree):
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            for decorator in node.decorator_list:
+                # @pre(...) or @post(...)
+                if isinstance(decorator, ast.Call):
+                    func = decorator.func
+                    if isinstance(func, ast.Name) and func.id in _CONTRACT_DECORATORS:
+                        return True
+                    if isinstance(func, ast.Attribute) and func.attr in _CONTRACT_DECORATORS:
+                        return True
+                # @pre (without call - rare but possible)
+                elif isinstance(decorator, ast.Name) and decorator.id in _CONTRACT_DECORATORS:
+                    return True
+    return False
+
+
+# @shell_orchestration: AST analysis
+# @shell_complexity: AST branches
+def _has_io_imports(tree: ast.Module) -> bool:
+    """
+    Check if AST contains imports of I/O libraries.
+
+    Examples:
+        >>> import ast
+        >>> tree = ast.parse("import os")
+        >>> _has_io_imports(tree)
+        True
+        >>> tree = ast.parse("from pathlib import Path")
+        >>> _has_io_imports(tree)
+        True
+        >>> tree = ast.parse("import json")
+        >>> _has_io_imports(tree)
+        False
+        >>> tree = ast.parse("def foo():\\n    '''import os'''\\n    pass")
+        >>> _has_io_imports(tree)
+        False
+    """
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                lib = alias.name.split(".")[0]
+                if lib in _IO_LIBRARIES:
+                    return True
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            lib = node.module.split(".")[0]
+            if lib in _IO_LIBRARIES:
+                return True
+    return False
+
+
+# @shell_orchestration: AST analysis
+# @shell_complexity: AST branches
+def _has_result_types(tree: ast.Module) -> bool:
+    """
+    Check if AST contains Result/Success/Failure usage.
+
+    Checks:
+    - Return type annotations: -> Result[T, E]
+    - Imports: from returns.result import Success
+    - Function calls: Success(...), Failure(...)
+
+    Examples:
+        >>> import ast
+        >>> tree = ast.parse("from returns.result import Success")
+        >>> _has_result_types(tree)
+        True
+        >>> tree = ast.parse("def foo() -> Result[int, str]: pass")
+        >>> _has_result_types(tree)
+        True
+        >>> tree = ast.parse("return Success(42)")
+        >>> _has_result_types(tree)
+        True
+        >>> tree = ast.parse("def foo():\\n    '''Success'''\\n    pass")
+        >>> _has_result_types(tree)
+        False
+    """
+    for node in ast.walk(tree):
+        # Check imports: from returns.result import Success
+        if isinstance(node, ast.ImportFrom):
+            if node.module and "returns" in node.module:
+                for alias in node.names:
+                    if alias.name in _RESULT_TYPES:
+                        return True
+        # Check function calls: Success(...), Failure(...)
+        elif isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name) and node.func.id in _RESULT_TYPES:
+                return True
+        # Check type annotations: -> Result[T, E]
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            if node.returns:
+                ann = node.returns
+                if isinstance(ann, ast.Subscript):
+                    if isinstance(ann.value, ast.Name) and ann.value.id == "Result":
+                        return True
+                elif isinstance(ann, ast.Name) and ann.id in _RESULT_TYPES:
+                    return True
+    return False
+
+
+# @shell_complexity: Classification decision tree requires multiple conditions
+def auto_detect_module_type(source: str, file_path: str = "") -> ModuleType:
+    """
+    Automatically detect module type from source content using AST.
+
+    DX-22: Content-based classification when path-based is inconclusive.
+    Uses AST parsing to avoid false positives from docstrings/comments.
+
+    Priority:
+    1. Path convention (**/core/** or **/shell/**)
+    2. Content features via AST (contracts, Result types, I/O imports)
+
+    Args:
+        source: Python source code as string
+        file_path: Optional file path for path-based hints
+
+    Returns:
+        ModuleType indicating Core, Shell, or Unknown
+
+    Examples:
+        >>> auto_detect_module_type("@pre(lambda x: x > 0)\\ndef foo(x): pass")
+        <ModuleType.CORE: 'core'>
+        >>> auto_detect_module_type("from returns.result import Success\\ndef load(): return Success('ok')")
+        <ModuleType.SHELL: 'shell'>
+        >>> auto_detect_module_type("def helper(): pass")
+        <ModuleType.UNKNOWN: 'unknown'>
+        >>> auto_detect_module_type("def foo():\\n    '''>>> @pre(x)'''\\n    pass")
+        <ModuleType.UNKNOWN: 'unknown'>
+    """
+    # Priority 1: Path convention
+    if file_path:
+        path_lower = file_path.lower()
+        if "/core/" in path_lower or path_lower.endswith("/core"):
+            return ModuleType.CORE
+        if "/shell/" in path_lower or path_lower.endswith("/shell"):
+            return ModuleType.SHELL
+
+    # Priority 2: Content features via AST
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return ModuleType.UNKNOWN
+
+    has_contracts = _has_contract_decorators(tree)
+    has_io = _has_io_imports(tree)
+    has_result = _has_result_types(tree)
+
+    # Core: has contracts AND no I/O
+    if has_contracts and not has_io:
+        return ModuleType.CORE
+
+    # Shell: has I/O or Result types
+    if has_io or has_result:
+        return ModuleType.SHELL
+
+    # Unknown: neither clear pattern
+    return ModuleType.UNKNOWN
+
 if TYPE_CHECKING:
     from pathlib import Path
 
 ConfigSource = Literal["pyproject", "invar", "invar_dir", "default"]
 
 
+# @shell_complexity: Config cascade checks multiple sources with fallback
 def _find_config_source(project_root: Path) -> Result[tuple[Path | None, ConfigSource], str]:
     """
     Find the first available config file.
@@ -76,6 +278,7 @@ def _read_toml(path: Path) -> Result[dict[str, Any], str]:
         return Failure(f"Failed to read {path.name}: {e}")
 
 
+# @shell_complexity: Config loading with multiple sources and parse error handling
 def load_config(project_root: Path) -> Result[RuleConfig, str]:
     """
     Load Invar configuration from available sources.
@@ -139,6 +342,9 @@ _DEFAULT_EXCLUDE_PATHS = [
     "dist",
     "build",
     ".tox",
+    # Templates and examples are documentation, not enforced code
+    "templates",
+    ".invar/examples",
 ]
 
 
@@ -206,11 +412,20 @@ def get_exclude_paths(project_root: Path) -> Result[list[str], str]:
     return Success(guard_config.get("exclude_paths", _DEFAULT_EXCLUDE_PATHS.copy()))
 
 
-def classify_file(file_path: str, project_root: Path) -> Result[tuple[bool, bool], str]:
+# @shell_complexity: Classification decision tree requires multiple config lookups and priority checks
+# @invar:allow entry_point_too_thick: False positive - .get() matches router.get pattern
+def classify_file(
+    file_path: str, project_root: Path, source: str = ""
+) -> Result[tuple[bool, bool], str]:
     """
     Classify a file as Core, Shell, or neither.
 
-    Priority: patterns > paths > uncategorized.
+    DX-22 Part 5: Priority order is patterns > paths > content > uncategorized.
+
+    Args:
+        file_path: Relative path to the file
+        project_root: Project root directory
+        source: Optional source content for content-based detection
 
     Examples:
         >>> import tempfile
@@ -220,18 +435,32 @@ def classify_file(file_path: str, project_root: Path) -> Result[tuple[bool, bool
         ...     result = classify_file("src/core/logic.py", root)
         ...     result.unwrap()[0]
         True
+        >>> classify_file("lib/utils.py", Path("."), "@pre(lambda x: x > 0)\\ndef foo(x): pass").unwrap()
+        (True, False)
+        >>> classify_file("lib/io.py", Path("."), "def read() -> Result[str, str]: return Success('ok')").unwrap()
+        (False, True)
     """
     pattern_result = get_pattern_classification(project_root)
-    core_patterns, shell_patterns = (
-        pattern_result.unwrap() if isinstance(pattern_result, Success) else ([], [])
-    )
+    if isinstance(pattern_result, Success):
+        core_patterns, shell_patterns = pattern_result.unwrap()
+    else:
+        # Log warning about config error, use defaults
+        import logging
+        logging.getLogger(__name__).debug(
+            "Pattern classification failed: %s, using defaults", pattern_result.failure()
+        )
+        core_patterns, shell_patterns = ([], [])
 
     path_result = get_path_classification(project_root)
-    core_paths, shell_paths = (
-        path_result.unwrap()
-        if isinstance(path_result, Success)
-        else (_DEFAULT_CORE_PATHS, _DEFAULT_SHELL_PATHS)
-    )
+    if isinstance(path_result, Success):
+        core_paths, shell_paths = path_result.unwrap()
+    else:
+        # Log warning about config error, use defaults
+        import logging
+        logging.getLogger(__name__).debug(
+            "Path classification failed: %s, using defaults", path_result.failure()
+        )
+        core_paths, shell_paths = (_DEFAULT_CORE_PATHS, _DEFAULT_SHELL_PATHS)
 
     # Priority 1: Pattern-based classification
     if core_patterns and matches_pattern(file_path, core_patterns):
@@ -245,4 +474,12 @@ def classify_file(file_path: str, project_root: Path) -> Result[tuple[bool, bool
     if matches_path_prefix(file_path, shell_paths):
         return Success((False, True))
 
+    # Priority 3: Content-based auto-detection (DX-22 Part 5)
+    if source:
+        module_type = auto_detect_module_type(source, file_path)
+        if module_type == ModuleType.CORE:
+            return Success((True, False))
+        if module_type == ModuleType.SHELL:
+            return Success((False, True))
+
     return Success((False, False))

invar/shell/coverage.py

@@ -0,0 +1,351 @@
+"""
+Coverage integration for Guard verification phases.
+
+DX-37: Collect branch coverage from doctest + hypothesis phases.
+Coverage.py is used for accurate tracking via sys.settrace().
+
+Note: CrossHair uses symbolic execution (Z3 solver) in subprocess,
+so coverage.py cannot track it. This is a fundamental limitation.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from deal import post, pre
+from returns.result import Failure, Result, Success
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from coverage import Coverage
+
+
+@dataclass
+class UncoveredBranch:
+    """A branch that was never taken during testing.
+
+    Examples:
+        >>> branch = UncoveredBranch(line=127, branch_type="else", context="if x > 0:")
+        >>> branch.line
+        127
+        >>> branch.branch_type
+        'else'
+    """
+
+    line: int
+    branch_type: str  # "if", "else", "elif", "except", "for", "while"
+    context: str  # Source line for context
+
+
+@dataclass
+class FileCoverage:
+    """Coverage data for a single file.
+
+    Examples:
+        >>> fc = FileCoverage(path="src/foo.py", branch_coverage=94.5)
+        >>> fc.branch_coverage
+        94.5
+        >>> len(fc.uncovered_branches)
+        0
+    """
+
+    path: str
+    branch_coverage: float  # 0.0 to 100.0
+    uncovered_branches: list[UncoveredBranch] = field(default_factory=list)
+
+
+@dataclass
+class CoverageReport:
+    """Coverage data from doctest + hypothesis phases.
+
+    Examples:
+        >>> report = CoverageReport(overall_branch_coverage=91.2)
+        >>> report.phases_tracked
+        []
+        >>> report.phases_excluded
+        ['crosshair']
+    """
+
+    overall_branch_coverage: float  # 0.0 to 100.0
+    files: dict[str, FileCoverage] = field(default_factory=dict)
+    phases_tracked: list[str] = field(default_factory=list)
+    phases_excluded: list[str] = field(default_factory=lambda: ["crosshair"])
+
+
+# @shell_orchestration: Import check utility for coverage.py dependency
+def _is_coverage_available() -> bool:
+    """Check if coverage.py is installed.
+
+    Examples:
+        >>> result = _is_coverage_available()
+        >>> isinstance(result, bool)
+        True
+    """
+    try:
+        import coverage  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+@pre(lambda source_dirs: len(source_dirs) >= 0)
+@contextmanager
+def collect_coverage(source_dirs: list[Path]) -> Iterator[Coverage]:
+    """Context manager for coverage collection.
+
+    Args:
+        source_dirs: Directories to track coverage for
+
+    Yields:
+        Coverage object for data extraction
+
+    Examples:
+        >>> from pathlib import Path
+        >>> # When coverage is available, yields a Coverage object
+        >>> # with collect_coverage([Path("src")]) as cov:
+        >>> #     pass  # Execute code to track
+    """
+    import coverage
+
+    cov = coverage.Coverage(
+        branch=True,
+        source=[str(d) for d in source_dirs] if source_dirs else None,
+        omit=["**/test_*", "**/*_test.py", "**/conftest.py"],
+    )
+
+    cov.start()
+    try:
+        yield cov
+    finally:
+        cov.stop()
+        cov.save()
+
+
+# @shell_complexity: Coverage API interaction with multiple analysis branches
+@pre(lambda cov, files: files is not None)
+@post(lambda result: isinstance(result, CoverageReport))
+def extract_coverage_report(cov: Coverage, files: list[Path], phase: str) -> CoverageReport:
+    """Extract coverage report from Coverage object.
+
+    Args:
+        cov: Coverage object after data collection
+        files: Files to extract coverage for
+        phase: Name of the phase ("doctest" or "hypothesis")
+
+    Returns:
+        CoverageReport with branch coverage data
+
+    Examples:
+        >>> # After running with collect_coverage:
+        >>> # report = extract_coverage_report(cov, [Path("src/foo.py")], "doctest")
+        >>> # report.phases_tracked == ["doctest"]
+    """
+    file_coverages: dict[str, FileCoverage] = {}
+    total_branches = 0
+    covered_branches = 0
+
+    # Get analysis data
+    for file_path in files:
+        str_path = str(file_path)
+        try:
+            # Trigger coverage analysis for this file
+            _ = cov.analysis2(str_path)
+
+            # Get branch data
+            branch_stats = cov._analyze(str_path)
+            if hasattr(branch_stats, "numbers"):
+                nums = branch_stats.numbers
+                file_total = nums.n_branches
+                file_covered = nums.n_branches - nums.n_missing_branches
+
+                if file_total > 0:
+                    total_branches += file_total
+                    covered_branches += file_covered
+                    branch_pct = (file_covered / file_total) * 100
+
+                    # Extract uncovered branches
+                    uncovered = []
+                    if hasattr(branch_stats, "missing_branch_arcs"):
+                        for arc in branch_stats.missing_branch_arcs():
+                            from_line, to_line = arc
+                            uncovered.append(
+                                UncoveredBranch(
+                                    line=from_line,
+                                    branch_type="branch",
+                                    context=f"line {from_line} -> {to_line}",
+                                )
+                            )
+
+                    file_coverages[str_path] = FileCoverage(
+                        path=str_path,
+                        branch_coverage=round(branch_pct, 1),
+                        uncovered_branches=uncovered[:5],  # Limit to 5 per file
+                    )
+        except Exception:
+            # File not covered or analysis failed
+            continue
+
+    overall = (covered_branches / total_branches * 100) if total_branches > 0 else 0.0
+
+    return CoverageReport(
+        overall_branch_coverage=round(overall, 1),
+        files=file_coverages,
+        phases_tracked=[phase],
+    )
+
+
+# @shell_orchestration: Report merging coordinates data from multiple phases
+# @shell_complexity: Report merging with multiple iteration paths
+@pre(lambda reports: all(isinstance(r, CoverageReport) for r in reports if r is not None))
+@post(lambda result: isinstance(result, CoverageReport))
+def merge_coverage_reports(reports: list[CoverageReport | None]) -> CoverageReport:
+    """Merge coverage from multiple phases.
+
+    Union of covered lines/branches across all phases.
+    Only branches uncovered in ALL phases are reported as uncovered.
+
+    Args:
+        reports: List of CoverageReport objects (None entries are skipped)
+
+    Returns:
+        Merged CoverageReport
+
+    Examples:
+        >>> r1 = CoverageReport(overall_branch_coverage=80.0, phases_tracked=["doctest"])
+        >>> r2 = CoverageReport(overall_branch_coverage=70.0, phases_tracked=["hypothesis"])
+        >>> merged = merge_coverage_reports([r1, r2])
+        >>> "doctest" in merged.phases_tracked
+        True
+        >>> "hypothesis" in merged.phases_tracked
+        True
+    """
+    valid_reports = [r for r in reports if r is not None]
+
+    if not valid_reports:
+        return CoverageReport(overall_branch_coverage=0.0)
+
+    if len(valid_reports) == 1:
+        return valid_reports[0]
+
+    # Merge phases tracked
+    all_phases: list[str] = []
+    for r in valid_reports:
+        all_phases.extend(r.phases_tracked)
+
+    # Merge file coverages - take the max coverage for each file
+    merged_files: dict[str, FileCoverage] = {}
+    for r in valid_reports:
+        for path, fc in r.files.items():
+            if path not in merged_files or fc.branch_coverage > merged_files[path].branch_coverage:
+                merged_files[path] = fc
+
+    # Calculate overall as average of file coverages (weighted would be better but needs LOC)
+    if merged_files:
+        overall = sum(fc.branch_coverage for fc in merged_files.values()) / len(merged_files)
+    else:
+        overall = 0.0
+
+    return CoverageReport(
+        overall_branch_coverage=round(overall, 1),
+        files=merged_files,
+        phases_tracked=all_phases,
+    )
+
+
+# @shell_orchestration: Format report for Rich console output
+@pre(lambda report: isinstance(report, CoverageReport))
+@post(lambda result: isinstance(result, str))
+def format_coverage_output(report: CoverageReport) -> str:
+    """Format coverage report for CLI output.
+
+    Args:
+        report: CoverageReport to format
+
+    Returns:
+        Formatted string for terminal output
+
+    Examples:
+        >>> report = CoverageReport(overall_branch_coverage=91.2, phases_tracked=["doctest"])
+        >>> output = format_coverage_output(report)
+        >>> "91.2%" in output
+        True
+        >>> "doctest" in output
+        True
+    """
+    lines = [
+        f"Coverage Analysis ({' + '.join(report.phases_tracked)}):",
+    ]
+
+    # Sort files by coverage (lowest first to highlight issues)
+    sorted_files = sorted(report.files.items(), key=lambda x: x[1].branch_coverage)
+
+    for path, fc in sorted_files[:10]:  # Limit to 10 files
+        uncovered_count = len(fc.uncovered_branches)
+        lines.append(f"  {path}: {fc.branch_coverage}% branch ({uncovered_count} uncovered)")
+        for branch in fc.uncovered_branches[:3]:  # Limit to 3 branches per file
+            lines.append(f"    Line {branch.line}: {branch.context}")
+
+    lines.append("")
+    lines.append(f"Overall: {report.overall_branch_coverage}% branch coverage ({' + '.join(report.phases_tracked)})")
+    lines.append("")
+    lines.append("Note: CrossHair uses symbolic execution; coverage not applicable.")
+
+    return "\n".join(lines)
+
+
+# @shell_orchestration: Format report for JSON agent output
+@post(lambda result: isinstance(result, dict))
+def format_coverage_json(report: CoverageReport) -> dict:
+    """Format coverage report for JSON output.
+
+    Args:
+        report: CoverageReport to format
+
+    Returns:
+        Dictionary for JSON serialization
+
+    Examples:
+        >>> report = CoverageReport(overall_branch_coverage=91.2, phases_tracked=["doctest"])
+        >>> data = format_coverage_json(report)
+        >>> data["enabled"]
+        True
+        >>> data["overall_branch_coverage"]
+        91.2
+    """
+    return {
+        "enabled": True,
+        "phases_tracked": report.phases_tracked,
+        "phases_excluded": report.phases_excluded,
+        "overall_branch_coverage": report.overall_branch_coverage,
+        "files": [
+            {
+                "path": fc.path,
+                "branch_coverage": fc.branch_coverage,
+                "uncovered_branches": [
+                    {"line": b.line, "type": b.branch_type, "context": b.context}
+                    for b in fc.uncovered_branches
+                ],
+            }
+            for fc in report.files.values()
+        ],
+    }
+
+
+def check_coverage_available() -> Result[bool, str]:
+    """Check if coverage.py is installed and return helpful error if not.
+
+    Returns:
+        Success(True) if available, Failure with install instructions if not
+
+    Examples:
+        >>> result = check_coverage_available()
+        >>> # Either Success(True) or Failure("Install coverage...")
+    """
+    if _is_coverage_available():
+        return Success(True)
+    return Failure("Install coverage for --coverage support: pip install coverage[toml]>=7.0")

invar/shell/fs.py

@@ -19,6 +19,7 @@ if TYPE_CHECKING:
     from pathlib import Path
 
 
+# @shell_complexity: Recursive file discovery with gitignore and exclusions
 def discover_python_files(
     project_root: Path,
     exclude_patterns: list[str] | None = None,
@@ -52,6 +53,7 @@ def discover_python_files(
             yield py_file
 
 
+# @shell_complexity: File reading with AST parsing and error handling
 def read_and_parse_file(file_path: Path, project_root: Path) -> Result[FileInfo, str]:
     """
     Read a Python file and parse it into FileInfo.
@@ -79,8 +81,8 @@ def read_and_parse_file(file_path: Path, project_root: Path) -> Result[FileInfo,
     if file_info is None:
         return Failure(f"Syntax error in {file_path}")
 
-    # Classify as Core or Shell based on patterns and paths
-    classify_result = classify_file(relative_path, project_root)
+    # Classify as Core or Shell based on patterns, paths, and content (DX-22 Part 5)
+    classify_result = classify_file(relative_path, project_root, file_info.source)
     file_info.is_core, file_info.is_shell = (
         classify_result.unwrap() if isinstance(classify_result, Success) else (False, False)
     )
@@ -88,6 +90,7 @@ def read_and_parse_file(file_path: Path, project_root: Path) -> Result[FileInfo,
     return Success(file_info)
 
 
+# @shell_complexity: Project scanning with exclusions and error handling
 def scan_project(
     project_root: Path,
     only_files: set[Path] | None = None,