@forwardimpact/libmock 0.1.2

package/src/mock/clients.js

@@ -0,0 +1,264 @@
+import { spy } from "./spy.js";
+import { common } from "@forwardimpact/libtype";
+import grpc from "@grpc/grpc-js";
+
+/**
+ * Creates a mock memory client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock memory client
+ */
+export function createMockMemoryClient(overrides = {}) {
+  return {
+    GetWindow: spy(() =>
+      Promise.resolve({
+        messages: [{ role: "system", content: "You are an assistant" }],
+        tools: [],
+      }),
+    ),
+    AppendMemory: spy(() => Promise.resolve({ accepted: "test-id" })),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock LLM client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock LLM client
+ */
+export function createMockLlmClient(overrides = {}) {
+  return {
+    CreateCompletions: spy(() =>
+      Promise.resolve({
+        id: "test-completion",
+        choices: [
+          {
+            message: common.Message.fromObject({
+              role: "assistant",
+              content: "Test response",
+            }),
+          },
+        ],
+        usage: { total_tokens: 100 },
+      }),
+    ),
+    CreateEmbeddings: spy(() =>
+      Promise.resolve({
+        data: [{ index: 0, embedding: [0.1, 0.2, 0.3] }],
+      }),
+    ),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock agent client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock agent client
+ */
+export function createMockAgentClient(overrides = {}) {
+  return {
+    ProcessUnary: spy(() =>
+      Promise.resolve({
+        resource_id: "test-conversation",
+        choices: [
+          {
+            message: common.Message.fromObject({
+              role: "assistant",
+              content: "Test response",
+            }),
+          },
+        ],
+      }),
+    ),
+    ProcessStream: spy(),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock trace client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock trace client
+ */
+export function createMockTraceClient(overrides = {}) {
+  return {
+    RecordSpan: spy(() => Promise.resolve()),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock vector client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock vector client
+ */
+export function createMockVectorClient(overrides = {}) {
+  return {
+    SearchContent: spy(() =>
+      Promise.resolve({
+        identifiers: [],
+      }),
+    ),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock graph client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock graph client
+ */
+export function createMockGraphClient(overrides = {}) {
+  return {
+    QueryByPattern: spy(() =>
+      Promise.resolve({
+        identifiers: [],
+      }),
+    ),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock tool client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock tool client
+ */
+export function createMockToolClient(overrides = {}) {
+  return {
+    CallTool: spy(() =>
+      Promise.resolve({
+        content: "Tool result",
+      }),
+    ),
+    ...overrides,
+  };
+}
+
+function notFound() {
+  return Object.assign(new Error("not found"), {
+    code: grpc.status.NOT_FOUND,
+  });
+}
+
+/**
+ * Creates a mock discussion (bridge) client
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock discussion client
+ */
+export function createMockDiscussionClient(overrides = {}) {
+  return {
+    LoadDiscussion: spy(() => Promise.reject(notFound())),
+    LoadDiscussionByCorrelation: spy(() => Promise.reject(notFound())),
+    ListOpenRecesses: spy(() => Promise.resolve({ refs: [] })),
+    SaveDiscussion: spy(() => Promise.resolve({})),
+    HasOrigin: spy(() => Promise.resolve({ exists: false })),
+    RecordOrigin: spy(() => Promise.resolve({})),
+    Sweep: spy(() =>
+      Promise.resolve({
+        evicted_discussions: 0,
+        evicted_origins: 0,
+        evicted_pending: 0,
+      }),
+    ),
+    PutPendingDispatch: spy(() => Promise.resolve({})),
+    ResolvePendingDispatch: spy(() => Promise.reject(notFound())),
+    ...overrides,
+  };
+}
+
+function coerceInt64Fields(obj) {
+  obj.open_rfcs ??= {};
+  obj.pending_callbacks ??= {};
+  obj.history ??= [];
+  obj.participants ??= [];
+  obj.dispatches = (obj.dispatches ?? []).map(Number);
+  if (obj.last_active_at != null)
+    obj.last_active_at = Number(obj.last_active_at);
+  for (const rfc of Object.values(obj.open_rfcs)) {
+    if (rfc.due_at != null) rfc.due_at = Number(rfc.due_at);
+    if (rfc.opened_at != null) rfc.opened_at = Number(rfc.opened_at);
+    if (rfc.history_index_at_open != null)
+      rfc.history_index_at_open = Number(rfc.history_index_at_open);
+    if (rfc.trigger?.replies != null)
+      rfc.trigger.replies = Number(rfc.trigger.replies);
+  }
+}
+
+/**
+ * Creates a stateful mock discussion client that retains records across
+ * save/load cycles, coercing proto int64 fields back to numbers.
+ * @returns {object} Stateful mock discussion client
+ */
+export function createStatefulDiscussionClient() {
+  const records = new Map();
+  const origins = new Map();
+  const pending = new Map();
+
+  return {
+    SaveDiscussion: spy(async (req) => {
+      const obj = req?.toJSON?.() ?? req;
+      coerceInt64Fields(obj);
+      records.set(obj.id, obj);
+      return {};
+    }),
+    LoadDiscussion: spy(async (req) => {
+      const obj = req?.toJSON?.() ?? req;
+      const key = `${obj.channel}:${obj.discussion_id}`;
+      const rec = records.get(key);
+      if (!rec) throw notFound();
+      return rec;
+    }),
+    LoadDiscussionByCorrelation: spy(async (req) => {
+      const obj = req?.toJSON?.() ?? req;
+      for (const rec of records.values()) {
+        if (
+          Object.values(rec.pending_callbacks ?? {}).includes(
+            obj.correlation_id,
+          ) ||
+          rec.open_rfcs?.[obj.correlation_id]
+        )
+          return rec;
+      }
+      throw notFound();
+    }),
+    ListOpenRecesses: spy(async () => {
+      const refs = [];
+      for (const rec of records.values())
+        for (const [cid, rfc] of Object.entries(rec.open_rfcs ?? {}))
+          if (typeof rfc.due_at === "number")
+            refs.push({ correlation_id: cid, due_at: rfc.due_at });
+      return { refs };
+    }),
+    HasOrigin: spy(async (req) => {
+      const obj = req?.toJSON?.() ?? req;
+      return { exists: origins.has(obj.id) };
+    }),
+    RecordOrigin: spy(async (req) => {
+      const obj = req?.toJSON?.() ?? req;
+      origins.set(obj.id, obj);
+      return {};
+    }),
+    Sweep: spy(async () => ({
+      evicted_discussions: 0,
+      evicted_origins: 0,
+      evicted_pending: 0,
+    })),
+    PutPendingDispatch: spy(async (req) => {
+      const obj = req?.toJSON?.() ?? req;
+      const p = obj.pending ?? obj;
+      pending.set(p.link_token, p);
+      return {};
+    }),
+    ResolvePendingDispatch: spy(async (req) => {
+      const obj = req?.toJSON?.() ?? req;
+      const token = obj.link_token;
+      const rec = pending.get(token);
+      if (!rec) throw notFound();
+      pending.delete(token);
+      return rec;
+    }),
+    EnqueueInbox: spy(async () => ({})),
+    DrainInbox: spy(async () => ({ messages: [] })),
+  };
+}

package/src/mock/clock.js

@@ -0,0 +1,62 @@
+import { spy } from "./spy.js";
+
+/**
+ * Creates a mock clock with controllable time and a no-wait sleep.
+ *
+ * `now()` returns the current virtual time in ms. `sleep(ms)` advances
+ * virtual time by `ms` and resolves on the next microtask — no real
+ * timers are scheduled. `advance(ms)` lets a test move time forward
+ * without going through `sleep` (e.g. to expire a token).
+ *
+ * Pass `{ sleep, now }` from a returned clock to any constructor that
+ * accepts those collaborators to make its tests deterministic.
+ *
+ * `setTimeout(fn, ms)` / `clearTimeout(handle)` / `setInterval(fn, ms)` /
+ * `clearInterval(handle)` delegate to the host's real timers (matching
+ * `createDefaultClock`), so a migrated module that schedules work through the
+ * injected clock keeps its real-timer test behaviour. Virtual `now()` and the
+ * real timers are intentionally independent — a test that needs a fired timer
+ * waits on real time as it did before migration; a periodic sweep timer is
+ * typically `.unref()`'d and never fires during a unit test, which exercises
+ * its eviction path through an explicit `now` argument instead.
+ *
+ * @param {object} [options]
+ * @param {number} [options.start=0] - Initial virtual time in ms.
+ * @returns {{
+ *   now: () => number,
+ *   sleep: (ms: number) => Promise<void>,
+ *   setTimeout: (fn: Function, ms: number) => *,
+ *   clearTimeout: (handle: *) => void,
+ *   setInterval: (fn: Function, ms: number) => *,
+ *   clearInterval: (handle: *) => void,
+ *   advance: (ms: number) => void,
+ *   set: (ms: number) => void,
+ *   sleeps: Array<number>,
+ * }}
+ */
+export function createMockClock({ start = 0 } = {}) {
+  let current = start;
+  const sleeps = [];
+
+  const now = spy(() => current);
+  const sleep = spy(async (ms) => {
+    sleeps.push(ms);
+    current += ms;
+  });
+
+  return {
+    now,
+    sleep,
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (handle) => clearInterval(handle),
+    advance(ms) {
+      current += ms;
+    },
+    set(ms) {
+      current = ms;
+    },
+    sleeps,
+  };
+}

package/src/mock/config.js

@@ -0,0 +1,45 @@
+/**
+ * Creates a mock configuration object
+ * @param {string} name - Service/extension name
+ * @param {object} overrides - Properties to override
+ * @returns {object} Mock config
+ */
+export function createMockConfig(name = "test-service", overrides = {}) {
+  return {
+    name,
+    namespace: "test",
+    host: "0.0.0.0",
+    port: 3000,
+    max_tokens: 4096,
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock service config with common service properties
+ * @param {string} name - Service name
+ * @param {object} overrides - Properties to override
+ * @returns {object} Mock service config
+ */
+export function createMockServiceConfig(name, overrides = {}) {
+  return createMockConfig(name, {
+    budget: 1000,
+    threshold: 0.3,
+    limit: 10,
+    ...overrides,
+  });
+}
+
+/**
+ * Creates a mock extension config
+ * @param {string} name - Extension name
+ * @param {object} overrides - Properties to override
+ * @returns {object} Mock extension config
+ */
+export function createMockExtensionConfig(name, overrides = {}) {
+  return createMockConfig(name, {
+    secret: "test-secret",
+    anthropicToken: async () => "test-anthropic-key",
+    ...overrides,
+  });
+}

package/src/mock/data.js

@@ -0,0 +1,46 @@
+/**
+ * Shared test data for common testing scenarios
+ */
+
+// Sample request data
+export const testRequestData = {
+  query: "test query",
+  userId: "test-user-123",
+  sessionId: "test-session-456",
+};
+
+// Sample vector data
+export const testVectorData = [
+  { id: "vector-1", embedding: [0.1, 0.2, 0.3], score: 0.9 },
+  { id: "vector-2", embedding: [0.4, 0.5, 0.6], score: 0.8 },
+  { id: "vector-3", embedding: [0.7, 0.8, 0.9], score: 0.7 },
+];
+
+// Sample message data
+export const testMessageData = [
+  { role: "system", content: "You are a helpful assistant." },
+  { role: "user", content: "Hello, how are you?" },
+  { role: "assistant", content: "I'm doing well, thank you for asking!" },
+];
+
+// Sample chunk data
+export const testChunkData = [
+  {
+    id: "chunk-1",
+    text: "This is a sample text chunk for testing purposes.",
+    tokens: 10,
+  },
+  {
+    id: "chunk-2",
+    text: "Another sample chunk with different content.",
+    tokens: 8,
+  },
+];
+
+// Sample configuration data
+export const testConfigData = {
+  host: "localhost",
+  port: 3000,
+  threshold: 0.5,
+  limit: 100,
+};

package/src/mock/environments.js

@@ -0,0 +1,80 @@
+import { createMockStorage } from "./storage.js";
+
+/**
+ * Graph-index test triple: a mock storage, an n3 Store, and a GraphIndex wired
+ * to both. GraphIndex and Store are injected so libmock stays dependency-free.
+ * @param {object} opts
+ * @param {Function} opts.GraphIndex - libgraph GraphIndex constructor.
+ * @param {Function} opts.Store - n3 Store constructor.
+ * @param {object} [opts.storageOverrides] - passed to createMockStorage.
+ * @param {*} [opts.prefixes] - prefixes arg for GraphIndex (default {}).
+ * @param {string} [opts.indexKey] - jsonl key (default "test-graph.jsonl").
+ * @returns {{ n3Store: object, graphIndex: object, mockStorage: object }}
+ */
+export function createGraphIndexFixture({
+  GraphIndex,
+  Store,
+  storageOverrides,
+  prefixes = {},
+  indexKey = "test-graph.jsonl",
+}) {
+  const mockStorage = createMockStorage(storageOverrides);
+  const n3Store = new Store();
+  const graphIndex = new GraphIndex(mockStorage, n3Store, prefixes, indexKey);
+  return { n3Store, graphIndex, mockStorage };
+}
+
+/**
+ * The stripped gRPC health service definition consumers' tests fake — the
+ * `{ Check: { path, requestStream, responseStream } }` shape, not librpc's
+ * real `healthDefinition` (which librpc's own tests exercise directly).
+ * @returns {{ Check: { path: string, requestStream: boolean, responseStream: boolean } }}
+ */
+export function createMockGrpcHealthDefinition() {
+  return {
+    Check: {
+      path: "/grpc.health.v1.Health/Check",
+      requestStream: false,
+      responseStream: false,
+    },
+  };
+}
+
+/**
+ * The readline/process/os/formatter/storage bundle librepl's tests inject.
+ * Mirrors libraries/librepl/test/librepl.test.js's pre-collapse beforeEach.
+ * @returns {{ readline: object, process: object, os: object, formatter: Function, storage: object }}
+ */
+export function createReplEnvironment() {
+  const proc = {
+    argv: ["node", "script.js"],
+    stdin: {
+      isTTY: true,
+      setEncoding: () => {},
+      async *[Symbol.asyncIterator]() {
+        yield "test input";
+      },
+    },
+    stdout: { write: () => {} },
+    stderr: { write: () => {} },
+    exit: (code) => {
+      proc._exitCalled = true;
+      proc._exitCode = code;
+    },
+    _exitCalled: false,
+    _exitCode: null,
+  };
+  return {
+    readline: {
+      createInterface: () => ({
+        on: () => {},
+        prompt: () => {},
+        close: () => {},
+      }),
+    },
+    process: proc,
+    os: { userInfo: () => ({ uid: 1000 }) },
+    formatter: () => ({ format: (text) => `formatted: ${text}` }),
+    storage: createMockStorage(),
+  };
+}

package/src/mock/finder.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { spy } from "./spy.js";
+
+/**
+ * Creates a mock `Finder` collaborator over an in-memory `files` map. Mimics
+ * the real `Finder` surface (`findUpward`, `findData`, `findProjectRoot`,
+ * `findPackagePath`, `findGeneratedPath`, `createSymlink`,
+ * `createPackageSymlinks`) without touching the real filesystem. Every call
+ * is recorded on `calls`.
+ *
+ * @param {object} [options]
+ * @param {Object<string, true|string>} [options.files] - Existing paths.
+ * @param {string} [options.cwd="/work"] - Working directory for `findData`.
+ * @returns {object} The mock finder.
+ */
+export function createMockFinder({ files = {}, cwd = "/work" } = {}) {
+  const calls = [];
+  const has = (p) => Object.hasOwn(files, p);
+  const record = (name, args) => calls.push({ name, args });
+
+  const findUpward = spy((root, relativePath, maxDepth = 3) => {
+    record("findUpward", [root, relativePath, maxDepth]);
+    let current = root;
+    for (let depth = 0; depth < maxDepth; depth++) {
+      const candidate = path.join(current, relativePath);
+      if (has(candidate)) return candidate;
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+    return null;
+  });
+
+  const findData = spy((baseName, homeDir) => {
+    record("findData", [baseName, homeDir]);
+    const found = findUpward(cwd, baseName);
+    if (found) return found;
+    const homePath = path.join(homeDir, ".fit", baseName);
+    if (has(homePath)) return homePath;
+    throw new Error(`No ${baseName} directory found.`);
+  });
+
+  const findProjectRoot = spy((startPath) => {
+    record("findProjectRoot", [startPath]);
+    const pkg = findUpward(startPath, "package.json", 5);
+    if (pkg) return path.dirname(pkg);
+    throw new Error("Could not find project root");
+  });
+
+  const findPackagePath = spy((projectRoot, packageName) => {
+    record("findPackagePath", [projectRoot, packageName]);
+    return path.join(projectRoot, "libraries", packageName);
+  });
+
+  const findGeneratedPath = spy((projectRoot, packageName) => {
+    record("findGeneratedPath", [projectRoot, packageName]);
+    return path.join(
+      findPackagePath(projectRoot, packageName),
+      "src",
+      "generated",
+    );
+  });
+
+  const createSymlink = spy(async (sourcePath, targetPath) => {
+    record("createSymlink", [sourcePath, targetPath]);
+    files[targetPath] = sourcePath;
+  });
+
+  const createPackageSymlinks = spy(async (generatedPath) => {
+    record("createPackageSymlinks", [generatedPath]);
+  });
+
+  return {
+    findUpward,
+    findData,
+    findProjectRoot,
+    findPackagePath,
+    findGeneratedPath,
+    createSymlink,
+    createPackageSymlinks,
+    calls,
+  };
+}