counterfact 2.10.0 → 2.11.0

package/dist/api-runner.js

@@ -64,6 +64,11 @@ export class ApiRunner {
      * Defaults to `""` (no subdirectory).
      */
     group;
+    /**
+     * Optional version label for this runner's spec (e.g. `"v1"`, `"v2"`).
+     * Defaults to `""` (unversioned).
+     */
+    version;
     /**
      * The subdirectory path segment derived from {@link group}.
      * Returns `""` when `group` is empty, otherwise `"/${group}"`.
@@ -72,8 +77,9 @@ export class ApiRunner {
         return this.group ? `/${this.group}` : "";
     }
     config;
-    constructor(config, nativeTs, openApiDocument, group) {
+    constructor(config, nativeTs, openApiDocument, group, version = "", versions = []) {
         this.group = group;
+        this.version = version;
         const modulesPath = this.group
             ? pathJoin(config.basePath, this.group)
             : config.basePath;
@@ -87,8 +93,8 @@ export class ApiRunner {
         this.contextRegistry = new ContextRegistry();
         this.scenarioRegistry = new ScenarioRegistry();
         this.scenarioFileGenerator = new ScenarioFileGenerator(modulesPath);
-        this.codeGenerator = new CodeGenerator(this.openApiPath, config.basePath + this.subdirectory, config.generate);
-        this.dispatcher = new Dispatcher(this.registry, this.contextRegistry, openApiDocument, config);
+        this.codeGenerator = new CodeGenerator(this.openApiPath, config.basePath + this.subdirectory, config.generate, version);
+        this.dispatcher = new Dispatcher(this.registry, this.contextRegistry, openApiDocument, config, version, versions);
         this.transpiler = new Transpiler(pathJoin(modulesPath, "routes"), compiledPathsDirectory, "commonjs");
         this.moduleLoader = new ModuleLoader(compiledPathsDirectory, this.registry, this.contextRegistry, pathJoin(modulesPath, "scenarios"), this.scenarioRegistry);
     }
@@ -101,8 +107,10 @@ export class ApiRunner {
      *
      * @param config - Runtime configuration for this runner instance.
      * @param group - Optional group name placing generated code in a subdirectory (default `""`).
+     * @param version - Optional version label for this spec (e.g. `"v1"`, `"v2"`).
+     * @param versions - Optional ordered list of all version labels in this group (oldest first).
      */
-    static async create(config, group = "") {
+    static async create(config, group = "", version = "", versions = []) {
         const nativeTs = await runtimeCanExecuteErasableTs();
         const modulesPath = group
             ? pathJoin(config.basePath, group)
@@ -114,7 +122,7 @@ export class ApiRunner {
         const openApiDocument = config.openApiPath === "_"
             ? undefined
             : await loadOpenApiDocument(config.openApiPath);
-        return new ApiRunner(config, nativeTs, openApiDocument, group);
+        return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions);
     }
     /**
      * Generates TypeScript route stubs and type files from the OpenAPI spec.
@@ -123,11 +131,15 @@ export class ApiRunner {
      * - Routes and types are only generated when `config.openApiPath` is not `"_"`.
      * - The scenario context type file is always generated when
      *   `config.generate.types` is `true`, even without a spec.
+     *
+     * @param repository - Optional shared repository.  Pass a shared instance
+     *   when multiple versioned specs in the same group should merge their types
+     *   into the same output tree.
      */
-    async generate() {
+    async generate(repository) {
         if (this.config.openApiPath !== "_" &&
             (this.config.generate.routes || this.config.generate.types)) {
-            await this.codeGenerator.generate();
+            await this.codeGenerator.generate(repository);
         }
         if (this.config.generate.types) {
             await this.scenarioFileGenerator.generate();

package/dist/app.js

@@ -1,8 +1,13 @@
+import fs from "node:fs/promises";
+import nodePath from "node:path";
 import { createHttpTerminator } from "http-terminator";
 import { ApiRunner } from "./api-runner.js";
 import { startRepl as startReplServer } from "./repl/repl.js";
 import { createRouteFunction } from "./repl/route-builder.js";
 import { createKoaApp } from "./server/web-server/create-koa-app.js";
+import { Repository } from "./typescript-generator/repository.js";
+import { ensureDirectoryExists } from "./util/ensure-directory-exists.js";
+import { generateVersionsTsContent } from "./typescript-generator/versions-ts-generator.js";
 export { loadOpenApiDocument } from "./server/load-openapi-document.js";
 export { createMswHandlers, handleMswRequest, } from "./msw.js";
 export async function runStartupScenario(scenarioRegistry, contextRegistry, config, openApiDocument) {
@@ -18,19 +23,47 @@ export async function runStartupScenario(scenarioRegistry, contextRegistry, conf
     };
     await indexModule["startup"](scenario$);
 }
+/**
+ * Derives the URL prefix for a spec entry.
+ *
+ * Applies the following precedence rules:
+ *  1. Explicit `prefix` (even `""`) → returned as-is.
+ *  2. `group` + `version` both present → `/<group>/<version>`.
+ *  3. `group` present (no `version`) → `/<group>`.
+ *  4. Neither → `""` (root).
+ */
+function derivePrefix(spec) {
+    if (spec.prefix !== undefined) {
+        return spec.prefix;
+    }
+    if (spec.group && spec.version) {
+        return `/${spec.group}/${spec.version}`;
+    }
+    if (spec.group) {
+        return `/${spec.group}`;
+    }
+    return "";
+}
 /**
  * Normalises the spec configuration to an array.
  *
- * When `specs` is provided it is returned as-is. When it is omitted, a
- * single-entry array is constructed from `config.openApiPath`,
- * `config.prefix`, and `group = ""` so that the rest of the code never
- * needs to branch on single-vs-multiple specs.
+ * When `specs` is provided, each entry's `prefix` is resolved via
+ * {@link derivePrefix} so the rest of the code can assume `prefix` is always
+ * a string. When `specs` is omitted, a single-entry array is constructed from
+ * `config.openApiPath`, `config.prefix`, and `group = ""`.
  */
 function normalizeSpecs(config, specs) {
     if (specs !== undefined) {
-        return specs;
+        return specs.map((spec) => ({ ...spec, prefix: derivePrefix(spec) }));
     }
-    return [{ source: config.openApiPath, prefix: config.prefix, group: "" }];
+    return [
+        {
+            source: config.openApiPath,
+            prefix: config.prefix,
+            group: "",
+            version: "",
+        },
+    ];
 }
 function validateSpecGroups(specs) {
     if (specs.length <= 1) {
@@ -41,20 +74,26 @@ function validateSpecGroups(specs) {
         .filter(({ group }) => group === "")
         .map(({ index }) => String(index + 1));
     if (invalidSpecNumbers.length === 0) {
-        const seenGroups = new Set();
-        const duplicateGroupNames = new Set();
+        const seenKeys = new Set();
+        const duplicateKeys = new Set();
         for (const spec of specs) {
             const group = spec.group.trim();
-            if (seenGroups.has(group)) {
-                duplicateGroupNames.add(group);
+            const version = spec.version?.trim() ?? "";
+            // Use group@version as the uniqueness key so that the same group can
+            // appear with different versions (e.g. v1 and v2 of the same API).
+            // The empty-group case is already rejected above, so `group` is always
+            // non-empty here and the `@version` suffix remains unambiguous.
+            const key = version ? `${group}@${version}` : group;
+            if (seenKeys.has(key)) {
+                duplicateKeys.add(key);
                 continue;
             }
-            seenGroups.add(group);
+            seenKeys.add(key);
         }
-        if (duplicateGroupNames.size === 0) {
+        if (duplicateKeys.size === 0) {
             return;
         }
-        throw new Error(`Each spec must define a unique group when multiple APIs are configured (duplicate groups: ${[...duplicateGroupNames].join(", ")}).`);
+        throw new Error(`Each spec must define a unique group (and version) when multiple APIs are configured (duplicates: ${[...duplicateKeys].join(", ")}).`);
     }
     throw new Error(`Each spec must define a non-empty group when multiple APIs are configured (invalid spec entries: ${invalidSpecNumbers.join(", ")}).`);
 }
@@ -81,7 +120,18 @@ function validateSpecGroups(specs) {
 export async function counterfact(config, specs) {
     const normalizedSpecs = normalizeSpecs({ openApiPath: config.openApiPath, prefix: config.prefix }, specs);
     validateSpecGroups(normalizedSpecs);
-    const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({ ...config, openApiPath: spec.source, prefix: spec.prefix }, spec.group)));
+    // Compute the ordered versions per group (oldest first, as declared in specs).
+    // This list is passed to each runner so that $.minVersion() can compare
+    // version positions at runtime.
+    const versionsByGroup = new Map();
+    for (const spec of normalizedSpecs) {
+        const version = spec.version ?? "";
+        if (version) {
+            const existing = versionsByGroup.get(spec.group) ?? [];
+            versionsByGroup.set(spec.group, [...existing, version]);
+        }
+    }
+    const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({ ...config, openApiPath: spec.source, prefix: spec.prefix }, spec.group, spec.version ?? "", versionsByGroup.get(spec.group) ?? [])));
     const koaApp = createKoaApp({
         runners,
         config,
@@ -89,7 +139,61 @@ export async function counterfact(config, specs) {
     // The REPL is configured using the first runner.
     const primaryRunner = runners[0];
     async function start(options) {
-        await Promise.all(runners.map((runner) => runner.generate()));
+        // Serialize generate() calls within each group to avoid concurrent writes
+        // to the same output directory.  Runners that share a group share the same
+        // basePath subdirectory (and therefore the same counterfact-types
+        // destination), so running them in parallel would cause a race when both
+        // try to create that directory at startup.  Different groups are still
+        // generated in parallel.
+        //
+        // When multiple versioned specs share the same group, they also share a
+        // single Repository instance so that the shared `types/paths/…` files
+        // accumulate all versions into a merged Versioned<…> type instead of each
+        // overwriting the previous version's types.
+        const runnersByGroup = new Map();
+        for (const runner of runners) {
+            const bucket = runnersByGroup.get(runner.group) ?? [];
+            bucket.push(runner);
+            runnersByGroup.set(runner.group, bucket);
+        }
+        await Promise.all(Array.from(runnersByGroup.values()).map(async (bucket) => {
+            const sharedRepository = bucket.length > 1 ? new Repository() : undefined;
+            for (const runner of bucket) {
+                await runner.generate(sharedRepository);
+            }
+        }));
+        if (options.generate?.types) {
+            // Build a per-group map of unique non-empty version strings in
+            // declaration order. new Set() preserves insertion order so the first
+            // occurrence of each version is kept and duplicates are dropped without
+            // reordering.
+            const versionsByGroup = new Map();
+            for (const spec of normalizedSpecs) {
+                const group = spec.group;
+                const version = (spec.version ?? "").trim();
+                if (version === "") {
+                    continue;
+                }
+                const existing = versionsByGroup.get(group) ?? [];
+                if (!existing.includes(version)) {
+                    existing.push(version);
+                }
+                versionsByGroup.set(group, existing);
+            }
+            // Write <basePath>/<group>/types/versions.ts for every group that has
+            // at least one versioned spec.  When the group is empty the path
+            // collapses to <basePath>/types/versions.ts (the single-spec case).
+            await Promise.all(Array.from(versionsByGroup.entries()).map(async ([group, versions]) => {
+                const content = await generateVersionsTsContent(versions);
+                const versionsFilePath = group
+                    ? nodePath.join(config.basePath, group, "types", "versions.ts")
+                    : nodePath.join(config.basePath, "types", "versions.ts");
+                /* eslint-disable security/detect-non-literal-fs-filename -- path is derived from the caller-supplied basePath and fixed suffixes. */
+                await ensureDirectoryExists(versionsFilePath);
+                await fs.writeFile(versionsFilePath, content, "utf8");
+                /* eslint-enable security/detect-non-literal-fs-filename */
+            }));
+        }
         await Promise.all(runners.map((runner) => runner.watch()));
         await Promise.all(runners.map((runner) => runner.start(options)));
         let httpTerminator;

package/dist/cli/banner.js

@@ -67,7 +67,7 @@ export function createIntroduction(params) {
         `   API Base URL  ${url}`,
         source === "_" ? undefined : `   Swagger UI    ${swaggerUrl}`,
         "",
-        "   Instructions  https://counterfact.dev/docs/usage.html",
+        "   Instructions  https://github.com/counterfact/api-simulator/blob/main/docs/usage.md",
         "   Help/feedback https://github.com/pmcelhaney/counterfact/issues",
         "",
         ...telemetryWarning,

package/dist/cli/run.js

@@ -22,18 +22,23 @@ const DEFAULT_PORT = 3100;
  * CLI flag) into an array of {@link SpecConfig} objects, or `undefined` when
  * the option is a plain string (single OpenAPI document path).
  *
- * - **Array**: each entry is mapped to `{source, prefix, group}` with defaults.
+ * - **Array**: each entry is mapped to `{source, prefix, group, version}` with defaults.
  * - **Object**: wrapped in a single-element array.
  * - **String / undefined**: returns `undefined` — caller handles the string
  *   case (it shifts the positional argument) and the `undefined` case
  *   (single spec derived from config).
+ *
+ * Note: `prefix` is intentionally left `undefined` when not supplied so that
+ * `normalizeSpecs` (in `app.ts`) can derive it automatically from
+ * `group`/`version`.
  */
 export function normalizeSpecOption(specOption) {
     if (Array.isArray(specOption)) {
         return specOption.map((entry) => ({
             source: entry.source,
-            prefix: entry.prefix ?? "",
+            prefix: entry.prefix,
             group: entry.group ?? "",
+            version: entry.version,
         }));
     }
     if (typeof specOption === "object" &&
@@ -42,8 +47,9 @@ export function normalizeSpecOption(specOption) {
         return [
             {
                 source: specOption.source,
-                prefix: specOption.prefix ?? "",
+                prefix: specOption.prefix,
                 group: specOption.group ?? "",
+                version: specOption.version,
             },
         ];
     }
@@ -253,7 +259,7 @@ function buildProgram(version, taglines) {
         .option("--watch-routes", "generate + watch routes for changes")
         .option("-s, --serve", "start the server")
         .option("-b, --build-cache", "builds the cache of compiled routes and types")
-        .option("--no-admin-api", "disable the admin API at /_counterfact/api/*")
+        .option("--admin-api", "enable the admin API at /_counterfact/api/*")
         .option("-r, --repl", "start the REPL")
         .option("--proxy-url <string>", "proxy URL")
         .option("--admin-api-token <string>", "bearer token required for /_counterfact/api/* endpoints (defaults to COUNTERFACT_ADMIN_API_TOKEN)")

package/dist/cli/telemetry.js

@@ -5,9 +5,7 @@ const POSTHOG_HOST = "https://us.i.posthog.com";
 /**
  * Returns `true` when telemetry should be sent.
  *
- * Telemetry is disabled in CI, when `COUNTERFACT_TELEMETRY_DISABLED=true`,
- * or before the May 2026 rollout date unless the user has explicitly opted
- * in with `COUNTERFACT_TELEMETRY_DISABLED=false`.
+ * Telemetry is disabled in CI or when `COUNTERFACT_TELEMETRY_DISABLED=true`.
  */
 export function isTelemetryEnabled() {
     if (process.env["CI"])
@@ -15,9 +13,6 @@ export function isTelemetryEnabled() {
     const telemetryDisabledEnv = process.env["COUNTERFACT_TELEMETRY_DISABLED"];
     if (telemetryDisabledEnv === "true")
         return false;
-    const isBeforeRollout = new Date() < new Date("2026-05-01");
-    if (isBeforeRollout && telemetryDisabledEnv !== "false")
-        return false;
     return true;
 }
 /**

package/dist/repl/repl.js

@@ -194,9 +194,6 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             }
             seenGroups.add(binding.key);
         }
-        if (duplicateGroups.size > 0) {
-            throw new Error(`Duplicate API groups are not allowed when multiple APIs are configured (duplicate groups: ${[...duplicateGroups].join(", ")}).`);
-        }
     }
     const rootBinding = groupedBindings[0];
     if (rootBinding === undefined) {
@@ -268,7 +265,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             print("- context: the root context ( same as loadContext('/') )");
             print("- route('/some/path'): create a request builder for the given path");
             print("");
-            print("For more information, see https://counterfact.dev/docs/usage.html");
+            print("For more information, see https://github.com/counterfact/api-simulator/blob/main/docs/usage.md");
             print("");
             this.clearBufferedCommand();
             this.displayPrompt();

package/dist/server/dispatcher.js

@@ -6,6 +6,23 @@ import { isExplodedObjectQueryParam, validateRequest, } from "./request-validato
 import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
+/**
+ * Merges path-item-level and operation-level parameter arrays.
+ *
+ * Operation-level parameters take precedence when both arrays define a
+ * parameter with the same `name` and `in` location, per the OpenAPI
+ * specification.
+ */
+function mergeParameters(pathItemParams, operationParams) {
+    const map = new Map();
+    for (const p of pathItemParams) {
+        map.set(`${p.in}:${p.name}`, p);
+    }
+    for (const p of operationParams) {
+        map.set(`${p.in}:${p.name}`, p);
+    }
+    return [...map.values()];
+}
 /**
  * Parses the `Cookie` request header into a key/value map.
  *
@@ -91,12 +108,26 @@ export class Dispatcher {
     openApiDocument;
     fetch;
     config; // Add config property
-    constructor(registry, contextRegistry, openApiDocument, config) {
+    /**
+     * The version label for this dispatcher's spec (e.g. `"v1"`, `"v2"`).
+     * Empty string when running without a version.
+     */
+    version;
+    /**
+     * Ordered list of all version labels for the API group this dispatcher
+     * belongs to. The first entry is the oldest version. Used by
+     * `$.minVersion()` at runtime to determine if the current version is
+     * greater than or equal to a given minimum version.
+     */
+    versions;
+    constructor(registry, contextRegistry, openApiDocument, config, version = "", versions = []) {
         this.registry = registry;
         this.contextRegistry = contextRegistry;
         this.openApiDocument = openApiDocument;
         this.fetch = fetch;
         this.config = config;
+        this.version = version;
+        this.versions = versions;
     }
     parameterTypes(parameters) {
         const types = {
@@ -111,43 +142,65 @@ export class Dispatcher {
             return types;
         }
         for (const parameter of parameters) {
-            const type = parameter?.type;
+            const type = parameter?.type ?? parameter?.schema?.type;
             if (type !== undefined) {
                 types[parameter.in].set(parameter.name, type === "integer" ? "number" : type);
             }
         }
         return types;
     }
-    findOperation(path, method) {
-        if (this.openApiDocument) {
-            for (const key in this.openApiDocument.paths) {
-                if (key.toLowerCase() === path.toLowerCase()) {
-                    return this.openApiDocument.paths[key]?.[method.toLowerCase()];
-                }
+    findPathItem(path) {
+        if (!this.openApiDocument) {
+            return undefined;
+        }
+        for (const key in this.openApiDocument.paths) {
+            if (key.toLowerCase() === path.toLowerCase()) {
+                return this.openApiDocument.paths[key];
             }
         }
         return undefined;
     }
     /**
      * Resolves the OpenAPI operation for `path` and `method`, merging any
-     * top-level `produces` array from the document root into the operation.
+     * top-level `produces` array from the document root and any path-item-level
+     * `parameters` into the operation.
+     *
+     * Per the OpenAPI specification, parameters defined at the path item level
+     * are shared across all operations on that path. Operation-level parameters
+     * take precedence when both define a parameter with the same `name` and `in`.
      *
      * @param path - The matched route path (e.g. `"/pets/{petId}"`).
      * @param method - The HTTP method.
      * @returns The {@link OpenApiOperation} if found, or `undefined`.
      */
     operationForPathAndMethod(path, method) {
-        const operation = this.findOperation(path, method);
+        const pathItem = this.findPathItem(path);
+        if (pathItem === undefined) {
+            return undefined;
+        }
+        const operation = pathItem[method.toLowerCase()];
         if (operation === undefined) {
             return undefined;
         }
+        // Merge path-item-level parameters with operation-level parameters.
+        // Operation-level parameters take precedence on same name+in collision.
+        const pathItemParams = pathItem.parameters ?? [];
+        const operationParams = operation.parameters ?? [];
+        const mergedParameters = pathItemParams.length > 0
+            ? mergeParameters(pathItemParams, operationParams)
+            : operationParams.length > 0
+                ? operationParams
+                : undefined;
+        const mergedOperation = mergedParameters !== undefined
+            ? { ...operation, parameters: mergedParameters }
+            : operation;
         if (this.openApiDocument?.produces) {
             return {
                 produces: this.openApiDocument.produces,
-                ...operation,
+                ...mergedOperation,
             };
         }
-        return operation;
+        return mergedOperation;
     }
     normalizeResponse(response, acceptHeader) {
         if (response.content !== undefined) {
@@ -285,6 +338,17 @@ export class Dispatcher {
             // @ts-expect-error - Might be pushing the limits of what TypeScript can do here
             response: createResponseBuilder(operation ?? { responses: {} }, this.config), // Pass config
             tools: new Tools({ headers }),
+            ...(this.version !== "" && {
+                version: this.version,
+                minVersion: (min) => {
+                    const currentIdx = this.versions.indexOf(this.version);
+                    const minIdx = this.versions.indexOf(min);
+                    if (currentIdx === -1 || minIdx === -1) {
+                        return false;
+                    }
+                    return currentIdx >= minIdx;
+                },
+            }),
         });
         if (response === undefined) {
             return {

package/dist/server/web-server/admin-api-middleware.js

@@ -166,7 +166,7 @@ export function adminApiMiddleware(pathPrefix, registry, contextRegistry, config
                         port: config.port,
                         proxyUrl: config.proxyUrl,
                         prefix: config.prefix,
-                        startAdminApi: config.startAdminApi,
+                        startAdminApi: config.startAdminApi ?? false,
                         startRepl: config.startRepl,
                         startServer: config.startServer,
                         watch: config.watch,

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

@@ -22,12 +22,14 @@ const debug = createDebug("counterfact:typescript-generator:generate");
 export class CodeGenerator extends EventTarget {
     openapiPath;
     destination;
+    version;
     generateOptions;
     watcher;
-    constructor(openApiPath, destination, generateOptions) {
+    constructor(openApiPath, destination, generateOptions, version = "") {
         super();
         this.openapiPath = openApiPath;
         this.destination = destination;
+        this.version = version;
         this.generateOptions = generateOptions;
     }
     /**
@@ -116,7 +118,7 @@ export class CodeGenerator extends EventTarget {
                 }
                 repository
                     .get(`routes${path}.ts`)
-                    .export(new OperationCoder(operation, "", requestMethod, securitySchemes));
+                    .export(new OperationCoder(operation, this.version, requestMethod, securitySchemes));
             });
         });
         debug("telling the repository to write the files to %s", destination);

package/dist/typescript-generator/operation-coder.js

@@ -1,6 +1,6 @@
 import { pathJoin } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
-import { OperationTypeCoder, } from "./operation-type-coder.js";
+import { OperationTypeCoder, VersionedArgTypeCoder, } from "./operation-type-coder.js";
 /**
  * Generates the default route handler stub for a single OpenAPI operation.
  *
@@ -41,6 +41,14 @@ export class OperationCoder extends Coder {
     }
     typeDeclaration(_namespace, script) {
         const operationTypeCoder = new OperationTypeCoder(this.requirement, this.version, this.requestMethod, this.securitySchemes);
+        if (this.version !== "") {
+            // For versioned APIs: register this version's $-argument type on the
+            // shared script so that Script.versionsTypeStatements() can emit the
+            // merged handler type after all versions have been declared.
+            const versionedArgCoder = new VersionedArgTypeCoder(this.requirement, this.version, this.requestMethod, this.securitySchemes);
+            const sharedScript = script.repository.get(operationTypeCoder.modulePath());
+            sharedScript.declareVersion(versionedArgCoder, operationTypeCoder.getOperationBaseName());
+        }
         return script.importType(operationTypeCoder);
     }
     modulePath() {

package/dist/typescript-generator/operation-type-coder.js

@@ -8,6 +8,7 @@ import { RESERVED_WORDS } from "./reserved-words.js";
 import { ResponsesTypeCoder } from "./responses-type-coder.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
+import { Requirement } from "./requirement.js";
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
 function sanitizeIdentifier(value) {
     // Treat any run of non-identifier characters as a camelCase separator
@@ -32,6 +33,14 @@ function sanitizeIdentifier(value) {
  * `cookie`, `body`, `context`, `response`, and `user` arguments.
  *
  * Output is written to `types/paths/<route>.types.ts`.
+ *
+ * **Versioned APIs**: when `version` is non-empty this coder emits only a
+ * sentinel `{raw: ""}` export (suppressing the normal flat type) and
+ * registers a formatter on the shared script so that
+ * {@link Script.versionsTypeStatements} can later emit the merged
+ * `HTTP_<METHOD>_$_Versions` map and the `HTTP_<METHOD>` handler type.
+ * Each version's `$`-argument type is emitted to
+ * `types/<version>/paths/<path>.types.ts` by {@link VersionedArgTypeCoder}.
  */
 export class OperationTypeCoder extends TypeCoder {
     requestMethod;
@@ -141,14 +150,57 @@ export class OperationTypeCoder extends TypeCoder {
         }
         return "never";
     }
-    writeCode(script) {
-        script.comments = READ_ONLY_COMMENTS;
+    /**
+     * Returns the effective parameters for this operation by merging path-item-level
+     * parameters with operation-level parameters. Per the OpenAPI specification,
+     * operation-level parameters override path-item-level parameters that share
+     * the same `name` and `in` location.
+     *
+     * Uses `this.requirement.parent` (the path item requirement) to access
+     * path-item-level parameters directly, without URL string parsing.
+     *
+     * When the parent is not set (e.g. in unit tests that construct requirements
+     * directly), only the operation-level parameters are returned.
+     */
+    getEffectiveParameters() {
+        const operationParams = this.requirement.get("parameters");
+        const pathItemParams = this.requirement.parent?.get("parameters");
+        if (!pathItemParams) {
+            return operationParams;
+        }
+        if (!operationParams) {
+            return pathItemParams;
+        }
+        // Merge using a Map keyed on `${in}:${name}`.
+        // Path-level params are added first; operation-level overrides them.
+        const pathData = pathItemParams.data;
+        const opData = operationParams.data;
+        const map = new Map();
+        for (const p of pathData) {
+            map.set(`${p.in}:${p.name}`, p);
+        }
+        for (const p of opData) {
+            map.set(`${p.in}:${p.name}`, p);
+        }
+        return new Requirement([...map.values()], this.requirement.url, this.requirement.specification);
+    }
+    /**
+     * Builds the `OmitValueWhenNever<{…}>` dollar-argument type body and sets
+     * up all required shared-type imports on `script`.
+     *
+     * This helper is reused by both {@link writeCode} (non-versioned) and
+     * {@link VersionedArgTypeCoder.writeCode} (per-version file).
+     *
+     * @param script - The script to write imports and parameter-type exports into.
+     * @param baseName - Identifier prefix used for named parameter-type exports.
+     * @param modulePath - Repository-relative path for parameter-type exports.
+     */
+    buildDollarArgType(script, baseName, modulePath) {
         const xType = script.importSharedType("WideOperationArgument");
         script.importSharedType("OmitValueWhenNever");
-        script.importSharedType("MaybePromise");
         script.importSharedType("COUNTERFACT_RESPONSE");
         const contextTypeImportName = script.importExternalType("Context", CONTEXT_FILE_TOKEN);
-        const parameters = this.requirement.get("parameters");
+        const parameters = this.getEffectiveParameters();
         const queryType = new ParametersTypeCoder(parameters, this.version, "query").write(script);
         const pathType = new ParametersTypeCoder(parameters, this.version, "path").write(script);
         const headersType = new ParametersTypeCoder(parameters, this.version, "header").write(script);
@@ -168,13 +220,114 @@ export class OperationTypeCoder extends TypeCoder {
         const responseType = new ResponsesTypeCoder(this.requirement.get("responses"), this.version, openApi2MediaTypes).write(script);
         const proxyType = "(url: string) => COUNTERFACT_RESPONSE";
         const delayType = "(milliseconds: number, maxMilliseconds?: number) => Promise<void>";
-        // Get the base name for this operation and export parameter types
-        const baseName = this.getOperationBaseName();
-        const modulePath = this.modulePath();
         const queryTypeName = this.exportParameterType(script, "query", queryType, baseName, modulePath);
         const pathTypeName = this.exportParameterType(script, "path", pathType, baseName, modulePath);
         const headersTypeName = this.exportParameterType(script, "headers", headersType, baseName, modulePath);
         const cookieTypeName = this.exportParameterType(script, "cookie", cookieType, baseName, modulePath);
-        return `($: OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType} }>) => MaybePromise<COUNTERFACT_RESPONSE>`;
+        const versionLiteralType = this.version !== "" ? `"${this.version}"` : "never";
+        return `OmitValueWhenNever<{ query: ${queryTypeName}, path: ${pathTypeName}, headers: ${headersTypeName}, cookie: ${cookieTypeName}, body: ${bodyType}, context: ${contextTypeImportName}, response: ${responseType}, x: ${xType}, proxy: ${proxyType}, user: ${this.userType()}, delay: ${delayType}, version: ${versionLiteralType} }>`;
+    }
+    writeCode(script) {
+        script.comments = READ_ONLY_COMMENTS;
+        if (this.version !== "") {
+            // Versioned case: suppress the normal flat export and register a
+            // formatter so that Script.versionsTypeStatements() can emit the
+            // merged HTTP_<METHOD>_$_Versions + HTTP_<METHOD> types after all
+            // versions have been declared via declareVersion().
+            const versionedType = script.importVersionsType("Versioned");
+            const maybePromiseType = script.importSharedType("MaybePromise");
+            const counterfactResponseType = script.importSharedType("COUNTERFACT_RESPONSE");
+            const baseName = this.getOperationBaseName();
+            script.setVersionFormatter(baseName, (versionCodes) => {
+                const versionsTypeName = `${baseName}_$_Versions`;
+                const versionMap = Array.from(versionCodes, ([v, code]) => `"${v}": ${code}`).join("; ");
+                return [
+                    `type ${versionsTypeName} = { ${versionMap} };`,
+                    `export type ${baseName} = ($: ${versionedType}<${versionsTypeName}>) => ${maybePromiseType}<${counterfactResponseType}>;`,
+                ].join("\n");
+            });
+            // Return a raw-empty sentinel so exportStatements() emits nothing for
+            // this export entry.  The real export is produced by
+            // versionsTypeStatements().
+            return { raw: "" };
+        }
+        // Non-versioned case: existing flat-type output.
+        // Import in the same order as the original writeCode so that the emitted
+        // import block is identical to the pre-refactor output (snapshot-safe).
+        script.importSharedType("WideOperationArgument");
+        script.importSharedType("OmitValueWhenNever");
+        script.importSharedType("MaybePromise");
+        script.importSharedType("COUNTERFACT_RESPONSE");
+        const baseName = this.getOperationBaseName();
+        const modulePath = this.modulePath();
+        const dollarArgType = this.buildDollarArgType(script, baseName, modulePath);
+        return `($: ${dollarArgType}) => MaybePromise<COUNTERFACT_RESPONSE>`;
+    }
+}
+/**
+ * Emits a per-version `$`-argument type to
+ * `types/<version>/paths/<path>.types.ts`.
+ *
+ * When called from a *different* script (e.g. the shared
+ * `types/paths/…` script via `Script.declareVersion`), `write()` delegates to
+ * `script.importType(this)` so that the type is written to the per-version
+ * file and an import is added to the calling script.
+ *
+ * Only the `OmitValueWhenNever<{…}>` type body is emitted — the
+ * function-wrapper `($: Versioned<…>) => MaybePromise<COUNTERFACT_RESPONSE>`
+ * is assembled by the shared script's `versionsTypeStatements()`.
+ */
+export class VersionedArgTypeCoder extends OperationTypeCoder {
+    /**
+     * Include the version in the cache key so v1 and v2 coders are treated as
+     * distinct exports even when they share the same requirement URL.
+     */
+    get id() {
+        return `${super.id}:${this.version}`;
+    }
+    /**
+     * The per-version `$`-argument type is emitted to
+     * `types/<version>/paths/<path>.types.ts`, not to the shared path.
+     */
+    modulePath() {
+        const pathString = this.requirement.url
+            .split("/")
+            .at(-2)
+            .replaceAll("~1", "/");
+        return `${pathJoin(`types/${this.version}/paths`, pathString === "/" ? "/index" : pathString)}.types.ts`;
+    }
+    /**
+     * Names are version-qualified (e.g. `HTTP_GET_$_v1`) so that importing
+     * multiple versions into the shared script requires no aliasing.
+     */
+    *names() {
+        const baseName = `${this.getOperationBaseName()}_$_${sanitizeIdentifier(this.version)}`;
+        yield baseName;
+        let index = 1;
+        const MAX = 100;
+        while (index < MAX) {
+            index += 1;
+            yield `${baseName}${index}`;
+        }
+    }
+    /**
+     * When called from the per-version file itself, generate the actual type.
+     * When called from any other script (e.g. the shared file), export to the
+     * per-version file and import the result back into that script.
+     */
+    write(script) {
+        if (script.path === this.modulePath()) {
+            return this.writeCode(script);
+        }
+        return script.importType(this);
+    }
+    /**
+     * Generates the `OmitValueWhenNever<{…}>` dollar-argument type and writes
+     * it to the per-version script.
+     */
+    writeCode(script) {
+        script.comments = READ_ONLY_COMMENTS;
+        const baseName = this.getOperationBaseName();
+        return this.buildDollarArgType(script, baseName, this.modulePath());
     }
 }

package/dist/typescript-generator/requirement.js

@@ -10,6 +10,15 @@ export class Requirement {
     data;
     url;
     specification;
+    /**
+     * The requirement that produced this one via a `get()` call, or `undefined`
+     * for root requirements that were constructed directly.
+     *
+     * For path-traversal purposes this is the "logical" parent: when a `$ref` is
+     * followed, the parent is the resolved reference target rather than the
+     * `$ref` node itself.
+     */
+    parent;
     constructor(data, url = "", specification = undefined) {
         this.data = data;
         this.url = url;
@@ -53,7 +62,9 @@ export class Requirement {
         if (!this.has(key)) {
             return undefined;
         }
-        return new Requirement(this.data[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
+        const child = new Requirement(this.data[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
+        child.parent = this;
+        return child;
     }
     /**
      * Navigates to a descendant node using a slash-delimited JSON Pointer path.

package/dist/typescript-generator/responses-type-coder.js

@@ -21,10 +21,16 @@ export class ResponsesTypeCoder extends TypeCoder {
         return statusCode;
     }
     buildResponseObjectType(script) {
-        return printObjectWithoutQuotes(this.requirement.map((response, responseCode) => [
+        const entries = this.requirement.map((response, responseCode) => [
             this.normalizeStatusCode(responseCode),
             new ResponseTypeCoder(response, this.version, this.openApi2MediaTypes).write(script),
-        ]));
+        ]);
+        const explicitEntries = entries.filter(([key]) => !key.startsWith("["));
+        const mappedEntries = entries.filter(([key]) => key.startsWith("["));
+        if (explicitEntries.length > 0 && mappedEntries.length > 0) {
+            return `${printObjectWithoutQuotes(explicitEntries)} & ${printObjectWithoutQuotes(mappedEntries)}`;
+        }
+        return printObjectWithoutQuotes(entries);
     }
     writeCode(script) {
         script.importSharedType("ResponseBuilderFactory");

package/dist/typescript-generator/script.js

@@ -18,6 +18,7 @@ export class Script {
     comments;
     exports;
     versions;
+    versionFormatters;
     imports;
     externalImport;
     cache;
@@ -28,6 +29,7 @@ export class Script {
         this.comments = [];
         this.exports = new Map();
         this.versions = new Map();
+        this.versionFormatters = new Map();
         this.imports = new Map();
         this.externalImport = new Map();
         this.cache = new Map();
@@ -175,9 +177,30 @@ export class Script {
     importSharedType(name) {
         return this.importExternal(name, pathJoin(this.relativePathToBase, "counterfact-types/index.ts"), true);
     }
+    /**
+     * Imports a type from the generated `types/versions.ts` module,
+     * resolving the path relative to this script's location in the repository.
+     *
+     * @param name - The type name to import (e.g. `"Versioned"`).
+     */
+    importVersionsType(name) {
+        return this.importExternal(name, pathJoin(this.relativePathToBase, "types/versions.ts"), true);
+    }
     exportType(coder) {
         return this.export(coder, true);
     }
+    /**
+     * Registers a formatter function for the merged versioned type emitted under
+     * `name` by {@link versionsTypeStatements}.
+     *
+     * When a formatter is present for a name, `versionsTypeStatements` delegates
+     * the entire type declaration to it instead of generating the default
+     * `Versions` object type.  The formatter receives a `Map<version, importAlias>`
+     * and must return the complete TypeScript source for that operation type.
+     */
+    setVersionFormatter(name, formatter) {
+        this.versionFormatters.set(name, formatter);
+    }
     declareVersion(coder, name) {
         const version = coder.version;
         const versions = this.versions.get(name) ?? new Map();
@@ -254,11 +277,29 @@ export class Script {
         if (this.versions.size === 0) {
             return [];
         }
-        const names = Array.from(this.versions, ([name, versions]) => {
-            const mappedVersions = Array.from(versions, ([version, versionStatement]) => `"${version}": ${versionStatement.code}`);
-            return `"${name}": { ${mappedVersions.join(", ")} }`;
-        });
-        return [`export type Versions = { ${names.join(", ")} };`];
+        const statements = [];
+        const unformatted = [];
+        for (const [name, versions] of this.versions) {
+            const formatter = this.versionFormatters.get(name);
+            if (formatter) {
+                const versionCodes = new Map(Array.from(versions, ([version, stmt]) => [
+                    version,
+                    stmt.code,
+                ]));
+                statements.push(formatter(versionCodes));
+            }
+            else {
+                unformatted.push([name, versions]);
+            }
+        }
+        if (unformatted.length > 0) {
+            const names = unformatted.map(([name, versions]) => {
+                const mappedVersions = Array.from(versions, ([version, versionStatement]) => `"${version}": ${versionStatement.code}`);
+                return `"${name}": { ${mappedVersions.join(", ")} }`;
+            });
+            statements.push(`export type Versions = { ${names.join(", ")} };`);
+        }
+        return statements;
     }
     /**
      * Formats the fully assembled script source with Prettier and returns it.

package/dist/typescript-generator/versions-ts-generator.js

@@ -0,0 +1,57 @@
+import { format } from "prettier";
+/**
+ * Builds the `VersionsGTE` map: for each version V at index i,
+ * maps V to all versions at indices >= i (i.e. V and all later-declared
+ * versions, where "later" means "newer").
+ */
+function buildVersionsGTE(versions) {
+    const result = new Map();
+    versions.forEach((version, index) => {
+        result.set(version, versions.slice(index));
+    });
+    return result;
+}
+/**
+ * Generates the TypeScript source text for `types/versions.ts`.
+ *
+ * Returns an empty string when `versions` is empty.
+ * The returned string is formatted with Prettier.
+ *
+ * @param versions - Ordered list of unique, non-empty version strings.
+ *   The first entry is the oldest version.
+ */
+export async function generateVersionsTsContent(versions) {
+    if (versions.length === 0) {
+        return "";
+    }
+    const versionsUnion = versions.map((v) => `"${v}"`).join(" | ");
+    const versionsGTE = buildVersionsGTE(versions);
+    const versionsGTEBody = Array.from(versionsGTE, ([v, gte]) => `  "${v}": ${gte.map((g) => `"${g}"`).join(" | ")};`).join("\n");
+    const source = [
+        "// This file is auto-generated by Counterfact. Do not edit.",
+        "",
+        `export type Versions = ${versionsUnion};`,
+        "",
+        "/**",
+        " * Maps each version to the set of versions that are greater than or equal to it.",
+        " * Used by `Versioned.minVersion()` to narrow which versions a handler must support.",
+        " */",
+        "export type VersionsGTE = {",
+        versionsGTEBody,
+        "};",
+        "",
+        "type VersionMap = Partial<Record<Versions, object>>;",
+        "",
+        "export type Versioned<",
+        "  T extends VersionMap,",
+        "  V extends keyof T & Versions = keyof T & Versions,",
+        "> = T[V] & {",
+        "  version: V;",
+        "  minVersion<M extends keyof T & Versions>(",
+        "    min: M,",
+        "  ): this is Versioned<T, Extract<V, VersionsGTE[M]>>;",
+        "};",
+        "",
+    ].join("\n");
+    return format(source, { parser: "typescript" });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Generate a TypeScript-based mock server from an OpenAPI spec in seconds — with stateful routes, hot reload, and REPL support.",
   "type": "module",
   "main": "./dist/app.js",