counterfact 2.14.1 → 2.14.2

package/dist/api-runner.js

@@ -82,7 +82,7 @@ export class ApiRunner {
         return this.group ? `/${this.group}` : "";
     }
     config;
-    constructor(config, nativeTs, openApiDocument, group, version = "", versions = []) {
+    constructor(config, nativeTs, openApiDocument, group, version = "", versions = [], groupState) {
         this.group = group;
         this.version = version;
         const modulesPath = this.group
@@ -96,8 +96,9 @@ export class ApiRunner {
         this.prefix = config.prefix;
         this.overlays = config.overlays ?? [];
         this.registry = new Registry();
-        this.contextRegistry = new ContextRegistry();
-        this.scenarioRegistry = new ScenarioRegistry();
+        this.contextRegistry = groupState?.contextRegistry ?? new ContextRegistry();
+        this.scenarioRegistry =
+            groupState?.scenarioRegistry ?? new ScenarioRegistry();
         this.scenarioFileGenerator = new ScenarioFileGenerator(modulesPath);
         this.codeGenerator = new CodeGenerator(this.openApiPath, config.basePath + this.subdirectory, config.generate, version, config.overlays ?? []);
         this.dispatcher = new Dispatcher(this.registry, this.contextRegistry, openApiDocument, config, version, versions);
@@ -115,8 +116,9 @@ export class ApiRunner {
      * @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).
+     * @param groupState - Optional context/scenario registries shared by the group's runners.
      */
-    static async create(config, group = "", version = "", versions = []) {
+    static async create(config, group = "", version = "", versions = [], groupState) {
         const nativeTs = await runtimeCanExecuteErasableTs();
         const modulesPath = group
             ? pathJoin(config.basePath, group)
@@ -128,7 +130,7 @@ export class ApiRunner {
         const openApiDocument = config.openApiPath === "_"
             ? undefined
             : await loadOpenApiDocument(config.openApiPath, config.overlays ?? []);
-        return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions);
+        return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions, groupState);
     }
     /**
      * Generates TypeScript route stubs and type files from the OpenAPI spec.

package/dist/app.js

@@ -4,7 +4,9 @@ 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 { ContextRegistry } from "./server/context-registry.js";
 import { createKoaApp } from "./server/web-server/create-koa-app.js";
+import { ScenarioRegistry } from "./server/scenario-registry.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";
@@ -24,37 +26,42 @@ 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).
+ * Runs one startup scenario per API group, in specification declaration order.
+ * Versioned runners in one group share the same scenario and context registries,
+ * so only the group's first runner participates in startup.
  */
-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}`;
+async function runGroupStartupScenarios(runners, config) {
+    const startedGroups = new Set();
+    for (const runner of runners) {
+        if (startedGroups.has(runner.group)) {
+            continue;
+        }
+        startedGroups.add(runner.group);
+        try {
+            await runStartupScenario(runner.scenarioRegistry, runner.contextRegistry, config, runner.openApiDocument);
+        }
+        catch (error) {
+            const groupLabel = runner.group
+                ? `group "${runner.group}"${runner.version ? ` (version "${runner.version}")` : ""}`
+                : "the primary API";
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Startup scenario failed for ${groupLabel}: ${message}`, {
+                cause: error,
+            });
+        }
     }
-    return "";
 }
 /**
  * Normalises the spec configuration to an array.
  *
- * 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 = ""`.
+ * When `specs` is provided, each omitted `prefix` defaults to `""` so the rest
+ * of the code can assume it 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.map((spec) => ({ ...spec, prefix: derivePrefix(spec) }));
+        return specs.map((spec) => ({ ...spec, prefix: spec.prefix ?? "" }));
     }
     return [
         {
@@ -131,6 +138,18 @@ export async function counterfact(config, specs) {
             versionsByGroup.set(spec.group, [...existing, version]);
         }
     }
+    // A group is one state boundary even when it contains several versioned
+    // specification runners. Preserve separate registries between groups while
+    // sharing context and scenarios between every runner in the same group.
+    const stateByGroup = new Map();
+    for (const spec of normalizedSpecs) {
+        if (!stateByGroup.has(spec.group)) {
+            stateByGroup.set(spec.group, {
+                contextRegistry: new ContextRegistry(),
+                scenarioRegistry: new ScenarioRegistry(),
+            });
+        }
+    }
     const runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({
         ...config,
         openApiPath: spec.source,
@@ -138,7 +157,7 @@ export async function counterfact(config, specs) {
         // so that the --overlay CLI flag works in single-spec mode.
         overlays: spec.overlays ?? config.overlays ?? [],
         prefix: spec.prefix,
-    }, spec.group, spec.version ?? "", versionsByGroup.get(spec.group) ?? [])));
+    }, spec.group, spec.version ?? "", versionsByGroup.get(spec.group) ?? [], stateByGroup.get(spec.group))));
     const koaApp = createKoaApp({
         runners,
         config,
@@ -205,7 +224,15 @@ export async function counterfact(config, specs) {
         await Promise.all(runners.map((runner) => runner.start(options)));
         let httpTerminator;
         if (options.startServer) {
-            await runStartupScenario(primaryRunner.scenarioRegistry, primaryRunner.contextRegistry, { port: config.port }, primaryRunner.openApiDocument);
+            try {
+                await runGroupStartupScenarios(runners, { port: config.port });
+            }
+            catch (error) {
+                // Startup happens after the runner watchers are active. If a scenario
+                // fails, release those resources and leave the HTTP port untouched.
+                await Promise.allSettled(runners.map((runner) => runner.stopWatching()));
+                throw error;
+            }
             const server = koaApp.listen({
                 port: config.port,
             });

package/dist/cli/run.js

@@ -29,8 +29,7 @@ const DEFAULT_PORT = 3100;
  *   (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`.
+ * `normalizeSpecs` (in `app.ts`) can apply the root-prefix default.
  */
 export function normalizeSpecOption(specOption) {
     if (Array.isArray(specOption)) {

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

@@ -4,7 +4,7 @@ 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 { routesMiddleware, routesMiddlewareForRunners, } from "./routes-middleware.js";
 import { openapiMiddleware } from "./openapi-middleware.js";
 const debug = createDebug("counterfact:server:create-koa-app");
 /**
@@ -61,8 +61,15 @@ export function createKoaApp({ runners, config, }) {
             ctx.type = "application/json";
         }
     });
-    for (const runner of runners) {
-        app.use(routesMiddleware(runner.prefix, runner.dispatcher, {
+    const [onlyRunner] = runners;
+    if (runners.length === 1 && onlyRunner !== undefined) {
+        app.use(routesMiddleware(onlyRunner.prefix, onlyRunner.dispatcher, {
+            proxyPaths: config.proxyPaths,
+            proxyUrl: config.proxyUrl,
+        }));
+    }
+    else {
+        app.use(routesMiddlewareForRunners(runners, {
             proxyPaths: config.proxyPaths,
             proxyUrl: config.proxyUrl,
         }));

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

@@ -91,7 +91,7 @@ function getAuthObject(ctx) {
  * @param proxy - Proxy factory; injectable for testing.
  * @returns A Koa middleware function.
  */
-export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
+export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy, allowedMethodsOverride) {
     return async function middleware(ctx, next) {
         const { proxyUrl } = config;
         debug("middleware running for path: %s", ctx.request.path);
@@ -106,7 +106,7 @@ export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
         if (isProxyEnabledForPath(path, config) && proxyUrl) {
             return proxy("/", { changeOrigin: true, target: proxyUrl })(ctx, next);
         }
-        addCors(ctx, dispatcher.registry.allowedMethods(path), headers);
+        addCors(ctx, allowedMethodsOverride ?? dispatcher.registry.allowedMethods(path), headers);
         if (method === "OPTIONS") {
             ctx.status = HTTP_STATUS_CODE_OK;
             return undefined;
@@ -156,7 +156,56 @@ export function routesMiddleware(prefix, dispatcher, config, proxy = koaProxy) {
                 ctx.res.appendHeader(key, value);
             }
         }
+        if (response.status === 405 && allowedMethodsOverride !== undefined) {
+            ctx.set("Allow", allowedMethodsOverride);
+        }
         ctx.status = response.status ?? HTTP_STATUS_CODE_OK;
         return undefined;
     };
 }
+/**
+ * Selects the first runner that can handle a request, allowing runners with
+ * overlapping prefixes to share one public URL space.
+ */
+export function routesMiddlewareForRunners(runners, config, proxy = koaProxy) {
+    return async function multiRunnerRoutesMiddleware(ctx, next) {
+        const candidates = runners
+            .filter(({ prefix }) => ctx.request.path.startsWith(prefix))
+            .map((runner) => ({
+            path: ctx.request.path.slice(runner.prefix.length),
+            runner,
+        }));
+        if (candidates.length === 0) {
+            return await next();
+        }
+        const method = ctx.request.method;
+        for (const candidate of candidates) {
+            if ((config.proxyUrl && isProxyEnabledForPath(candidate.path, config)) ||
+                candidate.runner.dispatcher.registry.exists(method, candidate.path)) {
+                return routesMiddleware(candidate.runner.prefix, candidate.runner.dispatcher, config, proxy)(ctx, next);
+            }
+        }
+        const allowedMethods = new Set();
+        let pathOwner;
+        for (const candidate of candidates) {
+            const methods = candidate.runner.dispatcher.registry.allowedMethods(candidate.path);
+            if (methods === "")
+                continue;
+            pathOwner ??= candidate;
+            for (const allowedMethod of methods.split(", ")) {
+                allowedMethods.add(allowedMethod);
+            }
+        }
+        if (method === "OPTIONS") {
+            const selected = pathOwner ?? candidates[0];
+            if (selected === undefined) {
+                return await next();
+            }
+            return routesMiddleware(selected.runner.prefix, selected.runner.dispatcher, config, proxy, [...allowedMethods].join(", "))(ctx, next);
+        }
+        if (pathOwner === undefined) {
+            return await next();
+        }
+        return routesMiddleware(pathOwner.runner.prefix, pathOwner.runner.dispatcher, config, proxy, [...allowedMethods].join(", "))(ctx, next);
+    };
+}

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

@@ -8,7 +8,8 @@ import { CHOKIDAR_OPTIONS } from "../server/constants.js";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { waitForEvent } from "../util/wait-for-event.js";
 import { OperationCoder } from "./operation-coder.js";
-import { pruneRoutes } from "./prune.js";
+import { assertNoNormalizedPathCollisions, normalizeOpenApiPath, } from "./openapi-path.js";
+import { pruneRoutes, pruneTypes } from "./prune.js";
 import { Repository } from "./repository.js";
 import { Specification } from "./specification.js";
 const debug = createDebug("counterfact:typescript-generator:generate");
@@ -94,9 +95,11 @@ export class CodeGenerator extends EventTarget {
         debug("reading the #/paths from the specification");
         const paths = await this.getPathsFromSpecification(specification);
         debug("got %i paths", paths?.map?.length ?? 0);
+        const openApiPaths = paths.map((_pathDefinition, key) => key);
+        assertNoNormalizedPathCollisions(openApiPaths);
         if (this.generateOptions.prune && this.generateOptions.routes) {
             debug("pruning defunct route files");
-            await pruneRoutes(destination, paths.map((_v, key) => key));
+            await pruneRoutes(destination, openApiPaths);
             debug("done pruning");
         }
         const securityRequirement = specification.getRequirement("#/components/securitySchemes");
@@ -125,13 +128,24 @@ export class CodeGenerator extends EventTarget {
         });
         paths.forEach((pathDefinition, key) => {
             debug("processing path %s", key);
-            const path = key === "/" ? "/index" : key;
+            const normalizedPath = normalizeOpenApiPath(key);
+            const path = normalizedPath === "/" ? "/index" : normalizedPath;
             operationMethodsForPath(pathDefinition).forEach(([operation, requestMethod]) => {
                 repository
                     .get(`routes${path}.ts`)
                     .export(new OperationCoder(operation, this.version, requestMethod, securitySchemes));
             });
         });
+        if (this.generateOptions.prune && this.generateOptions.types) {
+            debug("resolving the expected generated type files");
+            await repository.finished();
+            debug("pruning defunct generated type files");
+            await pruneTypes(destination, [
+                ...repository.scripts.keys(),
+                ...(this.version === "" ? [] : ["types/versions.ts"]),
+            ]);
+            debug("done pruning generated type files");
+        }
         debug("telling the repository to write the files to %s", destination);
         await repository.writeFiles(destination, this.generateOptions);
         debug("finished writing the files");

package/dist/typescript-generator/openapi-path.js

@@ -0,0 +1,23 @@
+/**
+ * Normalizes an OpenAPI path for Counterfact's route and type module trees.
+ *
+ * Incoming requests already match route modules with or without a terminal
+ * slash, so terminal slashes must not create an extra empty file segment.
+ */
+export function normalizeOpenApiPath(openApiPath) {
+    return openApiPath.replace(/\/+$/u, "") || "/";
+}
+/**
+ * Rejects path keys that would target the same generated route module.
+ */
+export function assertNoNormalizedPathCollisions(openApiPaths) {
+    const originalPathByNormalizedPath = new Map();
+    for (const openApiPath of openApiPaths) {
+        const normalizedPath = normalizeOpenApiPath(openApiPath);
+        const existingPath = originalPathByNormalizedPath.get(normalizedPath);
+        if (existingPath !== undefined && existingPath !== openApiPath) {
+            throw new Error(`OpenAPI paths "${existingPath}" and "${openApiPath}" normalize to the same path "${normalizedPath}". Remove one of the conflicting paths.`);
+        }
+        originalPathByNormalizedPath.set(normalizedPath, openApiPath);
+    }
+}

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

@@ -1,5 +1,6 @@
 import { pathJoin } from "../util/forward-slash-path.js";
 import { Coder } from "./coder.js";
+import { normalizeOpenApiPath } from "./openapi-path.js";
 import { OperationTypeCoder, VersionedArgTypeCoder, } from "./operation-type-coder.js";
 import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 /**
@@ -66,10 +67,7 @@ export class OperationCoder extends Coder {
         return script.importType(operationTypeCoder);
     }
     modulePath() {
-        const pathString = this.requirement.url
-            .split("/")
-            .at(-2)
-            .replaceAll("~1", "/");
+        const pathString = normalizeOpenApiPath(this.requirement.url.split("/").at(-2).replaceAll("~1", "/"));
         return `${pathJoin("routes", pathString)}.types.ts`;
     }
 }

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

@@ -9,6 +9,7 @@ import { ResponsesTypeCoder } from "./responses-type-coder.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { STREAMING_CONTENT_TYPES } from "./streaming-content-types.js";
 import { TypeCoder } from "./type-coder.js";
+import { normalizeOpenApiPath } from "./openapi-path.js";
 import { Requirement } from "./requirement.js";
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
 function sanitizeIdentifier(value) {
@@ -145,10 +146,7 @@ export class OperationTypeCoder extends TypeCoder {
             .join(" | ");
     }
     modulePath() {
-        const pathString = this.requirement.url
-            .split("/")
-            .at(-2)
-            .replaceAll("~1", "/");
+        const pathString = normalizeOpenApiPath(this.requirement.url.split("/").at(-2).replaceAll("~1", "/"));
         return `${pathJoin("types/paths", pathString === "/" ? "/index" : pathString)}.types.ts`;
     }
     /**

package/dist/typescript-generator/prune.js

@@ -1,8 +1,9 @@
 import fs from "node:fs/promises";
 import nodePath from "node:path";
-/* eslint-disable security/detect-non-literal-fs-filename -- pruning only traverses and removes files under destination/routes. */
+/* eslint-disable security/detect-non-literal-fs-filename -- pruning only traverses and removes files under generator-owned destination subdirectories. */
 import createDebug from "debug";
 import { toForwardSlashPath } from "../util/forward-slash-path.js";
+import { normalizeOpenApiPath } from "./openapi-path.js";
 const debug = createDebug("counterfact:typescript-generator:prune");
 /**
  * Collects all .ts route files in a directory recursively.
@@ -11,21 +12,19 @@ const debug = createDebug("counterfact:typescript-generator:prune");
  * @param currentPath - Current subdirectory being processed (relative to routesDir)
  * @returns Array of relative paths (using forward slashes)
  */
-async function collectRouteFiles(routesDir, currentPath = "") {
+async function collectTypeScriptFiles(rootDir, currentPath = "") {
     const files = [];
     try {
-        const fullDir = currentPath
-            ? nodePath.join(routesDir, currentPath)
-            : routesDir;
+        const fullDir = currentPath ? nodePath.join(rootDir, currentPath) : rootDir;
         const entries = await fs.readdir(fullDir, { withFileTypes: true });
         for (const entry of entries) {
             const relativePath = currentPath
                 ? `${currentPath}/${entry.name}`
                 : entry.name;
             if (entry.isDirectory()) {
-                files.push(...(await collectRouteFiles(routesDir, relativePath)));
+                files.push(...(await collectTypeScriptFiles(rootDir, relativePath)));
             }
-            else if (entry.name.endsWith(".ts") && entry.name !== "_.context.ts") {
+            else if (entry.name.endsWith(".ts")) {
                 files.push(relativePath);
             }
         }
@@ -71,7 +70,8 @@ async function removeEmptyDirectories(dir, rootDir) {
  * @param openApiPath - The OpenAPI path string
  */
 function openApiPathToRouteFile(openApiPath) {
-    const filePath = openApiPath === "/" ? "index" : openApiPath.slice(1);
+    const normalizedPath = normalizeOpenApiPath(openApiPath);
+    const filePath = normalizedPath === "/" ? "index" : normalizedPath.slice(1);
     return `${filePath}.ts`;
 }
 /**
@@ -85,7 +85,7 @@ export async function pruneRoutes(destination, openApiPaths) {
     const routesDir = nodePath.join(destination, "routes");
     const expectedFiles = new Set(Array.from(openApiPaths).map(openApiPathToRouteFile));
     debug("expected route files: %o", Array.from(expectedFiles));
-    const actualFiles = await collectRouteFiles(routesDir);
+    const actualFiles = (await collectTypeScriptFiles(routesDir)).filter((file) => nodePath.basename(file) !== "_.context.ts");
     debug("actual route files: %o", actualFiles);
     let prunedCount = 0;
     for (const file of actualFiles) {
@@ -101,3 +101,46 @@ export async function pruneRoutes(destination, openApiPaths) {
     debug("pruned %d files", prunedCount);
     return prunedCount;
 }
+/**
+ * Returns whether a path below `types/` belongs to a namespace populated by
+ * the OpenAPI generator. Context support and arbitrary user-authored type
+ * modules are deliberately outside this ownership policy.
+ */
+function isGeneratorOwnedTypePath(path) {
+    const [first, second] = toForwardSlashPath(path).split("/");
+    const generatedCategory = (segment) => segment === "paths" || segment === "components" || segment === "#";
+    return (path === "versions.ts" ||
+        generatedCategory(first) ||
+        generatedCategory(second));
+}
+/**
+ * Prunes obsolete files from the OpenAPI generator-owned namespaces below
+ * `types/`. Hidden files are included by the recursive directory walk.
+ *
+ * `types/_.context.ts` and paths outside the known generated namespaces are
+ * preserved because separate generators or users own them.
+ *
+ * @param destination - Base destination directory (contains `types/`).
+ * @param expectedPaths - Repository-relative generated paths to retain.
+ * @returns Number of files removed.
+ */
+export async function pruneTypes(destination, expectedPaths) {
+    const typesDir = nodePath.join(destination, "types");
+    const expectedFiles = new Set(Array.from(expectedPaths, (path) => toForwardSlashPath(path).replace(/^types\//u, "")));
+    const actualFiles = (await collectTypeScriptFiles(typesDir)).filter(isGeneratorOwnedTypePath);
+    let prunedCount = 0;
+    debug("expected type files: %o", Array.from(expectedFiles));
+    debug("actual generated type files: %o", actualFiles);
+    for (const file of actualFiles) {
+        const normalizedFile = toForwardSlashPath(file);
+        if (!expectedFiles.has(normalizedFile)) {
+            const fullPath = nodePath.join(typesDir, file);
+            debug("pruning %s", fullPath);
+            await fs.rm(fullPath);
+            prunedCount++;
+        }
+    }
+    await removeEmptyDirectories(typesDir, typesDir);
+    debug("pruned %d type files", prunedCount);
+    return prunedCount;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.14.1",
+  "version": "2.14.2",
   "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",