counterfact 2.6.0 → 2.8.1

package/dist/typescript-generator/requirement.js

@@ -1,3 +1,11 @@
+/**
+ * A node in the dereferenced OpenAPI spec tree.
+ *
+ * A `Requirement` wraps a raw JSON object (`data`) together with its location
+ * (`url`, a JSON Pointer) and a back-reference to the owning
+ * {@link Specification}.  Navigation methods (`get`, `select`, `find`, …)
+ * transparently follow `$ref` pointers.
+ */
 export class Requirement {
     data;
     url;
@@ -7,18 +15,36 @@ export class Requirement {
         this.url = url;
         this.specification = specification;
     }
+    /** `true` when this node is a JSON Reference (`$ref`) rather than inline data. */
     get isReference() {
         return this.data["$ref"] !== undefined;
     }
+    /**
+     * Resolves the `$ref` and returns the target {@link Requirement}.
+     *
+     * @throws When `isReference` is `false` or the specification is not set.
+     */
     reference() {
         return this.specification.getRequirement(this.data["$ref"]);
     }
+    /**
+     * Returns `true` when this node has a child property named `item`.
+     *
+     * Transparently follows `$ref` references.
+     *
+     * @param item - The property key to check.
+     */
     has(item) {
         if (this.isReference) {
             return this.reference().has(item);
         }
         return item in this.data;
     }
+    /**
+     * Returns the child {@link Requirement} for `item`, or `undefined`.
+     *
+     * @param item - The property key (string) or array index (number).
+     */
     get(item) {
         if (this.isReference) {
             return this.reference().get(item);
@@ -29,6 +55,16 @@ export class Requirement {
         }
         return new Requirement(this.data[key], `${this.url}/${this.escapeJsonPointer(key)}`, this.specification);
     }
+    /**
+     * Navigates to a descendant node using a slash-delimited JSON Pointer path.
+     *
+     * Tilde-escaped characters (`~0` → `~`, `~1` → `/`) and percent-encoded
+     * characters are unescaped during traversal.
+     *
+     * @param path - A slash-delimited path (e.g. `"responses/200/content"`).
+     * @returns The target {@link Requirement}, or `undefined` if the path does
+     *   not exist.
+     */
     select(path) {
         const parts = path
             .split("/")
@@ -36,7 +72,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) {
@@ -47,19 +90,42 @@ export class Requirement {
         }
         return result;
     }
+    /**
+     * Iterates over all child properties and calls `callback` with each child
+     * requirement and its key.
+     *
+     * @param callback - Called for each child with `(child, key)`.
+     */
     forEach(callback) {
         Object.keys(this.data).forEach((key) => {
             callback(this.select(this.escapeJsonPointer(key)), key);
         });
     }
+    /**
+     * Maps over all child properties and returns the collected results.
+     *
+     * @param callback - Transformation function called with `(child, key)`.
+     */
     map(callback) {
         const result = [];
         this.forEach((value, key) => result.push(callback(value, key)));
         return result;
     }
+    /**
+     * Maps and flattens over all child properties.
+     *
+     * @param callback - Transformation function that may return a value or an
+     *   array of values.
+     */
     flatMap(callback) {
         return this.map(callback).flat();
     }
+    /**
+     * Returns the first child for which `callback` returns `true`, or
+     * `undefined` when nothing matches.
+     *
+     * @param callback - Predicate called with `(child, key)`.
+     */
     find(callback) {
         let result;
         this.forEach((value, key) => {
@@ -69,11 +135,21 @@ export class Requirement {
         });
         return result;
     }
+    /**
+     * Escapes a JSON Pointer token: `~` → `~0`, `/` → `~1`.
+     *
+     * @param value - The token to escape.
+     */
     escapeJsonPointer(value) {
         if (typeof value !== "string")
             return value;
         return value.replaceAll("~", "~0").replaceAll("/", "~1");
     }
+    /**
+     * Unescapes a JSON Pointer token: `~1` → `/`, `~0` → `~`.
+     *
+     * @param pointer - The token to unescape.
+     */
     unescapeJsonPointer(pointer) {
         if (typeof pointer !== "string")
             return pointer;

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/scenario-file-generator.js

@@ -0,0 +1,235 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+import { watch } from "chokidar";
+import { CHOKIDAR_OPTIONS } from "../server/constants.js";
+import { pathRelative } from "../util/forward-slash-path.js";
+import { waitForEvent } from "../util/wait-for-event.js";
+async function collectContextFiles(destination) {
+    const routesDir = nodePath.join(destination, "routes");
+    const results = [];
+    if (!existsSync(routesDir)) {
+        return results;
+    }
+    await walkForContextFiles(routesDir, routesDir, results);
+    results.sort((a, b) => b.depth - a.depth);
+    return results;
+}
+async function walkForContextFiles(routesDir, currentDir, results) {
+    let entries;
+    try {
+        entries = await fs.readdir(currentDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            await walkForContextFiles(routesDir, nodePath.join(currentDir, entry.name), results);
+        }
+        else if (entry.name === "_.context.ts") {
+            const relDir = pathRelative(routesDir, currentDir);
+            const routePath = relDir === "" ? "/" : `/${relDir}`;
+            const depth = relDir === "" ? 0 : relDir.split("/").length;
+            const importPath = relDir === "" ? "../routes/_.context" : `../routes/${relDir}/_.context`;
+            const alias = routePathToAlias(routePath);
+            results.push({ importPath, alias, routePath, depth });
+        }
+    }
+}
+function routePathToAlias(routePath) {
+    if (routePath === "/") {
+        return "Context";
+    }
+    return (routePath
+        .split("/")
+        .filter(Boolean)
+        .map((seg) => seg
+        .replace(/\{(.+?)\}/g, (_match, name) => name.replace(/[^a-z0-9]/gi, " "))
+        .replace(/[-_\s]([a-z])/g, (_match, c) => c.toUpperCase())
+        .replace(/^[a-z]/, (c) => c.toUpperCase())
+        .replace(/[^a-z0-9]/gi, ""))
+        .join("") + "Context");
+}
+const PARAM_SEGMENT_REGEX = /^\{.+\}$/u;
+function buildLoadContextOverload(routePath, alias) {
+    if (routePath === "/") {
+        return '  loadContext(path: "/" | `/${string}`): ' + alias + ";";
+    }
+    const segments = routePath.split("/").filter(Boolean);
+    const hasParam = segments.some((seg) => PARAM_SEGMENT_REGEX.test(seg));
+    if (!hasParam) {
+        return `  loadContext(path: "${routePath}" | \`${routePath}/\${string}\`): ${alias};`;
+    }
+    const templatePath = `/${segments
+        .map((seg) => (PARAM_SEGMENT_REGEX.test(seg) ? "${string}" : seg))
+        .join("/")}`;
+    return `  loadContext(path: \`${templatePath}\`): ${alias};`;
+}
+function buildScenarioContextContent(contextFiles) {
+    const rootContext = contextFiles.find((f) => f.routePath === "/");
+    const contextType = rootContext
+        ? rootContext.alias
+        : "Record<string, unknown>";
+    const importLines = contextFiles.map(({ importPath, alias }) => alias === "Context"
+        ? `import type { Context } from "${importPath}";`
+        : `import type { Context as ${alias} } from "${importPath}";`);
+    const overloadLines = contextFiles.map(({ alias, routePath }) => buildLoadContextOverload(routePath, alias));
+    const parts = [
+        "// This file is generated by Counterfact. Do not edit manually.",
+        ...importLines,
+        "",
+        "interface LoadContextDefinitions {",
+        "  /* code generator adds additional signatures here */",
+        ...overloadLines,
+        "  loadContext(path: string): Record<string, unknown>;",
+        "}",
+        "",
+        "export interface Scenario$ {",
+        '  /** Root context, same as loadContext("/") */',
+        `  readonly context: ${contextType};`,
+        '  readonly loadContext: LoadContextDefinitions["loadContext"];',
+        "  /** Named route builders stored in the REPL execution context */",
+        "  readonly routes: Record<string, unknown>;",
+        "  /** Create a new route builder for a given path */",
+        "  readonly route: (path: string) => unknown;",
+        "}",
+        "",
+        "/** A scenario function that receives the live REPL environment */",
+        "export type Scenario = ($: Scenario$) => Promise<void> | void;",
+        "",
+        "/** Interface for Context objects defined in _.context.ts files */",
+        "export interface Context$ {",
+        "  /** Load a context object for a specific path */",
+        '  readonly loadContext: LoadContextDefinitions["loadContext"];',
+        "  /** Load a JSON file relative to this file's path */",
+        "  readonly readJson: (relativePath: string) => Promise<unknown>;",
+        "}",
+        "",
+    ];
+    return parts.join("\n");
+}
+/**
+ * Writes the `types/_.context.ts` file, which exports the
+ * `Scenario$` interface used to type scenario functions.
+ *
+ * The interface is generated from all `_.context.ts` files found under the
+ * `routes/` directory, providing strongly typed `loadContext()` overloads for
+ * every route path that has a context file.
+ *
+ * @param destination - Root output directory.
+ */
+async function writeScenarioContextType(destination) {
+    const typesDir = nodePath.join(destination, "types");
+    const filePath = nodePath.join(typesDir, "_.context.ts");
+    const contextFiles = await collectContextFiles(destination);
+    const content = buildScenarioContextContent(contextFiles);
+    await fs.mkdir(typesDir, { recursive: true });
+    await fs.writeFile(filePath, content, "utf8");
+}
+const DEFAULT_SCENARIOS_INDEX = `import type { Scenario } from "../types/_.context.js";
+
+/**
+ * Scenario scripts are plain TypeScript functions that receive the live REPL
+ * environment and can read or mutate server state. Run them from the REPL with:
+ *   .scenario <functionName>
+ */
+
+/**
+ * Read or mutate the root context (same object routes see as $.context):
+ *   $.context.<property> = <value>;
+ *
+ * Load a context for a specific path:
+ *   const petsCtx = $.loadContext("/pets");
+ *
+ * Store a pre-configured route builder for later use in the REPL:
+ *   $.routes.myRequest = $.route("/pets").method("get");
+ */
+
+/**
+ * startup() runs automatically when the server initializes, right before the
+ * REPL starts. Use it to seed dummy data so the server is ready to use
+ * immediately. It receives the same $ argument as all other scenario functions.
+ *
+ * Tip: delegate to other scenario functions and pass $ along so each function
+ * stays focused on a single concern. You can also pass additional arguments to
+ * configure them, e.g. addPets($, 20, "dog").
+ *
+ * If you don't need a startup scenario, delete this function or leave it empty.
+ */
+export const startup: Scenario = ($) => {
+  void $;
+};
+
+/**
+ * An example scenario. To use it in the REPL, type:
+ *   .scenario help
+ */
+export const help: Scenario = ($) => {
+  void $;
+
+  console.log(
+    [
+      "Scenarios are functions that populate the context object",
+      "and / or the REPL environment. They are intended to",
+      "populate your environment with specific data and",
+      "configurations for testing purposes.",
+    ].join("\\n"),
+  );
+
+  console.log(
+    "\\nScenarios (including this one) are defined in the ./scenarios directory.",
+  );
+};
+`;
+async function writeDefaultScenariosIndex(destination) {
+    const scenariosDir = nodePath.join(destination, "scenarios");
+    const filePath = nodePath.join(scenariosDir, "index.ts");
+    if (existsSync(filePath)) {
+        return;
+    }
+    await fs.mkdir(scenariosDir, { recursive: true });
+    await fs.writeFile(filePath, DEFAULT_SCENARIOS_INDEX, "utf8");
+}
+/**
+ * Encapsulates the generation of scenario-related files:
+ * - `types/_.context.ts` — the typed `Scenario$` interface derived from all
+ *   `_.context.ts` files found under `routes/`.
+ * - `scenarios/index.ts` — the default scenarios entry-point (created only if
+ *   it does not already exist).
+ *
+ * When {@link watch} is called, a file-system watcher monitors the `routes/`
+ * directory for changes to `_.context.ts` files and automatically regenerates
+ * `types/_.context.ts`.
+ */
+export class ScenarioFileGenerator {
+    destination;
+    watcher;
+    constructor(destination) {
+        this.destination = destination;
+    }
+    /** Generates both scenario-related files once and resolves when complete. */
+    async generate() {
+        await writeScenarioContextType(this.destination);
+        await writeDefaultScenariosIndex(this.destination);
+    }
+    /**
+     * Starts watching the `routes/` directory for `_.context.ts` changes and
+     * regenerates `types/_.context.ts` on every change.
+     *
+     * Resolves once the watcher is ready.
+     */
+    async watch() {
+        const routesDir = nodePath.join(this.destination, "routes");
+        this.watcher = watch(routesDir, CHOKIDAR_OPTIONS).on("all", (_event, filePath) => {
+            if (filePath.endsWith("_.context.ts")) {
+                void writeScenarioContextType(this.destination);
+            }
+        });
+        await waitForEvent(this.watcher, "ready");
+    }
+    /** Closes the file-system watcher. */
+    async stopWatching() {
+        await this.watcher?.close();
+    }
+}

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,12 @@
 import fs from "node:fs";
 import nodePath from "node:path";
+/**
+ * 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 {