@mrclrchtr/supi-lsp 0.1.0 → 1.0.0

package/{types.ts → src/types.ts}

@@ -1,5 +1,6 @@
 // LSP protocol types — minimal subset needed for our client.
 // Based on the Language Server Protocol specification.
+// biome-ignore-all lint/nursery/noExcessiveLinesPerFile: protocol types are intentionally centralized in one catalog file.
 
 // ── Positions & Ranges ────────────────────────────────────────────────
 
@@ -130,6 +131,15 @@ export interface SymbolInformation {
   containerName?: string;
 }
 
+export interface WorkspaceSymbol {
+  name: string;
+  kind: SymbolKind;
+  location: Location;
+  containerName?: string;
+  /** LSP 3.17+ extra data for resolve support */
+  data?: unknown;
+}
+
 // ── Code Actions ──────────────────────────────────────────────────────
 
 export interface CodeActionContext {
@@ -160,6 +170,73 @@ export interface PublishDiagnosticsParams {
   diagnostics: Diagnostic[];
 }
 
+export const FileChangeType = {
+  Created: 1,
+  Changed: 2,
+  Deleted: 3,
+} as const;
+export type FileChangeType = (typeof FileChangeType)[keyof typeof FileChangeType];
+
+export interface FileEvent {
+  uri: string;
+  type: FileChangeType;
+}
+
+export interface DidChangeWatchedFilesParams {
+  changes: FileEvent[];
+}
+
+// ── LSP 3.17 Pull Diagnostics ─────────────────────────────────────────
+
+export interface DocumentDiagnosticParams {
+  textDocument: TextDocumentIdentifier;
+  identifier?: string;
+  previousResultId?: string;
+  workDoneToken?: unknown;
+  partialResultToken?: unknown;
+}
+
+/** LSP 3.17 document diagnostic report shape used by textDocument/diagnostic. */
+export type DocumentDiagnosticReport =
+  | RelatedFullDocumentDiagnosticReport
+  | RelatedUnchangedDocumentDiagnosticReport;
+
+/** Full document diagnostic report, optionally carrying related document reports. */
+export interface RelatedFullDocumentDiagnosticReport extends FullDocumentDiagnosticReport {
+  relatedDocuments?: Record<
+    string,
+    FullDocumentDiagnosticReport | UnchangedDocumentDiagnosticReport
+  >;
+}
+
+/** Unchanged document diagnostic report, optionally carrying related document reports. */
+export interface RelatedUnchangedDocumentDiagnosticReport
+  extends UnchangedDocumentDiagnosticReport {
+  relatedDocuments?: Record<
+    string,
+    FullDocumentDiagnosticReport | UnchangedDocumentDiagnosticReport
+  >;
+}
+
+/** Full diagnostic payload for a document. */
+export interface FullDocumentDiagnosticReport {
+  kind: "full";
+  resultId?: string;
+  items: Diagnostic[];
+}
+
+/** Result-id-only report indicating a document's diagnostics are unchanged. */
+export interface UnchangedDocumentDiagnosticReport {
+  kind: "unchanged";
+  resultId: string;
+}
+
+/** Client capability for pull diagnostics. */
+export interface ClientDiagnosticCapabilities {
+  dynamicRegistration?: boolean;
+  relatedDocumentSupport?: boolean;
+}
+
 // ── Initialize ────────────────────────────────────────────────────────
 
 export interface InitializeParams {
@@ -202,10 +279,16 @@ export interface ClientCapabilities {
     };
     publishDiagnostics?: {
       relatedInformation?: boolean;
+      versionSupport?: boolean;
     };
+    /** LSP 3.17+ pull diagnostic capability */
+    diagnostic?: ClientDiagnosticCapabilities;
   };
   workspace?: {
     workspaceFolders?: boolean;
+    diagnostics?: {
+      refreshSupport?: boolean;
+    };
   };
 }
 
@@ -219,8 +302,25 @@ export interface ServerCapabilities {
   definitionProvider?: boolean;
   referencesProvider?: boolean;
   documentSymbolProvider?: boolean;
+  workspaceSymbolProvider?: boolean;
   renameProvider?: boolean | { prepareProvider?: boolean };
   codeActionProvider?: boolean | { codeActionKinds?: string[] };
+  implementationProvider?: boolean;
+  /** LSP 3.17+ pull diagnostic support */
+  diagnosticProvider?:
+    | boolean
+    | {
+        /** Document diagnostic provider */
+        documentIdentifierProvider?: boolean | { workDoneProgress?: boolean };
+        /** Workspace diagnostic provider */
+        workspaceDiagnostics?: boolean | { workDoneProgress?: boolean };
+        /** Identifier for result sets */
+        identifierSet?: boolean;
+        /** Inter-file dependency support */
+        interFileDependencies?: boolean;
+        /** Workspace-wide multi-file support */
+        workspaceDiagnosticsSupport?: boolean;
+      };
 }
 
 // ── Text Document Items ───────────────────────────────────────────────
@@ -281,6 +381,29 @@ export interface ServerConfig {
   initializationOptions?: unknown;
 }
 
+/** LSP configuration keyed by language name (e.g. `typescript`, `python`). */
 export interface LspConfig {
   servers: Record<string, ServerConfig>;
 }
+
+export interface DetectedProjectServer {
+  name: string;
+  root: string;
+  fileTypes: string[];
+}
+
+export interface ProjectServerInfo extends DetectedProjectServer {
+  status: "running" | "error" | "unavailable";
+  supportedActions: string[];
+  openFiles: string[];
+}
+
+/** A language whose source files are present but the server binary is missing. */
+export interface MissingServer {
+  /** Language name (e.g. "python", "rust"). */
+  name: string;
+  /** Server command that was not found on PATH. */
+  command: string;
+  /** File extensions found in the project (subset of server.fileTypes). */
+  foundExtensions: string[];
+}

package/src/ui.ts

@@ -0,0 +1,358 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import type { OverlayHandle } from "@earendil-works/pi-tui";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import type { LspManager } from "./manager/manager.ts";
+import type { OutstandingDiagnosticSummaryEntry } from "./manager/manager-types.ts";
+import type { Diagnostic, ProjectServerInfo } from "./types.ts";
+import { DiagnosticSeverity } from "./types.ts";
+
+export interface LspInspectorState {
+  handle: OverlayHandle | null;
+  close: (() => void) | null;
+}
+
+export function updateLspUi(
+  ctx: ExtensionContext,
+  manager: LspManager,
+  inlineSeverity: number,
+  servers: ProjectServerInfo[],
+): void {
+  const diagnostics = manager.getOutstandingDiagnosticSummary(inlineSeverity);
+
+  ctx.ui.setStatus("lsp", buildLspStatus(ctx, servers, diagnostics));
+  ctx.ui.setWidget(
+    "lsp",
+    hasWidgetContent(diagnostics)
+      ? (_tui, theme) => buildLspWidgetComponent(theme, diagnostics)
+      : undefined,
+    { placement: "belowEditor" },
+  );
+}
+
+// biome-ignore lint/complexity/useMaxParams: overlay inputs travel together
+export function toggleLspStatusOverlay(
+  ctx: ExtensionContext,
+  manager: LspManager,
+  inlineSeverity: number,
+  inspector: LspInspectorState,
+  servers: ProjectServerInfo[],
+): void {
+  if (inspector.handle && inspector.close) {
+    inspector.close();
+    return;
+  }
+
+  void ctx.ui
+    .custom<void>(
+      (_tui, theme, _kb, done) => {
+        inspector.close = () => done(undefined);
+        return createLspInspectorComponent(theme, manager, inlineSeverity, servers);
+      },
+      {
+        overlay: true,
+        overlayOptions: {
+          anchor: "right-center",
+          width: "60%",
+          minWidth: 72,
+          maxHeight: "90%",
+          margin: { right: 1, top: 1, bottom: 1 },
+          nonCapturing: true,
+        },
+        onHandle: (handle) => {
+          inspector.handle = handle;
+        },
+      },
+    )
+    .finally(() => {
+      inspector.handle = null;
+      inspector.close = null;
+    });
+}
+
+function createLspInspectorComponent(
+  theme: ExtensionContext["ui"]["theme"],
+  manager: LspManager,
+  inlineSeverity: number,
+  servers: ProjectServerInfo[],
+): { render: (width: number) => string[]; invalidate: () => void } {
+  return {
+    render: (width) =>
+      buildLspInspectorContainer({
+        theme,
+        manager,
+        inlineSeverity,
+        servers,
+        width,
+      }).render(width),
+    invalidate: () => {},
+  };
+}
+
+interface LspInspectorContainerInput {
+  theme: ExtensionContext["ui"]["theme"];
+  manager: LspManager;
+  inlineSeverity: number;
+  servers: ProjectServerInfo[];
+  width: number;
+}
+
+function buildLspInspectorContainer(input: LspInspectorContainerInput): Container {
+  const diagnostics = input.manager.getOutstandingDiagnosticSummary(input.inlineSeverity);
+  const detailedDiagnostics = input.manager.getOutstandingDiagnostics(input.inlineSeverity);
+  const container = new Container();
+
+  const { theme, servers, width } = input;
+
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+  container.addChild(
+    new Text(
+      theme.fg("accent", theme.bold(" λ LSP")) + theme.fg("dim", " inspector  /lsp-status toggles"),
+      1,
+      0,
+    ),
+  );
+
+  if (servers.length === 0 && diagnostics.length === 0) {
+    container.addChild(
+      new Text(theme.fg("dim", "no LSP servers available for this project"), 1, 0),
+    );
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    return container;
+  }
+
+  container.addChild(new Text(buildOverlaySummaryLine(theme, servers, diagnostics), 1, 0));
+  container.addChild(new Spacer(1));
+  container.addChild(
+    buildOverlaySection(theme, "Servers", buildOverlayServerLines(theme, servers)),
+  );
+  container.addChild(new Spacer(1));
+  container.addChild(
+    buildOverlaySection(
+      theme,
+      diagnostics.length > 0 ? "Problems" : "Diagnostics",
+      buildOverlayDiagnosticLines(theme, diagnostics, detailedDiagnostics, width),
+    ),
+  );
+  container.addChild(new Spacer(1));
+  container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+  return container;
+}
+
+function buildLspStatus(
+  ctx: ExtensionContext,
+  servers: ProjectServerInfo[],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): string | undefined {
+  const runningServers = servers.filter((server) => server.status === "running").length;
+  const openFiles = servers.reduce((sum, server) => sum + server.openFiles.length, 0);
+  const totals = collectDiagnosticTotals(diagnostics);
+
+  if (runningServers === 0 && openFiles === 0 && diagnostics.length === 0) {
+    return undefined;
+  }
+
+  const { theme } = ctx.ui;
+  const parts = [theme.fg("accent", "λ lsp")];
+  if (runningServers > 0) parts.push(theme.fg("dim", pluralize(runningServers, "server")));
+  if (openFiles > 0) parts.push(theme.fg("dim", pluralize(openFiles, "open file")));
+  if (totals.errors > 0) parts.push(theme.fg("error", pluralize(totals.errors, "error")));
+  if (totals.warnings > 0) parts.push(theme.fg("warning", pluralize(totals.warnings, "warning")));
+  if (totals.information > 0) parts.push(theme.fg("accent", pluralize(totals.information, "info")));
+  if (totals.hints > 0) parts.push(theme.fg("dim", pluralize(totals.hints, "hint")));
+  return parts.join(theme.fg("dim", " • "));
+}
+
+function hasWidgetContent(diagnostics: OutstandingDiagnosticSummaryEntry[]): boolean {
+  return diagnostics.length > 0;
+}
+
+function buildLspWidgetComponent(
+  theme: ExtensionContext["ui"]["theme"],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): Container {
+  const container = new Container();
+
+  for (const line of buildWidgetDiagnosticLines(theme, diagnostics)) {
+    container.addChild(new Text(line, 0, 0));
+  }
+
+  return container;
+}
+
+function buildWidgetDiagnosticLines(
+  theme: ExtensionContext["ui"]["theme"],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): string[] {
+  if (diagnostics.length === 1) {
+    const [entry] = diagnostics;
+    if (!entry) return [];
+    return [
+      `${theme.fg("error", "●")} ${entry.file} ${theme.fg("dim", `— ${formatDiagnosticCounts(entry)}`)}`,
+    ];
+  }
+
+  const totals = collectDiagnosticTotals(diagnostics);
+  const counts: string[] = [];
+  if (totals.errors > 0) counts.push(theme.fg("error", pluralize(totals.errors, "error")));
+  if (totals.warnings > 0) counts.push(theme.fg("warning", pluralize(totals.warnings, "warning")));
+  if (totals.information > 0)
+    counts.push(theme.fg("accent", pluralize(totals.information, "info")));
+  if (totals.hints > 0) counts.push(theme.fg("dim", pluralize(totals.hints, "hint")));
+
+  const visibleFiles = diagnostics.slice(0, 2).map((entry) => entry.file);
+  const remaining = diagnostics.length - visibleFiles.length;
+  const suffix = remaining > 0 ? `${theme.fg("dim", ` +${remaining} more`)}` : "";
+
+  return [
+    `${theme.fg("accent", theme.bold("λ LSP diagnostics"))} ${theme.fg("dim", `— ${pluralize(diagnostics.length, "file")}`)} ${counts.join(theme.fg("dim", " • "))}`,
+    `${theme.fg("error", "↳")} ${visibleFiles.join(", ")}${suffix}`,
+  ];
+}
+
+function buildOverlaySummaryLine(
+  theme: ExtensionContext["ui"]["theme"],
+  servers: ProjectServerInfo[],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): string {
+  const runningServers = servers.filter((server) => server.status === "running").length;
+  const openFiles = servers.reduce((sum, server) => sum + server.openFiles.length, 0);
+  const totals = collectDiagnosticTotals(diagnostics);
+
+  const parts = [
+    theme.fg(
+      "dim",
+      `${pluralize(runningServers, "server")} • ${pluralize(openFiles, "open file")}`,
+    ),
+  ];
+  if (totals.errors > 0) {
+    parts.push(theme.fg("error", pluralize(totals.errors, "error")));
+  } else if (totals.warnings > 0) {
+    parts.push(theme.fg("warning", pluralize(totals.warnings, "warning")));
+  } else if (totals.information > 0) {
+    parts.push(theme.fg("accent", pluralize(totals.information, "info")));
+  } else if (totals.hints > 0) {
+    parts.push(theme.fg("dim", pluralize(totals.hints, "hint")));
+  } else {
+    parts.push(theme.fg("success", "clean"));
+  }
+
+  return parts.join(theme.fg("dim", "   "));
+}
+
+function buildOverlaySection(
+  theme: ExtensionContext["ui"]["theme"],
+  title: string,
+  lines: string[],
+): Container {
+  const container = new Container();
+  container.addChild(new Text(theme.fg("accent", theme.bold(` ${title}`)), 1, 0));
+  for (const line of lines) {
+    container.addChild(new Text(line, 2, 0));
+  }
+  return container;
+}
+
+function buildOverlayServerLines(
+  theme: ExtensionContext["ui"]["theme"],
+  servers: ProjectServerInfo[],
+): string[] {
+  if (servers.length === 0) {
+    return [theme.fg("dim", "no LSP servers available for this project")];
+  }
+
+  return servers.flatMap((server) => {
+    const statusColor =
+      server.status === "running" ? "success" : server.status === "error" ? "error" : "warning";
+    const actions =
+      server.supportedActions.length > 0 ? server.supportedActions.join(", ") : "none";
+    const fileTypes = server.fileTypes.map((entry) => `.${entry}`).join(", ");
+    const openFiles =
+      server.openFiles.length > 0 ? server.openFiles.slice(0, 3).join(", ") : "none";
+    const remaining = server.openFiles.length - Math.min(server.openFiles.length, 3);
+    const suffix = remaining > 0 ? theme.fg("dim", ` +${remaining} more`) : "";
+
+    return [
+      `${theme.fg("accent", "◆")} ${server.name} ${theme.fg(statusColor, server.status)} ${theme.fg("dim", `— root: ${server.root}`)}`,
+      `${theme.fg("dim", "↳")} files: ${fileTypes}`,
+      `${theme.fg("dim", "↳")} actions: ${actions}`,
+      `${theme.fg("dim", "↳")} open: ${openFiles}${suffix}`,
+    ];
+  });
+}
+
+function buildOverlayDiagnosticLines(
+  theme: ExtensionContext["ui"]["theme"],
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+  detailedDiagnostics: Array<{ file: string; diagnostics: Diagnostic[] }>,
+  width: number,
+): string[] {
+  if (diagnostics.length === 0) {
+    return [theme.fg("success", "✓ no outstanding diagnostics")];
+  }
+
+  const lines: string[] = [];
+  const maxFiles = 5;
+  const maxMessagesPerFile = 5;
+  // Budget for prefix: 2 spaces + tree char + space + line:col + space + Text paddingX(2)*2
+  const maxMessageLen = Math.max(24, width - 18);
+
+  for (const entry of detailedDiagnostics.slice(0, maxFiles)) {
+    const summary = diagnostics.find((d) => d.file === entry.file);
+    const countLabel = summary ? formatDiagnosticCounts(summary) : "";
+    lines.push(`${theme.fg("error", "●")} ${entry.file} ${theme.fg("dim", `— ${countLabel}`)}`);
+
+    for (const diag of entry.diagnostics.slice(0, maxMessagesPerFile)) {
+      const line = diag.range.start.line + 1;
+      const col = diag.range.start.character + 1;
+      const sevColor = diag.severity === DiagnosticSeverity.Error ? "error" : "warning";
+      const message = truncate(diag.message, maxMessageLen);
+      lines.push(`  ${theme.fg(sevColor, "└")} ${line}:${col} ${theme.fg("dim", message)}`);
+    }
+
+    const remainingMessages = entry.diagnostics.length - maxMessagesPerFile;
+    if (remainingMessages > 0) {
+      lines.push(`  ${theme.fg("dim", `└ +${remainingMessages} more`)}`);
+    }
+  }
+
+  const remainingFiles = diagnostics.length - Math.min(diagnostics.length, maxFiles);
+  if (remainingFiles > 0) {
+    lines.push(theme.fg("dim", `↳ +${remainingFiles} more file${remainingFiles === 1 ? "" : "s"}`));
+  }
+
+  return lines;
+}
+
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength - 1)}…`;
+}
+
+function formatDiagnosticCounts(entry: OutstandingDiagnosticSummaryEntry): string {
+  const counts: string[] = [];
+  if (entry.errors > 0) counts.push(pluralize(entry.errors, "error"));
+  if (entry.warnings > 0) counts.push(pluralize(entry.warnings, "warning"));
+  if (entry.information > 0) counts.push(pluralize(entry.information, "info"));
+  if (entry.hints > 0) counts.push(pluralize(entry.hints, "hint"));
+  return counts.join(", ");
+}
+
+function collectDiagnosticTotals(
+  diagnostics: OutstandingDiagnosticSummaryEntry[],
+): Pick<OutstandingDiagnosticSummaryEntry, "errors" | "warnings" | "information" | "hints"> {
+  return diagnostics.reduce(
+    (totals, entry) => ({
+      errors: totals.errors + entry.errors,
+      warnings: totals.warnings + entry.warnings,
+      information: totals.information + entry.information,
+      hints: totals.hints + entry.hints,
+    }),
+    { errors: 0, warnings: 0, information: 0, hints: 0 },
+  );
+}
+
+function pluralize(count: number, word: string): string {
+  return `${count} ${word}${count === 1 ? "" : "s"}`;
+}

package/{utils.ts → src/utils.ts}

@@ -2,7 +2,6 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-
 // ── URI Handling ──────────────────────────────────────────────────────
 
 /** Convert a file path to a file:// URI. */
@@ -58,16 +57,24 @@ const EXT_TO_LANGUAGE: Record<string, string> = {
   yml: "yaml",
   md: "markdown",
   html: "html",
+  htm: "html",
+  xhtml: "html",
   css: "css",
   scss: "scss",
   sh: "shellscript",
   bash: "shellscript",
+  zsh: "shellscript",
+  ksh: "shellscript",
   toml: "toml",
   xml: "xml",
   sql: "sql",
+  r: "r",
   rb: "ruby",
+  erb: "ruby",
+  gemspec: "ruby",
   java: "java",
   kt: "kotlin",
+  kts: "kotlin",
   swift: "swift",
   lua: "lua",
   zig: "zig",
@@ -84,30 +91,6 @@ export function getFileExtension(filePath: string): string {
   return path.extname(filePath).slice(1).toLowerCase();
 }
 
-// ── Root Marker Detection ─────────────────────────────────────────────
-
-/**
- * Search upward from `startDir` for any of the `markers` files/dirs.
- * Returns the directory containing the first found marker, or `fallback`.
- */
-export function findProjectRoot(startDir: string, markers: string[], fallback: string): string {
-  let dir = path.resolve(startDir);
-  const root = path.parse(dir).root;
-
-  while (dir !== root) {
-    for (const marker of markers) {
-      if (fs.existsSync(path.join(dir, marker))) {
-        return dir;
-      }
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-
-  return fallback;
-}
-
 // ── PATH Validation ───────────────────────────────────────────────────
 
 /**

package/src/workspace-sentinels.ts

@@ -0,0 +1,114 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { FileChangeType, type FileEvent } from "./types.ts";
+import { fileToUri } from "./utils.ts";
+
+const IGNORED_DIRECTORIES = new Set(["node_modules", ".pnpm", ".git", "dist", "coverage"]);
+const ROOT_LOCKFILES = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"];
+
+/** Build a fresh snapshot of workspace sentinel files and their mtimes. */
+export function scanWorkspaceSentinels(cwd: string): Map<string, number> {
+  const resolvedCwd = path.resolve(cwd);
+  const snapshot = new Map<string, number>();
+
+  if (!fs.existsSync(resolvedCwd)) return snapshot;
+
+  try {
+    walkWorkspace(resolvedCwd, resolvedCwd, snapshot);
+  } catch {
+    return snapshot;
+  }
+
+  return snapshot;
+}
+
+/** Diff two sentinel snapshots into LSP file change events. */
+export function diffWorkspaceSentinelSnapshot(
+  previous: Map<string, number>,
+  next: Map<string, number>,
+): FileEvent[] {
+  const changes: FileEvent[] = [];
+
+  for (const [filePath, mtime] of next) {
+    const previousMtime = previous.get(filePath);
+    if (previousMtime === undefined) {
+      changes.push({ uri: fileToUri(filePath), type: FileChangeType.Created });
+      continue;
+    }
+    if (previousMtime !== mtime) {
+      changes.push({ uri: fileToUri(filePath), type: FileChangeType.Changed });
+    }
+  }
+
+  for (const filePath of previous.keys()) {
+    if (next.has(filePath)) continue;
+    changes.push({ uri: fileToUri(filePath), type: FileChangeType.Deleted });
+  }
+
+  return changes.sort((a, b) => a.uri.localeCompare(b.uri));
+}
+
+/** Refresh a previous snapshot and return the new snapshot plus change events. */
+export function syncWorkspaceSentinelSnapshot(
+  cwd: string,
+  previous: Map<string, number>,
+): { snapshot: Map<string, number>; changes: FileEvent[] } {
+  const snapshot = scanWorkspaceSentinels(cwd);
+  return {
+    snapshot,
+    changes: diffWorkspaceSentinelSnapshot(previous, snapshot),
+  };
+}
+
+/** Determine whether a file path should trigger workspace recovery. */
+export function isWorkspaceRecoveryTrigger(filePath: string, cwd: string): boolean {
+  const root = path.resolve(cwd);
+  return isWorkspaceSentinelPath(path.resolve(root, filePath), root);
+}
+
+function walkWorkspace(root: string, directory: string, snapshot: Map<string, number>): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    // Permission error or deleted directory — skip it rather than
+    // failing the entire scan. A partial snapshot still detects
+    // changes in accessible subtrees.
+    return;
+  }
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+      walkWorkspace(root, path.join(directory, entry.name), snapshot);
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+
+    const filePath = path.join(directory, entry.name);
+    if (!isWorkspaceSentinelPath(filePath, root)) continue;
+    try {
+      snapshot.set(filePath, fs.statSync(filePath).mtimeMs);
+    } catch {
+      // File deleted between readdir and stat — skip.
+    }
+  }
+}
+
+function isWorkspaceSentinelPath(filePath: string, root: string): boolean {
+  const name = path.basename(filePath);
+
+  if (name === "package.json") return true;
+  if (name === "jsconfig.json") return true;
+  if (name === "tsconfig.json") return true;
+  if (name.startsWith("tsconfig.") && name.endsWith(".json")) return true;
+  if (filePath.endsWith(".d.ts")) return true;
+
+  return isRootLockfile(filePath, root);
+}
+
+function isRootLockfile(filePath: string, root: string): boolean {
+  if (path.dirname(filePath) !== root) return false;
+  return ROOT_LOCKFILES.includes(path.basename(filePath));
+}