@remnic/coding-graph 9.3.759

package/src/lsp/resolution.ts

@@ -0,0 +1,483 @@
+/**
+ * LSP resolution pass — upgrades Phase A heuristic edges with real
+ * definition-lookup results from language servers.
+ *
+ * Two halves (issue #1555 step 4):
+ *
+ *   1. **Planner** (pure): `planLspUpgrades(unresolvedCallSites, budget)`
+ *      decides which call sites to query and in what order. Pure function —
+ *      no side effects, no I/O. Deterministic output for deterministic input.
+ *
+ *   2. **Executor**: sends `textDocument/didOpen` + `textDocument/definition`
+ *      for each planned request via the LSP client, maps returned locations
+ *      back to graph nodes by file + half-open span containment (rule 35),
+ *      and applies edge upgrades transactionally per batch. A mid-batch
+ *      failure leaves zero partial upgrades (rule 25 — tested).
+ *
+ * Budgets (issue #1555): `maxRequestsPerRun` caps the worst case. Remaining
+ * call sites keep their Phase A resolution. Everything degrades to Phase A
+ * results with a tagged degradation surfaced in index_status.
+ *
+ * Files whose ingest failed are excluded (rule 44 — the executor never
+ * queries for a file that isn't in the store).
+ */
+
+import path from "node:path";
+
+import type { CodingGraphLanguage } from "@remnic/core";
+
+import type { LspClient } from "./client.js";
+import { uriToPath } from "./client.js";
+import type { LspDegradation } from "./degradation.js";
+import {
+  buildLineOffsetMap,
+  byteOffsetToPosition,
+  positionToByteOffset,
+  type LineOffsetMap,
+} from "./byte-position.js";
+import type { LspLocation } from "./types.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Input types — what the resolution pass consumes
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * A call site that Phase A left unresolved or at low confidence. The
+ * resolution pass will query the LSP server for its definition.
+ */
+export interface UnresolvedCallSite {
+  /** Repo-relative file path of the CALLER (the file containing the call). */
+  readonly filePath: string;
+  readonly language: CodingGraphLanguage;
+  /** Full file content — needed for byte↔position conversion. */
+  readonly content: string;
+  /** Byte offset of the callee name in the source (for the definition query position). */
+  readonly calleeByteOffset: number;
+  /** The callee name as extracted by Phase A (for logging/debugging). */
+  readonly calleeName: string;
+  /** The caller's qualified name (source node for the edge). */
+  readonly srcQualifiedName: string;
+}
+
+/**
+ * A planned LSP definition request — the planner's output. Each request
+ * targets one call site at one position in one file.
+ */
+export interface PlannedLspRequest {
+  readonly filePath: string;
+  readonly language: CodingGraphLanguage;
+  readonly content: string;
+  readonly calleeName: string;
+  readonly srcQualifiedName: string;
+  /** LSP position derived from calleeByteOffset via line-offset map. */
+  readonly position: { readonly line: number; readonly character: number };
+}
+
+/**
+ * The planner's budget — how many requests can be sent this run.
+ */
+export interface LspBudget {
+  readonly maxRequests: number;
+}
+
+/**
+ * Result of the planner — the requests to send, plus how many call sites
+ * were deferred due to budget exhaustion.
+ */
+export interface PlanResult {
+  readonly requests: readonly PlannedLspRequest[];
+  readonly budgetExhausted: number;
+}
+
+/**
+ * A location that the LSP server returned, mapped to a byte offset in
+ * a known file.
+ */
+export interface ResolvedLocation {
+  readonly filePath: string;
+  readonly startByte: number;
+  readonly endByte: number;
+}
+
+/**
+ * Result of the resolution pass.
+ */
+export interface ResolutionResult {
+  /** Edges upgraded from heuristic → lsp with resolved dst node. */
+  readonly upgraded: number;
+  /** LSP returned no location or the location didn't map to an indexed node. */
+  readonly unresolved: number;
+  /** Call sites skipped because maxRequestsPerRun was reached. */
+  readonly budgetExhausted: number;
+  /** Degradation if the pass could not run (server crashed, protocol error). */
+  readonly degradation?: LspDegradation;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Node-location lookup — the seam between LSP locations and graph nodes.
+// Implemented by the caller (the store-backed resolution executor) so
+// the planner stays pure and testable without a database.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Look up a graph node by file path + byte span containment (rule 35 —
+ * half-open). Returns the node's qualified name if exactly one node's
+ * span contains the byte offset, or null if none/ambiguous.
+ *
+ * The executor provides this closure backed by the GraphStore; tests
+ * inject a mock.
+ */
+export type NodeLocator = (
+  filePath: string,
+  byteOffset: number,
+) => string | null;
+
+/**
+ * Context for mapping an LSP location to a graph node. Provides the
+ * caller's file path and content (for same-file definitions), plus
+ * optional workspace-root normalization and cross-file content resolution.
+ */
+export interface MapLocationContext {
+  /** Repo-relative path of the caller file. */
+  readonly callerFilePath: string;
+  /** Full content of the caller file. */
+  readonly callerContent: string;
+  /** Workspace root for normalizing absolute LSP URIs to repo-relative paths. */
+  readonly workspaceRoot?: string;
+  /** Resolve content for a target file path (repo-relative). */
+  readonly resolveContent?: (filePath: string) => string | null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Planner — pure function, no side effects
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Plan which call sites to resolve via LSP. Pure — deterministic output
+ * for deterministic input. Orders requests by file path then byte offset
+ * for predictable, reviewable batches (rule 38 — byte-stable ordering).
+ *
+ * Budget enforcement: at most `budget.maxRequests` requests are planned.
+ * Excess call sites are counted in `budgetExhausted` so the caller can
+ * surface the degradation.
+ */
+export function planLspUpgrades(
+  callSites: readonly UnresolvedCallSite[],
+  budget: LspBudget,
+): PlanResult {
+  // Sort for deterministic ordering (rule 38): by file path, then byte offset.
+  const sorted = [...callSites].sort(
+    (a, b) =>
+      a.filePath.localeCompare(b.filePath) ||
+      a.calleeByteOffset - b.calleeByteOffset,
+  );
+
+  const max = Math.max(0, budget.maxRequests);
+  const planned = sorted.slice(0, max);
+  const exhausted = sorted.length - planned.length;
+
+  // Pre-compute line-offset maps per unique file to avoid recomputation
+  // in the executor. Group by content identity (same content → same map).
+  const maps = new Map<string, LineOffsetMap>();
+  const requests: PlannedLspRequest[] = planned.map((cs) => {
+    let map = maps.get(cs.filePath);
+    if (!map) {
+      map = buildLineOffsetMap(cs.content);
+      maps.set(cs.filePath, map);
+    }
+    const position = byteOffsetToPosition(cs.content, cs.calleeByteOffset, map);
+    return {
+      filePath: cs.filePath,
+      language: cs.language,
+      content: cs.content,
+      calleeName: cs.calleeName,
+      srcQualifiedName: cs.srcQualifiedName,
+      position,
+    };
+  });
+
+  return { requests, budgetExhausted: exhausted };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Executor — sends definition requests, maps locations, applies upgrades
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Options for the resolution executor.
+ */
+export interface ResolveOptions {
+  readonly client: LspClient;
+  readonly nodeLocator: NodeLocator;
+  /**
+   * Apply a batch of edge upgrades atomically. Called once per file batch.
+   * MUST be transactional — if it throws, zero upgrades from this batch
+   * persist (rule 25). Each upgrade is an edge `{srcQualifiedName,
+   * dstQualifiedName, type: "CALLS", confidence, provenance: "lsp"}`.
+   */
+  readonly applyUpgrades: (
+    upgrades: readonly EdgeUpgrade[],
+  ) => Promise<void>;
+  /**
+   * Workspace root for resolving repo-relative file paths to absolute LSP
+   * URIs and normalizing returned URIs back to repo-relative paths.
+   */
+  readonly workspaceRoot?: string;
+  /**
+   * Resolve the content of a target file by repo-relative path. Used for
+   * cross-file definition positions — without this, cross-file byte-offset
+   * conversion falls back to the caller's content (best-effort).
+   */
+  readonly resolveContent?: (filePath: string) => string | null;
+}
+
+/**
+ * A single edge upgrade — the output of a successful definition lookup.
+ */
+export interface EdgeUpgrade {
+  readonly srcQualifiedName: string;
+  readonly dstQualifiedName: string;
+  readonly type: string;
+  readonly confidence: number;
+  readonly provenance: "lsp";
+}
+
+/**
+ * Map a {@link CodingGraphLanguage} to its LSP languageId string. Most
+ * tier-1 languages use their own name; a few differ (tsx → typescriptreact,
+ * bash → shellscript).
+ */
+const LANGUAGE_ID_MAP: Partial<Record<CodingGraphLanguage, string>> = {
+  tsx: "typescriptreact",
+  bash: "shellscript",
+};
+
+/**
+ * Execute the resolution pass: for each planned request, send a
+ * `textDocument/didOpen` + `textDocument/definition` query, map the
+ * returned location to a graph node, and collect edge upgrades. Upgrades
+ * are applied in file-batched transactions — a mid-batch failure leaves
+ * zero partial upgrades.
+ *
+ * Never throws — degrades to Phase A results with a tagged degradation.
+ */
+export async function executeLspResolution(
+  requests: readonly PlannedLspRequest[],
+  options: ResolveOptions,
+): Promise<ResolutionResult> {
+  const { client, nodeLocator, applyUpgrades } = options;
+
+  // Group requests by file for batched transactional application.
+  const byFile = new Map<string, PlannedLspRequest[]>();
+  for (const req of requests) {
+    let batch = byFile.get(req.filePath);
+    if (!batch) {
+      batch = [];
+      byFile.set(req.filePath, batch);
+    }
+    batch.push(req);
+  }
+
+  let upgraded = 0;
+  let unresolved = 0;
+  let degradation: LspDegradation | undefined;
+
+  for (const [filePath, batchReqs] of byFile) {
+    // Send all definition requests for this file, collecting upgrades.
+    const upgrades: EdgeUpgrade[] = [];
+    let batchFailed = false;
+
+    // Open the document with full text before querying definitions (LSP 3.17).
+    // The server needs the content to answer definition requests accurately.
+    const firstReq = batchReqs[0];
+    client.didOpen({
+      uri: filePathToUri(filePath, options.workspaceRoot),
+      languageId: LANGUAGE_ID_MAP[firstReq.language] ?? firstReq.language,
+      version: 1,
+      text: firstReq.content,
+    });
+
+    for (let i = 0; i < batchReqs.length; i++) {
+      const req = batchReqs[i];
+      if (degradation) {
+        // Server died in a previous batch — count remaining unattempted.
+        unresolved += batchReqs.length - i;
+        break;
+      }
+
+      const defResult = await client.definition({
+        textDocument: { uri: filePathToUri(req.filePath, options.workspaceRoot) },
+        position: req.position,
+      });
+
+      if (!defResult.ok) {
+        // Distinguish "server problem" (stop the whole pass) from
+        // "this particular definition returned nothing" (continue).
+        if (
+          defResult.degradation.code === "server_crashed" ||
+          defResult.degradation.code === "protocol_error"
+        ) {
+          degradation = defResult.degradation;
+          // Count this request plus all remaining unattempted requests
+          // in this batch as unresolved for accurate reporting.
+          unresolved += batchReqs.length - i;
+          // Mark the batch failed so collected upgrades are NOT committed
+          // (rule 25 — per-batch atomicity; a degraded batch must not
+          // persist partial LSP edges).
+          batchFailed = true;
+          break;
+        }
+        // request_timeout / request_error — count as unresolved, continue.
+        unresolved++;
+        continue;
+      }
+
+      const dstQName = mapLocationToNode(
+        defResult.locations,
+        {
+          callerFilePath: req.filePath,
+          callerContent: req.content,
+          workspaceRoot: options.workspaceRoot,
+          resolveContent: options.resolveContent,
+        },
+        nodeLocator,
+      );
+      if (dstQName === null) {
+        unresolved++;
+        continue;
+      }
+      upgrades.push({
+        srcQualifiedName: req.srcQualifiedName,
+        dstQualifiedName: dstQName,
+        type: "CALLS",
+        confidence: 0.9,
+        provenance: "lsp",
+      });
+    }
+
+    if (batchFailed) {
+      // The batch was poisoned — collected upgrades must NOT be committed.
+      // Count them as unresolved for reporting accuracy.
+      unresolved += upgrades.length;
+      break;
+    }
+
+    // Apply upgrades transactionally per file batch. If the apply throws,
+    // zero upgrades from this batch persist (rule 25 — the applyUpgrades
+    // callback MUST be transactional).
+    if (upgrades.length > 0) {
+      try {
+        await applyUpgrades(upgrades);
+        upgraded += upgrades.length;
+      } catch {
+        // The apply failed — degrade but don't crash. Upgrades from this
+        // batch are lost (the callback's transaction rolled back). Edges
+        // from already-applied batches survive (they were in separate
+        // transactions — this is the documented per-batch isolation).
+        // Count the lost upgrades as unresolved for reporting.
+        unresolved += upgrades.length;
+      }
+    }
+  }
+
+  return {
+    upgraded,
+    unresolved,
+    budgetExhausted: 0, // set by the caller from the planner result
+    degradation,
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Location → node mapping (rule 35 — half-open span containment)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Map an LSP definition location to a graph node's qualified name.
+ *
+ * Uses half-open span containment (rule 35): the location's start byte
+ * must be within `[node.spanStart, node.spanEnd)` for the node to match.
+ * If multiple locations are returned, the FIRST one that maps to a node
+ * wins (LSP servers typically return the most relevant definition first).
+ *
+ * For same-file definitions, the caller's content is used for byte-offset
+ * conversion (exact). For cross-file definitions, `context.resolveContent`
+ * is used to fetch the target file's content; if unavailable, the caller's
+ * content is used as a best-effort fallback.
+ *
+ * Returns null if no location maps to an indexed node.
+ */
+export function mapLocationToNode(
+  locations: readonly LspLocation[],
+  context: MapLocationContext,
+  nodeLocator: NodeLocator,
+): string | null {
+  for (const loc of locations) {
+    const filePath = normalizeLocationPath(loc.uri, context.workspaceRoot);
+
+    // Resolve content for this location's file.
+    let content: string;
+    if (filePath === context.callerFilePath) {
+      // Same file as the caller — use the caller's exact content.
+      content = context.callerContent;
+    } else if (context.resolveContent) {
+      // Cross-file — use the content resolver for exact conversion.
+      const resolved = context.resolveContent(filePath);
+      if (resolved === null) continue; // file not indexed — skip
+      content = resolved;
+    } else {
+      // Cross-file without a resolver — best-effort fallback to caller
+      // content. The byte offset may be imprecise for files with different
+      // line lengths or Unicode, but the half-open containment check
+      // tolerates small offsets.
+      content = context.callerContent;
+    }
+
+    const map = buildLineOffsetMap(content);
+    const startByte = positionToByteOffset(content, loc.range.start, map);
+    const qName = nodeLocator(filePath, startByte);
+    if (qName !== null) return qName;
+  }
+  return null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// URI helpers
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a repo-relative file path to a `file://` URI for LSP requests.
+ * When `workspaceRoot` is provided, relative paths are resolved against
+ * it to produce an absolute URI (e.g. `file:///workspace/src/a.ts`). LSP
+ * servers do not reinterpret URIs relative to `rootUri`, so the URI must
+ * be absolute.
+ */
+function filePathToUri(filePath: string, workspaceRoot?: string): string {
+  const isAbsolute = filePath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(filePath);
+  if (isAbsolute) {
+    return `file://${filePath.replace(/\\/g, "/")}`;
+  }
+  if (workspaceRoot) {
+    const abs = path.join(workspaceRoot, filePath).replace(/\\/g, "/");
+    return `file://${abs}`;
+  }
+  // No workspace root — best-effort for backward compatibility.
+  return `file:///${filePath.replace(/\\/g, "/")}`;
+}
+
+/**
+ * Normalize an LSP `Location.uri` to a repo-relative file path. Strips the
+ * workspace root prefix so the result matches the store's canonical paths.
+ * Without `workspaceRoot`, returns the absolute path from the URI.
+ */
+function normalizeLocationPath(uri: string, workspaceRoot?: string): string {
+  const absPath = uriToPath(uri);
+  if (workspaceRoot) {
+    const root = path.resolve(workspaceRoot);
+    const rel = path.relative(root, absPath);
+    if (!rel.startsWith("..") && rel !== "") {
+      return rel.replace(/\\/g, "/");
+    }
+  }
+  return absPath;
+}

package/src/lsp/status.ts

@@ -0,0 +1,140 @@
+/**
+ * LSP status surfacing — per-language LSP state for index_status and
+ * `remnic doctor` (issue #1555 step 5).
+ *
+ * Reports per-language: enabled / probed / degraded(code) / requests_used.
+ * A missing server is normal, not an error — the status entry shows
+ * `probed: false` with a degradation code so the operator knows LSP
+ * resolution is available but inactive for that language.
+ */
+
+import type { LspDegradationCode } from "./degradation.js";
+import type { LspConfig } from "./config.js";
+import type { CodingGraphLanguage } from "@remnic/core";
+import type { ResolutionResult } from "./resolution.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Status entry — one per configured language
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Per-language LSP status. Surfaced in `index_status` and rendered as a
+ * single line by `remnic doctor`.
+ */
+export interface LspStatusEntry {
+  readonly language: CodingGraphLanguage;
+  /** Master switch state (codingGraph.lsp.enabled). */
+  readonly enabled: boolean;
+  /** Server binary found and initialize handshake succeeded. */
+  readonly probed: boolean;
+  /** True if the last resolution pass degraded (timeout/crash/protocol). */
+  readonly degraded: boolean;
+  /** Specific degradation code if `degraded` is true. */
+  readonly degradationCode?: LspDegradationCode;
+  /** Definition requests sent in the last index run. */
+  readonly requestsUsed: number;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Status computation
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Input for LSP status computation — the probe results and resolution
+ * results from the last index run. The caller (the index pipeline)
+ * collects these during the run and passes them here.
+ */
+export interface LspStatusInput {
+  readonly config: LspConfig;
+  /**
+   * Per-language probe results from the last run. `true` = server found
+   * and handshake succeeded.
+   */
+  readonly probeResults: ReadonlyMap<CodingGraphLanguage, boolean>;
+  /**
+   * Per-language degradation codes from the last run. A language in this
+   * map with a code means the resolution pass degraded for that language.
+   */
+  readonly degradations: ReadonlyMap<CodingGraphLanguage, LspDegradationCode>;
+  /**
+   * Per-language definition request counts from the last run.
+   */
+  readonly requestCounts: ReadonlyMap<CodingGraphLanguage, number>;
+  /**
+   * The languages configured for resolution (from the index run's
+   * candidate set). Only these languages get status entries.
+   */
+  readonly languages: readonly CodingGraphLanguage[];
+}
+
+/**
+ * Compute per-language LSP status entries. Pure — no side effects.
+ * Returns one entry per language in `languages`.
+ */
+export function getLspStatus(input: LspStatusInput): readonly LspStatusEntry[] {
+  return input.languages.map((lang) => {
+    const probed = input.probeResults.get(lang) ?? false;
+    const degradationCode = input.degradations.get(lang);
+    const requestsUsed = input.requestCounts.get(lang) ?? 0;
+    return {
+      language: lang,
+      enabled: input.config.enabled,
+      probed,
+      degraded: degradationCode !== undefined,
+      degradationCode,
+      requestsUsed,
+    };
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Doctor rendering — one line per language
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Render a single LSP status line for `remnic doctor`. Format:
+ *
+ *   typescript: lsp [probed] 12 requests
+ *   python:     lsp [degraded:request_timeout] 3 requests
+ *   go:         lsp [not_probed] 0 requests
+ *   rust:       lsp [disabled]
+ */
+export function formatLspStatusLine(entry: LspStatusEntry): string {
+  if (!entry.enabled) {
+    return `${entry.language}: lsp [disabled]`;
+  }
+  const parts: string[] = [];
+  if (entry.probed) {
+    parts.push("probed");
+  } else {
+    parts.push("not_probed");
+  }
+  if (entry.degraded && entry.degradationCode) {
+    parts[parts.length - 1] = `degraded:${entry.degradationCode}`;
+  }
+  const stateStr = parts.join(" ");
+  return `${entry.language}: lsp [${stateStr}] ${entry.requestsUsed} requests`;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Resolution result → status input adapter
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Adapter: convert a {@link ResolutionResult} into the per-language
+ * degradation + request-count maps that {@link getLspStatus} consumes.
+ *
+ * The resolution pass runs once per language (each language has its own
+ * server). This helper is called once per language to populate the maps.
+ */
+export function resolutionResultToStatusMaps(
+  language: CodingGraphLanguage,
+  result: ResolutionResult,
+  degradations: Map<CodingGraphLanguage, LspDegradationCode>,
+  requestCounts: Map<CodingGraphLanguage, number>,
+): void {
+  requestCounts.set(language, result.upgraded + result.unresolved);
+  if (result.degradation) {
+    degradations.set(language, result.degradation.code);
+  }
+}