@mrclrchtr/supi-lsp 11.2.0 → 11.4.0

package/src/client/client-input-admission.ts

@@ -0,0 +1,149 @@
+import {
+  type CodeRequestControl,
+  CodeRequestDeadlineError,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+
+const MAX_PENDING_INPUT_OPERATIONS = 32;
+
+type InputOperationKind = "request" | "enrollment" | "request-enrollment";
+
+interface PendingInputOperation {
+  readonly uri: string | undefined;
+  readonly kind: InputOperationKind;
+  start(): void;
+  cancel(reason: unknown): void;
+}
+
+/**
+ * Admit first opens between semantic query and refactor-planning attempts on one client.
+ * Consecutive readers run concurrently; FIFO admission prevents either new
+ * readers or enrollments from overtaking a waiting operation. This is not
+ * diagnostic transport ownership: an interrupted semantic attempt can release
+ * its admission even when the server has not yet acknowledged cancellation.
+ */
+export class SemanticInputAdmission {
+  readonly #pending: PendingInputOperation[] = [];
+  #readers = 0;
+  #enrolling = false;
+  #disposed = false;
+
+  /** Cover one attempt's synchronization, RPCs and acceptance, never its retry. */
+  request<T>(run: () => Promise<T>, control?: CodeRequestControl, uri?: string): Promise<T> {
+    return this.#run("request", uri, run, control);
+  }
+
+  /**
+   * Commit a first open after earlier attempts leave. Demand with original
+   * semantic/refactor parameters opts into input invalidation while waiting.
+   */
+  enroll(
+    uri: string,
+    run: () => void,
+    control?: CodeRequestControl,
+    protectInputs = false,
+  ): Promise<void> {
+    return this.#run(protectInputs ? "request-enrollment" : "enrollment", uri, run, control);
+  }
+
+  /** A close cancels queued opens and queries for that document, before dispatch. */
+  close(uri: string): void {
+    const cancelled = this.#pending.filter((pending) => pending.uri === uri);
+    for (const pending of cancelled) this.#pending.splice(this.#pending.indexOf(pending), 1);
+    for (const pending of cancelled)
+      pending.cancel(new Error("Document closed before input admission."));
+  }
+
+  /** Discard queued request parameters after a known non-enrollment input change. */
+  invalidateRequests(): void {
+    const cancelled = this.#pending.filter((pending) => pending.kind !== "enrollment");
+    for (const pending of cancelled) this.#pending.splice(this.#pending.indexOf(pending), 1);
+    for (const pending of cancelled)
+      pending.cancel(new Error("Semantic inputs changed before request admission."));
+  }
+
+  /** Reject queued work without confusing caller completion with transport settlement. */
+  dispose(): void {
+    this.#disposed = true;
+    for (const pending of [...this.#pending]) {
+      pending.cancel(new Error("LSP client stopped before input admission."));
+    }
+  }
+
+  #run<T>(
+    kind: InputOperationKind,
+    uri: string | undefined,
+    run: () => T | Promise<T>,
+    control: CodeRequestControl | undefined,
+  ): Promise<T> {
+    throwIfCodeRequestInterrupted(control);
+    if (this.#disposed) return Promise.reject(new Error("LSP input admission is disposed."));
+    if (this.#pending.length >= MAX_PENDING_INPUT_OPERATIONS) {
+      return Promise.reject(new Error("LSP input admission queue is full."));
+    }
+    return new Promise<T>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let waiting = true;
+      const cleanup = () => {
+        if (timer !== undefined) clearTimeout(timer);
+        control?.signal?.removeEventListener("abort", abort);
+      };
+      const operation: PendingInputOperation = {
+        uri,
+        kind,
+        cancel: (reason) => {
+          if (!waiting) return;
+          waiting = false;
+          cleanup();
+          const index = this.#pending.indexOf(operation);
+          if (index !== -1) this.#pending.splice(index, 1);
+          reject(reason);
+          this.#drain();
+        },
+        start: () => {
+          waiting = false;
+          cleanup();
+          if (kind !== "request") this.#enrolling = true;
+          else this.#readers++;
+          const finish = () => {
+            if (kind !== "request") this.#enrolling = false;
+            else this.#readers--;
+            this.#drain();
+          };
+          try {
+            throwIfCodeRequestInterrupted(control);
+            Promise.resolve(run()).then(resolve, reject).finally(finish);
+          } catch (error) {
+            reject(error);
+            finish();
+          }
+        },
+      };
+      const abort = () => {
+        try {
+          throwIfCodeRequestInterrupted(control);
+        } catch (error) {
+          operation.cancel(error);
+        }
+      };
+      this.#pending.push(operation);
+      control?.signal?.addEventListener("abort", abort, { once: true });
+      if (control?.deadline !== undefined) {
+        timer = setTimeout(
+          () => operation.cancel(new CodeRequestDeadlineError()),
+          Math.max(0, control.deadline - Date.now()),
+        );
+      }
+      this.#drain();
+    });
+  }
+
+  #drain(): void {
+    while (!this.#disposed && !this.#enrolling && this.#pending.length > 0) {
+      const next = this.#pending[0];
+      if (next.kind !== "request" && this.#readers > 0) return;
+      this.#pending.shift();
+      next.start();
+    }
+  }
+}

package/src/client/client-typescript-project.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether tsserver placed an open file in a configured project.
+ *
+ * - `configured`: a `tsconfig.json` / `jsconfig.json` program owns the file.
+ * - `inferred`: tsserver created an inferred project for the file alone, so
+ *   project-wide requests such as `workspace/symbol` do not cover the
+ *   configured program.
+ * - `unknown`: the route is not TypeScript or tsserver could not answer.
+ */
+export type ProjectMembership = "configured" | "inferred" | "unknown";
+
+/** Build `workspace/executeCommand` params for tsserver `projectInfo`. */
+export function typeScriptProjectInfoParams(uri: string): unknown {
+  return {
+    command: "typescript.tsserverRequest",
+    arguments: [
+      "projectInfo",
+      { file: uri, needFileNameList: false },
+      // Semantic execution target; the project must be loaded to answer.
+      { executionTarget: 0, expectsResult: true, isAsync: false },
+    ],
+  };
+}
+
+/**
+ * Read project membership from a tsserver `projectInfo` response.
+ * tsserver names projects without a config file `/dev/null/<kind>Project<N>*`.
+ */
+export function readTypeScriptProjectMembership(response: unknown): ProjectMembership {
+  if (!isRecord(response) || response.type !== "response" || response.success !== true) {
+    return "unknown";
+  }
+  const body = response.body;
+  if (!isRecord(body) || typeof body.configFileName !== "string") return "unknown";
+  return body.configFileName.startsWith("/dev/null/") ? "inferred" : "configured";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

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/config/tsconfig-scope.ts

@@ -162,6 +162,16 @@ export function getFileScopeDecision(filePath: string, cwd: string): FileScopeDe
   };
 }
 
+/**
+ * Whether a project config's program includes a file, by its own file set or
+ * include/exclude rules. Unlike {@link getFileScopeDecision}, the config need
+ * not be the file's nearest one (e.g. a test config including `../src`).
+ */
+export function projectConfigIncludesFile(configPath: string, filePath: string): boolean {
+  const parsed = parseProjectConfig(configPath);
+  return parsed !== null && decideFileScope(parsed, path.resolve(filePath)).included;
+}
+
 function isOutOfTree(cwd: string, absolutePath: string): boolean {
   const relative = path.relative(path.resolve(cwd), absolutePath);
   return relative.startsWith(`..${path.sep}`) || relative === "..";

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-typescript-coverage.ts

@@ -0,0 +1,118 @@
+import * as path from "node:path";
+import { collectExtendedProjectConfigs } from "../config/tsconfig-extends.ts";
+import { normalizeTsconfigPath } from "../config/tsconfig-path.ts";
+import { getFileScopeDecision, projectConfigIncludesFile } from "../config/tsconfig-scope.ts";
+import { type AutomaticLspPathPolicy, walkAutomaticLspTree } from "../workspace-path-policy.ts";
+
+/** Directory depth searched for project configs below a TypeScript route root. */
+const PROJECT_CONFIG_SCAN_DEPTH = 8;
+/** Project config paths named in one coverage reason. */
+const MAX_NAMED_PROJECTS = 3;
+/** File names tsserver loads as projects; `tsconfig.*.json` variants are never auto-loaded. */
+const LOADABLE_PROJECT_CONFIGS = new Set(["tsconfig.json", "jsconfig.json"]);
+
+/** Find loadable project configs under a route root, honoring the automatic path policy. */
+export function discoverTypeScriptProjectConfigs(
+  root: string,
+  policy: AutomaticLspPathPolicy,
+): string[] {
+  const configs: string[] = [];
+  walkAutomaticLspTree(policy, root, PROJECT_CONFIG_SCAN_DEPTH, (directory, entries) => {
+    for (const entry of entries) {
+      if (entry.isFile() && LOADABLE_PROJECT_CONFIGS.has(entry.name)) {
+        configs.push(path.join(directory, entry.name));
+      }
+    }
+    return false;
+  });
+  return configs;
+}
+
+/**
+ * Project configs whose program includes `file` but show no sign of being loaded.
+ *
+ * tsserver answers project-wide requests such as references and
+ * implementations only from loaded projects, and loads a project only when one
+ * of its files is open. An unloaded including project (typically a test
+ * config that includes `../src`) can hold matches the answer omits.
+ *
+ * A project counts as loaded when it is the nearest config of an open file or
+ * of a file in the answer (`resultFiles`): tsserver also loads projects on its
+ * own during a search, and a match from a project's own file proves it was searched.
+ *
+ * Base configs extended by another discovered config are skipped: their
+ * default include usually spans the whole tree while they own only root
+ * tooling files, so counting them would mark nearly every answer partial.
+ */
+export function findUnloadedTypeScriptProjects(options: {
+  readonly file: string;
+  readonly cwd: string;
+  readonly openFiles: readonly string[];
+  readonly resultFiles?: readonly string[];
+  readonly configs: readonly string[];
+}): string[] {
+  const baseConfigs = new Set(
+    options.configs.flatMap((config) => [...collectExtendedProjectConfigs(config)]),
+  );
+  const loaded = new Set<string>();
+  for (const loadedFile of [...options.openFiles, ...(options.resultFiles ?? [])]) {
+    const decision = getFileScopeDecision(loadedFile, options.cwd);
+    if (decision.status === "included" && decision.configPath) {
+      loaded.add(normalizeTsconfigPath(decision.configPath));
+    }
+  }
+  return options.configs.filter((config) => {
+    const key = normalizeTsconfigPath(config);
+    return (
+      !loaded.has(key) && !baseConfigs.has(key) && projectConfigIncludesFile(config, options.file)
+    );
+  });
+}
+
+/**
+ * Other projects that tsserver's implementation search skips for `file`.
+ *
+ * tsserver 6 and earlier answer `textDocument/implementation` from the file's
+ * default project only, unlike references, which span loaded projects. Any
+ * other non-base project may implement the target through an import, and
+ * opening its files does not change the answer.
+ */
+export function findSkippedImplementationProjects(options: {
+  readonly file: string;
+  readonly cwd: string;
+  readonly configs: readonly string[];
+}): string[] {
+  const baseConfigs = new Set(
+    options.configs.flatMap((config) => [...collectExtendedProjectConfigs(config)]),
+  );
+  const decision = getFileScopeDecision(options.file, options.cwd);
+  const own = decision.configPath ? normalizeTsconfigPath(decision.configPath) : undefined;
+  return options.configs.filter((config) => {
+    const key = normalizeTsconfigPath(config);
+    return key !== own && !baseConfigs.has(key);
+  });
+}
+
+/** Partial-result reason for tsserver's single-project implementation search. */
+export function singleProjectImplementationReason(skipped: readonly string[]): string {
+  const noun = skipped.length === 1 ? "1 other project is" : `${skipped.length} other projects are`;
+  return (
+    "TypeScript coverage is limited: the TypeScript 6 or earlier server (tsserver) " +
+    `searches implementations only in this file's project; ${noun} not searched. ` +
+    "Use references to find uses in other projects, or use TypeScript 7."
+  );
+}
+
+/** Actionable partial-result reason naming a bounded set of unloaded projects. */
+export function typeScriptCoverageGapReason(unloaded: readonly string[], cwd: string): string {
+  const named = unloaded
+    .slice(0, MAX_NAMED_PROJECTS)
+    .map((config) => path.relative(cwd, config) || path.basename(config));
+  const more = unloaded.length > named.length ? `, +${unloaded.length - named.length} more` : "";
+  const noun = unloaded.length === 1 ? "project that includes" : "projects that include";
+  return (
+    `TypeScript coverage is limited: ${unloaded.length} ${noun} this file ` +
+    `${unloaded.length === 1 ? "is" : "are"} not loaded (${named.join(", ")}${more}). ` +
+    "Open a file from each project and retry."
+  );
+}