@scalar/openapi-to-markdown 0.6.0 → 1.0.0

package/dist/load-document.d.ts

@@ -0,0 +1,4 @@
+import { type OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+/** Coerce one plain document and keep references linked to shared targets. */
+export declare const loadDocument: (input: OpenApiDocument | Record<string, unknown> | string) => Promise<OpenApiDocument>;
+//# sourceMappingURL=load-document.d.ts.map

package/dist/load-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-document.d.ts","sourceRoot":"","sources":["../src/load-document.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,8DAA8D,CAAA;AAyErE,8EAA8E;AAC9E,eAAO,MAAM,YAAY,GACvB,OAAO,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,KACxD,OAAO,CAAC,eAAe,CAoFzB,CAAA"}

package/dist/load-document.js

@@ -0,0 +1,151 @@
+import { parseJsonPointerSegments } from '@scalar/helpers/json/parse-json-pointer-segments';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { bundle } from '@scalar/json-magic/bundle';
+import { convertToLocalRef } from '@scalar/json-magic/helpers/convert-to-local-ref';
+import { getId, getSchemas } from '@scalar/json-magic/helpers/get-schemas';
+import { getValueByPath } from '@scalar/json-magic/helpers/get-value-by-path';
+import { normalize } from '@scalar/json-magic/helpers/normalize';
+import { getRaw } from '@scalar/json-magic/magic-proxy';
+import { upgrade } from '@scalar/openapi-upgrader';
+import { deepClone } from '@scalar/workspace-store/helpers/deep-clone';
+import { coerceValue } from '@scalar/workspace-store/schemas/typebox-coerce';
+import { OpenAPIDocumentSchema, } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+/**
+ * Link references in a private, bundled document without proxies or expanded copies.
+ * JSON Magic owns `$id` and anchor indexing, which keeps local-reference behavior
+ * aligned with the external-reference bundler without retaining a second resolver.
+ * Non-enumerable links preserve serialization and share recursive schema targets.
+ * Casting temporarily uses enumerable links to satisfy TypeBox reference branches.
+ * Returns whether external references remain and require bundling.
+ */
+const attachRefValues = (document, enumerable = false, schemas = getSchemas(document)) => {
+    // A single traversal covers both normal trees and previously linked recursive objects.
+    const seen = new WeakSet();
+    let hasExternalReferences = false;
+    const visit = (node, context = getId(document) ?? '') => {
+        if (node === null || typeof node !== 'object' || seen.has(node)) {
+            return;
+        }
+        seen.add(node);
+        // Nested `$id` values redefine the base for relative references and anchors.
+        const base = getId(node) ?? context;
+        if (isObject(node) && typeof node.$ref === 'string') {
+            const ref = node.$ref;
+            const path = ref === '#' ? '' : convertToLocalRef(ref, base, schemas);
+            // Point to the bundled target instead of copying it into every reference.
+            const target = path === undefined ? undefined : getValueByPath(document, parseJsonPointerSegments(`/${path}`)).value;
+            // JSON Magic only needs to bundle references outside this document's resource index.
+            if (path === undefined && ref.split('#')[0]) {
+                hasExternalReferences = true;
+            }
+            if (enumerable) {
+                const followed = new WeakSet();
+                let resolved = target;
+                // TypeBox needs the final target, so collapse a pre-existing reference chain safely.
+                while (isObject(resolved) && '$ref-value' in resolved && !followed.has(resolved)) {
+                    followed.add(resolved);
+                    resolved = resolved['$ref-value'];
+                }
+                if (resolved !== undefined) {
+                    Object.defineProperty(node, '$ref-value', {
+                        value: resolved,
+                        enumerable,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+            }
+            else if (target !== undefined) {
+                Object.defineProperty(node, '$ref-value', {
+                    value: target,
+                    enumerable,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+        }
+        // Preserve the nearest resource base while walking into child schemas.
+        for (const child of Object.values(node)) {
+            visit(child, base);
+        }
+    };
+    visit(document);
+    return hasExternalReferences;
+};
+/** Coerce one plain document and keep references linked to shared targets. */
+export const loadDocument = async (input) => {
+    let raw;
+    let origin;
+    // Reference links are attached below, so never mutate the caller's document.
+    if (typeof input !== 'string') {
+        raw = deepClone(getRaw(input));
+    }
+    // Inline JSON and YAML avoid the I/O path; URLs and files are loaded afterward.
+    else {
+        const normalized = normalize(input);
+        if (isObject(normalized)) {
+            raw = normalized;
+        }
+        else if (/^https?:\/\//i.test(input)) {
+            const response = await fetch(input);
+            if (!response.ok) {
+                throw new Error(`Failed to load OpenAPI document (HTTP ${response.status})`);
+            }
+            raw = normalize(await response.text());
+            origin = input;
+        }
+        else {
+            const [{ resolve }, { readFile }] = await Promise.all([import('node:path'), import('node:fs/promises')]);
+            origin = resolve(input);
+            raw = normalize(await readFile(origin, 'utf8'));
+        }
+    }
+    if (!isObject(raw)) {
+        throw new Error('Failed to load OpenAPI document');
+    }
+    // Upgrade before indexing so reference resolution sees one consistent dialect.
+    const upgraded = upgrade(raw, '3.2');
+    const upgradedSchemas = getSchemas(upgraded);
+    const hasExternalReferences = attachRefValues(upgraded, false, upgradedSchemas);
+    let document = upgraded;
+    let schemas = upgradedSchemas;
+    // Resolve external targets only when the initial local-reference pass finds them.
+    if (hasExternalReferences) {
+        const errors = [];
+        const plugins = typeof process === 'undefined'
+            ? [(await import('@scalar/json-magic/bundle/plugins/browser')).fetchUrls()]
+            : [
+                (await import('@scalar/json-magic/bundle/plugins/node')).fetchUrls(),
+                (await import('@scalar/json-magic/bundle/plugins/node')).readFiles(),
+            ];
+        document = await bundle(upgraded, {
+            plugins,
+            origin,
+            treeShake: false,
+            hooks: { onResolveError: (node) => errors.push(`Failed to resolve ${node.$ref}`) },
+        });
+        if (errors.length) {
+            throw new Error(errors.join('\n'));
+        }
+        schemas = getSchemas(document);
+        attachRefValues(document, false, schemas);
+    }
+    // TypeBox's reference branches require an enumerable $ref-value during casting.
+    // Restore non-enumerable shared links afterward so rendering never expands the graph.
+    attachRefValues(document, true, schemas);
+    const coerced = coerceValue(OpenAPIDocumentSchema, document);
+    // Keep extension resources that local and bundled references can target.
+    for (const [key, value] of Object.entries(document)) {
+        if (key.startsWith('x-') && !(key in coerced)) {
+            Object.defineProperty(coerced, key, {
+                value,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+        }
+    }
+    // Redefine TypeBox's temporary links as non-enumerable links to coerced targets.
+    attachRefValues(coerced, false, schemas);
+    return coerced;
+};

package/dist/markdown-nodes.d.ts

@@ -0,0 +1,25 @@
+import type { Heading, InlineCode, Link, List, ListItem, Paragraph, PhrasingContent, Strong, Text } from 'mdast';
+/** Collapse HTML-style inline whitespace; the serializer escapes generated text as Markdown. */
+export declare const text: (value: unknown) => Text;
+/** Inline code fences are chosen by the serializer. */
+export declare const inlineCode: (value: unknown) => InlineCode;
+/** Construct a paragraph from phrasing nodes. */
+export declare const paragraph: (...children: PhrasingContent[]) => Paragraph;
+/** Construct an emphasized label. */
+export declare const strong: (...children: PhrasingContent[]) => Strong;
+/** Construct a section heading. */
+export declare const heading: (depth: Heading["depth"], ...children: PhrasingContent[]) => Heading;
+/** Construct a list item that may contain nested blocks. */
+export declare const item: (...children: ListItem["children"]) => ListItem;
+/** Construct an unordered list. */
+export declare const list: (children: ListItem[]) => List;
+/**
+ * Retain rehype-sanitize's protocol policy. The general sanitizeUrl helper allows
+ * additional schemes and excludes IRC/XMPP, so it is not compatible here.
+ */
+export declare const safeUrl: (url: string) => string;
+/** Links from OpenAPI metadata follow the same URL policy as descriptions. */
+export declare const link: (url: string, label: string) => Link;
+/** Render a metadata label and value with the established nonbreaking separator. */
+export declare const field: (label: string, value: PhrasingContent) => ListItem;
+//# sourceMappingURL=markdown-nodes.d.ts.map

package/dist/markdown-nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-nodes.d.ts","sourceRoot":"","sources":["../src/markdown-nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEhH,gGAAgG;AAChG,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,IAGpC,CAAA;AACF,uDAAuD;AACvD,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,UAAkE,CAAA;AAC9G,iDAAiD;AACjD,eAAO,MAAM,SAAS,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,SAA8C,CAAA;AACzG,qCAAqC;AACrC,eAAO,MAAM,MAAM,GAAI,GAAG,UAAU,eAAe,EAAE,KAAG,MAAwC,CAAA;AAChG,mCAAmC;AACnC,eAAO,MAAM,OAAO,GAAI,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,UAAU,eAAe,EAAE,KAAG,OAIhF,CAAA;AACF,4DAA4D;AAC5D,eAAO,MAAM,IAAI,GAAI,GAAG,UAAU,QAAQ,CAAC,UAAU,CAAC,KAAG,QAA2D,CAAA;AACpH,mCAAmC;AACnC,eAAO,MAAM,IAAI,GAAI,UAAU,QAAQ,EAAE,KAAG,IAAmE,CAAA;AAC/G;;;GAGG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,MAIrC,CAAA;AACD,8EAA8E;AAC9E,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,KAAG,IAAsE,CAAA;AACxH,oFAAoF;AACpF,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,EAAE,OAAO,eAAe,KAAG,QACK,CAAA"}

package/dist/markdown-nodes.js

@@ -0,0 +1,34 @@
+/** Collapse HTML-style inline whitespace; the serializer escapes generated text as Markdown. */
+export const text = (value) => ({
+    type: 'text',
+    value: String(value ?? '').replace(/[\t\n\f\r ]+/g, ' '),
+});
+/** Inline code fences are chosen by the serializer. */
+export const inlineCode = (value) => ({ type: 'inlineCode', value: String(value ?? '') });
+/** Construct a paragraph from phrasing nodes. */
+export const paragraph = (...children) => ({ type: 'paragraph', children });
+/** Construct an emphasized label. */
+export const strong = (...children) => ({ type: 'strong', children });
+/** Construct a section heading. */
+export const heading = (depth, ...children) => ({
+    type: 'heading',
+    depth,
+    children,
+});
+/** Construct a list item that may contain nested blocks. */
+export const item = (...children) => ({ type: 'listItem', spread: false, children });
+/** Construct an unordered list. */
+export const list = (children) => ({ type: 'list', ordered: false, spread: false, children });
+/**
+ * Retain rehype-sanitize's protocol policy. The general sanitizeUrl helper allows
+ * additional schemes and excludes IRC/XMPP, so it is not compatible here.
+ */
+export const safeUrl = (url) => {
+    const normalized = url.replace(/[\u0000-\u0020\u007f-\u009f]/g, '');
+    const protocol = /^([^/?#]*):/.exec(normalized)?.[1];
+    return protocol && !['http', 'https', 'irc', 'ircs', 'mailto', 'xmpp'].includes(protocol.toLowerCase()) ? '' : url;
+};
+/** Links from OpenAPI metadata follow the same URL policy as descriptions. */
+export const link = (url, label) => ({ type: 'link', url: safeUrl(url), children: [text(label)] });
+/** Render a metadata label and value with the established nonbreaking separator. */
+export const field = (label, value) => item(paragraph(strong(text(`${label}:`)), text('\u00a0'), value));

package/dist/parse-description.d.ts

@@ -0,0 +1,6 @@
+import type { RootContent } from 'mdast';
+/** Parse one description into blocks suitable for insertion into the current document. */
+export type DescriptionParser = (value?: string) => Promise<RootContent[]>;
+/** Share parsing across pages while giving every rendered document its own reference namespace. */
+export declare const createDescriptionParser: () => (() => DescriptionParser);
+//# sourceMappingURL=parse-description.d.ts.map

package/dist/parse-description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-description.d.ts","sourceRoot":"","sources":["../src/parse-description.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,OAAO,CAAA;AA2ErD,0FAA0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;AAE1E,mGAAmG;AACnG,eAAO,MAAM,uBAAuB,QAAO,CAAC,MAAM,iBAAiB,CA0ClE,CAAA"}

package/dist/parse-description.js

@@ -0,0 +1,116 @@
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { safeUrl } from './markdown-nodes.js';
+const parser = unified().use(remarkParse).use(remarkGfm).freeze();
+const containsHtml = (node) => node.type === 'html' || ('children' in node && node.children.some(containsHtml));
+/** Remove images and unsafe URLs without converting ordinary Markdown to HTML. */
+const clean = (node) => {
+    if ('url' in node) {
+        node.url = safeUrl(node.url);
+    }
+    if ('children' in node) {
+        for (const child of node.children)
+            clean(child);
+        // The filter preserves the parent's existing child types.
+        const previousLength = node.children.length;
+        node.children = node.children.filter((child) => child.type !== 'image' &&
+            child.type !== 'imageReference' &&
+            !([
+                'strong',
+                'emphasis',
+                'delete',
+                'link',
+                'linkReference',
+                'paragraph',
+                'heading',
+                'blockquote',
+                'list',
+                'listItem',
+            ].includes(child.type) &&
+                'children' in child &&
+                child.children.every((descendant) => descendant.type === 'text' && !descendant.value.trim())));
+        if (node.children.length !== previousLength) {
+            const first = node.children.at(0);
+            const last = node.children.at(-1);
+            if (first?.type === 'text')
+                first.value = first.value.trimStart();
+            if (last?.type === 'text')
+                last.value = last.value.trimEnd();
+        }
+    }
+    delete node.position;
+};
+/** Removed images must not leave their reference definitions or empty paragraphs behind. */
+const pruneDefinitions = (tree) => {
+    const links = new Set();
+    const footnotes = new Set();
+    const definitions = new Map(tree.children.filter((node) => node.type === 'footnoteDefinition').map((node) => [node.identifier, node]));
+    const collect = (node) => {
+        if (node.type === 'linkReference')
+            links.add(node.identifier);
+        if (node.type === 'footnoteReference')
+            footnotes.add(node.identifier);
+        if ('children' in node)
+            node.children.forEach(collect);
+    };
+    tree.children.filter((node) => node.type !== 'footnoteDefinition').forEach(collect);
+    // Set iteration also visits footnotes discovered inside another footnote.
+    for (const identifier of footnotes)
+        definitions.get(identifier)?.children.forEach(collect);
+    tree.children = tree.children.filter((node) => {
+        if (node.type === 'definition')
+            return links.has(node.identifier);
+        if (node.type === 'footnoteDefinition')
+            return footnotes.has(node.identifier);
+        if (node.type === 'paragraph')
+            return node.children.some((child) => child.type !== 'text' || child.value.trim());
+        return true;
+    });
+};
+/** Share parsing across pages while giving every rendered document its own reference namespace. */
+export const createDescriptionParser = () => {
+    const cache = new Map();
+    const parse = async (value) => {
+        const parsed = parser.parse(value);
+        // Raw HTML and GitHub alerts retain Scalar's existing conversion behavior.
+        const tree = containsHtml(parsed) || /^\s*>\s*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION|SUCCESS)\]/im.test(value)
+            ? await (await import('./parse-html-description.js')).parseHtmlDescription(value)
+            : parsed;
+        clean(tree);
+        pruneDefinitions(tree);
+        return tree.children;
+    };
+    const namespace = (node, prefix) => {
+        const copy = { ...node };
+        if ('identifier' in copy) {
+            copy.identifier = `${prefix}${copy.identifier}`;
+            if ('label' in copy)
+                copy.label = copy.identifier;
+            if ('referenceType' in copy)
+                copy.referenceType = 'full';
+        }
+        if ('children' in copy)
+            copy.children = copy.children.map((child) => namespace(child, prefix));
+        return copy;
+    };
+    const hasReference = (node) => 'identifier' in node || ('children' in node && node.children.some(hasReference));
+    return () => {
+        const state = { nextId: 0 };
+        return async (value) => {
+            if (!value)
+                return [];
+            const prefix = `description-${state.nextId++}-`;
+            const cached = cache.get(value) ?? parse(value);
+            if (!cache.has(value)) {
+                if (cache.size >= 256)
+                    cache.clear();
+                cache.set(value, cached);
+            }
+            const nodes = await cached;
+            // Ordinary Markdown can share immutable nodes. Reference definitions need a copy
+            // so repeated descriptions and concurrent page renders cannot affect one another.
+            return nodes.map((node) => (hasReference(node) ? namespace(node, prefix) : node));
+        };
+    };
+};

package/dist/parse-html-description.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+/** Compatibility path loaded only for descriptions containing HTML or Scalar alerts. */
+export declare const parseHtmlDescription: (value: string) => Root;
+//# sourceMappingURL=parse-html-description.d.ts.map

package/dist/parse-html-description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-html-description.d.ts","sourceRoot":"","sources":["../src/parse-html-description.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAQjC,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,IAGpD,CAAA"}

package/dist/parse-html-description.js

@@ -0,0 +1,11 @@
+import { htmlFromMarkdown } from '@scalar/code-highlight';
+import rehypeParse from 'rehype-parse';
+import rehypeRemark from 'rehype-remark';
+import rehypeSanitize from 'rehype-sanitize';
+import { unified } from 'unified';
+const converter = unified().use(rehypeParse, { fragment: true }).use(rehypeSanitize).use(rehypeRemark).freeze();
+/** Compatibility path loaded only for descriptions containing HTML or Scalar alerts. */
+export const parseHtmlDescription = (value) => {
+    const html = htmlFromMarkdown(value, { removeTags: ['img', 'picture'] });
+    return converter.runSync(converter.parse(html));
+};

package/dist/render-document.d.ts

@@ -0,0 +1,4 @@
+import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+/** Build Markdown directly, retaining caches only for this immutable document snapshot. */
+export declare const createDocumentRenderer: () => ((document: OpenApiDocument) => Promise<string>);
+//# sourceMappingURL=render-document.d.ts.map

package/dist/render-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,8DAA8D,CAAA;AAcpH,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAgIxF,CAAA"}

package/dist/render-document.js

@@ -0,0 +1,112 @@
+import { forEachPathItemOperation, getResolvedPathItem, } from '@scalar/workspace-store/helpers/for-each-path-item-operation';
+import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import remarkGfm from 'remark-gfm';
+import remarkStringify from 'remark-stringify';
+import { unified } from 'unified';
+import { field, heading, inlineCode, item, link, list, paragraph, strong, text } from './markdown-nodes.js';
+import { createDescriptionParser } from './parse-description.js';
+import { renderOperation } from './render-operation.js';
+import { createSchemaRenderer } from './render-schema.js';
+import { renderSecurity } from './render-security.js';
+const serializer = unified().use(remarkGfm).use(remarkStringify, { bullet: '-' }).freeze();
+/** Build Markdown directly, retaining caches only for this immutable document snapshot. */
+export const createDocumentRenderer = () => {
+    const descriptions = createDescriptionParser();
+    const schemas = createSchemaRenderer();
+    return async (document) => {
+        const description = descriptions();
+        const { info } = document;
+        const metadata = [
+            field('OpenAPI Version', inlineCode(document.openapi)),
+            field('API Version', inlineCode(info.version)),
+        ];
+        if (info.termsOfService)
+            metadata.push(field('Terms of service', link(info.termsOfService, info.termsOfService)));
+        if (info.contact) {
+            const contact = [text(info.contact.name ?? '')];
+            metadata.push(item(paragraph(strong(text('Contact:')), text(' '), ...contact, ...(info.contact.url ? [text(' '), link(info.contact.url, info.contact.url)] : []), ...(info.contact.email ? [text(' '), link(`mailto:${info.contact.email}`, info.contact.email)] : []))));
+        }
+        if (info.license)
+            metadata.push(field('License', info.license.url ? link(info.license.url, info.license.name ?? '') : text(info.license.name)));
+        const nodes = [
+            heading(1, text(info.title)),
+            list(metadata),
+            ...(await description(info.description)),
+        ];
+        if (document.servers?.length) {
+            nodes.push(heading(2, text('Servers')));
+            const servers = document.servers.map((server) => {
+                const nested = [];
+                if (server.description)
+                    nested.push(field('Description', text(server.description)));
+                const variables = Object.entries(server.variables ?? {});
+                if (variables.length)
+                    nested.push(item(paragraph(strong(text('Variables:'))), list(variables.map(([name, variable]) => item(paragraph(inlineCode(name), text(' (default: '), inlineCode(variable.default), text(`)${variable.description ? `: ${variable.description}` : ''}`)))))));
+                const entry = field('URL', inlineCode(server.url));
+                if (nested.length)
+                    entry.children.push(list(nested));
+                return entry;
+            });
+            nodes.push(list(servers));
+        }
+        nodes.push(...(await renderSecurity(document.security, document.components?.securitySchemes, description)));
+        if (document.tags?.length) {
+            nodes.push(heading(2, text('Tags')));
+            for (const tag of document.tags) {
+                nodes.push(heading(3, text(tag.name)), ...(await description(tag.description)));
+                if (tag.externalDocs)
+                    nodes.push(paragraph(link(tag.externalDocs.url, tag.externalDocs.description ?? tag.externalDocs.url)));
+            }
+        }
+        const sections = [];
+        const flush = () => {
+            if (nodes.length) {
+                const tree = { type: 'root', children: nodes.splice(0) };
+                sections.push(serializer.stringify(tree).trimEnd());
+            }
+        };
+        flush();
+        for (const group of [
+            { title: 'Operations', paths: document.paths, webhook: false },
+            { title: 'Webhooks', paths: document.webhooks, webhook: true },
+        ]) {
+            let hasOperations = false;
+            for (const [path, reference] of Object.entries(group.paths ?? {})) {
+                const pathItem = getResolvedPathItem(reference);
+                if (!pathItem)
+                    continue;
+                const entries = [];
+                forEachPathItemOperation(reference, (method, operation) => {
+                    entries.push({ method, operation: getResolvedRef(operation, mergeSiblingReferences) });
+                });
+                for (const { method, operation } of entries) {
+                    if (!hasOperations) {
+                        nodes.push(heading(2, text(group.title)));
+                        hasOperations = true;
+                    }
+                    nodes.push(...(await renderOperation(document, path, method, pathItem, operation, group.webhook, {
+                        description,
+                        schemas,
+                    })));
+                    flush();
+                }
+            }
+        }
+        const models = Object.entries(document.components?.schemas ?? {});
+        if (models.length)
+            nodes.push(heading(2, text('Schemas')));
+        for (const [name, schema] of models) {
+            const view = schemas.view(schema);
+            nodes.push(heading(3, text(view.title ?? name)), list([
+                view.type
+                    ? field('Type', inlineCode(Array.isArray(view.type) ? view.type.join(' | ') : view.type))
+                    : item(paragraph(strong(text('Type:')))),
+            ]), ...(await description(view.description)), ...schemas.render(schema));
+            if (view.type === 'object')
+                nodes.push(paragraph(strong(text('Example:'))), schemas.example(schema));
+            flush();
+        }
+        flush();
+        return `${sections.join('\n\n')}\n`;
+    };
+};

package/dist/render-operation.d.ts

@@ -0,0 +1,13 @@
+import type { OpenApiDocument, OperationObject, PathItemObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import type { RootContent } from 'mdast';
+import type { DescriptionParser } from './parse-description.js';
+import type { SchemaRenderer } from './render-schema.js';
+/** Dependencies shared by all sections of one prepared renderer. */
+type RenderContext = {
+    description: DescriptionParser;
+    schemas: SchemaRenderer;
+};
+/** Render effective operation context without mutating the prepared document. */
+export declare const renderOperation: (document: OpenApiDocument, path: string, method: string, pathItem: PathItemObject, operation: OperationObject, webhook: boolean, { description, schemas }: RenderContext) => Promise<RootContent[]>;
+export {};
+//# sourceMappingURL=render-operation.d.ts.map

package/dist/render-operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-operation.d.ts","sourceRoot":"","sources":["../src/render-operation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EAGf,MAAM,8DAA8D,CAAA;AACrE,OAAO,KAAK,EAAY,WAAW,EAAE,MAAM,OAAO,CAAA;AAGlD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGrD,oEAAoE;AACpE,KAAK,aAAa,GAAG;IACnB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,OAAO,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,eAAe,GAC1B,UAAU,eAAe,EACzB,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,UAAU,cAAc,EACxB,WAAW,eAAe,EAC1B,SAAS,OAAO,EAChB,0BAA0B,aAAa,KACtC,OAAO,CAAC,WAAW,EAAE,CAgGvB,CAAA"}

package/dist/render-operation.js

@@ -0,0 +1,89 @@
+import { getResolvedRef, mergeSiblingReferences } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { field, heading, inlineCode, item, list, paragraph, strong, text } from './markdown-nodes.js';
+import { renderSecurity } from './render-security.js';
+/** Render effective operation context without mutating the prepared document. */
+export const renderOperation = async (document, path, method, pathItem, operation, webhook, { description, schemas }) => {
+    const stability = operation['x-scalar-stability'];
+    const title = (operation.summary || `${method.toUpperCase()} ${path}`) +
+        (stability ? ` (${stability})` : operation.deprecated ? ' ⚠️ Deprecated' : '');
+    const metadata = [
+        field('Method', inlineCode(method.toUpperCase())),
+        field(webhook ? 'Webhook' : 'Path', inlineCode(path)),
+    ];
+    if (operation.tags)
+        metadata.push(field('Tags', text(operation.tags.join(', '))));
+    if (stability)
+        metadata.push(field('Stability', text(stability)));
+    const nodes = [heading(3, text(title)), list(metadata), ...(await description(operation.description))];
+    const servers = operation.servers ?? pathItem.servers ?? document.servers;
+    if (servers?.length) {
+        nodes.push(heading(4, text('Effective servers')));
+        const serverItems = [];
+        for (const server of servers) {
+            const blocks = [
+                paragraph(inlineCode(server.url)),
+                ...(await description(server.description)),
+            ];
+            const variables = Object.entries(server.variables ?? {});
+            if (variables.length)
+                blocks.push(list(variables.map(([name, variable]) => item(paragraph(text(`${name}: `), inlineCode(variable.default))))));
+            serverItems.push(item(...blocks));
+        }
+        nodes.push(list(serverItems));
+    }
+    nodes.push(...(await renderSecurity(operation.security ?? document.security, document.components?.securitySchemes, description)));
+    const parameters = new Map();
+    for (const reference of [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])]) {
+        const parameter = getResolvedRef(reference, mergeSiblingReferences);
+        if (parameter)
+            parameters.set(`${parameter.in}:${parameter.name}`, parameter);
+    }
+    if (parameters.size)
+        nodes.push(heading(4, text('Parameters')));
+    for (const parameter of parameters.values()) {
+        nodes.push(heading(5, inlineCode(parameter.name), text(`${parameter.required ? ' required' : ''}${parameter.deprecated ? ' deprecated' : ''}`)));
+        const fields = [field('In', inlineCode(parameter.in))];
+        if ('style' in parameter && parameter.style)
+            fields.push(field('Style', inlineCode(parameter.style)));
+        if ('explode' in parameter && typeof parameter.explode === 'boolean')
+            fields.push(field('Explode', inlineCode(parameter.explode)));
+        if (parameter.allowEmptyValue)
+            fields.push(field('Allow Empty Value', text('true')));
+        if ('allowReserved' in parameter && parameter.allowReserved)
+            fields.push(field('Allow Reserved', text('true')));
+        nodes.push(list(fields), ...(await description(parameter.description)));
+        if ('schema' in parameter && parameter.schema)
+            nodes.push(...schemas.render(parameter.schema));
+        for (const [mediaType, content] of Object.entries('content' in parameter ? (parameter.content ?? {}) : {})) {
+            nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
+            if (content.schema)
+                nodes.push(...schemas.render(content.schema));
+        }
+    }
+    const body = getResolvedRef(operation.requestBody, mergeSiblingReferences);
+    if (body?.content) {
+        nodes.push(heading(4, text('Request Body')), ...(await description(body.description)));
+        if (body.required)
+            nodes.push(paragraph(strong(text('Required:')), text(' true')));
+        for (const [mediaType, content] of Object.entries(body.content)) {
+            nodes.push(heading(5, text(`Content-Type: ${mediaType}`)));
+            if (content.schema)
+                nodes.push(...schemas.render(content.schema), paragraph(strong(text('Example:'))), schemas.example(content.schema, mediaType.includes('xml')));
+        }
+    }
+    const responses = Object.entries(operation.responses ?? {}).flatMap(([status, reference]) => {
+        const response = getResolvedRef(reference, mergeSiblingReferences);
+        return response ? [{ status, response }] : [];
+    });
+    if (responses.length)
+        nodes.push(heading(4, text('Responses')));
+    for (const { status, response } of responses) {
+        nodes.push(heading(5, text(`Status: ${status}${response.description ? ` ${response.description}` : ''}`)));
+        for (const [mediaType, content] of Object.entries(response.content ?? {})) {
+            nodes.push(heading(6, text(`Content-Type: ${mediaType}`)));
+            if (content.schema)
+                nodes.push(...schemas.render(content.schema), paragraph(strong(text('Example:'))), schemas.example(content.schema, mediaType.includes('xml')));
+        }
+    }
+    return nodes;
+};

package/dist/render-schema.d.ts

@@ -0,0 +1,31 @@
+import type { MaybeRefSchemaObject, SchemaObject } from '@scalar/workspace-store/schemas/v3.2/strict/schema';
+import type { Code, RootContent } from 'mdast';
+type SchemaView = {
+    schema: SchemaObject;
+    title?: string;
+    description?: string;
+    type?: string | string[];
+    format?: string;
+    enum?: unknown[];
+    default?: unknown;
+    allOf?: MaybeRefSchemaObject[];
+    anyOf?: MaybeRefSchemaObject[];
+    oneOf?: MaybeRefSchemaObject[];
+    not?: MaybeRefSchemaObject;
+    properties: [string, MaybeRefSchemaObject][];
+    required: ReadonlySet<string>;
+    items?: MaybeRefSchemaObject;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+};
+/** Schema normalization is cached separately from ancestry-dependent expansion. */
+export type SchemaRenderer = {
+    view: (schema: MaybeRefSchemaObject) => SchemaView;
+    render: (schema: MaybeRefSchemaObject, depth?: number, ancestors?: readonly unknown[]) => RootContent[];
+    example: (schema: MaybeRefSchemaObject, xml?: boolean) => Code;
+};
+/** Keep merged reference siblings and sorted properties stable throughout an export. */
+export declare const createSchemaRenderer: () => SchemaRenderer;
+export {};
+//# sourceMappingURL=render-schema.d.ts.map

package/dist/render-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-schema.d.ts","sourceRoot":"","sources":["../src/render-schema.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,oDAAoD,CAAA;AAC5G,OAAO,KAAK,EAAE,IAAI,EAA6B,WAAW,EAAE,MAAM,OAAO,CAAA;AAIzE,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC9B,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC9B,KAAK,CAAC,EAAE,oBAAoB,EAAE,CAAA;IAC9B,GAAG,CAAC,EAAE,oBAAoB,CAAA;IAC1B,UAAU,EAAE,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAAE,CAAA;IAC5C,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC7B,KAAK,CAAC,EAAE,oBAAoB,CAAA;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,UAAU,CAAA;IAClD,MAAM,EAAE,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,WAAW,EAAE,CAAA;IACvG,OAAO,EAAE,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAC/D,CAAA;AAED,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,QAAO,cA0FvC,CAAA"}