@mrclrchtr/supi-code-intelligence 1.7.0 → 1.8.0

package/src/substrates/lsp-adapter.ts

@@ -0,0 +1,197 @@
+// LSP semantic substrate adapter — wraps SessionLspService into SemanticSubstrate.
+
+import type { CodeLocation, CodePosition } from "@mrclrchtr/supi-core/types";
+import {
+  getSessionLspService,
+  type SessionLspService,
+  waitForSessionLspService,
+} from "@mrclrchtr/supi-lsp/api";
+import type { CodeSymbol, SemanticSubstrate } from "./types.ts";
+
+const SYMBOL_KIND_NAMES: Record<number, string> = {
+  1: "File",
+  2: "Module",
+  3: "Namespace",
+  4: "Package",
+  5: "Class",
+  6: "Method",
+  7: "Property",
+  8: "Field",
+  9: "Constructor",
+  10: "Enum",
+  11: "Interface",
+  12: "Function",
+  13: "Variable",
+  14: "Constant",
+  15: "String",
+  16: "Number",
+  17: "Boolean",
+  18: "Array",
+  19: "Object",
+  20: "Key",
+  21: "Null",
+  22: "EnumMember",
+  23: "Struct",
+  24: "Event",
+  25: "Operator",
+  26: "TypeParameter",
+};
+
+function symbolKindName(kind: number): string {
+  return SYMBOL_KIND_NAMES[kind] ?? "Unknown";
+}
+
+/**
+ * Create a SemanticSubstrate backed by the session-scoped LSP service.
+ *
+ * The adapter handles service acquisition, readiness waiting, and
+ * normalizes LSP types into CodeLocation / CodeSymbol.
+ */
+export function createSemanticSubstrate(cwd: string): SemanticSubstrate {
+  return {
+    references: async (filePath, position) =>
+      withService(cwd, (lsp) =>
+        lsp.references(filePath, position).then((locs) =>
+          locs
+            ? locs.map((l: { uri: string; range: { start: CodePosition; end: CodePosition } }) => ({
+                uri: l.uri,
+                range: l.range,
+              }))
+            : null,
+        ),
+      ),
+
+    implementation: async (filePath, position) =>
+      withService(cwd, async (lsp) => {
+        const result = await lsp.implementation(filePath, position);
+        if (!result) return null;
+        const list: Array<Record<string, unknown>> = Array.isArray(result) ? result : [result];
+        return list.map(toCodeLocation).filter(Boolean) as CodeLocation[];
+      }),
+
+    documentSymbols: async (filePath) =>
+      withService(cwd, async (lsp) => {
+        const symbols = await lsp.documentSymbols(filePath);
+        if (!symbols) return null;
+        return flattenDocumentSymbols(symbols, filePath);
+      }),
+
+    workspaceSymbols: async (query) =>
+      withService(cwd, async (lsp) => {
+        const results = await lsp.workspaceSymbol(query);
+        if (!results) return null;
+        return results.map(toCodeSymbol);
+      }),
+  };
+}
+
+// ── Acquisition ─────────────────────────────────────────────────────
+
+async function acquire(cwd: string): Promise<SessionLspService | null> {
+  const state = getSessionLspService(cwd);
+  if (state.kind === "ready") return state.service;
+  if (state.kind === "pending") {
+    const waited = await waitForSessionLspService(cwd, 250);
+    return waited.kind === "ready" ? waited.service : null;
+  }
+  return null;
+}
+
+async function withService<T>(
+  cwd: string,
+  fn: (lsp: SessionLspService) => Promise<T | null>,
+): Promise<T | null> {
+  const lsp = await acquire(cwd);
+  if (!lsp) return null;
+  return fn(lsp);
+}
+
+// ── Type mapping ────────────────────────────────────────────────────
+
+function toCodeLocation(loc: Record<string, unknown>): CodeLocation | null {
+  const uri = loc.uri ?? loc.targetUri;
+  // LocationLink has targetSelectionRange (precise symbol span) and targetRange (full range).
+  // Location has range only. Prefer the most precise: targetSelectionRange > targetRange > range.
+  const range = loc.targetSelectionRange ?? loc.targetRange ?? loc.range;
+  if (typeof uri !== "string") return null;
+  if (!range || typeof range !== "object") return null;
+  const r = range as { start: Record<string, unknown>; end: Record<string, unknown> };
+  const start = r.start;
+  const end = r.end;
+  if (!start || !end) return null;
+  return {
+    uri,
+    range: {
+      start: { line: (start.line as number) ?? 0, character: (start.character as number) ?? 0 },
+      end: { line: (end.line as number) ?? 0, character: (end.character as number) ?? 0 },
+    },
+  };
+}
+
+function flattenDocumentSymbols(
+  symbols: Array<{
+    name: string;
+    kind: number;
+    selectionRange?: { start: { line: number; character: number } };
+    children?: Array<unknown>;
+  }>,
+  filePath: string,
+  container: string | null = null,
+): CodeSymbol[] {
+  const result: CodeSymbol[] = [];
+
+  for (const sym of symbols) {
+    const start =
+      sym.selectionRange?.start ??
+      (sym as { location?: { range?: { start: { line: number; character: number } } } }).location
+        ?.range?.start;
+    if (!start) continue;
+
+    result.push({
+      name: sym.name,
+      kind: symbolKindName(sym.kind),
+      file: filePath,
+      line: start.line + 1,
+      character: start.character + 1,
+      container,
+    });
+
+    if (Array.isArray(sym.children) && sym.children.length > 0) {
+      result.push(
+        ...flattenDocumentSymbols(
+          sym.children as Array<{
+            name: string;
+            kind: number;
+            selectionRange?: { start: { line: number; character: number } };
+            children?: Array<unknown>;
+          }>,
+          filePath,
+          sym.name,
+        ),
+      );
+    }
+  }
+
+  return result;
+}
+
+function toCodeSymbol(sym: {
+  name: string;
+  kind: number;
+  containerName?: string | null;
+  location?: {
+    uri: string;
+    range?: { start: { line: number; character: number } };
+  } | null;
+}): CodeSymbol {
+  const uri = sym.location?.uri ?? "";
+  const start = sym.location?.range?.start;
+  return {
+    name: sym.name,
+    kind: symbolKindName(sym.kind),
+    file: uri.startsWith("file://") ? decodeURIComponent(uri.slice(7)) : uri,
+    line: start ? start.line + 1 : 0,
+    character: start ? start.character + 1 : 0,
+    container: sym.containerName ?? null,
+  };
+}

package/src/substrates/tree-sitter-adapter.ts

@@ -0,0 +1,173 @@
+// Tree-sitter structural substrate adapter — wraps TreeSitterService into StructuralSubstrate.
+
+import {
+  createTreeSitterSession,
+  getSessionTreeSitterService,
+} from "@mrclrchtr/supi-tree-sitter/api";
+import type {
+  CalleesData,
+  ExportData,
+  ImportData,
+  NodeAtData,
+  OutlineData,
+  StructuralResult,
+  StructuralSubstrate,
+} from "./types.ts";
+
+/**
+ * Create a StructuralSubstrate backed by the tree-sitter service.
+ *
+ * Reuses the shared session-scoped service when available, falling back to
+ * a short-lived owned session (disposed after the operation).
+ */
+export function createStructuralSubstrate(cwd: string): StructuralSubstrate {
+  return {
+    calleesAt: (file, line, character) =>
+      withSession(cwd, (s) => s.calleesAt(file, line, character)).then(mapResult(mapCallees)),
+
+    exports: (file) => withSession(cwd, (s) => s.exports(file)).then(mapResult(mapExports)),
+
+    outline: (file) => withSession(cwd, (s) => s.outline(file)).then(mapResult(mapOutline)),
+
+    imports: (file) => withSession(cwd, (s) => s.imports(file)).then(mapResult(mapImports)),
+
+    nodeAt: (file, line, character) =>
+      withSession(cwd, (s) => s.nodeAt(file, line, character)).then(mapResult(mapNodeAt)),
+  };
+}
+
+// ── Session acquisition ─────────────────────────────────────────────
+
+async function withSession<T>(
+  cwd: string,
+  fn: (session: {
+    calleesAt: (f: string, l: number, c: number) => Promise<unknown>;
+    exports: (f: string) => Promise<unknown>;
+    outline: (f: string) => Promise<unknown>;
+    imports: (f: string) => Promise<unknown>;
+    nodeAt: (f: string, l: number, c: number) => Promise<unknown>;
+  }) => Promise<T>,
+): Promise<T> {
+  const current = getSessionTreeSitterService(cwd);
+  if (current.kind === "ready") {
+    return fn(current.service);
+  }
+  const session = createTreeSitterSession(cwd);
+  try {
+    return await fn(session);
+  } finally {
+    session.dispose();
+  }
+}
+
+// ── Generic result mapper ───────────────────────────────────────────
+
+function mapResult<T>(mapData: (data: unknown) => T): (raw: unknown) => StructuralResult<T> {
+  return (raw) => {
+    const r = raw as { kind: string; data?: unknown };
+    if (r.kind === "success") {
+      return { kind: "success", data: mapData(r.data) };
+    }
+    return raw as StructuralResult<T>;
+  };
+}
+
+// ── Mapping helpers (unpack nested `range` into flat fields) ────────
+
+type RangeLike = {
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+};
+
+function takeRange(r: RangeLike): {
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+} {
+  return {
+    startLine: r.startLine,
+    startCharacter: r.startCharacter,
+    endLine: r.endLine,
+    endCharacter: r.endCharacter,
+  };
+}
+
+function mapExports(data: unknown): ExportData[] {
+  const items = data as Array<{
+    name: string;
+    kind: string;
+    range: RangeLike;
+    moduleSpecifier?: string;
+  }>;
+  return items.map((item) => ({
+    name: item.name,
+    kind: item.kind,
+    ...takeRange(item.range),
+    moduleSpecifier: item.moduleSpecifier,
+  }));
+}
+
+function mapOutline(data: unknown): OutlineData[] {
+  const items = data as Array<{
+    name: string;
+    kind: string;
+    range: RangeLike;
+    children?: unknown[];
+  }>;
+  return items.map((item) => ({
+    name: item.name,
+    kind: item.kind,
+    ...takeRange(item.range),
+    children: item.children ? mapOutline(item.children) : undefined,
+  }));
+}
+
+function mapImports(data: unknown): ImportData[] {
+  const items = data as Array<{
+    moduleSpecifier: string;
+    range: RangeLike;
+  }>;
+  return items.map((item) => ({
+    moduleSpecifier: item.moduleSpecifier,
+    ...takeRange(item.range),
+  }));
+}
+
+function mapNodeAt(data: unknown): NodeAtData {
+  const d = data as {
+    type: string;
+    range: RangeLike;
+    text: string;
+    ancestry: Array<{ type: string; range: RangeLike }>;
+  };
+  return {
+    type: d.type,
+    ...takeRange(d.range),
+    text: d.text,
+    ancestry: d.ancestry.map((a) => ({
+      type: a.type,
+      ...takeRange(a.range),
+    })),
+  };
+}
+
+function mapCallees(data: unknown): CalleesData {
+  const d = data as {
+    enclosingScope: { name: string; range: RangeLike };
+    callees: Array<{ name: string; range: RangeLike }>;
+  };
+  return {
+    enclosingScope: {
+      name: d.enclosingScope.name,
+      startLine: d.enclosingScope.range.startLine,
+      endLine: d.enclosingScope.range.endLine,
+    },
+    callees: d.callees.map((c) => ({
+      name: c.name,
+      startLine: c.range.startLine,
+    })),
+  };
+}

package/src/substrates/types.ts

@@ -0,0 +1,113 @@
+// Substrate interfaces and value types for code-intelligence's
+// semantic (LSP) and structural (tree-sitter) adapters.
+//
+// Interfaces are consumer-side: supi-code-intelligence defines what it needs.
+// Concrete adapters wrap supi-lsp / supi-tree-sitter and map their types.
+
+import type { CodeLocation, CodePosition } from "@mrclrchtr/supi-core/types";
+
+// ── Discriminated result union (mirrors TreeSitterResult, package-agnostic) ──
+
+export type StructuralResult<T> =
+  | { kind: "success"; data: T }
+  | { kind: "unsupported-language"; file: string; message: string }
+  | { kind: "file-access-error"; file: string; message: string }
+  | { kind: "validation-error"; message: string }
+  | { kind: "runtime-error"; message: string };
+
+// ── Flat value types (normalized from tree-sitter nested range shapes) ──
+
+export interface OutlineData {
+  name: string;
+  kind: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  children?: OutlineData[];
+}
+
+export interface ExportData {
+  name: string;
+  kind: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  moduleSpecifier?: string;
+}
+
+export interface ImportData {
+  moduleSpecifier: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+}
+
+export interface NodeAtData {
+  type: string;
+  startLine: number;
+  startCharacter: number;
+  endLine: number;
+  endCharacter: number;
+  text: string;
+  ancestry: Array<{
+    type: string;
+    startLine: number;
+    startCharacter: number;
+    endLine: number;
+    endCharacter: number;
+  }>;
+}
+
+export interface CalleesData {
+  enclosingScope: { name: string; startLine: number; endLine: number };
+  callees: Array<{ name: string; startLine: number }>;
+}
+
+export interface CodeSymbol {
+  name: string;
+  kind: string;
+  file: string;
+  /** 1-based display line. */
+  line: number;
+  /** 1-based display character. */
+  character: number;
+  container?: string | null;
+}
+
+// ── Substrate interfaces ──────────────────────────────────────────────
+
+/** Semantic (LSP-backed) code analysis operations. */
+export interface SemanticSubstrate {
+  /** Find all references to a symbol at the given position. */
+  references(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
+
+  /** Find implementations of a symbol at the given position. */
+  implementation(filePath: string, position: CodePosition): Promise<CodeLocation[] | null>;
+
+  /** Get document-level symbols for a file. */
+  documentSymbols(filePath: string): Promise<CodeSymbol[] | null>;
+
+  /** Search workspace symbols by name. */
+  workspaceSymbols(query: string): Promise<CodeSymbol[] | null>;
+}
+
+/** Structural (tree-sitter-backed) code analysis operations. */
+export interface StructuralSubstrate {
+  /** Extract outgoing calls from the enclosing scope at a position. */
+  calleesAt(file: string, line: number, character: number): Promise<StructuralResult<CalleesData>>;
+
+  /** Extract exported declarations from a file. */
+  exports(file: string): Promise<StructuralResult<ExportData[]>>;
+
+  /** Extract top-level declarations from a file. */
+  outline(file: string): Promise<StructuralResult<OutlineData[]>>;
+
+  /** Extract import declarations from a file. */
+  imports(file: string): Promise<StructuralResult<ImportData[]>>;
+
+  /** Get the syntax node at a 1-based position. */
+  nodeAt(file: string, line: number, character: number): Promise<StructuralResult<NodeAtData>>;
+}