@counterfact/generator 0.1.1

package/dist/operation-type-name-mapping.js

@@ -0,0 +1,53 @@
+import createDebug from "debug";
+import { OperationTypeCoder, } from "./operation-type-coder.js";
+import { Specification } from "./specification.js";
+const debug = createDebug("counterfact:typescript-generator:operation-type-name-mapping");
+const HTTP_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "DELETE",
+    "PATCH",
+    "HEAD",
+    "OPTIONS",
+    "QUERY",
+]);
+function openApiPathToFilePath(openApiPath) {
+    if (openApiPath === "/") {
+        return "index";
+    }
+    return openApiPath.startsWith("/") ? openApiPath.slice(1) : openApiPath;
+}
+/**
+ * Resolves the generated operation type name for each route and HTTP method.
+ * This is the migration-facing API; concrete coder and specification classes
+ * remain internal implementation details.
+ */
+export async function buildOperationTypeNameMapping(source, overlays = []) {
+    debug("building operation type name mapping from %s", source);
+    const specification = await Specification.fromFile(source, overlays);
+    const mapping = new Map();
+    const paths = specification.getRequirement("#/paths");
+    if (!paths) {
+        return mapping;
+    }
+    const securityRequirement = specification.getRequirement("#/components/securitySchemes");
+    const securitySchemes = Object.values(securityRequirement?.data ?? {});
+    paths.forEach((pathDefinition, openApiPath) => {
+        const methodMap = new Map();
+        pathDefinition.forEach((operation, requestMethod) => {
+            const method = requestMethod.toUpperCase();
+            if (!HTTP_METHODS.has(method)) {
+                return;
+            }
+            const typeName = new OperationTypeCoder(operation, "", requestMethod, securitySchemes)
+                .names()
+                .next().value;
+            methodMap.set(method, typeName);
+        });
+        if (methodMap.size > 0) {
+            mapping.set(openApiPathToFilePath(openApiPath), methodMap);
+        }
+    });
+    return mapping;
+}

package/dist/parameter-export-type-coder.d.ts

@@ -0,0 +1,13 @@
+import { TypeCoder } from "./type-coder.js";
+import type { Requirement } from "./requirement.js";
+export declare class ParameterExportTypeCoder extends TypeCoder {
+    _typeName: string;
+    _typeCode: string;
+    _parameterKind: string;
+    _modulePath: string;
+    constructor(requirement: Requirement, version: string, typeName: string, typeCode: string, parameterKind: string);
+    get id(): string;
+    names(): Generator<string>;
+    writeCode(): string;
+    modulePath(): string;
+}

package/dist/parameter-export-type-coder.js

@@ -0,0 +1,27 @@
+import { TypeCoder } from "./type-coder.js";
+export class ParameterExportTypeCoder extends TypeCoder {
+    _typeName;
+    _typeCode;
+    _parameterKind;
+    _modulePath;
+    constructor(requirement, version, typeName, typeCode, parameterKind) {
+        super(requirement, version);
+        this._typeName = typeName;
+        this._typeCode = typeCode;
+        this._parameterKind = parameterKind;
+    }
+    get id() {
+        // Make the id unique by including the parameter kind
+        return `${super.id}:${this._parameterKind}`;
+    }
+    *names() {
+        yield this._typeName;
+    }
+    writeCode() {
+        return this._typeCode;
+    }
+    modulePath() {
+        // Use the same module path as the parent operation
+        return this._modulePath;
+    }
+}

package/dist/parameters-type-coder.d.ts

@@ -0,0 +1,10 @@
+import { TypeCoder } from "./type-coder.js";
+import type { Requirement } from "./requirement.js";
+import type { Script } from "./script.js";
+export declare class ParametersTypeCoder extends TypeCoder {
+    placement: string;
+    constructor(requirement: Requirement, version?: string, placement?: string);
+    names(): Generator<string>;
+    writeCode(script: Script): string;
+    modulePath(): string;
+}

package/dist/parameters-type-coder.js

@@ -0,0 +1,44 @@
+import { pathJoin } from "./forward-slash-path.js";
+import { buildJsDoc } from "./jsdoc.js";
+import { SchemaTypeCoder } from "./schema-type-coder.js";
+import { TypeCoder } from "./type-coder.js";
+export class ParametersTypeCoder extends TypeCoder {
+    placement;
+    constructor(requirement, version = "", placement = "") {
+        super(requirement, version);
+        this.placement = placement;
+    }
+    names() {
+        return super.names("parameters");
+    }
+    writeCode(script) {
+        const typeDefinitions = (this.requirement?.data ?? [])
+            .map((_, index) => {
+            return this.requirement.get(index);
+        })
+            .filter((parameter) => parameter.get("in").data === this.placement)
+            .map((parameter) => {
+            const name = parameter.get("name")?.data;
+            const required = parameter.get("required")?.data;
+            const optionalFlag = required ? "" : "?";
+            const schema = parameter.has("schema")
+                ? parameter.get("schema")
+                : parameter;
+            const comment = buildJsDoc(parameter.data);
+            const commentPrefix = comment ? `\n${comment}` : "";
+            const typeString = new SchemaTypeCoder(schema, this.version).write(script);
+            return `${commentPrefix}"${name}"${optionalFlag}: ${typeString}`;
+        });
+        if (typeDefinitions.length === 0) {
+            return "never";
+        }
+        return `{${typeDefinitions.join(", ")}}`;
+    }
+    modulePath() {
+        const pathString = this.requirement.url
+            .split("/")
+            .at(-2)
+            .replaceAll("~1", "/");
+        return `${pathJoin("parameters", pathString)}.types.ts`;
+    }
+}

package/dist/printers.d.ts

@@ -0,0 +1,2 @@
+export declare function printObjectWithoutQuotes(entries: [string, string][]): string;
+export declare function printObject(entries: [string, string][]): string;

package/dist/printers.js

@@ -0,0 +1,10 @@
+export function printObjectWithoutQuotes(entries) {
+    return `{\n${entries
+        .map(([key, value]) => `${key}: ${value}`)
+        .join(",\n")}\n}`;
+}
+export function printObject(entries) {
+    return `{\n${entries
+        .map(([key, value]) => `"${key}": ${value}`)
+        .join(",\n")}\n}`;
+}

package/dist/prune.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Prunes route files that no longer correspond to any path in the OpenAPI spec.
+ * Context files (_.context.ts) are never pruned.
+ * @param destination - Base destination directory (contains the routes/ sub-directory)
+ * @param openApiPaths - Iterable of OpenAPI path strings (e.g. "/pet/{id}")
+ * @returns Number of files removed
+ */
+export declare function pruneRoutes(destination: string, openApiPaths: Iterable<string>): Promise<number>;
+/**
+ * Prunes obsolete files from the OpenAPI generator-owned namespaces below
+ * `types/`. Hidden files are included by the recursive directory walk.
+ *
+ * `types/_.context.ts` and paths outside the known generated namespaces are
+ * preserved because separate generators or users own them.
+ *
+ * @param destination - Base destination directory (contains `types/`).
+ * @param expectedPaths - Repository-relative generated paths to retain.
+ * @returns Number of files removed.
+ */
+export declare function pruneTypes(destination: string, expectedPaths: Iterable<string>): Promise<number>;

package/dist/prune.js

@@ -0,0 +1,146 @@
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+/* eslint-disable security/detect-non-literal-fs-filename -- pruning only traverses and removes files under generator-owned destination subdirectories. */
+import createDebug from "debug";
+import { toForwardSlashPath } from "./forward-slash-path.js";
+import { normalizeOpenApiPath } from "./openapi-path.js";
+const debug = createDebug("counterfact:typescript-generator:prune");
+/**
+ * Collects all .ts route files in a directory recursively.
+ * Context files (_.context.ts) are excluded.
+ * @param routesDir - Path to routes directory
+ * @param currentPath - Current subdirectory being processed (relative to routesDir)
+ * @returns Array of relative paths (using forward slashes)
+ */
+async function collectTypeScriptFiles(rootDir, currentPath = "") {
+    const files = [];
+    try {
+        const fullDir = currentPath ? nodePath.join(rootDir, currentPath) : rootDir;
+        const entries = await fs.readdir(fullDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relativePath = currentPath
+                ? `${currentPath}/${entry.name}`
+                : entry.name;
+            if (entry.isDirectory()) {
+                files.push(...(await collectTypeScriptFiles(rootDir, relativePath)));
+            }
+            else if (entry.name.endsWith(".ts")) {
+                files.push(relativePath);
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    return files;
+}
+/**
+ * Recursively removes empty directories under rootDir, but not rootDir itself.
+ * @param dir - Directory to check
+ * @param rootDir - Root directory that should never be removed
+ */
+async function removeEmptyDirectories(dir, rootDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        debug("could not read directory %s: %o", dir, error);
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            await removeEmptyDirectories(nodePath.join(dir, entry.name), rootDir);
+        }
+    }
+    if (nodePath.resolve(dir) === nodePath.resolve(rootDir)) {
+        return;
+    }
+    const remaining = await fs.readdir(dir);
+    if (remaining.length === 0) {
+        await fs.rmdir(dir);
+        debug("removed empty directory: %s", dir);
+    }
+}
+/**
+ * Converts an OpenAPI path to the expected route file path (relative to routesDir).
+ * e.g. "/pet/{id}" -> "pet/{id}.ts", "/" -> "index.ts"
+ * @param openApiPath - The OpenAPI path string
+ */
+function openApiPathToRouteFile(openApiPath) {
+    const normalizedPath = normalizeOpenApiPath(openApiPath);
+    const filePath = normalizedPath === "/" ? "index" : normalizedPath.slice(1);
+    return `${filePath}.ts`;
+}
+/**
+ * Prunes route files that no longer correspond to any path in the OpenAPI spec.
+ * Context files (_.context.ts) are never pruned.
+ * @param destination - Base destination directory (contains the routes/ sub-directory)
+ * @param openApiPaths - Iterable of OpenAPI path strings (e.g. "/pet/{id}")
+ * @returns Number of files removed
+ */
+export async function pruneRoutes(destination, openApiPaths) {
+    const routesDir = nodePath.join(destination, "routes");
+    const expectedFiles = new Set(Array.from(openApiPaths).map(openApiPathToRouteFile));
+    debug("expected route files: %o", Array.from(expectedFiles));
+    const actualFiles = (await collectTypeScriptFiles(routesDir)).filter((file) => nodePath.basename(file) !== "_.context.ts");
+    debug("actual route files: %o", actualFiles);
+    let prunedCount = 0;
+    for (const file of actualFiles) {
+        const normalizedFile = toForwardSlashPath(file);
+        if (!expectedFiles.has(normalizedFile)) {
+            const fullPath = nodePath.join(routesDir, file);
+            debug("pruning %s", fullPath);
+            await fs.rm(fullPath);
+            prunedCount++;
+        }
+    }
+    await removeEmptyDirectories(routesDir, routesDir);
+    debug("pruned %d files", prunedCount);
+    return prunedCount;
+}
+/**
+ * Returns whether a path below `types/` belongs to a namespace populated by
+ * the OpenAPI generator. Context support and arbitrary user-authored type
+ * modules are deliberately outside this ownership policy.
+ */
+function isGeneratorOwnedTypePath(path) {
+    const [first, second] = toForwardSlashPath(path).split("/");
+    const generatedCategory = (segment) => segment === "paths" || segment === "components" || segment === "#";
+    return (path === "versions.ts" ||
+        generatedCategory(first) ||
+        generatedCategory(second));
+}
+/**
+ * Prunes obsolete files from the OpenAPI generator-owned namespaces below
+ * `types/`. Hidden files are included by the recursive directory walk.
+ *
+ * `types/_.context.ts` and paths outside the known generated namespaces are
+ * preserved because separate generators or users own them.
+ *
+ * @param destination - Base destination directory (contains `types/`).
+ * @param expectedPaths - Repository-relative generated paths to retain.
+ * @returns Number of files removed.
+ */
+export async function pruneTypes(destination, expectedPaths) {
+    const typesDir = nodePath.join(destination, "types");
+    const expectedFiles = new Set(Array.from(expectedPaths, (path) => toForwardSlashPath(path).replace(/^types\//u, "")));
+    const actualFiles = (await collectTypeScriptFiles(typesDir)).filter(isGeneratorOwnedTypePath);
+    let prunedCount = 0;
+    debug("expected type files: %o", Array.from(expectedFiles));
+    debug("actual generated type files: %o", actualFiles);
+    for (const file of actualFiles) {
+        const normalizedFile = toForwardSlashPath(file);
+        if (!expectedFiles.has(normalizedFile)) {
+            const fullPath = nodePath.join(typesDir, file);
+            debug("pruning %s", fullPath);
+            await fs.rm(fullPath);
+            prunedCount++;
+        }
+    }
+    await removeEmptyDirectories(typesDir, typesDir);
+    debug("pruned %d type files", prunedCount);
+    return prunedCount;
+}

package/dist/read-only-comments.d.ts

@@ -0,0 +1 @@
+export declare const READ_ONLY_COMMENTS: string[];

package/dist/read-only-comments.js

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

package/dist/repository.d.ts

@@ -0,0 +1,87 @@
+import { Script } from "./script.js";
+interface WriteFilesOptions {
+    routes?: boolean;
+    types?: boolean;
+}
+/**
+ * Collection of {@link Script} objects keyed by their repository-relative
+ * path.
+ *
+ * Coders call {@link get} to obtain (or create) the script where they should
+ * export their generated TypeScript.  After all coders have been registered,
+ * {@link writeFiles} waits for every script to finish and writes the output to
+ * disk.
+ */
+export declare class Repository {
+    scripts: Map<string, Script>;
+    constructor();
+    /**
+     * Returns the {@link Script} for `path`, creating it if it does not yet
+     * exist.
+     *
+     * @param path - Repository-relative path (e.g. `"routes/pets.ts"`).
+     */
+    get(path: string): Script;
+    /** Waits until all scripts have resolved all of their pending export promises. */
+    finished(): Promise<void>;
+    /**
+     * Copies the compiled `counterfact-types` directory from the Counterfact
+     * distribution into the generated output tree.
+     *
+     * Returns `false` when the source directory does not exist (e.g. running
+     * from source without a prior build).
+     *
+     * @param destination - The root of the generated output tree.
+     */
+    copyCoreFiles(destination: string): Promise<boolean | void>;
+    /**
+     * Waits for all scripts to finish, then writes each one to disk.
+     *
+     * Route files (`routes/…`) are never fully overwritten if they already exist
+     * on disk, preserving user edits.  However, if the generated script contains
+     * HTTP-method handler exports that are absent from the existing file, those
+     * new exports (and their `import type` statements) are appended to the file.
+     * Type files (`types/…`) are always overwritten.
+     *
+     * @param destination - Absolute path to the output root directory.
+     * @param options - Controls which artefacts are written.
+     */
+    writeFiles(destination: string, { routes, types }: WriteFilesOptions): Promise<void>;
+    /**
+     * Creates the default `routes/_.context.ts` file if it does not already
+     * exist.
+     *
+     * @param destination - Absolute path to the output root directory.
+     */
+    createDefaultContextFile(destination: string): Promise<void>;
+    /**
+     * Appends any HTTP-method handler exports that appear in `generatedContent`
+     * but are absent from the existing file at `fullPath`.
+     *
+     * For each new export the corresponding `import type` statement is inserted
+     * after the last existing import line (or prepended when no imports exist),
+     * and the export block is appended at the end of the file.
+     *
+     * @param fullPath - Absolute path of the route file to update.
+     * @param generatedContent - The fully-generated file content (used as the
+     *   source of new import and export statements).
+     */
+    private appendNewHandlers;
+    /**
+     * Returns the path of the `_.context.ts` file that is nearest to `path` in
+     * the directory hierarchy, relative to the script's output directory.
+     *
+     * @param destination - Output root directory.
+     * @param path - Repository-relative path of the script being generated.
+     */
+    findContextPath(destination: string, path: string): string;
+    /**
+     * Walks up the directory tree from `path` to find the nearest
+     * `_.context.ts` file, falling back to `routes/_.context.ts` at the root.
+     *
+     * @param destination - Output root directory.
+     * @param path - Repository-relative path to start from.
+     */
+    nearestContextFile(destination: string, path: string): string;
+}
+export {};