invar-tools 1.11.0__py3-none-any.whl → 1.14.0__py3-none-any.whl

invar/shell/commands/perception.py

@@ -7,6 +7,7 @@ Shell module: handles file I/O for map and sig commands.
 from __future__ import annotations
 
 import json
+from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
@@ -70,7 +71,11 @@ def run_sig(target: str, json_output: bool) -> Result[None, str]:
 
     file_path = Path(file_path_str)
     if not file_path.exists():
-        return Failure(f"File not found: {file_path}")
+        # DX-78 Phase B: Suggest alternative tools
+        return Failure(
+            f"File not found: {file_path}\n\n"
+            "💡 Try using Grep to search for the symbol across the codebase."
+        )
 
     # Read file content
     try:
@@ -122,7 +127,59 @@ def _run_sig_python(
 def _run_sig_typescript(
     content: str, file_path: Path, symbol_name: str | None, json_output: bool
 ) -> Result[None, str]:
-    """Run sig for TypeScript files (LX-06)."""
+    """Run sig for TypeScript files.
+
+    DX-78: Uses TS Compiler API when available, falls back to regex parser.
+    """
+    from invar.shell.ts_compiler import is_typescript_available, run_sig_typescript
+
+    # Try TS Compiler API first (DX-78)
+    if is_typescript_available():
+        sig_result = run_sig_typescript(file_path)
+        if isinstance(sig_result, Success):
+            symbols = sig_result.unwrap()
+
+            # Filter by symbol name if specified
+            if symbol_name:
+                symbols = [s for s in symbols if s.name == symbol_name]
+                if not symbols:
+                    return Failure(f"Symbol '{symbol_name}' not found in {file_path}")
+
+            # Output using TS Compiler API format
+            if json_output:
+                output = {
+                    "file": str(file_path),
+                    "symbols": [
+                        {
+                            "name": s.name,
+                            "kind": s.kind,
+                            "signature": s.signature,
+                            "line": s.line,
+                            "contracts": s.contracts,
+                            "members": s.members,
+                        }
+                        for s in symbols
+                    ],
+                }
+                console.print(json.dumps(output, indent=2))
+            else:
+                console.print(f"[bold]{file_path}[/bold]")
+                for s in symbols:
+                    console.print(f"  [{s.kind}] {s.name}")
+                    console.print(f"    {s.signature}")
+                    if s.contracts:
+                        for pre in s.contracts.get("pre", []):
+                            console.print(f"    @pre {pre}")
+                        for post in s.contracts.get("post", []):
+                            console.print(f"    @post {post}")
+                    if s.members:
+                        for m in s.members:
+                            console.print(f"    [{m['kind']}] {m['name']}: {m.get('signature', '')}")
+                    console.print()
+
+            return Success(None)
+
+    # Fallback to regex parser (LX-06 legacy)
     from invar.core.ts_sig_parser import (
         extract_ts_signatures,
         format_ts_signatures_json,
@@ -172,7 +229,14 @@ def _run_map_python(path: Path, top_n: int, json_output: bool) -> Result[None, s
             continue
 
     if not file_infos:
-        return Failure("No Python files found")
+        return Failure(
+            "No Python symbols found.\n\n"
+            "Available tools:\n"
+            "- invar sig <file.py> — Extract signatures\n"
+            "- invar refs <file.py>::Symbol — Find references\n"
+            "- invar_doc_* — Document navigation\n"
+            "- invar_guard — Static verification"
+        )
 
     # Build perception map
     perception_map = build_perception_map(file_infos, sources, str(path.absolute()))
@@ -190,10 +254,47 @@ def _run_map_python(path: Path, top_n: int, json_output: bool) -> Result[None, s
 
 # @shell_complexity: TypeScript map with file discovery and symbol extraction
 def _run_map_typescript(path: Path, top_n: int, json_output: bool) -> Result[None, str]:
-    """Run map for TypeScript projects (LX-06).
+    """Run map for TypeScript projects.
 
-    MVP: Lists symbols without reference counting (Phase 2 can add references).
+    DX-78: Uses TS Compiler API when available, falls back to regex parser.
     """
+    from invar.shell.ts_compiler import is_typescript_available, run_map_typescript
+
+    # Try TS Compiler API first (DX-78)
+    if is_typescript_available():
+        map_result = run_map_typescript(path, top_n)
+        if isinstance(map_result, Success):
+            data = map_result.unwrap()
+
+            if not data.get("symbols"):
+                return Failure(
+                    "No TypeScript symbols found.\n\n"
+                    "Available tools:\n"
+                    "- invar sig <file.ts> — Extract signatures\n"
+                    "- invar refs <file.ts>::Symbol — Find references\n"
+                    "- invar_doc_* — Document navigation\n"
+                    "- invar_guard — Static verification"
+                )
+
+            # Output using TS Compiler API format
+            if json_output:
+                output = {
+                    "language": "typescript",
+                    "total_symbols": data.get("total", len(data["symbols"])),
+                    "symbols": data["symbols"],
+                }
+                console.print(json.dumps(output, indent=2))
+            else:
+                console.print("[bold]TypeScript Symbol Map[/bold]")
+                console.print(f"Total symbols: {data.get('total', len(data['symbols']))}\n")
+                for sym in data["symbols"]:
+                    console.print(f"[{sym['kind']}] {sym['name']}")
+                    console.print(f"  {sym['file']}:{sym['line']}")
+                    console.print()
+
+            return Success(None)
+
+    # Fallback to regex parser (LX-06 legacy)
     from invar.core.ts_sig_parser import TSSymbol, extract_ts_signatures
     from invar.shell.fs import discover_typescript_files
 
@@ -213,7 +314,14 @@ def _run_map_typescript(path: Path, top_n: int, json_output: bool) -> Result[Non
             continue
 
     if not all_symbols:
-        return Failure("No TypeScript symbols found (files may be empty or contain no exportable symbols)")
+        return Failure(
+            "No TypeScript symbols found.\n\n"
+            "Available tools:\n"
+            "- invar sig <file.ts> — Extract signatures\n"
+            "- invar refs <file.ts>::Symbol — Find references\n"
+            "- invar_doc_* — Document navigation\n"
+            "- invar_guard — Static verification"
+        )
 
     # Sort by kind priority (function/class first), then by name
     kind_order = {"function": 0, "class": 1, "interface": 2, "type": 3, "const": 4, "method": 5}
@@ -249,3 +357,191 @@ def _run_map_typescript(path: Path, top_n: int, json_output: bool) -> Result[Non
             console.print()
 
     return Success(None)
+
+
+# @shell_complexity: Reference finding with multi-language support and output formatting
+def run_refs(target: str, json_output: bool) -> Result[None, str]:
+    """Find all references to a symbol.
+
+    Target format: "path/to/file.py::symbol_name" or "path/to/file.ts::symbol_name"
+    DX-78: Supports both Python (via jedi) and TypeScript (via TS Compiler API).
+    """
+    # Parse target
+    if "::" not in target:
+        return Failure(
+            "Invalid target format.\n\n"
+            "Expected: path/to/file.py::symbol_name\n"
+            "Example: src/auth.py::validate_token"
+        )
+
+    file_part, symbol_name = target.rsplit("::", 1)
+    file_path = Path(file_part)
+
+    if not file_path.exists():
+        return Failure(f"File not found: {file_path}")
+
+    suffix = file_path.suffix.lower()
+
+    # Route to language-specific implementation
+    if suffix in (".ts", ".tsx"):
+        return _run_refs_typescript(file_path, symbol_name, json_output)
+    elif suffix in (".py", ".pyi"):
+        return _run_refs_python(file_path, symbol_name, json_output)
+    else:
+        return Failure(
+            f"Unsupported file type: {suffix}\n\n"
+            "Supported: .py, .pyi, .ts, .tsx"
+        )
+
+
+# @shell_complexity: Reference finding with output formatting and error handling
+def _run_refs_python(
+    file_path: Path, symbol_name: str, json_output: bool
+) -> Result[None, str]:
+    """Find references in Python using jedi."""
+    from invar.shell.py_refs import find_all_references_to_symbol
+
+    # Find project root
+    project_root = file_path.parent
+    for parent in file_path.parents:
+        if (parent / "pyproject.toml").exists() or (parent / "setup.py").exists():
+            project_root = parent
+            break
+
+    refs = find_all_references_to_symbol(file_path, symbol_name, project_root)
+
+    if not refs:
+        return Failure(f"Symbol '{symbol_name}' not found in {file_path}")
+
+    # Output
+    if json_output:
+        output = {
+            "target": str(file_path) + "::" + symbol_name,
+            "total": len(refs),
+            "references": [
+                {
+                    "file": str(ref.file.relative_to(project_root))
+                    if ref.file.is_relative_to(project_root)
+                    else str(ref.file),
+                    "line": ref.line,
+                    "column": ref.column,
+                    "context": ref.context,
+                    "is_definition": ref.is_definition,
+                }
+                for ref in refs
+            ],
+        }
+        console.print(json.dumps(output, indent=2))
+    else:
+        console.print(f"[bold]References to {symbol_name}[/bold]")
+        console.print(f"Found {len(refs)} reference(s)\n")
+
+        for ref in refs:
+            rel_path = (
+                ref.file.relative_to(project_root)
+                if ref.file.is_relative_to(project_root)
+                else ref.file
+            )
+            marker = " [definition]" if ref.is_definition else ""
+            console.print(f"{rel_path}:{ref.line}{marker}")
+            if ref.context:
+                console.print(f"  {ref.context}")
+            console.print()
+
+    return Success(None)
+
+
+@dataclass
+class _SymbolPosition:
+    """Temporary holder for symbol position during refs lookup."""
+    line: int
+    column: int
+    name: str
+
+
+# @shell_complexity: TypeScript refs with symbol lookup and output formatting
+def _run_refs_typescript(
+    file_path: Path, symbol_name: str, json_output: bool
+) -> Result[None, str]:
+    """Find references in TypeScript using TS Compiler API."""
+    from invar.shell.ts_compiler import is_typescript_available, run_refs_typescript
+
+    if not is_typescript_available():
+        return Failure(
+            "TypeScript tools not available.\n\n"
+            "Requirements:\n"
+            "- Node.js installed\n"
+            "- tsconfig.json in project root"
+        )
+
+    # First, find the symbol's position using sig command
+    from invar.shell.ts_compiler import run_sig_typescript
+
+    sig_result = run_sig_typescript(file_path)
+    if isinstance(sig_result, Failure):
+        return sig_result
+
+    symbols = sig_result.unwrap()
+    symbol = next((s for s in symbols if s.name == symbol_name), None)
+
+    if symbol is None:
+        # Check class members
+        for s in symbols:
+            if s.members:
+                for member in s.members:
+                    if member.get("name") == symbol_name:
+                        # Extract column if available, default to 0
+                        column = member.get("column", 0)
+                        symbol = _SymbolPosition(
+                            line=member["line"],
+                            column=column,
+                            name=symbol_name
+                        )
+                        break
+            if symbol:
+                break
+
+    if symbol is None:
+        return Failure(f"Symbol '{symbol_name}' not found in {file_path}")
+
+    # Find references using position
+    # Use symbol.column if available (from member dict), defaults to 0
+    column = getattr(symbol, "column", 0)
+    refs_result = run_refs_typescript(file_path, symbol.line, column)
+    if isinstance(refs_result, Failure):
+        return refs_result
+
+    refs = refs_result.unwrap()
+
+    if not refs:
+        return Failure(f"No references found for '{symbol_name}'")
+
+    # Output (refs already have relative paths from ts-query.js)
+    if json_output:
+        output = {
+            "target": str(file_path) + "::" + symbol_name,
+            "total": len(refs),
+            "references": [
+                {
+                    "file": ref.file,
+                    "line": ref.line,
+                    "column": ref.column,
+                    "context": ref.context,
+                    "is_definition": ref.is_definition,
+                }
+                for ref in refs
+            ],
+        }
+        console.print(json.dumps(output, indent=2))
+    else:
+        console.print(f"[bold]References to {symbol_name}[/bold]")
+        console.print(f"Found {len(refs)} reference(s)\n")
+
+        for ref in refs:
+            marker = " [definition]" if ref.is_definition else ""
+            console.print(f"{ref.file}:{ref.line}{marker}")
+            if ref.context:
+                console.print(f"  {ref.context}")
+            console.print()
+
+    return Success(None)

invar/shell/py_refs.py

@@ -0,0 +1,156 @@
+"""Python reference finding using jedi.
+
+DX-78: Provides cross-file reference finding for Python symbols.
+Shell module: Uses jedi library for I/O-based symbol analysis.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import jedi
+
+
+@dataclass
+class Reference:
+    """A reference to a Python symbol."""
+
+    file: Path
+    line: int
+    column: int
+    context: str
+    is_definition: bool = False
+
+
+# @shell_complexity: Reference finding with jedi library and error handling
+def find_references(
+    file_path: Path,
+    line: int,
+    column: int,
+    project_root: Path | None = None,
+) -> list[Reference]:
+    """Find all references to symbol at position using jedi.
+
+    Args:
+        file_path: File containing the symbol
+        line: 1-based line number
+        column: 0-based column number
+        project_root: Project root for cross-file resolution
+
+    Returns:
+        List of references found
+
+    >>> from pathlib import Path
+    >>> import tempfile, os
+    >>> # Test with a simple Python file
+    >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+    ...     _ = f.write('def hello():\\n    pass\\n')
+    ...     temp_file = Path(f.name)
+    >>> # Find references returns a list (may be empty if jedi not configured)
+    >>> refs = find_references(temp_file, 1, 4)
+    >>> isinstance(refs, list)
+    True
+    >>> os.unlink(temp_file)
+    """
+    source = file_path.read_text(encoding="utf-8")
+
+    project = None
+    if project_root:
+        project = jedi.Project(path=str(project_root))
+
+    script = jedi.Script(source, path=str(file_path), project=project)
+    refs = script.get_references(line, column)
+
+    results: list[Reference] = []
+    for ref in refs:
+        # Skip builtins (no module_path)
+        if not ref.module_path:
+            continue
+
+        line_code = ref.get_line_code()
+        context = line_code.strip() if line_code else ""
+
+        results.append(
+            Reference(
+                file=Path(ref.module_path),
+                line=ref.line,
+                column=ref.column,
+                context=context,
+                is_definition=ref.is_definition(),
+            )
+        )
+
+    return results
+
+
+# @shell_complexity: Symbol search using jedi library
+def find_symbol_position(file_path: Path, symbol_name: str) -> tuple[int, int] | None:
+    """Find the position of a symbol definition in a file.
+
+    Args:
+        file_path: File to search
+        symbol_name: Name of the symbol to find
+
+    Returns:
+        Tuple of (line, column) or None if not found
+
+    >>> from pathlib import Path
+    >>> import tempfile, os
+    >>> # Test finding a function definition
+    >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+    ...     _ = f.write('def test_func():\\n    return 42\\n')
+    ...     temp_file = Path(f.name)
+    >>> pos = find_symbol_position(temp_file, "test_func")
+    >>> isinstance(pos, tuple) or pos is None  # Returns tuple or None
+    True
+    >>> os.unlink(temp_file)
+    """
+    source = file_path.read_text(encoding="utf-8")
+    script = jedi.Script(source, path=str(file_path))
+
+    # Get all names defined in the file
+    names = script.get_names(all_scopes=True)
+
+    for name in names:
+        if name.name == symbol_name and name.is_definition():
+            return (name.line, name.column)
+
+    return None
+
+
+# @shell_complexity: Combines symbol position lookup and reference finding
+def find_all_references_to_symbol(
+    file_path: Path,
+    symbol_name: str,
+    project_root: Path | None = None,
+) -> list[Reference]:
+    """Find all references to a named symbol.
+
+    Convenience function that combines find_symbol_position and find_references.
+
+    Args:
+        file_path: File containing the symbol definition
+        symbol_name: Name of the symbol
+        project_root: Project root for cross-file resolution
+
+    Returns:
+        List of references found
+
+    >>> from pathlib import Path
+    >>> import tempfile, os
+    >>> # Test finding all references to a symbol
+    >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+    ...     _ = f.write('def greet():\\n    pass\\ngreet()\\n')
+    ...     temp_file = Path(f.name)
+    >>> refs = find_all_references_to_symbol(temp_file, "greet")
+    >>> isinstance(refs, list)  # Returns list of references
+    True
+    >>> os.unlink(temp_file)
+    """
+    position = find_symbol_position(file_path, symbol_name)
+    if position is None:
+        return []
+
+    line, column = position
+    return find_references(file_path, line, column, project_root)