@remnic/coding-graph 9.3.759

package/src/lsp/characterization.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Characterization test (issue #1555 — rule 30/48):
+ *
+ * With `lsp.enabled: false`, enabling LSP with zero servers installed
+ * must produce a working index IDENTICAL to Phase A. The LSP layer is
+ * a pure addition — when disabled, no LSP code path runs, no edges
+ * change, no degradations surface beyond `not_enabled`.
+ *
+ * This test also covers the characterization contract: the LSP layer
+ * never throws, never changes graph state, and produces a visible
+ * `not_enabled` degradation when disabled.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { DEFAULT_LSP_CONFIG, parseLspConfig } from "./config.js";
+import { lspDegradation } from "./degradation.js";
+import { getLspStatus, formatLspStatusLine } from "./status.js";
+import {
+  planLspUpgrades,
+  executeLspResolution,
+  type EdgeUpgrade,
+} from "./resolution.js";
+import type { CodingGraphLanguage } from "@remnic/core";
+
+test("characterization: default config has enabled=false (rule 30/48)", () => {
+  assert.equal(DEFAULT_LSP_CONFIG.enabled, false);
+  assert.equal(DEFAULT_LSP_CONFIG.servers === undefined || Object.keys(DEFAULT_LSP_CONFIG.servers).length === 0, true);
+  assert.equal(DEFAULT_LSP_CONFIG.timeoutMs, 3_000);
+  assert.equal(DEFAULT_LSP_CONFIG.maxRequestsPerRun, 500);
+});
+
+test("characterization: parseLspConfig(null) → default (disabled)", () => {
+  const result = parseLspConfig(null, ["typescript"]);
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.config.enabled, false);
+  }
+});
+
+test("characterization: parseLspConfig(undefined) → default (disabled)", () => {
+  const result = parseLspConfig(undefined, ["typescript"]);
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.config.enabled, false);
+  }
+});
+
+test("characterization: planLspUpgrades with enabled=false → planner still works but executor is not called", () => {
+  // The planner is pure — it doesn't check config.enabled. The caller
+  // checks config.enabled BEFORE calling the planner. This test verifies
+  // the planner produces correct output regardless, so the caller's gate
+  // is the only thing preventing LSP requests.
+  const sites = [
+    {
+      filePath: "src/a.ts",
+      language: "typescript" as CodingGraphLanguage,
+      content: "export function foo() {}",
+      calleeByteOffset: 0,
+      calleeName: "foo",
+      srcQualifiedName: "a.foo",
+    },
+  ];
+  const plan = planLspUpgrades(sites, { maxRequests: 100 });
+  assert.equal(plan.requests.length, 1);
+
+  // But with enabled=false, the caller MUST NOT call executeLspResolution.
+  // This is the characterization: the index is byte-identical to Phase A.
+  // We verify this by asserting the planner output is non-empty but the
+  // caller's gate (config.enabled === false) prevents execution.
+  assert.equal(DEFAULT_LSP_CONFIG.enabled, false);
+});
+
+test("characterization: getLspStatus with enabled=false → all entries show [disabled]", () => {
+  const status = getLspStatus({
+    config: DEFAULT_LSP_CONFIG,
+    probeResults: new Map(),
+    degradations: new Map(),
+    requestCounts: new Map(),
+    languages: ["typescript", "python"],
+  });
+  assert.equal(status.length, 2);
+  for (const entry of status) {
+    assert.equal(entry.enabled, false);
+    assert.equal(entry.probed, false);
+    assert.equal(entry.degraded, false);
+    assert.equal(entry.requestsUsed, 0);
+    const line = formatLspStatusLine(entry);
+    assert.ok(line.includes("[disabled]"), `line should show [disabled]: ${line}`);
+  }
+});
+
+test("characterization: enabled=true but zero servers → [not_probed] + visible degradation", () => {
+  // Enabling LSP with zero servers installed must produce a working
+  // index identical to Phase A PLUS visible degradations. This is the
+  // rule 30/48 characterization: enabling is safe, it just doesn't help.
+  const status = getLspStatus({
+    config: { ...DEFAULT_LSP_CONFIG, enabled: true },
+    probeResults: new Map([["typescript", false]]),
+    degradations: new Map([["typescript", "server_missing"]]),
+    requestCounts: new Map(),
+    languages: ["typescript"],
+  });
+  assert.equal(status.length, 1);
+  const entry = status[0];
+  assert.equal(entry.enabled, true);
+  assert.equal(entry.probed, false);
+  assert.equal(entry.degraded, true);
+  assert.equal(entry.degradationCode, "server_missing");
+  const line = formatLspStatusLine(entry);
+  assert.ok(line.includes("not_probed") || line.includes("degraded"), `line should show state: ${line}`);
+});
+
+test("characterization: formatLspStatusLine renders probed + request count", () => {
+  const line = formatLspStatusLine({
+    language: "typescript",
+    enabled: true,
+    probed: true,
+    degraded: false,
+    requestsUsed: 42,
+  });
+  assert.ok(line.includes("probed"), line);
+  assert.ok(line.includes("42 requests"), line);
+});
+
+test("characterization: formatLspStatusLine renders degraded state", () => {
+  const line = formatLspStatusLine({
+    language: "python",
+    enabled: true,
+    probed: true,
+    degraded: true,
+    degradationCode: "request_timeout",
+    requestsUsed: 3,
+  });
+  assert.ok(line.includes("degraded:request_timeout"), line);
+});
+
+test("characterization: lspDegradation produces backend=lsp for all codes", () => {
+  const codes = [
+    "server_missing",
+    "handshake_timeout",
+    "request_timeout",
+    "protocol_error",
+    "server_crashed",
+    "budget_exhausted",
+    "not_enabled",
+    "unknown_language",
+  ] as const;
+  for (const code of codes) {
+    const d = lspDegradation(code);
+    assert.equal(d.backend, "lsp", `${code} must have backend=lsp`);
+    assert.equal(d.code, code);
+  }
+});
+
+test("characterization: executeLspResolution with empty requests never calls client", async () => {
+  // When the planner produces zero requests (budget=0 or no call sites),
+  // the executor does nothing — no client calls, no applyUpgrades calls.
+  let clientCalled = false;
+  let applyCalled = false;
+  const result = await executeLspResolution([], {
+    client: {
+      definition: async () => { clientCalled = true; return { ok: true, locations: [] }; },
+      didOpen: () => {},
+      dispose: async () => {},
+    } as never,
+    nodeLocator: () => null,
+    applyUpgrades: async () => { applyCalled = true; },
+  });
+  assert.equal(result.upgraded, 0);
+  assert.equal(result.unresolved, 0);
+  assert.equal(clientCalled, false, "client.definition must not be called with zero requests");
+  assert.equal(applyCalled, false, "applyUpgrades must not be called with zero requests");
+});

package/src/lsp/client.test.ts

@@ -0,0 +1,275 @@
+/**
+ * LSP client tests — the 5-mode fake-server matrix (issue #1555 step 1).
+ *
+ * Each failure mode yields a DISTINCT degradation code (rule 34):
+ *   - happy             → ok:true
+ *   - server_missing    → server_missing
+ *   - handshake_timeout → handshake_timeout
+ *   - request_timeout   → request_timeout
+ *   - protocol_error    → protocol_error
+ *
+ * Plus the zombie-cleanup test: after dispose(), no child process remains
+ * (asserted via pid liveness).
+ *
+ * The fake server is a checked-in Node script speaking canned JSON-RPC
+ * over stdio (synthetic responses only — rule 33: shapes match LSP 3.17).
+ */
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import test from "node:test";
+
+import { LspClient } from "./client.js";
+import { DEFAULT_LSP_TIMEOUT_MS } from "./config.js";
+
+const FAKE_SERVER = path.resolve(
+  import.meta.dirname,
+  "fixtures",
+  "fake-server.mjs",
+);
+
+/**
+ * Spawn the fake server with the given scenario and connect a real client.
+ * Returns the connect result.
+ */
+function connectFake(
+  scenario: string,
+  timeoutMs: number = DEFAULT_LSP_TIMEOUT_MS,
+): Promise<
+  | { ok: true; client: LspClient }
+  | { ok: false; degradation: { code: string; detail?: string } }
+> {
+  return LspClient.connect({
+    launchSpec: { command: process.execPath, args: [FAKE_SERVER, scenario] },
+    rootUri: null,
+    timeoutMs,
+  });
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// The 5-mode matrix
+// ──────────────────────────────────────────────────────────────────────────
+
+test("fake-server matrix: happy — handshake succeeds, supportsDefinition=true", async () => {
+  const result = await connectFake("happy", 5_000);
+  assert.equal(result.ok, true, `expected ok, got degradation: ${JSON.stringify(result)}`);
+  if (!result.ok) return;
+  assert.equal(result.client.supportsDefinition, true);
+  await result.client.dispose();
+});
+
+test("fake-server matrix: server_missing — spawn fails with ENOENT", async () => {
+  const result = await LspClient.connect({
+    launchSpec: { command: "/nonexistent/binary/that/does/not/exist", args: [] },
+    rootUri: null,
+    timeoutMs: 2_000,
+  });
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.degradation.code, "server_missing");
+  }
+});
+
+test("fake-server matrix: handshake_timeout — initialize never responds", async () => {
+  const result = await connectFake("handshake_timeout", 1_500);
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.degradation.code, "handshake_timeout");
+  }
+});
+
+test("fake-server matrix: request_timeout — definition never responds", async () => {
+  // Handshake succeeds, but definition request hangs.
+  const connectResult = await connectFake("request_timeout", 5_000);
+  assert.equal(connectResult.ok, true, `handshake should succeed: ${JSON.stringify(connectResult)}`);
+  if (!connectResult.ok) return;
+
+  // Override the client's timeout for the definition request.
+  // We create a new client with a shorter timeout to test request-level
+  // timeout separately from handshake timeout.
+  await connectResult.client.dispose();
+
+  // Now connect with a short timeout — both handshake AND requests use it.
+  const shortResult = await connectFake("request_timeout", 1_000);
+  assert.equal(shortResult.ok, true, `handshake should succeed with short timeout`);
+  if (!shortResult.ok) return;
+
+  const defResult = await shortResult.client.definition({
+    textDocument: { uri: "file:///fake/test.ts" },
+    position: { line: 0, character: 0 },
+  });
+  assert.equal(defResult.ok, false);
+  if (!defResult.ok) {
+    assert.equal(defResult.degradation.code, "request_timeout");
+  }
+  await shortResult.client.dispose();
+});
+
+test("fake-server matrix: protocol_error — malformed frame from server", async () => {
+  const result = await connectFake("protocol_error", 2_000);
+  // The protocol error happens during handshake — the server sends
+  // garbage after receiving initialize.
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.degradation.code, "protocol_error");
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Zombie cleanup — after dispose, no child process remains.
+// ──────────────────────────────────────────────────────────────────────────
+
+test("zombie cleanup: after dispose, no child process remains (pid liveness)", async () => {
+  const result = await connectFake("happy", 5_000);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+
+  const pid = result.client.pid;
+  assert.ok(typeof pid === "number" && pid > 0, "client must have a pid");
+  assert.ok(isProcessAlive(pid), "process must be alive before dispose");
+
+  await result.client.dispose();
+
+  // After dispose, the process should be gone. Poll pid liveness with a
+  // bounded retry instead of a fixed sleep — the process usually dies
+  // within one event-loop tick (SIGKILL is synchronous), but on a loaded
+  // machine the reaping may lag by a few ms.
+  // Integration test: real child-process lifecycle, not fake-timerable.
+  const dead = await waitForCondition(() => !isProcessAlive(pid), 2_000, 50);
+  assert.equal(
+    dead,
+    true,
+    "process must be dead after dispose — no zombie",
+  );
+});
+
+test("zombie cleanup: dispose is idempotent — safe to call twice", async () => {
+  const result = await connectFake("happy", 5_000);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  await result.client.dispose();
+  // Second dispose must not throw.
+  await result.client.dispose();
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Happy-path definition request — end-to-end resolution.
+// ──────────────────────────────────────────────────────────────────────────
+
+test("happy path: didOpen + definition returns canned locations", async () => {
+  const result = await connectFake("happy", 5_000);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+
+  result.client.didOpen({
+    uri: "file:///fake/src/caller.ts",
+    languageId: "typescript",
+    version: 1,
+    text: "export function caller() { target(); }",
+  });
+
+  const defResult = await result.client.definition({
+    textDocument: { uri: "file:///fake/src/caller.ts" },
+    position: { line: 0, character: 30 },
+  });
+  assert.equal(defResult.ok, true, `definition should succeed: ${JSON.stringify(defResult)}`);
+  if (defResult.ok) {
+    assert.ok(defResult.locations.length > 0, "should return at least one location");
+    const loc = defResult.locations[0];
+    assert.ok(loc.uri, "location must have a uri");
+    assert.ok(loc.range, "location must have a range");
+  }
+  await result.client.dispose();
+});
+
+test("definition after dispose → server_crashed degradation", async () => {
+  const result = await connectFake("happy", 5_000);
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  await result.client.dispose();
+  const defResult = await result.client.definition({
+    textDocument: { uri: "file:///fake/test.ts" },
+    position: { line: 0, character: 0 },
+  });
+  assert.equal(defResult.ok, false);
+  if (!defResult.ok) {
+    assert.equal(defResult.degradation.code, "server_crashed");
+  }
+});
+
+test("crash_after_start: server exits mid-run → server_crashed", async () => {
+  const result = await connectFake("crash_after_start", 5_000);
+  assert.equal(result.ok, true, `handshake should succeed before crash: ${JSON.stringify(result)}`);
+  if (!result.ok) return;
+
+  // The fake server exits immediately after the initialized notification.
+  // Wait for the child process to actually exit before sending the next
+  // request. Integration test: real process exit, not fake-timerable.
+  const pid = result.client.pid;
+  if (typeof pid === "number") {
+    await waitForCondition(() => !isProcessAlive(pid), 2_000, 50);
+  }
+
+  const defResult = await result.client.definition({
+    textDocument: { uri: "file:///fake/test.ts" },
+    position: { line: 0, character: 0 },
+  });
+  assert.equal(defResult.ok, false);
+  if (!defResult.ok) {
+    assert.equal(
+      defResult.degradation.code,
+      "server_crashed",
+      `expected server_crashed, got ${defResult.degradation.code}`,
+    );
+  }
+  await result.client.dispose();
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check whether a process is still alive by sending signal 0.
+ * Returns true if the process exists and we can signal it.
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Poll a condition at a bounded interval until it returns true or the
+ * deadline elapses. Used for real child-process lifecycle checks where
+ * deterministic fake-timers cannot replace the OS scheduler.
+ */
+function waitForCondition(
+  cond: () => boolean,
+  timeoutMs: number,
+  intervalMs: number,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const deadline = Date.now() + timeoutMs;
+    const check = () => {
+      if (cond()) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        resolve(false);
+        return;
+      }
+      setTimeout(check, intervalMs);
+    };
+    check();
+  });
+}
+
+// Suppress unhandled rejection noise from the fake server's exit events
+// during tests (the 'error' event from ENOENT is handled by the client).
+process.on("unhandledRejection", () => {});