counterfact 2.7.0 → 2.9.0

package/dist/repl/repl.js

@@ -15,61 +15,125 @@ const ROUTE_BUILDER_METHODS = [
     "ready(",
     "send(",
 ];
+function getScenarioCompletions(line, scenarioRegistry, groupedScenarioRegistries) {
+    function getPathCompletions(partial, registry) {
+        if (registry === undefined) {
+            return [[], partial];
+        }
+        const slashIdx = partial.lastIndexOf("/");
+        if (slashIdx === -1) {
+            const indexFunctions = registry.getExportedFunctionNames("index");
+            const fileKeys = registry.getFileKeys().filter((k) => k !== "index");
+            const topLevelPrefixes = [
+                ...new Set(fileKeys.map((k) => k.split("/")[0] + "/")),
+            ];
+            const allOptions = [...indexFunctions, ...topLevelPrefixes];
+            const matches = allOptions.filter((c) => c.startsWith(partial));
+            return [matches, partial];
+        }
+        const fileKey = partial.slice(0, slashIdx);
+        const funcPartial = partial.slice(slashIdx + 1);
+        const functions = registry.getExportedFunctionNames(fileKey);
+        const matches = functions
+            .filter((e) => e.startsWith(funcPartial))
+            .map((e) => `${fileKey}/${e}`);
+        return [matches, partial];
+    }
+    if (groupedScenarioRegistries !== undefined) {
+        if (!/^\.scenario(?:\s|$)/u.test(line)) {
+            return undefined;
+        }
+        const hasTrailingWhitespace = /\s$/u.test(line);
+        const args = line.trim().split(/\s+/u).slice(1);
+        const groupKeys = Object.keys(groupedScenarioRegistries);
+        if (args.length === 0) {
+            return [groupKeys, ""];
+        }
+        if (args.length === 1 && !hasTrailingWhitespace) {
+            const groupPartial = args[0] ?? "";
+            const matches = groupKeys.filter((key) => key.startsWith(groupPartial));
+            return [matches, groupPartial];
+        }
+        const selectedGroup = args[0] ?? "";
+        const selectedRegistry = groupedScenarioRegistries[selectedGroup];
+        if (selectedRegistry === undefined) {
+            const scenarioPartial = hasTrailingWhitespace
+                ? ""
+                : (args[args.length - 1] ?? "");
+            return [[], scenarioPartial];
+        }
+        if (args.length === 1 && hasTrailingWhitespace) {
+            return getPathCompletions("", selectedRegistry);
+        }
+        if (args.length === 2 && !hasTrailingWhitespace) {
+            const scenarioPartial = args[1];
+            if (scenarioPartial === undefined) {
+                return [[], ""];
+            }
+            return getPathCompletions(scenarioPartial, selectedRegistry);
+        }
+        // More than two args (or trailing whitespace after the second arg) means
+        // no additional `.scenario` arguments are valid in multi-API mode.
+        return [[], args[args.length - 1] ?? ""];
+    }
+    const applyMatch = line.match(/^\.scenario\s+(?<partial>\S*)$/u);
+    if (!applyMatch) {
+        return undefined;
+    }
+    const partial = applyMatch.groups?.["partial"] ?? "";
+    return getPathCompletions(partial, scenarioRegistry);
+}
+function getRouteBuilderMethodCompletions(line) {
+    const builderMatch = line.match(/route\(.*\)\.(?<partial>[a-zA-Z]*)$/u);
+    if (!builderMatch) {
+        return undefined;
+    }
+    const partial = builderMatch.groups?.["partial"] ?? "";
+    const matches = ROUTE_BUILDER_METHODS.filter((m) => m.startsWith(partial));
+    return [matches, partial];
+}
+function getRoutesForCompletion(registry, openApiDocument) {
+    const openApiPaths = openApiDocument
+        ? Object.keys(openApiDocument.paths)
+        : [];
+    if (openApiPaths.length > 0) {
+        return openApiPaths;
+    }
+    return registry.routes.map((route) => route.path);
+}
+function getRouteCompletions(line, routes) {
+    const routeMatch = line.match(/(?:client\.(?:get|post|put|patch|delete)|route)\("(?<partial>[^"]*)$/u);
+    if (!routeMatch) {
+        return undefined;
+    }
+    const partial = routeMatch.groups?.["partial"] ?? "";
+    const matches = routes.filter((route) => route.startsWith(partial));
+    return [matches, partial];
+}
 /**
  * Creates a tab-completion function for the REPL.
  *
  * @param registry - The route registry used to complete path arguments for `route()` and `client.*()` calls.
  * @param fallback - Optional fallback completer (e.g. the Node.js built-in completer) invoked when no custom completion matches.
- * @param scenarioRegistry - When provided, enables tab completion for `.apply` commands by enumerating
+ * @param openApiDocument - Optional OpenAPI document used as the source of route completions when available.
+ * @param scenarioRegistry - When provided, enables tab completion for `.scenario` commands by enumerating
  *   exported function names and file-key prefixes from the loaded scenario modules.
  */
-export function createCompleter(registry, fallback, scenarioRegistry) {
+export function createCompleter(registry, fallback, openApiDocument, scenarioRegistry, groupedScenarioRegistries) {
+    const routes = getRoutesForCompletion(registry, openApiDocument);
     return (line, callback) => {
-        // Check for .apply completion: .apply <partial>
-        const applyMatch = line.match(/^\.apply\s+(?<partial>\S*)$/u);
-        if (applyMatch) {
-            const partial = applyMatch.groups?.["partial"] ?? "";
-            if (scenarioRegistry !== undefined) {
-                const slashIdx = partial.lastIndexOf("/");
-                if (slashIdx === -1) {
-                    // No slash: complete exports from "index" key + top-level file prefixes
-                    const indexFunctions = scenarioRegistry.getExportedFunctionNames("index");
-                    const fileKeys = scenarioRegistry
-                        .getFileKeys()
-                        .filter((k) => k !== "index");
-                    const topLevelPrefixes = [
-                        ...new Set(fileKeys.map((k) => k.split("/")[0] + "/")),
-                    ];
-                    const allOptions = [...indexFunctions, ...topLevelPrefixes];
-                    const matches = allOptions.filter((c) => c.startsWith(partial));
-                    callback(null, [matches, partial]);
-                }
-                else {
-                    // Has slash: complete exports from the named file key
-                    const fileKey = partial.slice(0, slashIdx);
-                    const funcPartial = partial.slice(slashIdx + 1);
-                    const functions = scenarioRegistry.getExportedFunctionNames(fileKey);
-                    const matches = functions
-                        .filter((e) => e.startsWith(funcPartial))
-                        .map((e) => `${fileKey}/${e}`);
-                    callback(null, [matches, partial]);
-                }
-            }
-            else {
-                callback(null, [[], partial]);
-            }
+        const scenarioCompletions = getScenarioCompletions(line, scenarioRegistry, groupedScenarioRegistries);
+        if (scenarioCompletions !== undefined) {
+            callback(null, scenarioCompletions);
             return;
         }
-        // Check for RouteBuilder method completion: route("..."). or chained calls
-        const builderMatch = line.match(/route\(.*\)\.(?<partial>[a-zA-Z]*)$/u);
-        if (builderMatch) {
-            const partial = builderMatch.groups?.["partial"] ?? "";
-            const matches = ROUTE_BUILDER_METHODS.filter((m) => m.startsWith(partial));
-            callback(null, [matches, partial]);
+        const routeBuilderCompletions = getRouteBuilderMethodCompletions(line);
+        if (routeBuilderCompletions !== undefined) {
+            callback(null, routeBuilderCompletions);
             return;
         }
-        const match = line.match(/(?:client\.(?:get|post|put|patch|delete)|route)\("(?<partial>[^"]*)$/u);
-        if (!match) {
+        const routeCompletions = getRouteCompletions(line, routes);
+        if (routeCompletions === undefined) {
             if (fallback) {
                 fallback(line, callback);
             }
@@ -78,13 +142,74 @@ export function createCompleter(registry, fallback, scenarioRegistry) {
             }
             return;
         }
-        const partial = match.groups?.["partial"] ?? "";
-        const routes = registry.routes.map((route) => route.path);
-        const matches = routes.filter((route) => route.startsWith(partial));
-        callback(null, [matches, partial]);
+        callback(null, routeCompletions);
     };
 }
-export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry) {
+/**
+ * Launches the interactive Counterfact REPL.
+ *
+ * The REPL is a standard Node.js REPL augmented with:
+ * - `context` / `loadContext(path)` globals wired to the {@link ContextRegistry}.
+ * - `client` — a {@link RawHttpClient} pre-configured for `localhost`.
+ * - `route(path)` — creates a {@link RouteBuilder} for the given path.
+ * - `.counterfact` — help command.
+ * - `.proxy` — proxy configuration command.
+ * - `.scenario` — runs a named scenario function from the scenarios directory.
+ *
+ * @param contextRegistry - The live context registry.
+ * @param registry - The route registry (used for tab completion).
+ * @param config - Server configuration.
+ * @param print - Output function; defaults to writing to `stdout`.
+ * @param openApiDocument - Optional OpenAPI document for tab completion.
+ * @param scenarioRegistry - Optional scenario registry for `.scenario` support.
+ * @returns The configured Node.js REPL server instance.
+ */
+export function startRepl(contextRegistry, registry, config, print = printToStdout, openApiDocument, scenarioRegistry, apiBindings) {
+    const bindings = apiBindings === undefined || apiBindings.length === 0
+        ? [
+            {
+                contextRegistry,
+                group: "",
+                openApiDocument,
+                registry,
+                scenarioRegistry,
+            },
+        ]
+        : apiBindings;
+    const isMultiApi = bindings.length > 1;
+    const groupedBindings = bindings.map((binding) => ({
+        ...binding,
+        key: binding.group.trim(),
+    }));
+    if (isMultiApi) {
+        const invalidBindings = groupedBindings.filter((binding) => binding.key === "");
+        if (invalidBindings.length > 0) {
+            throw new Error("Each API binding must define a non-empty group when multiple APIs are configured.");
+        }
+        const seenGroups = new Set();
+        const duplicateGroups = new Set();
+        for (const binding of groupedBindings) {
+            if (seenGroups.has(binding.key)) {
+                duplicateGroups.add(binding.key);
+            }
+            seenGroups.add(binding.key);
+        }
+        if (duplicateGroups.size > 0) {
+            throw new Error(`Duplicate API groups are not allowed when multiple APIs are configured (duplicate groups: ${[...duplicateGroups].join(", ")}).`);
+        }
+    }
+    const rootBinding = groupedBindings[0];
+    if (rootBinding === undefined) {
+        throw new Error("startRepl requires at least one API binding");
+    }
+    const groupedLoadContext = Object.fromEntries(groupedBindings.map((binding) => [
+        binding.key,
+        (path) => binding.contextRegistry.find(path),
+    ]));
+    const groupedRoute = Object.fromEntries(groupedBindings.map((binding) => [
+        binding.key,
+        createRouteFunction(config.port, "localhost", binding.openApiDocument),
+    ]));
     function printProxyStatus() {
         if (config.proxyUrl === "") {
             print("The proxy URL is not set.");
@@ -123,12 +248,17 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         }
     }
     const replServer = repl.start({
-        prompt: "⬣> ",
+        prompt: "\x1b[38;2;0;113;181m⬣> \x1b[0m",
     });
     const builtinCompleter = replServer.completer;
     // completer is typed as readonly in @types/node but is writable at runtime
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    replServer.completer = createCompleter(registry, builtinCompleter, scenarioRegistry);
+    replServer.completer = createCompleter(rootBinding.registry, builtinCompleter, rootBinding.openApiDocument, rootBinding.scenarioRegistry, isMultiApi
+        ? Object.fromEntries(groupedBindings.map((binding) => [
+            binding.key,
+            binding.scenarioRegistry,
+        ]))
+        : undefined);
     replServer.defineCommand("counterfact", {
         action() {
             print("This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.");
@@ -167,17 +297,63 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
         },
         help: 'proxy configuration (".proxy help" for details)',
     });
-    replServer.context.loadContext = (path) => contextRegistry.find(path);
-    replServer.context.context = replServer.context.loadContext("/");
+    replServer.context.loadContext = isMultiApi
+        ? groupedLoadContext
+        : groupedLoadContext[rootBinding.key];
+    replServer.context.context = isMultiApi
+        ? Object.fromEntries(groupedBindings.map((binding) => [
+            binding.key,
+            binding.contextRegistry.find("/"),
+        ]))
+        : rootBinding.contextRegistry.find("/");
     replServer.context.client = new RawHttpClient("localhost", config.port);
     replServer.context.RawHttpClient = RawHttpClient;
-    replServer.context.route = createRouteFunction(config.port, "localhost", openApiDocument);
-    replServer.context.routes = {};
-    replServer.defineCommand("apply", {
+    replServer.context.route = isMultiApi
+        ? groupedRoute
+        : groupedRoute[rootBinding.key];
+    replServer.context.routes = isMultiApi
+        ? Object.fromEntries(groupedBindings.map((binding) => [binding.key, {}]))
+        : {};
+    replServer.defineCommand("scenario", {
         async action(text) {
-            const parts = text.trim().split("/").filter(Boolean);
+            const trimmedText = text.trim();
+            const parsedArgs = trimmedText.split(/\s+/u).filter(Boolean);
+            const usage = isMultiApi
+                ? "usage: .scenario <group> <path>"
+                : "usage: .scenario <path>";
+            const { selectedBinding, scenarioPath } = (() => {
+                if (!isMultiApi) {
+                    if (trimmedText === "") {
+                        return { scenarioPath: undefined, selectedBinding: undefined };
+                    }
+                    return { scenarioPath: trimmedText, selectedBinding: rootBinding };
+                }
+                if (parsedArgs.length !== 2) {
+                    return { scenarioPath: undefined, selectedBinding: undefined };
+                }
+                return {
+                    scenarioPath: parsedArgs[1],
+                    selectedBinding: groupedBindings.find((binding) => binding.key === parsedArgs[0]),
+                };
+            })();
+            if (selectedBinding === undefined || scenarioPath === undefined) {
+                if (isMultiApi &&
+                    scenarioPath !== undefined &&
+                    selectedBinding === undefined) {
+                    const groupName = parsedArgs[0] ?? "";
+                    const availableGroups = groupedBindings.map((binding) => binding.key);
+                    print(`Error: Unknown API group "${groupName}". Available groups: ${availableGroups.join(", ")}`);
+                }
+                else {
+                    print(usage);
+                }
+                this.clearBufferedCommand();
+                this.displayPrompt();
+                return;
+            }
+            const parts = scenarioPath.split("/").filter(Boolean);
             if (parts.length === 0) {
-                print("usage: .apply <path>");
+                print(usage);
                 this.clearBufferedCommand();
                 this.displayPrompt();
                 return;
@@ -190,7 +366,7 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             }
             const functionName = parts[parts.length - 1] ?? "";
             const fileKey = parts.length === 1 ? "index" : parts.slice(0, -1).join("/");
-            const module = scenarioRegistry?.getModule(fileKey);
+            const module = selectedBinding.scenarioRegistry?.getModule(fileKey);
             if (module === undefined) {
                 print(`Error: Could not find scenario file "${fileKey}"`);
                 this.clearBufferedCommand();
@@ -205,11 +381,20 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
                 return;
             }
             try {
+                const selectedRoutes = isMultiApi
+                    ? replServer.context["routes"][selectedBinding.key]
+                    : replServer.context["routes"];
+                if (isMultiApi && selectedRoutes === undefined) {
+                    print(`Error: Could not resolve routes for API group "${selectedBinding.key}"`);
+                    this.clearBufferedCommand();
+                    this.displayPrompt();
+                    return;
+                }
                 const applyContext = {
-                    context: replServer.context["context"],
-                    loadContext: replServer.context["loadContext"],
-                    route: replServer.context["route"],
-                    routes: replServer.context["routes"],
+                    context: selectedBinding.contextRegistry.find("/"),
+                    loadContext: ((path) => selectedBinding.contextRegistry.find(path)),
+                    route: groupedRoute[selectedBinding.key],
+                    routes: selectedRoutes,
                 };
                 await fn(applyContext);
                 print(`Applied ${text.trim()}`);
@@ -220,7 +405,9 @@ export function startRepl(contextRegistry, registry, config, print = printToStdo
             this.clearBufferedCommand();
             this.displayPrompt();
         },
-        help: 'apply a scenario script (".apply <path>" calls the named export from scenarios/)',
+        help: isMultiApi
+            ? 'apply a scenario script (".scenario <group> <path>" calls the named export from that group\'s scenarios/)'
+            : 'apply a scenario script (".scenario <path>" calls the named export from scenarios/)',
     });
     return replServer;
 }

package/dist/repl/route-builder.js

@@ -1,4 +1,17 @@
 import { RawHttpClient } from "./raw-http-client.js";
+/**
+ * Immutable fluent builder for constructing and sending HTTP requests from the
+ * Counterfact REPL.
+ *
+ * Each builder method returns a **new** `RouteBuilder` instance with the
+ * updated field — the original is never mutated.  When all required parameters
+ * are set, call {@link send} to execute the request.
+ *
+ * ```ts
+ * // Inside the REPL:
+ * route("/pets/{petId}").method("get").path({ petId: 1 }).send();
+ * ```
+ */
 export class RouteBuilder {
     routePath;
     _body;
@@ -47,29 +60,63 @@ export class RouteBuilder {
             queryParams: overrides.queryParams ?? this._queryParams,
         });
     }
+    /**
+     * Returns a new builder with the HTTP method set.
+     *
+     * @param method - HTTP method name (case-insensitive, e.g. `"get"`, `"POST"`).
+     */
     method(method) {
         return this.clone({ method: method.toUpperCase() });
     }
+    /**
+     * Returns a new builder with additional path parameters merged in.
+     *
+     * @param params - Key/value map of path variable names to values.
+     */
     path(params) {
         return this.clone({ pathParams: { ...this._pathParams, ...params } });
     }
+    /**
+     * Returns a new builder with additional query parameters merged in.
+     *
+     * @param params - Key/value map of query parameter names to values.
+     */
     query(params) {
         return this.clone({ queryParams: { ...this._queryParams, ...params } });
     }
+    /**
+     * Returns a new builder with additional request headers merged in.
+     *
+     * @param params - Key/value map of header names to values.
+     */
     headers(params) {
         return this.clone({ headerParams: { ...this._headerParams, ...params } });
     }
+    /**
+     * Returns a new builder with the request body set.
+     *
+     * @param body - The request body (will be serialised to JSON or sent as-is).
+     */
     body(body) {
         return this.clone({ body });
     }
     getOperation() {
         return this._operation;
     }
+    /**
+     * Returns `true` when a method is set and no required parameters are
+     * missing.
+     */
     ready() {
         if (!this._method)
             return false;
         return this.missing() === undefined;
     }
+    /**
+     * Returns a {@link MissingParams} object describing all required parameters
+     * that have not yet been set, or `undefined` when nothing is missing (or
+     * when the operation has no parameters).
+     */
     missing() {
         const operation = this.getOperation();
         if (!operation?.parameters)
@@ -98,6 +145,10 @@ export class RouteBuilder {
             return undefined;
         return missingParams;
     }
+    /**
+     * Returns a human-readable help string describing the operation, its
+     * parameters, and the expected responses.
+     */
     help() {
         const method = this._method ?? "[no method set]";
         const operation = this.getOperation();
@@ -168,6 +219,13 @@ export class RouteBuilder {
         }
         return lines.join("\n");
     }
+    /**
+     * Executes the HTTP request and returns the parsed response body.
+     *
+     * @throws When no HTTP method has been set.
+     * @throws When required parameters are missing.
+     * @throws When an unsupported HTTP method is used.
+     */
     async send() {
         if (!this._method) {
             throw new Error('No HTTP method set. Use .method("get") to set the method.');
@@ -265,6 +323,16 @@ export class RouteBuilder {
         return lines.join("\n");
     }
 }
+/**
+ * Creates a factory function that constructs a {@link RouteBuilder} for a
+ * given route path, pre-configured with the server's host, port, and OpenAPI
+ * document.
+ *
+ * @param port - The port the Counterfact server is listening on.
+ * @param host - The server hostname (default `"localhost"`).
+ * @param openApiDocument - Optional OpenAPI document for parameter introspection.
+ * @returns A function `(routePath: string) => RouteBuilder`.
+ */
 export function createRouteFunction(port, host, openApiDocument) {
     return (routePath) => new RouteBuilder(routePath, { host, openApiDocument, port });
 }

package/dist/server/constants.js

@@ -1,3 +1,11 @@
+/**
+ * Default options passed to every chokidar watcher in Counterfact.
+ *
+ * - `ignoreInitial: true` — suppresses the initial `"add"` events emitted for
+ *   files already present when the watcher starts.
+ * - `usePolling: true` on Windows — chokidar's native FSEvents are unreliable
+ *   on Windows; polling is more reliable there.
+ */
 export const CHOKIDAR_OPTIONS = {
     ignoreInitial: true,
     usePolling: process.platform === "win32",

package/dist/server/context-registry.js

@@ -1,6 +1,19 @@
+/**
+ * A context object that lives at a specific route path and is shared across
+ * all requests to that path (and its descendants).
+ *
+ * Route handlers receive this object as `$.context` and may freely add or
+ * modify properties to maintain state between requests.
+ */
 export class Context {
     constructor() { }
 }
+/**
+ * Returns the parent path of a route path by stripping the last segment.
+ *
+ * @param path - A route path such as `"/pets/1"`.
+ * @returns The parent path (e.g. `"/pets"`), or `"/"` for top-level paths.
+ */
 export function parentPath(path) {
     return String(path.split("/").slice(0, -1).join("/")) || "/";
 }
@@ -29,6 +42,19 @@ function cloneForCache(value) {
     }
     return clone;
 }
+/**
+ * Registry of per-path {@link Context} objects that persist state across
+ * requests.
+ *
+ * The registry is case-insensitive for path lookups and uses a write-through
+ * cache to detect which context properties have changed between hot-reloads.
+ * It extends {@link EventTarget} so that listeners can react to structural
+ * changes (e.g. to regenerate type files):
+ *
+ * ```ts
+ * contextRegistry.addEventListener("context-changed", () => { ... });
+ * ```
+ */
 export class ContextRegistry extends EventTarget {
     entries = new Map();
     cache = new Map();
@@ -46,6 +72,13 @@ export class ContextRegistry extends EventTarget {
         }
         return undefined;
     }
+    /**
+     * Registers a new context for `path`, replacing any existing one, and
+     * dispatches a `"context-changed"` event so listeners can react.
+     *
+     * @param path - The route path (e.g. `"/pets"`).
+     * @param context - The context object to store.
+     */
     add(path, context) {
         this.entries.set(path, context);
         this.cache.set(path, cloneForCache(context));
@@ -53,7 +86,7 @@ export class ContextRegistry extends EventTarget {
     }
     /**
      * Removes the context entry for the given path and dispatches a
-     * "context-changed" event so that listeners (e.g. the scenario-context type
+     * "context-changed" event so that listeners (e.g. the _.context type
      * generator) can regenerate type files in response to the removal.
      *
      * @param path - The route path whose context entry should be deleted
@@ -65,10 +98,28 @@ export class ContextRegistry extends EventTarget {
         this.seen.delete(path);
         this.dispatchEvent(new Event("context-changed"));
     }
+    /**
+     * Finds the context for `path`, walking up the path hierarchy until a
+     * context is found.  Falls back to `"/"` which always has a context.
+     *
+     * @param path - The route path to look up.
+     * @returns The nearest ancestor context (or the root context).
+     */
     find(path) {
         return (this.getContextIgnoreCase(this.entries, path) ??
             this.find(parentPath(path)));
     }
+    /**
+     * Merges `updatedContext` into the existing context for `path`.
+     *
+     * On the first call for a path the context is added directly.  On subsequent
+     * calls only properties whose values differ from the cached snapshot are
+     * applied, preserving live mutations made by route handlers between reloads.
+     *
+     * @param path - The route path (e.g. `"/pets"`).
+     * @param updatedContext - The new context instance (typically freshly
+     *   constructed from the reloaded `_.context.ts` file).
+     */
     update(path, updatedContext) {
         if (updatedContext === undefined) {
             return;
@@ -87,9 +138,11 @@ export class ContextRegistry extends EventTarget {
         Object.setPrototypeOf(context, Object.getPrototypeOf(updatedContext));
         this.cache.set(path, cloneForCache(updatedContext));
     }
+    /** Returns all registered route paths as an array. */
     getAllPaths() {
         return Array.from(this.entries.keys());
     }
+    /** Returns a plain object mapping every registered path to its context. */
     getAllContexts() {
         const result = {};
         for (const [path, context] of this.entries.entries()) {

package/dist/server/determine-module-kind.js

@@ -1,7 +1,21 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- module kind detection only probes package.json while walking parent directories. */
 const DEFAULT_MODULE_KIND = "commonjs";
+/**
+ * Determines whether a module file should be treated as CommonJS or ESM.
+ *
+ * Resolution order (matches Node.js conventions):
+ * 1. `.cjs` extension → `"commonjs"`.
+ * 2. `.mjs` or `.ts` extension → `"module"`.
+ * 3. Walk up the directory tree looking for a `package.json` with a `"type"`
+ *    field.
+ * 4. Falls back to `"commonjs"` at the filesystem root.
+ *
+ * @param modulePath - Absolute or relative path to the module file.
+ * @returns `"commonjs"` or `"module"`.
+ */
 export async function determineModuleKind(modulePath) {
     if (modulePath.endsWith(".cjs")) {
         return "commonjs";