invar-tools 1.10.0__py3-none-any.whl → 1.12.0__py3-none-any.whl

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)

invar/shell/skill_manager.py

@@ -11,6 +11,7 @@ DX-71: Simplified to idempotent `add` command with region merge.
 
 from __future__ import annotations
 
+import re
 import shutil
 from dataclasses import dataclass
 from pathlib import Path
@@ -35,12 +36,15 @@ CORE_SKILLS = {"develop", "review", "investigate", "propose", "guard", "audit"}
 
 # @shell_orchestration: Validation helper used only by shell add_skill/remove_skill
 def _is_valid_skill_name(name: str) -> bool:
-    """Validate skill name to prevent path traversal attacks."""
-    # Block path traversal characters
-    if ".." in name or "/" in name or "\\" in name:
+    """Validate skill name to prevent path traversal and filesystem attacks."""
+    # Block path traversal characters and null bytes
+    if ".." in name or "/" in name or "\\" in name or "\x00" in name:
         return False
-    # Must be non-empty and not start with dot or underscore
-    return bool(name) and not name.startswith(".") and not name.startswith("_")
+    # Block special names that could cause issues
+    if name in (".", ""):
+        return False
+    # Must not start with dot or underscore
+    return not name.startswith(".") and not name.startswith("_")
 
 
 def _merge_md_file(src: Path, dst: Path) -> tuple[bool, str]:
@@ -74,10 +78,10 @@ def _merge_md_file(src: Path, dst: Path) -> tuple[bool, str]:
         shutil.copy2(src, dst)
         return False, "Updated"
 
-    except Exception:
-        # On parse error, preserve existing file - don't silently lose user data
-        # Return warning message so caller can inform user
-        return False, "Skipped (merge failed, existing file preserved)"
+    except (OSError, UnicodeDecodeError, ValueError, KeyError) as e:
+        # On I/O or parse error, preserve existing file - don't silently lose user data
+        # Include error details for debugging
+        return False, f"Skipped (merge failed: {type(e).__name__}: {e})"
 
 
 @dataclass
@@ -109,7 +113,7 @@ def load_registry() -> Result[dict, str]:
         content = registry_path.read_text()
         data = yaml.safe_load(content)
         return Success(data)
-    except Exception as e:
+    except (yaml.YAMLError, OSError, UnicodeDecodeError) as e:
         return Failure(f"Failed to parse registry: {e}")
 
 
@@ -245,7 +249,7 @@ def add_skill(
         result_msg = "updated" if is_update else "installed"
         return Success(f"Skill '{skill_name}' {result_msg} successfully")
 
-    except Exception as e:
+    except (OSError, shutil.Error) as e:
         # Clean up on failure (only for fresh install)
         # M3 note: Updates that fail mid-way may leave directory in partial state.
         # This is acceptable because: (1) user extensions are preserved via merge,
@@ -258,8 +262,6 @@ def add_skill(
 
 def has_user_extensions(skill_dir: Path) -> bool:
     """Check if SKILL.md has user content in extensions region."""
-    import re
-
     skill_md = skill_dir / "SKILL.md"
     if not skill_md.exists():
         return False
@@ -283,7 +285,7 @@ def has_user_extensions(skill_dir: Path) -> bool:
 
             # Check if any non-whitespace content remains
             return bool(cleaned.strip())
-    except Exception:
+    except (ValueError, KeyError):
         # Parse error - assume extensions exist (safe default)
         return True
 
@@ -334,7 +336,7 @@ def remove_skill(
     try:
         shutil.rmtree(dest_dir)
         return Success(f"Skill '{skill_name}' removed successfully")
-    except Exception as e:
+    except (OSError, shutil.Error) as e:
         return Failure(f"Failed to remove skill: {e}")
 
 

invar/shell/ts_compiler.py

@@ -0,0 +1,238 @@
+"""TypeScript Compiler API wrapper (single-shot subprocess).
+
+DX-78: Provides Python interface to ts-query.js for TypeScript analysis.
+
+Architecture:
+- Single-shot subprocess: starts, runs query, exits
+- No persistent process, no orphan risk
+- Falls back to regex parser if Node.js unavailable
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from returns.result import Failure, Result, Success
+
+
+@dataclass
+class TSSymbolInfo:
+    """TypeScript symbol information from Compiler API."""
+
+    name: str
+    kind: str
+    signature: str
+    line: int
+    file: str = ""
+    contracts: dict[str, list[str]] | None = None
+    members: list[dict[str, Any]] | None = None
+
+
+@dataclass
+class TSReference:
+    """A reference to a TypeScript symbol."""
+
+    file: str
+    line: int
+    column: int
+    context: str
+    is_definition: bool = False
+
+
+def _find_ts_query_js() -> Path:
+    """Find the ts-query.js script bundled with invar-tools."""
+    # Look relative to this file's location
+    this_dir = Path(__file__).parent.parent
+    ts_query_path = this_dir / "node_tools" / "ts-query.js"
+
+    if ts_query_path.exists():
+        return ts_query_path
+
+    # Fallback: check if installed globally or in node_modules
+    raise FileNotFoundError("ts-query.js not found")
+
+
+# @shell_complexity: Project root discovery with parent traversal
+def _find_tsconfig_root(file_path: Path) -> Path:
+    """Find the project root containing tsconfig.json."""
+    current = file_path.parent if file_path.is_file() else file_path
+
+    while current != current.parent:
+        if (current / "tsconfig.json").exists():
+            return current
+        current = current.parent
+
+    # Fallback to file's directory
+    return file_path.parent if file_path.is_file() else file_path
+
+
+# @shell_complexity: Subprocess orchestration with error handling and JSON parsing
+def query_typescript(
+    project_root: Path,
+    command: str,
+    **params: Any,
+) -> Result[dict[str, Any], str]:
+    """Run ts-query.js and return parsed result.
+
+    Single-shot subprocess: starts, runs query, exits.
+    No persistent process, no orphan risk.
+
+    Args:
+        project_root: Project root containing tsconfig.json
+        command: Query command (sig, map, refs)
+        **params: Command-specific parameters
+
+    Returns:
+        Parsed JSON result or error message
+    """
+    try:
+        ts_query_path = _find_ts_query_js()
+    except FileNotFoundError:
+        return Failure("ts-query.js not found. Install Node.js to use TypeScript tools.")
+
+    query = {"command": command, **params}
+
+    try:
+        result = subprocess.run(
+            ["node", str(ts_query_path), json.dumps(query)],
+            cwd=str(project_root),
+            capture_output=True,
+            text=True,
+            timeout=30,  # Safety timeout
+        )
+
+        if result.returncode != 0:
+            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
+            return Failure(f"ts-query failed: {error_msg}")
+
+        output = json.loads(result.stdout)
+
+        # Check for error in output
+        if "error" in output:
+            return Failure(output["error"])
+
+        return Success(output)
+
+    except subprocess.TimeoutExpired:
+        return Failure("TypeScript query timed out (30s)")
+    except FileNotFoundError:
+        return Failure(
+            "Node.js not found.\n\n"
+            "To use TypeScript tools, install Node.js:\n"
+            "- macOS: brew install node\n"
+            "- Ubuntu: apt install nodejs\n"
+            "- Windows: https://nodejs.org/"
+        )
+    except json.JSONDecodeError as e:
+        return Failure(f"Invalid JSON from ts-query: {e}")
+    except Exception as e:
+        return Failure(f"TypeScript query error: {e}")
+
+
+def run_sig_typescript(file_path: Path) -> Result[list[TSSymbolInfo], str]:
+    """Get signatures for TypeScript file using Compiler API.
+
+    Args:
+        file_path: Path to TypeScript file
+
+    Returns:
+        List of symbol information or error message
+    """
+    project_root = _find_tsconfig_root(file_path)
+    result = query_typescript(project_root, "sig", file=str(file_path))
+
+    if isinstance(result, Failure):
+        return result
+
+    data = result.unwrap()
+    symbols = []
+
+    for sym in data.get("symbols", []):
+        symbols.append(
+            TSSymbolInfo(
+                name=sym.get("name", ""),
+                kind=sym.get("kind", ""),
+                signature=sym.get("signature", ""),
+                line=sym.get("line", 0),
+                file=str(file_path),
+                contracts=sym.get("contracts"),
+                members=sym.get("members"),
+            )
+        )
+
+    return Success(symbols)
+
+
+def run_map_typescript(path: Path, top_n: int) -> Result[dict[str, Any], str]:
+    """Get symbol map with reference counts for TypeScript project.
+
+    Args:
+        path: Project path to scan
+        top_n: Maximum number of symbols to return
+
+    Returns:
+        Symbol map data or error message
+    """
+    return query_typescript(path, "map", path=str(path), top=top_n)
+
+
+def run_refs_typescript(
+    file_path: Path, line: int, column: int
+) -> Result[list[TSReference], str]:
+    """Find all references to symbol at position.
+
+    Args:
+        file_path: File containing the symbol
+        line: 1-based line number
+        column: 0-based column number
+
+    Returns:
+        List of references or error message
+    """
+    project_root = _find_tsconfig_root(file_path)
+    result = query_typescript(
+        project_root,
+        "refs",
+        file=str(file_path),
+        line=line,
+        column=column,
+    )
+
+    if isinstance(result, Failure):
+        return result
+
+    data = result.unwrap()
+    references = []
+
+    for ref in data.get("references", []):
+        references.append(
+            TSReference(
+                file=ref.get("file", ""),
+                line=ref.get("line", 0),
+                column=ref.get("column", 0),
+                context=ref.get("context", ""),
+                is_definition=ref.get("isDefinition", False),
+            )
+        )
+
+    return Success(references)
+
+
+def is_typescript_available() -> bool:
+    """Check if TypeScript Compiler API tools are available."""
+    try:
+        _find_ts_query_js()
+        # Also check if Node.js is available
+        result = subprocess.run(
+            ["node", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False

invar/templates/examples/typescript/patterns.md

@@ -0,0 +1,193 @@
+# TypeScript Patterns for Agents
+
+Reference patterns for AI agents working with TypeScript under Invar Protocol.
+
+## Tool × Feature Matrix
+
+| Feature | TypeScript Pattern | Tool Command |
+|---------|-------------------|--------------|
+| Signatures | `function name(params): Return` | `invar sig file.ts` |
+| Contracts | `@pre`, `@post` JSDoc + Zod | `invar sig file.ts` |
+| References | Cross-file symbol usage | `invar refs file.ts::Symbol` |
+| Verification | tsc + eslint + vitest | `invar guard` |
+| Document nav | Markdown structure | `invar doc toc file.md` |
+
+---
+
+## Pattern 1: Preconditions with Zod
+
+```typescript
+import { z } from 'zod';
+
+// Schema IS the precondition
+const UserInputSchema = z.object({
+  email: z.string().email(),
+  age: z.number().int().positive().max(150),
+});
+
+type UserInput = z.infer<typeof UserInputSchema>;
+
+/**
+ * Create a user with validated input.
+ * @pre UserInputSchema.parse(input) succeeds
+ * @post result.id is set
+ */
+function createUser(input: UserInput): User {
+  // Zod already validated - safe to use
+  return { id: generateId(), ...input };
+}
+```
+
+**Agent workflow:**
+1. Define Zod schema FIRST (the @pre)
+2. Derive TypeScript type from schema
+3. Implement function body
+4. Zod validates at runtime
+
+---
+
+## Pattern 2: Postconditions
+
+```typescript
+/**
+ * Calculate discount price.
+ * @pre price > 0 && discount >= 0 && discount <= 1
+ * @post result >= 0 && result <= price
+ */
+function applyDiscount(price: number, discount: number): number {
+  const result = price * (1 - discount);
+
+  // Postcondition check (development only)
+  console.assert(result >= 0 && result <= price,
+    `Postcondition failed: ${result}`);
+
+  return result;
+}
+```
+
+**Note:** Unlike Python's `@post` decorator, TypeScript postconditions
+are documented in JSDoc and checked manually or via assertion.
+
+---
+
+## Pattern 3: Core/Shell Separation
+
+```typescript
+// ─── Core (Pure) ───
+// No I/O, no side effects, only data transformations
+
+function validateEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+function calculateTotal(items: CartItem[]): number {
+  return items.reduce((sum, item) => sum + item.price * item.qty, 0);
+}
+
+// ─── Shell (I/O) ───
+// All external interactions, returns Result<T, E>
+
+import { Result, ok, err } from 'neverthrow';
+
+async function fetchUser(id: string): Promise<Result<User, ApiError>> {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) return err({ code: response.status });
+    return ok(await response.json());
+  } catch (e) {
+    return err({ code: 500, message: String(e) });
+  }
+}
+```
+
+**Agent checklist:**
+- [ ] Core functions: No imports from `fs`, `http`, `fetch`, etc.
+- [ ] Shell functions: Return `Result<T, E>` for fallible operations
+- [ ] Dependency injection: Pass data to Core, not paths
+
+---
+
+## Pattern 4: Exhaustive Switch
+
+```typescript
+type Status = 'pending' | 'approved' | 'rejected';
+
+function getStatusMessage(status: Status): string {
+  switch (status) {
+    case 'pending': return 'Waiting for review';
+    case 'approved': return 'Request approved';
+    case 'rejected': return 'Request denied';
+    default:
+      // TypeScript ensures this is never reached
+      const _exhaustive: never = status;
+      throw new Error(`Unknown status: ${_exhaustive}`);
+  }
+}
+```
+
+**Why:** Adding a new status forces handling in all switches.
+
+---
+
+## Pattern 5: Branded Types
+
+```typescript
+// Nominal typing for semantic safety
+type UserId = string & { readonly __brand: 'UserId' };
+type OrderId = string & { readonly __brand: 'OrderId' };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+// Compiler prevents mixing IDs
+function getUser(id: UserId): User { ... }
+function getOrder(id: OrderId): Order { ... }
+
+getUser(orderId);  // ❌ Type error: OrderId is not UserId
+```
+
+---
+
+## Tool Usage Examples
+
+### View signatures
+
+```bash
+$ invar sig src/auth.ts
+src/auth.ts
+  function validateToken(token: string): boolean
+    @pre token.length > 0
+    @post result indicates valid JWT
+
+  class AuthService
+    method login(email: string, password: string): Promise<Result<Token, AuthError>>
+    method logout(): Promise<void>
+```
+
+### Find references
+
+```bash
+$ invar refs src/auth.ts::validateToken
+src/auth.ts:15 — Definition
+src/routes/api.ts:42 — if (validateToken(req.headers.auth)) {
+src/middleware/auth.ts:18 — const isValid = validateToken(token);
+tests/auth.test.ts:8 — expect(validateToken('invalid')).toBe(false);
+```
+
+### Verify code
+
+```bash
+$ invar guard
+TypeScript Guard Report
+========================================
+[PASS] tsc --noEmit (no type errors)
+[PASS] eslint (0 errors, 2 warnings)
+[PASS] vitest (24 tests passed)
+----------------------------------------
+Guard passed.
+```
+
+---
+
+*Managed by Invar - regenerated on `invar update`*