@mrclrchtr/supi-lsp 11.2.0 → 11.4.0

package/src/manager/typescript-file-local.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs";
+import ts from "typescript";
+
+/**
+ * Whether the identifier at `position` names a top-level declaration that only
+ * its own file can reference: the file is an ES module and the declaration is
+ * neither exported by a modifier nor by an export clause or assignment.
+ *
+ * Other TypeScript projects can then hold no references or implementations,
+ * so a project coverage gap cannot apply. Script files (no import or export),
+ * members, unreadable files, and non-declaration positions return false.
+ *
+ * @param position Zero-based LSP position.
+ */
+export function isFileLocalTopLevelDeclaration(
+  filePath: string,
+  position: { readonly line: number; readonly character: number },
+): boolean {
+  let text: string;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch {
+    return false;
+  }
+  const sourceFile = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true);
+  if (!ts.isExternalModule(sourceFile)) return false;
+  let offset: number;
+  try {
+    offset = ts.getPositionOfLineAndCharacter(sourceFile, position.line, position.character);
+  } catch {
+    return false;
+  }
+  const statement = sourceFile.statements.find(
+    (candidate) => candidate.getStart(sourceFile) <= offset && offset < candidate.end,
+  );
+  if (!statement) return false;
+  const name = topLevelDeclarationNameAt(statement, offset, sourceFile);
+  return name !== null && !hasExportModifier(statement) && !exportedByName(sourceFile, name);
+}
+
+/** Name of the declaration `statement` declares at `offset`, or null. */
+function topLevelDeclarationNameAt(
+  statement: ts.Statement,
+  offset: number,
+  sourceFile: ts.SourceFile,
+): string | null {
+  const names: ts.Identifier[] = [];
+  if (
+    ts.isFunctionDeclaration(statement) ||
+    ts.isClassDeclaration(statement) ||
+    ts.isInterfaceDeclaration(statement) ||
+    ts.isTypeAliasDeclaration(statement) ||
+    ts.isEnumDeclaration(statement)
+  ) {
+    if (statement.name) names.push(statement.name);
+  } else if (ts.isVariableStatement(statement)) {
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name)) names.push(declaration.name);
+    }
+  }
+  const hit = names.find((name) => name.getStart(sourceFile) <= offset && offset <= name.end);
+  return hit ? hit.text : null;
+}
+
+function hasExportModifier(statement: ts.Statement): boolean {
+  return (
+    ts.canHaveModifiers(statement) &&
+    (ts.getModifiers(statement) ?? []).some(
+      (modifier) =>
+        modifier.kind === ts.SyntaxKind.ExportKeyword ||
+        modifier.kind === ts.SyntaxKind.DeclareKeyword,
+    )
+  );
+}
+
+/** `export { name }`, `export default name`, or `export = name` in this file. */
+function exportedByName(sourceFile: ts.SourceFile, name: string): boolean {
+  return sourceFile.statements.some((statement) => {
+    if (ts.isExportAssignment(statement)) {
+      return ts.isIdentifier(statement.expression) && statement.expression.text === name;
+    }
+    if (!ts.isExportDeclaration(statement) || statement.moduleSpecifier) return false;
+    const clause = statement.exportClause;
+    if (!clause || !ts.isNamedExports(clause)) return false;
+    return clause.elements.some((element) => (element.propertyName ?? element.name).text === name);
+  });
+}

package/src/provider/semantic-symbol-mapper.ts

@@ -2,10 +2,11 @@ import { readFile } from "node:fs/promises";
 import type {
   CodeLocation,
   CodeSymbol,
-  DeclarationNesting,
+  DeclarationLevel,
   DocumentCodeSymbol,
   SourceRange,
 } from "@mrclrchtr/supi-code-runtime/api";
+import { childDeclarationLevel } from "@mrclrchtr/supi-code-runtime/api";
 import { uriToFile } from "@mrclrchtr/supi-core/path";
 import type {
   DocumentSymbol,
@@ -100,15 +101,26 @@ export async function mapDocumentSymbols(
 ): Promise<DocumentCodeSymbol[]> {
   return flattenDocumentSymbols(symbols, filePath, null, {
     sourceLines: await readSourceLines(filePath),
-    nesting: "top-level",
+    parent: null,
   });
 }
 
+/** Level of a symbol reported inside `parent`, or top-level without one. */
+function levelWithin(
+  parent: { readonly kind: string; readonly level: DeclarationLevel } | null,
+  kind: string,
+): DeclarationLevel {
+  return parent ? childDeclarationLevel(parent, kind) : "top-level";
+}
+
 function flattenDocumentSymbols(
   symbols: DocumentSymbol[] | SymbolInformation[],
   filePath: string,
   container: string | null,
-  context: { sourceLines: readonly string[] | null; nesting: DeclarationNesting },
+  context: {
+    sourceLines: readonly string[] | null;
+    parent: { readonly kind: string; readonly level: DeclarationLevel } | null;
+  },
 ): DocumentCodeSymbol[] {
   const result: DocumentCodeSymbol[] = [];
   for (const sym of symbols) {
@@ -116,15 +128,13 @@ function flattenDocumentSymbols(
     let document: DocumentSymbol | null = null;
     if (isSymbolInformation(sym)) information = sym;
     else document = sym;
+    const kind = symbolKindName(sym.kind);
+    const level = information ? "unknown" : levelWithin(context.parent, kind);
+    const childContext = { sourceLines: context.sourceLines, parent: { kind, level } };
     const declarationRange = toValidRange(document?.range ?? information?.location.range);
     if (!declarationRange) {
       if (document?.children?.length) {
-        result.push(
-          ...flattenDocumentSymbols(document.children, filePath, sym.name, {
-            sourceLines: context.sourceLines,
-            nesting: "nested",
-          }),
-        );
+        result.push(...flattenDocumentSymbols(document.children, filePath, sym.name, childContext));
       }
       continue;
     }
@@ -134,23 +144,18 @@ function flattenDocumentSymbols(
       : null;
     const symbol: DocumentCodeSymbol = {
       name: sym.name,
-      kind: symbolKindName(sym.kind),
+      kind,
       file: filePath,
       declarationAnchor: { line: declStart.line + 1, character: declStart.character + 1 },
       container: information?.containerName ?? container,
-      nesting: information ? "unknown" : context.nesting,
+      level,
     };
     if (nameStart) {
       symbol.nameAnchor = { line: nameStart.line + 1, character: nameStart.character + 1 };
     }
     result.push(symbol);
     if (document?.children?.length) {
-      result.push(
-        ...flattenDocumentSymbols(document.children, filePath, sym.name, {
-          sourceLines: context.sourceLines,
-          nesting: "nested",
-        }),
-      );
+      result.push(...flattenDocumentSymbols(document.children, filePath, sym.name, childContext));
     }
   }
   return result;

package/src/session/runtime-registry.ts

@@ -1,11 +1,13 @@
 // Shared session-scoped LSP service registry reused by peer extensions.
 
 // biome-ignore lint/style/noExcessiveLinesPerFile: session registry, runtime recovery, and telemetry stay in one file; splitting would hide the recovery contract.
+import { fileURLToPath } from "node:url";
 import {
   type CodeQueryResult,
   type CodeRequestControl,
   isCodeRequestInterruption,
   mapCodeQueryResult,
+  partialCodeQuery,
   throwIfCodeRequestInterrupted,
   unavailableCodeQuery,
 } from "@mrclrchtr/supi-code-runtime/api";
@@ -139,6 +141,8 @@ function recordScopeDecisionEvent(manager: LspManager): void {
   }
 }
 
+const FILE_STARTUP_FAILURE_REASON = "The routed LSP client could not be started for this file";
+
 class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
   constructor(private readonly manager: LspManager) {}
 
@@ -157,6 +161,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("hover", resolvedPath);
@@ -171,6 +176,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("definition", resolvedPath);
@@ -185,12 +191,18 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("references", resolvedPath);
-    return mapCodeQueryResult(
-      await client.references(resolvedPath, position, control),
-      (data) => data ?? [],
+    return this.withProjectCoverage(
+      client,
+      { file: resolvedPath, position },
+      "references",
+      mapCodeQueryResult(
+        await client.references(resolvedPath, position, control),
+        (data) => data ?? [],
+      ),
     );
   }
 
@@ -202,10 +214,34 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("implementation", resolvedPath);
-    return client.implementation(resolvedPath, position, control);
+    return this.withProjectCoverage(
+      client,
+      { file: resolvedPath, position },
+      "implementation",
+      await client.implementation(resolvedPath, position, control),
+    );
+  }
+
+  /**
+   * Downgrade a completed project-wide answer to partial when the TypeScript
+   * server may not have searched every relevant project.
+   */
+  private withProjectCoverage<T extends Location[] | Location | LocationLink[] | null>(
+    client: NonNullable<Awaited<ReturnType<LspManager["ensureFileOpen"]>>>,
+    target: { readonly file: string; readonly position: Position },
+    request: "references" | "implementation",
+    result: CodeQueryResult<T>,
+  ): CodeQueryResult<T> {
+    if (result.kind !== "completed") return result;
+    const gap = this.manager.typeScriptProjectCoverageGap(client, target.file, request, {
+      resultFiles: locationFiles(result.data),
+      position: target.position,
+    });
+    return gap ? partialCodeQuery(result.data, gap) : result;
   }
 
   async documentSymbols(
@@ -215,6 +251,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return unavailableFileQuery("document symbols", resolvedPath);
@@ -260,6 +297,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     const resolvedPath = this.resolveFilePath(filePath);
     const client = await this.manager.ensureFileOpen(resolvedPath, {
       recoverProcessCrash: true,
+      protectInputs: true,
       control,
     });
     if (!client) return null;
@@ -309,7 +347,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
       const processCrashRecovery = this.manager.getProcessCrashRecoveryReportForFile(resolvedPath);
       return {
         kind: "unavailable",
-        reason: "No LSP client can serve this file",
+        reason: this.fileUnavailableReason(resolvedPath, "No LSP client can serve this file"),
         ...(processCrashRecovery ? { processCrashRecovery } : {}),
       };
     }
@@ -347,7 +385,7 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     if (!client) {
       return {
         kind: "unavailable",
-        reason: "The routed LSP client could not be started for this file",
+        reason: this.fileUnavailableReason(resolvedPath, FILE_STARTUP_FAILURE_REASON),
         ...startup,
         ...recovery,
       };
@@ -355,6 +393,15 @@ class DefaultWorkspaceLspRuntime implements WorkspaceLspRuntime {
     return { kind: "ready", ...startup, ...recovery };
   }
 
+  private fileUnavailableReason(filePath: string, configuredRouteReason: string): string {
+    if (!this.manager.hasConfiguredServerForFile(filePath)) {
+      return "No compatible LSP server is configured for this file";
+    }
+    return this.manager.hasFailedStartupForFile(filePath)
+      ? FILE_STARTUP_FAILURE_REASON
+      : configuredRouteReason;
+  }
+
   /**
    * Wait until all started LSP clients are ready for semantic queries.
    * Performs one representative warm-up probe per client/root.
@@ -588,6 +635,21 @@ export async function waitForWorkspaceLspRuntime(
   return state;
 }
 
+/** Local file paths of LSP locations or location links; non-file URIs are skipped. */
+function locationFiles(data: Location[] | Location | LocationLink[] | null): string[] {
+  const items: (Location | LocationLink)[] =
+    data === null ? [] : Array.isArray(data) ? data : [data];
+  return items.flatMap((item) => {
+    const uri = "targetUri" in item ? item.targetUri : item.uri;
+    if (!uri.startsWith("file:")) return [];
+    try {
+      return [fileURLToPath(uri)];
+    } catch {
+      return [];
+    }
+  });
+}
+
 /** Remove the LSP service state for a session cwd. */
 export function clearWorkspaceLspRuntime(cwd: string): void {
   registry.clear(cwd);

package/src/session/runtime-rename.ts

@@ -21,6 +21,7 @@ export async function runRoutedRename(options: {
   const { manager, file, position, newName, control } = options;
   const client = await manager.ensureFileOpen(file, {
     recoverProcessCrash: true,
+    protectInputs: true,
     control,
   });
   if (!client) return null;

package/src/session/workspace-lsp-runtime.ts

@@ -143,7 +143,11 @@ export interface WorkspaceLspRuntime extends WorkspaceLspDiagnosticSurface {
     filePath: string,
     control?: CodeRequestControl,
   ): Promise<CodeQueryResult<DocumentSymbol[] | SymbolInformation[]>>;
-  /** Collect symbols from routes that can contribute within the optional path scopes. */
+  /**
+   * Collect symbols from contributing routes; completeness is relative to scopes.
+   * Data may include out-of-scope rows, which callers must filter themselves.
+   * Only policy exclusions proven outside every scope are irrelevant to completeness.
+   */
   workspaceSymbol(
     query: string,
     control?: CodeRequestControl,