@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/openapi/extract-schemas.d.ts

@@ -0,0 +1,11 @@
+import type { GRAPH } from "../routing/app.ts";
+import type { HoneyGraph } from "../routing/register.ts";
+import { type JsonSchema, type JsonSchemaOptions } from "../schema/to-json-schema.ts";
+export type RouteSchemas = {
+    readonly input?: Readonly<Record<string, JsonSchema>>;
+    readonly output?: Readonly<Record<string, Readonly<Record<string, JsonSchema>>>>;
+};
+/** Every route's schemas, keyed `METHOD /pattern`; a route that declares none has `{}`. */
+export declare function extractSchemas(app: {
+    readonly [GRAPH]: HoneyGraph;
+}, options?: JsonSchemaOptions): Record<string, RouteSchemas>;

package/dist/openapi/extract-schemas.js

@@ -0,0 +1,31 @@
+import { jsonSchemaOf } from "../schema/to-json-schema.js";
+import { collectRoutes } from "./collect.js";
+/** The keys of `.output()` that are no media type. */
+const NOT_MEDIA = ["headers", "redirect"];
+/** The schema an input entry documents: a `readableStream()` wrapper by the schema it wraps. */
+function schemaOf(entry) {
+    return "_tag" in entry ? entry.schema : entry;
+}
+/** Every route's schemas, keyed `METHOD /pattern`; a route that declares none has `{}`. */
+export function extractSchemas(app, options = {}) {
+    const out = {};
+    for (const route of collectRoutes(app).http) {
+        const schemas = {};
+        if (route.input !== null) {
+            const sources = Object.entries(route.input).filter(([source]) => source !== "binary");
+            schemas.input = Object.fromEntries(sources.map(([source, entry]) => [source, jsonSchemaOf(schemaOf(entry), "input", options)]));
+        }
+        if (route.output !== null) {
+            const media = Object.entries(route.output).filter(([key]) => !NOT_MEDIA.includes(key));
+            schemas.output = Object.fromEntries(media.map(([type, statuses]) => [
+                type,
+                Object.fromEntries(Object.entries(statuses).map(([status, schema]) => [
+                    status,
+                    jsonSchemaOf(schema, "output", options),
+                ])),
+            ]));
+        }
+        out[`${route.method} ${route.pattern}`] = schemas;
+    }
+    return out;
+}

package/dist/openapi/generate.d.ts

@@ -0,0 +1,47 @@
+import { GRAPH } from "../routing/app.ts";
+import { type InvalidateCheckConfig } from "../routing/invalidate-check.ts";
+import type { HoneyGraph } from "../routing/register.ts";
+import { type JsonSchemaOptions } from "../schema/to-json-schema.ts";
+import type { Logger } from "../telemetry/logger.ts";
+import { type OpenApiDocument, type OpenApiInfo } from "./document.ts";
+import { type OpenApiServer } from "./servers.ts";
+import { type OpenApiExternalDocs, type OpenApiTag } from "./tags.ts";
+import { type OpenApiWebhook } from "./webhooks.ts";
+export type { OpenApiDocument, OpenApiInfo } from "./document.ts";
+export type { OpenApiServer, OpenApiServerVariable } from "./servers.ts";
+export type { OpenApiExternalDocs, OpenApiTag } from "./tags.ts";
+export type { OpenApiWebhook, WebhookSignature } from "./webhooks.ts";
+/** What `filterRoutes` is shown of a route: its resolved meta, its method and its honey pattern. */
+export type OpenApiRouteInfo = {
+    readonly meta: Readonly<Record<string, unknown>>;
+    readonly method: string;
+    readonly path: string;
+};
+export type GenerateOpenApiOptions = {
+    readonly converters?: JsonSchemaOptions["converters"];
+    /** the document's own external docs */
+    readonly externalDocs?: OpenApiExternalDocs;
+    /** leave out every route this answers false for */
+    readonly filterRoutes?: (route: OpenApiRouteInfo) => boolean;
+    readonly info: OpenApiInfo;
+    /** mutations that declare no `invalidate`: reported at `"warn"` (the default), failing at `"error"` */
+    readonly invalidate?: InvalidateCheckConfig;
+    /** where warnings go; the app's logger by default */
+    readonly logger?: Logger;
+    /** a schema no converter can describe: fail the document (`"throw"`, the default) or document it `{}` */
+    readonly onSchemaError?: "throw" | "warn";
+    /** the metaSpec profile this document carries */
+    readonly profile?: string;
+    readonly securitySchemes?: Readonly<Record<string, unknown>>;
+    /** the servers it lists, in place of the stripped prefix; that prefix is appended to each */
+    readonly servers?: readonly OpenApiServer[];
+    /** metadata for the tags operations name; tags are never derived */
+    readonly tags?: readonly OpenApiTag[];
+    /** the requests the API sends subscribers, by name */
+    readonly webhooks?: Readonly<Record<string, OpenApiWebhook>>;
+};
+type App = {
+    readonly [GRAPH]: HoneyGraph;
+};
+/** The app's OpenAPI 3.1 document. */
+export declare function generateOpenApi(app: App, options: GenerateOpenApiOptions): OpenApiDocument;

package/dist/openapi/generate.js

@@ -0,0 +1,180 @@
+import { applyMetaSpec } from "../meta/meta-spec-apply.js";
+import { compileMetaSpec, resolveProfile } from "../meta/meta-spec.js";
+import { metaSpecOf } from "../meta/meta-spec-merge.js";
+import { MetaSpecDiagnostics, schemaMetaLookup } from "../meta/meta-spec-validate.js";
+import { statusKeyToCode } from "../response/status.js";
+import { GRAPH } from "../routing/app.js";
+import { findInvalidSelectors, invalidateLevel, missingInvalidateReport, } from "../routing/invalidate-check.js";
+import { deduplicateSchemas } from "../schema/slots.js";
+import { jsonSchemaOf, } from "../schema/to-json-schema.js";
+import { collectRoutes } from "./collect.js";
+import { createComponents } from "./components.js";
+import { assembleDocument } from "./document.js";
+import { assignOperationIds, buildPaths } from "./paths.js";
+import { addErrorResponses, ordered, successResponses } from "./responses.js";
+import { checkSecurity } from "./security.js";
+import { serversOf } from "./servers.js";
+import { tagsOf } from "./tags.js";
+import { webhooksOf } from "./webhooks.js";
+/** What a conversion issue reports, and how loudly. */
+function issueOf(issue, onError) {
+    if (issue.kind === "failed") {
+        const reason = issue.error instanceof Error ? issue.error.message : String(issue.error);
+        return [
+            "SCHEMA_FAILED",
+            onError === "throw" ? "error" : "warn",
+            `a ${issue.vendor} schema (${issue.io}) could not be converted: ${reason}`,
+        ];
+    }
+    if (issue.kind === "degraded")
+        return [
+            "SCHEMA_DEGRADED",
+            "warn",
+            `a ${issue.vendor} schema (${issue.io}) documents ${issue.nodes.join(", ")} unconstrained`,
+        ];
+    return [
+        "SCHEMA_DEGRADED",
+        "warn",
+        `no JSON Schema converter for vendor "${issue.vendor}" (${issue.io}); documented unconstrained`,
+    ];
+}
+/** The schemas a route's metaSpec schema entries read: its lowest 2xx JSON answer and each input source. */
+function rootsOf(route, options) {
+    const roots = {};
+    const json = "output" in route ? route.output?.["application/json"] : undefined;
+    const codes = Object.keys(json ?? {})
+        .map((key) => [statusKeyToCode[key], key])
+        .filter(([code]) => code >= 200 && code < 300)
+        .sort(([a], [b]) => a - b);
+    const primary = codes[0] === undefined ? undefined : json?.[codes[0][1]];
+    if (primary !== undefined && primary !== true)
+        roots.output = jsonSchemaOf(primary, "output", options);
+    for (const [source, entry] of Object.entries(route.input ?? {})) {
+        if (source === "binary")
+            continue;
+        const schema = "_tag" in entry ? entry.schema : entry;
+        roots[`input.${source}`] = jsonSchemaOf(schema, "input", options);
+    }
+    return schemaMetaLookup(roots);
+}
+/** The converter for one route: `jsonSchemaOf`, its local references lifted, its issues reported against `where`. */
+function converterOf(run) {
+    const onSchemaError = run.options.onSchemaError ?? "throw";
+    return (where) => (schema, io, hint) => {
+        const report = (issue) => {
+            const [code, level, text] = issueOf(issue, onSchemaError);
+            run.diagnostics.add(code, level, `${where}: ${text}`);
+        };
+        return run.components.hoist(jsonSchemaOf(schema, io, { converters: run.options.converters, report }), hint);
+    };
+}
+/** The routes the document describes: none internal, none `filterRoutes` rejects. */
+function routesOf(app, options) {
+    const keep = (route, method) => route.meta.internal !== true && (options.filterRoutes?.({ meta: route.meta, method, path: route.pattern }) ?? true);
+    const collected = collectRoutes(app);
+    return {
+        http: collected.http.filter((route) => keep(route, route.method)),
+        ws: collected.ws.filter((route) => keep(route, "WS")),
+    };
+}
+/** The policy's fields for one operation of `route`. */
+function policyOf(run) {
+    const { diagnostics, profile, spec } = run;
+    return (route, method, kind) => {
+        const operation = {};
+        const schemaMeta = spec.needsSchemas ? rootsOf(route, { converters: run.options.converters }) : undefined;
+        const meta = route.meta;
+        const { filter, name } = profile;
+        applyMetaSpec({
+            diagnostics,
+            filter,
+            kind,
+            meta,
+            method,
+            operation,
+            path: route.pattern,
+            profile: name,
+            schemaMeta,
+            spec,
+        });
+        return operation;
+    };
+}
+/** A route's responses (what it declares, its errors, else a bare 200) and its declared errors. */
+function responsesOf(errors) {
+    return (route, convert, hint) => {
+        const out = successResponses(route.output, convert, hint);
+        const declared = addErrorResponses(out, route.errorMeta, errors, (schema, h) => convert(schema, "output", h));
+        const responses = Object.keys(out).length === 0 ? { "200": { description: "Success" } } : ordered(out);
+        return { errors: declared, responses };
+    };
+}
+/** The checks over the whole document: ids, security, invalidate selectors, then every diagnostic out. */
+function check(run, operations, routes, logger) {
+    const { diagnostics, options } = run;
+    assignOperationIds(operations, (message) => diagnostics.add("DUPLICATE_OPERATION_ID", "error", message));
+    checkSecurity(operations, options.securitySchemes, (level, message) => diagnostics.add("UNKNOWN_SECURITY_SCHEME", level, message));
+    const emitted = operations
+        .filter(({ route }) => "registration" in route)
+        .map(({ method, operation, path, route }) => ({ meta: route.meta, method, operation, path }));
+    const level = invalidateLevel(options.invalidate);
+    if (level !== "off") {
+        const inventory = new Set(routes.http.map((route) => route.id));
+        for (const bad of findInvalidSelectors(emitted, inventory)) {
+            const selector = JSON.stringify(bad.selector);
+            const hint = 'write "<METHOD> <pattern>" for a registered route, e.g. "GET /users/:id"';
+            diagnostics.add("INVALID_SELECTOR", "error", `${bad.method} ${bad.path}: invalidate selector ${selector} names no route — ${hint}`);
+        }
+    }
+    for (const { code, message } of diagnostics.throwIfErrors())
+        logger.warn(`[honey:openapi] ${code}: ${message}`);
+    const missing = missingInvalidateReport(emitted, options.invalidate);
+    if (missing !== null && level === "error")
+        throw new Error(missing);
+    if (missing !== null)
+        logger.warn(missing);
+}
+/** The app's OpenAPI 3.1 document. */
+export function generateOpenApi(app, options) {
+    const settings = app[GRAPH].settings;
+    const diagnostics = new MetaSpecDiagnostics();
+    const spec = compileMetaSpec(metaSpecOf(app), diagnostics);
+    const run = {
+        components: createComponents(),
+        diagnostics,
+        options,
+        profile: resolveProfile(spec, options.profile, diagnostics),
+        spec,
+    };
+    const convertFor = converterOf(run);
+    const settingsSchema = (schema, hint) => schema === null ? null : convertFor("the app's error schema")(schema, "output", hint);
+    const errors = {
+        customErrorSchema: settingsSchema(settings.customErrorSchema, "CustomError"),
+        errorFormat: settings.errorFormat,
+        errorSchema: settingsSchema(settings.errorSchema, "Error"),
+    };
+    const routes = routesOf(app, options);
+    const { operations, paths } = buildPaths(routes, {
+        convert: convertFor,
+        policy: policyOf(run),
+        responses: responsesOf(errors),
+        trailingSlash: settings.trailingSlash,
+        warn: (code, message) => diagnostics.add(code, "warn", message),
+    });
+    const report = (code) => (message) => diagnostics.add(code, "error", message);
+    const servers = serversOf(options.servers, settings.stripPrefix, report("INVALID_SERVER"));
+    const webhooks = webhooksOf(options.webhooks, convertFor("webhooks"), report("INVALID_WEBHOOK"));
+    const tags = tagsOf(operations, options.tags, (code, level, message) => diagnostics.add(code, level, message));
+    check(run, operations, routes, options.logger ?? settings.logger);
+    const document = assembleDocument({
+        externalDocs: options.externalDocs,
+        info: options.info,
+        paths,
+        schemas: run.components.schemas(),
+        securitySchemes: options.securitySchemes,
+        servers,
+        tags,
+        webhooks,
+    });
+    return deduplicateSchemas(document);
+}

package/dist/openapi/manifest.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `generateManifest(app, options?)`: the app's routes as plain data, one entry per route by method
+ * and honey pattern, with the keys it may answer, its meta, the middleware it runs by name, and
+ * its shapes as JSON Schema; then every key once with its status. `visibility: "all"` (the
+ * generate-time artifact) keeps every route and meta key; `"published"` (a served manifest)
+ * applies the document's policy: no internal route, only the meta keys the metaSpec publishes.
+ */
+import type { GRAPH } from "../routing/app.ts";
+import { type HoneyGraph } from "../routing/register.ts";
+import type { JsonSchema, JsonSchemaOptions } from "../schema/to-json-schema.ts";
+import type { OpenApiRouteInfo } from "./generate.ts";
+export type ManifestRoute = {
+    readonly errors: readonly string[];
+    readonly input?: Readonly<Record<string, JsonSchema>>;
+    readonly meta: Readonly<Record<string, unknown>>;
+    readonly method: string;
+    readonly middleware: readonly string[];
+    readonly output?: Readonly<Record<string, Readonly<Record<string, JsonSchema>>>>;
+    readonly params: readonly string[];
+    readonly path: string;
+};
+export type ManifestError = {
+    readonly errorKey: string;
+    readonly status: number;
+    readonly statusKey: string;
+};
+export type RouteManifest = {
+    readonly errors: readonly ManifestError[];
+    readonly routes: readonly ManifestRoute[];
+};
+export type GenerateManifestOptions = {
+    readonly converters?: JsonSchemaOptions["converters"];
+    /** leave out every route this answers false for */
+    readonly filterRoutes?: (route: OpenApiRouteInfo) => boolean;
+    /** `"all"` (the default) keeps everything; `"published"` applies the document's visibility */
+    readonly visibility?: "all" | "published";
+};
+/** The app's route manifest. */
+export declare function generateManifest(app: {
+    readonly [GRAPH]: HoneyGraph;
+}, options?: GenerateManifestOptions): RouteManifest;

package/dist/openapi/manifest.js

@@ -0,0 +1,49 @@
+import { SERVED } from "../routing/register.js";
+import { compareCodeUnits } from "../schema/canonicalize.js";
+import { metaSpecOf } from "../meta/meta-spec-merge.js";
+import { publishableMetaKeys } from "../meta/meta-spec.js";
+import { collectRoutes } from "./collect.js";
+import { extractSchemas } from "./extract-schemas.js";
+/** One entry per route: an optional param's variants come shortest first, so the last is the fullest. */
+function byRoute(collected) {
+    const out = new Map();
+    for (const route of collected)
+        out.set(route.id, route);
+    return [...out.values()];
+}
+/** The app's route manifest. */
+export function generateManifest(app, options = {}) {
+    const published = options.visibility === "published";
+    const publishable = published ? publishableMetaKeys(metaSpecOf(app)) : () => true;
+    const schemas = extractSchemas(app, { converters: options.converters });
+    /* a route the app serves about itself is in no manifest; another internal route only in "all" */
+    const keep = (route) => route.meta[SERVED] !== true &&
+        !(published && route.internal) &&
+        (options.filterRoutes?.({ meta: route.meta, method: route.method, path: route.pattern }) ?? true);
+    const routes = byRoute(collectRoutes(app).http).filter(keep);
+    const errors = new Map();
+    const entries = routes.map((route) => {
+        for (const key of route.errorKeys)
+            if (!errors.has(key))
+                errors.set(key, route.errorMeta[key]);
+        /* every HTTP route has its entry, keyed by its id */
+        const { input, output } = schemas[route.id];
+        return {
+            errors: route.errorKeys,
+            ...(input === undefined ? {} : { input }),
+            meta: Object.fromEntries(Object.entries(route.meta).filter(([key]) => publishable(key))),
+            method: route.method,
+            middleware: route.middleware,
+            ...(output === undefined ? {} : { output }),
+            params: route.params,
+            path: route.pattern,
+        };
+    });
+    return {
+        errors: [...errors.keys()].sort(compareCodeUnits).map((errorKey) => {
+            const { status, statusKey } = errors.get(errorKey);
+            return { errorKey, status, statusKey };
+        }),
+        routes: entries,
+    };
+}

package/dist/openapi/output-keys.d.ts

@@ -0,0 +1,6 @@
+import type { OutputSchemas } from "../routing/output-types.ts";
+import type { RouteTree } from "../routing/tree.ts";
+/** Throws, naming route `id` and the key, when `output` holds a key that is no media type or no status. */
+export declare function assertOutputKeys(output: OutputSchemas, id: string): void;
+/** Throws as `assertOutputKeys` does for the first route of `tree` whose output holds such a key. */
+export declare function assertTreeOutputKeys(tree: RouteTree): void;

package/dist/openapi/output-keys.js

@@ -0,0 +1,24 @@
+/**
+ * What `KnownStatusKeys` refuses in the types, refused where an app is documented or its tree generated: an output
+ * declaration whose outer key is no media type (`type/subtype`), `headers` or `redirect`, or whose inner key names no
+ * status. Every document keys an answer by its status's code, so such a key would be documented under none. It sits
+ * on the generation paths only (collectRoutes, and the tree `honey generate` writes), never on the request path: an
+ * app that serves no document bundles none of it, and the types refuse the key where it is written.
+ */
+import { statusKeyToCode } from "../response/status.js";
+/** Throws, naming route `id` and the key, when `output` holds a key that is no media type or no status. */
+export function assertOutputKeys(output, id) {
+    for (const [outer, statuses] of Object.entries(output)) {
+        if (!/\/|^headers$|^redirect$/.test(outer))
+            throw new Error(`${id}: .output() key "${outer}" is no type/subtype, headers or redirect`);
+        for (const key of Object.keys(statuses ?? {}))
+            if (!Object.hasOwn(statusKeyToCode, key))
+                throw new Error(`${id}: .output() key "${key}" under ${outer} is none of ${Object.keys(statusKeyToCode).join(", ")}`);
+    }
+}
+/** Throws as `assertOutputKeys` does for the first route of `tree` whose output holds such a key. */
+export function assertTreeOutputKeys(tree) {
+    for (const [id, { out }] of Object.entries(tree.routes))
+        if (out)
+            assertOutputKeys(out, id);
+}

package/dist/openapi/paths.d.ts

@@ -0,0 +1,35 @@
+import type { CollectedRoute, CollectedRoutes, CollectedWsRoute } from "./collect.ts";
+import type { Convert, DeclaredError, ResponseObject } from "./responses.ts";
+export type Operation = Record<string, unknown>;
+export type PathItem = Record<string, Operation>;
+/** One emitted operation, for the checks that run over the whole document. */
+export type EmittedOperation = {
+    readonly method: string;
+    readonly operation: Operation;
+    readonly path: string;
+    readonly route: CollectedRoute | CollectedWsRoute;
+};
+export type PathsContext = {
+    /** the schema converter for one route; `where` names it in a report */
+    readonly convert: (where: string) => Convert;
+    /** the route's policy fields for one method, written first */
+    readonly policy: (route: CollectedRoute | CollectedWsRoute, method: string, kind: "http" | "ws") => Operation;
+    /** the route's responses, the errors it declares among them, and every declared error key (`x-honey-errors`) */
+    readonly responses: (route: CollectedRoute, convert: Convert, hint: (code: number) => string) => {
+        errors: Record<string, DeclaredError>;
+        responses: Record<string, ResponseObject>;
+    };
+    readonly trailingSlash: "enforce" | "ignore" | "strip";
+    readonly warn: (code: "WS_SHADOWED", message: string) => void;
+};
+/** Every operation of `collected`, by public path and method, and the list the document checks run over. */
+export declare function buildPaths(collected: CollectedRoutes, ctx: PathsContext): {
+    operations: EmittedOperation[];
+    paths: Record<string, PathItem>;
+};
+/**
+ * Make operationIds unique. One registration the document expands into several operations
+ * (`.on([...])`, `all()`, an optional param) keeps its id with a method or variant suffix; two
+ * registrations declaring one id is an authoring error.
+ */
+export declare function assignOperationIds(operations: readonly EmittedOperation[], error: (message: string) => void): void;

package/dist/openapi/paths.js

@@ -0,0 +1,175 @@
+import { parsePattern, UNNAMED_WILDCARD } from "../routing/pattern.js";
+import { deriveSchemaName } from "../schema/naming.js";
+const ALL_METHODS = ["get", "post", "put", "patch", "delete"];
+const BINARY_FORMATS = ["binary", "byte", "file"];
+const PROPERTY_SOURCES = { cookies: "cookie", headers: "header", search: "query" };
+/** The path a client sends: `trailingSlash("enforce")` adds the slash. */
+function publicPath(path, trailingSlash) {
+    return trailingSlash === "enforce" && path.length > 1 && !path.endsWith("/") ? `${path}/` : path;
+}
+/** The path parameters of one concrete path: each required, a wildcard marked as one. */
+function pathParameters(route) {
+    const last = parsePattern(route.pattern).at(-1);
+    const wildcard = last?.k === "wildcard" ? (last.n === UNNAMED_WILDCARD ? "wildcard" : last.n) : null;
+    return route.params.map((name) => name === wildcard
+        ? {
+            description: "The rest of the path; may contain `/`.",
+            in: "path",
+            name,
+            required: true,
+            schema: { type: "string" },
+            "x-honey-wildcard": true,
+        }
+        : { in: "path", name, required: true, schema: { type: "string" } });
+}
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** The schema an input entry documents: a `readableStream()` wrapper by the schema it wraps. */
+const schemaOf = (entry) => ("_tag" in entry ? entry.schema : entry);
+/** Whether a form part carries bytes: a binary format, a file, or an array of them. */
+function isBinaryPart(schema) {
+    if (!isRecord(schema))
+        return false;
+    if (BINARY_FORMATS.includes(schema.format) || schema.type === "file")
+        return true;
+    return schema.type === "array" && isBinaryPart(schema.items);
+}
+/** `schema` without its `x-internal` properties, and without them in `required`. */
+function withoutInternal(schema) {
+    if (!isRecord(schema.properties))
+        return schema;
+    const kept = Object.entries(schema.properties).filter(([, p]) => !isRecord(p) || p["x-internal"] !== true);
+    const out = { ...schema, properties: Object.fromEntries(kept) };
+    if (Array.isArray(schema.required))
+        out.required = schema.required.filter((k) => kept.some(([name]) => name === k));
+    return out;
+}
+/** One parameter per property of a search, headers or cookies object, `x-internal` ones left out. */
+function propertyParameters(schema, location) {
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    return Object.entries(isRecord(schema.properties) ? schema.properties : {})
+        .filter(([, p]) => !isRecord(p) || p["x-internal"] !== true)
+        .map(([name, p]) => ({ in: location, name, required: required.includes(name), schema: p }));
+}
+/** The request body and parameters a route's `.input()` declares, on their input side. */
+function inputsOf(input, convert, hint, parameters) {
+    let body = null;
+    for (const [source, entry] of Object.entries(input ?? {})) {
+        if (source === "binary") {
+            const types = typeof entry === "string" ? [entry] : entry;
+            /* OpenAPI 3.1 says "any bytes" by leaving the schema out */
+            body = Object.fromEntries(types.map((t) => [t, {}]));
+            continue;
+        }
+        const schema = convert(schemaOf(entry), "input", hint);
+        if (source === "json")
+            body = { "application/json": { schema: withoutInternal(schema) } };
+        else if (source === "form") {
+            const stripped = withoutInternal(schema);
+            const binary = Object.values(isRecord(schema.properties) ? schema.properties : {}).some(isBinaryPart);
+            body = binary ? { "multipart/form-data": { schema: stripped } } : {};
+            body["application/x-www-form-urlencoded"] = { schema: stripped };
+        }
+        else if (source === "params") {
+            for (const param of parameters) {
+                const declared = isRecord(schema.properties) ? schema.properties[param.name] : undefined;
+                if (declared !== undefined)
+                    param.schema = declared;
+            }
+        }
+        else
+            parameters.push(...propertyParameters(schema, PROPERTY_SOURCES[source]));
+    }
+    return { body, parameters };
+}
+/** The methods a route documents: its own, or for `all()` the standard ones its path leaves free. */
+function methodsOf(route, declared) {
+    if (route.method !== "ALL")
+        return [route.method.toLowerCase()];
+    return ALL_METHODS.filter((m) => !declared.has(`${m} ${route.path}`));
+}
+/** Every operation of `collected`, by public path and method, and the list the document checks run over. */
+export function buildPaths(collected, ctx) {
+    const paths = Object.create(null);
+    const operations = [];
+    const declared = new Set(collected.http.filter((r) => r.method !== "ALL").map((r) => `${r.method.toLowerCase()} ${r.path}`));
+    for (const route of collected.http) {
+        const methods = methodsOf(route, declared);
+        const path = publicPath(route.path, ctx.trailingSlash);
+        const convert = ctx.convert(`${route.method} ${route.pattern}`);
+        const name = (role, status = 200) => deriveSchemaName(role === "request"
+            ? { method: methods[0], path, role }
+            : { method: methods[0], path, role, status });
+        const { body, parameters } = inputsOf(route.input, convert, name("request"), pathParameters(route));
+        const { errors, responses } = ctx.responses(route, convert, (code) => name("response", code));
+        for (const method of methods) {
+            const operation = { ...ctx.policy(route, method.toUpperCase(), "http"), "x-honey-route": route.id };
+            if (body !== null)
+                operation.requestBody = { content: structuredClone(body), required: true };
+            if (parameters.length > 0)
+                operation.parameters = structuredClone(parameters);
+            operation.responses = structuredClone(responses);
+            if (Object.keys(errors).length > 0)
+                operation["x-honey-errors"] = structuredClone(errors);
+            paths[path] ??= {};
+            paths[path][method] = operation;
+            operations.push({ method, operation, path, route });
+        }
+    }
+    for (const route of collected.ws) {
+        const path = publicPath(route.path, ctx.trailingSlash);
+        if (paths[path]?.get !== undefined) {
+            ctx.warn("WS_SHADOWED", `WS ${route.pattern}: GET ${path} is an HTTP operation; the websocket route is left out of the document`);
+            continue;
+        }
+        const hint = deriveSchemaName({ method: "get", path, role: "request" });
+        const search = route.input?.search;
+        const input = search === undefined ? null : { search };
+        const { parameters } = inputsOf(input, ctx.convert(`WS ${route.pattern}`), hint, pathParameters(route));
+        const operation = { "x-websocket": true, ...ctx.policy(route, "WS", "ws"), "x-honey-route": route.id };
+        if (parameters.length > 0)
+            operation.parameters = parameters;
+        operation.responses = { "101": { description: "WebSocket upgrade" } };
+        paths[path] ??= {};
+        paths[path].get = operation;
+        operations.push({ method: "get", operation, path, route });
+    }
+    return { operations, paths };
+}
+/**
+ * Make operationIds unique. One registration the document expands into several operations
+ * (`.on([...])`, `all()`, an optional param) keeps its id with a method or variant suffix; two
+ * registrations declaring one id is an authoring error.
+ */
+export function assignOperationIds(operations, error) {
+    const byId = new Map();
+    for (const entry of operations) {
+        const id = entry.operation.operationId;
+        if (typeof id === "string")
+            byId.set(id, [...(byId.get(id) ?? []), entry]);
+    }
+    const used = new Set(byId.keys());
+    for (const [id, group] of byId) {
+        if (group.length < 2)
+            continue;
+        /* a WS route is its own registration: its id, shared by its variants */
+        if (new Set(group.map(({ route }) => ("registration" in route ? route.registration : route.id))).size > 1) {
+            const where = group.map((g) => `${g.method.toUpperCase()} ${g.path}`).join(", ");
+            error(`operationId "${id}" is declared by more than one route (${where}); operationIds must be unique`);
+            continue;
+        }
+        const methods = new Set(group.map((g) => g.method));
+        const fewest = Math.min(...group.map((g) => g.route.params.length));
+        for (const entry of group) {
+            let next = methods.size > 1 ? `${id}_${entry.method}` : id;
+            const extra = entry.route.params.slice(fewest);
+            if (extra.length > 0)
+                next += `_with_${extra.join("_")}`;
+            if (next === id)
+                continue;
+            while (used.has(next))
+                next += "_";
+            used.add(next);
+            entry.operation.operationId = next;
+        }
+    }
+}

package/dist/openapi/register.d.ts

@@ -1,3 +1,14 @@
-export declare function enableOpenApi(): void;
-export { spec } from "./spec.ts";
-//# sourceMappingURL=register.d.ts.map
+/**
+ * `@lovrozagar/honey/openapi`: the app's OpenAPI 3.1 document and route manifest, generated or
+ * served, and the docs pages. A plain subpath: nothing registers itself, and an app that never
+ * imports it carries none of it.
+ */
+export { SERVED } from "../routing/register.ts";
+export type { OpenApiDocument, OpenApiInfo } from "./document.ts";
+export { type GenerateOpenApiOptions, generateOpenApi, type OpenApiExternalDocs, type OpenApiRouteInfo, type OpenApiServer, type OpenApiServerVariable, type OpenApiTag, type OpenApiWebhook, type WebhookSignature, } from "./generate.ts";
+export { type GenerateManifestOptions, generateManifest, type ManifestError, type ManifestRoute, type RouteManifest, } from "./manifest.ts";
+export { type DocsConfig, inlineJson } from "./docs-page.ts";
+export { scalar } from "./scalar.ts";
+export { type ServeManifestOptions, type ServeOpenApiOptions, serveManifest, serveOpenApi } from "./serve.ts";
+export { swagger } from "./swagger.ts";
+export { toYaml } from "./yaml.ts";