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

package/dist/parse.js

@@ -19,20 +19,8 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve, join, isAbsolute } from "node:path";
-import { dereference, upgrade } from "@scalar/openapi-parser";
-import MarkdownIt from "markdown-it";
 import { parse as parseYaml } from "yaml";
-import { operationToSlug, slugifyTag } from "./slug.js";
-import { resolveCodeSamples } from "./code-samples.js";
-const HTTP_METHODS = [
-    "get",
-    "post",
-    "put",
-    "patch",
-    "delete",
-    "head",
-    "options",
-];
+import { embedSpec, parseSpecText, prepareSpec, specToPages, } from "./core.js";
 /** Extensions a spec file can plausibly have. See the note in detectSpecPath. */
 const SPEC_FILE_EXT = /\.(ya?ml|json)$/i;
 /** Auto-detect spec location given the configured source path. */
@@ -160,235 +148,19 @@ export async function parseOpenApiSpec(sourcePath, options = {}) {
         throw new Error(`OpenAPI spec not found at ${sourcePath}. Looked for openapi.{yaml,yml,json} ` +
             `and spec.{yaml,yml,json} (or expected a direct file path / URL).`);
     }
-    const spec = await loadSpec(specPath);
-    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: 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 };
-}
-/**
- * Read, parse and dereference a spec. 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.
- */
-async function loadSpec(specPath) {
-    const raw = await readSpecText(specPath);
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        parsed = parseYaml(raw);
-    }
-    if (typeof parsed?.swagger === "string" && parsed.swagger.startsWith("2")) {
-        parsed = upgrade(parsed).specification;
-    }
-    const { schema: spec } = await dereference(parsed);
-    if (!spec) {
-        throw new Error(`Failed to dereference OpenAPI spec at ${specPath}`);
-    }
-    return spec;
+    return specToPages(await loadSpec(specPath), options);
 }
-/** 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;
+/** Read a spec file (or URL) and prepare it (core.ts `prepareSpec`). */
+export async function loadSpec(specPath) {
+    return prepareSpec(parseSpecText(await readSpecText(specPath), parseYaml), specPath);
 }
 /**
- * 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.
- *
- * `parseOpenApiSpec` 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.
+ * A whole spec as the BODY of one page (core.ts `embedSpec`), read from a
+ * file. Each call parses the spec; a build that embeds one spec on several
+ * pages uses `createSpecCache` and `embedSpec` instead.
  */
 export async function openApiEmbed(specPath, options = {}) {
-    const spec = await loadSpec(specPath);
-    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) {
-        const node = { type: "endpoint", props: 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 };
+    return embedSpec(await loadSpec(specPath), options);
 }
 async function readSpecText(specPath) {
     if (specPath.startsWith("http://") || specPath.startsWith("https://")) {
@@ -402,363 +174,4 @@ async function readSpecText(specPath) {
     const abs = isAbsolute(specPath) ? specPath : resolve(specPath);
     return await readFile(abs, "utf-8");
 }
-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=parse.js.map