counterfact 2.7.0 → 2.9.0

package/dist/server/response-builder.js

@@ -56,6 +56,21 @@ function unknownStatusCodeResponse(statusCode) {
         status: 500,
     };
 }
+/**
+ * Creates the `$.response` builder proxy made available to route handlers.
+ *
+ * The proxy maps HTTP status codes to a fluent builder object.  Example usage
+ * in a route handler:
+ *
+ * ```ts
+ * return $.response[200].json({ id: 1, name: "Fluffy" });
+ * ```
+ *
+ * @param operation - The OpenAPI operation descriptor used for schema-driven
+ *   random generation and example resolution.
+ * @param config - Server configuration (e.g. `alwaysFakeOptionals`).
+ * @returns A {@link ResponseBuilder} proxy keyed by HTTP status code.
+ */
 export function createResponseBuilder(operation, config) {
     return new Proxy({}, {
         get: (target, statusCode) => ({

package/dist/server/scenario-registry.js

@@ -1,11 +1,37 @@
+/**
+ * Registry of loaded scenario modules.
+ *
+ * Scenario modules are plain JavaScript/TypeScript files that export named
+ * functions.  Each module is keyed by a slash-delimited path relative to the
+ * `scenarios/` directory (e.g. `"index"`, `"sub/reset"`).
+ *
+ * The registry is used by the REPL's `.scenario` command and by tab-completion
+ * to enumerate available scenarios and their exported function names.
+ */
 export class ScenarioRegistry {
     modules = new Map();
+    /**
+     * Registers (or replaces) a scenario module.
+     *
+     * @param key - Slash-delimited file key (e.g. `"index"`, `"auth/setup"`).
+     * @param module - The module's exported values.
+     */
     add(key, module) {
         this.modules.set(key, module);
     }
+    /**
+     * Removes the scenario module for `key`.
+     *
+     * @param key - The file key to remove.
+     */
     remove(key) {
         this.modules.delete(key);
     }
+    /**
+     * Returns the module for `fileKey`, or `undefined` if not registered.
+     *
+     * @param fileKey - The file key to look up.
+     */
     getModule(fileKey) {
         return this.modules.get(fileKey);
     }

package/dist/server/tools.js

@@ -1,12 +1,33 @@
 import { generate } from "json-schema-faker";
+/**
+ * A collection of utility helpers made available to route handlers via
+ * `$.tools`.
+ *
+ * Provides random selection, content-type acceptance checking, and
+ * schema-based random data generation.
+ */
 export class Tools {
     headers;
     constructor({ headers = {}, } = {}) {
         this.headers = headers;
     }
+    /**
+     * Returns a randomly selected element from `array`.
+     *
+     * @param array - The array to pick from.
+     * @returns A random element.
+     */
     oneOf(array) {
         return array[Math.floor(Math.random() * array.length)];
     }
+    /**
+     * Returns `true` when the request's `Accept` header is compatible with
+     * `contentType`.
+     *
+     * A missing or empty `Accept` header is treated as `*/*` (accepts anything).
+     *
+     * @param contentType - The MIME type to check (e.g. `"application/json"`).
+     */
     accepts(contentType) {
         const acceptHeader = Object.entries(this.headers).find(([key]) => key.toLowerCase() === "accept")?.[1];
         if (acceptHeader === "" || acceptHeader === undefined) {
@@ -19,6 +40,12 @@ export class Tools {
                 (subtype === "*" || subtype === contentType.split("/")[1]));
         });
     }
+    /**
+     * Generates a random value that satisfies `schema` using json-schema-faker.
+     *
+     * @param schema - A JSON Schema object.
+     * @returns A promise that resolves to a generated value.
+     */
     randomFromSchema(schema) {
         return generate(schema, { useExamplesValue: true, fillProperties: false });
     }

package/dist/server/transpiler.js

@@ -1,14 +1,26 @@
 // Stryker disable all
 import { once } from "node:events";
 import fs from "node:fs/promises";
-import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- transpiler consumes watched source files and writes paired outputs under configured directories. */
 import { watch as chokidarWatch } from "chokidar";
 import createDebug from "debug";
 import ts from "typescript";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
+import { toForwardSlashPath, pathJoin } from "../util/forward-slash-path.js";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
 import { convertFileExtensionsToCjs } from "./convert-js-extensions-to-cjs.js";
 const debug = createDebug("counterfact:server:transpiler");
+/**
+ * Watches TypeScript source files in `sourcePath` and compiles them to
+ * JavaScript in `destinationPath` using the TypeScript compiler API.
+ *
+ * Used when the runtime cannot execute TypeScript natively (i.e. Node.js
+ * without the `--experimental-strip-types` flag).  Each file is compiled
+ * independently (no type-checking) for maximum speed.
+ *
+ * Emits DOM-style events: `"write"` after a successful transpile, `"delete"`
+ * after a source file is removed, and `"error"` on write or compilation errors.
+ */
 export class Transpiler extends EventTarget {
     sourcePath;
     destinationPath;
@@ -23,6 +35,11 @@ export class Transpiler extends EventTarget {
     get extension() {
         return this.moduleKind.toLowerCase() === "commonjs" ? ".cjs" : ".js";
     }
+    /**
+     * Starts the file-system watcher and transpiles all existing files in the
+     * source path.  Resolves once the initial scan and all pending transpiles
+     * are complete.
+     */
     async watch() {
         debug("transpiler: watch");
         this.watcher = chokidarWatch(this.sourcePath, {
@@ -36,11 +53,10 @@ export class Transpiler extends EventTarget {
             const JS_EXTENSIONS = ["js", "mjs", "ts", "mts"];
             if (!JS_EXTENSIONS.some((extension) => sourcePathOriginal.endsWith(`.${extension}`)))
                 return;
-            const sourcePath = sourcePathOriginal.replaceAll("\\", "/");
-            const destinationPath = sourcePath
+            const sourcePath = toForwardSlashPath(sourcePathOriginal);
+            const destinationPath = toForwardSlashPath(sourcePath
                 .replace(this.sourcePath, this.destinationPath)
-                .replaceAll("\\", "/")
-                .replace(".ts", this.extension);
+                .replace(".ts", this.extension));
             if (["add", "change"].includes(eventName)) {
                 transpiles.push(this.transpileFile(eventName, sourcePath, destinationPath));
             }
@@ -61,6 +77,7 @@ export class Transpiler extends EventTarget {
         await once(this.watcher, "ready");
         await Promise.all(transpiles);
     }
+    /** Closes the file-system watcher. */
     async stopWatching() {
         await this.watcher?.close();
     }
@@ -81,11 +98,9 @@ export class Transpiler extends EventTarget {
             }
         }
         const result = transpileOutput.outputText;
-        const fullDestination = nodePath
-            .join(sourcePath
+        const fullDestination = pathJoin(sourcePath
             .replace(this.sourcePath, this.destinationPath)
-            .replace(".ts", this.extension))
-            .replaceAll("\\", "/");
+            .replace(".ts", this.extension));
         const resultWithTransformedFileExtensions = convertFileExtensionsToCjs(result);
         try {
             await fs.writeFile(fullDestination, resultWithTransformedFileExtensions);

package/dist/server/{admin-api-middleware.js → web-server/admin-api-middleware.js}

@@ -24,16 +24,25 @@ function isLoopbackIp(ip) {
 /**
  * Admin API middleware for programmatic access to Counterfact internals.
  * Exposes context management, proxy configuration, and route discovery
- * through HTTP endpoints at /_counterfact/api/*
+ * through HTTP endpoints at the given path prefix.
  *
  * This enables AI agents and external tools to interact with the mock server
  * in the same way the REPL does, but via HTTP requests.
+ *
+ * @param pathPrefix - The URL path prefix at which the admin API is mounted,
+ *   e.g. `"/_counterfact/api"`. Requests to paths that do not start with this
+ *   prefix fall through to the next middleware.
+ * @param registry - The route registry used to list available routes.
+ * @param contextRegistry - The context registry used to read and update
+ *   per-path context objects.
+ * @param config - Server configuration (proxy settings, port, etc.).
+ * @returns A Koa middleware function.
  */
-export function adminApiMiddleware(registry, contextRegistry, config) {
+export function adminApiMiddleware(pathPrefix, registry, contextRegistry, config) {
     return async (ctx, next) => {
         const { pathname } = ctx.URL;
-        // Only handle admin API routes
-        if (!pathname.startsWith("/_counterfact/api/")) {
+        // Only handle admin API routes (exact prefix or paths beneath it)
+        if (pathname !== pathPrefix && !pathname.startsWith(`${pathPrefix}/`)) {
             return await next();
         }
         // ===== Admin API Access Guard =====
@@ -72,9 +81,10 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
             }
         }
         debug("Admin API request: %s %s", ctx.method, pathname);
-        // Extract route components: ["_counterfact", "api", "resource", ...rest]
-        const parts = pathname.split("/").filter(Boolean);
-        const [, , resource, ...rest] = parts;
+        // Extract the resource path after the prefix
+        const subPath = pathname.slice(pathPrefix.length);
+        const parts = subPath.split("/").filter(Boolean);
+        const [resource, ...rest] = parts;
         try {
             // ===== Health Check =====
             if (resource === "health" && ctx.method === "GET") {
@@ -83,7 +93,7 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
                     port: config.port,
                     uptime: process.uptime(),
                     basePath: config.basePath,
-                    routePrefix: config.routePrefix,
+                    prefix: config.prefix,
                 };
                 return;
             }
@@ -155,7 +165,7 @@ export function adminApiMiddleware(registry, contextRegistry, config) {
                         openApiPath: config.openApiPath,
                         port: config.port,
                         proxyUrl: config.proxyUrl,
-                        routePrefix: config.routePrefix,
+                        prefix: config.prefix,
                         startAdminApi: config.startAdminApi,
                         startRepl: config.startRepl,
                         startServer: config.startServer,

package/dist/server/web-server/create-koa-app.js

@@ -0,0 +1,68 @@
+import createDebug from "debug";
+import Koa from "koa";
+import bodyParser from "koa-bodyparser";
+import { koaSwagger } from "koa2-swagger-ui";
+import { adminApiMiddleware } from "./admin-api-middleware.js";
+import { routesMiddleware } from "./routes-middleware.js";
+import { openapiMiddleware } from "./openapi-middleware.js";
+const debug = createDebug("counterfact:server:create-koa-app");
+/**
+ * Builds and configures the Koa application with all built-in middleware.
+ *
+ * The middleware stack (in order) is:
+ * 1. Per runner: OpenAPI document serving at `/counterfact/openapi${runner.subdirectory}`
+ * 2. Per runner: Swagger UI at `/counterfact/swagger${runner.subdirectory}`
+ * 3. Per runner: Admin API (when `config.startAdminApi` is `true`) at `/_counterfact/api${runner.subdirectory}`
+ * 4. Redirect `/counterfact` → `/counterfact/swagger`
+ * 5. Body parser
+ * 6. JSON serialisation of object bodies
+ * 7. Per runner: Route-dispatching middleware at `runner.prefix`
+ *
+ * @param runners - The ApiRunner instances, one per API spec.
+ * @param config - Server configuration.
+ * @returns A configured Koa application (not yet listening).
+ */
+export function createKoaApp({ runners, config, }) {
+    const app = new Koa();
+    for (const runner of runners) {
+        app.use(openapiMiddleware(`/counterfact/openapi${runner.subdirectory}`, {
+            path: runner.openApiPath,
+            baseUrl: `//localhost:${config.port}${runner.prefix}`,
+        }));
+        app.use(koaSwagger({
+            routePrefix: `/counterfact/swagger${runner.subdirectory}`,
+            swaggerOptions: {
+                url: `/counterfact/openapi${runner.subdirectory}`,
+            },
+        }));
+        if (config.startAdminApi) {
+            app.use(adminApiMiddleware(`/_counterfact/api${runner.subdirectory}`, runner.registry, runner.contextRegistry, config));
+        }
+    }
+    debug("basePath: %s", config.basePath);
+    app.use(async (ctx, next) => {
+        if (ctx.URL.pathname === "/counterfact") {
+            ctx.redirect("/counterfact/swagger");
+            return;
+        }
+        await next();
+    });
+    app.use(bodyParser());
+    app.use(async (ctx, next) => {
+        await next();
+        if (ctx.body !== null &&
+            ctx.body !== undefined &&
+            typeof ctx.body === "object" &&
+            !Buffer.isBuffer(ctx.body)) {
+            ctx.body = JSON.stringify(ctx.body, null, 2);
+            ctx.type = "application/json";
+        }
+    });
+    for (const runner of runners) {
+        app.use(routesMiddleware(runner.prefix, runner.dispatcher, {
+            proxyPaths: config.proxyPaths,
+            proxyUrl: config.proxyUrl,
+        }));
+    }
+    return app;
+}

package/dist/server/web-server/openapi-middleware.js

@@ -0,0 +1,34 @@
+import { bundle } from "@apidevtools/json-schema-ref-parser";
+import { dump } from "js-yaml";
+/**
+ * Returns a Koa middleware that serves a bundled OpenAPI document as YAML at
+ * the given `pathPrefix`.
+ *
+ * The served document is augmented with a `servers` entry (OpenAPI 3.x) and a
+ * `host` field (OpenAPI 2.x / Swagger) so that the Swagger UI can send
+ * requests to the running Counterfact instance.
+ *
+ * @param pathPrefix - The URL path at which to serve the document, e.g.
+ *   `"/counterfact/openapi"`. Requests to any other path fall through to the
+ *   next middleware.
+ * @param document - Descriptor providing `path` (file path or URL to the
+ *   source OpenAPI document) and `baseUrl` (the base URL to inject, e.g.
+ *   `"//localhost:3100/api"`).
+ * @returns A Koa middleware function.
+ */
+export function openapiMiddleware(pathPrefix, document) {
+    return async (ctx, next) => {
+        if (ctx.URL.pathname !== pathPrefix) {
+            return await next();
+        }
+        const openApiDocument = (await bundle(document.path));
+        openApiDocument.servers ??= [];
+        openApiDocument.servers.unshift({
+            description: "Counterfact",
+            url: document.baseUrl,
+        });
+        // OpenApi 2 support:
+        openApiDocument.host = document.baseUrl;
+        ctx.body = dump(openApiDocument);
+    };
+}

package/dist/server/{koa-middleware.js → web-server/routes-middleware.js}

@@ -1,6 +1,6 @@
 import createDebug from "debug";
 import koaProxy from "koa-proxies";
-import { isProxyEnabledForPath } from "./is-proxy-enabled-for-path.js";
+import { isProxyEnabledForPath } from "../is-proxy-enabled-for-path.js";
 const debug = createDebug("counterfact:server:create-koa-app");
 const HTTP_STATUS_CODE_OK = 200;
 const HEADERS_TO_DROP = new Set([
@@ -40,17 +40,37 @@ function getAuthObject(ctx) {
     const [username, password] = user.split(":");
     return { password, username };
 }
-export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
+/**
+ * Builds the Koa middleware function that bridges Koa's request context with
+ * the Counterfact {@link Dispatcher}.
+ *
+ * Responsibilities:
+ * - Respects `prefix` — requests outside the prefix are passed to `next`.
+ * - Adds CORS headers to every response.
+ * - Handles `OPTIONS` pre-flight requests (200 with CORS headers, no body).
+ * - Proxies the request upstream when proxy is enabled for the path.
+ * - Forwards the request to the dispatcher and maps the response back onto
+ *   the Koa context.
+ *
+ * @param prefix - The URL path prefix that this middleware handles, e.g.
+ *   `"/api/v1"`. Requests to paths that do not start with this prefix fall
+ *   through to the next middleware.
+ * @param dispatcher - The {@link Dispatcher} instance that handles requests.
+ * @param config - Server configuration (proxy settings, etc.).
+ * @param proxy - Proxy factory; injectable for testing.
+ * @returns A Koa middleware function.
+ */
+export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
     return async function middleware(ctx, next) {
-        const { proxyUrl, routePrefix } = config;
+        const { proxyUrl } = config;
         debug("middleware running for path: %s", ctx.request.path);
-        debug("routePrefix: %s", routePrefix);
-        if (!ctx.request.path.startsWith(routePrefix)) {
+        debug("prefix: %s", prefix);
+        if (!ctx.request.path.startsWith(prefix)) {
             return await next();
         }
         const auth = getAuthObject(ctx);
         const { body, headers, query, rawBody } = ctx.request;
-        const path = ctx.request.path.slice(routePrefix.length);
+        const path = ctx.request.path.slice(prefix.length);
         const method = ctx.request.method;
         if (isProxyEnabledForPath(path, config) && proxyUrl) {
             return proxy("/", { changeOrigin: true, target: proxyUrl })(ctx, next);

package/dist/typescript-generator/code-generator.js

@@ -1,7 +1,24 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- generated files are written under the caller-provided destination tree. */
 import { watch } from "chokidar";
+import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "../server/constants.js";
+import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { waitForEvent } from "../util/wait-for-event.js";
-import { generate } from "./generate.js";
+import { OperationCoder } from "./operation-coder.js";
+import { pruneRoutes } from "./prune.js";
+import { Repository } from "./repository.js";
+import { Specification } from "./specification.js";
+const debug = createDebug("counterfact:typescript-generator:generate");
+/**
+ * Orchestrates the code-generation pipeline and optional file-system watching.
+ *
+ * When {@link watch} is called, Counterfact watches the source OpenAPI document
+ * for changes and re-runs code generation automatically.  `"generate"` and
+ * `"failed"` events are emitted after each attempt.
+ */
 export class CodeGenerator extends EventTarget {
     openapiPath;
     destination;
@@ -13,15 +30,111 @@ export class CodeGenerator extends EventTarget {
         this.destination = destination;
         this.generateOptions = generateOptions;
     }
-    async generate() {
-        await generate(this.openapiPath, this.destination, this.generateOptions);
+    /**
+     * Initialises the `.cache` directory that holds compiled JS output.
+     *
+     * Creates a `.gitignore` file that excludes the `.cache` sub-directory and a
+     * `README.md` inside `.cache` that explains its purpose.
+     *
+     * @param destination - The root output directory.
+     */
+    async buildCacheDirectory(destination) {
+        const gitignorePath = nodePath.join(destination, ".gitignore");
+        const cacheReadmePath = nodePath.join(destination, ".cache", "README.md");
+        debug("ensuring the directory containing .gitgnore exists");
+        await ensureDirectoryExists(gitignorePath);
+        debug("creating the .gitignore file if it doesn't already exist");
+        if (!existsSync(gitignorePath)) {
+            await fs.writeFile(gitignorePath, ".cache\n", "utf8");
+        }
+        debug("creating the .cache/README.md file");
+        ensureDirectoryExists(cacheReadmePath);
+        await fs.writeFile(cacheReadmePath, "This directory contains compiled JS files from the paths directory. Do not edit these files directly.\n", "utf8");
+    }
+    /**
+     * Reads and returns the `#/paths` requirement from `specification`.
+     *
+     * Writes a diagnostic message to stderr and returns an empty set when the
+     * `paths` key is missing or cannot be read.
+     *
+     * @param specification - The loaded OpenAPI specification.
+     */
+    async getPathsFromSpecification(specification) {
+        try {
+            return specification.getRequirement("#/paths") ?? new Set();
+        }
+        catch (error) {
+            process.stderr.write(`Could not find #/paths in the specification.\n${error}\n`);
+            return undefined;
+        }
+    }
+    /**
+     * Runs the main code-generation pipeline once and resolves when complete.
+     *
+     * Loads the OpenAPI spec from `openapiPath`, optionally prunes defunct route
+     * files, registers all path operations as {@link OperationCoder} exports, and
+     * writes the resulting TypeScript files to `destination`.
+     *
+     * @param repository - Injectable repository instance; defaults to a fresh one
+     *   (primarily useful in tests).
+     */
+    async generate(repository = new Repository()) {
+        const { destination } = this;
+        debug("generating code from %s to %s", this.openapiPath, destination);
+        debug("initializing the .cache directory");
+        await this.buildCacheDirectory(destination);
+        debug("done initializing the .cache directory");
+        debug("creating specification from %s", this.openapiPath);
+        const specification = await Specification.fromFile(this.openapiPath);
+        debug("created specification: $o", specification);
+        debug("reading the #/paths from the specification");
+        const paths = await this.getPathsFromSpecification(specification);
+        debug("got %i paths", paths?.map?.length ?? 0);
+        if (this.generateOptions.prune && this.generateOptions.routes) {
+            debug("pruning defunct route files");
+            await pruneRoutes(destination, paths.map((_v, key) => key));
+            debug("done pruning");
+        }
+        const securityRequirement = specification.getRequirement("#/components/securitySchemes");
+        const securitySchemes = Object.values(securityRequirement?.data ?? {});
+        const HTTP_VERBS = new Set([
+            "get",
+            "put",
+            "post",
+            "delete",
+            "options",
+            "head",
+            "patch",
+            "trace",
+        ]);
+        paths.forEach((pathDefinition, key) => {
+            debug("processing path %s", key);
+            const path = key === "/" ? "/index" : key;
+            pathDefinition.forEach((operation, requestMethod) => {
+                if (!HTTP_VERBS.has(requestMethod)) {
+                    return;
+                }
+                repository
+                    .get(`routes${path}.ts`)
+                    .export(new OperationCoder(operation, requestMethod, securitySchemes));
+            });
+        });
+        debug("telling the repository to write the files to %s", destination);
+        await repository.writeFiles(destination, this.generateOptions);
+        debug("finished writing the files");
     }
+    /**
+     * Starts watching the OpenAPI document for changes.
+     *
+     * Has no effect when `openApiPath` is a URL (HTTP sources are not watched).
+     * Resolves once the watcher is ready.
+     */
     async watch() {
         if (this.openapiPath.startsWith("http")) {
             return;
         }
         this.watcher = watch(this.openapiPath, CHOKIDAR_OPTIONS).on("change", () => {
-            void generate(this.openapiPath, this.destination, this.generateOptions).then(() => {
+            void this.generate().then(() => {
                 this.dispatchEvent(new Event("generate"));
                 return true;
             }, () => {
@@ -31,6 +144,7 @@ export class CodeGenerator extends EventTarget {
         });
         await waitForEvent(this.watcher, "ready");
     }
+    /** Closes the file-system watcher. */
     async stopWatching() {
         await this.watcher?.close();
     }

package/dist/typescript-generator/coder.js

@@ -1,30 +1,84 @@
 import { RESERVED_WORDS } from "./reserved-words.js";
+/**
+ * Base class for all code-generation helpers in the TypeScript generator.
+ *
+ * A `Coder` wraps a single {@link Requirement} node from the OpenAPI spec and
+ * knows how to emit TypeScript code for it.  Subclasses override
+ * {@link writeCode} to produce the actual source text.
+ *
+ * Coders are used by {@link Script} and {@link Repository} to lazily generate
+ * exports and imports, resolving `$ref` references through the
+ * {@link Specification} before writing.
+ */
 export class Coder {
     requirement;
     constructor(requirement) {
         this.requirement = requirement;
     }
+    /**
+     * A stable cache key for this coder, composed of the constructor name and
+     * either the `$ref` value (for references) or the requirement URL.
+     */
     get id() {
         if (this.requirement.isReference) {
             return `${this.constructor.name}@${this.requirement.data["$ref"]}`;
         }
         return `${this.constructor.name}@${this.requirement.url}`;
     }
+    /**
+     * Optional preamble emitted before the `export` keyword.
+     *
+     * Subclasses can return a string (e.g. a type alias) that must appear in the
+     * output before this coder's export statement.
+     *
+     * @param _path - The path of the script being written (unused in base class).
+     */
     beforeExport(_path) {
         return "";
     }
+    /**
+     * Returns a JSDoc comment block to be placed immediately before the export.
+     *
+     * Returns `""` by default; subclasses override this to surface OpenAPI
+     * metadata (description, summary, examples, etc.).
+     */
     jsdoc() {
         return "";
     }
+    /**
+     * Writes this coder's contribution to `script`.
+     *
+     * When the requirement is a `$ref`, delegates to {@link Script.import} so
+     * the reference target is exported from its own module.  Otherwise calls
+     * {@link writeCode}.
+     *
+     * @param script - The script being assembled.
+     * @returns The TypeScript source text for this coder's export value.
+     */
     write(script) {
         if (this.requirement.isReference) {
             return script.import(this);
         }
         return this.writeCode(script);
     }
+    /**
+     * Generates the TypeScript source text for this coder's value.
+     *
+     * This method is abstract — subclasses **must** override it.
+     *
+     * @param _script - The script being assembled.
+     * @throws Always — callers should never reach the base implementation.
+     */
     writeCode(_script) {
         throw new Error("write() is abstract and should be overwritten by a subclass");
     }
+    /**
+     * Resolves `$ref` references by returning the target coder.
+     *
+     * When this coder's requirement is not a reference, returns `this`.
+     * Otherwise loads the referenced requirement and wraps it in an instance of
+     * the same concrete coder class.
+     */
     async delegate() {
         if (!this.requirement.isReference) {
             return this;
@@ -32,6 +86,15 @@ export class Coder {
         const requirement = await this.requirement.reference();
         return new this.constructor(requirement);
     }
+    /**
+     * Generator that yields candidate export names for this coder.
+     *
+     * The first name is derived from the last path segment of the requirement
+     * URL, sanitised to be a valid TypeScript identifier.  Subsequent names have
+     * an incrementing numeric suffix to resolve collisions.
+     *
+     * @param rawName - Override the starting name (used by subclasses).
+     */
     *names(rawName = this.requirement.url.split("/").at(-1)) {
         const name = rawName
             .replace(/^\d/u, (digit) => `_${digit}`)
@@ -45,9 +108,22 @@ export class Coder {
             yield baseName + index;
         }
     }
+    /**
+     * Returns an optional TypeScript type annotation string to be placed between
+     * the export name and its value (`export const name: <type> = value`).
+     *
+     * Returns `""` by default.
+     */
     typeDeclaration(_namespace, _script) {
         return "";
     }
+    /**
+     * Returns the repository-relative path of the script where this coder's
+     * export should live when imported by another script.
+     *
+     * Subclasses override this to place type exports in `types/paths/…` and
+     * route exports in `routes/…`.
+     */
     modulePath() {
         return "did-not-override-coder-modulePath.ts";
     }