lsp-intelligence 0.3.0 → 0.3.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "lsp-intelligence-marketplace",
+  "description": "Official marketplace for the lsp-intelligence Claude Code plugin",
+  "owner": {
+    "name": "Peri Levy"
+  },
+  "plugins": [
+    {
+      "name": "lsp-intelligence",
+      "description": "Local code intelligence for TypeScript/JavaScript — Find code, explain failures, guard API contracts, simulate changes.",
+      "source": {
+        "source": "npm",
+        "package": "lsp-intelligence",
+        "version": "0.3.2"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "lsp-intelligence",
+  "description": "Local code intelligence for TypeScript/JavaScript — Find code, explain failures, guard API contracts, simulate changes.",
+  "version": "0.3.2",
+  "mcpServers": {
+    "lsp-intelligence": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/launch.mjs"]
+    }
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,75 @@
+# LSP Intelligence — Agent Instructions
+
+Local code intelligence for real engineering workflows. **Find** code, **explain** failures, **guard** API contracts.
+
+> **Note:** The first query in a new session may take a few seconds while the TypeScript engine warms up. The workspace index is persisted and loads instantly on repeat sessions. Subsequent queries are 100-300ms.
+
+## Primary tools
+
+| Workflow | Tool | Skill |
+|----------|------|-------|
+| Find code by intent | `find_code` | `/find` |
+| Find structural patterns | `find_pattern` | — |
+| Trace root cause of an error | `root_cause_trace` | `/why` |
+| Check API contract changes | `api_guard` | `/api-check` |
+| Full pre-merge verification | `verify_changes` | `/verify` |
+
+## When to use LSP tools
+
+| You want to... | Instead of... | Use |
+|----------------|---------------|-----|
+| Find where an API is used | `grep "symbolName"` | `find_code` or `find_references` |
+| Find implementations by concept | Multiple greps | `find_code` (auto-routes to behavior search) |
+| Find structural patterns | Manual code reading | `find_code` or `find_pattern` |
+| Find config/route/flag definitions | Grepping JSON/YAML | `find_code` with config focus |
+| Jump to a definition | Reading imports | `goto_definition` |
+| Understand a type signature | Reading the source file | `hover` |
+| See what a file contains | `read` on the whole file | `outline` |
+| Know what breaks if you change something | Manual tracing | `impact_trace` |
+| Prepare context for a coding task | Reading 5-10 files | `gather_context` |
+| Check for type errors after editing | Running `tsc` | `live_diagnostics` |
+| Understand a TypeScript error | Reading error + source | `explain_error` / `/why` |
+| Review what you changed semantically | `git diff` | `semantic_diff` |
+
+## When to still use grep
+
+- Searching for string literals in comments or logs
+- Searching non-code files where LSP has no coverage
+- Simple text matching where code-aware ranking isn't needed
+
+## Workflow patterns
+
+### Before modifying code
+1. `outline` — understand structure without reading everything
+2. `impact_trace` — know the blast radius
+3. `gather_context` — get only relevant code, token-budgeted
+4. `find_test_files` — know which tests to update
+
+### While implementing
+- `hover` to check types before writing
+- `auto_import` to get import paths right
+- `goto_definition` to navigate to source
+- `find_references` to verify you're not missing usages
+
+### After editing
+- `live_diagnostics` on every file you changed
+- If errors: `explain_error` or `/why` for root cause
+- `semantic_diff` before committing
+- `api_guard` or `/api-check` if exports changed
+
+## Symbol-name input
+
+All tools accept symbol names directly: `{ "symbol": "UserService" }`. You don't need file paths and line numbers. Only fall back to position-based input when the symbol name is ambiguous across packages.
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/find <query>` | Guided code search with follow-up actions |
+| `/why <file:line>` | Root cause trace with evidence chain |
+| `/api-check` | API contract guard with semver verdict |
+| `/verify` | Full pre-merge: types + API + test coverage |
+| `/check <files>` | Type check with error explanations |
+| `/impact <symbol>` | Transitive usage trace |
+| `/context <symbols>` | Token-budgeted context extraction |
+| `/diff` | Semantic diff with blast radius |

package/README.md

@@ -36,52 +36,35 @@ Or get a file overview without reading it:
 
 ## Installation
 
-Requires **Node.js 20+**. Dependencies are installed automatically on first session start.
-
-### Option 1: CLI (recommended)
+Requires **Node.js 20+**.
 
-Add the marketplace and install the plugin:
+### Plugin install (recommended)
 
-```shell
+```
 /plugin marketplace add perilevy/lsp-intelligence
-/plugin install lsp-intelligence@lsp-intelligence
+/plugin install lsp-intelligence
 /reload-plugins
 ```
 
-### Option 2: Project configuration (team setup)
+That's it. The plugin installs the MCP server, skills, hooks, and agent context in one step. No separate runtime install, no manual `.mcp.json` edits.
+
+### MCP server only (advanced)
 
-Add to your project's `.claude/settings.json` — any teammate who clones the repo gets it automatically:
+For non-Claude Code agents or manual MCP configuration:
 
 ```json
 {
-  "extraKnownMarketplaces": {
+  "mcpServers": {
     "lsp-intelligence": {
-      "source": {
-        "source": "github",
-        "repo": "perilevy/lsp-intelligence"
-      }
+      "command": "npx",
+      "args": ["-y", "lsp-intelligence"],
+      "env": { "LSP_WORKSPACE_ROOT": "${workspaceFolder}" }
     }
-  },
-  "enabledPlugins": {
-    "lsp-intelligence@lsp-intelligence": true
   }
 }
 ```
 
-### Option 3: npm source
-
-Use npm source in `marketplace.json` for version pinning and built-in dependency resolution:
-
-```json
-{
-  "name": "lsp-intelligence",
-  "source": {
-    "source": "npm",
-    "package": "lsp-intelligence",
-    "version": "0.2.0"
-  }
-}
-```
+This gives you the raw MCP tools only — no skills or hooks.
 
 ## Capabilities
 
@@ -260,10 +243,7 @@ Add to your `.mcp.json`:
   "mcpServers": {
     "lsp": {
       "command": "npx",
-      "args": ["-y", "lsp-intelligence"],
-      "env": {
-        "LSP_WORKSPACE_ROOT": "${CLAUDE_PROJECT_DIR}"
-      }
+      "args": ["-y", "lsp-intelligence"]
     }
   }
 }
@@ -286,10 +266,7 @@ Then in `.mcp.json`:
   "mcpServers": {
     "lsp": {
       "command": "node",
-      "args": ["/absolute/path/to/lsp-intelligence/dist/index.js"],
-      "env": {
-        "LSP_WORKSPACE_ROOT": "${CLAUDE_PROJECT_DIR}"
-      }
+      "args": ["/absolute/path/to/lsp-intelligence/dist/index.js"]
     }
   }
 }

package/hooks/hooks.json

@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const v = process.version.slice(1).split('.').map(Number); if(v[0]<20){console.error('lsp-intelligence requires Node 20+, found '+process.version);process.exit(1)}\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-check.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/post-edit-check.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Post-edit hook: only emit diagnostic prompt for TS/JS files in the workspace.
+# Reads tool input from stdin as JSON.
+FILE_PATH=$(cat /dev/stdin | node -e "process.stdin.setEncoding('utf8');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(d).tool_input.file_path||'')}catch{}})")
+
+# Skip non-TS/JS files
+case "$FILE_PATH" in
+  *.ts|*.tsx|*.js|*.jsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip files outside the workspace (e.g. editing other projects)
+WORKSPACE="${LSP_WORKSPACE_ROOT:-$PWD}"
+case "$FILE_PATH" in
+  "$WORKSPACE"*) ;;
+  *) exit 0 ;;
+esac
+
+echo "A TypeScript/JavaScript file was edited: $FILE_PATH
+1. Run live_diagnostics on it to check for new type errors
+2. If errors are found, run explain_error on each to provide fix suggestions
+3. If the file contains export statements, note that the exported API may have changed — consider running api_guard if the user is working on a cross-package change
+4. If no errors, say nothing"

package/package.json

@@ -1,26 +1,39 @@
 {
   "name": "lsp-intelligence",
-  "version": "0.3.0",
-  "description": "LSP-powered code intelligence MCP server for AI coding agents",
+  "version": "0.3.2",
+  "description": "Local code intelligence for TypeScript/JavaScript — Find code, explain failures, guard API contracts, simulate changes.",
   "type": "module",
   "bin": {
     "lsp-intelligence": "./dist/index.js"
   },
   "files": [
     "dist",
+    ".claude-plugin",
+    "skills",
+    "hooks",
+    "scripts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "clean": "rm -rf dist",
     "build": "rm -rf dist && tsc",
-    "prepack": "npm run clean && npm run build",
+    "prepublishOnly": "rm -rf dist && tsc",
     "start": "tsx src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "bench": "tsx benchmarks/run.ts",
-    "bench:e2e": "tsx benchmarks/run.ts --e2e"
+    "bench:e2e": "tsx benchmarks/run.ts --e2e",
+    "bench:api-guard": "tsx benchmarks/run-api-guard.ts",
+    "bench:root-cause": "tsx benchmarks/run-root-cause.ts",
+    "test:overlay": "tsx benchmarks/test-overlay.ts",
+    "test:program": "tsx benchmarks/test-program.ts",
+    "test:typestate": "tsx benchmarks/test-typestate.ts",
+    "test:simulate": "tsx benchmarks/test-simulate.ts",
+    "test:workflows": "tsx benchmarks/test-workflows.ts",
+    "test:cache": "tsx benchmarks/test-cache.ts"
   },
   "dependencies": {
     "@ast-grep/napi": "^0.42.0",
@@ -43,5 +56,6 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha1.ac34549e6aa8e7ead463a7407e1c7390f61a6610"
 }

package/scripts/launch.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * lsp-intelligence plugin launcher.
+ *
+ * Runs from the plugin-installed package directory.
+ * Fast: no network, no install, no dependency resolution.
+ * Just finds dist/index.js and spawns it.
+ *
+ * LSP_WORKSPACE_ROOT defaults to process.cwd() which Claude Code sets to
+ * the current workspace when starting MCP servers.
+ */
+import { spawn } from 'child_process';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverPath = join(__dirname, '..', 'dist', 'index.js');
+
+const child = spawn(process.execPath, [serverPath], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    LSP_WORKSPACE_ROOT: process.env.LSP_WORKSPACE_ROOT ?? process.cwd(),
+  },
+});
+
+child.on('exit', (code) => process.exit(code ?? 0));
+process.on('SIGTERM', () => child.kill('SIGTERM'));
+process.on('SIGINT', () => child.kill('SIGINT'));

package/skills/api-check/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: api-check
+description: Check for breaking API changes — what exports changed, who consumes them, and semver impact
+argument-hint: [--base <branch>] [--scope changed|all]
+---
+
+# API Guard
+
+Check the public API surface for breaking changes before merging.
+
+## Steps
+
+1. Parse the user's input:
+   - If `--base <branch>`: use that as the comparison base
+   - If `--scope all`: check all files, not just changed ones
+   - Default: changed files only, base auto-detected from main/master
+
+2. Run `api_guard` with the parsed arguments
+
+3. Present the result:
+   - **Semver verdict**: MAJOR (breaking), MINOR (additive), PATCH (internal)
+   - **Breaking changes**: list with structural diffs and consumer counts
+   - **Risky changes**: changes that might break consumers
+   - **Safe changes**: additive or internal-only
+
+4. For each breaking change, highlight:
+   - What exactly changed (enum member added, param now required, etc.)
+   - How many cross-package consumers are affected
+   - Sample consumer files
+
+5. If breaking changes exist:
+   - Suggest running `/impact` on the most impactful symbol
+   - Ask if the breaking change is intentional
+   - Offer to run `/check` on consumer files to verify they compile

package/skills/check/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: check
+description: Run type checking on files — catch errors immediately after edits
+argument-hint: [file-path ...]
+---
+
+# Type Check
+
+Check for type errors after edits and explain any issues found.
+
+## Steps
+
+1. Determine which files to check:
+   - If the user specified file paths, use those
+   - Otherwise, run `git diff --name-only` in the workspace to find changed TypeScript files
+   - If no git changes found, ask the user which files to check
+2. Run `live_diagnostics` on each file
+3. For each file:
+   - If clean: report "no errors"
+   - If errors found: run `explain_error` on each error location to get actionable context
+4. Present a summary:
+   - **Clean files**: list them briefly
+   - **Files with errors**: show each error with the explanation and suggested fix
+   - **Total**: "X files checked, Y errors found"
+5. If errors were found, offer to fix them

package/skills/context/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: context
+description: Gather token-budgeted context for a coding task — only the code you need, nothing you don't
+argument-hint: <symbol-name or task description> [--tokens <number>]
+---
+
+# Gather Context
+
+Build a minimal, complete context for the task the user described.
+
+## Steps
+
+1. Identify entry symbols:
+   - If the user provided a symbol name, use it directly
+   - If the user described a task (e.g. "add a new status type"), extract likely symbol names from the description and use `workspace_symbols` to resolve them
+2. Run `gather_context` with the entry symbols. Set `max_tokens`:
+   - If the user passed `--tokens <number>`, use that value
+   - Otherwise, consider your remaining context window — the default is 100k but reduce it if the conversation is already long
+3. Present the result to the user organized as:
+   - **Must modify**: files with full code bodies — these need changes
+   - **Verify only**: files shown as signatures — check these still work after changes
+   - **Skip**: files listed by name — update these later (usually tests)
+4. Ask the user: "Does this look right? Should I include more files or adjust the scope?"
+5. If the user wants more detail on a specific file, run `outline` on it

package/skills/diff/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: diff
+description: Semantic diff — see what symbols changed and their blast radius before committing
+argument-hint: [--base <branch>]
+---
+
+# Semantic Diff
+
+Analyze the current branch's changes semantically — not just lines changed, but which symbols changed and what might break.
+
+## Steps
+
+1. Determine the base branch:
+   - If the user passed `--base <branch>`, use it
+   - Otherwise, try `git rev-parse --verify main` — if it exists, use `main`
+   - If not, try `master`
+   - If neither exists, ask the user for the base branch
+   Run `semantic_diff` with the resolved base
+2. For each changed symbol with risk 🔴 (HIGH — >10 references):
+   - Run `find_test_files` to check if tests exist for it
+   - If no tests: flag as "untested change — high risk"
+3. Present results:
+   - **High risk** (🔴): symbols with many references — review carefully
+   - **Medium risk** (🟡): symbols with some references — verify
+   - **Safe** (🟢): symbols with no external references — low risk
+4. If any high-risk changes lack tests, suggest running `/impact` on those symbols
+5. If everything looks clean, confirm: "Changes look safe to commit"

package/skills/find/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: find
+description: Search code by natural language — finds implementations, API usage, structural patterns, configs, and likely roots
+argument-hint: <query>
+---
+
+# Code Search
+
+Find code using natural language. Automatically routes to the right search backend.
+
+## Steps
+
+1. Parse the user's query:
+   - If the user provided a query argument, use it directly
+   - Otherwise, ask what they're looking for
+
+2. Call `find_code` with the query:
+   - Let focus default to `auto`
+   - If the user mentioned a specific directory or package, pass it in `paths`
+   - If the user wants test files included, set `include_tests: true`
+   - If the user is debugging search quality, set `debug: true`
+
+3. Interpret the results based on confidence:
+
+   **High confidence** (strong matches from multiple sources):
+   - Show the top 3 candidates with file path, symbol name, and why it matched
+   - For the #1 candidate, show the snippet and enclosing function/component
+   - If the result has graph evidence, mention what was promoted/demoted
+   - Automatically call `gather_context` on the #1 candidate's symbol to provide ready-to-use context
+
+   **Medium confidence** (reasonable matches, single source):
+   - Show top 3 candidates with evidence
+   - Suggest the user refine their query or try a more specific term
+   - Offer to run `find_pattern` if the query has a structural shape
+   - Note any warnings (scope capped, partial results)
+
+   **Low confidence** (weak or no matches):
+   - Explain what was searched and why it didn't match well
+   - Check the IR: suggest using the exact function name if only NL tokens were used
+   - Offer to try `find_pattern` with an AST pattern instead
+   - If scope was capped, mention it and suggest narrowing with `paths`
+
+4. Offer follow-up actions:
+   - "Want me to read the top result?" → Read the file
+   - "Want more context?" → Call `gather_context` on the top candidate's symbol
+   - "What calls this?" → Call `call_hierarchy` on the symbol
+   - "What breaks if I change this?" → Call `impact_trace` on the symbol
+   - "Is the API safe?" → Call `api_guard` on the file
+
+5. If `stats.partialResult` is true or `warnings` is non-empty, mention it clearly so the user knows the search was incomplete.
+
+## Examples
+
+| Query | What happens |
+|-------|-------------|
+| `/find useEffect` | Identifier search → all useEffect call sites |
+| `/find useEffect that returns cleanup conditionally` | Structural → useEffect with conditional cleanup |
+| `/find useEffect that sets state based on previous state` | React recipe → functional state updater pattern |
+| `/find where do we validate permissions` | Behavior → permission validation entrypoints |
+| `/find where is the feature flag configured` | Config → JSON/YAML/env entries |
+| `/find where is this endpoint defined` | Route → route definitions + handler code |
+| `/find switch without default` | Structural → switch statements missing default |
+| `/find retry logic` in packages/core | Scoped behavior search |

package/skills/impact/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: impact
+description: Trace the blast radius of changing a symbol — find every file, reference, and affected test
+argument-hint: <symbol-name> [--depth <number>]
+---
+
+# Impact Analysis
+
+Analyze the full impact of changing the symbol the user specified.
+
+## Steps
+
+1. Run `impact_trace` with the user's symbol name. If the user passed `--depth <number>`, use that as `max_depth`; otherwise default to 3. If it returns no results, run `workspace_symbols` with the same query to suggest similar names — the user may have a typo or the symbol may live in a non-TS file.
+2. Run `find_test_files` with the same symbol to identify tests that need updating
+3. Present a summary:
+   - **Severity**: LOW (< 5 refs), MEDIUM (5-20 refs), HIGH (> 20 refs)
+   - **Direct references**: files that import/call the symbol directly
+   - **Transitive references**: files affected through type aliases or re-exports
+   - **Affected tests**: test/spec/stories files that reference the symbol
+4. If severity is HIGH, suggest running `gather_context` on the most affected files before proceeding
+5. If the user wants to continue, offer to run `outline` on the files they'll need to modify

package/skills/verify/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: verify
+description: Full pre-merge verification — diagnostics, API contract, test coverage, verdict
+argument-hint: [--base <branch>]
+---
+
+# Verify Changes
+
+Full pre-commit/pre-PR verification in one command. Orchestrates diagnostics, API contract analysis, and test coverage into a single structured verdict.
+
+## Steps
+
+1. Call `verify_changes` with the user's base branch (if specified):
+   - If `--base <branch>` provided, pass it
+   - Otherwise, let the tool auto-detect the merge base
+
+2. Present the result in this order:
+
+   **Changed files** — list what was modified
+
+   **Type errors** — if `totalErrors > 0`:
+   - Show each file with its error count
+   - Show the first 3 errors per file with line and message
+   - Offer to run `/why` on the first error for root cause
+
+   **API changes** — if `api` is not null:
+   - Show semver verdict: MAJOR / MINOR / PATCH
+   - If breaking > 0: list breaking changes with details
+   - If risky > 0: list risky changes
+   - Offer to run `/api-check` for full details
+
+   **Test gaps** — if any `testGaps` have `hasTests: false`:
+   - List untested high-risk symbols with reference counts
+   - Offer to run `/impact <symbol>` for blast radius
+
+   **Verdict** — show the final verdict prominently:
+   - "safe to merge" — all clear
+   - "needs attention" — breaking API changes or untested high-risk symbols
+   - "has errors" — type errors must be fixed first
+
+3. If there are warnings, show them at the bottom.
+
+4. Offer follow-up actions based on verdict:
+   - **has errors**: "Want me to fix the errors?" or `/why <file:line>`
+   - **needs attention**: "Want me to check the breaking changes?" or `/api-check`
+   - **safe to merge**: "Ready to commit?" or `/diff` to review
+
+## Examples
+
+| Command | What happens |
+|---------|-------------|
+| `/verify` | Auto-detect base, check all changed files |
+| `/verify --base main` | Compare against main branch |
+| `/verify --base develop` | Compare against develop branch |

package/skills/why/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: why
+description: Trace the root cause of a TypeScript error — find what declaration change actually broke it
+argument-hint: <file:line> or <file>
+---
+
+# Root Cause Trace
+
+Trace the root cause of a TypeScript error. Don't just fix the symptom — find what changed upstream.
+
+## Steps
+
+1. Parse the user's input:
+   - If `file:line` format: use both
+   - If just a file: let the tool find the first error
+   - If no input: check files edited in the current conversation for errors
+
+2. Run `root_cause_trace` with the file path and optional line
+
+3. Present the result:
+   - **The error**: what diagnostic, where
+   - **The root cause**: which declaration changed and why it caused this
+   - **Evidence chain**: definition → change → impact
+   - **Suggested fix**: if the tool provides one
+   - **Other candidates**: if the top result has low confidence
+
+4. If confidence is low, suggest:
+   - Running `/check` on related files to find more errors
+   - Running `/impact` on the suspected symbol to see full blast radius
+
+5. If the user wants to fix it, use `gather_context` on the root cause file to get the relevant code