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

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/claude-md/universal/tool-selection.md

@@ -0,0 +1,110 @@
+### Document Tools (DX-76)
+
+| I want to... | Use |
+|--------------|-----|
+| View document structure | `{% if syntax == "mcp" %}invar_doc_toc(file="<file>"){% else %}invar doc toc <file> [--format text]{% endif %}` |
+| Read specific section | `{% if syntax == "mcp" %}invar_doc_read(file="<file>", section="<section>"){% else %}invar doc read <file> <section>{% endif %}` |
+| Search sections by title | `{% if syntax == "mcp" %}invar_doc_find(file="<file>", pattern="<pattern>"){% else %}invar doc find <pattern> <files...>{% endif %}` |
+| Replace section content | `{% if syntax == "mcp" %}invar_doc_replace(file="<file>", section="<section>"){% else %}invar doc replace <file> <section>{% endif %}` |
+| Insert new section | `{% if syntax == "mcp" %}invar_doc_insert(file="<file>", anchor="<anchor>"){% else %}invar doc insert <file> <anchor>{% endif %}` |
+| Delete section | `{% if syntax == "mcp" %}invar_doc_delete(file="<file>", section="<section>"){% else %}invar doc delete <file> <section>{% endif %}` |
+
+**Section addressing:** slug path (`requirements/auth`), fuzzy (`auth`), index (`#0/#1`), line (`@48`)
+
+## Tool Selection
+
+### Calling Methods (Priority Order)
+
+Invar tools can be called in 3 ways. **Try in order:**
+
+1. **MCP tools** (Claude Code with MCP enabled)
+   - Direct function calls: `invar_guard()`, `invar_sig()`, etc.
+   - No Bash wrapper needed
+
+2. **CLI command** (if `invar` installed in PATH)
+   - Via Bash: `invar guard`, `invar sig`, etc.
+   - Install: `pip install invar-tools`
+
+3. **uvx fallback** (always available, no install needed)
+   - Via Bash: `uvx invar-tools guard`, `uvx invar-tools sig`, etc.
+
+---
+
+### Parameter Reference
+
+**guard** - Verify code quality
+```{% if syntax == "mcp" %}python
+# MCP
+invar_guard()                    # Check changed files (default)
+invar_guard(changed=False)       # Check all files{% else %}bash
+# CLI
+invar guard                      # Check changed files (default)
+invar guard --all                # Check all files{% endif %}
+```
+
+**sig** - Show function signatures and contracts
+```{% if syntax == "mcp" %}python
+# MCP
+invar_sig(target="src/foo.py"){% else %}bash
+# CLI
+invar sig src/foo.py
+invar sig src/foo.py::function_name{% endif %}
+```
+
+**map** - Find entry points
+```{% if syntax == "mcp" %}python
+# MCP
+invar_map(path=".", top=10){% else %}bash
+# CLI
+invar map [path] --top 10{% endif %}
+```
+
+**refs** - Find all references to a symbol
+```{% if syntax == "mcp" %}python
+# MCP
+invar_refs(target="src/foo.py::MyClass"){% else %}bash
+# CLI
+invar refs src/foo.py::MyClass{% endif %}
+```
+
+**doc*** - Document tools
+```{% if syntax == "mcp" %}python
+# MCP
+invar_doc_toc(file="docs/spec.md")
+invar_doc_read(file="docs/spec.md", section="intro"){% else %}bash
+# CLI
+invar doc toc docs/spec.md
+invar doc read docs/spec.md intro{% endif %}
+```
+
+---
+
+### Quick Examples
+
+```{% if syntax == "mcp" %}python
+# Verify after changes (all three methods identical)
+invar_guard()                        # MCP
+bash("invar guard")                  # CLI
+bash("uvx invar-tools guard")        # uvx
+
+# Full project check
+invar_guard(changed=False)           # MCP
+bash("invar guard --all")            # CLI
+
+# See function contracts
+invar_sig(target="src/core/parser.py")
+bash("invar sig src/core/parser.py"){% else %}bash
+# Verify after changes (all three methods identical)
+invar guard                          # CLI
+uvx invar-tools guard                # uvx
+
+# Full project check
+invar guard --all                    # CLI
+uvx invar-tools guard --all          # uvx
+
+# See function contracts
+invar sig src/core/parser.py
+uvx invar-tools sig src/core/parser.py{% endif %}
+```
+
+**Note**: All three methods now have identical default behavior.

invar/templates/config/CLAUDE.md.jinja

@@ -23,6 +23,8 @@
 {% include "claude-md/typescript/quick-reference.md" %}
 {% endif %}
 
+{% include "claude-md/universal/tool-selection.md" %}
+
 {% include "claude-md/universal/workflow.md" %}
 
 ---

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`*

invar/templates/manifest.toml

@@ -64,6 +64,11 @@ extensions = { action = "preserve" }
 ".claude/skills/propose/SKILL.md" = { src = "skills/propose/SKILL.md.jinja", type = "jinja" }
 ".claude/skills/review/SKILL.md" = { src = "skills/review/SKILL.md.jinja", type = "jinja" }
 
+# DX-79: Invar usage feedback skill
+".claude/skills/invar-reflect/SKILL.md" = { src = "skills/invar-reflect/SKILL.md", type = "copy" }
+".claude/skills/invar-reflect/template.md" = { src = "skills/invar-reflect/template.md", type = "copy" }
+".claude/skills/invar-reflect/CONFIG.md" = { src = "skills/invar-reflect/CONFIG.md", type = "copy" }
+
 # Commands (Jinja2 templates for language-specific content)
 ".claude/commands/audit.md" = { src = "commands/audit.md.jinja", type = "jinja" }
 ".claude/commands/guard.md" = { src = "commands/guard.md", type = "copy" }
@@ -136,4 +141,7 @@ create_only = [
     ".pre-commit-config.yaml",
     ".claude/commands/audit.md",
     ".claude/commands/guard.md",
+    ".claude/skills/invar-reflect/SKILL.md",
+    ".claude/skills/invar-reflect/template.md",
+    ".claude/skills/invar-reflect/CONFIG.md",
 ]

invar/templates/protocol/python/tools.md

@@ -1,9 +1,9 @@
 ## Commands (Python)
 
 ```bash
-invar guard              # Full: static + doctests + CrossHair + Hypothesis
+invar guard              # Check git-modified files (fast, default)
+invar guard --all        # Check entire project (CI, release)
 invar guard --static     # Static only (quick debug, ~0.5s)
-invar guard --changed    # Modified files only
 invar guard --coverage   # Collect branch coverage
 invar guard -c           # Contract coverage only (DX-63)
 invar sig <file>         # Show contracts + signatures
@@ -11,6 +11,9 @@ invar map --top 10       # Most-referenced symbols
 invar rules              # List all rules with detection/hints (JSON)
 ```
 
+**Default behavior**: Checks git-modified files for fast feedback during development.
+Use `--all` for comprehensive checks before release.
+
 ## Configuration (Python)
 
 ```toml

invar/templates/protocol/typescript/tools.md

@@ -2,15 +2,18 @@
 
 ```bash
 # Verification (Python CLI - works for TypeScript)
-invar guard                  # Full: tsc + eslint + vitest + ts-analyzer
+invar guard                  # Check git-modified files (fast, default)
+invar guard --all            # Check entire project (CI, release)
 invar guard --json           # Agent-friendly v2.0 JSON output
-invar guard --changed        # Modified files only
 
 # Analysis
 invar sig <file>             # Show function signatures
 invar map --top 10           # Most-referenced symbols
 ```
 
+**Default behavior**: Checks git-modified files for fast feedback during development.
+Use `--all` for comprehensive checks before release.
+
 ## Guard Output (v2.0 JSON)
 
 ```json