@lovrozagar/honey 0.7.3 → 1.0.0-rc.3

package/dist/openapi/document.js

@@ -1,695 +1,3 @@
-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; a gateway route documents the
-               keys its downstream app declared against that app's factory, the rest against its own */
-            const routeFactory = handler.fac ?? factory;
-            const sourceFactory = handler.sfac ?? null;
-            const factories = sourceFactory === null ? [routeFactory] : [sourceFactory, routeFactory];
-            addErrorResponses(responses, handler, {
-                baseErrorJsonSchema,
-                customErrorAddsSchema,
-                errorMeta: factories.map((f) => (f === factory ? errorMeta : getErrorMeta(f))),
-                factories,
-            });
-        }
-        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 };
@@ -697,93 +5,26 @@ function cleanInfo(info) {
         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 at = Math.max(ctx.factories.findIndex((f) => f?.[ek] !== undefined), 0);
-        const info = resolveErrorInfo(ek, ctx.factories[at] ?? null);
-        if (info.status <= 0)
-            continue;
-        let entries = byStatus.get(info.status);
-        if (!entries) {
-            entries = [];
-            byStatus.set(info.status, entries);
-        }
-        const meta = ctx.errorMeta[at]?.[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;
+/** The document of `parts`: each optional field only when there is something to put in it. */
+export function assembleDocument(parts) {
+    const doc = {
+        openapi: "3.1.0",
+        info: cleanInfo(parts.info),
+        ...(parts.servers.length > 0 ? { servers: [...parts.servers] } : {}),
+        paths: { ...parts.paths },
     };
-    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`);
-        }
-    }
+    if (Object.keys(parts.webhooks).length > 0)
+        doc.webhooks = parts.webhooks;
+    const components = {};
+    if (Object.keys(parts.schemas).length > 0)
+        components.schemas = parts.schemas;
+    if (parts.securitySchemes !== undefined)
+        components.securitySchemes = { ...parts.securitySchemes };
+    if (Object.keys(components).length > 0)
+        doc.components = components;
+    if (parts.tags.length > 0)
+        doc.tags = [...parts.tags];
+    if (parts.externalDocs !== undefined)
+        doc.externalDocs = structuredClone(parts.externalDocs);
+    return doc;
 }
-//# sourceMappingURL=document.js.map