counterfact 2.11.0 → 2.14.0

package/README.md

@@ -4,7 +4,7 @@
 
 <br>
 
-![MIT License](https://img.shields.io/badge/license-MIT-blue) [![Coverage Status](https://coveralls.io/repos/github/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) ![friction 0%](https://img.shields.io/badge/friction-0%25-brightgreen)
+![MIT License](https://img.shields.io/badge/license-MIT-blue) [![Coverage Status](https://coveralls.io/repos/github/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) ![friction 0%](https://img.shields.io/badge/friction-0%25-brightgreen) ![Swagger 2.0](https://img.shields.io/badge/Swagger-2.0-85EA2D) ![OpenAPI 3.0-3.2](https://img.shields.io/badge/OpenAPI-3.x-6BA539)
 
 </div>
 
@@ -17,6 +17,7 @@ Mock servers make it easy to get started, but hard to keep going.<br>
 Counterfact is an API simulator without those limits. 
 
 Point it at an [OpenAPI](https://www.openapis.org) document and get a live, stateful API in seconds. 
+Supports Swagger 2.0 and OpenAPI 3.0, 3.1, and 3.2.
 - Type-safe TypeScript handlers for every endpoint  
 - Hot reloading as you edit  
 - Shared state across routes  

package/dist/api-runner.js

@@ -59,6 +59,11 @@ export class ApiRunner {
     openApiPath;
     /** URL prefix that this runner intercepts (default `""`). */
     prefix;
+    /**
+     * Ordered list of overlay file paths/URLs applied to the OpenAPI document
+     * after loading.  Empty when no overlays are configured.
+     */
+    overlays;
     /**
      * Optional group name that places generated code in a subdirectory.
      * Defaults to `""` (no subdirectory).
@@ -89,11 +94,12 @@ export class ApiRunner {
         this.openApiDocument = openApiDocument;
         this.openApiPath = config.openApiPath;
         this.prefix = config.prefix;
+        this.overlays = config.overlays ?? [];
         this.registry = new Registry();
         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, version);
+        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);
         this.transpiler = new Transpiler(pathJoin(modulesPath, "routes"), compiledPathsDirectory, "commonjs");
         this.moduleLoader = new ModuleLoader(compiledPathsDirectory, this.registry, this.contextRegistry, pathJoin(modulesPath, "scenarios"), this.scenarioRegistry);
@@ -121,7 +127,7 @@ export class ApiRunner {
         }
         const openApiDocument = config.openApiPath === "_"
             ? undefined
-            : await loadOpenApiDocument(config.openApiPath);
+            : await loadOpenApiDocument(config.openApiPath, config.overlays ?? []);
         return new ApiRunner(config, nativeTs, openApiDocument, group, version, versions);
     }
     /**

package/dist/app.js

@@ -131,7 +131,14 @@ export async function counterfact(config, specs) {
             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 runners = await Promise.all(normalizedSpecs.map((spec) => ApiRunner.create({
+        ...config,
+        openApiPath: spec.source,
+        // Per-spec overlays take precedence; fall back to config-level overlays
+        // 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) ?? [])));
     const koaApp = createKoaApp({
         runners,
         config,

package/dist/cli/run.js

@@ -13,7 +13,7 @@ import { pathResolve } from "../util/forward-slash-path.js";
 import { loadConfigFile } from "../util/load-config-file.js";
 import { createIntroduction } from "./banner.js";
 import { checkForUpdates } from "./check-for-updates.js";
-import { isTelemetryEnabled, sendTelemetry } from "./telemetry.js";
+import { hashTelemetryLocation, isTelemetryEnabled, sendTelemetry, } from "./telemetry.js";
 const debug = createDebug("counterfact:cli:run");
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_PORT = 3100;
@@ -22,7 +22,7 @@ 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, version}` with defaults.
+ * - **Array**: each entry is mapped to `{source, prefix, group, version, overlays}` 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
@@ -39,6 +39,7 @@ export function normalizeSpecOption(specOption) {
             prefix: entry.prefix,
             group: entry.group ?? "",
             version: entry.version,
+            overlays: entry.overlays,
         }));
     }
     if (typeof specOption === "object" &&
@@ -50,11 +51,41 @@ export function normalizeSpecOption(specOption) {
                 prefix: specOption.prefix,
                 group: specOption.group ?? "",
                 version: specOption.version,
+                overlays: specOption.overlays,
             },
         ];
     }
     return undefined;
 }
+export function buildStartupTelemetryProperties(options, source, version, specs) {
+    const apiSources = specs?.map((spec) => spec.source) ?? [source];
+    const apiFileLocationHashes = apiSources
+        .filter((apiSource) => apiSource !== "_")
+        .map((apiSource) => hashTelemetryLocation(apiSource));
+    return {
+        alwaysFakeOptionals: Boolean(options.alwaysFakeOptionals),
+        apiFileLocationHashes,
+        buildCache: Boolean(options.buildCache),
+        generateRoutes: Boolean(options.generate) || Boolean(options.generateRoutes),
+        generateTypes: Boolean(options.generate) || Boolean(options.generateTypes),
+        mode: specs !== undefined
+            ? "multi-spec"
+            : source === "_"
+                ? "without-openapi"
+                : "single-spec",
+        openBrowser: Boolean(options.open),
+        port: options.port,
+        prune: Boolean(options.prune),
+        repl: Boolean(options.repl),
+        serve: Boolean(options.serve),
+        updateCheck: Boolean(options.updateCheck),
+        validateRequest: Boolean(options.validateRequest),
+        validateResponse: Boolean(options.validateResponse),
+        version,
+        watchRoutes: Boolean(options.watch) || Boolean(options.watchRoutes),
+        watchTypes: Boolean(options.watch) || Boolean(options.watchTypes),
+    };
+}
 /**
  * Builds the Commander program with all CLI options and the action handler.
  * Factored out of `runCli` so it is easy to test or extend.
@@ -75,11 +106,17 @@ function buildProgram(version, taglines) {
         const configFilePath = resolve(options.config ?? "counterfact.yaml");
         const fileConfig = await loadConfigFile(configFilePath, options.config !== undefined);
         debug("fileConfig: %o", fileConfig);
+        const knownOptionKeys = new Set(program.options.map((option) => option.attributeName()));
         // Apply config file values for any option that was not explicitly set on
         // the command line (i.e. its source is "default" or it was never defined).
         for (const [key, value] of Object.entries(fileConfig)) {
+            if (!knownOptionKeys.has(key)) {
+                debug("ignoring unknown config key %s", key);
+                continue;
+            }
             const optionSource = program.getOptionValueSource(key);
             if (optionSource !== "cli") {
+                // eslint-disable-next-line security/detect-object-injection -- key is validated against known Commander option names above.
                 options[key] = value;
             }
         }
@@ -110,12 +147,14 @@ function buildProgram(version, taglines) {
         const actions = ["repl", "serve", "watch", "generate", "buildCache"];
         if (!Object.keys(options).some((argument) => actions.some((action) => argument.startsWith(action)))) {
             for (const action of actions) {
+                // eslint-disable-next-line security/detect-object-injection -- action names come from the local allowlist above.
                 options[action] = true;
             }
         }
         debug("options: %o", options);
         debug("source: %s", source);
         debug("destination: %s", destination);
+        const startupTelemetryProperties = buildStartupTelemetryProperties(options, source, version, specs);
         const openBrowser = options.open;
         const url = `http://localhost:${options.port}${options.prefix}`;
         const guiUrl = `${url}/counterfact/`;
@@ -140,6 +179,7 @@ function buildProgram(version, taglines) {
                 prune: Boolean(options.prune),
             },
             openApiPath: source,
+            overlays: options.overlay ?? [],
             port: options.port,
             proxyPaths: new Map([["", Boolean(options.proxyUrl)]]),
             proxyUrl: options.proxyUrl ?? "",
@@ -213,6 +253,7 @@ function buildProgram(version, taglines) {
             process.exit(1);
         }
         debug("started server");
+        sendTelemetry("counterfact_started", startupTelemetryProperties);
         await updateCheckPromise;
         if (config.startRepl) {
             startRepl();
@@ -267,6 +308,7 @@ function buildProgram(version, taglines) {
         .option("--always-fake-optionals", "random responses will include optional fields")
         .option("--prune", "remove route files that no longer exist in the OpenAPI spec")
         .option("--spec <string>", "path or URL to OpenAPI document (alternative to the positional [openapi.yaml] argument)")
+        .option("--overlay <path>", "path or URL to an OpenAPI overlay file to apply (repeatable)", (value, previous) => [...previous, value], [])
         .option("--no-update-check", "disable the npm update check on startup")
         .option("--no-validate-request", "disable request validation against the OpenAPI spec")
         .option("--no-validate-response", "disable response validation against the OpenAPI spec")
@@ -300,10 +342,6 @@ export async function runCli(argv) {
     catch {
         taglines = ["counterfact — mock API server"];
     }
-    // Fire telemetry once on startup — fire-and-forget, never blocks.
-    if (isTelemetryEnabled()) {
-        sendTelemetry(version);
-    }
     debug("running counterfact CLI v%s", version);
     const program = buildProgram(version, taglines);
     await program.parseAsync(argv);

package/dist/cli/telemetry.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { PostHog } from "posthog-node";
 const POSTHOG_API_KEY = "phc_msXmBxiL8FVugNMLCx9bnPQGqfEMqmyBjnVkKhHkN3m7";
 const POSTHOG_HOST = "https://us.i.posthog.com";
@@ -15,24 +15,30 @@ export function isTelemetryEnabled() {
         return false;
     return true;
 }
+export function hashTelemetryLocation(location) {
+    return createHash("sha256").update(location).digest("hex");
+}
 /**
  * Fires a telemetry event to PostHog.  Fire-and-forget — never blocks
  * startup and never surfaces errors to the user.
  */
-export function sendTelemetry(version) {
+export function sendTelemetry(event, properties = {}) {
+    if (!isTelemetryEnabled()) {
+        return;
+    }
     const telemetryKey = process.env["POSTHOG_API_KEY"] ?? POSTHOG_API_KEY;
     const telemetryHost = process.env["POSTHOG_HOST"] ?? POSTHOG_HOST;
     try {
         const posthog = new PostHog(telemetryKey, { host: telemetryHost });
         posthog.capture({
             distinctId: randomUUID(),
-            event: "counterfact_started",
+            event,
             properties: {
-                version,
                 nodeVersion: process.version,
                 platform: process.platform,
                 arch: process.arch,
                 source: "counterfact-cli",
+                ...properties,
             },
         });
         posthog.flush().catch(() => {

package/dist/migrate/update-route-types.js

@@ -14,6 +14,7 @@ const HTTP_METHODS = [
     "PATCH",
     "HEAD",
     "OPTIONS",
+    "QUERY",
 ];
 // Pre-compile regex patterns derived from HTTP_METHODS
 const HTTP_METHOD_ALTERNATION = HTTP_METHODS.join("|");

package/dist/msw.js

@@ -14,6 +14,7 @@ const allowedMethods = [
     "delete",
     "patch",
     "options",
+    "query",
 ];
 const mswHandlers = {};
 /**

package/dist/repl/repl.js

@@ -1,4 +1,5 @@
 import repl from "node:repl";
+import { sendTelemetry } from "../cli/telemetry.js";
 import { RawHttpClient } from "./raw-http-client.js";
 import { createRouteFunction } from "./route-builder.js";
 function printToStdout(line) {
@@ -258,6 +259,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         : undefined);
     replServer.defineCommand("counterfact", {
         action() {
+            sendTelemetry("repl_command_used", { command: "counterfact" });
             print("This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.");
             print("Except that it's connected to the running server, which you can access with the following globals:");
             print("");
@@ -274,6 +276,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
     });
     replServer.defineCommand("proxy", {
         action(text) {
+            sendTelemetry("repl_command_used", { command: "proxy" });
             if (text === "help" || text === "") {
                 print(".proxy [on|off] - turn the proxy on/off at the root level");
                 print(".proxy [on|off] <path-prefix> - turn the proxy on for a path");
@@ -313,6 +316,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         : {};
     replServer.defineCommand("scenario", {
         async action(text) {
+            sendTelemetry("repl_command_used", { command: "scenario" });
             const trimmedText = text.trim();
             const parsedArgs = trimmedText.split(/\s+/u).filter(Boolean);
             const usage = isMultiApi

package/dist/server/counterfact-types/example.ts

@@ -2,9 +2,13 @@
  * Represents a named example defined in an OpenAPI document.
  * Examples can be referenced by route handlers via the `.example(name)` method
  * on the response builder.
+ *
+ * OpenAPI 3.2 adds `dataValue` as a structured alternative to `value`.
+ * When present, `dataValue` is preferred over `value`.
  */
 export interface Example {
+  dataValue?: unknown;
   description: string;
   summary: string;
-  value: unknown;
+  value?: unknown;
 }

package/dist/server/counterfact-types/generic-response-builder.ts

@@ -130,6 +130,10 @@ export type GenericResponseBuilderInner<
     : (name: ExampleNames<Response>) => COUNTERFACT_RESPONSE;
   text: MaybeShortcut<["text/plain"], Response>;
   xml: MaybeShortcut<["application/xml", "text/xml"], Response>;
+  stream: MaybeShortcut<
+    ["text/event-stream", "application/jsonl", "application/json-seq"],
+    Response
+  >;
 }>;
 
 /**

package/dist/server/counterfact-types/open-api-parameters.ts

@@ -6,7 +6,14 @@
  */
 export interface OpenApiParameters {
   explode?: boolean;
-  in: "body" | "cookie" | "formData" | "header" | "path" | "query";
+  in:
+    | "body"
+    | "cookie"
+    | "formData"
+    | "header"
+    | "path"
+    | "query"
+    | "querystring";
   name: string;
   required?: boolean;
   schema?: {

package/dist/server/counterfact-types/response-builder.ts

@@ -26,6 +26,11 @@ export interface ResponseBuilder {
   random: () => MaybePromise<ResponseBuilder>;
   randomLegacy: () => MaybePromise<ResponseBuilder>;
   status?: number;
+  stream: (iterable: AsyncIterable<unknown>) => {
+    body: AsyncIterable<unknown>;
+    contentType: string;
+    status?: number;
+  };
   text: (body: unknown) => ResponseBuilder;
   xml: (body: unknown) => ResponseBuilder;
 }

package/dist/server/counterfact-types/wide-response-builder.ts

@@ -23,4 +23,5 @@ export interface WideResponseBuilder {
   random: () => MaybePromise<WideResponseBuilder>;
   text: (body: unknown) => WideResponseBuilder;
   xml: (body: unknown) => WideResponseBuilder;
+  stream: (body: AsyncIterable<unknown>) => WideResponseBuilder;
 }

package/dist/server/dispatcher.js

@@ -142,6 +142,11 @@ export class Dispatcher {
             return types;
         }
         for (const parameter of parameters) {
+            // querystring parameters represent the entire query string as a single
+            // typed object; they are not individually coerced by name.
+            if (parameter.in === "querystring") {
+                continue;
+            }
             const type = parameter?.type ?? parameter?.schema?.type;
             if (type !== undefined) {
                 types[parameter.in].set(parameter.name, type === "integer" ? "number" : type);
@@ -160,6 +165,36 @@ export class Dispatcher {
         }
         return undefined;
     }
+    apiKeySecurityParameters() {
+        const schemes = this.openApiDocument?.components?.securitySchemes;
+        return Object.values(schemes ?? {})
+            .filter(({ in: location, name, type }) => type === "apiKey" &&
+            typeof name === "string" &&
+            (location === "header" ||
+                location === "query" ||
+                location === "cookie"))
+            .map(({ in: location, name }) => ({
+            in: location,
+            name: name,
+            required: false,
+            schema: { type: "string" },
+        }));
+    }
+    authWithApiKey(auth, cookie, headers, query) {
+        const apiKeyScheme = this.apiKeySecurityParameters().find((parameter) => ["cookie", "header", "query"].includes(parameter.in));
+        if (!apiKeyScheme) {
+            return auth;
+        }
+        const apiKey = apiKeyScheme.in === "query"
+            ? query[apiKeyScheme.name]
+            : apiKeyScheme.in === "cookie"
+                ? cookie[apiKeyScheme.name]
+                : Object.entries(headers).find(([key]) => key.toLowerCase() === apiKeyScheme.name.toLowerCase())?.[1];
+        const normalizedApiKey = Array.isArray(apiKey)
+            ? (apiKey[0] ?? "")
+            : (apiKey ?? "");
+        return { ...auth, apiKey: normalizedApiKey };
+    }
     /**
      * Resolves the OpenAPI operation for `path` and `method`, merging any
      * top-level `produces` array from the document root and any path-item-level
@@ -178,7 +213,11 @@ export class Dispatcher {
         if (pathItem === undefined) {
             return undefined;
         }
-        const operation = pathItem[method.toLowerCase()];
+        const normalizedMethod = method.toLowerCase();
+        const operation = pathItem[normalizedMethod] ??
+            pathItem.additionalOperations?.[method] ??
+            pathItem.additionalOperations?.[method.toUpperCase()] ??
+            pathItem.additionalOperations?.[normalizedMethod];
         if (operation === undefined) {
             return undefined;
         }
@@ -194,13 +233,20 @@ export class Dispatcher {
         const mergedOperation = mergedParameters !== undefined
             ? { ...operation, parameters: mergedParameters }
             : operation;
+        const apiKeyParameters = this.apiKeySecurityParameters();
+        const operationWithSecurity = apiKeyParameters.length > 0
+            ? {
+                ...mergedOperation,
+                parameters: mergeParameters(mergedOperation.parameters ?? [], apiKeyParameters),
+            }
+            : mergedOperation;
         if (this.openApiDocument?.produces) {
             return {
                 produces: this.openApiDocument.produces,
-                ...mergedOperation,
+                ...operationWithSecurity,
             };
         }
-        return mergedOperation;
+        return operationWithSecurity;
     }
     normalizeResponse(response, acceptHeader) {
         if (response.content !== undefined) {
@@ -290,8 +336,14 @@ export class Dispatcher {
             };
         }
         const operation = this.operationForPathAndMethod(matchedPath, method);
+        const requestCookie = parseCookies(headers.cookie ?? headers.Cookie ?? "");
         if (this.config?.validateRequests !== false) {
-            const validation = validateRequest(operation, { body, headers, query });
+            const validation = validateRequest(operation, {
+                body,
+                cookie: requestCookie,
+                headers,
+                query,
+            });
             if (!validation.valid) {
                 return {
                     body: `Request validation failed:\n${validation.errors.join("\n")}`,
@@ -307,7 +359,7 @@ export class Dispatcher {
             return min + Math.random() * (max - min);
         };
         const response = await this.registry.endpoint(method, path, this.parameterTypes(operation?.parameters))({
-            auth,
+            auth: this.authWithApiKey(auth, requestCookie, headers, query),
             body,
             context: this.contextRegistry.find(matchedPath),
             async delay(milliseconds = 0, maxMilliseconds = 0) {
@@ -316,7 +368,7 @@ export class Dispatcher {
                     : continuousDistribution(milliseconds, maxMilliseconds);
                 return new Promise((resolve) => setTimeout(resolve, delayInMs));
             },
-            cookie: parseCookies(headers.cookie ?? headers.Cookie ?? ""),
+            cookie: requestCookie,
             headers,
             proxy: async (url) => {
                 delete headers.host;
@@ -335,6 +387,8 @@ export class Dispatcher {
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- object params are reconstructed and typed by generated route types
             query: processedQuery,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- typed by generated route types; entire query string as a single object
+            querystring: processedQuery,
             // @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 }),

package/dist/server/json-to-xml.js

@@ -22,19 +22,44 @@ function xmlEscape(xmlString) {
         }
     });
 }
+function resolveNodeType(schema) {
+    if (schema?.xml?.nodeType !== undefined) {
+        return schema.xml.nodeType;
+    }
+    if (schema?.xml?.attribute || schema?.attribute) {
+        return "attribute";
+    }
+    return "element";
+}
 function objectToXml(json, schema, name) {
     const xml = [];
     const attributes = [];
     Object.entries(json).forEach(([key, value]) => {
         const properties = schema?.properties?.[key];
-        if (properties?.attribute) {
-            attributes.push(` ${key}="${xmlEscape(String(value))}"`);
-        }
-        else {
-            xml.push(jsonToXml(value, properties, key));
+        const nodeType = resolveNodeType(properties);
+        const xmlName = properties?.xml?.name ?? key;
+        switch (nodeType) {
+            case "attribute": {
+                attributes.push(` ${xmlName}="${xmlEscape(String(value))}"`);
+                break;
+            }
+            case "text": {
+                xml.push(xmlEscape(String(value)));
+                break;
+            }
+            case "cdata": {
+                xml.push(`<![CDATA[${String(value)}]]>`);
+                break;
+            }
+            case "none": {
+                break;
+            }
+            default: {
+                xml.push(jsonToXml(value, properties, key));
+            }
         }
     });
-    return `<${name}${attributes.join("")}>${String(xml.join(""))}</${name}>`;
+    return `<${name}${attributes.join("")}>${xml.join("")}</${name}>`;
 }
 /**
  * Converts a JSON value to an XML string using optional OpenAPI `xml` schema
@@ -52,7 +77,7 @@ export function jsonToXml(json, schema, keyName = "root") {
         const items = json
             .map((item) => jsonToXml(item, schema?.items, name))
             .join("");
-        if (schema?.xml?.wrapped) {
+        if (schema?.xml?.wrapped || schema?.xml?.nodeType === "element") {
             return `<${name}>${items}</${name}>`;
         }
         return items;

package/dist/server/load-openapi-document.js

@@ -1,6 +1,6 @@
 import { OpenApiDocument } from "./openapi-document.js";
-export async function loadOpenApiDocument(source) {
-    const document = new OpenApiDocument(source);
+export async function loadOpenApiDocument(source, overlays = []) {
+    const document = new OpenApiDocument(source, overlays);
     await document.load();
     return document;
 }

package/dist/server/module-loader.js

@@ -11,6 +11,7 @@ import { FileDiscovery } from "./file-discovery.js";
 import { isContextModule, isMiddlewareModule, } from "./middleware-detector.js";
 import { ModuleDependencyGraph } from "./module-dependency-graph.js";
 import { uncachedImport } from "./uncached-import.js";
+import { sendTelemetry } from "../cli/telemetry.js";
 import { toForwardSlashPath, pathDirname, pathRelative, } from "../util/forward-slash-path.js";
 import { unescapePathForWindows } from "../util/windows-escape.js";
 const { uncachedRequire } = await import("./uncached-require.cjs");
@@ -74,6 +75,10 @@ export class ModuleLoader extends EventTarget {
                 return;
             }
             const parts = nodePath.parse(pathName.replace(this.basePath, ""));
+            sendTelemetry("file_change_detected", {
+                changeType: eventName,
+                fileType: this.isContextFile(pathName) ? "context" : "route",
+            });
             const url = unescapePathForWindows(toForwardSlashPath(`/${parts.dir}/${parts.name}`).replaceAll(/\/+/gu, "/"));
             if (eventName === "unlink") {
                 this.registry.remove(url);

package/dist/server/openapi-document.js

@@ -1,7 +1,9 @@
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { dereference } from "@apidevtools/json-schema-ref-parser";
+import { applyOverlays } from "../util/apply-overlay.js";
 import { waitForEvent } from "../util/wait-for-event.js";
+import { sendTelemetry } from "../cli/telemetry.js";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
 const debug = createDebug("counterfact:server:openapi-document");
 /**
@@ -13,13 +15,20 @@ const debug = createDebug("counterfact:server:openapi-document");
 export class OpenApiDocument extends EventTarget {
     /** The path or URL of the OpenAPI source file. */
     source;
+    /**
+     * Optional ordered list of overlay file paths/URLs to apply after each
+     * load of the document.
+     */
+    overlays;
     basePath;
+    components;
     paths = {};
     produces;
     watcher;
-    constructor(source) {
+    constructor(source, overlays = []) {
         super();
         this.source = source;
+        this.overlays = overlays;
     }
     /**
      * Reads the source file and populates the document's properties.
@@ -28,7 +37,11 @@ export class OpenApiDocument extends EventTarget {
     async load() {
         try {
             const data = (await dereference(this.source));
+            if (this.overlays.length > 0) {
+                await applyOverlays(data, this.overlays);
+            }
             this.basePath = data.basePath;
+            this.components = data.components;
             this.paths = data.paths;
             this.produces = data.produces;
         }
@@ -49,6 +62,10 @@ export class OpenApiDocument extends EventTarget {
             return;
         }
         this.watcher = watch(this.source, CHOKIDAR_OPTIONS).on("change", () => {
+            sendTelemetry("file_change_detected", {
+                changeType: "change",
+                fileType: "openapi",
+            });
             void (async () => {
                 try {
                     await this.load();