@lovrozagar/honey 0.6.8 → 0.7.1

package/dist/openapi/document.js

@@ -0,0 +1,785 @@
+import { deriveSchemaName, sanitizeComponentName } from "../codegen-schema-naming.js";
+import { ERROR_META } from "../errors.js";
+import { findInvalidSelectors, invalidateLevel, reportMissingInvalidate } from "../invalidate-check.js";
+import { applyMetaSpec, compileMetaSpec, MetaSpecCollector, resolveProfile, securitySchemeNames, } from "../meta-spec.js";
+import { metaSpecOf } from "../meta-spec-merge.js";
+import { parsePattern, UNNAMED_WILDCARD } from "../pattern.js";
+import { statusKeyToCode } from "../types.js";
+import { collectRoutes, collectWsRoutes, toOpenApiPath, unwrapEntry } from "./collect.js";
+import { getJsonSchemaConverter, instanceJsonSchema } from "./json-schema-slot.js";
+export const DEFAULT_ERROR_JSON_SCHEMA = {
+    properties: {
+        error_key: { type: "string" },
+        fields: {
+            additionalProperties: {
+                items: {
+                    properties: {
+                        error_key: { type: "string" },
+                        message: { type: "string" },
+                        path: { type: "string" },
+                    },
+                    required: ["error_key", "message", "path"],
+                    type: "object",
+                },
+                type: "array",
+            },
+            type: "object",
+        },
+        message: { type: "string" },
+        status: { type: "integer" },
+        status_key: { type: "string" },
+        success: { const: false },
+    },
+    required: ["error_key", "fields", "message", "status", "status_key", "success"],
+    type: "object",
+};
+const STATUS_KEYS_BY_LENGTH = Object.keys(statusKeyToCode).sort((a, b) => b.length - a.length);
+function inferErrorInfo(errorKey) {
+    const exact = statusKeyToCode[errorKey];
+    if (exact !== undefined) {
+        if (exact < 400)
+            return null;
+        return { errorKey, status: exact, statusKey: errorKey };
+    }
+    for (const statusKey of STATUS_KEYS_BY_LENGTH) {
+        if (!errorKey.endsWith(`_${statusKey}`))
+            continue;
+        const status = statusKeyToCode[statusKey];
+        if (status < 400)
+            continue;
+        return { errorKey, status, statusKey };
+    }
+    return null;
+}
+function resolveErrorInfo(errorKey, factory) {
+    if (factory?.[errorKey]) {
+        try {
+            const err = factory[errorKey]();
+            return { errorKey, status: err.status, statusKey: err.statusKey };
+        }
+        catch {
+            /* factory call failed — fall through to suffix inference */
+        }
+    }
+    return inferErrorInfo(errorKey) ?? { errorKey, status: 0, statusKey: "unknown" };
+}
+function getErrorFactory(app) {
+    return app._errorFactory;
+}
+function getErrorSchema(app) {
+    return app._errorSchema;
+}
+function getCustomErrorSchema(app) {
+    return app._customErrorSchema;
+}
+function getErrorMeta(factory) {
+    if (!factory)
+        return null;
+    return factory[ERROR_META] ?? null;
+}
+function getMetaSpecConfig(app) {
+    return metaSpecOf(app);
+}
+function cloneJson(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        return JSON.parse(JSON.stringify(value));
+    }
+}
+function stripInternalProps(schema) {
+    const props = schema.properties;
+    if (!props)
+        return schema;
+    const filtered = {};
+    for (const [key, val] of Object.entries(props)) {
+        if (val?.["x-internal"] === true)
+            continue;
+        filtered[key] = val;
+    }
+    const required = schema.required;
+    const result = { ...schema, properties: filtered };
+    if (required) {
+        result.required = required.filter((k) => filtered[k] !== undefined);
+    }
+    return result;
+}
+const BINARY_FORM_FORMATS = new Set(["binary", "byte", "file"]);
+function isBinaryFormPart(schema) {
+    if (!schema)
+        return false;
+    const format = schema.format;
+    if (typeof format === "string" && BINARY_FORM_FORMATS.has(format))
+        return true;
+    if (schema.type === "file")
+        return true;
+    if (schema.type === "array") {
+        const items = schema.items;
+        if (items !== null && typeof items === "object" && !Array.isArray(items)) {
+            return isBinaryFormPart(items);
+        }
+    }
+    return false;
+}
+function formSchemaHasBinaryPart(schema) {
+    const props = schema.properties;
+    if (!props)
+        return false;
+    for (const prop of Object.values(props)) {
+        if (isBinaryFormPart(prop))
+            return true;
+    }
+    return false;
+}
+function asJsonSchema(entry, io = "output") {
+    if (entry !== null && entry !== undefined && "~standard" in entry) {
+        const convert = getJsonSchemaConverter() ?? instanceJsonSchema;
+        return convert(entry, io);
+    }
+    return entry;
+}
+function primaryOutputSchema(handler) {
+    const json = handler.os?.["application/json"];
+    if (!json)
+        return null;
+    let best = null;
+    for (const [statusKey, schema] of Object.entries(json)) {
+        if (schema === undefined)
+            continue;
+        const code = statusKeyToCode[statusKey];
+        if (!code || code < 200 || code > 299)
+            continue;
+        if (!best || code < best.code)
+            best = { code, schema: schema };
+    }
+    return best?.schema ?? null;
+}
+function schemaChildren(node) {
+    const out = [];
+    const push = (value) => {
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            out.push(value);
+        }
+    };
+    const props = node.properties;
+    if (props !== null && typeof props === "object" && !Array.isArray(props)) {
+        for (const child of Object.values(props))
+            push(child);
+    }
+    push(node.items);
+    for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+        const members = node[key];
+        if (Array.isArray(members)) {
+            for (const member of members)
+                push(member);
+        }
+    }
+    return out;
+}
+function searchSchemaKey(root, key, maxDepth) {
+    let level = [root];
+    for (let depth = 0; depth <= maxDepth && level.length > 0; depth++) {
+        const matches = [];
+        const seen = new Set();
+        for (const node of level) {
+            if (!Object.hasOwn(node, key) || node[key] === undefined)
+                continue;
+            const fingerprint = JSON.stringify(node[key]) ?? "undefined";
+            if (seen.has(fingerprint))
+                continue;
+            seen.add(fingerprint);
+            matches.push(node[key]);
+        }
+        if (matches.length === 1)
+            return { found: true, value: matches[0] };
+        if (matches.length > 1)
+            return { found: "ambiguous", values: matches };
+        const next = [];
+        for (const node of level)
+            next.push(...schemaChildren(node));
+        level = next;
+    }
+    return { found: false };
+}
+const DEEP_SEARCH_MAX_DEPTH = 6;
+function makeSchemaMetaLookup(handler) {
+    const cache = new Map();
+    const rootOf = (source) => {
+        if (cache.has(source))
+            return cache.get(source);
+        let schema = null;
+        let io = "output";
+        if (source === "output") {
+            schema = primaryOutputSchema(handler);
+        }
+        else {
+            io = "input";
+            const key = source.slice("input.".length);
+            const entry = handler.iv?.[key];
+            schema = entry ? unwrapEntry(entry) : null;
+        }
+        let root;
+        if (schema) {
+            const converted = asJsonSchema(schema, io);
+            root = converted && typeof converted === "object" ? converted : undefined;
+        }
+        cache.set(source, root);
+        return root;
+    };
+    return (source, key, search) => {
+        const root = rootOf(source);
+        if (!root)
+            return { found: false };
+        if (search === "deep")
+            return searchSchemaKey(root, key, DEEP_SEARCH_MAX_DEPTH);
+        if (Object.hasOwn(root, key) && root[key] !== undefined)
+            return { found: true, value: root[key] };
+        if (root.type === "array") {
+            const items = root.items;
+            if (items !== null && typeof items === "object" && !Array.isArray(items)) {
+                const itemRoot = items;
+                if (Object.hasOwn(itemRoot, key) && itemRoot[key] !== undefined) {
+                    return { found: true, value: itemRoot[key] };
+                }
+            }
+        }
+        return { found: false };
+    };
+}
+/** Methods an OpenAPI path item can hold. Anything else cannot be described and is skipped. */
+const OPENAPI_METHODS = new Set(["delete", "get", "head", "options", "patch", "post", "put", "trace"]);
+/** What `app.all()` documents: every method a client would send to it, unless the path declares that method itself. */
+const ALL_METHODS = ["get", "post", "put", "patch", "delete"];
+function appSettings(app) {
+    return app._graph?.settings ?? {};
+}
+/** The URL path a client sends for a route path: `trailingSlash("enforce")` adds a slash. */
+function publicPath(path, settings) {
+    if (settings.trailingSlash === "enforce" && path.length > 1 && !path.endsWith("/"))
+        return `${path}/`;
+    return path;
+}
+function isMetaInternal(meta) {
+    return meta?.internal === true;
+}
+/** Path parameters of a concrete route path. Every path parameter is required in OpenAPI. */
+function pathParameters(path) {
+    const out = [];
+    for (const seg of parsePattern(path)) {
+        if (seg.k === "param") {
+            out.push({ in: "path", name: seg.n, required: true, schema: { type: "string" } });
+        }
+        else if (seg.k === "wildcard") {
+            out.push({
+                description: "The rest of the path; may contain `/`.",
+                in: "path",
+                name: seg.n === UNNAMED_WILDCARD ? "wildcard" : seg.n,
+                required: true,
+                schema: { type: "string" },
+                "x-honey-wildcard": true,
+            });
+        }
+    }
+    return out;
+}
+/** Add a response, merging content types and headers into one already declared for the status. */
+function addResponse(responses, status, description, content, headers) {
+    const existing = responses[status];
+    if (existing === undefined) {
+        const response = {};
+        if (content)
+            response.content = content;
+        response.description = description;
+        if (headers)
+            response.headers = headers;
+        responses[status] = response;
+        return;
+    }
+    if (headers)
+        existing.headers = { ...existing.headers, ...headers };
+    if (content)
+        existing.content = { ...existing.content, ...content };
+}
+/**
+ * Turn a converted schema's local references into component references.
+ *
+ * Converters write `$ref: "#"` for recursion and `#/$defs/<name>` for shared nodes — relative
+ * to the schema's own root. In an OpenAPI document `#` is the document, so each is hoisted into
+ * `components.schemas` and the reference rewritten to point at it.
+ */
+class LocalRefHoister {
+    components = Object.create(null);
+    taken;
+    constructor(taken) {
+        this.taken = taken;
+    }
+    reserve(base) {
+        const clean = sanitizeComponentName(base) || "Schema";
+        let name = clean;
+        for (let n = 2; this.taken(name) || Object.hasOwn(this.components, name); n++)
+            name = `${clean}${n}`;
+        this.components[name] = {};
+        return name;
+    }
+    hoist(schema, hint) {
+        const defs = schema.$defs ?? schema.definitions;
+        const hasDefs = defs !== null && typeof defs === "object" && Object.keys(defs).length > 0;
+        const selfRef = refersTo(schema, "#");
+        if (!hasDefs && !selfRef)
+            return schema;
+        const rootName = selfRef ? this.reserve(hint) : null;
+        const defNames = new Map();
+        if (hasDefs) {
+            for (const key of Object.keys(defs)) {
+                defNames.set(key, this.reserve(key.startsWith("__schema") ? `${hint}${key.slice(8)}` : key));
+            }
+        }
+        const rewrite = (ref) => {
+            if (ref === "#" && rootName !== null)
+                return `#/components/schemas/${rootName}`;
+            for (const prefix of ["#/$defs/", "#/definitions/"]) {
+                if (!ref.startsWith(prefix))
+                    continue;
+                const name = defNames.get(decodePointer(ref.slice(prefix.length)));
+                if (name !== undefined)
+                    return `#/components/schemas/${name}`;
+            }
+            return null;
+        };
+        for (const [key, name] of defNames) {
+            this.components[name] = rewriteRefs(defs[key], rewrite);
+        }
+        const { $defs: _defs, definitions: _definitions, ...rest } = schema;
+        const root = rewriteRefs(rest, rewrite);
+        if (rootName === null)
+            return root;
+        this.components[rootName] = root;
+        return { $ref: `#/components/schemas/${rootName}` };
+    }
+}
+function decodePointer(token) {
+    return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+/** Keys whose values are data, not schemas: a `$ref` inside them is a value, not a reference. */
+const DATA_KEYS = new Set(["const", "default", "enum", "example", "examples"]);
+function refersTo(node, target) {
+    if (Array.isArray(node))
+        return node.some((item) => refersTo(item, target));
+    if (node === null || typeof node !== "object")
+        return false;
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "$ref" && value === target)
+            return true;
+        if (DATA_KEYS.has(key))
+            continue;
+        if (refersTo(value, target))
+            return true;
+    }
+    return false;
+}
+function rewriteRefs(node, rewrite) {
+    const walk = (value) => {
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value === null || typeof value !== "object")
+            return value;
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            if (key === "$ref" && typeof child === "string") {
+                out[key] = rewrite(child) ?? child;
+            }
+            else if (DATA_KEYS.has(key)) {
+                out[key] = child;
+            }
+            else {
+                out[key] = walk(child);
+            }
+        }
+        return out;
+    };
+    return walk(node);
+}
+function operationIdOf(operation) {
+    return typeof operation.operationId === "string" ? operation.operationId : null;
+}
+/**
+ * Make `operationId`s unique. One route that the document expands into several operations
+ * (`.on(["GET","POST"])`, `all()`, an optional param) keeps one meta `operationId`; each
+ * operation gets a method or variant suffix. Two different routes declaring the same id is
+ * an authoring error.
+ */
+function assignOperationIds(emitted, collector) {
+    const byId = new Map();
+    for (const entry of emitted) {
+        const id = operationIdOf(entry.operation);
+        if (id === null)
+            continue;
+        const list = byId.get(id);
+        if (list)
+            list.push(entry);
+        else
+            byId.set(id, [entry]);
+    }
+    const used = new Set(byId.keys());
+    for (const [id, group] of byId) {
+        if (group.length < 2)
+            continue;
+        /* `.on([...])` registers one record per method around one handler function */
+        const handlers = new Set(group.map((g) => g.source));
+        if (handlers.size > 1) {
+            const where = group.map((g) => `${g.method.toUpperCase()} ${g.path}`).join(", ");
+            collector.add("DUPLICATE_OPERATION_ID", "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 minParams = Math.min(...group.map((g) => g.params.length));
+        for (const entry of group) {
+            let next = id;
+            if (methods.size > 1)
+                next += `_${entry.method}`;
+            const extra = entry.params.slice(minParams);
+            if (extra.length > 0)
+                next += `_with_${extra.join("_")}`;
+            if (next === id)
+                continue;
+            while (used.has(next))
+                next += "_";
+            used.add(next);
+            entry.operation.operationId = next;
+        }
+    }
+}
+export function generateOpenApiFromTree(app, options) {
+    const collector = new MetaSpecCollector();
+    const metaSpec = compileMetaSpec(getMetaSpecConfig(app), collector);
+    const { filter: profileFilter, name: profileName } = resolveProfile(metaSpec, options.profile, collector);
+    const factory = getErrorFactory(app);
+    const errorMeta = getErrorMeta(factory);
+    const settings = appSettings(app);
+    const hoister = new LocalRefHoister(() => false);
+    const rawErrorSchema = getErrorSchema(app);
+    const baseErrorJsonSchema = rawErrorSchema ? asJsonSchema(rawErrorSchema) : DEFAULT_ERROR_JSON_SCHEMA;
+    const rawCustomErrorSchema = getCustomErrorSchema(app);
+    const customErrorAddsSchema = rawCustomErrorSchema ? asJsonSchema(rawCustomErrorSchema) : null;
+    const collected = collectRoutes(app);
+    const routeFilter = options.filterRoutes;
+    const paths = Object.create(null);
+    const emitted = [];
+    const operations = [];
+    /* explicit methods per path — `all()` documents only the methods nobody declared */
+    const declared = new Set();
+    for (const { method, path } of collected) {
+        if (method !== "ALL")
+            declared.add(`${method.toLowerCase()} ${path}`);
+    }
+    const shortestParams = new Map();
+    for (const { handler, path } of collected) {
+        const n = pathParameters(path).length;
+        const prev = shortestParams.get(handler);
+        if (prev === undefined || n < prev)
+            shortestParams.set(handler, n);
+    }
+    for (const { handler, method, path } of collected) {
+        const meta = (handler.mt ?? null);
+        if (isMetaInternal(meta))
+            continue;
+        if (routeFilter && !routeFilter({ meta: (meta ?? {}), method, path }))
+            continue;
+        const methods = method === "ALL"
+            ? ALL_METHODS.filter((m) => !declared.has(`${m} ${path}`))
+            : [method.toLowerCase()].filter((m) => {
+                if (OPENAPI_METHODS.has(m))
+                    return true;
+                collector.add("UNSUPPORTED_METHOD", "warn", `${method} ${path}: OpenAPI cannot describe the ${method} method; the route is left out of the document`);
+                return false;
+            });
+        if (methods.length === 0)
+            continue;
+        const oaPath = publicPath(toOpenApiPath(path), settings);
+        const params = pathParameters(path);
+        const schemaHint = (role, status) => role === "request"
+            ? deriveSchemaName({ method: methods[0], path: oaPath, role })
+            : deriveSchemaName({ method: methods[0], path: oaPath, role, status: status ?? 200 });
+        /* the parts that do not depend on the method are built once per route */
+        const parameters = params.map((p) => ({ ...p }));
+        let requestBody = null;
+        const responses = {};
+        if (handler.iv) {
+            const body = {};
+            for (const [source, entry] of Object.entries(handler.iv)) {
+                if (entry === undefined)
+                    continue;
+                const unwrapped = unwrapEntry(entry);
+                const jsonSchema = asJsonSchema(unwrapped, "input");
+                if (source === "json" || source === "form") {
+                    const schema = hoister.hoist(stripInternalProps(jsonSchema), schemaHint("request"));
+                    if (source === "form") {
+                        if (formSchemaHasBinaryPart(jsonSchema))
+                            body["multipart/form-data"] = { schema };
+                        body["application/x-www-form-urlencoded"] = { schema };
+                    }
+                    else {
+                        body["application/json"] = { schema };
+                    }
+                }
+                else if (source === "search" || source === "headers" || source === "cookies") {
+                    let location = "cookie";
+                    if (source === "search")
+                        location = "query";
+                    else if (source === "headers")
+                        location = "header";
+                    parameters.push(...propertyParameters(jsonSchema, location, hoister, schemaHint("request")));
+                }
+                else if (source === "params") {
+                    const props = jsonSchema.properties;
+                    if (props) {
+                        for (const param of parameters) {
+                            if (param.in !== "path" || !Object.hasOwn(props, param.name))
+                                continue;
+                            param.schema = props[param.name];
+                        }
+                    }
+                }
+            }
+            if (Object.keys(body).length > 0)
+                requestBody = { content: body, required: true };
+        }
+        if (handler.os) {
+            for (const [contentType, schemas] of Object.entries(handler.os)) {
+                if (schemas === undefined)
+                    continue;
+                if (contentType === "redirect") {
+                    for (const statusKey of Object.keys(schemas)) {
+                        const statusCode = statusKeyToCode[statusKey];
+                        if (!statusCode)
+                            continue;
+                        addResponse(responses, String(statusCode), statusKey.replace(/_/g, " "), null, {
+                            Location: {
+                                description: "Redirect target URL",
+                                schema: { format: "uri", type: "string" },
+                            },
+                        });
+                    }
+                    continue;
+                }
+                for (const [statusKey, schema] of Object.entries(schemas)) {
+                    if (schema === undefined)
+                        continue;
+                    const statusCode = statusKeyToCode[statusKey];
+                    if (!statusCode)
+                        continue;
+                    const converted = asJsonSchema(schema);
+                    addResponse(responses, String(statusCode), statusKey.replace(/_/g, " "), { [contentType]: { schema: hoister.hoist(converted, schemaHint("response", statusCode)) } }, null);
+                }
+            }
+        }
+        if (handler.ek.size > 0) {
+            /* a mounted sub-app's route keeps its own error factory */
+            const routeFactory = handler.fac ?? factory;
+            addErrorResponses(responses, handler, {
+                baseErrorJsonSchema,
+                customErrorAddsSchema,
+                errorMeta: routeFactory === factory ? errorMeta : getErrorMeta(routeFactory),
+                factory: routeFactory,
+            });
+        }
+        if (Object.keys(responses).length === 0) {
+            responses["200"] = { description: "Success" };
+        }
+        for (const methodKey of methods) {
+            const operation = {};
+            applyMetaSpec({
+                collector,
+                filter: profileFilter,
+                kind: "http",
+                meta,
+                method: methodKey.toUpperCase(),
+                operation,
+                path,
+                profile: profileName,
+                schemaMeta: metaSpec.needsSchemas ? makeSchemaMetaLookup(handler) : undefined,
+                spec: metaSpec,
+            });
+            if (requestBody)
+                operation.requestBody = methods.length > 1 ? cloneJson(requestBody) : requestBody;
+            if (parameters.length > 0)
+                operation.parameters = methods.length > 1 ? cloneJson(parameters) : parameters;
+            operation.responses = methods.length > 1 ? cloneJson(responses) : responses;
+            const pathItem = paths[oaPath] ?? (paths[oaPath] = {});
+            pathItem[methodKey] = operation;
+            operations.push({
+                handler,
+                method: methodKey,
+                source: handler.fn ?? handler,
+                operation,
+                params: params.slice(shortestParams.get(handler) ?? 0).map((p) => p.name),
+                path: oaPath,
+            });
+            emitted.push({ meta, method: methodKey, operation, path: oaPath });
+        }
+    }
+    const wsRoutes = collectWsRoutes(app);
+    for (const { handler, path } of wsRoutes) {
+        const meta = handler.mt;
+        if (isMetaInternal(meta))
+            continue;
+        if (routeFilter && !routeFilter({ meta: (meta ?? {}), method: "WS", path }))
+            continue;
+        const oaPath = publicPath(toOpenApiPath(path), settings);
+        if (paths[oaPath]?.get !== undefined) {
+            collector.add("WS_SHADOWED", "warn", `WS ${path}: GET ${oaPath} is an HTTP operation; the websocket route is left out of the document`);
+            continue;
+        }
+        const operation = { "x-websocket": true };
+        const parameters = pathParameters(path);
+        applyMetaSpec({
+            collector,
+            filter: profileFilter,
+            kind: "ws",
+            meta,
+            method: "WS",
+            operation,
+            path,
+            profile: profileName,
+            schemaMeta: metaSpec.needsSchemas ? makeSchemaMetaLookup(handler) : undefined,
+            spec: metaSpec,
+        });
+        const searchEntry = handler.iv?.search;
+        if (searchEntry) {
+            const jsonSchema = asJsonSchema(unwrapEntry(searchEntry), "input");
+            const hint = deriveSchemaName({ method: "get", path: oaPath, role: "request" });
+            parameters.push(...propertyParameters(jsonSchema, "query", hoister, hint));
+        }
+        if (parameters.length > 0)
+            operation.parameters = parameters;
+        operation.responses = { "101": { description: "WebSocket upgrade" } };
+        const pathItem = paths[oaPath] ?? (paths[oaPath] = {});
+        pathItem.get = operation;
+        operations.push({ handler, method: "get", operation, params: [], path: oaPath, source: handler.fn ?? handler });
+    }
+    assignOperationIds(operations, collector);
+    checkSecurityReferences(operations, options.securitySchemes, collector);
+    if (invalidateLevel(options.invalidate) !== "off") {
+        const inventory = new Set(collected.map((r) => `${r.method} ${r.path}`));
+        for (const bad of findInvalidSelectors(emitted, inventory)) {
+            collector.add("INVALID_SELECTOR", "error", `${bad.method} ${bad.path}: invalidate selector ${JSON.stringify(bad.selector)} names no route ` +
+                '— write "<METHOD> <pattern>" for a registered route, e.g. "GET /users/:id"');
+        }
+    }
+    collector.flush();
+    reportMissingInvalidate(emitted, options.invalidate);
+    const result = {
+        info: cleanInfo(options.info),
+        openapi: "3.1.0",
+        paths: { ...paths },
+    };
+    if (settings.stripPrefix) {
+        result.servers = [{ url: settings.stripPrefix }];
+    }
+    const hoisted = Object.keys(hoister.components).length > 0 ? { ...hoister.components } : null;
+    if (hoisted || options.securitySchemes) {
+        result.components = {};
+        if (hoisted)
+            result.components.schemas = hoisted;
+        if (options.securitySchemes)
+            result.components.securitySchemes = options.securitySchemes;
+    }
+    return result;
+}
+/** Only the Info Object's own fields: callers pass their whole options bag. */
+function cleanInfo(info) {
+    const out = { title: info.title, version: info.version };
+    if (typeof info.description === "string")
+        out.description = info.description;
+    return out;
+}
+/** One parameter per property of an object schema (`search`, `headers`, `cookies`). */
+function propertyParameters(jsonSchema, location, hoister, hint) {
+    const out = [];
+    const hoisted = hoister.hoist(jsonSchema, hint);
+    /* a recursive search schema hoists its root; its properties are still the parameters */
+    const root = hoisted.$ref === undefined ? hoisted : jsonSchema;
+    const props = root.properties;
+    if (!props)
+        return out;
+    const required = new Set(root.required ?? []);
+    for (const name of Object.keys(props)) {
+        const propSchema = props[name];
+        if (propSchema?.["x-internal"] === true)
+            continue;
+        out.push({ in: location, name, required: required.has(name), schema: propSchema ?? {} });
+    }
+    return out;
+}
+function addErrorResponses(responses, handler, ctx) {
+    const byStatus = new Map();
+    for (const ek of handler.ek) {
+        const info = resolveErrorInfo(ek, ctx.factory);
+        if (info.status <= 0)
+            continue;
+        let entries = byStatus.get(info.status);
+        if (!entries) {
+            entries = [];
+            byStatus.set(info.status, entries);
+        }
+        const meta = ctx.errorMeta?.[ek];
+        let customSchema = null;
+        if (meta?.schema) {
+            const converted = asJsonSchema(meta.schema);
+            if (converted && Object.keys(converted).length > 0) {
+                customSchema = ctx.customErrorAddsSchema ? { allOf: [converted, ctx.customErrorAddsSchema] } : converted;
+            }
+        }
+        entries.push({ key: ek, schema: customSchema });
+    }
+    const standardSchema = (status, keys) => {
+        const schema = cloneJson(ctx.baseErrorJsonSchema);
+        const props = schema.properties;
+        if (props?.error_key)
+            props.error_key = { enum: [...keys].sort(), type: "string" };
+        if (props?.status)
+            props.status = { enum: [status], type: "integer" };
+        return schema;
+    };
+    for (const [status, entries] of byStatus) {
+        if (responses[String(status)] !== undefined)
+            continue;
+        const standardKeys = entries.filter((e) => !e.schema).map((e) => e.key);
+        const customSchemas = entries.filter((e) => e.schema).map((e) => e.schema);
+        let schema;
+        if (customSchemas.length === 0) {
+            schema = standardSchema(status, standardKeys);
+        }
+        else if (standardKeys.length === 0 && customSchemas.length === 1) {
+            schema = customSchemas[0];
+        }
+        else {
+            const schemas = [];
+            if (standardKeys.length > 0)
+                schemas.push(standardSchema(status, standardKeys));
+            schemas.push(...customSchemas);
+            schema = { oneOf: schemas };
+        }
+        responses[String(status)] = {
+            content: { "application/json": { schema } },
+            description: entries
+                .map((e) => e.key)
+                .sort()
+                .join(", "),
+        };
+    }
+}
+/** Every scheme an operation's `security` names must exist in `components.securitySchemes`. */
+function checkSecurityReferences(operations, schemes, collector) {
+    for (const { method, operation, path } of operations) {
+        for (const name of securitySchemeNames(operation.security)) {
+            if (schemes && Object.hasOwn(schemes, name))
+                continue;
+            collector.add("UNKNOWN_SECURITY_SCHEME", schemes ? "error" : "warn", schemes
+                ? `${method.toUpperCase()} ${path}: security names "${name}", which is not in securitySchemes`
+                : `security scheme "${name}" (first used by ${method.toUpperCase()} ${path}) is not declared — pass securitySchemes`);
+        }
+    }
+}
+//# sourceMappingURL=document.js.map