@dogsbay/format-openapi 0.2.0-beta.12 → 0.2.0-beta.120

package/dist/core.js

@@ -0,0 +1,930 @@
+/**
+ * The OpenAPI conversion with no file or network access, and no Node
+ * built-ins: it runs in a Cloudflare Worker (dogsbay-ssg) as well as in
+ * the CLI. A spec comes in as text (or an already-parsed object) and goes
+ * out as `endpoint` TreeNodes; finding and reading the file is the
+ * caller's (parse.ts for the CLI, a build's file map for dogsbay-ssg).
+ *
+ *   text ─ parseSpecText ─▶ object ─ prepareSpec ─▶ spec ─┬ embedSpec    (one page's body)
+ *                                                         └ specToPages  (a page per operation)
+ *
+ * `prepareSpec` is the expensive step (upgrade, dereference); `createSpecCache`
+ * runs it once per spec file per build. `findSpec` holds the rules for which
+ * file a page's `:::openapi{spec}` may name.
+ */
+import { dereference, upgrade } from "@scalar/openapi-parser";
+import MarkdownIt from "markdown-it";
+import { operationToSlug, slugifyTag } from "./slug.js";
+import { resolveCodeSamples } from "./code-samples.js";
+export { findSpec, specCandidates } from "./spec-path.js";
+const HTTP_METHODS = [
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+];
+/**
+ * A dereferenced spec (`prepareSpec`) as a page per operation, a page per tag
+ * and an info page, with their nav: for a spec that IS the source.
+ */
+export function specToPages(spec, options = {}) {
+    const hrefPrefix = normalisePrefix(options.hrefPrefix);
+    const pages = [];
+    // Collect tag descriptions (from spec.tags[]) for tag overview pages.
+    const tagDescriptions = new Map();
+    for (const t of spec.tags || []) {
+        if (txt(t?.name))
+            tagDescriptions.set(t.name, txt(t.description) ?? "");
+    }
+    const tagToOps = new Map();
+    const untagged = [];
+    const operations = collectOperations(spec);
+    const slugs = pageSlugs(spec, operations, options.reservedSlugs);
+    for (const op of operations) {
+        const { method, path, operation, props } = op;
+        const primaryTag = props.tags?.[0];
+        const tagSlug = primaryTag ? slugs.tags.get(primaryTag) : "";
+        const opSlug = slugs.operations.get(op);
+        const slug = tagSlug ? `${tagSlug}/${opSlug}` : opSlug;
+        const title = txt(operation.summary) || `${method.toUpperCase()} ${path}`;
+        const tree = [
+            {
+                type: "endpoint",
+                props: structuredClone(props),
+            },
+        ];
+        const headings = [{ depth: 1, slug: opSlug, text: title }];
+        pages.push({
+            slug,
+            title,
+            tree,
+            headings,
+        });
+        const summary = {
+            slug,
+            title,
+            method,
+            path,
+            deprecated: operation.deprecated === true,
+        };
+        if (primaryTag) {
+            const arr = tagToOps.get(primaryTag) || [];
+            arr.push(summary);
+            tagToOps.set(primaryTag, arr);
+        }
+        else {
+            untagged.push(summary);
+        }
+    }
+    // Tag overview pages.
+    for (const [tagName, ops] of tagToOps) {
+        const tagSlug = slugs.tags.get(tagName);
+        const description = tagDescriptions.get(tagName) || "";
+        pages.push(buildTagPage(tagName, tagSlug, description, ops));
+    }
+    // Root info page.
+    const info = spec.info || {};
+    pages.push(buildInfoPage(txt(info.title) || "API Reference", txt(info.description) ?? "", txt(info.version) ?? (typeof info.version === "number" ? String(info.version) : "")));
+    // Build nav: tag groups in declaration order, with operations as
+    // children. Untagged operations land under a synthetic "Other" group
+    // so they're discoverable but visually separated.
+    const nav = buildNav(spec, pages, tagToOps, untagged, hrefPrefix, slugs.tags);
+    return { pages, nav };
+}
+/**
+ * Every page's URL, distinct. The root page is `index`, a tag's overview is
+ * `<tag>`, a tagged operation `<tag>/<operation>` and an untagged one
+ * `<operation>`, where `<operation>` comes from the operationId, or else the
+ * method and path. Slugs that would land on a URL already taken (`getPet` and
+ * `get_pet`; an operationId `index`; an untagged operation named like a tag;
+ * two tags that slugify alike) are made distinct: an operation falls back to
+ * its method and path, then a numeric suffix, in spec order, so the first
+ * claimant keeps the plain slug. Before, the later page silently replaced the
+ * earlier one.
+ */
+function pageSlugs(spec, operations, reserved = []) {
+    const tags = new Map();
+    const rootTaken = new Set(["index", ...reserved.map((r) => r.toLowerCase())]);
+    // Tags that have pages, the spec's declared order first (as in the nav).
+    const used = new Set(operations.map((op) => op.props.tags?.[0]).filter(Boolean));
+    const tagNames = [];
+    for (const t of spec.tags || [])
+        if (used.has(txt(t?.name)))
+            tagNames.push(t.name);
+    for (const op of operations)
+        if (op.props.tags?.[0])
+            tagNames.push(op.props.tags[0]);
+    for (const name of tagNames) {
+        if (tags.has(name))
+            continue;
+        const slug = claim(slugifyTag(name) || "tag", rootTaken);
+        tags.set(name, slug);
+    }
+    const folders = new Map();
+    const taken = (op) => {
+        const primary = op.props.tags?.[0];
+        if (!primary)
+            return rootTaken;
+        const folder = tags.get(primary);
+        let set = folders.get(folder);
+        if (!set)
+            folders.set(folder, (set = new Set(["index"])));
+        return set;
+    };
+    // Two passes: every operation's own slug first, so a fallback never takes
+    // the slug a LATER operation would have had (moving a URL that had no
+    // collision); then the operations that lost theirs.
+    const out = new Map();
+    for (const op of operations) {
+        const preferred = operationToSlug(op.method, op.path, txt(op.operation.operationId));
+        const set = taken(op);
+        if (preferred && !set.has(preferred)) {
+            set.add(preferred);
+            out.set(op, preferred);
+        }
+    }
+    for (const op of operations) {
+        if (out.has(op))
+            continue;
+        // Letters, digits and dashes only: a path's `:`, `?` or `%2F` must not
+        // reach a URL this function invents.
+        const fallback = operationToSlug(op.method, op.path).replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || op.method;
+        out.set(op, claim(fallback, taken(op)));
+    }
+    return { tags, operations: out };
+}
+/** `base`, or `base-2`, `base-3`… : the first not in `used`, which it joins. */
+function claim(base, used) {
+    let slug = base;
+    for (let n = 2; used.has(slug); n++)
+        slug = `${base}-${n}`;
+    used.add(slug);
+    return slug;
+}
+/**
+ * Spec text → object. JSON is read natively; YAML needs a parser passed in
+ * (`yaml`'s `parse`, js-yaml's `load`), so a host that has one does not
+ * bundle a second.
+ */
+export function parseSpecText(text, parseYaml) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        if (!parseYaml)
+            throw new Error(`not JSON, and no YAML parser was given (${err.message})`);
+        return parseYaml(text);
+    }
+}
+/**
+ * A parsed spec → the dereferenced OpenAPI 3 document every function here
+ * reads. Swagger 2.0 is upgraded to OpenAPI 3 first: everything below reads
+ * the 3.x shape (`requestBody`, response `content`, `servers`), so a 2.0
+ * spec parsed without the upgrade lost every body parameter and response
+ * schema while still producing plausible-looking pages. Canonical's Anbox
+ * Cloud API specs are 2.0.
+ */
+export async function prepareSpec(parsed, label = "the spec") {
+    if (!parsed || typeof parsed !== "object")
+        throw new Error(`${label} is not an OpenAPI document`);
+    let doc = acyclic(parsed, label);
+    if (typeof doc.swagger === "string" && doc.swagger.startsWith("2")) {
+        doc = upgrade(doc).specification;
+    }
+    const { schema: spec } = await dereference(doc);
+    if (!spec)
+        throw new Error(`Failed to dereference OpenAPI spec at ${label}`);
+    return spec;
+}
+/** The most a parsed document may expand to, in characters, counting every alias at each place it is used. */
+const SPEC_MAX_EXPANDED_CHARS = 64_000_000;
+/**
+ * A parsed document with no cycles, and no larger than SPEC_MAX_EXPANDED_CHARS
+ * once its aliases are expanded.
+ *
+ * YAML aliases make the parsed value a graph. `&a {self: *a}` is an object
+ * that contains itself, which sent the dereferencer into unbounded
+ * recursion (a stack overflow, not an error). A value reached again while
+ * it is still being copied (a cycle) becomes "(circular)"; one reached
+ * again after (an alias used twice) is shared, as the parser shared it, so
+ * the copy is linear.
+ *
+ * Sharing is not enough: the dereferencer and every renderer walk each path
+ * through the graph, so `l2: {l: *l1, r: *l1}` doubles per level (a 724-byte
+ * spec took 6.8 s to dereference at depth 22, and a `summary` aliased the
+ * same way made a 147 MB page). So the copy also counts the expanded size
+ * (memoized per node, so counting is linear too) and refuses a document past
+ * the bound, as the `yaml` parser does with its alias limit. js-yaml, which
+ * dogsbay-ssg parses with, has no such limit. JSON never has either problem.
+ */
+function acyclic(root, label) {
+    const done = new Map();
+    const open = new Set();
+    const add = (a, b) => Math.min(SPEC_MAX_EXPANDED_CHARS + 1, a + b);
+    const copy = (v, depth) => {
+        if (typeof v === "string")
+            return { out: v, size: v.length + 2 };
+        if (!v || typeof v !== "object" || v instanceof Date)
+            return { out: v, size: 8 };
+        const finished = done.get(v);
+        if (finished)
+            return finished;
+        if (open.has(v))
+            return { out: "(circular)", size: 12 };
+        if (depth > 1_000)
+            throw new Error(`${label} is nested more than 1,000 levels deep`);
+        open.add(v);
+        let size = 2;
+        let out;
+        if (Array.isArray(v)) {
+            out = v.map((e) => {
+                const c = copy(e, depth + 1);
+                size = add(size, c.size + 1);
+                return c.out;
+            });
+        }
+        else {
+            out = {};
+            for (const [k, e] of Object.entries(v)) {
+                const c = copy(e, depth + 1);
+                size = add(size, c.size + k.length + 4);
+                out[k] = c.out;
+            }
+        }
+        open.delete(v);
+        const r = { out, size };
+        done.set(v, r);
+        return r;
+    };
+    const r = copy(root, 0);
+    if (r.size > SPEC_MAX_EXPANDED_CHARS) {
+        throw new Error(`${label} expands to more than ${SPEC_MAX_EXPANDED_CHARS.toLocaleString("en")} characters through repeated YAML aliases`);
+    }
+    return r.out;
+}
+/**
+ * Prepared specs by path, each parsed and dereferenced once however many
+ * pages embed it. `read` returns the file's text; failures are cached too,
+ * so a broken spec is reported per page without being parsed again.
+ */
+export function createSpecCache(read, parseYaml) {
+    const specs = new Map();
+    return {
+        get(path) {
+            let p = specs.get(path);
+            if (!p) {
+                p = Promise.resolve()
+                    .then(() => read(path))
+                    .then((text) => prepareSpec(parseSpecText(text, parseYaml), path));
+                specs.set(path, p);
+            }
+            return p;
+        },
+        get size() {
+            return specs.size;
+        },
+    };
+}
+/** A spec field read as text: a YAML alias can put any value where a string belongs. */
+const txt = (v) => (typeof v === "string" ? v : undefined);
+// ─── Values copied from the spec ─────────────────────────────────────
+/**
+ * Bounds on the spec values an operation's props carry verbatim: examples,
+ * defaults and enums. A YAML anchor repeated through aliases is ONE object
+ * in the parsed spec and a full copy in every place a renderer serializes
+ * it: a 300-byte spec grew to a 33 MB page and 720 MB of memory in
+ * dogsbay-ssg, and an example that refers to itself crashed the build
+ * (JSON.stringify on a cycle). Values are copied here, so props are plain,
+ * acyclic and bounded, and every renderer is protected.
+ */
+const VALUE_MAX_CHARS = 4_000; // one default, enum entry or property example
+const EXAMPLE_MAX_CHARS = 50_000; // a request or response example
+const ENUM_MAX_VALUES = 200;
+const OPERATION_MAX_CHARS = 500_000; // everything copied for one operation
+const VALUE_MAX_DEPTH = 32;
+/** What a value over its bound is shown as. */
+export const VALUE_TOO_LARGE = "(not shown: too large)";
+/** The budget of the operation being collected (collectOperations is synchronous). */
+let operationBudget = OPERATION_MAX_CHARS;
+class TooLarge extends Error {
+}
+/**
+ * A plain JSON copy of a spec value within `max` serialized characters (and
+ * the operation's remaining budget), or VALUE_TOO_LARGE. A reference back
+ * to an enclosing value becomes "(circular)". Counting stops at the bound,
+ * so an exponentially aliased value costs no more than the bound to refuse.
+ */
+function copyValue(v, max = VALUE_MAX_CHARS) {
+    if (v === undefined)
+        return undefined;
+    const limit = Math.min(max, operationBudget);
+    let left = limit;
+    const ancestors = new Set();
+    const spend = (n) => {
+        if ((left -= n) < 0)
+            throw new TooLarge();
+    };
+    const copy = (x, depth) => {
+        if (x === null || x === undefined)
+            return spend(4), null;
+        if (typeof x === "string")
+            return spend(x.length + 2), x;
+        if (typeof x === "number" || typeof x === "boolean")
+            return spend(String(x).length), x;
+        if (x instanceof Date)
+            return spend(26), Number.isNaN(x.getTime()) ? String(x) : x.toISOString();
+        if (typeof x !== "object")
+            return spend(String(x).length + 2), String(x);
+        if (ancestors.has(x))
+            return spend(10), "(circular)";
+        if (depth >= VALUE_MAX_DEPTH)
+            throw new TooLarge();
+        ancestors.add(x);
+        try {
+            if (Array.isArray(x))
+                return spend(2), x.map((e) => (spend(1), copy(e, depth + 1)));
+            const out = {};
+            spend(2);
+            for (const [k, e] of Object.entries(x)) {
+                spend(k.length + 4);
+                out[k] = copy(e, depth + 1);
+            }
+            return out;
+        }
+        finally {
+            ancestors.delete(x);
+        }
+    };
+    try {
+        const out = copy(v, 0);
+        operationBudget -= limit - left;
+        return out;
+    }
+    catch (err) {
+        if (!(err instanceof TooLarge))
+            throw err;
+        operationBudget -= Math.min(operationBudget, VALUE_TOO_LARGE.length);
+        return VALUE_TOO_LARGE;
+    }
+}
+/** An enum's values, each copied with copyValue, at most ENUM_MAX_VALUES; a cut list ends in "…". */
+function copyEnum(list) {
+    if (!Array.isArray(list))
+        return undefined;
+    const out = [];
+    for (const v of list) {
+        if (out.length >= ENUM_MAX_VALUES || operationBudget <= 0)
+            return [...out, "…"];
+        out.push(copyValue(v));
+    }
+    return out;
+}
+/** Every operation in the spec, in document order, as `endpoint` props. */
+function collectOperations(spec) {
+    const out = [];
+    const baseUrl = txt(spec.servers?.[0]?.url) ?? "";
+    for (const [path, pathItem] of Object.entries(spec.paths || {})) {
+        if (!pathItem)
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = buildOperation(path, pathItem, method, baseUrl);
+            if (op)
+                out.push(op);
+        }
+    }
+    return out;
+}
+/** One operation as `endpoint` props, or undefined when the path item has none for `method`. */
+function buildOperation(path, pathItem, method, baseUrl) {
+    const operation = pathItem?.[method];
+    if (!operation)
+        return undefined;
+    operationBudget = OPERATION_MAX_CHARS;
+    const opTags = Array.isArray(operation.tags) ? operation.tags.filter((t) => typeof t === "string") : [];
+    const props = {
+        method,
+        path,
+        baseUrl,
+        summary: txt(operation.summary) || undefined,
+        description: txt(operation.description) || undefined,
+        operationId: txt(operation.operationId) || undefined,
+        tags: opTags.length > 0 ? opTags : undefined,
+        deprecated: operation.deprecated === true ? true : undefined,
+        parameters: extractParameters(operation, pathItem),
+        ...extractRequestBody(operation),
+        responses: extractResponses(operation),
+        codeSamples: resolveCodeSamples(operation, method, path, baseUrl),
+    };
+    return { method, path, operation, props };
+}
+/**
+ * The operation a `:::openapi` directive selects from its props, or why it
+ * cannot: `path` and `method` come together or not at all.
+ */
+export function directiveOperation(props) {
+    const path = typeof props?.path === "string" ? props.path.trim() : "";
+    const method = typeof props?.method === "string" ? props.method.trim().toLowerCase() : "";
+    if (!path && !method)
+        return {};
+    if (!path || !method)
+        return { error: "`path` and `method` select an operation together; give both or neither" };
+    if (!HTTP_METHODS.includes(method))
+        return { error: `not an HTTP method: ${method}` };
+    return { operation: { path, method } };
+}
+/**
+ * A whole spec as the BODY of one page: what Swagger UI or Redoc show when a
+ * page embeds them. The info version and description, then a section per tag
+ * (declared order, then first use; untagged operations last, under "Other"),
+ * each holding its operations as `endpoint` nodes in document order.
+ *
+ * `spec` is a dereferenced spec (`prepareSpec`), and is not modified: the
+ * nodes are copies, so one parsed spec serves every page that embeds it.
+ *
+ * `specToPages` is the other shape — a page per operation — for a spec
+ * that IS the source. This one is for a spec a prose page points at.
+ */
+export function embedSpec(spec, options = {}) {
+    if (options.operation) {
+        const { path, method } = options.operation;
+        // Only this operation is built: building them all to keep one made a page per operation
+        // quadratic in the spec (400 pages over a 400-operation spec: 4 s, in dogsbay-ssg).
+        const m = method.toLowerCase();
+        const paths = spec.paths && typeof spec.paths === "object" ? spec.paths : {};
+        const op = HTTP_METHODS.includes(m) && Object.hasOwn(paths, path) ? buildOperation(path, paths[path], m, txt(spec.servers?.[0]?.url) ?? "") : undefined;
+        if (!op)
+            throw new Error(`the spec has no operation ${method.toUpperCase()} ${path}`);
+        return { tree: [{ type: "endpoint", props: structuredClone(op.props) }], headings: [], operations: 1 };
+    }
+    const level = Math.min(6, Math.max(2, options.level ?? 2));
+    const tree = [];
+    const headings = [];
+    const used = new Set(options.usedIds ?? []);
+    // A description's own headings go under the section that holds it, with
+    // ids, and into the outline (a `# Title` was a second H1).
+    const describe = (text, minLevel) => {
+        const d = descriptionHtml(text, minLevel, used);
+        headings.push(...d.headings);
+        tree.push({ type: "prose", html: d.html });
+    };
+    const info = spec.info || {};
+    if (txt(info.version) || typeof info.version === "number") {
+        tree.push({
+            type: "prose",
+            html: `<p class="text-sm text-muted-foreground">Version ${escapeHtml(String(info.version))}</p>`,
+        });
+    }
+    if (typeof info.description === "string" && info.description.trim()) {
+        describe(info.description, level);
+    }
+    const tagDescriptions = new Map();
+    for (const t of spec.tags || []) {
+        if (txt(t?.name))
+            tagDescriptions.set(t.name, txt(t.description) ?? "");
+    }
+    const groups = new Map();
+    for (const t of tagDescriptions.keys())
+        groups.set(t, []);
+    const untagged = [];
+    const operations = collectOperations(spec);
+    for (const { props } of operations) {
+        // A copy: enum, default and example values are the spec's own objects, and the spec is shared.
+        const node = { type: "endpoint", props: structuredClone(props) };
+        const tag = props.tags?.[0];
+        if (!tag) {
+            untagged.push(node);
+            continue;
+        }
+        if (!groups.has(tag))
+            groups.set(tag, []);
+        groups.get(tag).push(node);
+    }
+    if (untagged.length)
+        groups.set("\u0000other", untagged);
+    for (const [tag, nodes] of groups) {
+        if (!nodes.length)
+            continue;
+        const text = tag === "\u0000other" ? "Other" : tag;
+        const id = uniqueId(slugifyTag(text) || "section", used);
+        tree.push({
+            type: "heading",
+            props: { level, id },
+            inline: [{ type: "text", text: text }],
+        });
+        headings.push({ depth: level, slug: id, text });
+        const description = tagDescriptions.get(tag);
+        if (description)
+            describe(description, level + 1);
+        tree.push(...nodes);
+    }
+    return { tree, headings, operations: operations.length };
+}
+function uniqueId(base, used) {
+    let id = base;
+    for (let n = 2; used.has(id); n++)
+        id = `${base}-${n}`;
+    used.add(id);
+    return id;
+}
+/**
+ * A description (CommonMark) → HTML with its headings shifted so the
+ * highest is `minLevel`, each given a unique id, and listed for the TOC.
+ * Raw HTML stays off (see `md`).
+ */
+function descriptionHtml(text, minLevel, used) {
+    const tokens = md.parse(text, {});
+    const levels = tokens.filter((t) => t.type === "heading_open").map((t) => Number(t.tag.slice(1)));
+    const headings = [];
+    if (levels.length) {
+        const shift = Math.max(0, minLevel - Math.min(...levels));
+        for (let i = 0; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t.type !== "heading_open")
+                continue;
+            const depth = Math.min(6, Number(t.tag.slice(1)) + shift);
+            const inline = tokens[i + 1];
+            const label = (inline?.children ?? [])
+                .filter((c) => c.type === "text" || c.type === "code_inline")
+                .map((c) => c.content)
+                .join("")
+                .trim();
+            const id = uniqueId(slugifyTag(label) || "section", used);
+            t.tag = `h${depth}`;
+            t.attrSet("id", id);
+            if (tokens[i + 2]?.type === "heading_close")
+                tokens[i + 2].tag = `h${depth}`;
+            headings.push({ depth, slug: id, text: label });
+        }
+    }
+    return { html: md.renderer.render(tokens, md.options, {}).trim(), headings };
+}
+function normalisePrefix(p) {
+    if (!p)
+        return "";
+    return p.replace(/\/+$/, "");
+}
+/** The one non-null type of a schema: OpenAPI 3.1 (and an upgraded 2.0
+ *  spec) writes a nullable object as `type: [object, "null"]`. */
+function primaryType(schema) {
+    if (!schema)
+        return undefined;
+    if (!Array.isArray(schema.type))
+        return schema.type;
+    const types = schema.type.filter((t) => t !== "null");
+    return types.length === 1 ? types[0] : undefined;
+}
+function schemaToType(schema, depth = 0) {
+    if (!schema)
+        return "any";
+    // An array of itself (a cycle once dereferenced) has no finite name.
+    if (depth > SCHEMA_MAX_DEPTH)
+        return "any";
+    // OpenAPI 3.1 (and a Swagger 2.0 spec upgraded to it) writes nullable as
+    // a type list: `type: [string, "null"]`.
+    if (Array.isArray(schema.type)) {
+        const types = schema.type.filter((t) => t !== "null");
+        if (types.length === 1)
+            return schemaToType({ ...schema, type: types[0] }, depth + 1);
+        return types.length ? types.join(" | ") : "null";
+    }
+    if (schema.type === "array") {
+        const itemType = schema.items ? schemaToType(schema.items, depth + 1) : "any";
+        return `${itemType}[]`;
+    }
+    return schema.type || "any";
+}
+/**
+ * Bounds on walking one schema. A dereferenced spec is a GRAPH: a
+ * self-referencing schema is a cycle (the walk overflowed the stack), and
+ * eight properties that each reference the level below grow 8× per level
+ * (a 2.2 KB spec made 18 MB of tree at depth 6). Past a bound the walk stops
+ * and the property shows without children.
+ */
+const SCHEMA_MAX_DEPTH = 10;
+const SCHEMA_MAX_NODES = 2000;
+const newWalk = () => ({ nodes: SCHEMA_MAX_NODES, depth: 0, ancestors: new Set() });
+/** Run `f` one level into `schema`, or return `empty` past a bound. */
+function descend(walk, schema, empty, f) {
+    if (!schema || typeof schema !== "object")
+        return f();
+    if (walk.depth >= SCHEMA_MAX_DEPTH || walk.nodes <= 0 || walk.ancestors.has(schema))
+        return empty;
+    walk.depth++;
+    walk.ancestors.add(schema);
+    try {
+        return f();
+    }
+    finally {
+        walk.depth--;
+        walk.ancestors.delete(schema);
+    }
+}
+function extractSchemaProperties(schema, requiredFields, walk = newWalk()) {
+    if (!schema?.properties)
+        return [];
+    return descend(walk, schema, [], () => propertiesOf(schema, requiredFields, walk));
+}
+function propertiesOf(schema, requiredFields, walk) {
+    const required = requiredFields || schema.required || [];
+    const out = [];
+    for (const [name, prop] of Object.entries(schema.properties)) {
+        if (walk.nodes-- <= 0)
+            break;
+        out.push(propertyOf(name, prop ?? {}, required, walk));
+    }
+    return out;
+}
+function propertyOf(name, prop, required, walk) {
+    const result = {
+        name,
+        type: schemaToType(prop),
+        required: required.includes(name),
+    };
+    if (txt(prop.description))
+        result.description = prop.description;
+    if (prop.nullable)
+        result.nullable = true;
+    if (txt(prop.format))
+        result.format = prop.format;
+    if (prop.enum)
+        result.enum = copyEnum(prop.enum);
+    if (prop.default !== undefined)
+        result.default = copyValue(prop.default);
+    if (prop.example !== undefined)
+        result.example = copyValue(prop.example);
+    if (primaryType(prop) === "object" && prop.properties) {
+        result.properties = extractSchemaProperties(prop, undefined, walk);
+    }
+    if (primaryType(prop) === "array" && prop.items) {
+        if (primaryType(prop.items) === "object" && prop.items.properties) {
+            result.items = extractSchemaProperties(prop.items, undefined, walk);
+        }
+    }
+    return result;
+}
+function extractParameters(operation, pathItem) {
+    const params = [];
+    const allParams = [
+        ...(pathItem.parameters || []),
+        ...(operation.parameters || []),
+    ];
+    // Operation-level wins over path-level on (name, in) collision.
+    const seen = new Map();
+    for (const p of allParams) {
+        if (!txt(p?.name) || !txt(p?.in))
+            continue;
+        seen.set(`${p.name}:${p.in}`, p);
+    }
+    for (const p of seen.values()) {
+        const param = {
+            name: p.name,
+            in: p.in,
+            type: schemaToType(p.schema),
+            required: p.required || false,
+        };
+        if (txt(p.description))
+            param.description = p.description;
+        if (p.schema?.default !== undefined) {
+            const d = copyValue(p.schema.default);
+            param.default = typeof d === "string" ? d : JSON.stringify(d);
+        }
+        if (p.schema?.enum)
+            param.enum = copyEnum(p.schema.enum);
+        if (p.deprecated)
+            param.deprecated = true;
+        params.push(param);
+    }
+    return params;
+}
+function extractRequestBody(operation) {
+    const body = operation.requestBody;
+    if (!body?.content)
+        return {};
+    const mediaType = body.content["application/json"] ||
+        Object.values(body.content)[0];
+    if (!mediaType?.schema)
+        return {};
+    return {
+        requestBody: extractSchemaProperties(mediaType.schema),
+        requestBodyExample: copyValue(generateExampleFromSchema(mediaType.schema), EXAMPLE_MAX_CHARS),
+    };
+}
+function extractResponses(operation) {
+    if (!operation.responses)
+        return [];
+    return Object.entries(operation.responses)
+        .filter(([status]) => status !== "default")
+        .map(([status, resp]) => {
+        const result = {
+            status,
+            description: txt(resp.description),
+        };
+        if (resp.content) {
+            const contentTypeKey = resp.content["application/json"]
+                ? "application/json"
+                : Object.keys(resp.content)[0];
+            const mediaType = resp.content[contentTypeKey];
+            if (contentTypeKey)
+                result.contentType = contentTypeKey;
+            if (mediaType?.schema) {
+                const rawSchema = mediaType.schema;
+                const schema = primaryType(rawSchema) === "array" && rawSchema.items
+                    ? rawSchema.items
+                    : rawSchema;
+                result.schema = extractSchemaProperties(schema);
+                result.example = copyValue(generateExampleFromSchema(rawSchema), EXAMPLE_MAX_CHARS);
+            }
+        }
+        return result;
+    })
+        .sort((a, b) => a.status.localeCompare(b.status));
+}
+function generateExampleFromSchema(schema, walk = newWalk()) {
+    if (!schema)
+        return undefined;
+    if (walk.nodes-- <= 0)
+        return null;
+    return descend(walk, schema, null, () => exampleOf(schema, walk));
+}
+function exampleOf(schema, walk) {
+    if (schema.example !== undefined)
+        return schema.example;
+    switch (primaryType(schema)) {
+        case "object": {
+            if (!schema.properties)
+                return {};
+            const obj = {};
+            for (const [name, prop] of Object.entries(schema.properties)) {
+                obj[name] = generateExampleFromSchema(prop, walk);
+            }
+            return obj;
+        }
+        case "array":
+            return schema.items ? [generateExampleFromSchema(schema.items, walk)] : [];
+        case "string": {
+            if (schema.enum)
+                return schema.enum[0];
+            if (schema.format === "date-time")
+                return "2024-01-01T00:00:00Z";
+            if (schema.format === "email")
+                return "user@example.com";
+            if (schema.format === "uri" || schema.format === "url") {
+                return "https://example.com";
+            }
+            if (schema.format === "uuid") {
+                return "550e8400-e29b-41d4-a716-446655440000";
+            }
+            if (schema.default !== undefined)
+                return schema.default;
+            return "string";
+        }
+        case "integer":
+            return schema.example ?? schema.default ?? 0;
+        case "number":
+            return schema.example ?? schema.default ?? 0.0;
+        case "boolean":
+            return schema.example ?? schema.default ?? true;
+        default:
+            return null;
+    }
+}
+function buildTagPage(tagName, tagSlug, description, ops) {
+    const tree = [
+        {
+            type: "heading",
+            props: { level: 1, id: tagSlug },
+            inline: [{ type: "text", text: tagName }],
+        },
+    ];
+    const used = new Set([tagSlug]);
+    const described = description ? descriptionHtml(description, 2, used) : null;
+    if (described)
+        tree.push({ type: "prose", html: described.html });
+    // Link nodes with site-root hrefs, as an importer writes them, so the build
+    // adds the base path and the source's /<name>/ prefix like any other link.
+    // These were relative `<a href="pets/list-pets">` in raw HTML: on the tag
+    // page, served at /pets/, the browser read them as /pets/pets/list-pets.
+    const items = ops.map((op) => ({
+        type: "list-item",
+        inline: [
+            {
+                type: "link",
+                href: `/${op.slug}`,
+                children: [
+                    { type: "code", text: op.method.toUpperCase() },
+                    { type: "text", text: ` ${op.path}` },
+                ],
+            },
+            ...(op.deprecated ? [{ type: "text", text: " (deprecated)" }] : []),
+        ],
+    }));
+    tree.push({ type: "unordered-list", children: items });
+    return {
+        slug: tagSlug,
+        title: tagName,
+        tree,
+        headings: [{ depth: 1, slug: tagSlug, text: tagName }, ...(described?.headings ?? [])],
+    };
+}
+function buildInfoPage(title, description, version) {
+    const tree = [
+        {
+            type: "heading",
+            props: { level: 1, id: "api-reference" },
+            inline: [{ type: "text", text: title }],
+        },
+    ];
+    if (version) {
+        tree.push({
+            type: "prose",
+            html: `<p class="text-sm text-muted-foreground">Version ${escapeHtml(version)}</p>`,
+        });
+    }
+    const described = description ? descriptionHtml(description, 2, new Set(["api-reference"])) : null;
+    if (described)
+        tree.push({ type: "prose", html: described.html });
+    return {
+        slug: "index",
+        title,
+        tree,
+        headings: [{ depth: 1, slug: "api-reference", text: title }, ...(described?.headings ?? [])],
+    };
+}
+function buildNav(spec, pages, tagToOps, untagged, hrefPrefix, tagSlugs) {
+    const nav = [];
+    const root = {
+        label: txt(spec.info?.title) || "API Reference",
+        href: hrefHref(hrefPrefix, "index"),
+    };
+    nav.push(root);
+    // Use spec.tags[] order when present so authors control nav order.
+    const declaredTagOrder = Array.isArray(spec.tags)
+        ? spec.tags.map((t) => txt(t?.name)).filter(Boolean)
+        : [];
+    const seenTags = new Set();
+    const tagOrder = [];
+    for (const t of declaredTagOrder) {
+        if (tagToOps.has(t)) {
+            tagOrder.push(t);
+            seenTags.add(t);
+        }
+    }
+    for (const t of tagToOps.keys()) {
+        if (!seenTags.has(t))
+            tagOrder.push(t);
+    }
+    for (const tagName of tagOrder) {
+        const ops = tagToOps.get(tagName) || [];
+        const tagSlug = tagSlugs.get(tagName);
+        nav.push({
+            label: tagName,
+            href: hrefHref(hrefPrefix, tagSlug),
+            children: ops
+                .slice()
+                .sort(byMethodThenPath)
+                .map((op) => ({
+                label: op.title,
+                href: hrefHref(hrefPrefix, op.slug),
+            })),
+        });
+    }
+    if (untagged.length > 0) {
+        nav.push({
+            label: "Other",
+            children: untagged
+                .slice()
+                .sort(byMethodThenPath)
+                .map((op) => ({
+                label: op.title,
+                href: hrefHref(hrefPrefix, op.slug),
+            })),
+        });
+    }
+    return nav;
+}
+function byMethodThenPath(a, b) {
+    const m = a.method.localeCompare(b.method);
+    if (m !== 0)
+        return m;
+    return a.path.localeCompare(b.path);
+}
+function hrefHref(prefix, slug) {
+    const p = prefix ? `${prefix}/` : "/";
+    return slug === "index" ? p : `${p}${slug}`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * A spec description (CommonMark, per OpenAPI) → HTML, raw HTML off: a `<`
+ * in the spec is escaped, and markdown-it refuses `javascript:` links.
+ * Plain-text paragraphs showed a spec's `## Authentication` literally.
+ */
+const md = new MarkdownIt({ html: false, linkify: false });
+//# sourceMappingURL=core.js.map