@counterfact/generator 0.1.1

package/License.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Patrick McElhaney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# `@counterfact/generator`
+
+Generate Counterfact route scaffolds, OpenAPI-derived TypeScript contracts,
+scenario types, and compatible local `counterfact-types` templates.
+
+The public package boundary is intentionally small:
+`CodeGenerator`, `ScenarioFileGenerator`, and `Repository` support the
+`counterfact` facade, `generateVersionsTsContent` supports multi-version
+projects, and `buildOperationTypeNameMapping` supports legacy route migration.
+Concrete coders remain private implementation details.
+
+The build carries the generated-handler-compatible portion of
+`@counterfact/types` under `dist/templates/counterfact-types`. Runtime-only
+shared values are excluded so generated projects retain their existing file
+contract.
+
+See [`examples/generate-routes.mjs`](./examples/generate-routes.mjs) for a
+complete public-import example.

package/dist/code-generator.d.ts

@@ -0,0 +1,60 @@
+import { Repository } from "./repository.js";
+/**
+ * Orchestrates the code-generation pipeline and optional file-system watching.
+ *
+ * When {@link watch} is called, Counterfact watches the source OpenAPI document
+ * for changes and re-runs code generation automatically.  `"generate"` and
+ * `"failed"` events are emitted after each attempt.
+ */
+export declare class CodeGenerator extends EventTarget {
+    private readonly openapiPath;
+    private readonly destination;
+    private readonly version;
+    private readonly overlays;
+    private readonly generateOptions;
+    private watcher;
+    constructor(openApiPath: string, destination: string, generateOptions: {
+        prune?: boolean;
+        routes?: boolean;
+        types?: boolean;
+    }, version?: string, overlays?: readonly string[]);
+    /**
+     * Initialises the `.cache` directory that holds compiled JS output.
+     *
+     * Creates a `.gitignore` file that excludes the `.cache` sub-directory and a
+     * `README.md` inside `.cache` that explains its purpose.
+     *
+     * @param destination - The root output directory.
+     */
+    private buildCacheDirectory;
+    /**
+     * Reads and returns the `#/paths` requirement from `specification`.
+     *
+     * Writes a diagnostic message to stderr and returns an empty set when the
+     * `paths` key is missing or cannot be read.
+     *
+     * @param specification - The loaded OpenAPI specification.
+     */
+    private getPathsFromSpecification;
+    /**
+     * Runs the main code-generation pipeline once and resolves when complete.
+     *
+     * Loads the OpenAPI spec from `openapiPath`, optionally prunes defunct route
+     * files, registers all path operations as {@link OperationCoder} exports, and
+     * writes the resulting TypeScript files to `destination`.
+     *
+     * @param repository - Injectable repository instance; defaults to a fresh one
+     *   (primarily useful in tests).
+     */
+    generate(repository?: Repository): Promise<void>;
+    /**
+     * Starts watching the OpenAPI document and any overlay files for changes.
+     *
+     * Has no effect when neither source is watchable (for example, an HTTP
+     * OpenAPI source with no local overlays).
+     * Resolves once the watcher is ready.
+     */
+    watch(): Promise<void>;
+    /** Closes the file-system watcher. */
+    stopWatching(): Promise<void>;
+}

package/dist/code-generator.js

@@ -0,0 +1,182 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- generated files are written under the caller-provided destination tree. */
+import { watch } from "chokidar";
+import createDebug from "debug";
+import { ensureDirectoryExists } from "./ensure-directory-exists.js";
+import { OperationCoder } from "./operation-coder.js";
+import { assertNoNormalizedPathCollisions, normalizeOpenApiPath, } from "./openapi-path.js";
+import { pruneRoutes, pruneTypes } from "./prune.js";
+import { Repository } from "./repository.js";
+import { Specification } from "./specification.js";
+import { waitForEvent } from "./wait-for-event.js";
+import { CHOKIDAR_OPTIONS } from "./watch-options.js";
+const debug = createDebug("counterfact:typescript-generator:generate");
+/**
+ * Orchestrates the code-generation pipeline and optional file-system watching.
+ *
+ * When {@link watch} is called, Counterfact watches the source OpenAPI document
+ * for changes and re-runs code generation automatically.  `"generate"` and
+ * `"failed"` events are emitted after each attempt.
+ */
+export class CodeGenerator extends EventTarget {
+    openapiPath;
+    destination;
+    version;
+    overlays;
+    generateOptions;
+    watcher;
+    constructor(openApiPath, destination, generateOptions, version = "", overlays = []) {
+        super();
+        this.openapiPath = openApiPath;
+        this.destination = destination;
+        this.version = version;
+        this.overlays = overlays;
+        this.generateOptions = generateOptions;
+    }
+    /**
+     * Initialises the `.cache` directory that holds compiled JS output.
+     *
+     * Creates a `.gitignore` file that excludes the `.cache` sub-directory and a
+     * `README.md` inside `.cache` that explains its purpose.
+     *
+     * @param destination - The root output directory.
+     */
+    async buildCacheDirectory(destination) {
+        const gitignorePath = nodePath.join(destination, ".gitignore");
+        const cacheReadmePath = nodePath.join(destination, ".cache", "README.md");
+        debug("ensuring the directory containing .gitgnore exists");
+        await ensureDirectoryExists(gitignorePath);
+        debug("creating the .gitignore file if it doesn't already exist");
+        if (!existsSync(gitignorePath)) {
+            await fs.writeFile(gitignorePath, ".cache\n", "utf8");
+        }
+        debug("creating the .cache/README.md file");
+        ensureDirectoryExists(cacheReadmePath);
+        await fs.writeFile(cacheReadmePath, "This directory contains compiled JS files from the paths directory. Do not edit these files directly.\n", "utf8");
+    }
+    /**
+     * Reads and returns the `#/paths` requirement from `specification`.
+     *
+     * Writes a diagnostic message to stderr and returns an empty set when the
+     * `paths` key is missing or cannot be read.
+     *
+     * @param specification - The loaded OpenAPI specification.
+     */
+    async getPathsFromSpecification(specification) {
+        try {
+            return specification.getRequirement("#/paths") ?? new Set();
+        }
+        catch (error) {
+            process.stderr.write(`Could not find #/paths in the specification.\n${error}\n`);
+            return undefined;
+        }
+    }
+    /**
+     * Runs the main code-generation pipeline once and resolves when complete.
+     *
+     * Loads the OpenAPI spec from `openapiPath`, optionally prunes defunct route
+     * files, registers all path operations as {@link OperationCoder} exports, and
+     * writes the resulting TypeScript files to `destination`.
+     *
+     * @param repository - Injectable repository instance; defaults to a fresh one
+     *   (primarily useful in tests).
+     */
+    async generate(repository = new Repository()) {
+        const { destination } = this;
+        debug("generating code from %s to %s", this.openapiPath, destination);
+        debug("initializing the .cache directory");
+        await this.buildCacheDirectory(destination);
+        debug("done initializing the .cache directory");
+        debug("creating specification from %s", this.openapiPath);
+        const specification = await Specification.fromFile(this.openapiPath, this.overlays);
+        debug("created specification: $o", specification);
+        debug("reading the #/paths from the specification");
+        const paths = await this.getPathsFromSpecification(specification);
+        debug("got %i paths", paths?.map?.length ?? 0);
+        const openApiPaths = paths.map((_pathDefinition, key) => key);
+        assertNoNormalizedPathCollisions(openApiPaths);
+        if (this.generateOptions.prune && this.generateOptions.routes) {
+            debug("pruning defunct route files");
+            await pruneRoutes(destination, openApiPaths);
+            debug("done pruning");
+        }
+        const securityRequirement = specification.getRequirement("#/components/securitySchemes");
+        const securitySchemes = Object.values(securityRequirement?.data ?? {});
+        const HTTP_VERBS = new Set([
+            "get",
+            "put",
+            "post",
+            "delete",
+            "options",
+            "head",
+            "patch",
+            "trace",
+        ]);
+        const operationMethodsForPath = (pathDefinition) => pathDefinition.flatMap((operation, requestMethod) => {
+            if (requestMethod === "additionalOperations") {
+                return operation.map((additionalOperation, additionalMethod) => [
+                    additionalOperation,
+                    additionalMethod.toLowerCase(),
+                ]);
+            }
+            if (!HTTP_VERBS.has(requestMethod)) {
+                return [];
+            }
+            return [[operation, requestMethod]];
+        });
+        paths.forEach((pathDefinition, key) => {
+            debug("processing path %s", key);
+            const normalizedPath = normalizeOpenApiPath(key);
+            const path = normalizedPath === "/" ? "/index" : normalizedPath;
+            operationMethodsForPath(pathDefinition).forEach(([operation, requestMethod]) => {
+                repository
+                    .get(`routes${path}.ts`)
+                    .export(new OperationCoder(operation, this.version, requestMethod, securitySchemes));
+            });
+        });
+        if (this.generateOptions.prune && this.generateOptions.types) {
+            debug("resolving the expected generated type files");
+            await repository.finished();
+            debug("pruning defunct generated type files");
+            await pruneTypes(destination, [
+                ...repository.scripts.keys(),
+                ...(this.version === "" ? [] : ["types/versions.ts"]),
+            ]);
+            debug("done pruning generated type files");
+        }
+        debug("telling the repository to write the files to %s", destination);
+        await repository.writeFiles(destination, this.generateOptions);
+        debug("finished writing the files");
+    }
+    /**
+     * Starts watching the OpenAPI document and any overlay files for changes.
+     *
+     * Has no effect when neither source is watchable (for example, an HTTP
+     * OpenAPI source with no local overlays).
+     * Resolves once the watcher is ready.
+     */
+    async watch() {
+        const watchablePaths = this.openapiPath.startsWith("http")
+            ? [...this.overlays]
+            : [this.openapiPath, ...this.overlays];
+        if (watchablePaths.length === 0) {
+            return;
+        }
+        this.watcher = watch(watchablePaths, CHOKIDAR_OPTIONS).on("change", () => {
+            void this.generate().then(() => {
+                this.dispatchEvent(new Event("generate"));
+                return true;
+            }, () => {
+                this.dispatchEvent(new Event("failed"));
+                return false;
+            });
+        });
+        await waitForEvent(this.watcher, "ready");
+    }
+    /** Closes the file-system watcher. */
+    async stopWatching() {
+        await this.watcher?.close();
+    }
+}

package/dist/coder.d.ts

@@ -0,0 +1,107 @@
+import type { Requirement } from "./requirement.js";
+import type { Script } from "./script.js";
+/**
+ * Base class for all code-generation helpers in the TypeScript generator.
+ *
+ * A `Coder` wraps a single {@link Requirement} node from the OpenAPI spec and
+ * knows how to emit TypeScript code for it.  Subclasses override
+ * {@link writeCode} to produce the actual source text.
+ *
+ * Coders are used by {@link Script} and {@link Repository} to lazily generate
+ * exports and imports, resolving `$ref` references through the
+ * {@link Specification} before writing.
+ */
+export declare class Coder {
+    requirement: Requirement;
+    version: string;
+    constructor(requirement: Requirement, version?: string);
+    /**
+     * A stable cache key for this coder, composed of the constructor name and
+     * either the `$ref` value (for references) or the requirement URL.
+     */
+    get id(): string;
+    /**
+     * Optional preamble emitted before the `export` keyword.
+     *
+     * Subclasses can return a string (e.g. a type alias) that must appear in the
+     * output before this coder's export statement.
+     *
+     * @param _path - The path of the script being written (unused in base class).
+     */
+    beforeExport(_path?: string): string;
+    /**
+     * Returns a JSDoc comment block to be placed immediately before the export.
+     *
+     * Returns `""` by default; subclasses override this to surface OpenAPI
+     * metadata (description, summary, examples, etc.).
+     */
+    jsdoc(): string;
+    /**
+     * Writes this coder's contribution to `script`.
+     *
+     * When the requirement is a `$ref`, delegates to {@link Script.import} so
+     * the reference target is exported from its own module.  Otherwise calls
+     * {@link writeCode}.
+     *
+     * @param script - The script being assembled.
+     * @returns The TypeScript source text for this coder's export value.
+     */
+    write(script: Script): string;
+    /**
+     * Generates the TypeScript source text for this coder's value.
+     *
+     * This method is abstract — subclasses **must** override it.
+     *
+     * @param _script - The script being assembled.
+     * @throws Always — callers should never reach the base implementation.
+     */
+    writeCode(_script: Script): string;
+    /**
+     * Resolves `$ref` references by returning the target coder.
+     *
+     * When this coder's requirement is not a reference, returns `this`.
+     * Otherwise loads the referenced requirement and wraps it in an instance of
+     * the same concrete coder class.
+     */
+    delegate(): Promise<Coder>;
+    /**
+     * Generator that yields candidate export names for this coder.
+     *
+     * The first name is derived from the last path segment of the requirement
+     * URL, sanitised to be a valid TypeScript identifier.  Subsequent names have
+     * an incrementing numeric suffix to resolve collisions.
+     *
+     * @param rawName - Override the starting name (used by subclasses).
+     */
+    names(rawName?: string): Generator<string>;
+    /**
+     * Returns an optional TypeScript type annotation string to be placed between
+     * the export name and its value (`export const name: <type> = value`).
+     *
+     * Returns `""` by default.
+     */
+    typeDeclaration(_namespace?: Map<string, ExportStatement>, _script?: Script): string;
+    /**
+     * Returns the repository-relative path of the script where this coder's
+     * export should live when imported by another script.
+     *
+     * Subclasses override this to place type exports in `types/paths/…` and
+     * route exports in `routes/…`.
+     */
+    modulePath(): string;
+}
+export interface ExportStatement {
+    beforeExport: string;
+    done: boolean;
+    id: string;
+    isDefault: boolean;
+    isType: boolean;
+    jsdoc: string;
+    typeDeclaration: string;
+    name?: string;
+    code?: string | {
+        raw: string;
+    };
+    error?: Error;
+    promise?: Promise<Coder | undefined>;
+}

package/dist/coder.js

@@ -0,0 +1,132 @@
+import { RESERVED_WORDS } from "./reserved-words.js";
+/**
+ * Base class for all code-generation helpers in the TypeScript generator.
+ *
+ * A `Coder` wraps a single {@link Requirement} node from the OpenAPI spec and
+ * knows how to emit TypeScript code for it.  Subclasses override
+ * {@link writeCode} to produce the actual source text.
+ *
+ * Coders are used by {@link Script} and {@link Repository} to lazily generate
+ * exports and imports, resolving `$ref` references through the
+ * {@link Specification} before writing.
+ */
+export class Coder {
+    requirement;
+    version;
+    constructor(requirement, version = "") {
+        this.requirement = requirement;
+        this.version = version;
+    }
+    /**
+     * A stable cache key for this coder, composed of the constructor name and
+     * either the `$ref` value (for references) or the requirement URL.
+     */
+    get id() {
+        if (this.requirement.isReference) {
+            return `${this.constructor.name}@${this.requirement.refUrl}`;
+        }
+        return `${this.constructor.name}@${this.requirement.url}`;
+    }
+    /**
+     * Optional preamble emitted before the `export` keyword.
+     *
+     * Subclasses can return a string (e.g. a type alias) that must appear in the
+     * output before this coder's export statement.
+     *
+     * @param _path - The path of the script being written (unused in base class).
+     */
+    beforeExport(_path) {
+        return "";
+    }
+    /**
+     * Returns a JSDoc comment block to be placed immediately before the export.
+     *
+     * Returns `""` by default; subclasses override this to surface OpenAPI
+     * metadata (description, summary, examples, etc.).
+     */
+    jsdoc() {
+        return "";
+    }
+    /**
+     * Writes this coder's contribution to `script`.
+     *
+     * When the requirement is a `$ref`, delegates to {@link Script.import} so
+     * the reference target is exported from its own module.  Otherwise calls
+     * {@link writeCode}.
+     *
+     * @param script - The script being assembled.
+     * @returns The TypeScript source text for this coder's export value.
+     */
+    write(script) {
+        if (this.requirement.isReference) {
+            return script.import(this);
+        }
+        return this.writeCode(script);
+    }
+    /**
+     * Generates the TypeScript source text for this coder's value.
+     *
+     * This method is abstract — subclasses **must** override it.
+     *
+     * @param _script - The script being assembled.
+     * @throws Always — callers should never reach the base implementation.
+     */
+    writeCode(_script) {
+        throw new Error("write() is abstract and should be overwritten by a subclass");
+    }
+    /**
+     * Resolves `$ref` references by returning the target coder.
+     *
+     * When this coder's requirement is not a reference, returns `this`.
+     * Otherwise loads the referenced requirement and wraps it in an instance of
+     * the same concrete coder class.
+     */
+    async delegate() {
+        if (!this.requirement.isReference) {
+            return this;
+        }
+        const requirement = await this.requirement.reference();
+        return new this.constructor(requirement, this.version);
+    }
+    /**
+     * Generator that yields candidate export names for this coder.
+     *
+     * The first name is derived from the last path segment of the requirement
+     * URL, sanitised to be a valid TypeScript identifier.  Subsequent names have
+     * an incrementing numeric suffix to resolve collisions.
+     *
+     * @param rawName - Override the starting name (used by subclasses).
+     */
+    *names(rawName = this.requirement.url.split("/").at(-1)) {
+        const name = rawName
+            .replace(/^\d/u, (digit) => `_${digit}`)
+            .replaceAll(/[^\w$]/gu, "_");
+        const baseName = RESERVED_WORDS.has(name) ? `${name}_` : name;
+        yield baseName;
+        let index = 1;
+        const MAX_NAMES_TO_GENERATE_BEFORE_GIVING_UP = 100;
+        while (index < MAX_NAMES_TO_GENERATE_BEFORE_GIVING_UP) {
+            index += 1;
+            yield baseName + index;
+        }
+    }
+    /**
+     * Returns an optional TypeScript type annotation string to be placed between
+     * the export name and its value (`export const name: <type> = value`).
+     *
+     * Returns `""` by default.
+     */
+    typeDeclaration(_namespace, _script) {
+        return "";
+    }
+    /**
+     * Returns the repository-relative path of the script where this coder's
+     * export should live when imported by another script.
+     *
+     * Subclasses override this to place type exports in `types/paths/…` and
+     * route exports in `routes/…`.
+     */
+    modulePath() {
+        return "did-not-override-coder-modulePath.ts";
+    }
+}

package/dist/context-file-token.d.ts

@@ -0,0 +1 @@
+export declare const CONTEXT_FILE_TOKEN = "@@CONTEXT_FILE_TOKEN@@";

package/dist/context-file-token.js

@@ -0,0 +1 @@
+export const CONTEXT_FILE_TOKEN = "@@CONTEXT_FILE_TOKEN@@";

package/dist/ensure-directory-exists.d.ts

@@ -0,0 +1 @@
+export declare function ensureDirectoryExists(filePath: string): void;

package/dist/ensure-directory-exists.js

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- helper creates parent directories for caller-provided generator output paths. */
+export function ensureDirectoryExists(filePath) {
+    const directory = nodePath.dirname(filePath);
+    try {
+        fs.accessSync(directory, fs.constants.W_OK);
+    }
+    catch {
+        fs.mkdirSync(directory, { recursive: true });
+    }
+}

package/dist/forward-slash-path.d.ts

@@ -0,0 +1,9 @@
+declare const __forwardSlashPath: unique symbol;
+type ForwardSlashPath = string & {
+    readonly [__forwardSlashPath]: never;
+};
+export declare function toForwardSlashPath(path: string): ForwardSlashPath;
+export declare function pathJoin(...paths: string[]): ForwardSlashPath;
+export declare function pathRelative(from: string, to: string): ForwardSlashPath;
+export declare function pathDirname(path: string): ForwardSlashPath;
+export {};

package/dist/forward-slash-path.js

@@ -0,0 +1,13 @@
+import nodePath from "node:path";
+export function toForwardSlashPath(path) {
+    return path.replaceAll("\\", "/");
+}
+export function pathJoin(...paths) {
+    return toForwardSlashPath(nodePath.join(...paths));
+}
+export function pathRelative(from, to) {
+    return toForwardSlashPath(nodePath.relative(from, to));
+}
+export function pathDirname(path) {
+    return toForwardSlashPath(nodePath.dirname(path));
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { CodeGenerator } from "./code-generator.js";
+export { buildOperationTypeNameMapping, type OperationTypeNameMapping, } from "./operation-type-name-mapping.js";
+export { Repository } from "./repository.js";
+export { ScenarioFileGenerator } from "./scenario-file-generator.js";
+export { generateVersionsTsContent } from "./versions-ts-generator.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { CodeGenerator } from "./code-generator.js";
+export { buildOperationTypeNameMapping, } from "./operation-type-name-mapping.js";
+export { Repository } from "./repository.js";
+export { ScenarioFileGenerator } from "./scenario-file-generator.js";
+export { generateVersionsTsContent } from "./versions-ts-generator.js";

package/dist/jsdoc.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Builds a JSDoc comment string from OpenAPI schema metadata.
+ * Returns an empty string if there is no relevant metadata.
+ */
+export declare function buildJsDoc(data: unknown): string;

package/dist/jsdoc.js

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

package/dist/openapi-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalizes an OpenAPI path for Counterfact's route and type module trees.
+ *
+ * Incoming requests already match route modules with or without a terminal
+ * slash, so terminal slashes must not create an extra empty file segment.
+ */
+export declare function normalizeOpenApiPath(openApiPath: string): string;
+/**
+ * Rejects path keys that would target the same generated route module.
+ */
+export declare function assertNoNormalizedPathCollisions(openApiPaths: Iterable<string>): void;