@forwardimpact/libmock 0.1.2

package/src/mock/fs.js

@@ -0,0 +1,301 @@
+import { Readable, Writable } from "node:stream";
+import { spy } from "./spy.js";
+/**
+ * Creates a mock filesystem backed by an in-memory Map
+ * @param {Object<string, string>} files - Initial file contents keyed by path
+ * @returns {object} Mock fs with readFile, writeFile, readdir, stat, mkdir, access, copyFile
+ */
+export function createMockFs(files = {}) {
+  const data = new Map(Object.entries(files));
+  const dirs = new Set();
+  let nextFd = 3;
+  const openFds = new Map();
+
+  // Auto-create parent directories for initial files
+  for (const path of data.keys()) {
+    const parts = path.split("/");
+    for (let i = 1; i < parts.length; i++) {
+      dirs.add(parts.slice(0, i).join("/"));
+    }
+  }
+
+  return {
+    data,
+    dirs,
+    readFile: spy(async (path, encoding) => {
+      const content = data.get(path);
+      if (content === undefined) {
+        const err = new Error(
+          `ENOENT: no such file or directory, open '${path}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+      return encoding ? content : Buffer.from(content);
+    }),
+    writeFile: spy(async (path, content) => {
+      data.set(
+        path,
+        typeof content === "string" ? content : content.toString(),
+      );
+    }),
+    appendFile: spy(async (path, content) => {
+      const chunk = typeof content === "string" ? content : content.toString();
+      data.set(path, (data.get(path) ?? "") + chunk);
+    }),
+    rename: spy(async (src, dest) => {
+      if (!data.has(src)) {
+        const err = new Error(
+          `ENOENT: no such file or directory, rename '${src}' -> '${dest}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+      data.set(dest, data.get(src));
+      data.delete(src);
+    }),
+    readdir: spy(async (path, opts = {}) => {
+      // Collect immediate children; an entry is a directory if anything lives
+      // below it (a deeper key) or it was registered via mkdir/cp.
+      const prefix = path.endsWith("/") ? path : `${path}/`;
+      const isDir = new Map();
+      for (const key of [...data.keys(), ...dirs]) {
+        if (!key.startsWith(prefix)) continue;
+        const rest = key.slice(prefix.length);
+        const name = rest.split("/")[0];
+        if (!name) continue;
+        const dir = rest.includes("/") || dirs.has(`${prefix}${name}`);
+        isDir.set(name, isDir.get(name) || dir);
+      }
+      const names = [...isDir.keys()];
+      if (!opts.withFileTypes) return names;
+      // Mirror node:fs Dirent: name + isDirectory()/isFile()/isSymbolicLink().
+      return names.map((name) => ({
+        name,
+        isDirectory: () => isDir.get(name),
+        isFile: () => !isDir.get(name),
+        isSymbolicLink: () => false,
+      }));
+    }),
+    stat: spy(async (path) => {
+      if (data.has(path)) {
+        return { isFile: () => true, isDirectory: () => false };
+      }
+      if (dirs.has(path)) {
+        return { isFile: () => false, isDirectory: () => true };
+      }
+      const err = new Error(
+        `ENOENT: no such file or directory, stat '${path}'`,
+      );
+      err.code = "ENOENT";
+      throw err;
+    }),
+    mkdir: spy(async (path) => {
+      dirs.add(path);
+    }),
+    mkdtemp: spy(async (prefix) => {
+      // Mirror node:fs/promises.mkdtemp: append 6 random chars to the prefix
+      // and register the directory. Returns the created path.
+      const path = `${prefix}${Math.random().toString(36).slice(2, 8)}`;
+      dirs.add(path);
+      return path;
+    }),
+    rm: spy(async (path, opts = {}) => {
+      // Mirror fs.rm(path, { recursive }): with `recursive`, drop the entry
+      // and every descendant so subsequent readdir/access don't see ghosts.
+      const prefix = path.endsWith("/") ? path : `${path}/`;
+      const matches = (k) =>
+        k === path || (opts.recursive && k.startsWith(prefix));
+      for (const k of [...data.keys()]) if (matches(k)) data.delete(k);
+      for (const k of [...dirs]) if (matches(k)) dirs.delete(k);
+    }),
+    lstat: spy(async (path) => {
+      if (data.has(path)) {
+        return {
+          isFile: () => true,
+          isDirectory: () => false,
+          isSymbolicLink: () => false,
+        };
+      }
+      if (dirs.has(path)) {
+        return {
+          isFile: () => false,
+          isDirectory: () => true,
+          isSymbolicLink: () => false,
+        };
+      }
+      const err = new Error(
+        `ENOENT: no such file or directory, lstat '${path}'`,
+      );
+      err.code = "ENOENT";
+      throw err;
+    }),
+    unlink: spy(async (path) => {
+      data.delete(path);
+    }),
+    symlink: spy(async (_target, path) => {
+      dirs.add(path);
+    }),
+    access: spy(async (path) => {
+      if (!data.has(path) && !dirs.has(path)) {
+        const err = new Error(
+          `ENOENT: no such file or directory, access '${path}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+    }),
+    copyFile: spy(async (src, dest) => {
+      const content = data.get(src);
+      if (content === undefined) {
+        const err = new Error(
+          `ENOENT: no such file or directory, copyFile '${src}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+      data.set(dest, content);
+    }),
+    cp: spy(async (src, dest) => {
+      // Mirror fs.cp(src, dest, { recursive }): copy a file, or a directory
+      // subtree (every entry under `src/` re-rooted under `dest/`).
+      if (data.has(src)) {
+        data.set(dest, data.get(src));
+        return;
+      }
+      const prefix = src.endsWith("/") ? src : `${src}/`;
+      const destPrefix = dest.endsWith("/") ? dest : `${dest}/`;
+      const reroot = (k) => destPrefix + k.slice(prefix.length);
+      const under = (k) => k.startsWith(prefix);
+      dirs.add(dest);
+      for (const key of [...data.keys()].filter(under)) {
+        data.set(reroot(key), data.get(key));
+      }
+      for (const dir of [...dirs].filter(under)) dirs.add(reroot(dir));
+    }),
+    // Timestamps and permissions are not modeled by the in-memory store; these
+    // record the call (via spy) so consumers stay testable and assertable.
+    utimes: spy(async () => {}),
+    chmod: spy(async () => {}),
+    existsSync: spy((path) => data.has(path) || dirs.has(path)),
+    readFileSync: spy((path, encoding) => {
+      const content = data.get(path);
+      if (content === undefined) {
+        const err = new Error(
+          `ENOENT: no such file or directory, open '${path}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+      return encoding ? content : Buffer.from(content);
+    }),
+    writeFileSync: spy((path, content) => {
+      data.set(
+        path,
+        typeof content === "string" ? content : content.toString(),
+      );
+    }),
+    mkdirSync: spy((path) => {
+      dirs.add(path);
+    }),
+    statSync: spy((path) => {
+      const content = data.get(path);
+      if (content !== undefined)
+        return {
+          size: Buffer.byteLength(content),
+          mtimeMs: 0,
+          isFile: () => true,
+          isDirectory: () => false,
+        };
+      if (dirs.has(path))
+        return {
+          size: 0,
+          mtimeMs: 0,
+          isFile: () => false,
+          isDirectory: () => true,
+        };
+      const err = new Error(
+        `ENOENT: no such file or directory, stat '${path}'`,
+      );
+      err.code = "ENOENT";
+      throw err;
+    }),
+    readdirSync: spy((dir) => {
+      const prefix = dir.endsWith("/") ? dir : `${dir}/`;
+      const names = new Set();
+      for (const key of [...data.keys(), ...dirs]) {
+        if (!key.startsWith(prefix)) continue;
+        const name = key.slice(prefix.length).split("/")[0];
+        if (name) names.add(name);
+      }
+      return [...names];
+    }),
+    // Permissions are not modeled by the in-memory store; record the call.
+    chmodSync: spy(() => {}),
+    openSync: spy((path, flags = "r") => {
+      // For write/append flags, create/truncate; for read flags, require the
+      // file to exist (mirror node:fs.openSync ENOENT). Hand back a synthetic
+      // descriptor that records its backing path.
+      const reading = typeof flags === "string" && flags.startsWith("r");
+      if (reading && !data.has(path)) {
+        const err = new Error(
+          `ENOENT: no such file or directory, open '${path}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+      if (!reading) data.set(path, "");
+      const fd = nextFd++;
+      openFds.set(fd, path);
+      return fd;
+    }),
+    readSync: spy((fd, buffer, offset = 0, length, position = 0) => {
+      // Mirror fs.readSync(fd, buffer, offset, length, position): copy bytes
+      // from the file's stored content into `buffer`, returning the byte count.
+      const path = openFds.get(fd);
+      if (path === undefined) {
+        const err = new Error("EBADF: bad file descriptor, read");
+        err.code = "EBADF";
+        throw err;
+      }
+      const content = Buffer.from(data.get(path) ?? "");
+      const start = position ?? 0;
+      const want = length ?? buffer.length - offset;
+      const slice = content.subarray(start, start + want);
+      slice.copy(buffer, offset);
+      return slice.length;
+    }),
+    closeSync: spy((fd) => {
+      openFds.delete(fd);
+    }),
+    unlinkSync: spy((path) => {
+      data.delete(path);
+    }),
+    createReadStream: spy((path) => {
+      // Stream the stored content (or error asynchronously, like node:fs).
+      const content = data.get(path);
+      if (content === undefined) {
+        const err = new Error(
+          `ENOENT: no such file or directory, open '${path}'`,
+        );
+        err.code = "ENOENT";
+        const stream = new Readable({ read() {} });
+        queueMicrotask(() => stream.emit("error", err));
+        return stream;
+      }
+      return Readable.from([Buffer.from(content)]);
+    }),
+    createWriteStream: spy((path, opts = {}) => {
+      // Accumulate writes into the in-memory store. `flags: "a"` appends.
+      const append = opts.flags === "a";
+      if (!append || !data.has(path)) data.set(path, "");
+      const stream = new Writable({
+        write(chunk, _enc, cb) {
+          data.set(path, (data.get(path) ?? "") + chunk.toString());
+          cb();
+        },
+      });
+      return stream;
+    }),
+  };
+}

package/src/mock/gh-client.js

@@ -0,0 +1,28 @@
+import { spy } from "./spy.js";
+
+const GH_METHODS = ["prCreate", "prMerge", "apiGet", "apiPost"];
+
+/**
+ * Creates a mock `GhClient` collaborator. Each method is a spy returning the
+ * configured `responses[method]` value (or a no-op default). Invocations are
+ * recorded on `calls`.
+ *
+ * @param {object} [options]
+ * @param {Record<string, unknown>} [options.responses] - Per-method returns.
+ * @returns {object} The mock gh client.
+ */
+export function createMockGhClient({ responses = {} } = {}) {
+  const calls = [];
+  const client = { calls };
+
+  for (const method of GH_METHODS) {
+    client[method] = spy(async (...args) => {
+      calls.push({ method, args });
+      if (method in responses) return responses[method];
+      if (method === "prCreate") return "";
+      return null;
+    });
+  }
+
+  return client;
+}

package/src/mock/git-client.js

@@ -0,0 +1,56 @@
+import { spy } from "./spy.js";
+
+const GIT_METHODS = [
+  "clone",
+  "init",
+  "fetch",
+  "status",
+  "rebase",
+  "rebaseAbort",
+  "mergeOursStrategy",
+  "commitAll",
+  "push",
+  "revListCount",
+  "configGet",
+  "configSet",
+  "aheadCount",
+  "remoteGetUrl",
+];
+
+/**
+ * Creates a mock `GitClient` collaborator. Every method on the real
+ * `GitClient` surface is a spy returning a no-op success by default, or the
+ * configured `responses[method]` value. `withAuth(token)` returns a client
+ * sharing the same `calls` log. Invocations are recorded on `calls`.
+ *
+ * @param {object} [options]
+ * @param {Record<string, unknown>} [options.responses] - Per-method returns.
+ * @returns {object} The mock git client.
+ */
+export function createMockGitClient({ responses = {} } = {}) {
+  const calls = [];
+  const client = { calls };
+
+  for (const method of GIT_METHODS) {
+    client[method] = spy(async (...args) => {
+      calls.push({ method, args });
+      if (method in responses) return responses[method];
+      if (method === "revListCount" || method === "aheadCount") return 0;
+      if (
+        method === "status" ||
+        method === "configGet" ||
+        method === "remoteGetUrl"
+      ) {
+        return "";
+      }
+      return { stdout: "", stderr: "", exitCode: 0 };
+    });
+  }
+
+  client.withAuth = spy((token) => {
+    calls.push({ method: "withAuth", args: [token] });
+    return client;
+  });
+
+  return client;
+}

package/src/mock/grpc.js

@@ -0,0 +1,94 @@
+import { spy } from "./spy.js";
+/**
+ * Creates a mock gRPC factory function
+ * @param {object} overrides - Method overrides
+ * @returns {Function} Mock gRPC factory
+ */
+export function createMockGrpcFn(overrides = {}) {
+  const mockGrpc = {
+    Server: function () {
+      return {
+        addService: spy(),
+        bindAsync: spy((uri, creds, callback) => callback(null, 5000)),
+        tryShutdown: spy((callback) => callback()),
+        ...overrides.server,
+      };
+    },
+    loadPackageDefinition: spy(() => ({
+      test: { Test: { service: {} } },
+    })),
+    makeGenericClientConstructor: spy(() => function () {}),
+    ServerCredentials: {
+      createInsecure: spy(),
+    },
+    credentials: {
+      createInsecure: spy(),
+    },
+    status: {
+      OK: 0,
+      CANCELLED: 1,
+      UNKNOWN: 2,
+      INVALID_ARGUMENT: 3,
+      DEADLINE_EXCEEDED: 4,
+      NOT_FOUND: 5,
+      ALREADY_EXISTS: 6,
+      PERMISSION_DENIED: 7,
+      RESOURCE_EXHAUSTED: 8,
+      FAILED_PRECONDITION: 9,
+      ABORTED: 10,
+      OUT_OF_RANGE: 11,
+      UNIMPLEMENTED: 12,
+      INTERNAL: 13,
+      UNAVAILABLE: 14,
+      DATA_LOSS: 15,
+      UNAUTHENTICATED: 16,
+    },
+    ...overrides.grpc,
+  };
+
+  const mockProtoLoader = {
+    loadSync: spy(() => ({})),
+    ...overrides.protoLoader,
+  };
+
+  return () => ({ grpc: mockGrpc, protoLoader: mockProtoLoader });
+}
+
+/**
+ * Creates a mock gRPC Metadata class
+ */
+export class MockMetadata {
+  /**
+   * Creates a new MockMetadata instance
+   */
+  constructor() {
+    this.data = new Map();
+  }
+
+  /**
+   * Sets a metadata key-value pair
+   * @param {string} key - The metadata key
+   * @param {string} value - The metadata value
+   */
+  set(key, value) {
+    this.data.set(key, value);
+  }
+
+  /**
+   * Gets metadata value by key
+   * @param {string} key - The metadata key
+   * @returns {string[]} Array containing the value, or empty array if not found
+   */
+  get(key) {
+    const value = this.data.get(key);
+    return value !== undefined ? [value] : [];
+  }
+
+  /**
+   * Returns all metadata as a plain object
+   * @returns {object} Object with all metadata key-value pairs
+   */
+  getMap() {
+    return Object.fromEntries(this.data);
+  }
+}

package/src/mock/http.js

@@ -0,0 +1,60 @@
+/**
+ * Creates a mock HTTP request with event emitter behavior
+ * @param {object} options - Request options
+ * @returns {object} Mock request
+ */
+export function createMockRequest(options = {}) {
+  const { method = "GET", url = "/", body = {}, headers = {} } = options;
+
+  const bodyStr = JSON.stringify(body);
+  let dataCallback;
+  let endCallback;
+  let errorCallback;
+
+  return {
+    method,
+    url,
+    headers,
+    on(event, callback) {
+      if (event === "data") dataCallback = callback;
+      if (event === "end") endCallback = callback;
+      if (event === "error") errorCallback = callback;
+    },
+    simulateBody() {
+      if (dataCallback) dataCallback(bodyStr);
+      if (endCallback) endCallback();
+    },
+    simulateError(err) {
+      if (errorCallback) errorCallback(err);
+    },
+  };
+}
+
+/**
+ * Creates a mock HTTP response with tracking
+ * @returns {object} Mock response
+ */
+export function createMockResponse() {
+  const response = {
+    headersSent: false,
+    statusCode: null,
+    headers: {},
+    body: "",
+    chunks: [],
+    writeHead(status, headers) {
+      response.statusCode = status;
+      response.headers = headers || {};
+      response.headersSent = true;
+    },
+    write(data) {
+      response.chunks.push(data);
+    },
+    end(data) {
+      response.body = data || "";
+    },
+    getBody() {
+      return response.chunks.join("") + response.body;
+    },
+  };
+  return response;
+}

package/src/mock/index.js

@@ -0,0 +1,49 @@
+export {
+  createMockConfig,
+  createMockServiceConfig,
+  createMockExtensionConfig,
+} from "./config.js";
+export { createMockStorage, MockStorage } from "./storage.js";
+export { createMockLogger, createSilentLogger } from "./logger.js";
+export { createMockGrpcFn, MockMetadata } from "./grpc.js";
+export { createMockRequest, createMockResponse } from "./http.js";
+export {
+  createMockObserverFn,
+  createMockTracer,
+  createMockAuthFn,
+} from "./observer.js";
+
+export { createMockResourceIndex } from "./resource-index.js";
+export {
+  createMockMemoryClient,
+  createMockLlmClient,
+  createMockAgentClient,
+  createMockTraceClient,
+  createMockVectorClient,
+  createMockGraphClient,
+  createMockToolClient,
+  createMockDiscussionClient,
+  createStatefulDiscussionClient,
+} from "./clients.js";
+export { createMockServiceCallbacks } from "./service-callbacks.js";
+export { createMockFs } from "./fs.js";
+export { createMockClock } from "./clock.js";
+export { createMockSubprocess } from "./subprocess.js";
+export { createMockFinder } from "./finder.js";
+export { createMockGitClient } from "./git-client.js";
+export { createMockGhClient } from "./gh-client.js";
+export { spy } from "./spy.js";
+export {
+  createMockSupabaseClient,
+  createTurtleHelpers,
+  createMockProcess,
+  createMockStdin,
+  withSilentConsole,
+  createMockS3Client,
+  createMockQueries,
+} from "./infra.js";
+export {
+  createGraphIndexFixture,
+  createMockGrpcHealthDefinition,
+  createReplEnvironment,
+} from "./environments.js";