@remnic/coding-graph 9.6.37 → 9.6.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/coding-graph",
-  "version": "9.6.37",
+  "version": "9.6.39",
   "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.37"
+    "@remnic/core": "^9.6.39"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "@remnic/core": "9.6.37"
+    "@remnic/core": "9.6.39"
   },
   "license": "MIT",
   "repository": {

package/src/graph-store.ts

@@ -2909,6 +2909,128 @@ export class GraphStore {
     }
   }
 
+  /**
+   * Find the innermost node whose span contains a byte offset in a file
+   * (issue #1917). Used by the LSP resolution pass's NodeLocator to map
+   * definition locations back to indexed nodes. Returns the node's
+   * qualified name, or null when no node contains the offset.
+   */
+  findNodeBySpan(filePath: string, byteOffset: number): string | null {
+    if (this.closed) return null;
+    try {
+      // Fetch the two smallest containing spans: nested containment is
+      // normal (a method inside a class both contain the offset) and the
+      // INNERMOST (smallest) wins — but a TIE at the smallest size means
+      // the offset cannot be attributed to exactly one node, and the
+      // NodeLocator contract requires null over an arbitrary pick
+      // (review thread: a wrong winner persists incorrect CALLS edges).
+      const rows = expectRows<{ qualified_name: string; size: number }>(
+        this.db
+          .prepare(
+            `SELECT n.qualified_name, (n.span_end - n.span_start) AS size FROM nodes n
+              JOIN files f ON n.file_id = f.id
+              WHERE f.path = ? AND n.span_start <= ? AND n.span_end > ?
+              ORDER BY size ASC
+              LIMIT 2`,
+          )
+          .all(filePath, byteOffset, byteOffset),
+        ["qualified_name", "size"],
+      );
+      if (rows.length === 0) return null;
+      if (rows.length > 1 && rows[1] !== undefined && rows[0]!.size === rows[1].size) return null;
+      const qualifiedName = rows[0]!.qualified_name;
+      // The span lookup disambiguated by file, but the returned QUALIFIED
+      // NAME is the edge key downstream (upsertEdges resolves names, not
+      // ids). If another file defines the same qualified name (common for
+      // top-level `main`/`handler`/`init`), an edge written against the
+      // name could bind to the wrong node — return null and skip the
+      // upgrade instead (conservative; id-carrying upgrades are the
+      // follow-up, review thread on #1923).
+      const dupRow = expectRow<{ n: number }>(
+        this.db
+          .prepare(`SELECT COUNT(*) AS n FROM nodes WHERE qualified_name = ?`)
+          .get(qualifiedName),
+        ["n"],
+      );
+      if (dupRow && dupRow.n > 1) return null;
+      return qualifiedName;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Callee NAMES already linked from a caller symbol via CALLS edges of a
+   * given provenance (issue #1917 wiring). The LSP pass uses this to skip
+   * call sites Phase A (provenance "heuristic") already resolved WITHOUT
+   * also skipping sites whose only edge is a prior "lsp" edge — those must
+   * be re-asserted each run or reconciliation would retire them.
+   */
+  resolvedCalleeNames(srcQualifiedName: string, provenance: string, filePath?: string): string[] {
+    if (this.closed) return [];
+    try {
+      // Scoped to the caller FILE when provided: two files defining the
+      // same top-level qualified name (main/handler/init) must not leak
+      // each other's resolutions (#1923 review thread).
+      const fileClause = filePath !== undefined ? " AND f.path = ?" : "";
+      const bind = filePath !== undefined ? [srcQualifiedName, provenance, filePath] : [srcQualifiedName, provenance];
+      const rows = expectRows<{ name: string }>(
+        this.db
+          .prepare(
+            `SELECT DISTINCT dn.name AS name FROM edges e
+              JOIN nodes sn ON e.src = sn.id
+              JOIN files f ON sn.file_id = f.id
+              JOIN nodes dn ON e.dst = dn.id
+              WHERE sn.qualified_name = ? AND e.type = 'CALLS' AND e.provenance = ?${fileClause}`,
+          )
+          .all(...bind),
+        ["name"],
+      );
+      return rows.map((r) => r.name);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Current CALLS edges of a given provenance owned by a caller symbol in
+   * a file (#1923 review threads). The LSP pass uses this two ways:
+   * provenance "lsp" lists a filtered caller's existing lsp edges, and
+   * provenance "heuristic" lists its current Phase-A resolutions — an lsp
+   * edge is preserved at reconcile time only when it duplicates a current
+   * heuristic resolution (same dst), so removed member calls' edges retire
+   * while a filtered bare call's covering edge survives.
+   */
+  callEdgesForCaller(
+    srcQualifiedName: string,
+    filePath: string,
+    provenance: string,
+  ): Array<{ srcQualifiedName: string; dstQualifiedName: string; dstName: string; type: string }> {
+    if (this.closed) return [];
+    try {
+      const rows = expectRows<{ src_q: string; dst_q: string; dst_n: string; type: string }>(
+        this.db
+          .prepare(
+            `SELECT sn.qualified_name AS src_q, dn.qualified_name AS dst_q, dn.name AS dst_n, e.type AS type FROM edges e
+              JOIN nodes sn ON e.src = sn.id
+              JOIN files f ON sn.file_id = f.id
+              JOIN nodes dn ON e.dst = dn.id
+              WHERE sn.qualified_name = ? AND f.path = ? AND e.provenance = ? AND e.type = 'CALLS'`,
+          )
+          .all(srcQualifiedName, filePath, provenance),
+        ["src_q", "dst_q", "dst_n", "type"],
+      );
+      return rows.map((r) => ({
+        srcQualifiedName: r.src_q,
+        dstQualifiedName: r.dst_q,
+        dstName: r.dst_n,
+        type: r.type,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
   /**
    * Read a symbol's source span from disk. The store NEVER persists
    * file contents (privacy + DB size — issue #1552 design); this

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).