@mrclrchtr/supi-code-intelligence 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-intelligence",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi Code Intelligence extension — architecture briefs, caller/callee analysis, impact assessment, and pattern search for pi",
   "license": "MIT",
   "repository": {
@@ -19,9 +19,9 @@
     "src/**/*.ts"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-tree-sitter": "1.3.0",
-    "@mrclrchtr/supi-lsp": "1.3.0",
-    "@mrclrchtr/supi-core": "1.3.0"
+    "@mrclrchtr/supi-core": "1.4.0",
+    "@mrclrchtr/supi-lsp": "1.4.0",
+    "@mrclrchtr/supi-tree-sitter": "1.4.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core",
@@ -46,7 +46,10 @@
   },
   "pi": {
     "extensions": [
-      "./src/extension.ts"
+      "./src/extension.ts",
+      "node_modules/@mrclrchtr/supi-lsp/src/extension.ts",
+      "node_modules/@mrclrchtr/supi-core/src/extension.ts",
+      "node_modules/@mrclrchtr/supi-tree-sitter/src/extension.ts"
     ]
   },
   "main": "src/api.ts",

package/src/actions/affected-action.ts

@@ -2,12 +2,12 @@
 // biome-ignore-all lint/nursery/noExcessiveLinesPerFile: file-level and single-target affected flows share helpers to keep the blast-radius logic in one place
 
 import * as path from "node:path";
-import { getSessionLspService } from "@mrclrchtr/supi-lsp/api";
 import { buildArchitectureModel, findModuleForPath, getDependents } from "../architecture.ts";
 import {
   appendPrioritySignalsSection,
   summarizePrioritySignalsForFiles,
 } from "../prioritization-signals.ts";
+import { getSemanticService } from "../providers/semantic-provider.ts";
 import { resolveTarget } from "../resolve-target.ts";
 import {
   escapeRegex,
@@ -188,12 +188,12 @@ async function gatherReferences(
   params: ActionParams,
   cwd: string,
 ): Promise<{ refs: GatheredRef[]; confidence: ConfidenceMode; externalCount: number }> {
-  const lspState = getSessionLspService(cwd);
+  const lsp = await getSemanticService(cwd, { waitForReady: true });
   const refs: GatheredRef[] = [];
   let externalCount = 0;
 
-  if (lspState.kind === "ready") {
-    const lspRefs = await lspState.service.references(target.file, target.position);
+  if (lsp) {
+    const lspRefs = await lsp.references(target.file, target.position);
     if (lspRefs && lspRefs.length > 0) {
       const filtered = filterOutDeclaration(lspRefs, target.file, target.position);
       for (const ref of filtered) {

package/src/actions/brief-action.ts

@@ -2,9 +2,10 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
+import type { TreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
 import { buildArchitectureModel, findModuleForPath } from "../architecture.ts";
 import { generateFocusedBrief, generateProjectBrief } from "../brief.ts";
+import { withStructuralSession } from "../providers/structural-provider.ts";
 import { normalizePath } from "../search-helpers.ts";
 import type { ActionParams } from "../tool-actions.ts";
 import type { CodeIntelResult } from "../types.ts";
@@ -108,23 +109,21 @@ interface TreeSitterContextInput {
 
 async function addTreeSitterContext(input: TreeSitterContextInput): Promise<void> {
   const { lines, relPath, line1, char1, cwd } = input;
-  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
   try {
-    tsSession = createTreeSitterSession(cwd);
-    await addNodeContext(lines, tsSession, relPath, { line: line1, char: char1 });
-    await addOutlineContext(lines, tsSession, relPath, line1);
-    await addImportsContext(lines, tsSession, relPath);
-    await addExportsContext(lines, tsSession, relPath);
+    await withStructuralSession(cwd, async (tsSession) => {
+      await addNodeContext(lines, tsSession, relPath, { line: line1, char: char1 });
+      await addOutlineContext(lines, tsSession, relPath, line1);
+      await addImportsContext(lines, tsSession, relPath);
+      await addExportsContext(lines, tsSession, relPath);
+    });
   } catch {
     // Tree-sitter not available
-  } finally {
-    tsSession?.dispose();
   }
 }
 
 async function addNodeContext(
   lines: string[],
-  ts: ReturnType<typeof createTreeSitterSession>,
+  ts: TreeSitterSession,
   relPath: string,
   pos: { line: number; char: number },
 ): Promise<void> {
@@ -144,7 +143,7 @@ async function addNodeContext(
 
 async function addOutlineContext(
   lines: string[],
-  ts: ReturnType<typeof createTreeSitterSession>,
+  ts: TreeSitterSession,
   relPath: string,
   line1: number,
 ): Promise<void> {
@@ -183,7 +182,7 @@ function getOutlinePrefix(kind: string): string {
 
 async function addImportsContext(
   lines: string[],
-  ts: ReturnType<typeof createTreeSitterSession>,
+  ts: TreeSitterSession,
   relPath: string,
 ): Promise<void> {
   const result = await ts.imports(relPath);
@@ -201,7 +200,7 @@ async function addImportsContext(
 
 async function addExportsContext(
   lines: string[],
-  ts: ReturnType<typeof createTreeSitterSession>,
+  ts: TreeSitterSession,
   relPath: string,
 ): Promise<void> {
   const result = await ts.exports(relPath);

package/src/actions/callees-action.ts

@@ -3,7 +3,7 @@
 // extraction to @mrclrchtr/supi-tree-sitter/api.
 
 import * as path from "node:path";
-import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
+import { withStructuralSession } from "../providers/structural-provider.ts";
 import { resolveTarget } from "../resolve-target.ts";
 import { isResolvedTargetGroup } from "../semantic-action-helpers.ts";
 import type { ActionParams } from "../tool-actions.ts";
@@ -47,11 +47,11 @@ export async function executeCalleesAction(
   }
 
   const relPath = path.relative(cwd, target.file);
-  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
 
   try {
-    tsSession = createTreeSitterSession(cwd);
-    const result = await tsSession.calleesAt(relPath, target.displayLine, target.displayCharacter);
+    const result = await withStructuralSession(cwd, (tsSession) =>
+      tsSession.calleesAt(relPath, target.displayLine, target.displayCharacter),
+    );
 
     if (result.kind !== "success") {
       return {
@@ -63,7 +63,9 @@ export async function executeCalleesAction(
             scope: null,
             candidateCount: 0,
             omittedCount: 0,
-            nextQueries: ["Use `lsp` for type-aware analysis on this file"],
+            nextQueries: [
+              'Use `lsp_lookup` with `kind: "hover"` for type-aware analysis on this file',
+            ],
           },
         },
       };
@@ -95,7 +97,9 @@ export async function executeCalleesAction(
       scope: null,
       candidateCount: callees.length,
       omittedCount: Math.max(0, callees.length - (params.maxResults ?? 8)),
-      nextQueries: ["Use `lsp` for precise type information on callees"],
+      nextQueries: [
+        'Use `lsp_lookup` with `kind: "hover"` for precise type information on callees',
+      ],
     };
     return { content, details: { type: "search" as const, data: details } };
   } catch {
@@ -108,12 +112,12 @@ export async function executeCalleesAction(
           scope: null,
           candidateCount: 0,
           omittedCount: 0,
-          nextQueries: ["Use `lsp` for type-aware analysis on this file"],
+          nextQueries: [
+            'Use `lsp_lookup` with `kind: "hover"` for type-aware analysis on this file',
+          ],
         },
       },
     };
-  } finally {
-    tsSession?.dispose();
   }
 }
 
@@ -140,7 +144,7 @@ function formatCallees(
   }
   lines.push("");
   lines.push(
-    "_Structural analysis — may include unresolved or qualified names. Use `lsp` for precise type information._",
+    '_Structural analysis — may include unresolved or qualified names. Use `lsp_lookup` with `kind: "hover"` for precise type information._',
   );
   lines.push("");
   return lines.join("\n");

package/src/actions/callers-action.ts

@@ -1,7 +1,7 @@
 // Callers action — find call sites for a symbol.
 
 import * as path from "node:path";
-import { getSessionLspService } from "@mrclrchtr/supi-lsp/api";
+import { getSemanticService } from "../providers/semantic-provider.ts";
 import { resolveTarget } from "../resolve-target.ts";
 import {
   escapeRegex,
@@ -169,10 +169,10 @@ async function collectCallerRefs(
   params: ActionParams,
   cwd: string,
 ): Promise<CallerCollection> {
-  const lspState = getSessionLspService(cwd);
+  const lsp = await getSemanticService(cwd, { waitForReady: true });
 
-  if (lspState.kind === "ready") {
-    const refs = await lspState.service.references(target.file, target.position);
+  if (lsp) {
+    const refs = await lsp.references(target.file, target.position);
     if (refs && refs.length > 0) {
       const filtered = filterOutDeclaration(refs, target.file, target.position);
       const projectRefs: CallerRef[] = [];

package/src/actions/implementations-action.ts

@@ -1,7 +1,7 @@
 // Implementations action — find concrete implementations via LSP or heuristic.
 
 import * as path from "node:path";
-import { getSessionLspService } from "@mrclrchtr/supi-lsp/api";
+import { getSemanticService } from "../providers/semantic-provider.ts";
 import { resolveTarget } from "../resolve-target.ts";
 import {
   escapeRegex,
@@ -52,11 +52,11 @@ export async function executeImplementationsAction(
     };
   }
 
-  const lspState = getSessionLspService(cwd);
+  const lsp = await getSemanticService(cwd, { waitForReady: true });
   const relPath = path.relative(cwd, target.file);
 
-  if (lspState.kind === "ready") {
-    const impls = await lspState.service.implementation(target.file, target.position);
+  if (lsp) {
+    const impls = await lsp.implementation(target.file, target.position);
     if (impls) {
       const locations = Array.isArray(impls) ? impls : [impls];
       if (locations.length > 0) {

package/src/code-intelligence.ts

@@ -6,7 +6,7 @@ import type { BeforeAgentStartEventResult, ExtensionAPI } from "@earendil-works/
 import { Type } from "typebox";
 import { buildArchitectureModel } from "./architecture.ts";
 import { generateOverview } from "./brief.ts";
-import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
+import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
 import { type CodeIntelAction, executeAction } from "./tool-actions.ts";
 
 const OVERVIEW_CUSTOM_TYPE = "code-intelligence-overview";

package/src/pattern-structured.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
+import { withStructuralSession } from "./providers/structural-provider.ts";
 import type { ActionParams } from "./tool-actions.ts";
 
 export const STRUCTURED_PATTERN_FILE_CAP = 200;
@@ -42,31 +42,29 @@ export async function getStructuredPatternMatches(
     return matcher;
   }
 
-  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
   try {
-    tsSession = createTreeSitterSession(cwd);
-    const matches: StructuredMatch[] = [];
-    let timedOut = collected.timedOut;
-
-    for (const [index, file] of collected.files.entries()) {
-      if (Date.now() > deadline) {
-        collected.omittedCount += collected.files.length - index;
-        timedOut = true;
-        break;
+    return await withStructuralSession(cwd, async (tsSession) => {
+      const matches: StructuredMatch[] = [];
+      let timedOut = collected.timedOut;
+
+      for (const [index, file] of collected.files.entries()) {
+        if (Date.now() > deadline) {
+          collected.omittedCount += collected.files.length - index;
+          timedOut = true;
+          break;
+        }
+        const relFile = path.relative(cwd, file);
+        await collectMatchesForFile(matches, tsSession, relFile, params.kind, matcher);
       }
-      const relFile = path.relative(cwd, file);
-      await collectMatchesForFile(matches, tsSession, relFile, params.kind, matcher);
-    }
 
-    return {
-      matches,
-      omittedCount: timedOut ? Math.max(1, collected.omittedCount) : collected.omittedCount,
-      partialReason: timedOut ? "timeout" : collected.omittedCount > 0 ? "file-cap" : null,
-    };
+      return {
+        matches,
+        omittedCount: timedOut ? Math.max(1, collected.omittedCount) : collected.omittedCount,
+        partialReason: timedOut ? "timeout" : collected.omittedCount > 0 ? "file-cap" : null,
+      };
+    });
   } catch {
     return `No structured ${params.kind} search data available in \`${relScope}\`. Try omitting \`kind\` for plain text search.`;
-  } finally {
-    tsSession?.dispose();
   }
 }
 
@@ -74,7 +72,7 @@ export async function getStructuredPatternMatches(
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: kind-specific tree-sitter matching is clearest as one helper
 async function collectMatchesForFile(
   matches: StructuredMatch[],
-  tsSession: ReturnType<typeof createTreeSitterSession>,
+  tsSession: import("@mrclrchtr/supi-tree-sitter/api").TreeSitterSession,
   relFile: string,
   kind: StructuredPatternKind,
   matcher: (value: string) => boolean,

package/src/providers/semantic-provider.ts

@@ -0,0 +1,34 @@
+import {
+  getSessionLspService,
+  type SessionLspService,
+  type SessionLspServiceState,
+  waitForSessionLspService,
+} from "@mrclrchtr/supi-lsp/api";
+
+export interface SemanticProviderOptions {
+  waitForReady?: boolean;
+  timeoutMs?: number;
+}
+
+export const DEFAULT_SEMANTIC_WAIT_MS = 250;
+
+/** Acquire the current session-scoped LSP service, optionally waiting for startup. */
+export async function getSemanticService(
+  cwd: string,
+  options: SemanticProviderOptions = {},
+): Promise<SessionLspService | null> {
+  const state = await getSemanticServiceState(cwd, options);
+  return state.kind === "ready" ? state.service : null;
+}
+
+/** Read the current LSP service state with an optional short wait for readiness. */
+export async function getSemanticServiceState(
+  cwd: string,
+  options: SemanticProviderOptions = {},
+): Promise<SessionLspServiceState> {
+  const current = getSessionLspService(cwd);
+  if (!options.waitForReady || current.kind !== "pending") {
+    return current;
+  }
+  return waitForSessionLspService(cwd, options.timeoutMs ?? DEFAULT_SEMANTIC_WAIT_MS);
+}

package/src/providers/structural-provider.ts

@@ -0,0 +1,14 @@
+import { createTreeSitterSession, type TreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
+
+/** Run work against a short-lived Tree-sitter session and dispose it afterward. */
+export async function withStructuralSession<T>(
+  cwd: string,
+  fn: (session: TreeSitterSession) => Promise<T>,
+): Promise<T> {
+  const session = createTreeSitterSession(cwd);
+  try {
+    return await fn(session);
+  } finally {
+    session.dispose();
+  }
+}

package/src/target-resolution.ts

@@ -5,12 +5,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
-import {
-  getSessionLspService,
-  type Position,
-  type SessionLspService,
-} from "@mrclrchtr/supi-lsp/api";
-import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
+import { type Position, type SessionLspService, toLspPosition } from "@mrclrchtr/supi-lsp/api";
+import { getSemanticService, getSemanticServiceState } from "./providers/semantic-provider.ts";
+import { withStructuralSession } from "./providers/structural-provider.ts";
 import { escapeRegex, normalizePath } from "./search-helpers.ts";
 import { highestConfidence } from "./semantic-action-helpers.ts";
 import type { ConfidenceMode, DisambiguationCandidate } from "./types.ts";
@@ -46,7 +43,7 @@ export { normalizePath } from "./search-helpers.ts";
  * Convert 1-based public coordinates to 0-based LSP Position.
  */
 export function toZeroBased(line: number, character: number): Position {
-  return { line: line - 1, character: character - 1 };
+  return toLspPosition(line, character);
 }
 
 /**
@@ -146,16 +143,12 @@ export async function resolveSymbolTarget(
     exportedOnly?: boolean;
   },
 ): Promise<TargetResolutionResult> {
-  const lspState = getSessionLspService(cwd);
+  const lspState = await getSemanticServiceState(cwd, { waitForReady: true });
 
   if (lspState.kind === "ready") {
     return resolveSymbolViaLsp(symbol, cwd, lspState.service, options);
   }
 
-  if (lspState.kind === "pending") {
-    // In v1, we may wait for LSP. For now, try structural fallback.
-  }
-
   // Structural fallback via text search
   return resolveSymbolViaSearch(symbol, cwd, options);
 }
@@ -336,10 +329,10 @@ async function resolveFileTargetsViaLsp(
   cwd: string,
   structuralTargets: ResolvedTarget[] | null,
 ): Promise<ResolvedTarget[] | null> {
-  const lspState = getSessionLspService(cwd);
-  if (lspState.kind !== "ready") return null;
+  const lsp = await getSemanticService(cwd, { waitForReady: true });
+  if (!lsp) return null;
 
-  const symbols = await lspState.service.documentSymbols(resolvedFile);
+  const symbols = await lsp.documentSymbols(resolvedFile);
   if (!symbols || symbols.length === 0) {
     return structuralTargets;
   }
@@ -378,30 +371,28 @@ async function resolveFileTargetsViaTreeSitter(
   resolvedFile: string,
   cwd: string,
 ): Promise<ResolvedTarget[] | null> {
-  let tsSession: ReturnType<typeof createTreeSitterSession> | null = null;
   try {
-    tsSession = createTreeSitterSession(cwd);
-    const exportsResult = await tsSession.exports(relPath);
-    if (exportsResult.kind !== "success" || exportsResult.data.length === 0) {
-      return null;
-    }
+    return await withStructuralSession(cwd, async (tsSession) => {
+      const exportsResult = await tsSession.exports(relPath);
+      if (exportsResult.kind !== "success" || exportsResult.data.length === 0) {
+        return null;
+      }
 
-    return dedupeTargets(
-      exportsResult.data.map((record) =>
-        createResolvedTarget({
-          file: resolvedFile,
-          line: record.range.startLine,
-          character: record.range.startCharacter,
-          name: record.name,
-          kind: record.kind,
-          confidence: "structural",
-        }),
-      ),
-    );
+      return dedupeTargets(
+        exportsResult.data.map((record) =>
+          createResolvedTarget({
+            file: resolvedFile,
+            line: record.range.startLine,
+            character: record.range.startCharacter,
+            name: record.name,
+            kind: record.kind,
+            confidence: "structural",
+          }),
+        ),
+      );
+    });
   } catch {
     return null;
-  } finally {
-    tsSession?.dispose();
   }
 }
 

package/src/tool/guidance.ts

@@ -0,0 +1,21 @@
+// Prompt guidance and tool description for the code_intel tool.
+
+export const toolDescription = `Code intelligence tool — codebase orientation, semantic relationships, impact analysis, and scoped search.
+
+Actions: brief, callers, callees, implementations, affected, pattern, index.
+
+Use code_intel to localize relevant files before precise drill-down: summarize a project/package/file, find callers/callees/implementations, estimate blast radius, or search within a scope. Prefer lsp_lookup, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_refactor, and lsp_recover for semantic drill-down once the target is known; use tree_sitter for exact syntax and read/rg once you know the file. line and character are 1-based and require file. pattern is literal unless regex is true; kind supports definition, export, or import. Relative paths resolve from cwd, and leading @ on path/file is stripped.`;
+
+export const promptGuidelines = [
+  'Use code_intel with `action: "brief"` for a project, package, directory, file, or anchored-position brief before opening more files.',
+  'Use code_intel with `action: "index"` for a project map, top-level directories, language mix, or landmark files.',
+  'Use code_intel with `action: "callers"` or `action: "implementations"` to find who invokes a symbol or which concrete types implement a declaration.',
+  'Use code_intel with `action: "callees"` for outgoing calls from a function or method at a known `file`, `line`, and `character`.',
+  'Use code_intel with `action: "affected"` before edits for blast radius, downstream modules, risk, and likely follow-up checks or tests.',
+  'Use code_intel with `action: "pattern"` for bounded search within a path; `pattern` is literal by default, set `regex: true` for regex, and use `kind: "definition" | "export" | "import"` for structured search.',
+  "Use code_intel with `file`, `line`, and `character` for anchored positions; do not pair `line` or `character` with `path`.",
+  "Use code_intel first when the area is not yet localized; switch to lsp_lookup, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_refactor, or lsp_recover for semantic drill-down once code_intel narrows the target.",
+];
+
+export const promptSnippet =
+  "code_intel — codebase orientation, callers/callees, blast radius, and scoped search before file drill-down";