@mrclrchtr/supi-code-intelligence 4.10.0 → 6.0.0

package/src/substrate/lsp/maintenance.ts

@@ -6,70 +6,326 @@
  * semantic tool queries.
  */
 
+import { statSync } from "node:fs";
 import * as nodePath from "node:path";
-import type { WorkspaceLspRuntime } from "@mrclrchtr/supi-lsp/api";
 import {
-  clearTsconfigCache,
+  type CodeRequestControl,
+  isCodeRequestInterruption,
+  throwIfCodeRequestInterrupted,
+} from "@mrclrchtr/supi-code-runtime/api";
+import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
+import { uriToFile } from "@mrclrchtr/supi-core/path";
+import type { DiagnosticEvidenceSummary } from "@mrclrchtr/supi-lsp/api";
+import {
+  FileChangeType,
+  type FileEvent,
+  invalidateTsconfigCacheForConfig,
+  invalidateTsconfigCacheForConfigDir,
   isLikelyStaleDiagnostic,
+  isProjectConfigFileName,
+  raceRequestControl,
   syncWorkspaceSentinelSnapshot,
+  type WorkspaceLspRuntime,
 } from "@mrclrchtr/supi-lsp/api";
+import { mergeDiagnosticEvidence } from "../../diagnostics/evidence.ts";
+
+/** Options shared by the workspace and file-scoped maintenance passes. */
+export interface LspMaintenanceOptions {
+  control?: CodeRequestControl;
+  /**
+   * Workspace-relative scope prefix for source-file discovery. Discovery only
+   * tracks created files inside this prefix; null disables the scope bound.
+   */
+  scope?: string | null;
+  /**
+   * Track files created since the last refresh so the following refresh pull
+   * includes them. Only the workspace-runtime path sets this; the snapshot is
+   * still widened on file-scoped passes so later diffs stay correct.
+   */
+  trackSources?: boolean;
+}
 
 /**
- * Run sentinel-sync, stale-module resync, prune, and diagnostic refresh
- * as a single maintenance pass. Call before explicit diagnostic queries
- * (code_health with refresh:true) or semantic tool readiness checks.
+ * Run sentinel-sync, diagnostic refresh, and stale-module resync as a single
+ * maintenance pass. Call before explicit diagnostic queries (code_health with
+ * refresh:true) or semantic tool readiness checks.
  */
 export async function refreshLspMaintenance(
   runtime: WorkspaceLspRuntime,
   cwd: string,
   sentinelSnapshot: Map<string, number>,
-): Promise<Map<string, number>> {
-  // Sentinel refresh: detect lockfile/tsconfig/d.ts changes from outside
-  // write/edit/code_refactor_apply.
-  const { snapshot, changes } = syncWorkspaceSentinelSnapshot(cwd, sentinelSnapshot);
-
-  if (changes.length > 0) {
-    clearTsconfigCache();
-    runtime.noteWorkspaceChanges(changes);
+  options: LspMaintenanceOptions = {},
+): Promise<WorkspaceLspMaintenanceResult> {
+  const { snapshot } = await synchronizeSentinels(runtime, cwd, sentinelSnapshot, options);
+  let diagnosticEvidence = emptyEvidence();
+  let failureReason: string | undefined;
+
+  // Refresh before stale-module inspection. The refresh owns deleted-file
+  // classification; later snapshots must not erase its removed evidence.
+  try {
+    diagnosticEvidence = await runtime.refreshOpenDiagnostics(undefined, options.control);
+  } catch (error) {
+    if (isCodeRequestInterruption(error, options.control)) throw error;
+    failureReason = errorMessage(error);
+    diagnosticEvidence = readRuntimeEvidence(runtime);
   }
 
-  // Stale-module resync: force-reopen files with "Cannot find module" errors
-  await resyncStaleModuleFiles(runtime, cwd);
+  try {
+    const staleResult = await resyncStaleModuleFiles(runtime, cwd, options.control);
+    diagnosticEvidence = mergeDiagnosticEvidence(diagnosticEvidence, staleResult.evidence, cwd);
+    if (staleResult.completed) failureReason = undefined;
+  } catch (error) {
+    if (isCodeRequestInterruption(error, options.control)) throw error;
+    // Keep evidence from the first refresh when stale inspection fails.
+  }
+
+  return {
+    snapshot,
+    diagnosticEvidence,
+    ...(failureReason ? { failureReason } : {}),
+  };
+}
+
+/** Sentinel state and diagnostic evidence retained from one workspace pass. */
+export interface WorkspaceLspMaintenanceResult {
+  /** The next sentinel snapshot for the session-owned maintenance state. */
+  snapshot: Map<string, number>;
+  /** Evidence from every diagnostic refresh performed by this pass. */
+  diagnosticEvidence: DiagnosticEvidenceSummary;
+  /** Failure from the first workspace refresh, when no fresh pass completed. */
+  failureReason?: string;
+}
+
+/** Sentinel state and stale-file facts from one file-scoped pass. */
+export interface FileLspMaintenanceResult {
+  /** The next sentinel snapshot for the session-owned maintenance state. */
+  snapshot: Map<string, number>;
+  /** Number of stale files that matched the requested file. */
+  matchedStaleFileCount: number;
+}
+
+/** Refresh sentinel and stale-module state for one exact file without a workspace resync. */
+export async function refreshFileLspMaintenance(options: {
+  runtime: WorkspaceLspRuntime;
+  cwd: string;
+  sentinelSnapshot: Map<string, number>;
+  filePath: string;
+  control?: CodeRequestControl;
+}): Promise<FileLspMaintenanceResult> {
+  const { runtime, cwd, sentinelSnapshot, filePath, control } = options;
+  // A cancelled caller stops before any maintenance work starts.
+  throwIfCodeRequestInterrupted(control);
+  const { snapshot } = await synchronizeSentinels(runtime, cwd, sentinelSnapshot);
+  const target = nodePath.resolve(filePath);
+  const stale = confirmedOutstandingDiagnostics(runtime, cwd).some(
+    (entry) =>
+      nodePath.resolve(cwd, entry.file) === target &&
+      entry.diagnostics.some((diagnostic) => isLikelyStaleDiagnostic(diagnostic)),
+  );
 
-  // Two-pass prune/refresh for diagnostics
   runtime.pruneMissingFiles();
-  try {
-    await runtime.refreshOpenDiagnostics();
-  } catch {
-    /* best-effort */
+  if (stale) {
+    runtime.closeFile(target);
+    // Race the caller's cancellation so a client start during re-open does
+    // not outlive the caller; the underlying runtime keeps its own lifecycle.
+    await raceRequestControl(runtime.trackFile(target), control);
   }
   runtime.pruneMissingFiles();
+  throwIfCodeRequestInterrupted(control);
+
+  return { snapshot, matchedStaleFileCount: stale ? 1 : 0 };
+}
+
+/**
+ * Sync the widened workspace snapshot, forward sentinel changes, and track
+ * source files newly created since the last pass.
+ *
+ * The snapshot is widened to every regular file on every pass so later diffs
+ * see genuine creations. Only sentinel-file events are forwarded as workspace
+ * changes (config semantics unchanged); created source files are tracked only
+ * on the workspace-runtime path and only once the snapshot was primed by an
+ * earlier pass — the first pass establishes the baseline and cannot tell a
+ * just-created file from a long-existing one.
+ */
+async function synchronizeSentinels(
+  runtime: WorkspaceLspRuntime,
+  cwd: string,
+  sentinelSnapshot: Map<string, number>,
+  options: LspMaintenanceOptions = {},
+) {
+  const primed = sentinelSnapshot.size > 0;
+  const state = syncWorkspaceSentinelSnapshot(cwd, sentinelSnapshot, {
+    includeSourceFiles: true,
+  });
+
+  invalidateChangedProjectConfigs(state.changes);
+  if (state.changes.length > 0) runtime.noteWorkspaceChanges(state.changes);
+
+  if (options.trackSources && primed) {
+    await trackCreatedSourceFiles(runtime, state.sourceChanges, options.scope);
+  }
+
+  return state;
+}
+
+/** Invalidate cached tsconfig scope parses only for config files that changed. */
+function invalidateChangedProjectConfigs(changes: readonly FileEvent[]): void {
+  for (const change of changes) {
+    const filePath = uriToFile(change.uri);
+    if (!isProjectConfigFileName(nodePath.basename(filePath))) continue;
+    // Change-targeted invalidation: only config files affect tsconfig scope
+    // decisions. A created config can also turn previously empty lookups into
+    // resolved ones below the new config's directory.
+    invalidateTsconfigCacheForConfig(filePath);
+    if (change.type === FileChangeType.Created) {
+      invalidateTsconfigCacheForConfigDir(nodePath.dirname(filePath));
+    }
+  }
+}
 
-  return snapshot;
+/** Track source files newly created since the last pass, within the scope bound. */
+async function trackCreatedSourceFiles(
+  runtime: WorkspaceLspRuntime,
+  sourceChanges: readonly FileEvent[],
+  scope: string | null | undefined,
+): Promise<void> {
+  for (const change of sourceChanges) {
+    if (change.type !== FileChangeType.Created) continue;
+    const filePath = uriToFile(change.uri);
+    if (scope && !isWithinOrEqual(scope, filePath)) continue;
+    // Best-effort: a file no client can serve stays untracked and is
+    // simply absent from evidence until a later explicit request.
+    await runtime.trackFile(filePath);
+  }
 }
 
-/** Re-open files with stale module-resolution errors. */
-async function resyncStaleModuleFiles(runtime: WorkspaceLspRuntime, cwd: string): Promise<void> {
+/** Return only diagnostics whose document evidence is confirmed. */
+function confirmedOutstandingDiagnostics(runtime: WorkspaceLspRuntime, cwd: string) {
   const outstanding = runtime.getOutstandingDiagnostics(1);
+  const confirmedFiles = new Set(
+    outstanding.evidence.documents
+      .filter((document) => document.status === "confirmed")
+      .map((document) => nodePath.resolve(cwd, document.file)),
+  );
+  return outstanding.entries.filter((entry) =>
+    confirmedFiles.has(nodePath.resolve(cwd, entry.file)),
+  );
+}
+
+/** Re-open files with confirmed stale module-resolution errors. */
+async function resyncStaleModuleFiles(
+  runtime: WorkspaceLspRuntime,
+  cwd: string,
+  control?: CodeRequestControl,
+): Promise<{ evidence: DiagnosticEvidenceSummary; completed: boolean }> {
   const staleFiles: string[] = [];
 
-  for (const entry of outstanding) {
+  for (const entry of confirmedOutstandingDiagnostics(runtime, cwd)) {
     if (entry.diagnostics.some((d) => isLikelyStaleDiagnostic(d))) {
       staleFiles.push(entry.file);
     }
   }
 
-  if (staleFiles.length === 0) return;
+  if (staleFiles.length === 0) return { evidence: emptyEvidence(), completed: false };
 
+  const invalidated: Array<{
+    file: string;
+    status: "unconfirmed" | "failed" | "removed";
+  }> = staleFiles.map((file) => ({
+    file: nodePath.relative(cwd, nodePath.resolve(cwd, file)),
+    status: "unconfirmed",
+  }));
   for (const file of staleFiles) {
     const filePath = nodePath.resolve(cwd, file);
+    const relativeFile = nodePath.relative(cwd, filePath);
     runtime.closeFile(filePath);
-    await runtime.trackFile(filePath);
+    try {
+      if (!(await runtime.trackFile(filePath))) {
+        markUnavailable(invalidated, relativeFile, filePath);
+      }
+    } catch (error) {
+      if (isCodeRequestInterruption(error, control)) throw error;
+      markUnavailable(invalidated, relativeFile, filePath);
+    }
   }
 
   try {
-    await runtime.refreshOpenDiagnostics({ quietMs: 300, maxWaitMs: 2000 });
+    return {
+      evidence: mergeDiagnosticEvidence(
+        {
+          requested: invalidated.length,
+          confirmed: 0,
+          unconfirmed: invalidated.length,
+          failed: 0,
+          removed: 0,
+          documents: invalidated,
+        },
+        await runtime.refreshOpenDiagnostics({ quietMs: 300, maxWaitMs: 2000 }, control),
+        cwd,
+      ),
+      completed: true,
+    };
+  } catch (error) {
+    if (isCodeRequestInterruption(error, control)) throw error;
+    return {
+      evidence: {
+        requested: invalidated.length,
+        confirmed: 0,
+        unconfirmed: invalidated.filter((document) => document.status === "unconfirmed").length,
+        failed: invalidated.filter((document) => document.status === "failed").length,
+        removed: invalidated.filter((document) => document.status === "removed").length,
+        documents: invalidated,
+      },
+      completed: false,
+    };
+  }
+}
+
+function markUnavailable(
+  documents: Array<{ file: string; status: "unconfirmed" | "failed" | "removed" }>,
+  file: string,
+  filePath: string,
+): void {
+  const entry = documents.find((document) => document.file === file);
+  if (entry) entry.status = diagnosticFailureStatus(filePath);
+}
+
+function diagnosticFailureStatus(filePath: string): "failed" | "removed" {
+  try {
+    statSync(filePath);
+    return "failed";
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error.code === "ENOENT" || error.code === "ENOTDIR")
+    ) {
+      return "removed";
+    }
+    return "failed";
+  }
+}
+
+function readRuntimeEvidence(runtime: WorkspaceLspRuntime): DiagnosticEvidenceSummary {
+  try {
+    return runtime.getWorkspaceDiagnosticSummary().evidence;
   } catch {
-    /* best-effort */
+    return emptyEvidence();
   }
 }
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : "Diagnostic refresh failed.";
+}
+
+function emptyEvidence(): DiagnosticEvidenceSummary {
+  return {
+    requested: 0,
+    confirmed: 0,
+    unconfirmed: 0,
+    failed: 0,
+    removed: 0,
+    documents: [],
+  };
+}

package/src/substrate/lsp/recovery.ts

@@ -11,7 +11,11 @@ import type {
   ToolResultEvent,
 } from "@earendil-works/pi-coding-agent";
 import { fileToUri } from "@mrclrchtr/supi-core/path";
-import { clearTsconfigCache } from "@mrclrchtr/supi-lsp/api";
+import {
+  invalidateTsconfigCacheForConfig,
+  invalidateTsconfigCacheForConfigDir,
+  isProjectConfigFileName,
+} from "@mrclrchtr/supi-lsp/api";
 import type { LspAdapterState } from "./state.ts";
 
 /** Tool names whose successful results should trigger workspace change notifications. */
@@ -37,10 +41,12 @@ export function registerWorkspaceRecoveryHandler(pi: ExtensionAPI, state: LspAda
       const normalized = filePath.startsWith("@") ? filePath.slice(1) : filePath;
       const resolved = nodePath.resolve(cwd, normalized);
 
-      // Invalidate tsconfig cache when config files change
-      const ext = nodePath.extname(resolved).toLowerCase();
-      if (ext === ".json" || ext === ".jsonc") {
-        clearTsconfigCache();
+      // Invalidate the tsconfig scope cache only when a project config itself
+      // changed; other .json/.jsonc writes (package.json and friends) do not
+      // affect scope decisions and keep their cached parses.
+      if (isProjectConfigFileName(nodePath.basename(resolved))) {
+        invalidateTsconfigCacheForConfig(resolved);
+        invalidateTsconfigCacheForConfigDir(nodePath.dirname(resolved));
       }
 
       runtime.noteWorkspaceChanges([{ uri: fileToUri(resolved), type: 2 }]);

package/src/substrate/lsp/state.ts

@@ -25,7 +25,7 @@ export interface LspAdapterState {
   lspActive: boolean;
   /** Snapshot of workspace sentinel files (package.json, tsconfig, lockfiles) for change detection. */
   sentinelSnapshot: Map<string, number>;
-  /** Fired when server statuses or readiness change — footer listens for re-renders. */
+  /** Fired for runtime lifecycle changes that require a footer render. */
   stateChanges: EventTarget;
 }
 
@@ -40,5 +40,5 @@ export function createLspAdapterState(): LspAdapterState {
   };
 }
 
-/** Event type dispatched on {@link LspAdapterState.stateChanges} when server statuses change. */
+/** Event type dispatched on {@link LspAdapterState.stateChanges} for LSP lifecycle changes. */
 export const LSP_STATE_CHANGE_EVENT = "server-status-changed" as const;

package/src/substrate/workspace-provider-host.ts

@@ -5,9 +5,11 @@ import { LspRuntimeController, scanWorkspaceSentinels } from "@mrclrchtr/supi-ls
 import { TreeSitterRuntimeController } from "@mrclrchtr/supi-tree-sitter/api";
 
 const HOSTS = Symbol.for("supi-code-intelligence/workspace-provider-hosts");
+const CLOSING_HOSTS = Symbol.for("supi-code-intelligence/closing-workspace-provider-hosts");
 const SHUTDOWN_GRACE_MS = 2_000;
 
 type HostRegistry = Map<string, WorkspaceProviderHost>;
+type ClosingHostRegistry = Map<string, Promise<void>>;
 
 /** One acquired reference to a process-shared Workspace provider host. */
 export interface WorkspaceProviderHostLease {
@@ -23,6 +25,12 @@ function registry(): HostRegistry {
   return global[HOSTS];
 }
 
+function closingRegistry(): ClosingHostRegistry {
+  const global = globalThis as typeof globalThis & { [CLOSING_HOSTS]?: ClosingHostRegistry };
+  global[CLOSING_HOSTS] ??= new Map();
+  return global[CLOSING_HOSTS];
+}
+
 function canonicalWorkspace(cwd: string): string {
   try {
     return realpathSync(cwd);
@@ -76,8 +84,16 @@ class WorkspaceProviderHost {
         released = true;
         this.#leases--;
         if (this.#leases === 0) {
-          registry().delete(this.cwd);
-          await this.#shutdown();
+          await Promise.resolve();
+          if (this.#leases !== 0) return;
+          const shutdown = this.#shutdown();
+          closingRegistry().set(this.cwd, shutdown);
+          try {
+            await shutdown;
+          } finally {
+            if (closingRegistry().get(this.cwd) === shutdown) closingRegistry().delete(this.cwd);
+            registry().delete(this.cwd);
+          }
         }
       },
     };
@@ -101,7 +117,7 @@ class WorkspaceProviderHost {
     this.#closed = true;
     await Promise.all([
       ...(this.#lsp ? [settleWithin(this.#lsp.shutdown())] : []),
-      ...(this.#tree ? [settleWithin(this.#tree.shutdown())] : []),
+      ...(this.#tree ? [this.#tree.shutdown()] : []),
     ]);
     this.#lsp = null;
     this.#tree = null;
@@ -114,6 +130,11 @@ export async function acquireWorkspaceProviderHost(
   options: { projectTrusted: boolean },
 ): Promise<WorkspaceProviderHostLease> {
   const workspace = canonicalWorkspace(cwd);
+  for (;;) {
+    const closing = closingRegistry().get(workspace);
+    if (!closing) break;
+    await closing.catch(() => undefined);
+  }
   const hosts = registry();
   let host = hosts.get(workspace);
   if (!host) {
@@ -126,4 +147,5 @@ export async function acquireWorkspaceProviderHost(
 /** Clear process-shared hosts between isolated tests. */
 export function resetWorkspaceProviderHostsForTests(): void {
   registry().clear();
+  closingRegistry().clear();
 }

package/src/tool/{find → code_find}/execute.ts

@@ -3,10 +3,8 @@
 import type { FindMode, FindWorkflowInput } from "../../session/find-types.ts";
 import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
 import { toWorkflowControl } from "../infra/workflow-control.ts";
-import { searchErrorResult } from "../result/errors.ts";
-import { assembleFindWorkflowResult } from "../result/find.ts";
 import type { CodeFindAstKind } from "./ast-kinds.ts";
-import { renderFindResult } from "./render.ts";
+import { finishFindResult } from "./result.ts";
 
 export interface CodeFindToolParams {
   query: string;
@@ -21,17 +19,5 @@ export async function executeFindTool(
   ctx: CodeIntelToolExecCtx,
 ): Promise<CodeIntelResult> {
   const outcome = await ctx.session.find(params as FindWorkflowInput, toWorkflowControl(ctx));
-  if (outcome.kind === "unavailable") throw new Error(outcome.reason);
-  if (outcome.kind === "invalid-input") {
-    return searchErrorResult(`**Error:** ${outcome.message}`, {
-      scope: Array.isArray(params?.scope) ? params.scope.join(", ") : null,
-      nextQueries: ["Fix the search input and retry"],
-    });
-  }
-
-  const assembly = assembleFindWorkflowResult(outcome);
-  return {
-    content: renderFindResult(assembly),
-    details: { type: "search", data: assembly.details },
-  };
+  return finishFindResult(outcome, params.scope);
 }

package/src/tool/code_find/guidance.ts

@@ -0,0 +1,8 @@
+export const toolDescription =
+  'Search source shape with mode:"ast" or LSP workspace symbols with mode:"semantic". Modes never silently fall back. Unscoped AST scans cover visible supported files, skipping hidden and generated/dependency directories.';
+
+export const promptSnippet = "explicit structural or semantic code search";
+
+export const promptGuidelines = [
+  "Use code_find for structural or semantic search evidence; use PI grep for literal/regex source search and code_graph references for symbol-identity relationships.",
+];

package/src/tool/{find → code_find}/render.ts

@@ -4,8 +4,8 @@ import {
   type EvidenceListMetadata,
   renderEvidenceListMetadataDisclosure,
 } from "../../analysis/evidence.ts";
-import type { FindResultAssembly } from "../result/find.ts";
 import { renderStructuredEmptyState, renderStructuredMatches } from "./markdown.ts";
+import type { FindResultAssembly } from "./result.ts";
 
 export function renderFindResult(assembly: FindResultAssembly): string {
   const { outcome } = assembly;
@@ -38,9 +38,7 @@ function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMeta
   const { outcome } = assembly;
   if (outcome.data.kind !== "semantic") return "";
   const symbols = outcome.data.symbols;
-  if (symbols.length === 0) {
-    return `**Semantic search** — \`${outcome.query}\`\n\nNo semantic results found in \`${outcome.scopeLabel}\`.`;
-  }
+  if (symbols.length === 0) return renderEmptySemantic(assembly, evidence);
 
   const lines = [
     `**Semantic search** — \`${outcome.query}\` (${symbols.length} symbol${symbols.length === 1 ? "" : "s"} found)`,
@@ -55,3 +53,22 @@ function renderSemantic(assembly: FindResultAssembly, evidence: EvidenceListMeta
   if (disclosure) lines.push(disclosure);
   return lines.join("\n");
 }
+
+function renderEmptySemantic(assembly: FindResultAssembly, evidence: EvidenceListMetadata): string {
+  const { outcome } = assembly;
+  const lines = [
+    `**Semantic search** — \`${outcome.query}\``,
+    "",
+    evidence.partialReason
+      ? `No LSP workspace-symbol results were collected in \`${outcome.scopeLabel}\`.`
+      : `No LSP workspace-symbol results found in \`${outcome.scopeLabel}\`.`,
+  ];
+  const disclosure = renderEvidenceListMetadataDisclosure(evidence);
+  if (disclosure) lines.push("", disclosure);
+  lines.push("", "Document-level semantic symbols can differ from the workspace index.");
+  const fileQuery = assembly.assembled.actions.find(
+    (action) => action.kind === "query" && action.instruction.startsWith("If you know the file"),
+  );
+  if (fileQuery?.kind === "query") lines.push(fileQuery.instruction);
+  return lines.join("\n");
+}