@mrclrchtr/supi-lsp 11.2.0 → 11.3.0

package/src/client/client.ts

@@ -80,6 +80,11 @@ import type {
   SemanticInputSnapshot,
 } from "./client-semantic-input-barrier.ts";
 import { SemanticInputSynchronizationError } from "./client-semantic-input-errors.ts";
+import {
+  type ProjectMembership,
+  readTypeScriptProjectMembership,
+  typeScriptProjectInfoParams,
+} from "./client-typescript-project.ts";
 import { JsonRpcClient, JsonRpcRequestError } from "./transport.ts";
 
 const SHUTDOWN_TIMEOUT_MS = 5_000;
@@ -89,6 +94,12 @@ const CONTENT_MODIFIED_RETRY_DELAY_MS = 100;
 
 /** Bounded stderr tail kept for startup-failure error messages. */
 const STDERR_TAIL_MAX_CHARS = 4_000;
+/**
+ * Bound for draining a failed startup's stdio. An initialize write can fail
+ * (`EPIPE`) before the exiting server's stderr is read; waiting for `close`
+ * lets the failure report the server's own reason instead of the transport error.
+ */
+const STARTUP_FAILURE_DRAIN_MS = 500;
 
 interface SemanticRequestAttemptState {
   inputRevision: number | undefined;
@@ -492,6 +503,20 @@ function killFailedStartupProcess(child: ChildProcess): void {
   child.kill();
 }
 
+/** Resolve once `closed()` holds or the child emits `close`, bounded by `ms`. */
+function waitForStdioClose(child: ChildProcess, closed: () => boolean, ms: number): Promise<void> {
+  if (closed()) return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      child.off("close", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    child.once("close", done);
+  });
+}
+
 // ── Types ─────────────────────────────────────────────────────────────
 export type ClientStatus = "initializing" | "running" | "error" | "shutdown";
 
@@ -726,19 +751,24 @@ export class LspClient {
     });
     this.rpc.onRequest((method, params) => this.handleServerRequest(method, params));
 
-    // Handle crashes
+    // Handle crashes. A failing initialize reports its own detailed failure.
+    let reportingStartupFailure = false;
     this.process.on("exit", (_code) => {
-      this.handleProcessFailure(new Error("Client crashed"));
+      if (!reportingStartupFailure) this.handleProcessFailure(new Error("Client crashed"));
     });
 
     this.process.on("error", (_err) => {
-      this.handleProcessFailure(new Error("Client process error"));
+      if (!reportingStartupFailure) this.handleProcessFailure(new Error("Client process error"));
     });
 
     // Capture a bounded stderr tail (discarded otherwise) so startup
     // failures can surface the server's own exit reason — expired builds,
     // missing runtimes, or invalid flags. Stderr never reaches the agent.
     let stderrTail = "";
+    let stdioClosed = false;
+    this.process.once("close", () => {
+      stdioClosed = true;
+    });
     this.process.stderr?.on("data", (chunk: Buffer | string) => {
       stderrTail = `${stderrTail}${chunk}`.slice(-STDERR_TAIL_MAX_CHARS);
     });
@@ -777,12 +807,16 @@ export class LspClient {
 
       this.armNoProgressTimer();
     } catch (err) {
+      const child = this.process;
+      reportingStartupFailure = true;
+      killFailedStartupProcess(child);
+      // Let already-written stderr drain before reporting the failure.
+      await waitForStdioClose(child, () => stdioClosed, STARTUP_FAILURE_DRAIN_MS);
       const stderrDetail = stderrTail.trim() ? `\n${this.name} stderr:\n${stderrTail.trim()}` : "";
       const failure = new Error(`${this.name}: initialize failed: ${err}${stderrDetail}`, {
         cause: err,
       });
       this.handleProcessFailure(failure);
-      killFailedStartupProcess(this.process);
       throw failure;
     }
   }
@@ -879,6 +913,33 @@ export class LspClient {
   }
 
   // ── Document Synchronization and Diagnostics ────────────────────────
+  /**
+   * Admit a first open between semantic attempts, reading content after the wait.
+   * Semantic/refactor callers protect their original inputs; ordinary tracking
+   * can adopt fresh content after a known change instead.
+   */
+  async openDocument(
+    filePath: string,
+    readContent: () => string,
+    control?: CodeRequestControl,
+    protectInputs = false,
+  ): Promise<void> {
+    const trackedCount = this.openFiles.length;
+    await this.diagnostics.openDocument(filePath, readContent, control, protectInputs);
+    this.publishTrackedFileChange(trackedCount);
+  }
+
+  /** Restore retained state without resurrecting a closed or replaced document. */
+  async restoreDocument(
+    filePath: string,
+    readContent: () => string,
+    isCurrent: () => boolean,
+  ): Promise<void> {
+    const trackedCount = this.openFiles.length;
+    await this.diagnostics.restoreDocument(filePath, readContent, isCurrent);
+    this.publishTrackedFileChange(trackedCount);
+  }
+
   /** Open a document, or update it when it is already open. */
   didOpen(filePath: string, content: string): void {
     const trackedCount = this.openFiles.length;
@@ -1161,6 +1222,23 @@ export class LspClient {
     );
   }
 
+  /**
+   * Report whether the server placed an open file in a configured project.
+   * Only the TypeScript route can answer; other routes return `unknown`.
+   */
+  async projectMembership(
+    filePath: string,
+    control?: CodeRequestControl,
+  ): Promise<ProjectMembership> {
+    if (!this.hasTypeScriptRequestCommand()) return "unknown";
+    const result = await this.query<unknown>(
+      "workspace/executeCommand",
+      typeScriptProjectInfoParams(fileToUri(filePath)),
+      control,
+    );
+    return result.kind === "completed" ? readTypeScriptProjectMembership(result.data) : "unknown";
+  }
+
   async workspaceSymbol(
     query: string,
     control?: CodeRequestControl,
@@ -1258,6 +1336,7 @@ export class LspClient {
           | undefined;
       },
       {
+        documentUri: params.textDocument.uri,
         inputRevision: options.inputRevision,
         onVerifiedSnapshot: (snapshot) => {
           inputRevision = snapshot.revision;
@@ -1309,17 +1388,22 @@ export class LspClient {
       triggerKind: context.triggerKind ?? CodeActionTriggerKind.Invoked,
       ...(context.only ? { only: [...context.only] } : {}),
     };
-    return this.runRefactorTransaction("textDocument/codeAction", control, async (transaction) => {
-      const raw = await transaction.rpc.sendRequest(
-        "textDocument/codeAction",
-        { textDocument: { uri: fileToUri(filePath) }, range, context: requestContext },
-        control,
-      );
-      if (raw === null || raw === undefined) return null;
-      if (!Array.isArray(raw)) throw new Error("LSP server returned malformed code actions.");
+    return this.runRefactorTransaction(
+      "textDocument/codeAction",
+      control,
+      async (transaction) => {
+        const raw = await transaction.rpc.sendRequest(
+          "textDocument/codeAction",
+          { textDocument: { uri: fileToUri(filePath) }, range, context: requestContext },
+          control,
+        );
+        if (raw === null || raw === undefined) return null;
+        if (!Array.isArray(raw)) throw new Error("LSP server returned malformed code actions.");
 
-      return this.resolveCodeActions(raw, transaction, control, requestContext.only);
-    });
+        return this.resolveCodeActions(raw, transaction, control, requestContext.only);
+      },
+      { documentUri: fileToUri(filePath) },
+    );
   }
 
   async implementation(
@@ -1384,9 +1468,10 @@ export class LspClient {
     control: CodeRequestControl | undefined,
     operation: (transaction: RefactorTransaction) => Promise<T | null | undefined>,
     options: {
+      readonly documentUri: string;
       readonly onVerifiedSnapshot?: (snapshot: SemanticInputSnapshot) => void;
       readonly inputRevision?: number;
-    } = {},
+    },
   ): Promise<CodeQueryResult<T | null>> {
     throwIfCodeRequestInterrupted(control);
     if (!this.rpc || this._status !== "running") {
@@ -1405,6 +1490,7 @@ export class LspClient {
         retryGuard.assertCurrent();
         const data = await this.runRefactorTransactionAttempt({
           method,
+          documentUri: options.documentUri,
           control,
           operation,
           retryGuard,
@@ -1446,9 +1532,10 @@ export class LspClient {
     }
   }
 
-  /** Run the complete prepare/request/resolve transaction for one input snapshot. */
+  /** Admit one prepare/request/resolve attempt, not retries or rename's own enrollment. */
   private async runRefactorTransactionAttempt<T>(options: {
     method: string;
+    documentUri: string;
     control?: CodeRequestControl;
     operation: (transaction: RefactorTransaction) => Promise<T | null | undefined>;
     retryGuard: SemanticInputRequestRetryGuard;
@@ -1459,27 +1546,36 @@ export class LspClient {
     throwIfCodeRequestInterrupted(control);
     retryGuard.assertCurrent();
     await this.getReady(control);
-    const inputSnapshot = await this.diagnostics.synchronizeSemanticInputs(control);
-    attempt.inputRevision = inputSnapshot.revision;
-    throwIfCodeRequestInterrupted(control);
-    retryGuard.assertCurrent();
-    const rpc = this.rpc;
-    if (!rpc || this._status !== "running") {
-      throw new Error(`LSP request ${method} is unavailable because the client is not running.`);
-    }
-    const data = await operation({
-      rpc,
-      assertCurrent: async () => {
+    return this.diagnostics.withSemanticRequest(
+      async () => {
         retryGuard.assertCurrent();
-        return this.diagnostics.assertSemanticInputsCurrent(inputSnapshot, control);
+        const inputSnapshot = await this.diagnostics.synchronizeSemanticInputs(control);
+        attempt.inputRevision = inputSnapshot.revision;
+        throwIfCodeRequestInterrupted(control);
+        retryGuard.assertCurrent();
+        const rpc = this.rpc;
+        if (!rpc || this._status !== "running") {
+          throw new Error(
+            `LSP request ${method} is unavailable because the client is not running.`,
+          );
+        }
+        const data = await operation({
+          rpc,
+          assertCurrent: async () => {
+            retryGuard.assertCurrent();
+            return this.diagnostics.assertSemanticInputsCurrent(inputSnapshot, control);
+          },
+        });
+        const verifiedSnapshot = await this.diagnostics.assertSemanticInputsCurrent(
+          inputSnapshot,
+          control,
+        );
+        onVerifiedSnapshot?.(verifiedSnapshot);
+        return data ?? null;
       },
-    });
-    const verifiedSnapshot = await this.diagnostics.assertSemanticInputsCurrent(
-      inputSnapshot,
       control,
+      options.documentUri,
     );
-    onVerifiedSnapshot?.(verifiedSnapshot);
-    return data ?? null;
   }
 
   private async query<T>(
@@ -1651,17 +1747,28 @@ export class LspClient {
     throwIfCodeRequestInterrupted(control);
     retryGuard.assertCurrent();
     await this.getReady(control);
-    const inputSnapshot = await this.diagnostics.synchronizeSemanticInputs(control);
-    attempt.inputRevision = inputSnapshot.revision;
-    throwIfCodeRequestInterrupted(control);
-    retryGuard.assertCurrent();
-    const rpc = this.rpc;
-    if (!rpc || this._status !== "running") {
-      throw new Error(`LSP request ${method} is unavailable because the client is not running.`);
-    }
-    const data = (await rpc.sendRequest(method, params, control)) as T | null | undefined;
-    await this.diagnostics.assertSemanticInputsCurrent(inputSnapshot, control);
-    return data ?? null;
+    // Local query methods construct the standard TextDocumentIdentifier envelope.
+    const documentUri = (params as { textDocument?: { uri: string } } | null)?.textDocument?.uri;
+    return this.diagnostics.withSemanticRequest(
+      async () => {
+        retryGuard.assertCurrent();
+        const inputSnapshot = await this.diagnostics.synchronizeSemanticInputs(control);
+        attempt.inputRevision = inputSnapshot.revision;
+        throwIfCodeRequestInterrupted(control);
+        retryGuard.assertCurrent();
+        const rpc = this.rpc;
+        if (!rpc || this._status !== "running") {
+          throw new Error(
+            `LSP request ${method} is unavailable because the client is not running.`,
+          );
+        }
+        const data = (await rpc.sendRequest(method, params, control)) as T | null | undefined;
+        await this.diagnostics.assertSemanticInputsCurrent(inputSnapshot, control);
+        return data ?? null;
+      },
+      control,
+      documentUri,
+    );
   }
 
   private handleServerRequest(method: string, params: unknown): unknown {

package/src/diagnostics/evidence.ts

@@ -1,6 +1,6 @@
-/** Reason for a partial or unavailable single-file result when the push stays tentative. */
+/** Explain the lack of request-based confirmation when only ambient push evidence is available. */
 export const TENTATIVE_PUSH_UNAVAILABLE_REASON =
-  "A diagnostic publication is ambient evidence only; it may show issues, but an empty publication cannot confirm that the document is clean.";
+  "Only ambient push diagnostics are available for this file; completion of the diagnostic check cannot be confirmed. An empty publication cannot confirm that the document is clean.";
 
 /** A final evidence state for one tracked document. */
 export type DiagnosticEvidenceStatus = "confirmed" | "unconfirmed" | "failed" | "removed";

package/src/manager/manager-workspace-symbol.ts

@@ -1,4 +1,4 @@
-import { statSync } from "node:fs";
+import { type Dirent, realpathSync, statSync } from "node:fs";
 import * as path from "node:path";
 import {
   type CodeQueryResult,
@@ -25,6 +25,10 @@ type WorkspaceSymbolLike = SymbolInformation | WorkspaceSymbol;
 
 const DEFAULT_WARM_FILE_DEPTH = 4;
 const DEFAULT_MARKER_SCAN_DEPTH = 6;
+/** Candidates per marker root; later candidates help only when earlier ones land outside the project. */
+const WARM_FILES_PER_ROOT = 3;
+/** Conventional source directories tried before other top-level entries. */
+const PREFERRED_SOURCE_DIRECTORIES = ["src", "lib", "app"];
 
 export interface WorkspaceSymbolWarmTarget {
   projectRoot: string;
@@ -63,6 +67,26 @@ export interface WorkspaceSymbolCollection {
   excludedCount?: number;
   /** Bounded paths removed by the automatic path policy. */
   excludedExamples?: string[];
+  /** Known coverage limits: the server may not have loaded every project in scope. */
+  coverageGap?: string;
+}
+
+/**
+ * Mark a collection whose warm-up never reached a configured project.
+ * The server answered only from inferred projects of the opened probe files,
+ * so an empty or short result does not prove a symbol is absent.
+ */
+export function workspaceSymbolCoverageGap(
+  collection: WorkspaceSymbolCollection,
+  inferredProbeCount: number,
+): WorkspaceSymbolCollection {
+  const noun = `file${inferredProbeCount === 1 ? "" : "s"}`;
+  return {
+    ...collection,
+    coverageGap:
+      `Workspace-symbol coverage is limited: ${inferredProbeCount} opened warm-up ${noun} ` +
+      "loaded only inferred projects, not a configured project. Open a project source file and retry.",
+  };
 }
 
 export async function collectWorkspaceSymbols(
@@ -96,10 +120,8 @@ function workspaceSymbolExclusionReason(collection: WorkspaceSymbolCollection):
   const excludedCount = collection.excludedCount ?? 0;
   if (excludedCount === 0) return null;
   const noun = `workspace-symbol result${excludedCount === 1 ? "" : "s"}`;
-  const examples = collection.excludedExamples?.length
-    ? ` Examples: ${collection.excludedExamples.join(", ")}.`
-    : "";
-  return `Automatic path policy excluded ${excludedCount} ${noun}.${examples}`;
+  // Paths belong to typed metadata so consumers can distinguish observed aliases from navigation.
+  return `Automatic path policy excluded ${excludedCount} ${noun}.`;
 }
 
 /** Project one multi-client collection into the shared typed query contract. */
@@ -115,8 +137,9 @@ export function workspaceSymbolCollectionResult(
     );
   }
   const exclusion = workspaceSymbolExclusionReason(collection);
-  if (collection.failures.length > 0 || exclusion) {
+  if (collection.failures.length > 0 || exclusion || collection.coverageGap) {
     const excludedCount = collection.excludedCount ?? 0;
+    const exclusionOnly = collection.failures.length === 0 && !collection.coverageGap;
     const metadata =
       excludedCount > 0
         ? {
@@ -124,17 +147,30 @@ export function workspaceSymbolCollectionResult(
               excludedCount,
               examples: [...(collection.excludedExamples ?? [])],
             },
+            ...(exclusionOnly ? { exclusionOnly: true } : {}),
           }
         : undefined;
     return partialCodeQuery(
       collection.results,
-      [collection.failures.join("; "), exclusion].filter(Boolean).join("; "),
+      [collection.failures.join("; "), collection.coverageGap, exclusion]
+        .filter(Boolean)
+        .join("; "),
       metadata,
     );
   }
   return completedCodeQuery(collection.results);
 }
 
+/**
+ * Choose files to open so a workspace-symbol server loads the projects under `root`.
+ *
+ * Returns up to three candidates per marker root, interleaved so every root's
+ * best candidate comes before any root's fallback; nested roots first. Within a
+ * root, conventional source directories come first and hidden entries last:
+ * root-level dotfiles and tool configs are often outside the configured program
+ * (for example `tsconfig.json` `include`), and opening only such a file loads an
+ * unrelated project. Callers try candidates in order.
+ */
 export function findWorkspaceSymbolWarmTargets(
   root: string,
   rootMarkers: string[],
@@ -158,7 +194,7 @@ export function findWorkspaceSymbolWarmTargets(
       return searchRoot
         ? findWorkspaceSymbolWarmTargets(searchRoot, rootMarkers, fileTypes, {
             ...options,
-            policy,
+            policy: explicitScopePolicy(policy, scope),
             scopes: undefined,
           })
         : [];
@@ -174,26 +210,76 @@ export function findWorkspaceSymbolWarmTargets(
   }
 
   const markerRoots = collectMarkerRoots(resolvedRoot, rootMarkers, maxMarkerDepth, policy);
-  const targets = markerRoots
-    .map((entry) => {
-      const file = findWarmFileRecursive(entry.root, allowed, maxFileDepth, policy);
-      return file ? { projectRoot: entry.root, file, priority: entry.priority } : null;
-    })
-    .filter((entry): entry is { projectRoot: string; file: string; priority: number } =>
-      Boolean(entry),
-    )
+  const perRoot = markerRoots
     .sort(
       (a, b) =>
-        a.priority - b.priority ||
-        a.projectRoot.length - b.projectRoot.length ||
-        a.projectRoot.localeCompare(b.projectRoot),
+        a.priority - b.priority || a.root.length - b.root.length || a.root.localeCompare(b.root),
     )
-    .map(({ projectRoot, file }) => ({ projectRoot, file }));
+    .map((entry) =>
+      findWarmFiles(entry.root, allowed, maxFileDepth, policy).map((file) => ({
+        projectRoot: entry.root,
+        file,
+      })),
+    );
+  // Interleave by rank so each root's best candidate precedes any root's fallback.
+  const targets = Array.from({ length: WARM_FILES_PER_ROOT }, (_, rank) =>
+    perRoot.flatMap((candidates) => candidates[rank] ?? []),
+  ).flat();
+
+  if (targets.length > 0) {
+    // Keep the first, most specific root for a file a parent root also reaches.
+    const seen = new Set<string>();
+    return targets.filter((target) => !seen.has(target.file) && Boolean(seen.add(target.file)));
+  }
 
-  if (targets.length > 0) return targets;
+  return findWarmFiles(resolvedRoot, allowed, maxFileDepth, policy).map((file) => ({
+    projectRoot: resolvedRoot,
+    file,
+  }));
+}
+
+/**
+ * True when a reported file is inside a scope by spelling or physical identity.
+ * Servers may report realpaths for files requested through symlinked roots.
+ */
+export function isWithinAnyScope(file: string, scopes: readonly string[]): boolean {
+  if (scopes.some((scope) => isWithinOrEqual(scope, file))) return true;
+  try {
+    const physicalFile = realpathSync(file);
+    return scopes.some((scope) => {
+      try {
+        return isWithinOrEqual(realpathSync(scope), physicalFile);
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
 
-  const fallback = findWarmFileRecursive(resolvedRoot, allowed, maxFileDepth, policy);
-  return fallback ? [{ projectRoot: resolvedRoot, file: fallback }] : [];
+/**
+ * Keep an explicitly selected excluded file or directory warmable, matching the
+ * rows workspace-symbol filtering allows for that scope. Exclusions nested in an
+ * eligible directory scope stay excluded.
+ */
+function explicitScopePolicy(
+  policy: AutomaticLspPathPolicy,
+  scope: string,
+): AutomaticLspPathPolicy {
+  const kind = statSync(scope, { throwIfNoEntry: false });
+  if (!kind) return policy;
+  const selected = kind.isFile()
+    ? (candidate: string) => path.resolve(candidate) === path.resolve(scope)
+    : policy.isEligible(scope, "directory")
+      ? null
+      : (candidate: string) => isWithinOrEqual(scope, candidate);
+  if (!selected) return policy;
+  return {
+    ...policy,
+    isEligible: (candidate, candidateKind) =>
+      selected(candidate) ? true : policy.isEligible(candidate, candidateKind),
+  };
 }
 
 interface MarkerRootEntry {
@@ -234,6 +320,54 @@ function collectMarkerRoots(
   }));
 }
 
+/**
+ * Pick at most {@link WARM_FILES_PER_ROOT} files under `root`, one per top-level
+ * group: preferred source directories, other directories, root files, then
+ * hidden entries.
+ */
+function findWarmFiles(
+  root: string,
+  allowed: Set<string>,
+  depth: number,
+  policy: AutomaticLspPathPolicy,
+): string[] {
+  let topLevel: readonly Dirent[] = [];
+  walkAutomaticLspTree(policy, root, 0, (_directory, entries) => {
+    topLevel = entries;
+    return true;
+  });
+  const isAllowedFile = (entry: Dirent) =>
+    (entry.isFile() || entry.isSymbolicLink()) &&
+    allowed.has(path.extname(entry.name).slice(1).toLowerCase());
+  const rank = (entry: Dirent) => {
+    const hidden = entry.name.startsWith(".") ? 3 : 0;
+    if (!entry.isDirectory()) return hidden + 2;
+    return hidden + (PREFERRED_SOURCE_DIRECTORIES.includes(entry.name) ? 0 : 1);
+  };
+  const ordered = topLevel
+    .filter((entry) => entry.isDirectory() || isAllowedFile(entry))
+    .map((entry, index) => ({ entry, index, rank: rank(entry) }))
+    .sort((a, b) => a.rank - b.rank || a.index - b.index);
+
+  const files: string[] = [];
+  const rootFileRanks = new Set<number>();
+  for (const { entry, rank: entryRank } of ordered) {
+    if (files.length >= WARM_FILES_PER_ROOT) break;
+    const entryPath = path.join(root, entry.name);
+    if (!entry.isDirectory()) {
+      // One root file per visibility group is enough evidence for that group.
+      if (rootFileRanks.has(entryRank)) continue;
+      rootFileRanks.add(entryRank);
+      files.push(entryPath);
+      continue;
+    }
+    if (depth <= 0) continue;
+    const file = findWarmFileRecursive(entryPath, allowed, depth - 1, policy);
+    if (file) files.push(file);
+  }
+  return files;
+}
+
 function findWarmFileRecursive(
   directory: string,
   allowed: Set<string>,