ralph-hero-knowledge-index 0.1.21 → 0.1.23

package/src/__tests__/llm-client.test.ts

@@ -0,0 +1,349 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createLlmClient } from "../llm-client.js";
+
+type FetchFn = typeof globalThis.fetch;
+
+const originalFetch: FetchFn | undefined = globalThis.fetch;
+
+function installFetch(mock: FetchFn): void {
+  globalThis.fetch = mock;
+}
+
+function restoreFetch(): void {
+  if (originalFetch) {
+    globalThis.fetch = originalFetch;
+  } else {
+    // @ts-expect-error runtime cleanup when no original existed
+    delete globalThis.fetch;
+  }
+}
+
+function makeResponse(
+  init: { status?: number; ok?: boolean; json?: unknown } = {},
+): Response {
+  const status = init.status ?? 200;
+  const ok = init.ok ?? (status >= 200 && status < 300);
+  return {
+    status,
+    ok,
+    json: async () => init.json ?? {},
+  } as unknown as Response;
+}
+
+function abortError(): Error {
+  const err = new Error("aborted");
+  err.name = "AbortError";
+  return err;
+}
+
+function connectionRefused(): Error {
+  // Node fetch surfaces connection-refused as a TypeError whose cause has
+  // code `ECONNREFUSED`. Mimic the thrown error here.
+  const err = new TypeError("fetch failed");
+  (err as Error & { cause?: { code: string } }).cause = { code: "ECONNREFUSED" };
+  return err;
+}
+
+describe("createLlmClient", () => {
+  beforeEach(() => {
+    delete process.env.RALPH_LLM_URL;
+    delete process.env.RALPH_LLM_MODEL;
+  });
+
+  afterEach(() => {
+    restoreFetch();
+    vi.restoreAllMocks();
+    vi.useRealTimers();
+  });
+
+  describe("available()", () => {
+    it("returns true when /v1/models responds with status 200", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(makeResponse({ status: 200 }));
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.available();
+
+      expect(result).toBe(true);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const [url, init] = fetchMock.mock.calls[0]!;
+      expect(url).toBe("http://localhost:8000/v1/models");
+      expect(init?.method).toBe("GET");
+      expect(init?.signal).toBeInstanceOf(AbortSignal);
+    });
+
+    it("returns false when fetch rejects with AbortError (timeout)", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockRejectedValue(abortError());
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.available();
+
+      expect(result).toBe(false);
+    });
+
+    it("returns false when fetch returns status 404", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(makeResponse({ status: 404 }));
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.available();
+
+      expect(result).toBe(false);
+    });
+
+    it("returns false when fetch returns status 500", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(makeResponse({ status: 500 }));
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.available();
+
+      expect(result).toBe(false);
+    });
+
+    it("returns false when fetch throws ECONNREFUSED", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockRejectedValue(connectionRefused());
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.available();
+
+      expect(result).toBe(false);
+    });
+
+    it("aborts the probe after 2000ms", async () => {
+      vi.useFakeTimers();
+      let capturedSignal: AbortSignal | undefined;
+      const fetchMock = vi.fn<FetchFn>().mockImplementation((_input, init) => {
+        capturedSignal = init?.signal as AbortSignal | undefined;
+        return new Promise((_resolve, reject) => {
+          capturedSignal?.addEventListener("abort", () => reject(abortError()));
+        });
+      });
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const probe = client.available();
+
+      // Advance timers past the 2000ms probe timeout.
+      await vi.advanceTimersByTimeAsync(2000);
+
+      const result = await probe;
+      expect(result).toBe(false);
+      expect(capturedSignal?.aborted).toBe(true);
+    });
+  });
+
+  describe("contextualize()", () => {
+    it("returns mocked content on happy path (trimmed)", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({
+          status: 200,
+          json: {
+            choices: [{ message: { content: "  This chunk discusses X.  " } }],
+          },
+        }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc body", "chunk");
+
+      expect(result).toBe("This chunk discusses X.");
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const [url, init] = fetchMock.mock.calls[0]!;
+      expect(url).toBe("http://localhost:8000/v1/chat/completions");
+      expect(init?.method).toBe("POST");
+      const headers = init?.headers as Record<string, string> | undefined;
+      expect(headers?.["Content-Type"]).toBe("application/json");
+
+      const body = JSON.parse(init?.body as string) as {
+        model: string;
+        messages: Array<{ role: string; content: string }>;
+        max_tokens: number;
+      };
+      expect(body.model).toBe("mlx-community/gemma-4-26b-a4b-it-mxfp8");
+      expect(body.max_tokens).toBe(120);
+      expect(body.messages).toHaveLength(1);
+      expect(body.messages[0]!.role).toBe("user");
+      // Prompt should embed both the document and the chunk verbatim in the
+      // Anthropic Contextual Retrieval format.
+      expect(body.messages[0]!.content).toContain("<document>\ndoc body\n</document>");
+      expect(body.messages[0]!.content).toContain("<chunk>\nchunk\n</chunk>");
+      expect(body.messages[0]!.content).toContain(
+        "Please give a short succinct context",
+      );
+    });
+
+    it("returns empty string on timeout (AbortError)", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockRejectedValue(abortError());
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc", "chunk");
+
+      expect(result).toBe("");
+    });
+
+    it("returns empty string on malformed response (no choices key)", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({ status: 200, json: { unexpected: "shape" } }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc", "chunk");
+
+      expect(result).toBe("");
+    });
+
+    it("returns empty string when choices array is empty", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({ status: 200, json: { choices: [] } }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc", "chunk");
+
+      expect(result).toBe("");
+    });
+
+    it("returns empty string when message.content is missing", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({ status: 200, json: { choices: [{ message: {} }] } }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc", "chunk");
+
+      expect(result).toBe("");
+    });
+
+    it("returns empty string on non-2xx response", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({ status: 503, json: { error: "unavailable" } }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc", "chunk");
+
+      expect(result).toBe("");
+    });
+
+    it("returns empty string on JSON parse error", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue({
+        status: 200,
+        ok: true,
+        json: async () => {
+          throw new SyntaxError("Unexpected token in JSON");
+        },
+      } as unknown as Response);
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc", "chunk");
+
+      expect(result).toBe("");
+    });
+
+    it("returns empty string on network failure", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockRejectedValue(connectionRefused());
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      const result = await client.contextualize("doc", "chunk");
+
+      expect(result).toBe("");
+    });
+  });
+
+  describe("options and env overrides", () => {
+    it("honors custom baseUrl option", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(makeResponse({ status: 200 }));
+      installFetch(fetchMock);
+
+      const client = createLlmClient({ baseUrl: "http://example.test:9000" });
+      await client.available();
+
+      expect(fetchMock.mock.calls[0]![0]).toBe("http://example.test:9000/v1/models");
+    });
+
+    it("honors custom model option in chat completion body", async () => {
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({
+          status: 200,
+          json: { choices: [{ message: { content: "ctx" } }] },
+        }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient({ model: "custom/model-v1" });
+      await client.contextualize("doc", "chunk");
+
+      const body = JSON.parse(fetchMock.mock.calls[0]![1]?.body as string) as {
+        model: string;
+      };
+      expect(body.model).toBe("custom/model-v1");
+    });
+
+    it("falls back to RALPH_LLM_URL env var", async () => {
+      process.env.RALPH_LLM_URL = "http://env.override:1234";
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(makeResponse({ status: 200 }));
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      await client.available();
+
+      expect(fetchMock.mock.calls[0]![0]).toBe("http://env.override:1234/v1/models");
+    });
+
+    it("falls back to RALPH_LLM_MODEL env var", async () => {
+      process.env.RALPH_LLM_MODEL = "env/model-v2";
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({
+          status: 200,
+          json: { choices: [{ message: { content: "ctx" } }] },
+        }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient();
+      await client.contextualize("doc", "chunk");
+
+      const body = JSON.parse(fetchMock.mock.calls[0]![1]?.body as string) as {
+        model: string;
+      };
+      expect(body.model).toBe("env/model-v2");
+    });
+
+    it("prefers explicit options over env vars", async () => {
+      process.env.RALPH_LLM_URL = "http://env.should-not-win:1234";
+      process.env.RALPH_LLM_MODEL = "env/should-not-win";
+      const fetchMock = vi.fn<FetchFn>().mockResolvedValue(
+        makeResponse({
+          status: 200,
+          json: { choices: [{ message: { content: "ctx" } }] },
+        }),
+      );
+      installFetch(fetchMock);
+
+      const client = createLlmClient({
+        baseUrl: "http://explicit.wins:5000",
+        model: "explicit/model",
+      });
+      await client.contextualize("doc", "chunk");
+
+      expect(fetchMock.mock.calls[0]![0]).toBe(
+        "http://explicit.wins:5000/v1/chat/completions",
+      );
+      const body = JSON.parse(fetchMock.mock.calls[0]![1]?.body as string) as {
+        model: string;
+      };
+      expect(body.model).toBe("explicit/model");
+    });
+  });
+});

package/src/__tests__/memory-stats.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect } from "vitest";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { KnowledgeDB } from "../db.js";
+
+/**
+ * Helper: call the MCP `knowledge_memory_stats` tool directly via the
+ * server's private `_registeredTools` map. Mirrors graph-tools.test.ts.
+ */
+async function callStats(
+  server: McpServer,
+  args: Record<string, unknown> = {},
+): Promise<Record<string, unknown>> {
+  const registered = (server as unknown as Record<string, unknown>)
+    ._registeredTools as Record<
+    string,
+    { handler: (args: Record<string, unknown>, extra: unknown) => Promise<unknown> }
+  >;
+  const tool = registered.knowledge_memory_stats;
+  if (!tool) throw new Error("knowledge_memory_stats not registered");
+  const result = (await tool.handler(args, {})) as {
+    content: Array<{ text: string }>;
+    isError?: boolean;
+  };
+  if (result.isError) {
+    throw new Error(`tool error: ${result.content[0]?.text}`);
+  }
+  return JSON.parse(result.content[0].text) as Record<string, unknown>;
+}
+
+/**
+ * Ensure the v3 schema extensions (memory_tier column on documents, chunks
+ * table) exist on the test DB. Phase 1 (GH-762) owns the production schema
+ * migration; test fixtures add them so Phase 8 features can be exercised
+ * independently of Phase 1 merge order.
+ */
+function ensureV3Schema(db: KnowledgeDB): void {
+  const rows = db.db.prepare("PRAGMA table_info(documents)").all() as Array<{ name: string }>;
+  if (!rows.some((r) => r.name === "memory_tier")) {
+    db.db.exec(
+      "ALTER TABLE documents ADD COLUMN memory_tier TEXT NOT NULL DEFAULT 'doc' CHECK(memory_tier IN ('doc','raw','reflection'))",
+    );
+  }
+  db.db.exec(
+    `CREATE TABLE IF NOT EXISTS chunks (
+       id TEXT PRIMARY KEY,
+       document_id TEXT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+       chunk_index INTEGER NOT NULL,
+       content TEXT NOT NULL,
+       char_start INTEGER NOT NULL,
+       char_end INTEGER NOT NULL,
+       context_prefix TEXT NOT NULL DEFAULT '',
+       UNIQUE(document_id, chunk_index)
+     )`,
+  );
+}
+
+function seedDoc(
+  db: KnowledgeDB,
+  id: string,
+  tier: "doc" | "raw" | "reflection",
+  date: string | null,
+): void {
+  db.upsertDocument({
+    id,
+    path: `${id}.md`,
+    title: id,
+    date,
+    type: null,
+    status: null,
+    githubIssue: null,
+    content: "",
+  });
+  db.db.prepare("UPDATE documents SET memory_tier = ? WHERE id = ?").run(tier, id);
+}
+
+function seedChunks(db: KnowledgeDB, docId: string, count: number): void {
+  const stmt = db.db.prepare(
+    `INSERT INTO chunks (id, document_id, chunk_index, content, char_start, char_end, context_prefix)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  );
+  for (let i = 0; i < count; i++) {
+    stmt.run(`${docId}#c${i}`, docId, i, `chunk ${i}`, i * 100, (i + 1) * 100, "");
+  }
+}
+
+describe("knowledge_memory_stats", () => {
+  it("returns tier counts matching the fixture", async () => {
+    const mod = await import("../index.js");
+    const { server, db } = mod.createServer(":memory:");
+    ensureV3Schema(db);
+
+    // 2 doc, 3 raw, 1 reflection
+    seedDoc(db, "d1", "doc", "2026-04-01");
+    seedDoc(db, "d2", "doc", "2026-04-02");
+    seedDoc(db, "r1", "raw", "2026-04-03");
+    seedDoc(db, "r2", "raw", "2026-04-03");
+    seedDoc(db, "r3", "raw", "2026-04-04");
+    seedDoc(db, "f1", "reflection", "2026-04-05");
+
+    const out = await callStats(server, { since: "1970-01-01T00:00:00Z" });
+    expect(out.total_documents).toBe(6);
+    expect(out.by_tier).toEqual({ doc: 2, raw: 3, reflection: 1 });
+    expect(out.new_since).toEqual({ doc: 2, raw: 3, reflection: 1 });
+  });
+
+  it("computes chunks_per_doc_p50 and _p90 correctly on [1,2,3,4,5]", async () => {
+    const mod = await import("../index.js");
+    const { server, db } = mod.createServer(":memory:");
+    ensureV3Schema(db);
+
+    // Seed 5 docs each with 1,2,3,4,5 chunks respectively
+    const counts = [1, 2, 3, 4, 5];
+    for (let i = 0; i < counts.length; i++) {
+      const id = `chunked-${i}`;
+      seedDoc(db, id, "doc", "2026-04-10");
+      seedChunks(db, id, counts[i]);
+    }
+
+    const out = await callStats(server, { since: "1970-01-01T00:00:00Z" });
+    // sorted counts: [1,2,3,4,5]. floor(5*0.5)=2 -> 3; floor(5*0.9)=4 -> 5.
+    expect(out.chunks_per_doc_p50).toBe(3);
+    expect(out.chunks_per_doc_p90).toBe(5);
+  });
+
+  it("returns last_reflection_at as null when no reflection docs exist", async () => {
+    const mod = await import("../index.js");
+    const { server, db } = mod.createServer(":memory:");
+    ensureV3Schema(db);
+
+    seedDoc(db, "only-doc", "doc", "2026-04-01");
+
+    const out = await callStats(server, { since: "1970-01-01T00:00:00Z" });
+    expect(out.last_reflection_at).toBeNull();
+  });
+
+  it("returns ISO timestamp of most recent reflection when present", async () => {
+    const mod = await import("../index.js");
+    const { server, db } = mod.createServer(":memory:");
+    ensureV3Schema(db);
+
+    seedDoc(db, "r-older", "reflection", "2026-03-01");
+    seedDoc(db, "r-newer", "reflection", "2026-04-10");
+
+    const out = await callStats(server, { since: "1970-01-01T00:00:00Z" });
+    expect(out.last_reflection_at).toBe("2026-04-10");
+  });
+
+  it("counts new_since correctly when filtering by timestamp", async () => {
+    const mod = await import("../index.js");
+    const { server, db } = mod.createServer(":memory:");
+    ensureV3Schema(db);
+
+    seedDoc(db, "old-doc", "doc", "2026-01-01");
+    seedDoc(db, "new-doc", "doc", "2026-05-01");
+    seedDoc(db, "old-raw", "raw", "2026-01-15");
+    seedDoc(db, "new-raw", "raw", "2026-05-02");
+
+    const out = await callStats(server, { since: "2026-04-01T00:00:00Z" });
+    expect(out.total_documents).toBe(4);
+    expect(out.by_tier).toEqual({ doc: 2, raw: 2, reflection: 0 });
+    expect(out.new_since).toEqual({ doc: 1, raw: 1, reflection: 0 });
+  });
+
+  it("defaults `since` to ~24h ago when not provided", async () => {
+    const mod = await import("../index.js");
+    const { server, db } = mod.createServer(":memory:");
+    ensureV3Schema(db);
+    seedDoc(db, "d1", "doc", "2026-04-01");
+
+    const out = await callStats(server);
+    const since = out.since as string;
+    expect(since).toBeTruthy();
+    const sinceMs = Date.parse(since);
+    const nowMs = Date.now();
+    // Allow a wide window to accommodate slow test startup; the spec is 24h.
+    const ageMs = nowMs - sinceMs;
+    expect(ageMs).toBeGreaterThanOrEqual(23.5 * 3600 * 1000);
+    expect(ageMs).toBeLessThanOrEqual(24.5 * 3600 * 1000);
+  });
+
+  it("reports all documents as tier 'doc' on a v2 schema (column absent)", async () => {
+    const mod = await import("../index.js");
+    const { server, db } = mod.createServer(":memory:");
+    // Intentionally do NOT call ensureV3Schema — simulate v2 DB.
+
+    db.upsertDocument({
+      id: "legacy-doc",
+      path: "l.md",
+      title: "Legacy",
+      date: "2026-04-01",
+      type: null,
+      status: null,
+      githubIssue: null,
+      content: "",
+    });
+
+    const out = await callStats(server, { since: "1970-01-01T00:00:00Z" });
+    expect(out.total_documents).toBe(1);
+    expect(out.by_tier).toEqual({ doc: 1, raw: 0, reflection: 0 });
+    expect(out.chunks_per_doc_p50).toBe(0);
+    expect(out.chunks_per_doc_p90).toBe(0);
+    expect(out.last_reflection_at).toBeNull();
+  });
+});