invar-tools 1.11.0__tar.gz → 1.12.0__tar.gz

{invar_tools-1.11.0 → invar_tools-1.12.0}/.claude/skills/develop/SKILL.md

@@ -420,8 +420,7 @@ Agent:
 
 ✓ Final: guard PASS | 0 errors, 1 warning
 ```
-<!--/invar:skill-->
-<!--invar:extensions-->
+<!--/invar:skill--><!--invar:extensions-->
 <!-- ========================================================================
      EXTENSIONS REGION - USER EDITABLE
      Add project-specific extensions here. This section is preserved on update.

{invar_tools-1.11.0 → invar_tools-1.12.0}/.claude/skills/investigate/SKILL.md

@@ -67,61 +67,6 @@ Before any workflow action:
 | Find entry points | `invar_map(top=10)` |
 | Search code patterns | Grep with regex |
 | Explore codebase | Task(Explore) agent |
-| View document structure | `invar doc toc <file>` |
-| Read document section | `invar doc read <file> <section>` |
-| Search document sections | `invar doc find <pattern> <file>` |
-
-## Long Document Handling (>500 lines)
-
-When understanding long documents (PRD, Spec, Design docs):
-
-### 1. Structure First
-
-```bash
-invar doc toc spec.md --format text
-```
-
-See the table of contents before reading content. Understand the document's organization.
-
-### 2. Read On-Demand
-
-```bash
-invar doc read spec.md "requirements/auth"
-```
-
-Only read sections relevant to your task. Avoid full-document reads.
-
-### 3. Track with TodoWrite
-
-Create a todo item for each section you need to read:
-
-```
-□ Read: Introduction (context)
-□ Read: Requirements/Auth (main task)
-□ Read: API Design (reference)
-□ Read: Security (constraints)
-```
-
-Mark each as completed after reading.
-
-### 4. Maintain Running Summary
-
-After reading each section, update a mental summary:
-
-```
-Key Points:
-- Auth: JWT + refresh token (spec:48)
-- Rate limit: 100 req/min (spec:120)
-- Must support OAuth2 (spec:85)
-```
-
-Include line references for traceability.
-
-### 5. Verify Coverage
-
-Before concluding, check the TOC against your todos:
-- Did you read all relevant sections?
-- Any section titles suggest missed requirements?
 
 ## Exit Format
 

{invar_tools-1.11.0 → invar_tools-1.12.0}/.invar/context.md

@@ -51,10 +51,10 @@
 
 ## Current State
 
-- **PyPI:** `invar-tools` v1.10.0 + `invar-runtime` v1.3.0
+- **PyPI:** `invar-tools` v1.12.0 + `invar-runtime` v1.3.0
 - **Protocol:** v5.0 (USBV workflow, DX-58 critical section)
-- **Status:** Feature complete, TypeScript support added
-- **Recent:** LX-05 (language-agnostic), LX-06 (TypeScript tooling), LX-07 (Extension Skills)
+- **Status:** Feature complete, TypeScript support added (DX-78)
+- **Recent:** DX-78 (TypeScript Compiler API integration), LX-05 (language-agnostic), LX-06 (TypeScript tooling), LX-07 (Extension Skills)
 - **Blockers:** None
 
 ## Active Work
@@ -117,6 +117,55 @@ Smart Guard (`invar guard`) runs multiple verification layers:
 
 ---
 
+## TypeScript Integration (DX-78)
+
+**Status:** Complete and reviewed (2026-01-03)
+
+### Architecture
+
+- **Python wrapper:** `src/invar/shell/ts_compiler.py` (uses subprocess to call Node.js)
+- **TypeScript tool:** `src/invar/node_tools/ts-query.js` (TypeScript Compiler API)
+- **Python refs:** `src/invar/shell/py_refs.py` (jedi library)
+- **CLI integration:** `perception.py`, `guard.py` (multi-language routing)
+- **MCP integration:** `handlers.py`, `server.py` (invar_refs tool)
+
+### Supported Commands
+
+| Command | Python | TypeScript |
+|---------|--------|------------|
+| `invar sig <file>` | ✅ | ✅ |
+| `invar map <path>` | ✅ | ✅ |
+| `invar refs <file>::<symbol>` | ✅ (jedi) | ✅ (TS Compiler API) |
+
+### Security Model
+
+- **Single-shot subprocess:** Process starts, runs query, outputs JSON, exits
+- **No orphan risk:** No persistent Node.js processes
+- **Path validation:** All file paths validated before subprocess execution
+- **JSON parsing:** Input validation with error handling
+
+### Dependencies
+
+- **Runtime:** Node.js + TypeScript package (peer dependency)
+- **Python:** jedi library (required for Python refs)
+- **Detection:** Automatic via tsconfig.json presence
+
+### Known Limitations
+
+- Requires tsconfig.json in project root
+- TypeScript project must be compilable
+- No support for decorator metadata yet
+
+### Review History
+
+- **2026-01-03:** Adversarial review completed
+  - Fixed 4 critical TypeScript bugs (JSON parsing, null checks, I/O error handling, TOCTOU)
+  - Fixed 5 major Python bugs (column hardcoding, missing markers, weak tests, dynamic types)
+  - 32 integration tests passing
+  - Guard: 0 errors, 0 warnings
+
+---
+
 ## Release Process
 
 **Do NOT use `twine upload` manually.** GitHub Actions handles PyPI publishing.
@@ -136,6 +185,7 @@ gh release create vX.Y.Z --title "vX.Y.Z - Title" --notes "..."
 
 | Version | Date | Highlights |
 |---------|------|------------|
+| 1.12.0 | 2026-01 | TypeScript Compiler API integration (DX-78), multi-language refs |
 | 1.9.0 | 2026-01 | Extension Skills (LX-07), TypeScript support (LX-05/06) |
 | 1.8.0 | 2025-12 | Claude hooks improvements, interactive init (DX-70) |
 | 1.5.0 | 2025-12 | Language-agnostic protocol templates |

{invar_tools-1.11.0 → invar_tools-1.12.0}/CLAUDE.md

@@ -83,18 +83,7 @@ src/{project}/
 
 > Full decision tree: [INVAR.md#core-shell](./INVAR.md#decision-tree-core-vs-shell)
 
-### Document Tools (DX-76)
 
-| I want to... | Use |
-|--------------|-----|
-| View document structure | `invar doc toc <file> [--format text]` |
-| Read specific section | `invar doc read <file> <section>` |
-| Search sections by title | `invar doc find <pattern> <files...>` |
-| Replace section content | `invar doc replace <file> <section>` |
-| Insert new section | `invar doc insert <file> <anchor>` |
-| Delete section | `invar doc delete <file> <section>` |
-
-**Section addressing:** slug path (`requirements/auth`), fuzzy (`auth`), index (`#0/#1`), line (`@48`)
 
 ## Documentation Structure
 
@@ -299,6 +288,37 @@ When continuing from a previous session summary:
 3. **Display phase header** before resuming work
 4. **Re-read context.md** for project state
 
+## TypeScript Code Review
+
+**CRITICAL:** TypeScript files in `src/invar/node_tools/` are PART of this project and MUST be reviewed.
+
+When reviewing TypeScript code (*.js, *.ts files):
+
+### TypeScript-Specific Checklist
+
+- [ ] **Error Handling:** All `JSON.parse()` calls wrapped in try/catch
+- [ ] **Null Safety:** Optional property access uses `?.` or explicit null checks
+- [ ] **I/O Safety:** All `fs.readFileSync()` wrapped in try/catch
+- [ ] **Race Conditions:** No TOCTOU (check-then-use) patterns with file operations
+- [ ] **Type Guards:** Runtime type checks for external inputs
+- [ ] **Resource Cleanup:** No resource leaks in language services
+
+### Common TypeScript Vulnerabilities
+
+| Pattern | Risk | Fix |
+|---------|------|-----|
+| `JSON.parse(input)` | Crashes on invalid JSON | `try { JSON.parse() } catch { error }` |
+| `obj.prop.method()` | TypeError if prop is null | `obj.prop?.method()` or null check |
+| `if (exists(f)) read(f)` | TOCTOU race condition | `try { read(f) } catch { handle }` |
+| `fs.readFileSync()` in loop | One error kills all | Wrap each call in try/catch |
+
+### Integration Points
+
+TypeScript files interact with Python via:
+- **Subprocess:** Node.js process spawned by Python wrapper
+- **JSON protocol:** Structured input/output via stdin/stdout
+- **Path safety:** All file paths validated in Python layer before subprocess
+
 <!--/invar:user-->
 
 ---

{invar_tools-1.11.0 → invar_tools-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.11.0
+Version: 1.12.0
 Summary: AI-native software engineering tools with design-by-contract verification
 Project-URL: Homepage, https://github.com/tefx/invar
 Project-URL: Documentation, https://github.com/tefx/invar#readme
@@ -24,6 +24,7 @@ Requires-Python: >=3.11
 Requires-Dist: crosshair-tool>=0.0.60
 Requires-Dist: hypothesis>=6.0
 Requires-Dist: invar-runtime>=1.0
+Requires-Dist: jedi>=0.19
 Requires-Dist: jinja2>=3.0
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: mcp>=1.0
@@ -146,7 +147,19 @@ Guard passed.
 
 ## 🚀 Quick Start
 
-> **Language Support:** Python (full), TypeScript (verification via Zod contracts).
+### Tool × Language Support
+
+| Tool | Python | TypeScript | Notes |
+|------|--------|------------|-------|
+| `invar guard` | ✅ Full | ⚠️ Partial | TS: tsc + eslint + vitest |
+| `invar sig` | ✅ Full | ✅ Full | TS: TS Compiler API |
+| `invar map` | ✅ Full | ✅ Full | TS: With reference counts |
+| `invar refs` | ✅ Full | ✅ Full | Cross-file reference finding |
+| `invar doc *` | ✅ Full | ✅ Full | Language-agnostic |
+
+**TypeScript Notes:**
+- Requires Node.js + TypeScript (most TS projects have these)
+- Falls back to regex parser if Node.js unavailable
 
 ### 📦 Two Packages, Different Purposes
 
@@ -303,14 +316,17 @@ function average(items: number[]): number {
 
 ### ✅ Solution 2: Multi-Layer Verification
 
-Guard provides fast feedback. Agent sees errors, fixes immediately:
+Guard provides fast feedback **on top of standard type checking**. Agent sees errors, fixes immediately:
 
 | Layer | Tool | Speed | What It Catches |
 |-------|------|-------|-----------------|
+| **Type Check*** | mypy (Python) / tsc (TypeScript) | ~1s | Type errors, missing annotations |
 | **Static** | Guard rules | ~0.5s | Architecture violations, missing contracts |
-| **Doctest** | pytest | ~2s | Example correctness |
-| **Property** | Hypothesis | ~10s | Edge cases via random inputs |
-| **Symbolic** | CrossHair | ~30s | Mathematical proof of contracts |
+| **Doctest** | pytest / vitest | ~2s | Example correctness |
+| **Property** | Hypothesis / fast-check | ~10s | Edge cases via random inputs |
+| **Symbolic** | CrossHair / (TS: N/A) | ~30s | Mathematical proof of contracts |
+
+<sup>* Requires separate installation: `pip install mypy` or configure TypeScript in your project</sup>
 
 ```
 ┌──────────┐   ┌───────────┐   ┌───────────┐   ┌────────────┐
@@ -525,7 +541,7 @@ Cursor users get full verification via MCP:
 |----------------|---------|----------|
 | `INVAR.md` | Protocol for AI agents | Required |
 | `.invar/` | Config, context, examples | Required |
-| `.pre-commit-config.yaml` | Verification before commit | Optional |
+| `.pre-commit-config.yaml` | Verification before commit (Ruff, mypy*, Guard) | Optional |
 | `src/core/`, `src/shell/` | Recommended structure | Optional |
 | `CLAUDE.md` | Agent instructions | Claude Code |
 | `.claude/skills/` | Workflow + extension skills | Claude Code |
@@ -534,6 +550,8 @@ Cursor users get full verification via MCP:
 | `.mcp.json` | MCP server config | Claude Code |
 | `AGENT.md` | Universal agent instructions | Other agents |
 
+<sup>* mypy hook included in `.pre-commit-config.yaml` but requires: `pip install mypy`</sup>
+
 **Note:** If `pyproject.toml` exists, Guard configuration goes there as `[tool.invar.guard]` instead of `.invar/config.toml`.
 
 **Recommended structure:**

{invar_tools-1.11.0 → invar_tools-1.12.0}/README.md

@@ -103,7 +103,19 @@ Guard passed.
 
 ## 🚀 Quick Start
 
-> **Language Support:** Python (full), TypeScript (verification via Zod contracts).
+### Tool × Language Support
+
+| Tool | Python | TypeScript | Notes |
+|------|--------|------------|-------|
+| `invar guard` | ✅ Full | ⚠️ Partial | TS: tsc + eslint + vitest |
+| `invar sig` | ✅ Full | ✅ Full | TS: TS Compiler API |
+| `invar map` | ✅ Full | ✅ Full | TS: With reference counts |
+| `invar refs` | ✅ Full | ✅ Full | Cross-file reference finding |
+| `invar doc *` | ✅ Full | ✅ Full | Language-agnostic |
+
+**TypeScript Notes:**
+- Requires Node.js + TypeScript (most TS projects have these)
+- Falls back to regex parser if Node.js unavailable
 
 ### 📦 Two Packages, Different Purposes
 
@@ -260,14 +272,17 @@ function average(items: number[]): number {
 
 ### ✅ Solution 2: Multi-Layer Verification
 
-Guard provides fast feedback. Agent sees errors, fixes immediately:
+Guard provides fast feedback **on top of standard type checking**. Agent sees errors, fixes immediately:
 
 | Layer | Tool | Speed | What It Catches |
 |-------|------|-------|-----------------|
+| **Type Check*** | mypy (Python) / tsc (TypeScript) | ~1s | Type errors, missing annotations |
 | **Static** | Guard rules | ~0.5s | Architecture violations, missing contracts |
-| **Doctest** | pytest | ~2s | Example correctness |
-| **Property** | Hypothesis | ~10s | Edge cases via random inputs |
-| **Symbolic** | CrossHair | ~30s | Mathematical proof of contracts |
+| **Doctest** | pytest / vitest | ~2s | Example correctness |
+| **Property** | Hypothesis / fast-check | ~10s | Edge cases via random inputs |
+| **Symbolic** | CrossHair / (TS: N/A) | ~30s | Mathematical proof of contracts |
+
+<sup>* Requires separate installation: `pip install mypy` or configure TypeScript in your project</sup>
 
 ```
 ┌──────────┐   ┌───────────┐   ┌───────────┐   ┌────────────┐
@@ -482,7 +497,7 @@ Cursor users get full verification via MCP:
 |----------------|---------|----------|
 | `INVAR.md` | Protocol for AI agents | Required |
 | `.invar/` | Config, context, examples | Required |
-| `.pre-commit-config.yaml` | Verification before commit | Optional |
+| `.pre-commit-config.yaml` | Verification before commit (Ruff, mypy*, Guard) | Optional |
 | `src/core/`, `src/shell/` | Recommended structure | Optional |
 | `CLAUDE.md` | Agent instructions | Claude Code |
 | `.claude/skills/` | Workflow + extension skills | Claude Code |
@@ -491,6 +506,8 @@ Cursor users get full verification via MCP:
 | `.mcp.json` | MCP server config | Claude Code |
 | `AGENT.md` | Universal agent instructions | Other agents |
 
+<sup>* mypy hook included in `.pre-commit-config.yaml` but requires: `pip install mypy`</sup>
+
 **Note:** If `pyproject.toml` exists, Guard configuration goes there as `[tool.invar.guard]` instead of `.invar/config.toml`.
 
 **Recommended structure:**