lsp-intelligence 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peri Levy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# lsp-intelligence
+
+Type-aware code intelligence for AI agents — impact analysis, semantic diff, and context building via LSP.
+
+**25 MCP tools** across 5 layers — from basic navigation to "what breaks if I change this?" in one call.
+
+Currently supports **TypeScript and JavaScript** projects. The architecture supports other LSP servers — additional language support is planned.
+
+## Why this exists
+
+AI coding agents use `grep` to understand code. Grep finds text, not meaning. It can't follow types through aliases, can't distinguish imports from function calls, and returns false positives from comments and strings.
+
+`lsp-intelligence` gives agents the same code understanding that VS Code has — type-aware references, call hierarchies, impact analysis — via the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP).
+
+## Quick start
+
+After [installation](#installation), try in Claude Code:
+
+```
+"What breaks if I rename the UserService class?"
+```
+
+Under the hood, the agent calls:
+
+```json
+{ "tool": "impact_trace", "arguments": { "symbol": "UserService" } }
+```
+
+Or get a file overview without reading it:
+
+```json
+{ "tool": "outline", "arguments": { "file_path": "/workspace/src/services/auth.ts" } }
+```
+
+> All tools that accept `file_path` require absolute paths. The `LSP_WORKSPACE_ROOT` env var tells the engine where your project lives.
+
+## Capabilities
+
+### LSP vs text search
+
+| Query | Text search (grep) | lsp-intelligence |
+|-------|-------------------|-----------------|
+| Find all references to a function | Finds text matches | **Semantic references** — no false positives from comments or strings |
+| Find references to a type alias | ⚠️ Includes substring matches (e.g. `UserServiceConfig` matches `UserService`) | **Exact symbol resolution** — only true references |
+| Cross-package references in monorepo | ⚠️ Text matches only — includes false positives, can't distinguish import vs call vs type annotation | **Type-aware semantic references** across packages |
+
+### What agents can do with LSP that they can't with grep
+
+| Capability | Description |
+|-----------|-------------|
+| Follow type aliases | Trace through `ReturnType<typeof X>`, re-exports, and barrel files |
+| Go to definition | Jump to the actual source, not just a text match |
+| Call hierarchy | "Who calls this function?" / "What does this function call?" |
+| Type signatures | Get the full type signature without reading the implementation |
+| Impact analysis | "What breaks if I change this?" — one call, full answer |
+| Semantic diff | Git changes → which symbols changed → blast radius per symbol |
+| Context building | Trace an impact graph, extract only relevant code, token-budget the output |
+| Rename preview | See every file that would change before committing a rename |
+| Dead code detection | Find exports that nothing imports |
+| Auto-import | Resolve the correct import path for any symbol |
+
+### Performance
+
+Tested on a TypeScript monorepo (9 packages, ~200k LOC):
+
+| Metric | Value |
+|--------|-------|
+| Engine ready | ~10s (scales with repo size) |
+| Queries after warmup | 100-300ms |
+| 21 queries end-to-end | ~16s total |
+
+The engine initializes once per session and stays warm. Warmup includes spawning TypeScript Server and pre-opening all monorepo packages. Queries start as soon as the index is available — no fixed delay.
+
+## Tools
+
+### Layer 1: Primitives (14 tools)
+
+Direct LSP wrappers. Every tool accepts **symbol names** — agents never need to guess line numbers.
+
+| Tool | Description |
+|------|-------------|
+| `find_references` | Find every usage of a symbol across the codebase. Semantic, not text. |
+| `goto_definition` | Jump to where a symbol is defined. Follows imports and re-exports. |
+| `goto_type_definition` | Find the type that defines a variable. |
+| `hover` | Get full type signature and documentation. |
+| `find_implementations` | Find concrete implementations of an interface. |
+| `document_symbols` | List all symbols in a file. |
+| `workspace_symbols` | Search for symbols by name across the workspace. |
+| `call_hierarchy` | Trace incoming callers or outgoing callees. |
+| `type_hierarchy` | Explore supertypes and subtypes. |
+| `rename` | Preview a semantic rename across the codebase (dry-run by default). |
+| `diagnostics` | Get type errors and warnings for a file. |
+| `completions` | Code completion suggestions. |
+| `file_imports` | List all imports of a file. |
+| `file_exports` | List a file's public API including re-exports. |
+
+### Layer 2: Composites (6 tools)
+
+Combine multiple primitives into high-level operations.
+
+| Tool | Description |
+|------|-------------|
+| `inspect_symbol` | Hover + definition + references in one call. Full context about any symbol. |
+| `batch_query` | Look up multiple symbols at once. Saves round-trips when exploring. |
+| `impact_trace` | Follow a symbol through type aliases and re-exports to find ALL transitive usages. Answers **"what breaks if I change X?"** in one call. |
+| `semantic_diff` | Analyze git diff semantically: identify changed symbols and their blast radius. |
+| `find_test_files` | Find all test/spec/stories files that reference a symbol. |
+| `explain_error` | Turn a TypeScript error into actionable context: expected type, actual type, and fix suggestion. |
+
+### Layer 3: Context Engine (2 tools)
+
+Token-aware context building for agents.
+
+| Tool | Description |
+|------|-------------|
+| `outline` | File structure with type signatures — understand a file without reading it. |
+| `gather_context` | Trace impact graph from entry symbols, classify files as must-modify / verify-only / skip, return token-budgeted context. |
+
+### Layer 4: Live Intelligence (3 tools)
+
+Post-edit verification.
+
+| Tool | Description |
+|------|-------------|
+| `live_diagnostics` | Re-read a file after editing and check for new type errors. |
+| `find_unused_exports` | Find exported symbols with zero cross-package importers. |
+| `auto_import` | Resolve the correct import path for a symbol name. |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Layer 4: Live Intelligence              [state-mutating] │
+│   live_diagnostics, find_unused_exports, auto_import    │
+├─────────────────────────────────────────────────────────┤
+│ Layer 3: Context Engine                 [read-only]      │
+│   gather_context, outline                               │
+├─────────────────────────────────────────────────────────┤
+│ Layer 2: Composites                     [read-only]      │
+│   impact_trace, semantic_diff, inspect_symbol,          │
+│   batch_query, find_test_files, explain_error           │
+├─────────────────────────────────────────────────────────┤
+│ Layer 1: Primitives                     [read-only]      │
+│   find_references, hover, definition, call_hierarchy,   │
+│   type_hierarchy, rename, diagnostics, symbols, etc.    │
+├─────────────────────────────────────────────────────────┤
+│ Layer 0: LSP Engine                     [infrastructure]  │
+│   TypeScript Server spawn, monorepo preopen,            │
+│   symbol resolver, document manager                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+Each layer only depends on layers below it.
+
+### Monorepo Support
+
+Works with any monorepo structure out of the box:
+
+- `packages/`, `apps/`, `libs/`, `modules/`, `services/` directory conventions
+- `pnpm-workspace.yaml`
+- `package.json` workspaces (yarn, npm)
+
+At startup, the engine discovers all workspace packages and pre-opens one file per package. This triggers TypeScript Server to build configured projects for every package, enabling cross-package reference finding — a common challenge with LSP tooling in monorepos.
+
+### Symbol-Name Resolution
+
+Every tool accepts `{ symbol: "UserService" }` instead of requiring `{ file_path, line, column }`. The engine resolves names to positions via `workspace/symbol` with priority sorting. Agents never need to guess line numbers.
+
+## Installation
+
+Requires **Node.js 20+**.
+
+### Option 1: Claude Code plugin (recommended)
+
+Installs the MCP server, hooks, and skills (`/impact`, `/context`, `/check`) as a single package.
+
+```bash
+claude plugin add perilevy/lsp-intelligence
+```
+
+> The full experience — the agent gets code intelligence tools, guided workflows via skills, and automatic hooks.
+
+### Option 2: MCP server only
+
+For other AI agents (Copilot, Cursor, etc.) or if you only want the raw tools without hooks and skills.
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "lsp": {
+      "command": "npx",
+      "args": ["-y", "lsp-intelligence"],
+      "env": {
+        "LSP_WORKSPACE_ROOT": "${CLAUDE_PROJECT_DIR}"
+      }
+    }
+  }
+}
+```
+
+### Option 3: From source
+
+For contributors or debugging.
+
+```bash
+git clone https://github.com/perilevy/lsp-intelligence.git
+cd lsp-intelligence
+yarn install && yarn build
+```
+
+Then in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "lsp": {
+      "command": "node",
+      "args": ["/absolute/path/to/lsp-intelligence/dist/index.js"],
+      "env": {
+        "LSP_WORKSPACE_ROOT": "${CLAUDE_PROJECT_DIR}"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/perilevy/lsp-intelligence.git
+cd lsp-intelligence
+yarn install
+yarn build       # compile TypeScript → dist/
+yarn test        # vitest
+yarn typecheck   # TypeScript strict mode — no emit
+```
+
+### Testing
+
+Tests verify cross-package reference resolution, symbol-name lookup, type alias tracing, impact trace traversal, context building, and output formatting — all against a self-contained 3-package fixture monorepo at `test-fixtures/monorepo/`. No external dependencies needed.
+
+## Dependencies
+
+All dependencies are installed automatically. Under the hood: [`typescript-language-server`](https://github.com/typescript-language-server/typescript-language-server) for LSP, [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) for MCP, and supporting libraries from Microsoft. Uses your project's own TypeScript version.
+
+## License
+
+[MIT](LICENSE)

package/dist/engine/DocumentManager.d.ts

@@ -0,0 +1,20 @@
+import type { MessageConnection } from 'vscode-jsonrpc';
+import type { Diagnostic } from 'vscode-languageserver-protocol';
+export declare class DocumentManager {
+    private openDocs;
+    private diagnosticsCache;
+    /**
+     * Ensure a file is open in the LSP server. If already open, no-op.
+     * Returns the file content.
+     */
+    ensureOpen(filePath: string, connection: MessageConnection): Promise<string>;
+    /**
+     * Re-read a file from disk and send didChange. For live diagnostics after edits.
+     */
+    refreshFromDisk(filePath: string, connection: MessageConnection): Promise<string>;
+    getContent(uri: string): string | undefined;
+    isOpen(uri: string): boolean;
+    cacheDiagnostics(uri: string, diagnostics: Diagnostic[]): void;
+    getCachedDiagnostics(uri: string): Diagnostic[];
+    private detectLanguage;
+}

package/dist/engine/DocumentManager.js

@@ -0,0 +1,73 @@
+import * as fs from 'fs';
+import { pathToUri, uriToPath } from './positions.js';
+export class DocumentManager {
+    openDocs = new Map();
+    diagnosticsCache = new Map();
+    /**
+     * Ensure a file is open in the LSP server. If already open, no-op.
+     * Returns the file content.
+     */
+    async ensureOpen(filePath, connection) {
+        const uri = pathToUri(filePath);
+        const existing = this.openDocs.get(uri);
+        if (existing)
+            return existing.content;
+        const content = fs.readFileSync(uriToPath(uri), 'utf-8');
+        const languageId = this.detectLanguage(filePath);
+        const doc = { uri, version: 1, content, languageId };
+        this.openDocs.set(uri, doc);
+        connection.sendNotification('textDocument/didOpen', {
+            textDocument: {
+                uri,
+                languageId,
+                version: doc.version,
+                text: content,
+            },
+        });
+        return content;
+    }
+    /**
+     * Re-read a file from disk and send didChange. For live diagnostics after edits.
+     */
+    async refreshFromDisk(filePath, connection) {
+        const uri = pathToUri(filePath);
+        const content = fs.readFileSync(uriToPath(uri), 'utf-8');
+        const existing = this.openDocs.get(uri);
+        if (existing) {
+            existing.version++;
+            existing.content = content;
+            connection.sendNotification('textDocument/didChange', {
+                textDocument: { uri, version: existing.version },
+                contentChanges: [{ text: content }],
+            });
+        }
+        else {
+            await this.ensureOpen(filePath, connection);
+        }
+        return content;
+    }
+    getContent(uri) {
+        return this.openDocs.get(uri)?.content;
+    }
+    isOpen(uri) {
+        return this.openDocs.has(uri);
+    }
+    cacheDiagnostics(uri, diagnostics) {
+        this.diagnosticsCache.set(uri, diagnostics);
+    }
+    getCachedDiagnostics(uri) {
+        return this.diagnosticsCache.get(uri) ?? [];
+    }
+    detectLanguage(filePath) {
+        if (filePath.endsWith('.tsx'))
+            return 'typescriptreact';
+        if (filePath.endsWith('.ts'))
+            return 'typescript';
+        if (filePath.endsWith('.jsx'))
+            return 'javascriptreact';
+        if (filePath.endsWith('.js') || filePath.endsWith('.mjs') || filePath.endsWith('.cjs'))
+            return 'javascript';
+        return 'typescript';
+    }
+}
+//# sourceMappingURL=DocumentManager.js.map

package/dist/engine/DocumentManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentManager.js","sourceRoot":"","sources":["../../src/engine/DocumentManager.ts"],"names":[],"mappings":"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"}

package/dist/engine/LspEngine.d.ts

@@ -0,0 +1,50 @@
+import { DocumentManager } from './DocumentManager.js';
+import type { ResolvedLocation } from './types.js';
+export declare class LspEngine {
+    private connection;
+    private process;
+    private capabilities;
+    private _ready;
+    private _resolveReady;
+    private _rejectReady;
+    readonly docManager: DocumentManager;
+    readonly workspaceRoot: string;
+    gitAvailable: boolean;
+    constructor(workspaceRoot: string);
+    initialize(): Promise<void>;
+    /**
+     * Send an LSP request. Waits for engine to be ready first.
+     */
+    request<R>(method: string, params: unknown, timeoutMs?: number): Promise<R>;
+    /**
+     * Ensure a file is open and return its URI + content.
+     */
+    prepareFile(filePath: string): Promise<{
+        uri: string;
+        content: string;
+    }>;
+    /**
+     * Resolve a symbol name to a file position using workspace/symbol.
+     */
+    resolveSymbol(name: string, fileHint?: string): Promise<ResolvedLocation>;
+    /**
+     * Discover monorepo packages and open one file per package.
+     */
+    private preopenPackages;
+    /**
+     * Discover workspace packages from any monorepo structure.
+     * Supports: packages/, apps/, libs/, pnpm-workspace.yaml, lerna.json, rush.json
+     */
+    private discoverWorkspacePackages;
+    /**
+     * Build initializationOptions for typescript-language-server.
+     * Points tsserver.path to the consumer's TypeScript if available.
+     */
+    private buildInitOptions;
+    /**
+     * Resolve a binary — check bundled node_modules/.bin first, then global PATH.
+     */
+    private resolveBinary;
+    private findFirstTsFile;
+    shutdown(): Promise<void>;
+}