Merge remote-tracking branch 'origin/main' into copilot/convert-openapi-document-to-class

Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>

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/`.

.changeset/blue-hexagon-repl-prompt.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Make the hexagon in the REPL prompt the same shade of blue as the logo (#0071b5).

.changeset/move-openapi-example-to-fixtures.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Moved `openapi-example.yaml` from the repository root into `test/fixtures/openapi-example.yaml` and expanded it with many OpenAPI edge cases: CRUD operations on `/users` and `/users/{userId}`, polymorphic events via `oneOf`/`allOf`/`discriminator`, nullable fields, enum types, integer formats, file upload via `multipart/form-data`, cookie parameters, deprecated endpoints, multiple response content types, a no-body `204` health-check endpoint, and free-form `additionalProperties` objects.

.changeset/rename-apply-to-scenario.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Rename the `.apply` REPL command to `.scenario`. Update all references in code, tests, and documentation.

docs/adr/001-apply-command-with-function-injection.md

@@ -1,4 +1,4 @@
-# ADR 001: .apply Command Design — Minimalist Function Injection
+# ADR 001: .scenario Command Design — Minimalist Function Injection
 
 ## Status
 
@@ -8,7 +8,7 @@ Accepted
 
 Counterfact's REPL lets developers interact with the running mock server from the terminal. A common need is to transition the server into a specific state (e.g. "all pets sold", "service unavailable") in a reproducible, shareable way. Today, operators must manually call REPL commands one by one; there is no mechanism to save and replay a named scenario.
 
-The `.apply` command is proposed to address this: given a path argument, it loads and executes a user-authored script that mutates REPL context and routes, then reports what changed.
+The `.scenario` command is proposed to address this: given a path argument, it loads and executes a user-authored script that mutates REPL context and routes, then reports what changed.
 
 Three designs were proposed as working documents in `.github/issue-proposals/`:
 
@@ -27,7 +27,7 @@ Three designs were proposed as working documents in `.github/issue-proposals/`:
 
 **Solution 1 (Minimalist Function Injection) is selected.**
 
-An apply script is a TypeScript file with one or more named function exports. When `.apply <path>` is run, Counterfact splits the argument on `/`, uses the last segment as the function name and the rest as the file path (relative to `<basePath>/repl/`), dynamically imports the module, and calls the named function with a live `ApplyContext` (`$`) object:
+A scenario script is a TypeScript file with one or more named function exports. When `.scenario <path>` is run, Counterfact splits the argument on `/`, uses the last segment as the function name and the rest as the file path (relative to `<basePath>/repl/`), dynamically imports the module, and calls the named function with a live `ApplyContext` (`$`) object:
 
 ```ts
 // repl/sold-pets.ts
@@ -55,7 +55,7 @@ Scripts export named functions that receive `$: ApplyContext`. Counterfact resol
 
 ### Solution 2: Scenario Class with Lifecycle Hooks
 
-Scripts export a named class that implements a `Scenario` interface with `setup()` and optional `teardown()` methods. Counterfact instantiates the class, calls `setup()`, and tracks applied instances in a map for later `.unapply`. A static `dependencies` array enables ordered composition.
+Scripts export a named class that implements a `Scenario` interface with `setup()` and optional `teardown()` methods. Counterfact instantiates the class, calls `setup()`, and tracks applied instances in a map for later `.unscenario`. A static `dependencies` array enables ordered composition.
 
 **Why not chosen:** Class syntax and lifecycle coupling add complexity that is not justified until the need for teardown and dependency ordering is proven in practice. These concerns can be layered on top of Solution 1 once the basic command exists.
 
@@ -81,7 +81,7 @@ Identical surface syntax to Solution 1, but Counterfact wraps `context` and `rou
 
 ### Risks and downsides
 
-- Without lifecycle hooks, accumulated state across many `.apply` calls may be difficult to reason about.
+- Without lifecycle hooks, accumulated state across many `.scenario` calls may be difficult to reason about.
 - If teardown proves to be a common need, adding it later will require extending the API in a backward-compatible way.
 - Proxy-based auto-diffing (Solution 3) remains attractive for DX; deferring it means script authors will need to be disciplined about documenting context changes in the short term.
 

docs/features/repl.md

@@ -56,21 +56,21 @@ await req.send()
 
 See the [Route Builder guide](./route-builder.md) for full documentation.
 
-## Scenario scripts with `.apply`
+## Scenario scripts with `.scenario`
 
-For more complex setups you can automate REPL interactions by writing _scenario scripts_ — plain TypeScript files that export named functions. Run them with `.apply`:
+For more complex setups you can automate REPL interactions by writing _scenario scripts_ — plain TypeScript files that export named functions. Run them with `.scenario`:
 
 ```
-⬣> .apply soldPets
+⬣> .scenario soldPets
 ```
 
-**Path resolution:** the argument to `.apply` is a slash-separated path. The last segment is the function name; everything before it is the file path, resolved relative to `<basePath>/scenarios/` (with `index.ts` as the default file).
+**Path resolution:** the argument to `.scenario` is a slash-separated path. The last segment is the function name; everything before it is the file path, resolved relative to `<basePath>/scenarios/` (with `index.ts` as the default file).
 
 | Command | File | Function |
 |---|---|---|
-| `.apply foo` | `scenarios/index.ts` | `foo` |
-| `.apply foo/bar` | `scenarios/foo.ts` | `bar` |
-| `.apply foo/bar/baz` | `scenarios/foo/bar.ts` | `baz` |
+| `.scenario soldPets` | `scenarios/index.ts` | `soldPets` |
+| `.scenario pets/resetAll` | `scenarios/pets.ts` | `resetAll` |
+| `.scenario pets/orders/pending` | `scenarios/pets/orders.ts` | `pending` |
 
 A scenario function receives a single argument with `{ context, loadContext, routes, route }`:
 

openapi-example.yaml

@@ -76,7 +76,7 @@
     "lint:quickfix": "eslint --fix . eslint --fix demo-ts --rule=\"import/namespace: 0,etc/no-deprecated:0,import/no-cycle:0,no-explicit-type-exports/no-explicit-type-exports:0,import/no-deprecated:0,import/no-self-import:0,import/default:0,import/no-named-as-default:0\" --ignore-pattern dist --ignore-pattern out",
     "go:petstore": "yarn build && yarn counterfact https://petstore3.swagger.io/api/v3/openapi.json out",
     "go:petstore2": "yarn build && yarn counterfact  https://petstore.swagger.io/v2/swagger.json out",
-    "go:example": "yarn build && node ./bin/counterfact.js ./openapi-example.yaml out",
+    "go:example": "yarn build && node ./bin/counterfact.js ./test/fixtures/openapi-example.yaml out",
     "counterfact": "./bin/counterfact.js",
     "postinstall": "patch-package"
   },

package.json

@@ -38,6 +38,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}`];
@@ -48,6 +58,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,
@@ -98,6 +120,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/app.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);
   }