@mrclrchtr/supi-code-intelligence 1.3.0 → 1.4.0

package/node_modules/@mrclrchtr/supi-lsp/src/lsp.ts

@@ -1,76 +1,71 @@
-// LSP Extension for pi — provides hover, definition, diagnostics, symbols, rename, code-actions
-// via a registered `lsp` tool. Keeps language servers warm, surfaces inline diagnostics,
-// and injects diagnostic context only when outstanding issues exist.
+// LSP Extension for pi — registers an expert semantic toolset, keeps language servers warm,
+// surfaces inline diagnostics, and injects diagnostic context only when outstanding issues exist.
 // biome-ignore-all lint/nursery/noExcessiveLinesPerFile: lsp.ts stays cohesive wiring; recovery and sentinel helpers live in focused modules.
 
 import * as path from "node:path";
-import { StringEnum } from "@earendil-works/pi-ai";
-import type { BeforeAgentStartEventResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  AgentEndEvent,
+  BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
+  ContextEvent,
+  ExtensionAPI,
+  ExtensionContext,
+  SessionStartEvent,
+  ToolResultEvent,
+} from "@earendil-works/pi-coding-agent";
 import { pruneAndReorderContextMessages, restorePromptContent } from "@mrclrchtr/supi-core/api";
-import { Type } from "typebox";
-import { loadConfig, resolveLanguageAlias } from "./config.ts";
-import { formatDiagnosticsDisplayContent } from "./diagnostics/diagnostic-display.ts";
-import { assessStaleDiagnostics } from "./diagnostics/stale-diagnostics.ts";
+import { loadConfig, resolveLanguageAlias } from "./config/config.ts";
+import { clearTsconfigCache } from "./config/tsconfig-scope.ts";
+import { FileChangeType } from "./config/types.ts";
 import {
-  buildProjectGuidelines,
   diagnosticsContextFingerprint,
   formatDiagnosticsContext,
-  lspPromptGuidelines,
-  lspPromptSnippet,
   MAX_DETAILED_DIAGNOSTICS,
-} from "./guidance.ts";
+} from "./diagnostics/diagnostic-context.ts";
+import { formatDiagnosticsDisplayContent } from "./diagnostics/diagnostic-display.ts";
+import { assessStaleDiagnostics } from "./diagnostics/stale-diagnostics.ts";
+import {
+  isWorkspaceRecoveryTrigger,
+  scanWorkspaceSentinels,
+  syncWorkspaceSentinelSnapshot,
+} from "./diagnostics/workspace-sentinels.ts";
+import { LspManager } from "./manager/manager.ts";
+import { forceResyncStaleModuleFiles } from "./manager/manager-stale-resync.ts";
 import {
   createRuntimeState,
   disableLspState,
-  ensureLspToolActive,
+  ensureLspToolsActive,
   isLspAwareTool,
   type LspRuntimeState,
   refreshProjectServers,
-  removeLspTool,
-} from "./lsp-state.ts";
-import { LspManager } from "./manager/manager.ts";
-import { forceResyncStaleModuleFiles } from "./manager/manager-stale-resync.ts";
-import { registerLspAwareToolOverrides } from "./overrides.ts";
-import { registerLspMessageRenderer } from "./renderer.ts";
-import { scanMissingServers, scanProjectCapabilities, startDetectedServers } from "./scanner.ts";
+  removeLspTools,
+} from "./session/lsp-state.ts";
+import {
+  scanMissingServers,
+  scanProjectCapabilities,
+  startDetectedServers,
+} from "./session/scanner.ts";
 import {
   clearSessionLspService,
   SessionLspService,
   setSessionLspServiceState,
-} from "./service-registry.ts";
+} from "./session/service-registry.ts";
 import {
   getLspDisabledMessage,
   loadLspSettings,
   registerLspSettings,
-} from "./settings-registration.ts";
-import { type LspAction, lspToolDescription, safeExecuteAction } from "./tool-actions.ts";
+} from "./session/settings-registration.ts";
 import {
   persistLspActiveState,
   persistLspInactiveState,
   registerTreePersistHandlers,
-} from "./tree-persist.ts";
-import { FileChangeType } from "./types.ts";
-import { toggleLspStatusOverlay, updateLspUi } from "./ui.ts";
-import { fileToUri } from "./utils.ts";
-import {
-  isWorkspaceRecoveryTrigger,
-  scanWorkspaceSentinels,
-  syncWorkspaceSentinelSnapshot,
-} from "./workspace-sentinels.ts";
-
-const LspActionEnum = StringEnum([
-  "hover",
-  "definition",
-  "references",
-  "diagnostics",
-  "symbols",
-  "rename",
-  "code_actions",
-  "workspace_symbol",
-  "search",
-  "symbol_hover",
-  "recover",
-] as const);
+} from "./session/tree-persist.ts";
+import { buildLspToolPromptSurfaces, defaultLspToolPromptSurfaces } from "./tool/guidance.ts";
+import { registerLspAwareToolOverrides } from "./tool/overrides.ts";
+import { registerLspTools } from "./tool/register-tools.ts";
+import { registerLspMessageRenderer } from "./ui/renderer.ts";
+import { toggleLspStatusOverlay, updateLspUi } from "./ui/ui.ts";
+import { fileToUri, resolveSessionPath } from "./utils.ts";
 
 export default function lspExtension(pi: ExtensionAPI) {
   registerLspSettings();
@@ -79,10 +74,10 @@ export default function lspExtension(pi: ExtensionAPI) {
   registerLspAwareToolOverrides(pi, {
     getInlineSeverity: () => state.inlineSeverity,
     getManager: () => state.manager,
-    getCwd: () => state.manager?.getCwd() ?? process.cwd(),
+    isActive: () => state.lspActive,
   });
 
-  registerLspTool(pi, state, lspPromptGuidelines);
+  registerLspTools(pi, defaultLspToolPromptSurfaces);
   registerSessionLifecycleHandlers(pi, state);
   registerBehaviorHandlers(pi, state);
   registerTreePersistHandlers(pi, state);
@@ -92,13 +87,14 @@ export default function lspExtension(pi: ExtensionAPI) {
 
 function registerSessionLifecycleHandlers(pi: ExtensionAPI, state: LspRuntimeState): void {
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: session_start orchestrates setup, server detection, settings, and persistence.
-  pi.on("session_start", async (_event, ctx) => {
+  pi.on("session_start", async (_event: SessionStartEvent, ctx: ExtensionContext) => {
     if (state.manager) {
       clearSessionLspService(state.manager.getCwd());
       await state.manager.shutdownAll();
     }
 
     const cwd = ctx.cwd;
+    clearTsconfigCache();
     const lspSettings = loadLspSettings(cwd);
 
     if (!lspSettings.enabled) {
@@ -151,13 +147,14 @@ function registerSessionLifecycleHandlers(pi: ExtensionAPI, state: LspRuntimeSta
       kind: "ready",
       service: new SessionLspService(state.manager),
     });
-    registerLspTool(pi, state, buildProjectGuidelines(state.projectServers, cwd));
-    ensureLspToolActive(pi);
+    registerLspTools(pi, buildLspToolPromptSurfaces(state.projectServers, cwd));
+    ensureLspToolsActive(pi);
     persistLspActiveState(pi, state);
     updateLspUi(ctx, state.manager, state.inlineSeverity, state.projectServers);
   });
 
   pi.on("session_shutdown", async () => {
+    clearTsconfigCache();
     if (state.manager) {
       clearSessionLspService(state.manager.getCwd());
       await state.manager.shutdownAll();
@@ -174,7 +171,7 @@ function registerSessionLifecycleHandlers(pi: ExtensionAPI, state: LspRuntimeSta
     state.sentinelSnapshot = new Map();
   });
 
-  pi.on("agent_end", async (_event, ctx) => {
+  pi.on("agent_end", async (_event: AgentEndEvent, ctx: ExtensionContext) => {
     state.currentContextToken = null;
     refreshProjectServers(state);
 
@@ -193,10 +190,11 @@ function markWorkspaceChange(state: LspRuntimeState): void {
 
 function softRecoverWorkspaceChanges(
   state: LspRuntimeState,
-  changes: import("./types.ts").FileEvent[],
+  changes: import("./config/types.ts").FileEvent[],
 ): boolean {
   if (!state.manager || changes.length === 0) return false;
 
+  clearTsconfigCache();
   state.manager.clearAllPullResultIds();
   state.manager.notifyWorkspaceFileChanges(changes);
   markWorkspaceChange(state);
@@ -209,6 +207,11 @@ function refreshWorkspaceSentinels(state: LspRuntimeState, cwd: string): boolean
   return softRecoverWorkspaceChanges(state, changes);
 }
 
+function shouldInvalidateTsconfigScopeCache(filePath: string): boolean {
+  const ext = path.extname(filePath).toLowerCase();
+  return ext === ".json" || ext === ".jsonc";
+}
+
 function recoverWorkspaceChangesFromToolResult(
   state: LspRuntimeState,
   cwd: string,
@@ -221,11 +224,14 @@ function recoverWorkspaceChangesFromToolResult(
   const pathValue = (event.input as { path?: unknown }).path;
   if (typeof pathValue !== "string") return false;
 
-  const resolvedPath = path.resolve(cwd, pathValue);
+  const resolvedPath = resolveSessionPath(cwd, pathValue);
+  if (shouldInvalidateTsconfigScopeCache(resolvedPath)) {
+    clearTsconfigCache();
+  }
   const fileEvent = { uri: fileToUri(resolvedPath), type: FileChangeType.Changed };
 
   // Sentinel files (package.json, tsconfig.json, lockfiles, .d.ts)
-  if (isWorkspaceRecoveryTrigger(pathValue, cwd)) {
+  if (isWorkspaceRecoveryTrigger(resolvedPath, cwd)) {
     if (resolvedPath.endsWith(".d.ts")) {
       return softRecoverWorkspaceChanges(state, [fileEvent]);
     }
@@ -236,7 +242,7 @@ function recoverWorkspaceChangesFromToolResult(
   }
 
   // Source files matching an active language server's file types
-  if (state.manager.hasServerForExtension(pathValue)) {
+  if (state.manager.hasServerForExtension(resolvedPath)) {
     return softRecoverWorkspaceChanges(state, [fileEvent]);
   }
 
@@ -247,7 +253,7 @@ function recoverWorkspaceChangesFromToolResult(
 // biome-ignore lint/complexity/useMaxParams: wrapper groups the prompt payload fields in one place.
 function buildDiagnosticResult(
   diagnostics: import("./manager/manager-types.ts").OutstandingDiagnosticSummaryEntry[],
-  detailed: { file: string; diagnostics: import("./types.ts").Diagnostic[] }[] | undefined,
+  detailed: { file: string; diagnostics: import("./config/types.ts").Diagnostic[] }[] | undefined,
   severity: number,
   token: string,
   staleWarning?: string | null,
@@ -276,16 +282,16 @@ function buildDiagnosticResult(
 
 function registerBehaviorHandlers(pi: ExtensionAPI, state: LspRuntimeState): void {
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: before_agent_start coordinates sentinel recovery, pruning, refresh, and diagnostic injection.
-  pi.on("before_agent_start", async (_event, ctx) => {
+  pi.on("before_agent_start", async (_event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
     if (!state.manager || !state.lspActive) {
-      removeLspTool(pi);
+      removeLspTools(pi);
       if (!state.manager && state.lspActive) {
         persistLspInactiveState(pi, state);
       }
       return;
     }
 
-    ensureLspToolActive(pi);
+    ensureLspToolsActive(pi);
 
     refreshWorkspaceSentinels(state, ctx.cwd);
 
@@ -348,18 +354,16 @@ function registerBehaviorHandlers(pi: ExtensionAPI, state: LspRuntimeState): voi
     state.lastDiagnosticsFingerprint = fingerprint;
     state.currentContextToken = `lsp-context-${++state.contextCounter}`;
 
-    const result = buildDiagnosticResult(
+    return buildDiagnosticResult(
       diagnostics,
       detailed,
       state.inlineSeverity,
       state.currentContextToken,
       staleWarning,
     );
-
-    return result;
   });
 
-  pi.on("context", (event) => {
+  pi.on("context", (event: ContextEvent) => {
     const messages = pruneAndReorderContextMessages(
       event.messages as Array<{
         role?: string;
@@ -378,14 +382,14 @@ function registerBehaviorHandlers(pi: ExtensionAPI, state: LspRuntimeState): voi
 
     if (
       contextMessages.length === event.messages.length &&
-      contextMessages.every((m, i) => m === event.messages[i])
+      contextMessages.every((message, index) => message === event.messages[index])
     ) {
       return;
     }
     return { messages: contextMessages };
   });
 
-  pi.on("tool_result", async (event, ctx) => {
+  pi.on("tool_result", async (event: ToolResultEvent, ctx: ExtensionContext) => {
     if (!state.manager) return;
 
     const recoveryTriggered = recoverWorkspaceChangesFromToolResult(state, ctx.cwd, {
@@ -401,62 +405,10 @@ function registerBehaviorHandlers(pi: ExtensionAPI, state: LspRuntimeState): voi
   });
 }
 
-function registerLspTool(
-  pi: ExtensionAPI,
-  state: LspRuntimeState,
-  promptGuidelines: string[],
-): void {
-  pi.registerTool({
-    name: "lsp",
-    label: "LSP",
-    description: lspToolDescription,
-    promptSnippet: lspPromptSnippet,
-    promptGuidelines,
-    parameters: Type.Object({
-      action: LspActionEnum,
-      file: Type.Optional(Type.String({ description: "File path (relative or absolute)" })),
-      line: Type.Optional(Type.Number({ description: "1-based line number" })),
-      character: Type.Optional(Type.Number({ description: "1-based column number" })),
-      newName: Type.Optional(Type.String({ description: "New name (for rename action)" })),
-      query: Type.Optional(
-        Type.String({ description: "Search query (for workspace_symbol and search actions)" }),
-      ),
-      symbol: Type.Optional(Type.String({ description: "Symbol name (for symbol_hover action)" })),
-    }),
-    // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      if (!state.manager) {
-        return {
-          content: [{ type: "text", text: "LSP not initialized. Start a new session first." }],
-          details: {},
-        };
-      }
-
-      const text = await safeExecuteAction(
-        state.manager,
-        params as {
-          action: LspAction;
-          file?: string;
-          line?: number;
-          character?: number;
-          newName?: string;
-          query?: string;
-          symbol?: string;
-        },
-      );
-
-      return {
-        content: [{ type: "text", text }],
-        details: {},
-      };
-    },
-  });
-}
-
 function registerLspStatusCommand(pi: ExtensionAPI, state: LspRuntimeState): void {
   pi.registerCommand("lsp-status", {
     description: "Show detected LSP servers, roots, open files, and diagnostics",
-    handler: async (_args, ctx) => {
+    handler: async (_args: string, ctx: ExtensionContext) => {
       const lspSettings = loadLspSettings(ctx.cwd);
       if (!lspSettings.enabled) {
         ctx.ui.notify(getLspDisabledMessage(ctx.cwd), "warning");

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-diagnostics.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs";
 import type { LspClient } from "../client/client.ts";
+import type { Diagnostic } from "../config/types.ts";
 import { relativeFilePathFromUri } from "../diagnostics/diagnostic-summary.ts";
 import { shouldIgnoreLspPath } from "../summary.ts";
-import type { Diagnostic } from "../types.ts";
 import { fileToUri, uriToFile } from "../utils.ts";
 import { isExcludedByPattern } from "./manager-helpers.ts";
 

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-helpers.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import * as projectRoots from "@mrclrchtr/supi-core/api";
 import { isGlobMatch } from "../pattern-matcher.ts";
+import { resolveSessionPath } from "../utils.ts";
 
 /** Unique key for a client identified by server name and root. */
 export function clientKey(serverName: string, root: string): string {
@@ -14,10 +15,11 @@ export function resolveRootForFile(
   rootMarkers: string[],
   opts: { knownRoots: Map<string, string[]>; cwd: string },
 ): string {
+  const resolvedFilePath = resolveSessionPath(opts.cwd, filePath);
   const preferredRoots = opts.knownRoots.get(serverName) ?? [];
-  const knownRoot = projectRoots.resolveKnownRoot(filePath, preferredRoots);
+  const knownRoot = projectRoots.resolveKnownRoot(resolvedFilePath, preferredRoots);
   if (knownRoot) return knownRoot;
-  const fileDir = path.dirname(path.resolve(filePath));
+  const fileDir = path.dirname(resolvedFilePath);
   return projectRoots.findProjectRoot(fileDir, rootMarkers, opts.cwd);
 }
 

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-project-info.ts

@@ -1,26 +1,27 @@
 import type { LspClient } from "../client/client.ts";
+import type { ProjectServerInfo } from "../config/types.ts";
 import { displayRelativeFilePath } from "../summary.ts";
-import type { ProjectServerInfo } from "../types.ts";
 
 interface ProjectServerInfoInput {
   serverName: string;
   root: string;
   fileTypes: string[];
   client: LspClient | undefined;
-  unavailable: boolean;
+  unavailableReason?: "missing-command" | "start-failed" | "runtime-error";
 }
 
 export function buildProjectServerInfo(
   input: ProjectServerInfoInput,
   cwd: string,
 ): ProjectServerInfo {
-  const status = input.unavailable
-    ? "unavailable"
-    : input.client?.status === "running"
+  const status =
+    input.client?.status === "running"
       ? "running"
-      : input.client?.status === "error"
+      : input.client?.status === "error" || input.unavailableReason === "start-failed"
         ? "error"
-        : "unavailable";
+        : input.unavailableReason === "runtime-error"
+          ? "error"
+          : "unavailable";
 
   return {
     name: input.serverName,
@@ -39,7 +40,9 @@ function getSupportedActions(capabilities: LspClient["serverCapabilities"] | und
   if (capabilities.hoverProvider) actions.push("hover(file,line,char)");
   if (capabilities.definitionProvider) actions.push("definition(file,line,char)");
   if (capabilities.referencesProvider) actions.push("references(file,line,char)");
+  if (capabilities.implementationProvider) actions.push("implementation(file,line,char)");
   if (capabilities.documentSymbolProvider) actions.push("symbols(file)");
+  if (capabilities.workspaceSymbolProvider) actions.push("workspace_symbols(query)");
   if (capabilities.renameProvider) actions.push("rename(file,line,char,newName)");
   if (capabilities.codeActionProvider) actions.push("code_actions(file,line,char)");
   return actions;

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-recovery.ts

@@ -1,8 +1,8 @@
+import type { Diagnostic, FileEvent } from "../config/types.ts";
 import {
   assessStaleDiagnostics,
   type StaleDiagnosticAssessment,
 } from "../diagnostics/stale-diagnostics.ts";
-import type { Diagnostic, FileEvent } from "../types.ts";
 
 export interface WorkspaceRecoveryResult {
   refreshedClients: number;

package/node_modules/@mrclrchtr/supi-lsp/src/manager/manager-workspace-symbol.ts

@@ -1,18 +1,170 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { walkProject } from "@mrclrchtr/supi-core/api";
 import type { LspClient } from "../client/client.ts";
-import type { SymbolInformation, WorkspaceSymbol } from "../types.ts";
+import type {
+  DocumentSymbol,
+  Position,
+  SymbolInformation,
+  WorkspaceSymbol,
+} from "../config/types.ts";
 
-export async function managerWorkspaceSymbol(
+type WorkspaceSymbolLike = SymbolInformation | WorkspaceSymbol;
+
+const SKIP_DIRS = new Set(["node_modules", ".git", ".pnpm", "dist", "build", "coverage"]);
+const DEFAULT_WARM_FILE_DEPTH = 4;
+const DEFAULT_MARKER_SCAN_DEPTH = 6;
+
+export interface WorkspaceSymbolWarmTarget {
+  projectRoot: string;
+  file: string;
+}
+
+export interface WorkspaceSymbolWarmOptions {
+  maxFileDepth?: number;
+  maxMarkerDepth?: number;
+}
+
+export function getWorkspaceSymbolWarmPosition(
+  symbols: DocumentSymbol[] | SymbolInformation[] | null,
+): Position | null {
+  if (!symbols || symbols.length === 0) return null;
+  const first = symbols[0];
+  if ("selectionRange" in first) {
+    return first.selectionRange.start;
+  }
+  if ("location" in first) {
+    return first.location.range.start;
+  }
+  return null;
+}
+
+export async function collectWorkspaceSymbols(
   clients: Iterable<LspClient>,
   query: string,
-): Promise<(SymbolInformation | WorkspaceSymbol)[] | null> {
-  const all: (SymbolInformation | WorkspaceSymbol)[] = [];
+): Promise<{ results: WorkspaceSymbolLike[]; hasSupport: boolean }> {
+  const results: WorkspaceSymbolLike[] = [];
   let hasSupport = false;
+
   for (const client of clients) {
     if (client.status !== "running") continue;
     if (!client.serverCapabilities?.workspaceSymbolProvider) continue;
     hasSupport = true;
     const result = await client.workspaceSymbol(query);
-    if (result) all.push(...result);
+    if (result) results.push(...result);
   }
-  return hasSupport ? all : null;
+
+  return { results, hasSupport };
+}
+
+export async function managerWorkspaceSymbol(
+  clients: Iterable<LspClient>,
+  query: string,
+): Promise<WorkspaceSymbolLike[] | null> {
+  const { results, hasSupport } = await collectWorkspaceSymbols(clients, query);
+  return hasSupport ? results : null;
+}
+
+export function findWorkspaceSymbolWarmTargets(
+  root: string,
+  rootMarkers: string[],
+  fileTypes: string[],
+  options: WorkspaceSymbolWarmOptions = {},
+): WorkspaceSymbolWarmTarget[] {
+  const resolvedRoot = path.resolve(root);
+  const allowed = new Set(fileTypes.map((fileType) => fileType.toLowerCase()));
+  const maxFileDepth = options.maxFileDepth ?? DEFAULT_WARM_FILE_DEPTH;
+  const maxMarkerDepth = options.maxMarkerDepth ?? DEFAULT_MARKER_SCAN_DEPTH;
+  if (allowed.size === 0) return [];
+
+  const markerRoots = collectMarkerRoots(resolvedRoot, rootMarkers, maxMarkerDepth);
+  const targets = markerRoots
+    .map((entry) => {
+      const file = findWarmFileRecursive(entry.root, allowed, maxFileDepth);
+      return file ? { projectRoot: entry.root, file, priority: entry.priority } : null;
+    })
+    .filter((entry): entry is { projectRoot: string; file: string; priority: number } =>
+      Boolean(entry),
+    )
+    .sort(
+      (a, b) =>
+        a.priority - b.priority ||
+        a.projectRoot.length - b.projectRoot.length ||
+        a.projectRoot.localeCompare(b.projectRoot),
+    )
+    .map(({ projectRoot, file }) => ({ projectRoot, file }));
+
+  if (targets.length > 0) return targets;
+
+  const fallback = findWarmFileRecursive(resolvedRoot, allowed, maxFileDepth);
+  return fallback ? [{ projectRoot: resolvedRoot, file: fallback }] : [];
+}
+
+interface MarkerRootEntry {
+  root: string;
+  priority: number;
+}
+
+function collectMarkerRoots(
+  root: string,
+  rootMarkers: string[],
+  maxDepth: number,
+): MarkerRootEntry[] {
+  if (rootMarkers.length === 0) return [];
+
+  const markerIndex = new Map(rootMarkers.map((marker, index) => [marker, index]));
+  const matches = new Map<string, number>();
+
+  walkProject(root, maxDepth, (directory, entryNames) => {
+    const matchedPriority = rootMarkers.reduce<number | null>((best, marker) => {
+      if (!entryNames.has(marker)) return best;
+      const next = markerIndex.get(marker) ?? Number.MAX_SAFE_INTEGER;
+      return best === null ? next : Math.min(best, next);
+    }, null);
+
+    if (matchedPriority === null) return;
+    const resolvedDirectory = path.resolve(directory);
+    const existing = matches.get(resolvedDirectory);
+    if (existing === undefined || matchedPriority < existing) {
+      matches.set(resolvedDirectory, matchedPriority);
+    }
+  });
+
+  return Array.from(matches.entries()).map(([matchedRoot, priority]) => ({
+    root: matchedRoot,
+    priority,
+  }));
+}
+
+function findWarmFileRecursive(
+  directory: string,
+  allowed: Set<string>,
+  depth: number,
+): string | null {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const sortedEntries = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of sortedEntries) {
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name).slice(1).toLowerCase();
+    if (!allowed.has(ext)) continue;
+    return path.join(directory, entry.name);
+  }
+
+  if (depth <= 0) return null;
+
+  for (const entry of sortedEntries) {
+    if (!entry.isDirectory()) continue;
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const nested = findWarmFileRecursive(path.join(directory, entry.name), allowed, depth - 1);
+    if (nested) return nested;
+  }
+
+  return null;
 }