@remnic/coding-graph 9.6.38 → 9.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/coding-graph",
-  "version": "9.6.38",
+  "version": "9.7.0",
   "description": "Web-tree-sitter powered symbol-extraction engine + SQLite knowledge-graph store for codebase memory (Tier 1: TypeScript, TSX, JavaScript, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin, Swift, Bash). Optional companion of @remnic/core — install only when coding-graph features are needed.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,14 +41,14 @@
     "web-tree-sitter": "^0.25.0"
   },
   "peerDependencies": {
-    "@remnic/core": "^9.6.38"
+    "@remnic/core": "^9.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "@remnic/core": "9.6.38"
+    "@remnic/core": "9.7.0"
   },
   "license": "MIT",
   "repository": {

package/src/lsp/resolution.test.ts

@@ -295,12 +295,135 @@ test("executor: definition returns empty → unresolved", async () => {
     client: mockClient,
     nodeLocator: locator,
     applyUpgrades: async () => {},
+    // Warm-up retry (issue #1933) is exercised by its own tests below;
+    // this test asserts the definitive-empty path.
+    warmupRetryDelayMs: 0,
   });
 
   assert.equal(result.upgraded, 0);
   assert.equal(result.unresolved, 1);
 });
 
+// ──────────────────────────────────────────────────────────────────────────
+// Warm-up retry (issue #1933): tsserver answers pre-project-load definition
+// requests with [] instead of an error. An empty result before the server
+// has proven warm is retried once; the retry's answer is final.
+// ──────────────────────────────────────────────────────────────────────────
+
+test("executor: warm-up retry — empty first answer retried once, retry result upgrades", async () => {
+  const requests = planLspUpgrades(
+    [makeCallSite("src/a.ts", "target", 0, "a.caller")],
+    { maxRequests: 100 },
+  ).requests;
+
+  // Stateful mock: first definition call returns [], second returns the
+  // real location (project finished loading between the two).
+  let calls = 0;
+  const client = {
+    definition: async () => {
+      calls += 1;
+      if (calls === 1) return { ok: true as const, locations: [] };
+      return {
+        ok: true as const,
+        locations: [{
+          uri: "file:///src/target.ts",
+          range: { start: { line: 0, character: 0 }, end: { line: 0, character: 6 } },
+        }],
+      };
+    },
+    didOpen: () => {},
+    dispose: async () => {},
+  } as unknown as LspClient;
+
+  const applied: EdgeUpgrade[] = [];
+  const result = await executeLspResolution(requests, {
+    client,
+    nodeLocator: () => "mod.target",
+    applyUpgrades: async (upgrades) => {
+      applied.push(...upgrades);
+    },
+    warmupRetryDelayMs: 5,
+  });
+
+  assert.equal(calls, 2, "empty pre-warm answer must be retried exactly once");
+  assert.equal(result.upgraded, 1, "the retry's location produces the upgrade");
+  assert.equal(result.unresolved, 0);
+  assert.equal(applied.length, 1);
+});
+
+test("executor: warm-up retry — only ONE retry is paid; later empties are definitive", async () => {
+  const requests = planLspUpgrades(
+    [
+      makeCallSite("src/a.ts", "missing1", 0, "a.caller"),
+      makeCallSite("src/a.ts", "missing2", 10, "a.caller"),
+    ],
+    { maxRequests: 100 },
+  ).requests;
+
+  let calls = 0;
+  const client = {
+    definition: async () => {
+      calls += 1;
+      return { ok: true as const, locations: [] };
+    },
+    didOpen: () => {},
+    dispose: async () => {},
+  } as unknown as LspClient;
+
+  const result = await executeLspResolution(requests, {
+    client,
+    nodeLocator: () => null,
+    applyUpgrades: async () => {},
+    warmupRetryDelayMs: 5,
+  });
+
+  // Site 1: initial + one warm-up retry = 2 calls; the server is then
+  // considered warm. Site 2: exactly 1 call, its empty answer is final.
+  assert.equal(calls, 3, "one warm-up retry total, not one per site");
+  assert.equal(result.upgraded, 0);
+  assert.equal(result.unresolved, 2);
+});
+
+test("executor: warm-up retry — a non-empty FIRST answer marks the server warm (no retry paid)", async () => {
+  const requests = planLspUpgrades(
+    [
+      makeCallSite("src/a.ts", "target", 0, "a.caller"),
+      makeCallSite("src/a.ts", "missing", 10, "a.caller"),
+    ],
+    { maxRequests: 100 },
+  ).requests;
+
+  let calls = 0;
+  const client = {
+    definition: async () => {
+      calls += 1;
+      if (calls === 1) {
+        return {
+          ok: true as const,
+          locations: [{
+            uri: "file:///src/target.ts",
+            range: { start: { line: 0, character: 0 }, end: { line: 0, character: 6 } },
+          }],
+        };
+      }
+      return { ok: true as const, locations: [] };
+    },
+    didOpen: () => {},
+    dispose: async () => {},
+  } as unknown as LspClient;
+
+  const result = await executeLspResolution(requests, {
+    client,
+    nodeLocator: () => "mod.target",
+    applyUpgrades: async () => {},
+    warmupRetryDelayMs: 5,
+  });
+
+  assert.equal(calls, 2, "warm server: the second site's empty answer is definitive, no retry");
+  assert.equal(result.upgraded, 1);
+  assert.equal(result.unresolved, 1);
+});
+
 test("executor: mid-batch applyUpgrades failure → caught, counted as unresolved", async () => {
   const requests = planLspUpgrades(
     [makeCallSite("src/a.ts", "target", 0, "a.caller")],
@@ -488,6 +611,8 @@ test("executor: workspaceRoot resolves repo-relative paths to absolute URIs", as
     nodeLocator: () => null,
     applyUpgrades: async () => {},
     workspaceRoot: "/workspace",
+    // This test asserts URI shapes, not warm-up behavior (issue #1933).
+    warmupRetryDelayMs: 0,
   });
 
   assert.equal(didOpenUris.length, 1);

package/src/lsp/resolution.ts

@@ -209,6 +209,15 @@ export function planLspUpgrades(
 export interface ResolveOptions {
   readonly client: LspClient;
   readonly nodeLocator: NodeLocator;
+  /**
+   * Warm-up retry delay in ms (issue #1933). Language servers (tsserver
+   * in particular) load projects ASYNCHRONOUSLY after `didOpen`; a
+   * definition request that arrives too early returns an EMPTY location
+   * array — indistinguishable from "definitely no definition". Until the
+   * server has proven warm (any non-empty response), an empty result is
+   * retried ONCE after this delay. Default 2500. Set 0 to disable.
+   */
+  readonly warmupRetryDelayMs?: number;
   /**
    * Apply a batch of edge upgrades atomically. Called once per file batch.
    * MUST be transactional — if it throws, zero upgrades from this batch
@@ -297,6 +306,14 @@ export async function executeLspResolution(
   let unresolved = 0;
   let degradation: LspDegradation | undefined;
 
+  // Warm-up tracking (issue #1933): false until the server returns its
+  // first NON-EMPTY definition, or until one warm-up retry has been paid.
+  // tsserver answers pre-project-load requests with [] instead of an
+  // error, so without the retry every first-run resolution silently
+  // reports unresolved and Phase B never upgrades anything.
+  let serverWarm = false;
+  const warmupRetryDelayMs = options.warmupRetryDelayMs ?? 2_500;
+
   for (const [filePath, batchReqs] of byFile) {
     // Send all definition requests for this file, collecting upgrades.
     const upgrades: EdgeUpgrade[] = [];
@@ -327,11 +344,28 @@ export async function executeLspResolution(
         break;
       }
 
-      const defResult = await client.definition({
+      let defResult = await client.definition({
         textDocument: { uri: filePathToUri(req.filePath, options.workspaceRoot) },
         position: req.position,
       });
 
+      // Warm-up retry (issue #1933): an empty result from a not-yet-warm
+      // server is indeterminate, not definitive. Pay ONE bounded delay,
+      // re-ask, and treat the server as warm from then on — whatever the
+      // retry returns is the real answer.
+      if (defResult.ok && defResult.locations.length === 0 && !serverWarm && warmupRetryDelayMs > 0) {
+        await new Promise<void>((resolve) => setTimeout(resolve, warmupRetryDelayMs));
+        serverWarm = true;
+        const retryResult = await client.definition({
+          textDocument: { uri: filePathToUri(req.filePath, options.workspaceRoot) },
+          position: req.position,
+        });
+        defResult = retryResult;
+      }
+      if (defResult.ok && defResult.locations.length > 0) {
+        serverWarm = true;
+      }
+
       if (!defResult.ok) {
         // Distinguish "server problem" (stop the whole pass) from
         // "this particular definition returned nothing" (continue).