@dogsbay/format-openapi 0.2.0-beta.117 → 0.2.0-beta.118

package/dist/core.js

@@ -0,0 +1,658 @@
+/**
+ * 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 (t?.name)
+            tagDescriptions.set(t.name, t.description || "");
+    }
+    const tagToOps = new Map();
+    const untagged = [];
+    for (const op of collectOperations(spec)) {
+        const { method, path, operation, props } = op;
+        const primaryTag = props.tags?.[0];
+        const tagSlug = primaryTag ? slugifyTag(primaryTag) : "";
+        const opSlug = operationToSlug(method, path, operation.operationId);
+        const slug = tagSlug ? `${tagSlug}/${opSlug}` : opSlug;
+        const title = 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 = slugifyTag(tagName);
+        const description = tagDescriptions.get(tagName) || "";
+        pages.push(buildTagPage(tagName, tagSlug, description, ops));
+    }
+    // Root info page.
+    const info = spec.info || {};
+    pages.push(buildInfoPage(info.title || "API Reference", info.description || "", 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);
+    return { pages, nav };
+}
+/**
+ * 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") {
+    let doc = parsed;
+    if (!doc || typeof doc !== "object")
+        throw new Error(`${label} is not an OpenAPI document`);
+    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;
+}
+/**
+ * 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;
+        },
+    };
+}
+/** Every operation in the spec, in document order, as `endpoint` props. */
+function collectOperations(spec) {
+    const baseUrl = spec.servers?.[0]?.url || "";
+    const out = [];
+    for (const [path, pathItem] of Object.entries(spec.paths || {})) {
+        if (!pathItem)
+            continue;
+        for (const method of HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const opTags = Array.isArray(operation.tags) ? operation.tags : [];
+            const props = {
+                method,
+                path,
+                baseUrl,
+                summary: operation.summary || undefined,
+                description: operation.description || undefined,
+                operationId: 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),
+            };
+            out.push({ method, path, operation, props });
+        }
+    }
+    return out;
+}
+/**
+ * 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 = {}) {
+    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 (info.version) {
+        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 (t?.name)
+            tagDescriptions.set(t.name, 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 (prop.description)
+        result.description = prop.description;
+    if (prop.nullable)
+        result.nullable = true;
+    if (prop.format)
+        result.format = prop.format;
+    if (prop.enum)
+        result.enum = prop.enum;
+    if (prop.default !== undefined)
+        result.default = prop.default;
+    if (prop.example !== undefined)
+        result.example = 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 (!p?.name || !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 (p.description)
+            param.description = p.description;
+        if (p.schema?.default !== undefined) {
+            param.default = String(p.schema.default);
+        }
+        if (p.schema?.enum)
+            param.enum = 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: generateExampleFromSchema(mediaType.schema),
+    };
+}
+function extractResponses(operation) {
+    if (!operation.responses)
+        return [];
+    return Object.entries(operation.responses)
+        .filter(([status]) => status !== "default")
+        .map(([status, resp]) => {
+        const result = {
+            status,
+            description: 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 = generateExampleFromSchema(rawSchema);
+            }
+        }
+        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 });
+    const items = ops.map((op) => ({
+        type: "list-item",
+        children: [
+            {
+                type: "prose",
+                html: `<a href="${escapeAttr(op.slug)}"><code>${op.method.toUpperCase()}</code> ${escapeHtml(op.path)}</a>${op.deprecated ? ' <span class="text-muted-foreground">(deprecated)</span>' : ""}`,
+            },
+        ],
+    }));
+    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) {
+    const nav = [];
+    const root = {
+        label: (spec.info && 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) => 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 = slugifyTag(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;");
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+/**
+ * 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