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

invar/mcp/server.py

@@ -15,7 +15,7 @@ from typing import Any
 from mcp.server import Server
 from mcp.types import TextContent, Tool
 
-# Strong instructions for agent behavior (DX-16 + DX-17)
+# Strong instructions for agent behavior (DX-16 + DX-17 + DX-26)
 INVAR_INSTRUCTIONS = """
 ## Invar Tool Usage (MANDATORY)
 
@@ -83,6 +83,8 @@ the MCP tools and may not follow the correct workflow.
 """
 
 
+# @shell_orchestration: MCP tool factory - creates Tool objects
+# @invar:allow shell_result: MCP framework API returns Tool
 def _get_guard_tool() -> Tool:
     """Define the invar_guard tool."""
     return Tool(
@@ -103,6 +105,8 @@ def _get_guard_tool() -> Tool:
     )
 
 
+# @shell_orchestration: MCP tool factory - creates Tool objects
+# @invar:allow shell_result: MCP framework API returns Tool
 def _get_sig_tool() -> Tool:
     """Define the invar_sig tool."""
     return Tool(
@@ -121,6 +125,8 @@ def _get_sig_tool() -> Tool:
     )
 
 
+# @shell_orchestration: MCP tool factory - creates Tool objects
+# @invar:allow shell_result: MCP framework API returns Tool
 def _get_map_tool() -> Tool:
     """Define the invar_map tool."""
     return Tool(
@@ -139,6 +145,8 @@ def _get_map_tool() -> Tool:
     )
 
 
+# @shell_orchestration: MCP server setup - registers handlers with framework
+# @invar:allow shell_result: MCP framework API returns Server
 def create_server() -> Server:
     """Create and configure the Invar MCP server."""
     server = Server(name="invar", version="0.1.0", instructions=INVAR_INSTRUCTIONS)
@@ -158,6 +166,8 @@ def create_server() -> Server:
     return server
 
 
+# @shell_orchestration: MCP handler - subprocess is called inside
+# @invar:allow shell_result: MCP framework API returns list[TextContent]
 async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
     """Run invar guard command."""
     cmd = [sys.executable, "-m", "invar.shell.cli", "guard"]
@@ -170,12 +180,14 @@ async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
     if args.get("strict", False):
         cmd.append("--strict")
 
-    # Always use JSON output for agent consumption
-    cmd.append("--json")
+    # DX-26: TTY auto-detection - MCP runs in non-TTY, so agent JSON output is automatic
+    # No explicit flag needed
 
     return await _execute_command(cmd)
 
 
+# @shell_orchestration: MCP handler - subprocess is called inside
+# @invar:allow shell_result: MCP framework API returns list[TextContent]
 async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
     """Run invar sig command."""
     target = args.get("target", "")
@@ -186,6 +198,8 @@ async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
     return await _execute_command(cmd)
 
 
+# @shell_orchestration: MCP handler - subprocess is called inside
+# @invar:allow shell_result: MCP framework API returns list[TextContent]
 async def _run_map(args: dict[str, Any]) -> list[TextContent]:
     """Run invar map command."""
     cmd = [sys.executable, "-m", "invar.shell.cli", "map"]
@@ -200,6 +214,8 @@ async def _run_map(args: dict[str, Any]) -> list[TextContent]:
     return await _execute_command(cmd)
 
 
+# @shell_complexity: Command execution with error handling branches
+# @invar:allow shell_result: MCP framework API returns list[TextContent]
 async def _execute_command(cmd: list[str]) -> list[TextContent]:
     """Execute a command and return the result."""
     try:
@@ -229,6 +245,7 @@ async def _execute_command(cmd: list[str]) -> list[TextContent]:
         return [TextContent(type="text", text=f"Error: {e}")]
 
 
+# @shell_orchestration: MCP server entry point - runs async server
 def run_server() -> None:
     """Run the Invar MCP server."""
     import asyncio

invar/shell/cli.py

@@ -27,7 +27,7 @@ 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.fs import scan_project
-from invar.shell.guard_output import output_agent, output_json, output_rich
+from invar.shell.guard_output import output_agent, output_rich
 
 app = typer.Typer(
     name="invar",
@@ -37,6 +37,8 @@ app = typer.Typer(
 console = Console()
 
 
+# @shell_orchestration: Statistics helper for CLI guard output
+# @shell_complexity: Iterates symbols checking kind and contracts (4 branches minimal)
 def _count_core_functions(file_info) -> tuple[int, int]:
     """Count functions and functions with contracts in a Core file (P24)."""
     from invar.core.models import SymbolKind
@@ -54,10 +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
 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.shell_architecture import check_complexity_debt
+
     report = GuardReport(files_checked=0)
     for file_result in scan_project(path, only_files):
         if isinstance(file_result, Failure):
@@ -70,43 +75,53 @@ def _scan_and_check(
         report.update_coverage(total, with_contracts)
         for violation in check_all_rules(file_info, config):
             report.add_violation(violation)
+
+    # DX-22: Check project-level complexity debt (Fix-or-Explain enforcement)
+    for debt_violation in check_complexity_debt(
+        report.violations, config.shell_complexity_debt_limit
+    ):
+        report.add_violation(debt_violation)
+
     return Success(report)
 
 
+# @invar:allow entry_point_too_thick: Main CLI entry point, orchestrates all verification phases
 @app.command()
 def guard(
     path: Path = typer.Argument(
         Path(), help="Project root directory", exists=True, file_okay=False, dir_okay=True
     ),
     strict: bool = typer.Option(False, "--strict", help="Treat warnings as errors"),
+    changed: bool = typer.Option(
+        False, "--changed", help="Only check git-modified files"
+    ),
+    static: bool = typer.Option(
+        False, "--static", help="Static analysis only, skip all runtime tests"
+    ),
+    human: bool = typer.Option(
+        False, "--human", help="Force human-readable output (for testing/debugging)"
+    ),
+    # DX-26: Deprecated flags kept for backward compatibility
     no_strict_pure: bool = typer.Option(
-        False, "--no-strict-pure", help="Disable purity checks (internal imports, impure calls)"
+        False, "--no-strict-pure", hidden=True, help="[Deprecated] Disable purity checks"
     ),
     pedantic: bool = typer.Option(
-        False, "--pedantic", help="Show all violations including off-by-default rules"
+        False, "--pedantic", hidden=True, help="[Deprecated] Show off-by-default rules"
     ),
     explain: bool = typer.Option(
-        False, "--explain", help="Show detailed explanations and limitations"
-    ),
-    changed: bool = typer.Option(
-        False, "--changed", help="Only check git-modified files"
+        False, "--explain", hidden=True, help="[Deprecated] Show detailed explanations"
     ),
     agent: bool = typer.Option(
-        False, "--agent", help="Output JSON with fix instructions for agents"
+        False, "--agent", help="Force JSON output (for inspecting agent format)"
     ),
     json_output: bool = typer.Option(
-        False, "--json", help="Output as JSON (simple format, no fix instructions)"
-    ),
-    static: bool = typer.Option(
-        False, "--static", help="Static analysis only, skip all runtime tests"
+        False, "--json", hidden=True, help="[Deprecated] Use TTY auto-detection instead"
     ),
 ) -> 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).
-
-    DX-19: Simplified to 2 levels (Zero decisions).
     """
     from invar.shell.guard_helpers import (
         collect_files_to_check,
@@ -150,17 +165,15 @@ def guard(
         raise typer.Exit(1)
     report = scan_result.unwrap()
 
-    # Determine output mode
-    use_agent_output, use_json_output = _determine_output_mode(
-        json_output, agent
-    )
+    # DX-26: Simplified output mode (TTY auto-detect + --human override)
+    use_agent_output = _determine_output_mode(human, agent, json_output)
 
     # DX-19: Simplified to 2 levels (STATIC or STANDARD)
     verification_level = VerificationLevel.STATIC if static else VerificationLevel.STANDARD
     level_name = "STATIC" if static else "STANDARD"
 
     # Show verification level (human mode)
-    if not use_agent_output and not use_json_output:
+    if not use_agent_output:
         _show_verification_level(verification_level)
 
     # Run verification phases
@@ -187,20 +200,19 @@ def guard(
             checked_files, doctest_passed, static_exit_code
         )
 
-    # Output results
+    # DX-26: Unified output (agent JSON or human Rich)
     if use_agent_output:
         output_agent(
-            report, doctest_passed, doctest_output, crosshair_output, level_name,
+            report, strict, doctest_passed, doctest_output, crosshair_output, level_name,
             property_output=property_output,
         )
-    elif use_json_output:
-        output_json(report)
     else:
-        output_rich(report, config.strict_pure, changed, pedantic, explain)
+        output_rich(report, config.strict_pure, changed, pedantic, explain, static)
         output_verification_status(
             verification_level, static_exit_code, doctest_passed,
             doctest_output, crosshair_output, explain,
             property_output=property_output,
+            strict=strict,
         )
 
     # Exit with combined status
@@ -209,13 +221,26 @@ def guard(
     raise typer.Exit(final_exit)
 
 
-def _determine_output_mode(json_output: bool, agent: bool) -> tuple[bool, bool]:
-    """Determine output mode based on flags and context."""
-    if json_output:
-        return False, True
-    if agent or _detect_agent_mode():
-        return True, False
-    return False, False
+# @shell_orchestration: Output mode decision helper for CLI
+def _determine_output_mode(human: bool, agent: bool = False, json_output: bool = False) -> bool:
+    """Determine if agent JSON output should be used (DX-26).
+
+    DX-26: TTY auto-detection with --human override.
+    - --human flag → human output (for testing/debugging)
+    - TTY (terminal) → human output
+    - Non-TTY (pipe/redirect) → agent JSON output
+    - Deprecated --agent/--json flags → still work for backward compat
+    """
+    # --human flag always forces human output
+    if human:
+        return False  # use_agent = False
+
+    # Deprecated flags (backward compat)
+    if json_output or agent:
+        return True  # use_agent = True
+
+    # TTY auto-detection
+    return _detect_agent_mode()  # Returns True if non-TTY
 
 
 def _show_verification_level(verification_level) -> None:
@@ -271,6 +296,7 @@ def sig_command(
         raise typer.Exit(1)
 
 
+# @invar:allow entry_point_too_thick: Rules display with filtering and dual output modes
 @app.command()
 def rules(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
@@ -345,6 +371,7 @@ def rules(
 
 # Import commands from separate modules to reduce file size
 from invar.shell.init_cmd import init
+from invar.shell.mutate_cmd import mutate  # DX-28
 from invar.shell.test_cmd import test, verify
 from invar.shell.update_cmd import update
 
@@ -352,6 +379,7 @@ app.command()(init)
 app.command()(update)
 app.command()(test)
 app.command()(verify)
+app.command()(mutate)  # DX-28: Mutation testing
 
 
 if __name__ == "__main__":

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,223 @@ 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 helpers for module classification
+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 helper for module classification
+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 helper for module classification
+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 +291,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 +355,9 @@ _DEFAULT_EXCLUDE_PATHS = [
     "dist",
     "build",
     ".tox",
+    # Templates and examples are documentation, not enforced code
+    "templates",
+    ".invar/examples",
 ]
 
 
@@ -206,11 +425,19 @@ 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]:
+# @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 +447,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 +486,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/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,

invar/shell/git.py

@@ -28,6 +28,7 @@ def _run_git(args: list[str], cwd: Path) -> Result[str, str]:
         return Failure(f"Git error: {e}")
 
 
+# @shell_orchestration: Helper for git output parsing, tightly coupled to Shell
 def _parse_py_files(output: str, project_root: Path) -> set[Path]:
     """Parse git output and return Python file paths."""
     files: set[Path] = set()
@@ -37,6 +38,7 @@ def _parse_py_files(output: str, project_root: Path) -> set[Path]:
     return files
 
 
+# @shell_complexity: Git operations require multiple subprocess calls with error handling
 def get_changed_files(project_root: Path) -> Result[set[Path], str]:
     """
     Get Python files modified according to git (staged, unstaged, untracked).