counterfact 2.5.1 → 2.6.0

package/dist/server/module-tree.js

@@ -3,8 +3,8 @@ function isDirectory(test) {
 }
 export class ModuleTree {
     root = {
-        directories: {},
-        files: {},
+        directories: new Map(),
+        files: new Map(),
         isWildcard: false,
         name: "",
         rawName: "",
@@ -17,16 +17,19 @@ export class ModuleTree {
         if (remainingSegments.length === 0) {
             return directory;
         }
-        const isNewDirectory = directory.directories[segment.toLowerCase()] === undefined;
-        const nextDirectory = (directory.directories[segment.toLowerCase()] ??= {
-            directories: {},
-            files: {},
-            isWildcard: segment.startsWith("{"),
-            name: segment.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
-            rawName: segment,
-        });
+        const isNewDirectory = !directory.directories.has(segment.toLowerCase());
+        if (isNewDirectory) {
+            directory.directories.set(segment.toLowerCase(), {
+                directories: new Map(),
+                files: new Map(),
+                isWildcard: segment.startsWith("{"),
+                name: segment.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
+                rawName: segment,
+            });
+        }
+        const nextDirectory = directory.directories.get(segment.toLowerCase());
         if (isNewDirectory && segment.startsWith("{")) {
-            const ambiguousWildcardDirectories = Object.values(directory.directories).filter((subdirectory) => subdirectory.isWildcard);
+            const ambiguousWildcardDirectories = Array.from(directory.directories.values()).filter((subdirectory) => subdirectory.isWildcard);
             if (ambiguousWildcardDirectories.length > 1) {
                 process.stderr.write(`[counterfact] ERROR: Ambiguous wildcard paths detected. Multiple wildcard directories exist at the same level: ${ambiguousWildcardDirectories.map((d) => d.rawName).join(", ")}. Requests may be routed unpredictably.\n`);
             }
@@ -42,14 +45,14 @@ export class ModuleTree {
         if (filename === undefined) {
             throw new Error("The file name (the last segment of the URL) is undefined. This is theoretically impossible but TypeScript can't enforce it.");
         }
-        targetDirectory.files[filename] = {
+        targetDirectory.files.set(filename, {
             isWildcard: filename.startsWith("{"),
             module,
             name: filename.replace(/^\{(?<name>.*)\}$/u, "$<name>"),
             rawName: filename,
-        };
+        });
         if (filename.startsWith("{")) {
-            const ambiguousWildcardFiles = Object.values(targetDirectory.files).filter((file) => file.isWildcard);
+            const ambiguousWildcardFiles = Array.from(targetDirectory.files.values()).filter((file) => file.isWildcard);
             if (ambiguousWildcardFiles.length > 1) {
                 process.stderr.write(`[counterfact] ERROR: Ambiguous wildcard paths detected. Multiple wildcard files exist at the same path level: ${ambiguousWildcardFiles.map((f) => f.rawName).join(", ")}. Requests may be routed unpredictably.\n`);
             }
@@ -67,10 +70,10 @@ export class ModuleTree {
             return;
         }
         if (remainingSegments.length === 0) {
-            delete directory.files[segment.toLowerCase()];
+            directory.files.delete(segment.toLowerCase());
             return;
         }
-        this.removeModuleFromDirectory(directory.directories[segment.toLowerCase()], remainingSegments);
+        this.removeModuleFromDirectory(directory.directories.get(segment.toLowerCase()), remainingSegments);
     }
     remove(url) {
         const segments = url.split("/").slice(1);
@@ -81,14 +84,14 @@ export class ModuleTree {
     }
     buildMatch(directory, segment, pathVariables, matchedPath, method) {
         function normalizedSegment(segment, directory) {
-            for (const file in directory.files) {
+            for (const file of directory.files.keys()) {
                 if (file.toLowerCase() === segment.toLowerCase()) {
                     return file;
                 }
             }
             return "";
         }
-        const exactMatchFile = directory.files[normalizedSegment(segment, directory)];
+        const exactMatchFile = directory.files.get(normalizedSegment(segment, directory));
         // If the URL segment literally matches a file key (e.g., requesting "/{x}"
         // as a literal URL value), exactMatchFile may be a wildcard file. In that
         // case, fall through to wildcard matching below.
@@ -99,7 +102,7 @@ export class ModuleTree {
                 pathVariables,
             };
         }
-        const wildcardFiles = Object.values(directory.files).filter((file) => file.isWildcard && this.fileModuleDefined(file, method));
+        const wildcardFiles = Array.from(directory.files.values()).filter((file) => file.isWildcard && this.fileModuleDefined(file, method));
         if (wildcardFiles.length > 1) {
             const firstWildcard = wildcardFiles[0];
             return {
@@ -144,11 +147,11 @@ export class ModuleTree {
             (remainingSegments.length === 1 && remainingSegments[0] === "")) {
             return this.buildMatch(directory, segment, pathVariables, matchedPath, method);
         }
-        const exactMatch = directory.directories[segment.toLowerCase()];
+        const exactMatch = directory.directories.get(segment.toLowerCase());
         if (isDirectory(exactMatch)) {
             return this.matchWithinDirectory(exactMatch, remainingSegments, pathVariables, `${matchedPath}/${segment}`, method);
         }
-        const wildcardDirectories = Object.values(directory.directories).filter((subdirectory) => subdirectory.isWildcard);
+        const wildcardDirectories = Array.from(directory.directories.values()).filter((subdirectory) => subdirectory.isWildcard);
         const wildcardMatches = [];
         for (const wildcardDirectory of wildcardDirectories) {
             const wildcardMatch = this.matchWithinDirectory(wildcardDirectory, remainingSegments, {
@@ -171,10 +174,10 @@ export class ModuleTree {
     get routes() {
         const routes = [];
         function traverse(directory, path) {
-            Object.values(directory.directories).forEach((subdirectory) => {
+            directory.directories.forEach((subdirectory) => {
                 traverse(subdirectory, `${path}/${subdirectory.rawName}`);
             });
-            Object.values(directory.files).forEach((file) => {
+            directory.files.forEach((file) => {
                 const methods = Object.entries(file.module).map(([method, implementation]) => [method, String(implementation)]);
                 routes.push({
                     methods: Object.fromEntries(methods),

package/dist/server/openapi-middleware.js

@@ -1,5 +1,5 @@
 import { bundle } from "@apidevtools/json-schema-ref-parser";
-import yaml from "js-yaml";
+import { dump } from "js-yaml";
 export function openapiMiddleware(openApiPath, url) {
     return async (ctx, next) => {
         if (ctx.URL.pathname === "/counterfact/openapi") {
@@ -11,7 +11,7 @@ export function openapiMiddleware(openApiPath, url) {
             });
             // OpenApi 2 support:
             openApiDocument.host = url;
-            ctx.body = yaml.dump(openApiDocument);
+            ctx.body = dump(openApiDocument);
             return;
         }
         await next();

package/dist/server/registry.js

@@ -26,10 +26,10 @@ function castParameter(value, type) {
     }
     return value;
 }
-function castParameters(parameters = {}, parameterTypes = {}) {
+function castParameters(parameters = {}, parameterTypes = new Map()) {
     const copy = {};
     Object.entries(parameters).forEach(([key, value]) => {
-        copy[key] = castParameter(value, parameterTypes?.[key] ?? "string");
+        copy[key] = castParameter(value, parameterTypes.get(key) ?? "string");
     });
     return copy;
 }

package/dist/server/request-validator.js

@@ -0,0 +1,61 @@
+import Ajv from "ajv";
+const ajv = new Ajv({
+    allErrors: true,
+    unknownFormats: "ignore",
+    coerceTypes: false,
+});
+function findMissingRequired(parameters, location, values) {
+    return parameters
+        .filter((p) => p.in === location && p.required === true)
+        .filter((p) => !(p.name in values) || values[p.name] === undefined)
+        .map((p) => `${location} parameter '${p.name}' is required`);
+}
+export function validateRequest(operation, request) {
+    if (!operation) {
+        return { errors: [], valid: true };
+    }
+    const errors = [];
+    const parameters = operation.parameters ?? [];
+    // For query and header parameters, HTTP always delivers values as strings.
+    // Only check that required parameters are present; type coercion is handled
+    // by the registry before the route handler is called.
+    errors.push(...findMissingRequired(parameters, "query", request.query));
+    errors.push(...findMissingRequired(parameters, "header", request.headers));
+    // Validate request body (OpenAPI 3.x requestBody)
+    if (operation.requestBody?.content !== undefined) {
+        const schema = operation.requestBody.content["application/json"]?.schema ??
+            operation.requestBody.content["application/x-www-form-urlencoded"]
+                ?.schema;
+        if (schema !== undefined) {
+            const valid = ajv.validate(schema, request.body);
+            if (!valid && ajv.errors) {
+                for (const error of ajv.errors) {
+                    const path = error.instancePath ??
+                        error.dataPath ??
+                        "";
+                    errors.push(`body${path} ${error.message ?? "is invalid"}`);
+                }
+            }
+        }
+        else if (operation.requestBody.required === true && !request.body) {
+            errors.push("body is required");
+        }
+    }
+    // Validate request body (OpenAPI 2.x body parameter)
+    const bodyParam = parameters.find((p) => p.in === "body");
+    if (bodyParam?.schema !== undefined) {
+        const valid = ajv.validate(bodyParam.schema, request.body);
+        if (!valid && ajv.errors) {
+            for (const error of ajv.errors) {
+                const path = error.instancePath ??
+                    error.dataPath ??
+                    "";
+                errors.push(`body${path} ${error.message ?? "is invalid"}`);
+            }
+        }
+    }
+    return {
+        errors,
+        valid: errors.length === 0,
+    };
+}

package/dist/server/transpiler.js

@@ -67,12 +67,20 @@ export class Transpiler extends EventTarget {
     async transpileFile(eventName, sourcePath, destinationPath) {
         ensureDirectoryExists(destinationPath);
         const source = await fs.readFile(sourcePath, "utf8");
-        const result = ts.transpileModule(source, {
+        const transpileOutput = ts.transpileModule(source, {
             compilerOptions: {
                 module: ts.ModuleKind[this.moduleKind.toLowerCase() === "module" ? "ES2022" : "CommonJS"],
                 target: ts.ScriptTarget.ES2015,
             },
-        }).outputText;
+            reportDiagnostics: true,
+        });
+        if (transpileOutput.diagnostics?.length) {
+            for (const diagnostic of transpileOutput.diagnostics) {
+                const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+                debug("TypeScript diagnostic in %s: %s", sourcePath, message);
+            }
+        }
+        const result = transpileOutput.outputText;
         const fullDestination = nodePath
             .join(sourcePath
             .replace(this.sourcePath, this.destinationPath)
@@ -82,10 +90,10 @@ export class Transpiler extends EventTarget {
         try {
             await fs.writeFile(fullDestination, resultWithTransformedFileExtensions);
         }
-        catch {
-            debug("error transpiling %s", fullDestination);
+        catch (error) {
+            debug("error writing transpiled output to %s: %o", fullDestination, error);
             this.dispatchEvent(new Event("error"));
-            throw new Error("could not transpile");
+            throw new Error("could not transpile", { cause: error });
         }
         this.dispatchEvent(new Event("write"));
     }

package/dist/typescript-generator/coder.js

@@ -12,6 +12,9 @@ export class Coder {
     beforeExport(_path) {
         return "";
     }
+    jsdoc() {
+        return "";
+    }
     write(script) {
         if (this.requirement.isReference) {
             return script.import(this);

package/dist/typescript-generator/jsdoc.js

@@ -0,0 +1,45 @@
+/**
+ * Builds a JSDoc comment string from OpenAPI schema metadata.
+ * Returns an empty string if there is no relevant metadata.
+ */
+export function buildJsDoc(data) {
+    const lines = [];
+    const description = data["description"];
+    const summary = data["summary"];
+    const example = data["example"];
+    const examples = data["examples"];
+    const defaultValue = data["default"];
+    const format = data["format"];
+    const deprecated = data["deprecated"];
+    const mainText = description ?? summary;
+    if (mainText) {
+        // Escape */ to prevent prematurely closing the JSDoc block
+        const escaped = String(mainText).replace(/\*\//gu, "* /");
+        const textLines = escaped.split("\n");
+        for (const line of textLines) {
+            lines.push(` * ${line}`);
+        }
+    }
+    if (format !== undefined) {
+        lines.push(` * @format ${format}`);
+    }
+    if (defaultValue !== undefined) {
+        lines.push(` * @default ${JSON.stringify(defaultValue)}`);
+    }
+    // Use scalar `example`, or fall back to the first value from `examples`
+    const exampleValue = example !== undefined
+        ? example
+        : examples !== undefined
+            ? Object.values(examples)[0]?.value
+            : undefined;
+    if (exampleValue !== undefined) {
+        lines.push(` * @example ${JSON.stringify(exampleValue)}`);
+    }
+    if (deprecated === true) {
+        lines.push(` * @deprecated`);
+    }
+    if (lines.length === 0) {
+        return "";
+    }
+    return `/**\n${lines.join("\n")}\n */\n`;
+}

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

@@ -1,5 +1,6 @@
 import nodePath from "node:path";
 import { CONTEXT_FILE_TOKEN } from "./context-file-token.js";
+import { buildJsDoc } from "./jsdoc.js";
 import { ParameterExportTypeCoder } from "./parameter-export-type-coder.js";
 import { ParametersTypeCoder } from "./parameters-type-coder.js";
 import { READ_ONLY_COMMENTS } from "./read-only-comments.js";
@@ -88,6 +89,9 @@ export class OperationTypeCoder extends TypeCoder {
             ? sanitizeIdentifier(operationId)
             : `HTTP_${this.requestMethod.toUpperCase()}`;
     }
+    jsdoc() {
+        return buildJsDoc(this.requirement.data);
+    }
     names() {
         return super.names(this.getOperationBaseName());
     }

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

@@ -1,4 +1,5 @@
 import nodePath from "node:path";
+import { buildJsDoc } from "./jsdoc.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 export class ParametersTypeCoder extends TypeCoder {
@@ -23,7 +24,10 @@ export class ParametersTypeCoder extends TypeCoder {
             const schema = parameter.has("schema")
                 ? parameter.get("schema")
                 : parameter;
-            return `"${name}"${optionalFlag}: ${new SchemaTypeCoder(schema).write(script)}`;
+            const comment = buildJsDoc(parameter.data);
+            const commentPrefix = comment ? `\n${comment}` : "";
+            const typeString = new SchemaTypeCoder(schema).write(script);
+            return `${commentPrefix}"${name}"${optionalFlag}: ${typeString}`;
         });
         if (typeDefinitions.length === 0) {
             return "never";

package/dist/typescript-generator/prune.js

@@ -45,7 +45,8 @@ async function removeEmptyDirectories(dir, rootDir) {
     try {
         entries = await fs.readdir(dir, { withFileTypes: true });
     }
-    catch {
+    catch (error) {
+        debug("could not read directory %s: %o", dir, error);
         return;
     }
     for (const entry of entries) {

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

@@ -1,8 +1,12 @@
+import { buildJsDoc } from "./jsdoc.js";
 import { TypeCoder } from "./type-coder.js";
 export class SchemaTypeCoder extends TypeCoder {
     names() {
         return super.names(this.requirement.data["$ref"]?.split("/").at(-1));
     }
+    jsdoc() {
+        return buildJsDoc(this.requirement.data);
+    }
     additionalPropertiesType(script) {
         const { additionalProperties, properties } = this.requirement.data;
         if (!additionalProperties.type) {
@@ -22,7 +26,9 @@ export class SchemaTypeCoder extends TypeCoder {
             const propertyData = property.data;
             const isRequired = typedData.required?.includes(name) || propertyData.required === true;
             const optionalFlag = isRequired ? "" : "?";
-            return `"${name}"${optionalFlag}: ${new SchemaTypeCoder(property).write(script)}`;
+            const comment = buildJsDoc(property.data);
+            const commentPrefix = comment ? `\n${comment}` : "";
+            return `${commentPrefix}"${name}"${optionalFlag}: ${new SchemaTypeCoder(property).write(script)}`;
         });
         if (typedData.additionalProperties) {
             properties.push(`[key: string]: ${this.additionalPropertiesType(script)}`);

package/dist/typescript-generator/script.js

@@ -50,6 +50,7 @@ export class Script {
             id: coder.id,
             isDefault,
             isType,
+            jsdoc: "",
             typeDeclaration: coder.typeDeclaration(this.exports, this),
         };
         exportStatement.promise = coder
@@ -57,6 +58,7 @@ export class Script {
             .then((availableCoder) => {
             exportStatement.name = name;
             exportStatement.code = availableCoder.write(this);
+            exportStatement.jsdoc = availableCoder.jsdoc();
             return availableCoder;
         })
             .catch((error) => {
@@ -134,18 +136,18 @@ export class Script {
         });
     }
     exportStatements() {
-        return Array.from(this.exports.values(), ({ beforeExport, code, isDefault, isType, name, typeDeclaration }) => {
+        return Array.from(this.exports.values(), ({ beforeExport, code, isDefault, isType, jsdoc, name, typeDeclaration, }) => {
             if (typeof code === "object" && code !== null && "raw" in code) {
                 return code.raw;
             }
             if (isDefault) {
-                return `${beforeExport}export default ${code};`;
+                return `${jsdoc}${beforeExport}export default ${code};`;
             }
             const keyword = isType ? "type" : "const";
             const typeAnnotation = (typeDeclaration ?? "").length === 0
                 ? ""
                 : `:${typeDeclaration ?? ""}`;
-            return `${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code};`;
+            return `${jsdoc}${beforeExport}export ${keyword} ${name ?? ""}${typeAnnotation} = ${code};`;
         });
     }
     contents() {

package/dist/typescript-generator/specification.js

@@ -21,6 +21,12 @@ export class Specification {
         return this.rootRequirement.select(url.slice(2));
     }
     async load(urlOrPath) {
-        this.rootRequirement = new Requirement((await bundle(urlOrPath)), urlOrPath, this);
+        try {
+            this.rootRequirement = new Requirement((await bundle(urlOrPath)), urlOrPath, this);
+        }
+        catch (error) {
+            const details = error instanceof Error ? error.message : String(error);
+            throw new Error(`Could not load the OpenAPI spec from "${urlOrPath}".\n${details}`, { cause: error });
+        }
     }
 }

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

@@ -0,0 +1,22 @@
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+export async function runtimeCanExecuteErasableTs() {
+    const dir = mkdtempSync(join(tmpdir(), "ts-probe-"));
+    // helper.ts is imported via .js extension — the TypeScript convention used
+    // throughout this codebase. If the runtime resolves helper.js → helper.ts,
+    // it is fully capable of running the TypeScript source tree.
+    writeFileSync(join(dir, "helper.ts"), 'export const value: string = "ok";\n', "utf8");
+    writeFileSync(join(dir, "main.ts"), 'import { value } from "./helper.js"; export default value;\n', "utf8");
+    try {
+        const mod = await import(pathToFileURL(join(dir, "main.ts")).href);
+        return mod?.default === "ok";
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "2.5.1",
+  "version": "2.6.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",
@@ -94,10 +94,9 @@
     "@types/koa-bodyparser": "4.3.13",
     "@types/koa-proxy": "1.0.8",
     "@types/koa-static": "4.0.4",
-    "@types/lodash": "4.17.24",
     "@types/node": "22",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
     "copyfiles": "2.4.1",
     "eslint": "10.1.0",
     "eslint-formatter-github-annotations": "0.1.0",
@@ -127,10 +126,10 @@
     "@apidevtools/json-schema-ref-parser": "13.0.5",
     "@hapi/accept": "6.0.3",
     "@types/json-schema": "7.0.15",
+    "ajv": "6.14.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
     "debug": "4.4.3",
-    "fetch": "1.1.0",
     "fs-extra": "11.3.4",
     "handlebars": "4.7.9",
     "http-terminator": "3.2.0",
@@ -141,12 +140,14 @@
     "koa-bodyparser": "4.4.1",
     "koa-proxies": "0.12.4",
     "koa2-swagger-ui": "5.12.0",
-    "lodash": "4.18.1",
     "node-fetch": "3.3.2",
     "open": "11.0.0",
     "patch-package": "8.0.1",
+    "posthog-node": "^5.28.11",
     "precinct": "12.2.0",
     "prettier": "3.8.1",
+    "recast": "0.23.11",
+    "tsx": "^4.20.3",
     "typescript": "6.0.2"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",