counterfact 2.5.1 → 2.7.0

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

@@ -1,61 +1,14 @@
 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";
+import { RESERVED_WORDS } from "./reserved-words.js";
 import { ResponsesTypeCoder } from "./responses-type-coder.js";
 import { SchemaTypeCoder } from "./schema-type-coder.js";
 import { TypeCoder } from "./type-coder.js";
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
-const RESERVED_WORDS = new Set([
-    "break",
-    "case",
-    "catch",
-    "class",
-    "const",
-    "continue",
-    "debugger",
-    "default",
-    "delete",
-    "do",
-    "else",
-    "export",
-    "extends",
-    "false",
-    "finally",
-    "for",
-    "function",
-    "if",
-    "import",
-    "in",
-    "instanceof",
-    "new",
-    "null",
-    "return",
-    "static",
-    "super",
-    "switch",
-    "this",
-    "throw",
-    "true",
-    "try",
-    "typeof",
-    "var",
-    "void",
-    "while",
-    "with",
-    "yield",
-    "await",
-    "enum",
-    "implements",
-    "interface",
-    "let",
-    "package",
-    "private",
-    "protected",
-    "public",
-    "type",
-]);
 function sanitizeIdentifier(value) {
     // Treat any run of non-identifier characters as a camelCase separator
     let result = value.replaceAll(/[^\w$]+(?<next>.)/gu, (_, char) => char.toUpperCase());
@@ -88,6 +41,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/read-only-comments.js

@@ -1,5 +1,5 @@
 export const READ_ONLY_COMMENTS = [
     "This code was automatically generated from an OpenAPI description.",
     "Do not edit this file. Edit the OpenAPI file instead.",
-    "For more information, see https://github.com/pmcelhaney/counterfact/blob/main/docs/faq-generated-code.md",
+    "For more information, see https://github.com/pmcelhaney/counterfact/blob/main/docs/faq.md",
 ];

package/dist/typescript-generator/requirement.js

@@ -36,7 +36,14 @@ export class Requirement {
             // Unescape URL encoded characters (e.g. %20 -> " ")
             // Technically we should not be unescaping, but it came up in https://github.com/pmcelhaney/counterfact/issues/1083
             // and I can't think of a reason anyone would intentionally put a % in a key name.
-            .map(unescape);
+            .map((part) => {
+            try {
+                return decodeURIComponent(part);
+            }
+            catch {
+                return part;
+            }
+        });
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         let result = this;
         for (const part of parts) {

package/dist/typescript-generator/reserved-words.js

@@ -0,0 +1,50 @@
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#reserved_words
+export const RESERVED_WORDS = new Set([
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "null",
+    "return",
+    "static",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+    "await",
+    "enum",
+    "implements",
+    "interface",
+    "let",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "type",
+]);

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/load-config-file.js

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+import { load as loadYaml } from "js-yaml";
+function kebabToCamel(str) {
+    return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function normalizeKeys(obj) {
+    return Object.fromEntries(Object.entries(obj).map(([key, value]) => [kebabToCamel(key), value]));
+}
+/**
+ * Loads and parses a counterfact YAML config file.
+ *
+ * @param configPath - Absolute or relative path to the config file.
+ * @param required - When true, throws if the file does not exist.
+ *                   When false (default), returns an empty object for missing files.
+ * @returns A plain object of config keys (camelCase) to values.
+ */
+export async function loadConfigFile(configPath, required = false) {
+    let content;
+    try {
+        content = await readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            if (required) {
+                throw new Error(`Config file not found: ${configPath}`, {
+                    cause: error,
+                });
+            }
+            return {};
+        }
+        throw error;
+    }
+    const parsed = loadYaml(content);
+    if (parsed === null || parsed === undefined) {
+        return {};
+    }
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Config file must be a YAML object (mapping): ${configPath}`);
+    }
+    return normalizeKeys(parsed);
+}

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.7.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,7 +21,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pmcelhaney/counterfact.git"
+    "url": "git+https://github.com/pmcelhaney/counterfact.git"
   },
   "bugs": "https://github.com/pmcelhaney/counterfact/issues",
   "homepage": "https://counterfact.dev",
@@ -56,7 +56,7 @@
     "node": ">=22"
   },
   "bin": {
-    "counterfact": "./bin/counterfact.js"
+    "counterfact": "bin/counterfact.js"
   },
   "files": [
     "bin",
@@ -67,7 +67,7 @@
     "test": "yarn node --experimental-vm-modules ./node_modules/jest-cli/bin/jest --testPathIgnorePatterns=black-box",
     "test:black-box": "rimraf dist && yarn build && python3 -m pytest test-black-box/ -v",
     "test:tsd": "tsd --typings ./dist/server/counterfact-types/index.ts --files ./test/**/*.test-d.ts",
-    "build": "rm -rf dist && tsc && copyfiles -f \"src/client/**\" dist/client && copyfiles -f \"src/counterfact-types/*.ts\" dist/server/counterfact-types && copyfiles -f \"src/server/*.cjs\" dist/server",
+    "build": "rm -rf dist && tsc && copyfiles -f \"src/counterfact-types/*.ts\" dist/server/counterfact-types && copyfiles -f \"src/server/*.cjs\" dist/server",
     "prepack": "yarn build",
     "release": "npx changeset publish",
     "prepare": "husky install",
@@ -84,7 +84,7 @@
     "@changesets/cli": "2.30.0",
     "@eslint/js": "10.0.1",
     "@jest/globals": "^30.3.0",
-    "@swc/core": "1.15.21",
+    "@swc/core": "1.15.24",
     "@swc/jest": "0.2.39",
     "@testing-library/dom": "10.4.1",
     "@types/debug": "^4.1.12",
@@ -94,12 +94,11 @@
     "@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": "10.2.0",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "4.4.4",
     "eslint-plugin-etc": "2.0.3",
@@ -127,12 +126,11 @@
     "@apidevtools/json-schema-ref-parser": "13.0.5",
     "@hapi/accept": "6.0.3",
     "@types/json-schema": "7.0.15",
+    "ajv": "8.18.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",
     "js-yaml": "4.1.1",
     "json-schema-faker": "0.6.0",
@@ -141,12 +139,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",

package/dist/client/README.md

@@ -1,14 +0,0 @@
-# `src/client/` — Built-in UI Templates
-
-This directory contains [Handlebars](https://handlebarsjs.com/) (`.hbs`) templates that are rendered by `page-middleware.ts` to produce the browser-facing pages bundled with Counterfact.
-
-## Files
-
-| File | Description |
-|---|---|
-| `index.html.hbs` | Template for the Counterfact dashboard (`/counterfact/`); lists registered routes and shows server status |
-| `rapi-doc.html.hbs` | Template for the interactive API documentation page (`/counterfact/swagger/`); embeds the [RapiDoc](https://rapidocweb.com/) viewer and adds VSCode "open file" links |
-
-## How It Works
-
-When a request arrives for `/counterfact/` or `/counterfact/swagger/`, `page-middleware.ts` compiles the appropriate template with runtime data (routes, port, base path, etc.) and sends the resulting HTML to the browser. No build step is required; templates are rendered on the fly.