counterfact 2.8.1 → 2.10.0

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

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

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

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

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

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

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

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- generated files are written under the caller-provided destination tree. */
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "../server/constants.js";
@@ -115,7 +116,7 @@ export class CodeGenerator extends EventTarget {
                 }
                 repository
                     .get(`routes${path}.ts`)
-                    .export(new OperationCoder(operation, requestMethod, securitySchemes));
+                    .export(new OperationCoder(operation, "", requestMethod, securitySchemes));
             });
         });
         debug("telling the repository to write the files to %s", destination);

package/dist/typescript-generator/coder.js

@@ -12,8 +12,10 @@ import { RESERVED_WORDS } from "./reserved-words.js";
  */
 export class Coder {
     requirement;
-    constructor(requirement) {
+    version;
+    constructor(requirement, version = "") {
         this.requirement = requirement;
+        this.version = version;
     }
     /**
      * A stable cache key for this coder, composed of the constructor name and
@@ -84,7 +86,7 @@ export class Coder {
             return this;
         }
         const requirement = await this.requirement.reference();
-        return new this.constructor(requirement);
+        return new this.constructor(requirement, this.version);
     }
     /**
      * Generator that yields candidate export names for this coder.

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

@@ -14,9 +14,9 @@ import { OperationTypeCoder, } from "./operation-type-coder.js";
 export class OperationCoder extends Coder {
     requestMethod;
     securitySchemes;
-    constructor(requirement, requestMethod, securitySchemes = []) {
-        super(requirement);
-        if (requestMethod === undefined) {
+    constructor(requirement, version = "", requestMethod = "", securitySchemes = []) {
+        super(requirement, version);
+        if (requestMethod === "") {
             throw new Error("requestMethod is required");
         }
         this.requestMethod = requestMethod;
@@ -40,7 +40,7 @@ export class OperationCoder extends Coder {
     }`;
     }
     typeDeclaration(_namespace, script) {
-        const operationTypeCoder = new OperationTypeCoder(this.requirement, this.requestMethod, this.securitySchemes);
+        const operationTypeCoder = new OperationTypeCoder(this.requirement, this.version, this.requestMethod, this.securitySchemes);
         return script.importType(operationTypeCoder);
     }
     modulePath() {

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

@@ -36,9 +36,9 @@ function sanitizeIdentifier(value) {
 export class OperationTypeCoder extends TypeCoder {
     requestMethod;
     securitySchemes;
-    constructor(requirement, requestMethod, securitySchemes = []) {
-        super(requirement);
-        if (requestMethod === undefined) {
+    constructor(requirement, version = "", requestMethod = "", securitySchemes = []) {
+        super(requirement, version);
+        if (requestMethod === "") {
             throw new Error("requestMethod is required");
         }
         this.requestMethod = requestMethod;
@@ -79,7 +79,7 @@ export class OperationTypeCoder extends TypeCoder {
         }
         const capitalize = (str) => str.charAt(0).toUpperCase() + str.slice(1);
         const typeName = `${baseName}_${capitalize(parameterKind)}`;
-        const coder = new ParameterExportTypeCoder(this.requirement, typeName, inlineType, parameterKind);
+        const coder = new ParameterExportTypeCoder(this.requirement, this.version, typeName, inlineType, parameterKind);
         coder._modulePath = modulePath;
         return script.export(coder, true);
     }
@@ -99,7 +99,7 @@ export class OperationTypeCoder extends TypeCoder {
                 return response.get("content").map((content, contentType) => `{  
               status: ${status}, 
               contentType?: "${contentType}",
-              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema")).write(script) : "unknown"}
+              body?: ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
             }`);
             }
             if (response.has("schema")) {
@@ -111,7 +111,7 @@ export class OperationTypeCoder extends TypeCoder {
                         .map((contentType) => `{
             status: ${status},
             contentType?: "${contentType}",
-            body?: ${new SchemaTypeCoder(response.get("schema")).write(script)}
+            body?: ${new SchemaTypeCoder(response.get("schema"), this.version).write(script)}
           }`)
                         .join(" | ");
                 }
@@ -149,10 +149,10 @@ export class OperationTypeCoder extends TypeCoder {
         script.importSharedType("COUNTERFACT_RESPONSE");
         const contextTypeImportName = script.importExternalType("Context", CONTEXT_FILE_TOKEN);
         const parameters = this.requirement.get("parameters");
-        const queryType = new ParametersTypeCoder(parameters, "query").write(script);
-        const pathType = new ParametersTypeCoder(parameters, "path").write(script);
-        const headersType = new ParametersTypeCoder(parameters, "header").write(script);
-        const cookieType = new ParametersTypeCoder(parameters, "cookie").write(script);
+        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);
+        const cookieType = new ParametersTypeCoder(parameters, this.version, "cookie").write(script);
         const bodyRequirement = (this.requirement.get("consumes") ??
             this.requirement.specification?.rootRequirement?.get("consumes"))
             ? parameters
@@ -161,10 +161,11 @@ export class OperationTypeCoder extends TypeCoder {
             : this.requirement.select("requestBody/content/application~1json/schema");
         const bodyType = bodyRequirement === undefined
             ? "never"
-            : new SchemaTypeCoder(bodyRequirement).write(script);
-        const responseType = new ResponsesTypeCoder(this.requirement.get("responses"), (this.requirement.get("produces")?.data ??
+            : new SchemaTypeCoder(bodyRequirement, this.version).write(script);
+        const openApi2MediaTypes = (this.requirement.get("produces")?.data ??
             this.requirement.specification?.rootRequirement?.get("produces")
-                ?.data)).write(script);
+                ?.data);
+        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
@@ -174,6 +175,6 @@ export class OperationTypeCoder extends TypeCoder {
         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<${this.responseTypes(script)} | { status: 415, contentType: "text/plain", body: string } | COUNTERFACT_RESPONSE | { ALL_REMAINING_HEADERS_ARE_OPTIONAL: COUNTERFACT_RESPONSE }>`;
+        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>`;
     }
 }

package/dist/typescript-generator/parameter-export-type-coder.js

@@ -4,8 +4,8 @@ export class ParameterExportTypeCoder extends TypeCoder {
     _typeCode;
     _parameterKind;
     _modulePath;
-    constructor(requirement, typeName, typeCode, parameterKind) {
-        super(requirement);
+    constructor(requirement, version, typeName, typeCode, parameterKind) {
+        super(requirement, version);
         this._typeName = typeName;
         this._typeCode = typeCode;
         this._parameterKind = parameterKind;

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

@@ -4,8 +4,8 @@ import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 export class ParametersTypeCoder extends TypeCoder {
     placement;
-    constructor(requirement, placement) {
-        super(requirement);
+    constructor(requirement, version = "", placement = "") {
+        super(requirement, version);
         this.placement = placement;
     }
     names() {
@@ -26,7 +26,7 @@ export class ParametersTypeCoder extends TypeCoder {
                 : parameter;
             const comment = buildJsDoc(parameter.data);
             const commentPrefix = comment ? `\n${comment}` : "";
-            const typeString = new SchemaTypeCoder(schema).write(script);
+            const typeString = new SchemaTypeCoder(schema, this.version).write(script);
             return `${commentPrefix}"${name}"${optionalFlag}: ${typeString}`;
         });
         if (typeDefinitions.length === 0) {

package/dist/typescript-generator/prune.js

@@ -1,5 +1,6 @@
 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. */
 import createDebug from "debug";
 import { toForwardSlashPath } from "../util/forward-slash-path.js";
 const debug = createDebug("counterfact:typescript-generator:prune");

package/dist/typescript-generator/repository.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath, { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+/* eslint-disable security/detect-non-literal-fs-filename -- repository writes and stats generated files only inside destination output directories. */
 import createDebug from "debug";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { toForwardSlashPath, pathJoin, pathRelative, pathDirname, } from "../util/forward-slash-path.js";

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

@@ -1,10 +1,11 @@
 import { printObject } from "./printers.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
+import { pathJoin } from "../util/forward-slash-path.js";
 export class ResponseTypeCoder extends TypeCoder {
     openApi2MediaTypes;
-    constructor(requirement, openApi2MediaTypes = []) {
-        super(requirement);
+    constructor(requirement, version = "", openApi2MediaTypes = []) {
+        super(requirement, version);
         this.openApi2MediaTypes = openApi2MediaTypes;
     }
     names() {
@@ -17,14 +18,14 @@ export class ResponseTypeCoder extends TypeCoder {
                 .map((content, mediaType) => [
                 mediaType,
                 `{ 
-            schema:  ${content.has("schema") ? new SchemaTypeCoder(content.get("schema")).write(script) : "unknown"}
+            schema:  ${content.has("schema") ? new SchemaTypeCoder(content.get("schema"), this.version).write(script) : "unknown"}
          }`,
             ]);
         }
         return this.openApi2MediaTypes.map((mediaType) => [
             mediaType,
             `{
-            schema: ${new SchemaTypeCoder(response.get("schema")).write(script)}
+            schema: ${new SchemaTypeCoder(response.get("schema"), this.version).write(script)}
          }`,
         ]);
     }
@@ -39,7 +40,7 @@ export class ResponseTypeCoder extends TypeCoder {
             .get("headers")
             .map((value, name) => [
             name,
-            `{ schema: ${new SchemaTypeCoder(value.get("schema") ?? value).write(script)}}`,
+            `{ schema: ${new SchemaTypeCoder(value.get("schema") ?? value, this.version).write(script)}}`,
         ]);
     }
     printHeaders(script, response) {
@@ -77,7 +78,7 @@ export class ResponseTypeCoder extends TypeCoder {
         return printObject(exampleNames.map((name) => [name, "unknown"]));
     }
     modulePath() {
-        return `types/${this.requirement.data["$ref"]}.ts`;
+        return pathJoin("types", this.version, this.requirement.data["$ref"] + ".ts");
     }
     writeCode(script) {
         return `{

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

@@ -3,8 +3,8 @@ import { ResponseTypeCoder } from "./response-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 export class ResponsesTypeCoder extends TypeCoder {
     openApi2MediaTypes;
-    constructor(requirement, openApi2MediaTypes = []) {
-        super(requirement);
+    constructor(requirement, version = "", openApi2MediaTypes = []) {
+        super(requirement, version);
         this.openApi2MediaTypes = openApi2MediaTypes;
     }
     typeForDefaultStatusCode(listedStatusCodes) {
@@ -23,7 +23,7 @@ export class ResponsesTypeCoder extends TypeCoder {
     buildResponseObjectType(script) {
         return printObjectWithoutQuotes(this.requirement.map((response, responseCode) => [
             this.normalizeStatusCode(responseCode),
-            new ResponseTypeCoder(response, this.openApi2MediaTypes).write(script),
+            new ResponseTypeCoder(response, this.version, this.openApi2MediaTypes).write(script),
         ]));
     }
     writeCode(script) {

package/dist/typescript-generator/scenario-file-generator.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- scenario files are discovered and generated under the configured destination tree. */
 import { watch } from "chokidar";
 import { CHOKIDAR_OPTIONS } from "../server/constants.js";
 import { pathRelative } from "../util/forward-slash-path.js";

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

@@ -13,7 +13,7 @@ export class SchemaCoder extends Coder {
     objectSchema(script) {
         const { properties, required } = this.requirement.data;
         const propertyLines = Object.keys(properties ?? {}).map((name) => {
-            const schemaCoder = new SchemaCoder(this.requirement.select(`properties/${name}`));
+            const schemaCoder = new SchemaCoder(this.requirement.select(`properties/${name}`), this.version);
             return `"${name}": ${schemaCoder.write(script)}`;
         });
         return `
@@ -27,7 +27,7 @@ export class SchemaCoder extends Coder {
     arraySchema(script) {
         return `{
         type: "array",     
-        items: ${new SchemaCoder(this.requirement.get("items")).write(script)}
+        items: ${new SchemaCoder(this.requirement.get("items"), this.version).write(script)}
       }`;
     }
     typeDeclaration(_namespace, script) {

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

@@ -1,5 +1,6 @@
 import { buildJsDoc } from "./jsdoc.js";
 import { TypeCoder } from "./type-coder.js";
+import { pathJoin } from "../util/forward-slash-path.js";
 export class SchemaTypeCoder extends TypeCoder {
     names() {
         return super.names(this.requirement.data["$ref"]?.split("/").at(-1));
@@ -16,7 +17,7 @@ export class SchemaTypeCoder extends TypeCoder {
             return "unknown";
         }
         const requirement = this.requirement.get("additionalProperties");
-        return new SchemaTypeCoder(requirement).write(script);
+        return new SchemaTypeCoder(requirement, this.version).write(script);
     }
     objectSchema(script) {
         const { data } = this.requirement;
@@ -28,7 +29,8 @@ export class SchemaTypeCoder extends TypeCoder {
             const optionalFlag = isRequired ? "" : "?";
             const comment = buildJsDoc(property.data);
             const commentPrefix = comment ? `\n${comment}` : "";
-            return `${commentPrefix}"${name}"${optionalFlag}: ${new SchemaTypeCoder(property).write(script)}`;
+            const propertyType = new SchemaTypeCoder(property, this.version).write(script);
+            return `${commentPrefix}"${name}"${optionalFlag}: ${propertyType}`;
         });
         if (typedData.additionalProperties) {
             properties.push(`[key: string]: ${this.additionalPropertiesType(script)}`);
@@ -36,7 +38,7 @@ export class SchemaTypeCoder extends TypeCoder {
         return `{${properties.join(",")}}`;
     }
     arraySchema(script) {
-        return `Array<${new SchemaTypeCoder(this.requirement.get("items")).write(script)}>`;
+        return `Array<${new SchemaTypeCoder(this.requirement.get("items"), this.version).write(script)}>`;
     }
     writePrimitive(value) {
         if (typeof value === "string") {
@@ -79,7 +81,7 @@ export class SchemaTypeCoder extends TypeCoder {
         }
         const key = matchingKey();
         const items = (allOf ?? anyOf ?? oneOf);
-        const types = items.map((_item, index) => new SchemaTypeCoder(this.requirement.get(key).get(index)).write(script));
+        const types = items.map((_item, index) => new SchemaTypeCoder(this.requirement.get(key).get(index), this.version).write(script));
         return types.join(allOf ? " & " : " | ");
     }
     writeEnum(_script, requirement) {
@@ -88,7 +90,7 @@ export class SchemaTypeCoder extends TypeCoder {
             .join(" | ");
     }
     modulePath() {
-        return `types/${this.requirement.data["$ref"].replace(/^#\//u, "")}.ts`;
+        return pathJoin("types", this.version, this.requirement.data["$ref"].replace(/^#\//u, "") + ".ts");
     }
     writeCode(script) {
         const { allOf, anyOf, oneOf, type, format } = this.requirement.data;

package/dist/typescript-generator/script.js

@@ -17,6 +17,7 @@ export class Script {
     repository;
     comments;
     exports;
+    versions;
     imports;
     externalImport;
     cache;
@@ -26,6 +27,7 @@ export class Script {
         this.repository = repository;
         this.comments = [];
         this.exports = new Map();
+        this.versions = new Map();
         this.imports = new Map();
         this.externalImport = new Map();
         this.cache = new Map();
@@ -176,13 +178,53 @@ export class Script {
     exportType(coder) {
         return this.export(coder, true);
     }
+    declareVersion(coder, name) {
+        const version = coder.version;
+        const versions = this.versions.get(name) ?? new Map();
+        this.versions.set(name, versions);
+        if (versions.has(version)) {
+            return;
+        }
+        const versionStatement = {
+            beforeExport: "",
+            done: false,
+            id: coder.id,
+            isDefault: false,
+            isType: true,
+            jsdoc: "",
+            typeDeclaration: "",
+        };
+        versionStatement.promise = coder
+            .delegate()
+            .then((availableCoder) => {
+            versionStatement.code = availableCoder.write(this);
+            return availableCoder;
+        })
+            .catch((error) => {
+            versionStatement.code = `unknown /* error declaring version "${name}" (${version}) for ${this.path}: ${error.message} */`;
+            versionStatement.error = error;
+            return undefined;
+        })
+            .finally(() => {
+            versionStatement.done = true;
+        });
+        versions.set(version, versionStatement);
+    }
     /** `true` while at least one export promise is still pending. */
     isInProgress() {
-        return Array.from(this.exports.values()).some((exportStatement) => !exportStatement.done);
+        return (Array.from(this.exports.values()).some((exportStatement) => !exportStatement.done) ||
+            Array.from(this.versions.values())
+                .flatMap((versions) => Array.from(versions.values()))
+                .some((versionStatement) => !versionStatement.done));
     }
     /** Returns a promise that resolves when all pending export promises settle. */
     finished() {
-        return Promise.all(Array.from(this.exports.values(), (value) => value.promise));
+        return Promise.all([
+            ...Array.from(this.exports.values(), (value) => value.promise),
+            ...Array.from(this.versions.values())
+                .flatMap((versions) => Array.from(versions.values()))
+                .map((value) => value.promise),
+        ]);
     }
     externalImportStatements() {
         return Array.from(this.externalImport, ([name, { isDefault, isType, modulePath }]) => `import${isType ? " type" : ""} ${isDefault ? name : `{ ${name} }`} from "${modulePath}";`);
@@ -208,18 +250,31 @@ export class Script {
             return `${jsdoc}${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code};`;
         });
     }
+    versionsTypeStatements() {
+        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(", ")} };`];
+    }
     /**
      * Formats the fully assembled script source with Prettier and returns it.
      *
      * All pending export promises are awaited before formatting.
      */
-    contents() {
+    async contents() {
+        await this.finished();
         return format([
             this.comments.map((comment) => `// ${comment}`).join("\n"),
             this.comments.length > 0 ? "\n\n" : "",
             this.externalImportStatements().join("\n"),
             this.importStatements().join("\n"),
             "\n\n",
+            this.versionsTypeStatements().join("\n"),
+            this.versions.size > 0 ? "\n\n" : "",
             this.exportStatements().join("\n\n"),
         ].join(""), { parser: "typescript" });
     }

package/dist/util/ensure-directory-exists.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- helper creates parent directories for caller-provided output file paths. */
 /**
  * Synchronously ensures that the directory containing `filePath` exists,
  * creating it (and any missing ancestors) if necessary.

package/dist/util/load-config-file.js

@@ -1,5 +1,5 @@
-import { readFile } from "node:fs/promises";
 import { load as loadYaml } from "js-yaml";
+import { readFile } from "./read-file.js";
 function kebabToCamel(str) {
     return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }
@@ -17,7 +17,7 @@ function normalizeKeys(obj) {
 export async function loadConfigFile(configPath, required = false) {
     let content;
     try {
-        content = await readFile(configPath, "utf8");
+        content = await readFile(configPath);
     }
     catch (error) {
         if (typeof error === "object" &&

package/dist/util/read-file.js

@@ -1,5 +1,12 @@
 import fs from "node:fs/promises";
+import nodePath from "node:path";
 import nodeFetch from "node-fetch";
+function normalizeLocalPath(path) {
+    if (path.includes("\0")) {
+        throw new Error("File path cannot contain NUL bytes.");
+    }
+    return nodePath.resolve(path);
+}
 /**
  * Reads the content of a file or URL and returns it as a UTF-8 string.
  *
@@ -17,7 +24,14 @@ export async function readFile(urlOrPath) {
         return await response.text();
     }
     if (urlOrPath.startsWith("file")) {
-        return await fs.readFile(new URL(urlOrPath), "utf8");
+        const fileUrl = new URL(urlOrPath);
+        if (fileUrl.protocol !== "file:") {
+            throw new Error(`Unsupported URL protocol for file read: ${fileUrl.protocol}`);
+        }
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- file URL is parsed and protocol-validated immediately above.
+        return await fs.readFile(fileUrl, "utf8");
     }
-    return await fs.readFile(urlOrPath, "utf8");
+    const normalizedPath = normalizeLocalPath(urlOrPath);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is normalized and NUL-byte validated before filesystem access.
+    return await fs.readFile(normalizedPath, "utf8");
 }