counterfact 2.7.0 → 2.8.1

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/create-koa-app.js

@@ -3,11 +3,35 @@ import Koa from "koa";
 import bodyParser from "koa-bodyparser";
 import { koaSwagger } from "koa2-swagger-ui";
 import { adminApiMiddleware } from "./admin-api-middleware.js";
+import { routesMiddleware } from "./koa-middleware.js";
 import { openapiMiddleware } from "./openapi-middleware.js";
 const debug = createDebug("counterfact:server:create-koa-app");
-export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
+/**
+ * Builds and configures the Koa application with all built-in middleware.
+ *
+ * The middleware stack (in order) is:
+ * 1. OpenAPI document serving at `/counterfact/openapi`
+ * 2. Swagger UI at `/counterfact/swagger`
+ * 3. Admin API (when `config.startAdminApi` is `true`) at `/_counterfact/api/`
+ * 4. Redirect `/counterfact` → `/counterfact/swagger`
+ * 5. Body parser
+ * 6. JSON serialisation of object bodies
+ * 7. Route-dispatching middleware
+ *
+ * @param config - Server configuration.
+ * @param dispatcher - The Dispatcher used to build the route-dispatching middleware.
+ * @param registry - The route Registry used to build the admin API middleware.
+ * @param contextRegistry - The ContextRegistry used to build the admin API middleware.
+ * @returns A configured Koa application (not yet listening).
+ */
+export function createKoaApp({ config, contextRegistry, dispatcher, registry, }) {
     const app = new Koa();
-    app.use(openapiMiddleware(config.openApiPath, `//localhost:${config.port}${config.routePrefix}`));
+    app.use(openapiMiddleware([
+        {
+            path: config.openApiPath,
+            baseUrl: `//localhost:${config.port}${config.routePrefix}`,
+        },
+    ]));
     app.use(koaSwagger({
         routePrefix: "/counterfact/swagger",
         swaggerOptions: {
@@ -18,7 +42,6 @@ export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
         app.use(adminApiMiddleware(registry, contextRegistry, config));
     }
     debug("basePath: %s", config.basePath);
-    debug("routes", registry.routes);
     app.use(async (ctx, next) => {
         if (ctx.URL.pathname === "/counterfact") {
             ctx.redirect("/counterfact/swagger");
@@ -37,6 +60,6 @@ export function createKoaApp(registry, koaMiddleware, config, contextRegistry) {
             ctx.type = "application/json";
         }
     });
-    app.use(koaMiddleware);
+    app.use(routesMiddleware(dispatcher, config));
     return app;
 }

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

@@ -2,6 +2,19 @@ import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 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";

package/dist/server/dispatcher.js

@@ -6,6 +6,15 @@ import { validateRequest } from "./request-validator.js";
 import { validateResponse } from "./response-validator.js";
 import { Tools } from "./tools.js";
 const debug = createDebugger("counterfact:server:dispatcher");
+/**
+ * Parses the `Cookie` request header into a key/value map.
+ *
+ * Duplicate keys are silently dropped (first occurrence wins) and values are
+ * percent-decoded where possible.
+ *
+ * @param cookieHeader - The raw `Cookie` header string.
+ * @returns A record mapping cookie name to decoded value.
+ */
 function parseCookies(cookieHeader) {
     const cookies = {};
     for (const part of cookieHeader.split(";")) {
@@ -27,6 +36,16 @@ function parseCookies(cookieHeader) {
     }
     return cookies;
 }
+/**
+ * Core HTTP request dispatcher.
+ *
+ * Receives incoming requests from the Koa middleware layer, matches them
+ * against the {@link Registry}, optionally validates the request and response
+ * against the OpenAPI spec, and invokes the matching route-handler function.
+ *
+ * Content-negotiation (Accept header handling) is performed before returning
+ * the response so the caller always receives the most appropriate content type.
+ */
 export class Dispatcher {
     registry;
     contextRegistry;
@@ -70,6 +89,14 @@ export class Dispatcher {
         }
         return undefined;
     }
+    /**
+     * Resolves the OpenAPI operation for `path` and `method`, merging any
+     * top-level `produces` array from the document root into the operation.
+     *
+     * @param path - The matched route path (e.g. `"/pets/{petId}"`).
+     * @param method - The HTTP method.
+     * @returns The {@link OpenApiOperation} if found, or `undefined`.
+     */
     operationForPathAndMethod(path, method) {
         const operation = this.findOperation(path, method);
         if (operation === undefined) {
@@ -108,6 +135,16 @@ export class Dispatcher {
                 "unknown/unknown",
         };
     }
+    /**
+     * Picks the best matching content entry from a multi-type response using the
+     * request's `Accept` header preferences.
+     *
+     * @param acceptHeader - The value of the `Accept` request header.
+     * @param content - Array of `{ type, body }` objects representing all
+     *   available content-type variants.
+     * @returns The first entry whose MIME type satisfies the accept preferences,
+     *   or `undefined` when none match.
+     */
     selectContent(acceptHeader, content) {
         const preferredMediaTypes = mediaTypes(acceptHeader);
         for (const mediaType of preferredMediaTypes) {
@@ -132,6 +169,15 @@ export class Dispatcher {
         }
         return false;
     }
+    /**
+     * Main request handler.
+     *
+     * Orchestrates base-path stripping, route matching, request validation,
+     * handler invocation, content negotiation, and response validation.
+     *
+     * @param request - The incoming request descriptor.
+     * @returns A promise that resolves to a {@link CounterfactResponseObject}.
+     */
     async request({ auth, body, headers = {}, method, path, query, rawBody, req, }) {
         debug(`request: ${method} ${path}`);
         debug(`headers: ${JSON.stringify(headers)}`);

package/dist/server/file-discovery.js

@@ -1,32 +1,43 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import nodePath from "node:path";
+import { toForwardSlashPath, pathJoin } from "../util/forward-slash-path.js";
 import { escapePathForWindows } from "../util/windows-escape.js";
 const JS_EXTENSIONS = new Set(["cjs", "cts", "js", "mjs", "mts", "ts"]);
+/**
+ * Recursively discovers JavaScript/TypeScript source files under a base
+ * directory.
+ *
+ * Only files with one of the following extensions are returned:
+ * `js`, `mjs`, `cjs`, `ts`, `mts`, `cts`.
+ */
 export class FileDiscovery {
     basePath;
     constructor(basePath) {
-        this.basePath = basePath.replaceAll("\\", "/");
+        this.basePath = toForwardSlashPath(basePath);
     }
+    /**
+     * Returns an array of absolute file paths for all JS/TS files found
+     * recursively under `basePath/directory`.
+     *
+     * @param directory - Sub-directory relative to `basePath` to start from.
+     *   Defaults to `""` (the base path itself).
+     * @throws When `basePath/directory` does not exist.
+     */
     async findFiles(directory = "") {
-        const fullDir = nodePath
-            .join(this.basePath, directory)
-            .replaceAll("\\", "/");
+        const fullDir = pathJoin(this.basePath, directory);
         if (!existsSync(fullDir)) {
             throw new Error(`Directory does not exist ${fullDir}`);
         }
         const entries = await fs.readdir(fullDir, { withFileTypes: true });
         const results = await Promise.all(entries.map(async (entry) => {
             if (entry.isDirectory()) {
-                return this.findFiles(nodePath.join(directory, entry.name).replaceAll("\\", "/"));
+                return this.findFiles(pathJoin(directory, entry.name));
             }
             const extension = entry.name.split(".").at(-1);
             if (!JS_EXTENSIONS.has(extension ?? "")) {
                 return [];
             }
-            const fullPath = nodePath
-                .join(this.basePath, directory, entry.name)
-                .replaceAll("\\", "/");
+            const fullPath = pathJoin(this.basePath, directory, entry.name);
             return [escapePathForWindows(fullPath)];
         }));
         return results.flat();

package/dist/server/is-proxy-enabled-for-path.js

@@ -1,3 +1,15 @@
+/**
+ * Determines whether a given request path should be forwarded to the upstream
+ * proxy.
+ *
+ * The check walks up the path hierarchy until it either finds an explicit
+ * `proxyPaths` entry or reaches the root (in which case the proxy is
+ * considered disabled).
+ *
+ * @param path - The request path to check (e.g. `"/pets/1"`).
+ * @param config - Object containing the `proxyPaths` map.
+ * @returns `true` when the request should be proxied.
+ */
 export function isProxyEnabledForPath(path, config) {
     if (config.proxyPaths.has(path)) {
         return config.proxyPaths.get(path) ?? false;

package/dist/server/json-to-xml.js

@@ -36,6 +36,16 @@ function objectToXml(json, schema, name) {
     });
     return `<${name}${attributes.join("")}>${String(xml.join(""))}</${name}>`;
 }
+/**
+ * Converts a JSON value to an XML string using optional OpenAPI `xml` schema
+ * hints (element names, attributes, wrapping).
+ *
+ * @param json - The value to serialise.
+ * @param schema - Optional JSON Schema with an `xml` hint block.
+ * @param keyName - Fallback XML element name when the schema does not provide
+ *   one.  Defaults to `"root"`.
+ * @returns A well-formed XML string.
+ */
 export function jsonToXml(json, schema, keyName = "root") {
     const name = schema?.xml?.name ?? keyName;
     if (Array.isArray(json)) {

package/dist/server/koa-middleware.js

@@ -40,7 +40,24 @@ function getAuthObject(ctx) {
     const [username, password] = user.split(":");
     return { password, username };
 }
-export function koaMiddleware(dispatcher, config, proxy = koaProxy) {
+/**
+ * Builds the Koa middleware function that bridges Koa's request context with
+ * the Counterfact {@link Dispatcher}.
+ *
+ * Responsibilities:
+ * - Respects `routePrefix` — requests outside the prefix are passed to `next`.
+ * - Adds CORS headers to every response.
+ * - Handles `OPTIONS` pre-flight requests (200 with CORS headers, no body).
+ * - Proxies the request upstream when proxy is enabled for the path.
+ * - Forwards the request to the dispatcher and maps the response back onto
+ *   the Koa context.
+ *
+ * @param dispatcher - The {@link Dispatcher} instance that handles requests.
+ * @param config - Server configuration (proxy settings, route prefix, etc.).
+ * @param proxy - Proxy factory; injectable for testing.
+ * @returns A Koa middleware function.
+ */
+export function routesMiddleware(dispatcher, config, proxy = koaProxy) {
     return async function middleware(ctx, next) {
         const { proxyUrl, routePrefix } = config;
         debug("middleware running for path: %s", ctx.request.path);

package/dist/server/load-openapi-document.js

@@ -1,13 +1,6 @@
-import { dereference } from "@apidevtools/json-schema-ref-parser";
-import createDebug from "debug";
-const debug = createDebug("counterfact:server:load-openapi-document");
+import { OpenApiDocument } from "./openapi-document.js";
 export async function loadOpenApiDocument(source) {
-    try {
-        return (await dereference(source));
-    }
-    catch (error) {
-        debug("could not load OpenAPI document from %s: %o", source, error);
-        const details = error instanceof Error ? error.message : String(error);
-        throw new Error(`Could not load the OpenAPI spec from "${source}".\n${details}`, { cause: error });
-    }
+    const document = new OpenApiDocument(source);
+    await document.load();
+    return document;
 }

package/dist/server/module-dependency-graph.js

@@ -2,6 +2,14 @@ import { dirname, resolve } from "node:path";
 import createDebug from "debug";
 import precinct from "precinct";
 const debug = createDebug("counterfact:server:module-dependency-graph");
+/**
+ * Tracks which route files depend on shared modules so that when a shared
+ * module changes, all dependent route files can be reloaded.
+ *
+ * Dependency edges are extracted using [precinct](https://npm.im/precinct)'s
+ * static analysis and are stored as a reverse map (`dependency → Set<dependent
+ * files>`).
+ */
 export class ModuleDependencyGraph {
     dependents = new Map();
     loadDependencies(path) {
@@ -18,6 +26,14 @@ export class ModuleDependencyGraph {
             group.delete(path);
         });
     }
+    /**
+     * (Re-)indexes the dependency edges for `path`, replacing any previously
+     * recorded edges.
+     *
+     * Only relative imports are tracked; node_modules dependencies are ignored.
+     *
+     * @param path - Absolute path of the file to analyse.
+     */
     load(path) {
         this.clearDependents(path);
         for (const dependency of this.loadDependencies(path)) {
@@ -31,6 +47,15 @@ export class ModuleDependencyGraph {
             this.dependents.get(key)?.add(path);
         }
     }
+    /**
+     * Returns the transitive set of files that (directly or indirectly) import
+     * `path`.
+     *
+     * Uses a BFS traversal so each dependent is returned exactly once.
+     *
+     * @param path - Absolute path of the changed dependency.
+     * @returns A `Set` of absolute paths of all dependent files.
+     */
     dependentsOf(path) {
         const marked = new Set();
         const dependents = new Set();

package/dist/server/module-loader.js

@@ -1,6 +1,6 @@
 import { once } from "node:events";
 import fs from "node:fs/promises";
-import nodePath, { basename, dirname } from "node:path";
+import nodePath, { basename } from "node:path";
 import { watch } from "chokidar";
 import createDebug from "debug";
 import { CHOKIDAR_OPTIONS } from "./constants.js";
@@ -10,9 +10,23 @@ import { FileDiscovery } from "./file-discovery.js";
 import { isContextModule, isMiddlewareModule, } from "./middleware-detector.js";
 import { ModuleDependencyGraph } from "./module-dependency-graph.js";
 import { uncachedImport } from "./uncached-import.js";
+import { toForwardSlashPath, pathDirname, pathRelative, } from "../util/forward-slash-path.js";
 import { unescapePathForWindows } from "../util/windows-escape.js";
 const { uncachedRequire } = await import("./uncached-require.cjs");
 const debug = createDebug("counterfact:server:module-loader");
+/**
+ * Watches the compiled routes directory and dynamically loads/reloads route
+ * modules, context files, and middleware as files are added, changed, or
+ * removed.
+ *
+ * Loaded modules are registered in the {@link Registry} (route handlers) or
+ * the {@link ContextRegistry} (context files).  An optional
+ * {@link ScenarioRegistry} receives scenario modules loaded from a separate
+ * `scenarios/` directory.
+ *
+ * Emits DOM-style events (`"add"`, `"remove"`) so callers can react to module
+ * lifecycle changes.
+ */
 export class ModuleLoader extends EventTarget {
     basePath;
     registry;
@@ -28,19 +42,29 @@ export class ModuleLoader extends EventTarget {
     };
     constructor(basePath, registry, contextRegistry = new ContextRegistry(), scenariosPath, scenarioRegistry) {
         super();
-        this.basePath = basePath.replaceAll("\\", "/");
+        this.basePath = toForwardSlashPath(basePath);
         this.registry = registry;
         this.contextRegistry = contextRegistry;
-        this.scenariosPath = scenariosPath?.replaceAll("\\", "/");
+        this.scenariosPath =
+            scenariosPath === undefined
+                ? undefined
+                : toForwardSlashPath(scenariosPath);
         this.scenarioRegistry = scenarioRegistry;
         this.fileDiscovery = new FileDiscovery(this.basePath);
     }
+    /**
+     * Starts watching the routes directory (and optionally the scenarios
+     * directory) for file-system changes, loading or reloading modules on
+     * `"add"` and `"change"` events and deregistering them on `"unlink"`.
+     *
+     * Resolves once the initial directory scan is complete.
+     */
     async watch() {
         this.watcher = watch(this.basePath, CHOKIDAR_OPTIONS).on("all", (eventName, pathNameOriginal) => {
             const JS_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
             if (!JS_EXTENSIONS.some((extension) => pathNameOriginal.endsWith(`.${extension}`)))
                 return;
-            const pathName = pathNameOriginal.replaceAll("\\", "/");
+            const pathName = toForwardSlashPath(pathNameOriginal);
             if (pathName.includes("$.context") && eventName === "add") {
                 process.stdout.write(`\n\n!!! The file at ${pathName} needs a minor update.\n    See https://github.com/pmcelhaney/counterfact/blob/main/docs/faq.md\n\n\n`);
                 return;
@@ -49,14 +73,12 @@ export class ModuleLoader extends EventTarget {
                 return;
             }
             const parts = nodePath.parse(pathName.replace(this.basePath, ""));
-            const url = unescapePathForWindows(`/${parts.dir}/${parts.name}`
-                .replaceAll("\\", "/")
-                .replaceAll(/\/+/gu, "/"));
+            const url = unescapePathForWindows(toForwardSlashPath(`/${parts.dir}/${parts.name}`).replaceAll(/\/+/gu, "/"));
             if (eventName === "unlink") {
                 this.registry.remove(url);
                 this.dispatchEvent(new Event("remove"));
                 if (this.isContextFile(pathName)) {
-                    this.contextRegistry.remove(unescapePathForWindows(parts.dir).replaceAll("\\", "/") || "/");
+                    this.contextRegistry.remove(unescapePathForWindows(toForwardSlashPath(parts.dir)) || "/");
                 }
                 return;
             }
@@ -75,7 +97,7 @@ export class ModuleLoader extends EventTarget {
                     return;
                 if (!["add", "change", "unlink"].includes(eventName))
                     return;
-                const pathName = pathNameOriginal.replaceAll("\\", "/");
+                const pathName = toForwardSlashPath(pathNameOriginal);
                 if (eventName === "unlink") {
                     const fileKey = this.scenarioFileKey(pathName);
                     this.scenarioRegistry?.remove(fileKey);
@@ -86,6 +108,7 @@ export class ModuleLoader extends EventTarget {
             await once(this.scenariosWatcher, "ready");
         }
     }
+    /** Closes both file-system watchers (routes and scenarios). */
     async stopWatching() {
         await this.watcher?.close();
         await this.scenariosWatcher?.close();
@@ -93,6 +116,12 @@ export class ModuleLoader extends EventTarget {
     isContextFile(pathName) {
         return basename(pathName).startsWith("_.context.");
     }
+    /**
+     * Performs a one-shot load of all modules found under `directory` (relative
+     * to the configured base path) and all scenario files.
+     *
+     * @param directory - Sub-directory to load, defaults to the root (`""`).
+     */
     async load(directory = "") {
         const files = await this.fileDiscovery.findFiles(directory);
         await Promise.all(files.map((file) => this.loadEndpoint(file)));
@@ -115,12 +144,10 @@ export class ModuleLoader extends EventTarget {
         }
     }
     scenarioFileKey(pathName) {
-        const normalizedScenariosPath = (this.scenariosPath ?? "").replaceAll("\\", "/");
-        const directory = dirname(pathName.slice(normalizedScenariosPath.length)).replaceAll("\\", "/");
+        const normalizedScenariosPath = toForwardSlashPath(this.scenariosPath ?? "");
+        const directory = pathDirname(pathName.slice(normalizedScenariosPath.length));
         const name = nodePath.parse(basename(pathName)).name;
-        const url = unescapePathForWindows(`/${nodePath.join(directory, name)}`
-            .replaceAll("\\", "/")
-            .replaceAll(/\/+/gu, "/"));
+        const url = unescapePathForWindows(toForwardSlashPath(`/${nodePath.join(directory, name)}`).replaceAll(/\/+/gu, "/"));
         return url.slice(1); // strip leading "/"
     }
     async loadScenarioFile(pathName) {
@@ -142,10 +169,8 @@ export class ModuleLoader extends EventTarget {
     }
     async loadEndpoint(pathName) {
         debug("importing module: %s", pathName);
-        const directory = dirname(pathName.slice(this.basePath.length)).replaceAll("\\", "/");
-        const url = unescapePathForWindows(`/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`
-            .replaceAll("\\", "/")
-            .replaceAll(/\/+/gu, "/"));
+        const directory = pathDirname(pathName.slice(this.basePath.length));
+        const url = unescapePathForWindows(toForwardSlashPath(`/${nodePath.join(directory, nodePath.parse(basename(pathName)).name)}`).replaceAll(/\/+/gu, "/"));
         debug(`loading pathName from dependencyGraph: ${pathName}`);
         this.dependencyGraph.load(pathName);
         try {
@@ -159,9 +184,7 @@ export class ModuleLoader extends EventTarget {
             if (importError !== undefined) {
                 const isSyntaxError = importError instanceof SyntaxError ||
                     String(importError).startsWith("SyntaxError:");
-                const displayPath = nodePath
-                    .relative(process.cwd(), unescapePathForWindows(pathName))
-                    .replaceAll("\\", "/");
+                const displayPath = pathRelative(process.cwd(), unescapePathForWindows(pathName));
                 const message = isSyntaxError
                     ? `There is a syntax error in the route file: ${displayPath}`
                     : `There was an error loading the route file: ${displayPath}`;

package/dist/server/module-tree.js

@@ -1,6 +1,20 @@
 function isDirectory(test) {
     return test !== undefined;
 }
+/**
+ * Trie-based tree that maps URL path segments to route-handler modules.
+ *
+ * Each node in the tree represents one URL segment.  Segments whose names are
+ * wrapped in curly braces (e.g. `{petId}`) are treated as wildcards and can
+ * match any value in that position.
+ *
+ * The tree supports:
+ * - **Exact matches** — literal URL segments take precedence over wildcards.
+ * - **Wildcard matches** — `{param}` segments capture the matched value as a
+ *   path variable.
+ * - **Ambiguous-wildcard detection** — when multiple wildcards exist at the
+ *   same level the match is flagged as `ambiguous` and an error is logged.
+ */
 export class ModuleTree {
     root = {
         directories: new Map(),
@@ -58,6 +72,12 @@ export class ModuleTree {
             }
         }
     }
+    /**
+     * Registers a module at the given URL pattern.
+     *
+     * @param url - The route URL pattern (e.g. `"/pets/{petId}"`).
+     * @param module - The route-handler module to associate with the URL.
+     */
     add(url, module) {
         this.addModuleToDirectory(this.root, url.split("/").slice(1), module);
     }
@@ -75,6 +95,11 @@ export class ModuleTree {
         }
         this.removeModuleFromDirectory(directory.directories.get(segment.toLowerCase()), remainingSegments);
     }
+    /**
+     * Removes the module registered at `url`.
+     *
+     * @param url - The route URL pattern to deregister.
+     */
     remove(url) {
         const segments = url.split("/").slice(1);
         this.removeModuleFromDirectory(this.root, segments);
@@ -168,9 +193,20 @@ export class ModuleTree {
         }
         return wildcardMatches[0];
     }
+    /**
+     * Finds the best-matching module for `url` and `method`.
+     *
+     * Traverses the trie, preferring exact matches over wildcards at each
+     * segment.  Returns `undefined` when no match is found.
+     *
+     * @param url - The incoming request URL.
+     * @param method - The HTTP method (used to validate wildcard matches).
+     * @returns A {@link Match} object, or `undefined` when nothing matches.
+     */
     match(url, method) {
         return this.matchWithinDirectory(this.root, url.split("/").slice(1), {}, "", method);
     }
+    /** Returns all registered routes sorted alphabetically by path. */
     get routes() {
         const routes = [];
         function traverse(directory, path) {