@fluixi/api 0.0.0-stage → 0.1.0-alpha.2

package/dist/openapi.d.ts

@@ -0,0 +1,60 @@
+/**
+ * An OpenAPI 3.1 document, written from the route contracts.
+ *
+ * Nothing is described by hand: parameters, request bodies, responses and error responses all
+ * come from the schemas a route already validates with, so the document cannot drift from what
+ * the server does. Postman, Insomnia, Bruno and code generators import it.
+ *
+ * JSON Schema comes from the validator itself, through the Standard JSON Schema interface
+ * (`~standard.jsonSchema`, implemented by Zod 4). A validator without it can be given a converter
+ * with `setJsonSchemaConverter`; a schema nothing can convert is described as any value and
+ * marked `x-fluixi-unconverted`, so the gap shows in the document instead of breaking it.
+ */
+import type { StandardSchemaV1 } from './standard-schema.js';
+type JsonSchema = Record<string, unknown>;
+type Io = 'input' | 'output';
+/** What a route table entry needs to be described: its path template and its method exports. */
+export interface DescribedRoute {
+    path?: string;
+    mod: Record<string, unknown>;
+}
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+    /** Where the API runs. The first one is what tools like Postman use as the base URL. */
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+}
+export type JsonSchemaConverter = (schema: StandardSchemaV1, io: Io) => JsonSchema | undefined;
+/** For a validator that does not implement Standard JSON Schema (Valibot: `@valibot/to-json-schema`). */
+export declare function setJsonSchemaConverter(converter: JsonSchemaConverter | undefined): void;
+type OpenApiSource = () => Record<string, unknown> | Promise<Record<string, unknown>>;
+/**
+ * A handler whose routes a library describes itself: an auth engine, a webhook receiver. The
+ * library's own OpenAPI document replaces this route in the API's, with its paths under the
+ * route's path, minus a trailing parameter:
+ *
+ * ```ts
+ * // src/api/auth/[...all].ts, described as /api/auth/sign-in/email and the rest
+ * export const GET = describedBy(() => auth.api.generateOpenAPISchema(), (request) => auth.handler(request));
+ * export const POST = GET;
+ * ```
+ */
+export declare function describedBy<H extends (...args: any[]) => unknown>(document: OpenApiSource, handler: H): H;
+export declare function createOpenApiDocument(routes: readonly DescribedRoute[], info: OpenApiInfo): Record<string, unknown>;
+/**
+ * A route that serves the document: `export const GET = openApiRoute(() => apiRoutes, info)` in
+ * `src/api/openapi.json.ts`. The table is read per request, since this route is in it.
+ */
+export declare function openApiRoute(routes: () => readonly DescribedRoute[], info: OpenApiInfo): () => Promise<Response>;
+/**
+ * Adds another document's paths under `mount`, its tags, and its components. A component whose
+ * name is taken by a different one is renamed after the mount (`/api/auth` gives `AuthUser`),
+ * with its references, and so is a clashing operation id (`authGetOrganization`).
+ */
+export declare function includeDocument(target: Record<string, unknown>, source: Record<string, unknown>, mount: string): void;
+export {};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1C,KAAK,EAAE,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7B,gGAAgG;AAChG,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnD;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAAE,EAAE,KAAK,UAAU,GAAG,SAAS,CAAC;AAI/F,yGAAyG;AACzG,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAEvF;AAUD,KAAK,aAAa,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAGzG;AAkBD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqBnH;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,SAAS,cAAc,EAAE,EAAE,IAAI,EAAE,WAAW,SAE3D,OAAO,CAAC,QAAQ,CAAC,CAS5C;AAiBD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA+DrH"}

package/dist/openapi.js

@@ -0,0 +1,312 @@
+import { contractOf } from './route.js';
+let convert;
+/** For a validator that does not implement Standard JSON Schema (Valibot: `@valibot/to-json-schema`). */
+export function setJsonSchemaConverter(converter) {
+    convert = converter;
+}
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+/** Marks a handler that serves the description itself, which the description leaves out. */
+const DESCRIBES = Symbol.for('fluixi.api.describes');
+/** Holds the document of a handler that hands its requests to a library, set by `describedBy`. */
+const DESCRIBED_BY = Symbol.for('fluixi.api.described-by');
+/**
+ * A handler whose routes a library describes itself: an auth engine, a webhook receiver. The
+ * library's own OpenAPI document replaces this route in the API's, with its paths under the
+ * route's path, minus a trailing parameter:
+ *
+ * ```ts
+ * // src/api/auth/[...all].ts, described as /api/auth/sign-in/email and the rest
+ * export const GET = describedBy(() => auth.api.generateOpenAPISchema(), (request) => auth.handler(request));
+ * export const POST = GET;
+ * ```
+ */
+export function describedBy(document, handler) {
+    Object.defineProperty(handler, DESCRIBED_BY, { value: document });
+    return handler;
+}
+const ERROR_SCHEMA = {
+    type: 'object',
+    required: ['error'],
+    properties: {
+        error: {
+            type: 'object',
+            required: ['code', 'message'],
+            properties: {
+                code: { type: 'string', description: 'Machine-readable, stable: `validation_failed`, `not_found`, `internal`.' },
+                message: { type: 'string', description: 'For people. May change between versions.' },
+                details: { description: 'For `validation_failed`, the list of `{ path, message }` issues.' },
+            },
+        },
+    },
+};
+export function createOpenApiDocument(routes, info) {
+    const paths = {};
+    const securitySchemes = {};
+    for (const route of routes) {
+        if (!route.path)
+            continue;
+        for (const method of METHODS) {
+            const handler = route.mod[method.toUpperCase()];
+            if (typeof handler !== 'function')
+                continue;
+            const marks = handler;
+            if (marks[DESCRIBES] || marks[DESCRIBED_BY])
+                continue;
+            (paths[route.path] ??= {})[method] = operation(method, route.path, contractOf(handler), securitySchemes);
+        }
+    }
+    const { servers, ...rest } = info;
+    return {
+        openapi: '3.1.0',
+        info: rest,
+        ...(servers?.length ? { servers } : {}),
+        paths,
+        components: { schemas: { Error: ERROR_SCHEMA }, ...(Object.keys(securitySchemes).length ? { securitySchemes } : {}) },
+    };
+}
+/**
+ * A route that serves the document: `export const GET = openApiRoute(() => apiRoutes, info)` in
+ * `src/api/openapi.json.ts`. The table is read per request, since this route is in it.
+ */
+export function openApiRoute(routes, info) {
+    let cached;
+    const handler = async () => {
+        cached ??= describe(routes(), info).catch((error) => {
+            cached = undefined;
+            throw error;
+        });
+        return new Response(await cached, { headers: { 'content-type': 'application/json; charset=utf-8' } });
+    };
+    Object.defineProperty(handler, DESCRIBES, { value: true });
+    return handler;
+}
+async function describe(routes, info) {
+    const doc = createOpenApiDocument(routes, info);
+    // One document per source: GET and POST usually share the handler that carries it.
+    const mounts = new Map();
+    for (const route of routes) {
+        if (!route.path)
+            continue;
+        for (const handler of Object.values(route.mod)) {
+            const source = typeof handler === 'function' ? handler[DESCRIBED_BY] : undefined;
+            if (source && !mounts.has(source))
+                mounts.set(source, route.path.replace(/\/\{[^}]+\}$/, ''));
+        }
+    }
+    for (const [source, mount] of mounts)
+        includeDocument(doc, await source(), mount);
+    return JSON.stringify(doc, null, 2);
+}
+/**
+ * Adds another document's paths under `mount`, its tags, and its components. A component whose
+ * name is taken by a different one is renamed after the mount (`/api/auth` gives `AuthUser`),
+ * with its references, and so is a clashing operation id (`authGetOrganization`).
+ */
+export function includeDocument(target, source, mount) {
+    const prefix = pascal(mount.split('/').filter(Boolean).pop() ?? 'included');
+    const components = (target.components ??= {});
+    const prefixed = (name) => prefix + name[0].toUpperCase() + name.slice(1);
+    const renames = new Map();
+    for (const [section, entries] of Object.entries((source.components ?? {}))) {
+        for (const [name, value] of Object.entries(entries)) {
+            const existing = components[section]?.[name];
+            if (existing !== undefined && JSON.stringify(existing) !== JSON.stringify(value)) {
+                renames.set(`#/components/${section}/${name}`, `#/components/${section}/${prefixed(name)}`);
+            }
+        }
+    }
+    const rewrite = (node) => {
+        if (Array.isArray(node))
+            return node.map(rewrite);
+        if (!node || typeof node !== 'object')
+            return node;
+        const out = Object.fromEntries(Object.entries(node).map(([key, value]) => [key, key === '$ref' && typeof value === 'string' ? (renames.get(value) ?? value) : rewrite(value)]));
+        return 'nullable' in out ? nullable(out) : out;
+    };
+    for (const [section, entries] of Object.entries((source.components ?? {}))) {
+        const into = (components[section] ??= {});
+        for (const [name, value] of Object.entries(entries)) {
+            const renamed = renames.has(`#/components/${section}/${name}`) ? prefixed(name) : name;
+            into[renamed] = rewrite(value);
+        }
+    }
+    const paths = (target.paths ??= {});
+    // Operation ids must be unique across the document; ours are kept, an included one that clashes
+    // is renamed after the mount like a component.
+    const ids = new Set(Object.values(paths).flatMap((item) => Object.values(item).map((op) => op?.operationId)));
+    for (const [path, item] of Object.entries((source.paths ?? {}))) {
+        const described = rewrite(item);
+        for (const [method, op] of Object.entries(described)) {
+            // Requirements name a scheme instead of referencing it, so a renamed one is followed here.
+            if (Array.isArray(op.security)) {
+                op.security = op.security.map((requirement) => Object.fromEntries(Object.entries(requirement).map(([name, scopes]) => [
+                    renames.has(`#/components/securitySchemes/${name}`) ? prefixed(name) : name,
+                    scopes,
+                ])));
+            }
+            // Tools name requests after the summary; a library often gives only a description.
+            if (METHODS.includes(method) && !op.summary)
+                op.summary = summaryOf(op, method, mount + path);
+            if (typeof op.operationId === 'string' && ids.has(op.operationId)) {
+                op.operationId = prefix[0].toLowerCase() + prefix.slice(1) + op.operationId[0].toUpperCase() + op.operationId.slice(1);
+            }
+            if (typeof op.operationId === 'string')
+                ids.add(op.operationId);
+        }
+        paths[mount + path] = described;
+    }
+    const tags = (source.tags ?? []);
+    if (tags.length) {
+        const known = (target.tags ??= []);
+        for (const tag of tags)
+            if (!known.some((t) => t.name === tag.name))
+                known.push(tag);
+    }
+}
+/** OpenAPI 3.0's `nullable`, which 3.1 dropped, written as 3.1 says: `null` as one more type. */
+function nullable(schema) {
+    const { nullable: isNullable, ...rest } = schema;
+    if (isNullable !== true)
+        return rest;
+    if (typeof rest.type === 'string')
+        return { ...rest, type: [rest.type, 'null'] };
+    if (Array.isArray(rest.type))
+        return rest.type.includes('null') ? rest : { ...rest, type: [...rest.type, 'null'] };
+    return { anyOf: [rest, { type: 'null' }] };
+}
+function summaryOf(op, method, path) {
+    const description = typeof op.description === 'string' ? op.description.split(/\.\s|\n/)[0].trim() : '';
+    if (description && description.length <= 60)
+        return description.replace(/\.$/, '');
+    return typeof op.operationId === 'string'
+        ? op.operationId.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/^./, (c) => c.toUpperCase())
+        : summaryFor(method, path);
+}
+function pascal(word) {
+    return word
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join('');
+}
+function operation(method, path, contract, schemes) {
+    const operationId = contract?.operationId ?? idFor(method, path);
+    if (!contract) {
+        return {
+            operationId,
+            tags: [tagFor(path)],
+            summary: `${method.toUpperCase()} ${path}`,
+            description: 'This route declares no contract, so nothing about its input or output is known.',
+            'x-fluixi-contract': false,
+            responses: { default: { description: 'Undocumented.' } },
+        };
+    }
+    const parameters = [
+        ...parametersFrom(contract.params, 'path', pathNames(path)),
+        ...parametersFrom(contract.query, 'query', []),
+    ];
+    const success = contract.status ?? (contract.response ? 200 : 204);
+    const responses = {
+        [success]: contract.response
+            ? { description: 'Success.', content: { 'application/json': { schema: schemaFor(contract.response, 'output') } } }
+            : { description: 'Success, no content.' },
+    };
+    const error = (description) => ({ description, content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } });
+    if (contract.params || contract.query || contract.body)
+        responses[400] = error('The request is not valid: `validation_failed`, `invalid_json`.');
+    if (contract.body) {
+        responses[413] = error('The body is over the limit.');
+        responses[415] = error('The body is not JSON.');
+    }
+    const guard = contract.guard;
+    if (guard) {
+        const refuses = guard.refuses ?? [401];
+        if (refuses.includes(401))
+            responses[401] = error('Not signed in: `unauthorized`.');
+        if (refuses.includes(403))
+            responses[403] = error('Signed in, not allowed: `forbidden`, or a more precise code.');
+        if (refuses.includes(503))
+            responses[503] = error('A service the check depends on cannot answer now; try again.');
+    }
+    if (pathNames(path).length)
+        responses[404] = error('Nothing at this path.');
+    responses[500] = error('A fault on the server. Its detail is logged, never sent.');
+    return {
+        operationId,
+        tags: contract.tags?.length ? contract.tags : [tagFor(path)],
+        // Tools name the request after it (Postman does), so there is always one.
+        summary: contract.summary ?? summaryFor(method, path),
+        ...(contract.description ? { description: contract.description } : {}),
+        ...(contract.deprecated ? { deprecated: true } : {}),
+        // Stated on every contracted route, so a public one reads as public rather than unknown.
+        security: security(guard, schemes),
+        ...(parameters.length ? { parameters } : {}),
+        ...(contract.body
+            ? { requestBody: { required: true, content: { 'application/json': { schema: schemaFor(contract.body, 'input') } } } }
+            : {}),
+        responses,
+    };
+}
+function security(guard, schemes) {
+    if (!guard?.security)
+        return [];
+    const { name, scheme, scopes } = guard.security;
+    schemes[name] = scheme;
+    return [{ [name]: scopes ?? [] }];
+}
+/** Path or query parameters, one per property of the object schema. */
+function parametersFrom(schema, where, names) {
+    if (!schema)
+        return where === 'path' ? names.map((name) => ({ name, in: 'path', required: true, schema: { type: 'string' } })) : [];
+    const json = schemaFor(schema, 'input');
+    const properties = (json.properties ?? {});
+    const required = new Set(json.required ?? []);
+    return Object.entries(properties).map(([name, property]) => ({
+        name,
+        in: where,
+        required: where === 'path' ? true : required.has(name),
+        ...(typeof property.description === 'string' ? { description: property.description } : {}),
+        schema: property,
+        ...(where === 'query' && property.type === 'array' ? { style: 'form', explode: true } : {}),
+    }));
+}
+function schemaFor(schema, io) {
+    const standard = schema['~standard'].jsonSchema;
+    try {
+        // OpenAPI 3.1 is JSON Schema 2020-12. `unrepresentable: 'any'` turns a Date or a function
+        // into "any value" instead of an exception, for the libraries that read it (Zod does).
+        const json = standard?.[io]({ target: 'draft-2020-12', libraryOptions: { unrepresentable: 'any' } }) ?? convert?.(schema, io);
+        if (json) {
+            const { $schema: _dialect, ...rest } = json;
+            return rest;
+        }
+    }
+    catch {
+        // Described as any value below, rather than failing the whole document.
+    }
+    return { 'x-fluixi-unconverted': schema['~standard'].vendor };
+}
+function pathNames(path) {
+    return [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+}
+/** `/api/v1/projects/{id}` groups under `projects`: the first segment after the prefix and version. */
+function tagFor(path) {
+    const segments = path.split('/').filter((s) => s && !s.startsWith('{'));
+    const meaningful = segments.filter((s, i) => !(i === 0 && s === 'api') && !/^v\d+$/.test(s));
+    return meaningful[0] ?? 'default';
+}
+/** `get` `/api/v1/projects/{id}` reads "Get projects by id" when the contract gives no summary. */
+function summaryFor(method, path) {
+    const words = idFor(method, path).replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase();
+    return words[0].toUpperCase() + words.slice(1);
+}
+/** `get` `/api/v1/projects/{id}` is `getProjectsById`, stable across builds. */
+function idFor(method, path) {
+    const words = path
+        .split('/')
+        .filter((s) => s && s !== 'api' && !/^v\d+$/.test(s))
+        .map((s) => (s.startsWith('{') ? `By-${s.slice(1, -1)}` : s))
+        .flatMap((s) => s.split(/[^a-zA-Z0-9]+/))
+        .filter(Boolean);
+    return method + words.map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+}

package/dist/openapi.mjs

@@ -0,0 +1,259 @@
+// src/input.ts
+var DEFAULT_BODY_LIMIT = 1024 * 1024;
+
+// src/route.ts
+var CONTRACT = /* @__PURE__ */ Symbol.for("fluixi.api.contract");
+function contractOf(handler) {
+  return typeof handler === "function" ? handler[CONTRACT] : void 0;
+}
+
+// src/openapi.ts
+var convert;
+function setJsonSchemaConverter(converter) {
+  convert = converter;
+}
+var METHODS = ["get", "post", "put", "patch", "delete"];
+var DESCRIBES = /* @__PURE__ */ Symbol.for("fluixi.api.describes");
+var DESCRIBED_BY = /* @__PURE__ */ Symbol.for("fluixi.api.described-by");
+function describedBy(document, handler) {
+  Object.defineProperty(handler, DESCRIBED_BY, { value: document });
+  return handler;
+}
+var ERROR_SCHEMA = {
+  type: "object",
+  required: ["error"],
+  properties: {
+    error: {
+      type: "object",
+      required: ["code", "message"],
+      properties: {
+        code: { type: "string", description: "Machine-readable, stable: `validation_failed`, `not_found`, `internal`." },
+        message: { type: "string", description: "For people. May change between versions." },
+        details: { description: "For `validation_failed`, the list of `{ path, message }` issues." }
+      }
+    }
+  }
+};
+function createOpenApiDocument(routes, info) {
+  const paths = {};
+  const securitySchemes = {};
+  for (const route of routes) {
+    if (!route.path) continue;
+    for (const method of METHODS) {
+      const handler = route.mod[method.toUpperCase()];
+      if (typeof handler !== "function") continue;
+      const marks = handler;
+      if (marks[DESCRIBES] || marks[DESCRIBED_BY]) continue;
+      (paths[route.path] ??= {})[method] = operation(method, route.path, contractOf(handler), securitySchemes);
+    }
+  }
+  const { servers, ...rest } = info;
+  return {
+    openapi: "3.1.0",
+    info: rest,
+    ...servers?.length ? { servers } : {},
+    paths,
+    components: { schemas: { Error: ERROR_SCHEMA }, ...Object.keys(securitySchemes).length ? { securitySchemes } : {} }
+  };
+}
+function openApiRoute(routes, info) {
+  let cached;
+  const handler = async () => {
+    cached ??= describe(routes(), info).catch((error) => {
+      cached = void 0;
+      throw error;
+    });
+    return new Response(await cached, { headers: { "content-type": "application/json; charset=utf-8" } });
+  };
+  Object.defineProperty(handler, DESCRIBES, { value: true });
+  return handler;
+}
+async function describe(routes, info) {
+  const doc = createOpenApiDocument(routes, info);
+  const mounts = /* @__PURE__ */ new Map();
+  for (const route of routes) {
+    if (!route.path) continue;
+    for (const handler of Object.values(route.mod)) {
+      const source = typeof handler === "function" ? handler[DESCRIBED_BY] : void 0;
+      if (source && !mounts.has(source)) mounts.set(source, route.path.replace(/\/\{[^}]+\}$/, ""));
+    }
+  }
+  for (const [source, mount] of mounts) includeDocument(doc, await source(), mount);
+  return JSON.stringify(doc, null, 2);
+}
+function includeDocument(target, source, mount) {
+  const prefix = pascal(mount.split("/").filter(Boolean).pop() ?? "included");
+  const components = target.components ??= {};
+  const prefixed = (name) => prefix + name[0].toUpperCase() + name.slice(1);
+  const renames = /* @__PURE__ */ new Map();
+  for (const [section, entries] of Object.entries(source.components ?? {})) {
+    for (const [name, value] of Object.entries(entries)) {
+      const existing = components[section]?.[name];
+      if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(value)) {
+        renames.set(`#/components/${section}/${name}`, `#/components/${section}/${prefixed(name)}`);
+      }
+    }
+  }
+  const rewrite = (node) => {
+    if (Array.isArray(node)) return node.map(rewrite);
+    if (!node || typeof node !== "object") return node;
+    const out = Object.fromEntries(
+      Object.entries(node).map(([key, value]) => [key, key === "$ref" && typeof value === "string" ? renames.get(value) ?? value : rewrite(value)])
+    );
+    return "nullable" in out ? nullable(out) : out;
+  };
+  for (const [section, entries] of Object.entries(source.components ?? {})) {
+    const into = components[section] ??= {};
+    for (const [name, value] of Object.entries(entries)) {
+      const renamed = renames.has(`#/components/${section}/${name}`) ? prefixed(name) : name;
+      into[renamed] = rewrite(value);
+    }
+  }
+  const paths = target.paths ??= {};
+  const ids = new Set(Object.values(paths).flatMap((item) => Object.values(item).map((op) => op?.operationId)));
+  for (const [path, item] of Object.entries(source.paths ?? {})) {
+    const described = rewrite(item);
+    for (const [method, op] of Object.entries(described)) {
+      if (Array.isArray(op.security)) {
+        op.security = op.security.map(
+          (requirement) => Object.fromEntries(
+            Object.entries(requirement).map(([name, scopes]) => [
+              renames.has(`#/components/securitySchemes/${name}`) ? prefixed(name) : name,
+              scopes
+            ])
+          )
+        );
+      }
+      if (METHODS.includes(method) && !op.summary) op.summary = summaryOf(op, method, mount + path);
+      if (typeof op.operationId === "string" && ids.has(op.operationId)) {
+        op.operationId = prefix[0].toLowerCase() + prefix.slice(1) + op.operationId[0].toUpperCase() + op.operationId.slice(1);
+      }
+      if (typeof op.operationId === "string") ids.add(op.operationId);
+    }
+    paths[mount + path] = described;
+  }
+  const tags = source.tags ?? [];
+  if (tags.length) {
+    const known = target.tags ??= [];
+    for (const tag of tags) if (!known.some((t) => t.name === tag.name)) known.push(tag);
+  }
+}
+function nullable(schema) {
+  const { nullable: isNullable, ...rest } = schema;
+  if (isNullable !== true) return rest;
+  if (typeof rest.type === "string") return { ...rest, type: [rest.type, "null"] };
+  if (Array.isArray(rest.type)) return rest.type.includes("null") ? rest : { ...rest, type: [...rest.type, "null"] };
+  return { anyOf: [rest, { type: "null" }] };
+}
+function summaryOf(op, method, path) {
+  const description = typeof op.description === "string" ? op.description.split(/\.\s|\n/)[0].trim() : "";
+  if (description && description.length <= 60) return description.replace(/\.$/, "");
+  return typeof op.operationId === "string" ? op.operationId.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/^./, (c) => c.toUpperCase()) : summaryFor(method, path);
+}
+function pascal(word) {
+  return word.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+function operation(method, path, contract, schemes) {
+  const operationId = contract?.operationId ?? idFor(method, path);
+  if (!contract) {
+    return {
+      operationId,
+      tags: [tagFor(path)],
+      summary: `${method.toUpperCase()} ${path}`,
+      description: "This route declares no contract, so nothing about its input or output is known.",
+      "x-fluixi-contract": false,
+      responses: { default: { description: "Undocumented." } }
+    };
+  }
+  const parameters = [
+    ...parametersFrom(contract.params, "path", pathNames(path)),
+    ...parametersFrom(contract.query, "query", [])
+  ];
+  const success = contract.status ?? (contract.response ? 200 : 204);
+  const responses = {
+    [success]: contract.response ? { description: "Success.", content: { "application/json": { schema: schemaFor(contract.response, "output") } } } : { description: "Success, no content." }
+  };
+  const error = (description) => ({ description, content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } });
+  if (contract.params || contract.query || contract.body) responses[400] = error("The request is not valid: `validation_failed`, `invalid_json`.");
+  if (contract.body) {
+    responses[413] = error("The body is over the limit.");
+    responses[415] = error("The body is not JSON.");
+  }
+  const guard = contract.guard;
+  if (guard) {
+    const refuses = guard.refuses ?? [401];
+    if (refuses.includes(401)) responses[401] = error("Not signed in: `unauthorized`.");
+    if (refuses.includes(403)) responses[403] = error("Signed in, not allowed: `forbidden`, or a more precise code.");
+    if (refuses.includes(503)) responses[503] = error("A service the check depends on cannot answer now; try again.");
+  }
+  if (pathNames(path).length) responses[404] = error("Nothing at this path.");
+  responses[500] = error("A fault on the server. Its detail is logged, never sent.");
+  return {
+    operationId,
+    tags: contract.tags?.length ? contract.tags : [tagFor(path)],
+    // Tools name the request after it (Postman does), so there is always one.
+    summary: contract.summary ?? summaryFor(method, path),
+    ...contract.description ? { description: contract.description } : {},
+    ...contract.deprecated ? { deprecated: true } : {},
+    // Stated on every contracted route, so a public one reads as public rather than unknown.
+    security: security(guard, schemes),
+    ...parameters.length ? { parameters } : {},
+    ...contract.body ? { requestBody: { required: true, content: { "application/json": { schema: schemaFor(contract.body, "input") } } } } : {},
+    responses
+  };
+}
+function security(guard, schemes) {
+  if (!guard?.security) return [];
+  const { name, scheme, scopes } = guard.security;
+  schemes[name] = scheme;
+  return [{ [name]: scopes ?? [] }];
+}
+function parametersFrom(schema, where, names) {
+  if (!schema) return where === "path" ? names.map((name) => ({ name, in: "path", required: true, schema: { type: "string" } })) : [];
+  const json = schemaFor(schema, "input");
+  const properties = json.properties ?? {};
+  const required = new Set(json.required ?? []);
+  return Object.entries(properties).map(([name, property]) => ({
+    name,
+    in: where,
+    required: where === "path" ? true : required.has(name),
+    ...typeof property.description === "string" ? { description: property.description } : {},
+    schema: property,
+    ...where === "query" && property.type === "array" ? { style: "form", explode: true } : {}
+  }));
+}
+function schemaFor(schema, io) {
+  const standard = schema["~standard"].jsonSchema;
+  try {
+    const json = standard?.[io]({ target: "draft-2020-12", libraryOptions: { unrepresentable: "any" } }) ?? convert?.(schema, io);
+    if (json) {
+      const { $schema: _dialect, ...rest } = json;
+      return rest;
+    }
+  } catch {
+  }
+  return { "x-fluixi-unconverted": schema["~standard"].vendor };
+}
+function pathNames(path) {
+  return [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+}
+function tagFor(path) {
+  const segments = path.split("/").filter((s) => s && !s.startsWith("{"));
+  const meaningful = segments.filter((s, i) => !(i === 0 && s === "api") && !/^v\d+$/.test(s));
+  return meaningful[0] ?? "default";
+}
+function summaryFor(method, path) {
+  const words = idFor(method, path).replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  return words[0].toUpperCase() + words.slice(1);
+}
+function idFor(method, path) {
+  const words = path.split("/").filter((s) => s && s !== "api" && !/^v\d+$/.test(s)).map((s) => s.startsWith("{") ? `By-${s.slice(1, -1)}` : s).flatMap((s) => s.split(/[^a-zA-Z0-9]+/)).filter(Boolean);
+  return method + words.map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+export {
+  createOpenApiDocument,
+  describedBy,
+  includeDocument,
+  openApiRoute,
+  setJsonSchemaConverter
+};