counterfact 2.2.1 → 2.3.0

package/README.md

@@ -202,6 +202,7 @@ npx counterfact@latest [openapi.yaml] [destination] [options]
 | `-w, --watch`       | Generate and watch for spec changes         |
 | `-s, --serve`       | Start the mock server                       |
 | `-r, --repl`        | Start the interactive REPL                  |
+| `--spec <path>`     | Path or URL to the OpenAPI document         |
 | `--proxy-url <url>` | Forward all requests to this URL by default |
 | `--prefix <path>`   | Base path prefix (e.g. `/api/v1`)           |
 

package/bin/README.md

@@ -37,6 +37,7 @@ npx counterfact openapi.yaml ./api [options]
 | `-w, --watch` | Re-generate whenever the spec changes |
 | `-s, --serve` | Start the HTTP server |
 | `-r, --repl` | Start the interactive REPL |
+| `--spec <path>` | Path or URL to the OpenAPI document (alternative to positional argument) |
 | `--proxy-url <url>` | Forward all unmatched requests to this upstream URL |
 | `--prefix <path>` | Base path prefix for all routes (e.g. `/api/v1`) |
 

package/bin/counterfact.js

@@ -102,11 +102,20 @@ async function main(source, destination) {
 
   const options = program.opts();
 
+  // --spec takes precedence over the positional [openapi.yaml] argument.
+  // When --spec is provided, the [openapi.yaml] positional slot shifts to
+  // become the [destination] argument (so `counterfact --spec api.yaml ./api`
+  // works the same as `counterfact api.yaml ./api`).
+  if (options.spec) {
+    if (source !== "_") {
+      destination = source;
+    }
+    source = options.spec;
+  }
+
   const args = process.argv;
 
-  const destinationPath = nodePath
-    .join(process.cwd(), destination)
-    .replaceAll("\\", "/");
+  const destinationPath = nodePath.resolve(destination).replaceAll("\\", "/");
 
   const basePath = nodePath.resolve(destinationPath).replaceAll("\\", "/");
 
@@ -155,6 +164,8 @@ async function main(source, destination) {
         options.watch ||
         options.watchTypes ||
         options.buildCache,
+
+      prune: Boolean(options.prune),
     },
 
     openApiPath: source,
@@ -326,5 +337,13 @@ program
     "--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)",
+  )
   .action(main)
   .parse(process.argv);

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

@@ -1,3 +1,4 @@
 export interface OpenApiHeader {
-  schema: unknown;
+  required?: boolean;
+  schema: { [key: string]: unknown };
 }

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

@@ -38,7 +38,7 @@ type OmitValueWhenNever<Base> = Pick<
 interface OpenApiResponse {
   content: { [key: MediaType]: OpenApiContent };
   examples?: { [key: string]: unknown };
-  headers: { [key: string]: OpenApiHeader };
+  headers: { [key: string]: { schema: unknown } };
   requiredHeaders: string;
 }
 
@@ -257,6 +257,9 @@ interface OpenApiOperation {
         };
       };
       examples?: { [key: string]: unknown };
+      headers?: {
+        [name: string]: OpenApiHeader;
+      };
       schema?: { [key: string]: unknown };
     };
   };

package/dist/server/module-loader.js

@@ -110,10 +110,28 @@ export class ModuleLoader extends EventTarget {
             if (basename(pathName).startsWith("_.context.") &&
                 isContextModule(endpoint)) {
                 const loadContext = (path) => this.contextRegistry.find(path);
+                const contextDir = nodePath.dirname(unescapePathForWindows(pathName));
+                const readJson = async (relativePath) => {
+                    const absolutePath = nodePath.resolve(contextDir, relativePath);
+                    let content;
+                    try {
+                        content = await fs.readFile(absolutePath, "utf8");
+                    }
+                    catch {
+                        throw new Error(`readJson: could not read file at "${absolutePath}" (resolved from "${relativePath}" relative to "${contextDir}")`);
+                    }
+                    try {
+                        return JSON.parse(content);
+                    }
+                    catch {
+                        throw new Error(`readJson: file at "${absolutePath}" does not contain valid JSON`);
+                    }
+                };
                 this.contextRegistry.update(directory, 
                 // @ts-expect-error TS says Context has no constructable signatures but that's not true?
                 new endpoint.Context({
                     loadContext,
+                    readJson,
                 }));
                 return;
             }

package/dist/server/registry.js

@@ -37,7 +37,7 @@ export class Registry {
     moduleTree = new ModuleTree();
     middlewares = new Map();
     constructor() {
-        this.middlewares.set("/", ($, respondTo) => respondTo($));
+        this.middlewares.set("", ($, respondTo) => respondTo($));
     }
     get routes() {
         return this.moduleTree.routes;
@@ -46,7 +46,7 @@ export class Registry {
         this.moduleTree.add(url, module);
     }
     addMiddleware(url, callback) {
-        this.middlewares.set(url, callback);
+        this.middlewares.set(url === "/" ? "" : url, callback);
     }
     remove(url) {
         this.moduleTree.remove(url);
@@ -111,11 +111,10 @@ export class Registry {
             };
             const middlewares = this.middlewares;
             function recurse(path, respondTo) {
+                debug("recursing path", path);
                 if (path === null)
                     return respondTo;
-                const nextPath = path === "/" || path === ""
-                    ? null
-                    : path.slice(0, path.lastIndexOf("/")) || "/";
+                const nextPath = path === "" ? null : path.slice(0, path.lastIndexOf("/"));
                 const middleware = middlewares.get(path);
                 if (middleware !== undefined) {
                     return recurse(nextPath, ($) => middleware($, respondTo));

package/dist/server/response-builder.js

@@ -96,6 +96,12 @@ export function createResponseBuilder(operation, config) {
                     return unknownStatusCodeResponse(this.status);
                 }
                 const { content } = response;
+                const generatedHeaders = {};
+                for (const [name, header] of Object.entries(response.headers ?? {})) {
+                    if (header.required && !(name in (this.headers ?? {}))) {
+                        generatedHeaders[name] = JSONSchemaFaker.generate(header.schema ?? { type: "string" });
+                    }
+                }
                 return {
                     ...this,
                     content: Object.keys(content).map((type) => ({
@@ -104,6 +110,10 @@ export function createResponseBuilder(operation, config) {
                             : JSONSchemaFaker.generate(content[type]?.schema ?? { type: "object" }), content[type]?.schema),
                         type,
                     })),
+                    headers: {
+                        ...generatedHeaders,
+                        ...this.headers,
+                    },
                 };
             },
             randomLegacy() {

package/dist/typescript-generator/generate.js

@@ -5,6 +5,7 @@ import nodePath from "node:path";
 import createDebug from "debug";
 import { ensureDirectoryExists } from "../util/ensure-directory-exists.js";
 import { OperationCoder } from "./operation-coder.js";
+import { pruneRoutes } from "./prune.js";
 import { Repository } from "./repository.js";
 import { Specification } from "./specification.js";
 const debug = createDebug("counterfact:typescript-generator:generate");
@@ -41,6 +42,11 @@ export async function generate(source, destination, generateOptions, repository
     debug("reading the #/paths from the specification");
     const paths = await getPathsFromSpecification(specification);
     debug("got %i paths", paths.size);
+    if (generateOptions.prune && generateOptions.routes) {
+        debug("pruning defunct route files");
+        await pruneRoutes(destination, paths.keys());
+        debug("done pruning");
+    }
     const securityRequirement = specification.getRequirement("#/components/securitySchemes");
     const securitySchemes = Object.values(securityRequirement?.data ?? {});
     paths.forEach((pathDefinition, key) => {

package/dist/typescript-generator/prune.js

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+import createDebug from "debug";
+const debug = createDebug("counterfact:typescript-generator:prune");
+/**
+ * Collects all .ts route files in a directory recursively.
+ * Context files (_.context.ts) are excluded.
+ * @param {string} routesDir - Path to routes directory
+ * @param {string} currentPath - Current subdirectory being processed (relative to routesDir)
+ * @returns {Promise<string[]>} - Array of relative paths (using forward slashes)
+ */
+async function collectRouteFiles(routesDir, currentPath = "") {
+    const files = [];
+    try {
+        const fullDir = currentPath
+            ? nodePath.join(routesDir, currentPath)
+            : routesDir;
+        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)));
+            }
+            else if (entry.name.endsWith(".ts") && entry.name !== "_.context.ts") {
+                files.push(relativePath);
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    return files;
+}
+/**
+ * Recursively removes empty directories under rootDir, but not rootDir itself.
+ * @param {string} dir - Directory to check
+ * @param {string} rootDir - Root directory that should never be removed
+ */
+async function removeEmptyDirectories(dir, rootDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            await removeEmptyDirectories(nodePath.join(dir, entry.name), rootDir);
+        }
+    }
+    if (nodePath.resolve(dir) === nodePath.resolve(rootDir)) {
+        return;
+    }
+    const remaining = await fs.readdir(dir);
+    if (remaining.length === 0) {
+        await fs.rmdir(dir);
+        debug("removed empty directory: %s", dir);
+    }
+}
+/**
+ * Converts an OpenAPI path to the expected route file path (relative to routesDir).
+ * e.g. "/pet/{id}" -> "pet/{id}.ts", "/" -> "index.ts"
+ * @param {string} openApiPath
+ * @returns {string}
+ */
+function openApiPathToRouteFile(openApiPath) {
+    const filePath = openApiPath === "/" ? "index" : openApiPath.slice(1);
+    return `${filePath}.ts`;
+}
+/**
+ * Prunes route files that no longer correspond to any path in the OpenAPI spec.
+ * Context files (_.context.ts) are never pruned.
+ * @param {string} destination - Base destination directory (contains the routes/ sub-directory)
+ * @param {Iterable<string>} openApiPaths - Iterable of OpenAPI path strings (e.g. "/pet/{id}")
+ * @returns {Promise<number>} - Number of files removed
+ */
+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);
+    debug("actual route files: %o", actualFiles);
+    let prunedCount = 0;
+    for (const file of actualFiles) {
+        const normalizedFile = file.replaceAll("\\", "/");
+        if (!expectedFiles.has(normalizedFile)) {
+            const fullPath = nodePath.join(routesDir, file);
+            debug("pruning %s", fullPath);
+            await fs.rm(fullPath);
+            prunedCount++;
+        }
+    }
+    await removeEmptyDirectories(routesDir, routesDir);
+    debug("pruned %d files", prunedCount);
+    return prunedCount;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.2.1",
+  "version": "2.3.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",
@@ -87,7 +87,7 @@
     "@types/debug": "^4.1.12",
     "@types/jest": "30.0.0",
     "@types/js-yaml": "4.0.9",
-    "@types/koa": "3.0.1",
+    "@types/koa": "3.0.2",
     "@types/koa-bodyparser": "4.3.13",
     "@types/koa-proxy": "1.0.8",
     "@types/koa-static": "4.0.4",