invar-tools 1.5.0__py3-none-any.whl → 1.7.0__py3-none-any.whl

invar/__init__.py

@@ -8,7 +8,13 @@ This package provides development tools (guard, map, sig).
 For runtime contracts only, use invar-runtime instead.
 """
 
-__version__ = "1.0.0"
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("invar-tools")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0.dev"  # Development mode fallback
+
 __protocol_version__ = "5.0"  # Protocol/spec version (separate from package version)
 
 # Re-export from invar-runtime for backwards compatibility

invar/core/entry_points.py

@@ -100,30 +100,30 @@ def count_escape_hatches(source: str) -> int:
     return len(extract_escape_hatches(source))
 
 
-@post(lambda result: all(len(t) == 2 for t in result))  # Returns (rule, reason) tuples
-def extract_escape_hatches(source: str) -> list[tuple[str, str]]:
+@post(lambda result: all(len(t) == 3 for t in result))  # Returns (rule, reason, line) tuples
+def extract_escape_hatches(source: str) -> list[tuple[str, str, int]]:
     """
-    Extract @invar:allow markers with their reasons (DX-33 Option E).
+    Extract @invar:allow markers with their reasons and line numbers (DX-33, DX-66).
 
     Uses tokenize to only match real comments, not strings/docstrings.
-    Returns list of (rule, reason) tuples for cross-file analysis.
+    Returns list of (rule, reason, line) tuples for cross-file analysis.
 
     Examples:
         >>> extract_escape_hatches("")
         []
         >>> extract_escape_hatches("# @invar:allow shell_result: API boundary")
-        [('shell_result', 'API boundary')]
+        [('shell_result', 'API boundary', 1)]
         >>> source = '''
         ... # @invar:allow rule1: same reason
         ... # @invar:allow rule2: different reason
         ... '''
         >>> extract_escape_hatches(source)
-        [('rule1', 'same reason'), ('rule2', 'different reason')]
+        [('rule1', 'same reason', 2), ('rule2', 'different reason', 3)]
         >>> # DX-33 Option C: Strings containing the pattern should NOT match
         >>> extract_escape_hatches('suggestion = "# @invar:allow rule: reason"')
         []
     """
-    results: list[tuple[str, str]] = []
+    results: list[tuple[str, str, int]] = []
     try:
         # Use iterator-based readline to avoid io.StringIO (forbidden in Core)
         lines = iter(source.splitlines(keepends=True))
@@ -132,10 +132,12 @@ def extract_escape_hatches(source: str) -> list[tuple[str, str]]:
             if tok.type == tokenize.COMMENT:
                 match = INVAR_ALLOW_PATTERN.search(tok.string)
                 if match:
-                    results.append((match.group(1), match.group(2)))
+                    # DX-66: tok.start[0] is the 1-based line number
+                    results.append((match.group(1), match.group(2), tok.start[0]))
     except Exception:
-        # Fall back to regex if tokenization fails (invalid syntax, non-printable chars, etc.)
-        return INVAR_ALLOW_PATTERN.findall(source)
+        # Fall back to regex if tokenization fails - can't get line numbers
+        # Return line 0 to indicate unknown position
+        return [(r, reason, 0) for r, reason in INVAR_ALLOW_PATTERN.findall(source)]
     return results
 
 

invar/core/formatter.py

@@ -256,6 +256,21 @@ def format_guard_agent(report: GuardReport, combined_status: str | None = None)
     if report.suggests > 0:
         result["static"]["suggests"] = report.suggests
         result["summary"]["suggests"] = report.suggests
+    # DX-66: Add escape hatch summary if any exist
+    if report.escape_hatches.count > 0:
+        result["escape_hatches"] = {
+            "count": report.escape_hatches.count,
+            "by_rule": report.escape_hatches.by_rule,
+            "details": [
+                {
+                    "file": d.file,
+                    "line": d.line,
+                    "rule": d.rule,
+                    "reason": d.reason,
+                }
+                for d in report.escape_hatches.details
+            ],
+        }
     return result
 
 

invar/core/models.py

@@ -83,6 +83,89 @@ class Violation(BaseModel):
     suggestion: str | None = None
 
 
+class EscapeHatchDetail(BaseModel):
+    """
+    Detail of a single escape hatch (@invar:allow) marker (DX-66).
+
+    Examples:
+        >>> d = EscapeHatchDetail(file="test.py", line=10, rule="shell_result", reason="API")
+        >>> d.line
+        10
+        >>> # line=0 is valid (fallback when line number unknown)
+        >>> d0 = EscapeHatchDetail(file="test.py", line=0, rule="test", reason="fallback")
+        >>> d0.line
+        0
+    """
+
+    file: str
+    line: int = Field(ge=0)  # 0 = fallback when line number unknown
+    rule: str
+    reason: str
+
+
+class EscapeHatchSummary(BaseModel):
+    """
+    Summary of escape hatches in the codebase (DX-66).
+
+    Provides visibility into @invar:allow usage for tracking technical debt.
+
+    Examples:
+        >>> summary = EscapeHatchSummary()
+        >>> summary.count
+        0
+        >>> summary.by_rule
+        {}
+        >>> detail = EscapeHatchDetail(file="test.py", line=10, rule="shell_result", reason="API boundary")
+        >>> summary.add(detail)
+        >>> summary.count
+        1
+        >>> summary.by_rule
+        {'shell_result': 1}
+    """
+
+    details: list[EscapeHatchDetail] = Field(default_factory=list)
+
+    @property
+    @post(lambda result: result >= 0)
+    def count(self) -> int:
+        """
+        Total number of escape hatches.
+
+        Examples:
+            >>> EscapeHatchSummary().count
+            0
+        """
+        return len(self.details)
+
+    @property
+    @post(lambda result: all(v >= 0 for v in result.values()))
+    def by_rule(self) -> dict[str, int]:
+        """
+        Count of escape hatches grouped by rule.
+
+        Examples:
+            >>> EscapeHatchSummary().by_rule
+            {}
+        """
+        counts: dict[str, int] = {}
+        for detail in self.details:
+            counts[detail.rule] = counts.get(detail.rule, 0) + 1
+        return counts
+
+    @pre(lambda self, detail: bool(detail.rule) and bool(detail.file))
+    def add(self, detail: EscapeHatchDetail) -> None:
+        """
+        Add an escape hatch detail to the summary.
+
+        Examples:
+            >>> s = EscapeHatchSummary()
+            >>> s.add(EscapeHatchDetail(file="t.py", line=1, rule="r", reason="x"))
+            >>> s.count
+            1
+        """
+        self.details.append(detail)
+
+
 class GuardReport(BaseModel):
     """Complete Guard report for a project."""
 
@@ -95,6 +178,8 @@ class GuardReport(BaseModel):
     # P24: Contract coverage statistics (Core files only)
     core_functions_total: int = 0
     core_functions_with_contracts: int = 0
+    # DX-66: Escape hatch visibility
+    escape_hatches: EscapeHatchSummary = Field(default_factory=EscapeHatchSummary)
 
     @pre(lambda self, violation: violation.rule and violation.severity)  # Valid violation
     def add_violation(self, violation: Violation) -> None:

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(
@@ -157,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):
@@ -179,7 +200,9 @@ def guard(
             format_contract_coverage_report,
         )
 
-        coverage_result = calculate_contract_coverage(path, changed_only=changed)
+        # 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)
@@ -194,10 +217,14 @@ def guard(
 
         raise typer.Exit(0 if report_data.ready_for_build else 1)
 
-    # Handle --changed mode
+    # 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":
@@ -379,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")
@@ -494,9 +521,11 @@ from invar.shell.commands.init import init
 from invar.shell.commands.mutate import mutate  # DX-28
 from invar.shell.commands.sync_self import sync_self  # DX-49
 from invar.shell.commands.test import test, verify
+from invar.shell.commands.uninstall import uninstall  # DX-69
 from invar.shell.commands.update import update
 
 app.command()(init)
+app.command()(uninstall)  # DX-69: Remove Invar from project
 app.command()(update)
 app.command()(test)
 app.command()(verify)

invar/shell/commands/init.py

@@ -38,8 +38,6 @@ from invar.shell.mcp_config import (
 from invar.shell.template_engine import generate_from_manifest
 from invar.shell.templates import (
     add_config,
-    add_invar_reference,
-    create_agent_config,
     create_directories,
     detect_agent_configs,
     install_hooks,
@@ -65,18 +63,17 @@ def run_claude_init(path: Path) -> bool:
 
     console.print("\n[bold]Running claude /init...[/bold]")
     try:
+        # Don't capture output - claude /init is interactive and needs user input
         result = subprocess.run(
             ["claude", "/init"],
             cwd=path,
-            capture_output=True,
-            text=True,
             timeout=120,
         )
         if result.returncode == 0:
             console.print("[green]claude /init completed successfully[/green]")
             return True
         else:
-            console.print(f"[yellow]Warning:[/yellow] claude /init failed: {result.stderr}")
+            console.print("[yellow]Warning:[/yellow] claude /init failed")
             return False
     except subprocess.TimeoutExpired:
         console.print("[yellow]Warning:[/yellow] claude /init timed out")
@@ -86,57 +83,6 @@ def run_claude_init(path: Path) -> bool:
         return False
 
 
-def append_invar_reference_to_claude_md(path: Path) -> bool:
-    """
-    Append Invar reference to existing CLAUDE.md.
-
-    Preserves content generated by 'claude /init'.
-    Returns True if modified, False otherwise.
-    """
-    claude_md = path / "CLAUDE.md"
-    if not claude_md.exists():
-        return False
-
-    content = claude_md.read_text()
-    if "INVAR.md" in content:
-        console.print("[dim]CLAUDE.md already references INVAR.md[/dim]")
-        return False
-
-    # Append reference at the end
-    invar_reference = """
-
----
-
-## Invar Protocol
-
-> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion.
-
-### Check-In
-
-Your first message MUST display:
-
-```
-✓ Check-In: [project] | [branch] | [clean/dirty]
-```
-
-Read `.invar/context.md` first. Do NOT run guard/map at Check-In.
-
-### Final
-
-Your last message MUST display:
-
-```
-✓ Final: guard PASS | 0 errors, 2 warnings
-```
-
-Execute `invar guard` and show this one-line summary.
-"""
-
-    claude_md.write_text(content + invar_reference)
-    console.print("[green]Updated[/green] CLAUDE.md (added Invar reference)")
-    return True
-
-
 # @shell_complexity: MCP config with method selection and validation
 def configure_mcp_with_method(
     path: Path, mcp_method: str | None
@@ -312,11 +258,9 @@ def init(
             return
 
     # DX-21B: Run claude /init if requested (before sync)
+    # DX-69: sync_templates() will merge claude's CLAUDE.md with invar template
     if claude:
-        claude_success = run_claude_init(path)
-        if claude_success:
-            # Append Invar reference to generated CLAUDE.md
-            append_invar_reference_to_claude_md(path)
+        run_claude_init(path)
 
     config_result = add_config(path, console)
     if isinstance(config_result, Failure):
@@ -371,28 +315,13 @@ def init(
         if isinstance(result, Success) and result.unwrap():
             console.print("[green]Created[/green] .invar/proposals/TEMPLATE.md")
 
-    # Agent detection and configuration (DX-11)
+    # Agent detection (DX-69: simplified, only Claude Code supported)
     console.print("\n[bold]Checking for agent configurations...[/bold]")
     agent_result = detect_agent_configs(path)
-    if isinstance(agent_result, Failure):
-        console.print(f"[yellow]Warning:[/yellow] {agent_result.failure()}")
-        agent_status: dict[str, str] = {}
-    else:
+    if isinstance(agent_result, Success):
         agent_status = agent_result.unwrap()
-
-    # Handle agent configs (DX-11, DX-17)
-    for agent, status in agent_status.items():
-        if status == "configured":
-            console.print(f"  [green]✓[/green] {agent}: already configured")
-        elif status == "found":
-            # Existing file without Invar reference - ask before modifying
-            if yes or typer.confirm(f"  Add Invar reference to {agent} config?", default=True):
-                add_invar_reference(path, agent, console)
-            else:
-                console.print(f"  [yellow]○[/yellow] {agent}: skipped")
-        elif status == "not_found":
-            # Create full template with workflow enforcement (DX-17)
-            create_agent_config(path, agent, console)
+        if agent_status.get("claude") == "configured":
+            console.print("  [green]✓[/green] claude: already configured")
 
     # Configure MCP server (DX-16, DX-21B)
     configure_mcp_with_method(path, mcp_method)