Add internal JSDocs throughout the codebase

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/77726872-0686-4348-91f1-50cc99d7f8ca

Author: Copilot

.changeset/add-internal-jsdocs.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Add JSDoc comments throughout the codebase, covering all major classes, functions, and interfaces in `src/server/`, `src/typescript-generator/`, `src/repl/`, and `src/util/`.

src/app.ts

@@ -39,6 +39,16 @@ export type MockRequest = DispatcherRequest & { rawPath: string };
 
 const mswHandlers: MswHandlerMap = {};
 
+/**
+ * Dispatches a single MSW (Mock Service Worker) intercepted request to the
+ * matching Counterfact route handler registered via {@link createMswHandlers}.
+ *
+ * @param request - The intercepted request, including the HTTP method, path,
+ *   headers, query, body, and a `rawPath` that preserves the original URL
+ *   before base-path stripping.
+ * @returns The response produced by the matching handler, or a 404 object when
+ *   no handler has been registered for the given method and path.
+ */
 export async function handleMswRequest(request: MockRequest) {
   const { method, rawPath } = request;
   const handler = mswHandlers[`${method}:${rawPath}`];
@@ -49,6 +59,18 @@ export async function handleMswRequest(request: MockRequest) {
   return { error: `No handler found for ${method} ${rawPath}`, status: 404 };
 }
 
+/**
+ * Loads an OpenAPI document, registers all routes from it as MSW handlers, and
+ * returns the list of registered routes so callers (e.g. Vitest Browser mode)
+ * can mount them on their own request-interception layer.
+ *
+ * @param config - Counterfact configuration; `openApiPath` and `basePath` are
+ *   the most important fields for this function.
+ * @param ModuleLoaderClass - Injectable module-loader constructor, primarily
+ *   used in tests to substitute a test-friendly implementation.
+ * @returns An array of `{ method, path }` objects describing every registered
+ *   MSW handler.
+ */
 export async function createMswHandlers(
   config: Config,
   ModuleLoaderClass = ModuleLoader,
@@ -99,6 +121,22 @@ export async function createMswHandlers(
   return handlers;
 }
 
+/**
+ * Creates and configures a full Counterfact server instance.
+ *
+ * Sets up the route registry, context registry, scenario registry, code
+ * generator, transpiler, module loader, Koa application, and OpenAPI watcher.
+ * The returned object exposes handles for starting the server, stopping it, and
+ * launching the interactive REPL.
+ *
+ * @param config - Runtime configuration (port, paths, feature flags, etc.).
+ * @returns An object containing the configured sub-systems and two entry-point
+ *   functions:
+ *   - `start(options)` — generates/watches code and optionally starts the HTTP
+ *     server; returns a `stop()` handle.
+ *   - `startRepl()` — launches the interactive Node.js REPL connected to the
+ *     live server state.
+ */
 export async function counterfact(config: Config) {
   const modulesPath = config.basePath;
 

src/repl/raw-http-client.ts

@@ -62,6 +62,16 @@ function stringifyBody(body: string | object) {
   return JSON.stringify(body);
 }
 
+/**
+ * A minimal HTTP/1.1 client that communicates over a raw TCP socket.
+ *
+ * Used in the Counterfact REPL (`client.*`) to send requests to the local mock
+ * server and pretty-print the request and response to `stdout` with ANSI
+ * colours.
+ *
+ * Unlike `fetch` or Axios, `RawHttpClient` does not buffer or parse the
+ * response — the raw HTTP response string is returned from every method.
+ */
 export class RawHttpClient {
   host: string;
   port: number;
@@ -72,38 +82,47 @@ export class RawHttpClient {
     this.port = port;
   }
 
+  /** Sends a `GET` request and returns the raw HTTP response string. */
   get(path: string, headers = {}) {
     return this.#send("GET", path, "", headers);
   }
 
+  /** Sends a `HEAD` request and returns the raw HTTP response string. */
   head(path: string, headers = {}) {
     return this.#send("HEAD", path, "", headers);
   }
 
+  /** Sends a `POST` request with `body` and returns the raw HTTP response string. */
   post(path: string, body: string | object = "", headers = {}) {
     return this.#send("POST", path, body, headers);
   }
 
+  /** Sends a `PUT` request with `body` and returns the raw HTTP response string. */
   put(path: string, body: string | object = "", headers = {}) {
     return this.#send("PUT", path, body, headers);
   }
 
+  /** Sends a `DELETE` request and returns the raw HTTP response string. */
   delete(path: string, headers = {}) {
     return this.#send("DELETE", path, "", headers);
   }
 
+  /** Sends a `CONNECT` request and returns the raw HTTP response string. */
   connect(path: string, headers = {}) {
     return this.#send("CONNECT", path, "", headers);
   }
 
+  /** Sends an `OPTIONS` request and returns the raw HTTP response string. */
   options(path: string, headers = {}) {
     return this.#send("OPTIONS", path, "", headers);
   }
 
+  /** Sends a `TRACE` request and returns the raw HTTP response string. */
   trace(path: string, headers = {}) {
     return this.#send("TRACE", path, "", headers);
   }
 
+  /** Sends a `PATCH` request with `body` and returns the raw HTTP response string. */
   patch(path: string, body: string | object = "", headers = {}) {
     return this.#send("PATCH", path, body, headers);
   }

src/repl/repl.ts

@@ -121,6 +121,25 @@ export function createCompleter(
   };
 }
 
+/**
+ * Launches the interactive Counterfact REPL.
+ *
+ * The REPL is a standard Node.js REPL augmented with:
+ * - `context` / `loadContext(path)` globals wired to the {@link ContextRegistry}.
+ * - `client` — a {@link RawHttpClient} pre-configured for `localhost`.
+ * - `route(path)` — creates a {@link RouteBuilder} for the given path.
+ * - `.counterfact` — help command.
+ * - `.proxy` — proxy configuration command.
+ * - `.scenario` — runs a named scenario function from the scenarios directory.
+ *
+ * @param contextRegistry - The live context registry.
+ * @param registry - The route registry (used for tab completion).
+ * @param config - Server configuration.
+ * @param print - Output function; defaults to writing to `stdout`.
+ * @param openApiDocument - Optional OpenAPI document for tab completion.
+ * @param scenarioRegistry - Optional scenario registry for `.scenario` support.
+ * @returns The configured Node.js REPL server instance.
+ */
 export function startRepl(
   contextRegistry: ContextRegistry,
   registry: Registry,

src/repl/route-builder.ts

@@ -33,6 +33,19 @@ export interface MissingParams {
   query?: MissingParam[];
 }
 
+/**
+ * Immutable fluent builder for constructing and sending HTTP requests from the
+ * Counterfact REPL.
+ *
+ * Each builder method returns a **new** `RouteBuilder` instance with the
+ * updated field — the original is never mutated.  When all required parameters
+ * are set, call {@link send} to execute the request.
+ *
+ * ```ts
+ * // Inside the REPL:
+ * route("/pets/{petId}").method("get").path({ petId: 1 }).send();
+ * ```
+ */
 export class RouteBuilder {
   public readonly routePath: string;
 
@@ -116,22 +129,47 @@ export class RouteBuilder {
     });
   }
 
+  /**
+   * Returns a new builder with the HTTP method set.
+   *
+   * @param method - HTTP method name (case-insensitive, e.g. `"get"`, `"POST"`).
+   */
   public method(method: string): RouteBuilder {
     return this.clone({ method: method.toUpperCase() });
   }
 
+  /**
+   * Returns a new builder with additional path parameters merged in.
+   *
+   * @param params - Key/value map of path variable names to values.
+   */
   public path(params: Params): RouteBuilder {
     return this.clone({ pathParams: { ...this._pathParams, ...params } });
   }
 
+  /**
+   * Returns a new builder with additional query parameters merged in.
+   *
+   * @param params - Key/value map of query parameter names to values.
+   */
   public query(params: Params): RouteBuilder {
     return this.clone({ queryParams: { ...this._queryParams, ...params } });
   }
 
+  /**
+   * Returns a new builder with additional request headers merged in.
+   *
+   * @param params - Key/value map of header names to values.
+   */
   public headers(params: Params): RouteBuilder {
     return this.clone({ headerParams: { ...this._headerParams, ...params } });
   }
 
+  /**
+   * Returns a new builder with the request body set.
+   *
+   * @param body - The request body (will be serialised to JSON or sent as-is).
+   */
   public body(body: unknown): RouteBuilder {
     return this.clone({ body });
   }
@@ -140,12 +178,21 @@ export class RouteBuilder {
     return this._operation;
   }
 
+  /**
+   * Returns `true` when a method is set and no required parameters are
+   * missing.
+   */
   public ready(): boolean {
     if (!this._method) return false;
 
     return this.missing() === undefined;
   }
 
+  /**
+   * Returns a {@link MissingParams} object describing all required parameters
+   * that have not yet been set, or `undefined` when nothing is missing (or
+   * when the operation has no parameters).
+   */
   public missing(): MissingParams | undefined {
     const operation = this.getOperation();
 
@@ -177,6 +224,10 @@ export class RouteBuilder {
     return missingParams;
   }
 
+  /**
+   * Returns a human-readable help string describing the operation, its
+   * parameters, and the expected responses.
+   */
   public help(): string {
     const method = this._method ?? "[no method set]";
     const operation = this.getOperation();
@@ -260,6 +311,13 @@ export class RouteBuilder {
     return lines.join("\n");
   }
 
+  /**
+   * Executes the HTTP request and returns the parsed response body.
+   *
+   * @throws When no HTTP method has been set.
+   * @throws When required parameters are missing.
+   * @throws When an unsupported HTTP method is used.
+   */
   public async send(): Promise<unknown> {
     if (!this._method) {
       throw new Error(
@@ -389,6 +447,16 @@ export class RouteBuilder {
   }
 }
 
+/**
+ * Creates a factory function that constructs a {@link RouteBuilder} for a
+ * given route path, pre-configured with the server's host, port, and OpenAPI
+ * document.
+ *
+ * @param port - The port the Counterfact server is listening on.
+ * @param host - The server hostname (default `"localhost"`).
+ * @param openApiDocument - Optional OpenAPI document for parameter introspection.
+ * @returns A function `(routePath: string) => RouteBuilder`.
+ */
 export function createRouteFunction(
   port: number,
   host?: string,

src/server/config.ts

@@ -1,25 +1,50 @@
+/** Runtime configuration for a Counterfact server instance. */
 export interface Config {
+  /** Optional bearer token that protects the Admin API endpoints. */
   adminApiToken?: string;
+  /** When `true`, JSON Schema Faker generates values for all optional fields. */
   alwaysFakeOptionals: boolean;
+  /** Absolute path to the directory that contains generated route files. */
   basePath: string;
+  /** When `true`, transpile TypeScript route files to a `.cache/` directory. */
   buildCache: boolean;
+  /** Controls which artefacts are (re-)generated from the OpenAPI spec. */
   generate: {
+    /** Remove route files that no longer correspond to a spec path. */
     prune?: boolean;
+    /** Generate route handler stubs. */
     routes: boolean;
+    /** Generate TypeScript type files. */
     types: boolean;
   };
+  /** Path or URL to the OpenAPI document. Use `"_"` to skip spec loading. */
   openApiPath: string;
+  /** TCP port the HTTP server listens on. */
   port: number;
+  /**
+   * Per-path proxy toggle map.  `true` means requests to that path are
+   * forwarded to `proxyUrl`; `false` means they are handled locally.
+   */
   proxyPaths: Map<string, boolean>;
+  /** Base URL of the upstream server used when proxying is enabled. */
   proxyUrl: string;
+  /** URL prefix that Counterfact intercepts (default `""`). */
   routePrefix: string;
+  /** When `true`, mount the Admin API at `/_counterfact/api/`. */
   startAdminApi: boolean;
+  /** When `true`, launch the interactive REPL after the server starts. */
   startRepl: boolean;
+  /** When `true`, start the Koa HTTP server. */
   startServer: boolean;
+  /** When `true`, validate incoming requests against the OpenAPI spec. */
   validateRequests: boolean;
+  /** When `true`, validate outgoing responses against the OpenAPI spec. */
   validateResponses: boolean;
+  /** Controls which artefacts are watched for live reload. */
   watch: {
+    /** Re-generate route stubs when the OpenAPI spec changes. */
     routes: boolean;
+    /** Re-generate type files when the OpenAPI spec changes. */
     types: boolean;
   };
 }

src/server/constants.ts

@@ -1,3 +1,11 @@
+/**
+ * Default options passed to every chokidar watcher in Counterfact.
+ *
+ * - `ignoreInitial: true` — suppresses the initial `"add"` events emitted for
+ *   files already present when the watcher starts.
+ * - `usePolling: true` on Windows — chokidar's native FSEvents are unreliable
+ *   on Windows; polling is more reliable there.
+ */
 export const CHOKIDAR_OPTIONS = {
   ignoreInitial: true,
   usePolling: process.platform === "win32",