lsp-intelligence 0.2.1 → 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/dist/adapters/express/index.d.ts

@@ -0,0 +1,9 @@
+import type { IntelligenceAdapter } from '../types.js';
+/**
+ * Express/Fastify IntelligenceAdapter v2.
+ *
+ * Capabilities:
+ * - detect: route definition queries
+ * - graph.denylist: Express framework functions not useful as implementation roots
+ */
+export declare const expressAdapter: IntelligenceAdapter;

package/dist/adapters/express/index.js

@@ -0,0 +1,46 @@
+/**
+ * Express/Fastify IntelligenceAdapter v2.
+ *
+ * Capabilities:
+ * - detect: route definition queries
+ * - graph.denylist: Express framework functions not useful as implementation roots
+ */
+export const expressAdapter = {
+    id: 'express',
+    detect(ir) {
+        if (!ir.traits.routeLike)
+            return [];
+        const nlTokens = ir.nlTokens;
+        const recipes = [];
+        const isRouteDef = nlTokens.some(t => ['route', 'endpoint', 'handler', 'defined', 'registered', 'handled'].includes(t)) || ir.phrases.some(p => p.includes('is handled') || p.includes('is defined'));
+        if (isRouteDef) {
+            recipes.push({
+                id: 'express.route-definition',
+                adapter: 'express',
+                retrievers: ['route', 'behavior', 'regex'],
+                exactIdentifiers: [],
+                regexes: [
+                    { id: 'express-route', pattern: '(?:app|router)\\.(?:get|post|put|delete|patch|all|use)\\s*\\(', flags: 'gi' },
+                    { id: 'fastify-route', pattern: 'fastify\\.(?:get|post|put|delete|patch)\\s*\\(', flags: 'g' },
+                    { id: 'route-config', pattern: '(?:routes|endpoints)\\s*[:=]\\s*[\\[{]', flags: 'gi' },
+                ],
+                scoreBoost: 3,
+                reasons: ['Express adapter: route definition pattern'],
+            });
+        }
+        return recipes;
+    },
+    graph: {
+        denylist: [
+            // Express framework — not real implementation roots
+            'Router', 'express', 'use', 'listen', 'set',
+            'json', 'urlencoded', 'static', 'raw', 'text',
+            'next', // Express next() middleware callback
+            // Common Express middleware names
+            'cors', 'helmet', 'morgan', 'compression',
+            // Fastify framework
+            'fastify', 'register', 'addHook', 'addPlugin',
+        ],
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/express/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/express/index.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB;IACjD,EAAE,EAAE,SAAS;IAEb,MAAM,CAAC,EAAW;QAChB,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS;YAAE,OAAO,EAAE,CAAC;QAEpC,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;QAC7B,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CACnC,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CACjF,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;QAEhF,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,0BAA0B;gBAC9B,OAAO,EAAE,SAAS;gBAClB,UAAU,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC;gBAC1C,gBAAgB,EAAE,EAAE;gBACpB,OAAO,EAAE;oBACP,EAAE,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,+DAA+D,EAAE,KAAK,EAAE,IAAI,EAAE;oBAC9G,EAAE,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,gDAAgD,EAAE,KAAK,EAAE,GAAG,EAAE;oBAC9F,EAAE,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,wCAAwC,EAAE,KAAK,EAAE,IAAI,EAAE;iBACvF;gBACD,UAAU,EAAE,CAAC;gBACb,OAAO,EAAE,CAAC,2CAA2C,CAAC;aACvD,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,oDAAoD;YACpD,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK;YAC3C,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM;YAC7C,MAAM,EAAK,qCAAqC;YAChD,kCAAkC;YAClC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa;YACzC,oBAAoB;YACpB,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW;SAC9C;KACF;CACF,CAAC"}

package/dist/adapters/next/index.d.ts

@@ -0,0 +1,10 @@
+import type { IntelligenceAdapter } from '../types.js';
+/**
+ * Next.js IntelligenceAdapter v2.
+ *
+ * Capabilities:
+ * - detect: route/page/API queries routed to Next.js patterns
+ * - graph.denylist: Next.js framework functions not useful as impl roots
+ * - graph.rootHints: page/route handler patterns that ARE real roots
+ */
+export declare const nextAdapter: IntelligenceAdapter;

package/dist/adapters/next/index.js

@@ -0,0 +1,67 @@
+/**
+ * Next.js IntelligenceAdapter v2.
+ *
+ * Capabilities:
+ * - detect: route/page/API queries routed to Next.js patterns
+ * - graph.denylist: Next.js framework functions not useful as impl roots
+ * - graph.rootHints: page/route handler patterns that ARE real roots
+ */
+export const nextAdapter = {
+    id: 'next',
+    detect(ir) {
+        if (!ir.traits.routeLike && !ir.traits.reactLike)
+            return [];
+        const recipes = [];
+        const nlTokens = ir.nlTokens;
+        const isApiRoute = nlTokens.some(t => ['api', 'endpoint', 'handler'].includes(t)) ||
+            ir.phrases.some(p => p.includes('api route') || p.includes('api handler'));
+        const isPageRoute = nlTokens.some(t => ['page', 'route', 'layout'].includes(t)) ||
+            ir.phrases.some(p => p.includes('page component') || p.includes('app router'));
+        if (isApiRoute) {
+            recipes.push({
+                id: 'next.api-route',
+                adapter: 'next',
+                retrievers: ['route', 'identifier'],
+                exactIdentifiers: [],
+                regexes: [
+                    { id: 'next-api-handler', pattern: 'export\\s+(?:default\\s+)?(?:async\\s+)?function\\s+handler', flags: 'g' },
+                    { id: 'next-route-handler', pattern: 'export\\s+(?:async\\s+)?function\\s+(?:GET|POST|PUT|DELETE|PATCH)', flags: 'g' },
+                ],
+                scoreBoost: 3,
+                reasons: ['Next adapter: API route handler pattern'],
+            });
+        }
+        if (isPageRoute) {
+            recipes.push({
+                id: 'next.page-component',
+                adapter: 'next',
+                retrievers: ['identifier', 'route'],
+                exactIdentifiers: [],
+                regexes: [
+                    { id: 'next-page-export', pattern: 'export\\s+default\\s+(?:function|const|class)', flags: 'g' },
+                    { id: 'next-get-static', pattern: 'getStaticProps|getServerSideProps|generateStaticParams', flags: 'g' },
+                ],
+                scoreBoost: 2,
+                reasons: ['Next adapter: page component pattern'],
+            });
+        }
+        return recipes;
+    },
+    graph: {
+        denylist: [
+            // Next.js data fetching helpers — not implementation roots
+            'getStaticProps', 'getServerSideProps', 'getStaticPaths', 'generateStaticParams',
+            'generateMetadata', 'revalidate',
+            // Next.js router
+            'useRouter', 'usePathname', 'useSearchParams', 'useParams',
+            'redirect', 'notFound', 'permanentRedirect',
+            // Next.js image/link
+            'Image', 'Link', 'Script', 'Head',
+        ],
+        rootHints: [
+        // Functions that ARE real implementation roots in Next.js
+        // (future: boost these during graph expansion)
+        ],
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/next/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/next/index.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAwB;IAC9C,EAAE,EAAE,MAAM;IAEV,MAAM,CAAC,EAAW;QAChB,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS;YAAE,OAAO,EAAE,CAAC;QAE5D,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;QAE7B,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC/E,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;QAE7E,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC7E,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC;QAEjF,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,gBAAgB;gBACpB,OAAO,EAAE,MAAM;gBACf,UAAU,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC;gBACnC,gBAAgB,EAAE,EAAE;gBACpB,OAAO,EAAE;oBACP,EAAE,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE,6DAA6D,EAAE,KAAK,EAAE,GAAG,EAAE;oBAC9G,EAAE,EAAE,EAAE,oBAAoB,EAAE,OAAO,EAAE,mEAAmE,EAAE,KAAK,EAAE,GAAG,EAAE;iBACvH;gBACD,UAAU,EAAE,CAAC;gBACb,OAAO,EAAE,CAAC,yCAAyC,CAAC;aACrD,CAAC,CAAC;QACL,CAAC;QAED,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,qBAAqB;gBACzB,OAAO,EAAE,MAAM;gBACf,UAAU,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC;gBACnC,gBAAgB,EAAE,EAAE;gBACpB,OAAO,EAAE;oBACP,EAAE,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE,+CAA+C,EAAE,KAAK,EAAE,GAAG,EAAE;oBAChG,EAAE,EAAE,EAAE,iBAAiB,EAAE,OAAO,EAAE,wDAAwD,EAAE,KAAK,EAAE,GAAG,EAAE;iBACzG;gBACD,UAAU,EAAE,CAAC;gBACb,OAAO,EAAE,CAAC,sCAAsC,CAAC;aAClD,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,2DAA2D;YAC3D,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,sBAAsB;YAChF,kBAAkB,EAAE,YAAY;YAChC,iBAAiB;YACjB,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,WAAW;YAC1D,UAAU,EAAE,UAAU,EAAE,mBAAmB;YAC3C,qBAAqB;YACrB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;SAClC;QAED,SAAS,EAAE;QACT,0DAA0D;QAC1D,+CAA+C;SAChD;KACF;CACF,CAAC"}

package/dist/adapters/react/index.d.ts

@@ -0,0 +1,11 @@
+import type { IntelligenceAdapter } from '../types.js';
+/**
+ * React IntelligenceAdapter v2.
+ *
+ * Capabilities beyond the old SearchAdapter:
+ * - graph.denylist: React built-ins and HOC wrappers that should never be
+ *   promoted as implementation roots during graph expansion
+ * - graph.rootHints: patterns indicating actual component implementations
+ * - explain.causeHints: React-specific root cause patterns
+ */
+export declare const reactAdapter: IntelligenceAdapter;

package/dist/adapters/react/index.js

@@ -0,0 +1,133 @@
+const HOOK_PATTERN = /^use[A-Z]/;
+/**
+ * React IntelligenceAdapter v2.
+ *
+ * Capabilities beyond the old SearchAdapter:
+ * - graph.denylist: React built-ins and HOC wrappers that should never be
+ *   promoted as implementation roots during graph expansion
+ * - graph.rootHints: patterns indicating actual component implementations
+ * - explain.causeHints: React-specific root cause patterns
+ */
+export const reactAdapter = {
+    id: 'react',
+    // ---------------------------------------------------------------------------
+    // Search recipes (migrated from src/search/adapters/react.ts)
+    // ---------------------------------------------------------------------------
+    detect(ir) {
+        if (!ir.traits.reactLike)
+            return [];
+        const recipes = [];
+        const hookIds = ir.exactIdentifiers.filter((id) => HOOK_PATTERN.test(id));
+        const hasUseEffect = hookIds.includes('useEffect');
+        const hasUseMemo = hookIds.includes('useMemo');
+        const hasUseCallback = hookIds.includes('useCallback');
+        if (hasUseEffect && (ir.structuralPredicates.includes('conditional') ||
+            ir.structuralPredicates.includes('returns-cleanup') ||
+            ir.codeTokens.includes('cleanup'))) {
+            recipes.push({
+                id: 'react.useeffect.conditional-cleanup',
+                adapter: 'react',
+                retrievers: ['identifier', 'structural', 'regex'],
+                exactIdentifiers: ['useEffect'],
+                structuralPredicates: ['returns-cleanup', 'conditional'],
+                regexes: [
+                    { id: 'conditional-return', pattern: 'if\\s*\\([^)]*\\)\\s*\\{[^}]*return\\s*\\(\\)', flags: 'g' },
+                    { id: 'useeffect-cleanup', pattern: 'useEffect\\s*\\(\\s*\\(\\)\\s*=>\\s*\\{[\\s\\S]*?return\\s', flags: 'g' },
+                ],
+                scoreBoost: 3,
+                reasons: ['React adapter: useEffect + conditional cleanup pattern'],
+            });
+        }
+        if (hasUseEffect && ir.traits.previousStateLike) {
+            recipes.push({
+                id: 'react.useeffect.functional-state-updater',
+                adapter: 'react',
+                retrievers: ['identifier', 'structural', 'regex'],
+                exactIdentifiers: ['useEffect'],
+                structuralPredicates: ['functional-state-updater'],
+                regexes: [
+                    { id: 'functional-updater', pattern: 'set\\w+\\s*\\(\\s*(?:prev|current|existing|old)\\w*\\s*=>', flags: 'g' },
+                    { id: 'updater-arrow', pattern: 'set\\w+\\s*\\(\\s*\\w+\\s*=>\\s*\\w+', flags: 'g' },
+                ],
+                scoreBoost: 4,
+                reasons: ['React adapter: useEffect + functional state updater'],
+            });
+        }
+        if (hasUseMemo) {
+            recipes.push({
+                id: 'react.usememo.computation',
+                adapter: 'react',
+                retrievers: ['identifier'],
+                exactIdentifiers: ['useMemo'],
+                scoreBoost: 1,
+                reasons: ['React adapter: useMemo computation'],
+            });
+        }
+        if (hasUseCallback) {
+            recipes.push({
+                id: 'react.usecallback.memoized-handler',
+                adapter: 'react',
+                retrievers: ['identifier'],
+                exactIdentifiers: ['useCallback'],
+                scoreBoost: 1,
+                reasons: ['React adapter: useCallback memoized handler'],
+            });
+        }
+        if (hookIds.length > 0 && recipes.length === 0) {
+            recipes.push({
+                id: 'react.hook.general',
+                adapter: 'react',
+                retrievers: ['identifier'],
+                exactIdentifiers: hookIds,
+                scoreBoost: 0,
+                reasons: [`React adapter: general hook query for ${hookIds.join(', ')}`],
+            });
+        }
+        return recipes;
+    },
+    // ---------------------------------------------------------------------------
+    // Phase 2E: Graph intelligence — prevents React built-ins from appearing
+    // as implementation roots when users ask "what is the real implementation?"
+    // ---------------------------------------------------------------------------
+    graph: {
+        denylist: [
+            // React core hooks
+            'useState', 'useEffect', 'useMemo', 'useCallback', 'useRef', 'useContext',
+            'useReducer', 'useLayoutEffect', 'useImperativeHandle', 'useDebugValue',
+            'useTransition', 'useDeferredValue', 'useId', 'useSyncExternalStore',
+            // React component wrappers — not "real" implementations
+            'memo', 'forwardRef', 'lazy', 'Suspense',
+            // React factory functions
+            'createElement', 'createContext', 'createRef', 'createPortal',
+            'cloneElement', 'isValidElement', 'Children',
+            // React Router / Next.js HOCs
+            'withRouter', 'connect', 'inject',
+        ],
+        rootHints: [
+        // Functions named after common React patterns are often real implementations
+        // (used to boost these during graph expansion)
+        ],
+    },
+    // ---------------------------------------------------------------------------
+    // Phase 2E: Explain hints — React-specific root cause patterns
+    // ---------------------------------------------------------------------------
+    explain: {
+        causeHints: [
+            {
+                matchCode: '2345',
+                matchMessage: /props/i,
+                causeCategory: 'react-prop-type-mismatch',
+                hint: 'Check that the component\'s prop type interface matches what is being passed',
+                scoreBoost: 2,
+            },
+            {
+                matchCode: '2339',
+                matchMessage: /useEffect|useState|useMemo/i,
+                causeCategory: 'react-hook-return',
+                hint: 'The hook may not return what you expect — check the hook\'s return type definition',
+                scoreBoost: 2,
+            },
+        ],
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/adapters/react/index.js.map

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

package/dist/adapters/registry.d.ts

@@ -0,0 +1,22 @@
+import type { QueryIR, SearchRecipe } from '../search/types.js';
+import type { IntelligenceAdapter, AdapterCauseHint } from './types.js';
+/** Run all adapter detect() methods and return merged search recipes. */
+export declare function runAdapters(ir: QueryIR): SearchRecipe[];
+/** Get the merged denylist from all adapters. */
+export declare function getAdapterGraphDenylist(): Set<string>;
+/** Get all root hints from all adapters. */
+export declare function getAdapterRootHints(): string[];
+/** Get all cause hints from all adapters. */
+export declare function getAdapterCauseHints(): AdapterCauseHint[];
+/**
+ * Find the best cause hint for a given diagnostic code + message.
+ * Returns the highest-scoring matching hint, or null if none match.
+ */
+export declare function matchCauseHint(code: string | undefined, message: string): AdapterCauseHint | null;
+/** Run all adapter verify checks on the given files. */
+export declare function runAdapterVerifyChecks(filePaths: string[]): Array<{
+    adapterId: string;
+    issues: ReturnType<NonNullable<NonNullable<IntelligenceAdapter['verify']>['checks']>[number]['run']>;
+}>;
+export declare function getAdapter(id: string): IntelligenceAdapter | undefined;
+export declare function getAllAdapters(): readonly IntelligenceAdapter[];

package/dist/adapters/registry.js

@@ -0,0 +1,101 @@
+import { reactAdapter } from './react/index.js';
+import { nextAdapter } from './next/index.js';
+import { expressAdapter } from './express/index.js';
+// Config adapter remains in search/adapters until Phase 4 — wrapped here for compatibility
+import { configAdapter as legacyConfigAdapter } from '../search/adapters/config.js';
+/**
+ * Phase 2E — Central IntelligenceAdapter registry.
+ *
+ * This is the single source of truth for all adapter capabilities.
+ * The old src/search/adapters/registry.ts delegates here for backward compatibility.
+ */
+// Wrap the legacy configAdapter as an IntelligenceAdapter for inclusion
+const configAdapterCompat = {
+    id: 'config',
+    detect: (ir) => legacyConfigAdapter.detect(ir),
+};
+const ADAPTERS = [
+    reactAdapter,
+    nextAdapter,
+    expressAdapter,
+    configAdapterCompat,
+];
+// ---------------------------------------------------------------------------
+// Search recipes (backward-compatible with old SearchAdapter.detect())
+// ---------------------------------------------------------------------------
+/** Run all adapter detect() methods and return merged search recipes. */
+export function runAdapters(ir) {
+    const recipes = [];
+    for (const adapter of ADAPTERS) {
+        if (adapter.detect) {
+            recipes.push(...adapter.detect(ir));
+        }
+    }
+    return recipes;
+}
+// ---------------------------------------------------------------------------
+// Graph intelligence
+// ---------------------------------------------------------------------------
+/** Get the merged denylist from all adapters. */
+export function getAdapterGraphDenylist() {
+    const merged = new Set();
+    for (const adapter of ADAPTERS) {
+        for (const symbol of adapter.graph?.denylist ?? []) {
+            merged.add(symbol);
+        }
+    }
+    return merged;
+}
+/** Get all root hints from all adapters. */
+export function getAdapterRootHints() {
+    return ADAPTERS.flatMap((a) => a.graph?.rootHints ?? []);
+}
+// ---------------------------------------------------------------------------
+// Explain intelligence
+// ---------------------------------------------------------------------------
+/** Get all cause hints from all adapters. */
+export function getAdapterCauseHints() {
+    return ADAPTERS.flatMap((a) => a.explain?.causeHints ?? []);
+}
+/**
+ * Find the best cause hint for a given diagnostic code + message.
+ * Returns the highest-scoring matching hint, or null if none match.
+ */
+export function matchCauseHint(code, message) {
+    const candidates = getAdapterCauseHints().filter((h) => {
+        if (h.matchCode && code !== h.matchCode)
+            return false;
+        if (h.matchMessage && !h.matchMessage.test(message))
+            return false;
+        return true;
+    });
+    if (candidates.length === 0)
+        return null;
+    return candidates.reduce((best, c) => c.scoreBoost > best.scoreBoost ? c : best);
+}
+// ---------------------------------------------------------------------------
+// Verify checks
+// ---------------------------------------------------------------------------
+/** Run all adapter verify checks on the given files. */
+export function runAdapterVerifyChecks(filePaths) {
+    const results = [];
+    for (const adapter of ADAPTERS) {
+        for (const check of adapter.verify?.checks ?? []) {
+            const issues = check.run(filePaths);
+            if (issues.length > 0) {
+                results.push({ adapterId: adapter.id, issues });
+            }
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Adapter access
+// ---------------------------------------------------------------------------
+export function getAdapter(id) {
+    return ADAPTERS.find((a) => a.id === id);
+}
+export function getAllAdapters() {
+    return ADAPTERS;
+}
+//# sourceMappingURL=registry.js.map

package/dist/adapters/registry.js.map

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