counterfact 2.7.0 → 2.9.0

package/dist/typescript-generator/script.js

@@ -1,8 +1,18 @@
-import nodePath from "node:path";
 import createDebugger from "debug";
 import { format } from "prettier";
 import { escapePathForWindows } from "../util/windows-escape.js";
+import { pathJoin, pathRelative, pathDirname, } from "../util/forward-slash-path.js";
 const debug = createDebugger("counterfact:typescript-generator:script");
+/**
+ * Represents a single TypeScript file being assembled by the code generator.
+ *
+ * A `Script` accumulates exports, imports, and external imports contributed by
+ * {@link Coder} instances.  Once all coders have resolved, {@link contents}
+ * formats the result with Prettier and returns the final source text.
+ *
+ * Scripts are created and retrieved through a {@link Repository} so that the
+ * same module path always maps to the same `Script` instance.
+ */
 export class Script {
     repository;
     comments;
@@ -22,6 +32,10 @@ export class Script {
         this.typeCache = new Map();
         this.path = path;
     }
+    /**
+     * A `"../"` path fragment that points from this script's directory back to
+     * the repository root, used to resolve relative import paths.
+     */
     get relativePathToBase() {
         return this.path
             .split("/")
@@ -29,6 +43,13 @@ export class Script {
             .map(() => "..")
             .join("/");
     }
+    /**
+     * Picks the first name from `coder.names()` that is not already used as an
+     * import in this script, ensuring export/import name uniqueness.
+     *
+     * @param coder - The coder needing a name.
+     * @throws When all 100 candidate names are already taken.
+     */
     firstUniqueName(coder) {
         for (const name of coder.names()) {
             if (!this.imports.has(name)) {
@@ -37,6 +58,17 @@ export class Script {
         }
         throw new Error(`could not find a unique name for ${coder.id}`);
     }
+    /**
+     * Registers an export for `coder` in this script and returns the export name.
+     *
+     * If the same coder has already been exported (cache hit), the previously
+     * assigned name is returned without creating a duplicate.
+     *
+     * @param coder - The coder to export.
+     * @param isType - Emit `export type` instead of `export const`.
+     * @param isDefault - Emit `export default` instead of a named export.
+     * @returns The name under which the coder is exported.
+     */
     export(coder, isType = false, isDefault = false) {
         const cacheKey = isDefault ? "default" : `${coder.id}:${isType}`;
         if (this.cache.has(cacheKey)) {
@@ -75,6 +107,16 @@ export class Script {
     exportDefault(coder, isType = false) {
         this.export(coder, isType, true);
     }
+    /**
+     * Registers an import of `coder` from its owning module and returns the
+     * local alias used in this script.
+     *
+     * The coder is also exported from its home module as a side effect.
+     *
+     * @param coder - The coder to import.
+     * @param isType - Use a `import type` declaration.
+     * @param isDefault - Import the default export rather than a named export.
+     */
     import(coder, isType = false, isDefault = false) {
         debug("import coder: %s", coder.id);
         const modulePath = coder.modulePath();
@@ -103,24 +145,42 @@ export class Script {
     importDefault(coder, isType = false) {
         return this.import(coder, isType, true);
     }
+    /**
+     * Registers an import from an external npm package or absolute module path
+     * (not managed by the repository).
+     *
+     * @param name - The local binding name.
+     * @param modulePath - The module specifier (e.g. `"counterfact-types/index"`).
+     * @param isType - Use a `import type` declaration.
+     * @returns `name` (for convenience in method chaining).
+     */
     importExternal(name, modulePath, isType = false) {
         this.externalImport.set(name, { isType, modulePath });
         return name;
     }
+    /**
+     * Convenience wrapper that calls {@link importExternal} with `isType = true`.
+     */
     importExternalType(name, modulePath) {
         return this.importExternal(name, modulePath, true);
     }
+    /**
+     * Imports a type from the shared `counterfact-types/index.ts` module,
+     * resolving the path relative to this script's location in the repository.
+     *
+     * @param name - The type name to import (e.g. `"WideOperationArgument"`).
+     */
     importSharedType(name) {
-        return this.importExternal(name, nodePath
-            .join(this.relativePathToBase, "counterfact-types/index.ts")
-            .replaceAll("\\", "/"), true);
+        return this.importExternal(name, pathJoin(this.relativePathToBase, "counterfact-types/index.ts"), true);
     }
     exportType(coder) {
         return this.export(coder, true);
     }
+    /** `true` while at least one export promise is still pending. */
     isInProgress() {
         return Array.from(this.exports.values()).some((exportStatement) => !exportStatement.done);
     }
+    /** Returns a promise that resolves when all pending export promises settle. */
     finished() {
         return Promise.all(Array.from(this.exports.values(), (value) => value.promise));
     }
@@ -129,9 +189,7 @@ export class Script {
     }
     importStatements() {
         return Array.from(this.imports, ([name, { isDefault, isType, script }]) => {
-            const resolvedPath = escapePathForWindows(nodePath
-                .relative(nodePath.dirname(this.path).replaceAll("\\", "/"), script.path.replace(/\.ts$/u, ".js"))
-                .replaceAll("\\", "/"));
+            const resolvedPath = escapePathForWindows(pathRelative(pathDirname(this.path), script.path.replace(/\.ts$/u, ".js")));
             return `import${isType ? " type" : ""} ${isDefault ? name : `{ ${name} }`} from "${resolvedPath.includes("../") ? "" : "./"}${resolvedPath}";`;
         });
     }
@@ -150,6 +208,11 @@ export class Script {
             return `${jsdoc}${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code};`;
         });
     }
+    /**
+     * Formats the fully assembled script source with Prettier and returns it.
+     *
+     * All pending export promises are awaited before formatting.
+     */
     contents() {
         return format([
             this.comments.map((comment) => `// ${comment}`).join("\n"),

package/dist/typescript-generator/specification.js

@@ -2,6 +2,14 @@ import { bundle } from "@apidevtools/json-schema-ref-parser";
 import createDebug from "debug";
 import { Requirement } from "./requirement.js";
 const debug = createDebug("counterfact:typescript-generator:specification");
+/**
+ * Represents a fully dereferenced OpenAPI specification as a navigable tree
+ * of {@link Requirement} nodes.
+ *
+ * Use {@link Specification.fromFile} to load a spec from disk or a URL; the
+ * static method bundles external `$ref` references into a single in-memory
+ * object before constructing the tree.
+ */
 export class Specification {
     cache;
     rootRequirement;
@@ -11,15 +19,34 @@ export class Specification {
             this.rootRequirement = rootRequirement;
         }
     }
+    /**
+     * Loads the OpenAPI document at `urlOrPath`, bundles all external `$ref`
+     * references, and returns a fully initialised {@link Specification}.
+     *
+     * @param urlOrPath - A local file path or HTTP(S) URL.
+     * @throws When the document cannot be found or parsed.
+     */
     static async fromFile(urlOrPath) {
         const specification = new Specification();
         await specification.load(urlOrPath);
         return specification;
     }
+    /**
+     * Returns the {@link Requirement} at `url` (a JSON Pointer such as
+     * `"#/paths"`).
+     *
+     * @param url - A JSON Pointer string (must start with `"#/"`).
+     */
     getRequirement(url) {
         debug("getting requirement at %s", url);
         return this.rootRequirement.select(url.slice(2));
     }
+    /**
+     * Loads (or reloads) the specification from `urlOrPath`.
+     *
+     * @param urlOrPath - A local file path or HTTP(S) URL.
+     * @throws When the document cannot be found or parsed.
+     */
     async load(urlOrPath) {
         try {
             this.rootRequirement = new Requirement((await bundle(urlOrPath)), urlOrPath, this);

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

@@ -1,5 +1,13 @@
 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.
+ *
+ * @param filePath - Path to a file; the *directory* part of this path is
+ *   created, not the file itself.
+ */
 export function ensureDirectoryExists(filePath) {
     const directory = nodePath.dirname(filePath);
     try {

package/dist/util/forward-slash-path.js

@@ -0,0 +1,63 @@
+import nodePath from "node:path";
+/**
+ * Converts a file-system path to use forward slashes as separators.
+ *
+ * On Windows, `node:path` methods such as `path.join` and `path.resolve`
+ * return paths with backslash separators.  Many parts of Counterfact
+ * (chokidar watchers, ES module import specifiers, URL routing) require
+ * forward slashes.  This function centralises that normalisation and returns
+ * a {@link ForwardSlashPath} branded type so that call sites that demand a
+ * forward-slash path are statically enforced.
+ *
+ * @param path - Any file-system path string.
+ * @returns The same path with every `\` replaced by `/`.
+ */
+export function toForwardSlashPath(path) {
+    return path.replaceAll("\\", "/");
+}
+/**
+ * Joins path segments and returns a {@link ForwardSlashPath} with forward
+ * slashes regardless of the host operating system.
+ *
+ * Equivalent to `toForwardSlashPath(nodePath.join(...paths))`.
+ *
+ * @param paths - Path segments to join.
+ * @returns The joined path normalised to forward slashes.
+ */
+export function pathJoin(...paths) {
+    return toForwardSlashPath(nodePath.join(...paths));
+}
+/**
+ * Returns the relative path from `from` to `to` using forward slashes.
+ *
+ * Equivalent to `toForwardSlashPath(nodePath.relative(from, to))`.
+ *
+ * @param from - The starting path.
+ * @param to - The destination path.
+ * @returns The relative path normalised to forward slashes.
+ */
+export function pathRelative(from, to) {
+    return toForwardSlashPath(nodePath.relative(from, to));
+}
+/**
+ * Returns the directory portion of a path using forward slashes.
+ *
+ * Equivalent to `toForwardSlashPath(nodePath.dirname(path))`.
+ *
+ * @param path - The file path.
+ * @returns The directory portion normalised to forward slashes.
+ */
+export function pathDirname(path) {
+    return toForwardSlashPath(nodePath.dirname(path));
+}
+/**
+ * Resolves a sequence of paths into an absolute path using forward slashes.
+ *
+ * Equivalent to `toForwardSlashPath(nodePath.resolve(...paths))`.
+ *
+ * @param paths - Path segments to resolve.
+ * @returns The resolved absolute path normalised to forward slashes.
+ */
+export function pathResolve(...paths) {
+    return toForwardSlashPath(nodePath.resolve(...paths));
+}

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,12 +1,37 @@
 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.
+ *
+ * Accepts three kinds of inputs:
+ * - **HTTP(S) URLs** — fetches with `node-fetch`.
+ * - **`file://` URLs** — reads via the Node.js `fs` module.
+ * - **File system paths** — reads via the Node.js `fs` module.
+ *
+ * @param urlOrPath - A URL string or file-system path.
+ * @returns The file contents as a string.
+ */
 export async function readFile(urlOrPath) {
     if (urlOrPath.startsWith("http")) {
         const response = await nodeFetch(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");
 }

package/dist/util/runtime-can-execute-erasable-ts.js

@@ -2,6 +2,18 @@ import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+/* eslint-disable security/detect-non-literal-fs-filename -- runtime probe only writes fixed filenames in a fresh temporary directory. */
+/**
+ * Probes the current Node.js runtime to determine whether it can execute
+ * TypeScript source files directly (via `--experimental-strip-types` or
+ * equivalent).
+ *
+ * The check works by writing a tiny TypeScript module to a temporary directory
+ * and attempting to import it.  If the import succeeds and returns the
+ * expected value, the runtime supports native TypeScript execution.
+ *
+ * @returns `true` when the runtime can execute `.ts` files natively.
+ */
 export async function runtimeCanExecuteErasableTs() {
     const dir = mkdtempSync(join(tmpdir(), "ts-probe-"));
     // helper.ts is imported via .js extension — the TypeScript convention used

package/dist/util/windows-escape.js

@@ -1,5 +1,16 @@
 const UNICODE_RATIO_SYMBOL = "∶"; // U+2236
 const REGULAR_COLON = ":";
+/**
+ * Escapes a Windows absolute path for use in an ES module import specifier.
+ *
+ * On Windows, drive letters produce colons (e.g. `C:\path`) which are invalid
+ * in URL-like import paths.  The drive separator colon and any additional
+ * colons in the path are replaced with the Unicode ratio symbol `∶` (U+2236),
+ * which is visually identical but safe in import specifiers.
+ *
+ * @param path - The file-system path to escape.
+ * @returns An escaped path safe for use in an import specifier.
+ */
 export function escapePathForWindows(path) {
     if (path.at(1) === ":") {
         return (path.slice(0, 2) +
@@ -7,6 +18,13 @@ export function escapePathForWindows(path) {
     }
     return path.replaceAll(REGULAR_COLON, UNICODE_RATIO_SYMBOL);
 }
+/**
+ * Reverses the transformation applied by {@link escapePathForWindows},
+ * converting `∶` back to `:`.
+ *
+ * @param path - A previously escaped path.
+ * @returns The original unescaped path.
+ */
 export function unescapePathForWindows(path) {
     return path.replaceAll(UNICODE_RATIO_SYMBOL, REGULAR_COLON);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.7.0",
+  "version": "2.9.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",
@@ -21,9 +21,9 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pmcelhaney/counterfact.git"
+    "url": "git+https://github.com/counterfact/api-simulator.git"
   },
-  "bugs": "https://github.com/pmcelhaney/counterfact/issues",
+  "bugs": "https://github.com/counterfact/api-simulator/issues",
   "homepage": "https://counterfact.dev",
   "funding": {
     "type": "github",
@@ -76,7 +76,8 @@
     "lint:quickfix": "eslint --fix . eslint --fix demo-ts --rule=\"import/namespace: 0,etc/no-deprecated:0,import/no-cycle:0,no-explicit-type-exports/no-explicit-type-exports:0,import/no-deprecated:0,import/no-self-import:0,import/default:0,import/no-named-as-default:0\" --ignore-pattern dist --ignore-pattern out",
     "go:petstore": "yarn build && yarn counterfact https://petstore3.swagger.io/api/v3/openapi.json out",
     "go:petstore2": "yarn build && yarn counterfact  https://petstore.swagger.io/v2/swagger.json out",
-    "go:example": "yarn build && node ./bin/counterfact.js ./openapi-example.yaml out",
+    "go:example": "yarn build && node ./bin/counterfact.js ./test/fixtures/openapi/example.yaml out",
+    "go:multiple-apis": "yarn build && node ./bin/counterfact.js --config ./test/fixtures/config/multiple-apis.yaml",
     "counterfact": "./bin/counterfact.js",
     "postinstall": "patch-package"
   },

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

@@ -1,42 +0,0 @@
-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 { openapiMiddleware } from "./openapi-middleware.js";
-const debug = createDebug("counterfact:server:create-koa-app");
-export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
-    const app = new Koa();
-    app.use(openapiMiddleware(config.openApiPath, `//localhost:${config.port}${config.routePrefix}`));
-    app.use(koaSwagger({
-        routePrefix: "/counterfact/swagger",
-        swaggerOptions: {
-            url: "/counterfact/openapi",
-        },
-    }));
-    if (config.startAdminApi) {
-        app.use(adminApiMiddleware(registry, contextRegistry, config));
-    }
-    debug("basePath: %s", config.basePath);
-    debug("routes", registry.routes);
-    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";
-        }
-    });
-    app.use(koaMiddleware);
-    return app;
-}

package/dist/server/openapi-middleware.js

@@ -1,19 +0,0 @@
-import { bundle } from "@apidevtools/json-schema-ref-parser";
-import { dump } from "js-yaml";
-export function openapiMiddleware(openApiPath, url) {
-    return async (ctx, next) => {
-        if (ctx.URL.pathname === "/counterfact/openapi") {
-            const openApiDocument = (await bundle(openApiPath));
-            openApiDocument.servers ??= [];
-            openApiDocument.servers.unshift({
-                description: "Counterfact",
-                url,
-            });
-            // OpenApi 2 support:
-            openApiDocument.host = url;
-            ctx.body = dump(openApiDocument);
-            return;
-        }
-        await next();
-    };
-}