@scalar/openapi-to-markdown 1.5.2 → 1.5.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @scalar/openapi-to-markdown
 
+## 1.5.4
+
+### Patch Changes
+
+- [#10559](https://github.com/scalar/scalar/pull/10559): Clean up Biome warnings in package code and tests. Handle rejected debounced callbacks and await streaming writes.
+- [#10505](https://github.com/scalar/scalar/pull/10505): Apply formatting and lint compatibility changes for Biome 2.5.15.
+
+## 1.5.3
+
+### Patch Changes
+
+- [#10484](https://github.com/scalar/scalar/pull/10484): Use OpenAPI 3.2 tag summaries as Markdown headings, falling back to tag names.
+
 ## 1.5.2
 
 ## 1.5.1

package/README.md

@@ -143,6 +143,9 @@ Schema normalization and description parsing are cached within each renderer. Re
 schema expansion still tracks ancestors and stops at a depth of ten. Output may use tighter
 list spacing and normalized Markdown escaping compared with earlier versions.
 
+For OpenAPI 3.2 descriptions, tag headings use `summary` when present and otherwise
+use `name`. Tag selectors and operation tag metadata continue to use `name`.
+
 The package only generates Markdown. To produce HTML, pass the Markdown output to a
 Markdown renderer in your application.
 

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

@@ -1 +1 @@
-{"version":3,"file":"document-anchors.d.ts","sourceRoot":"","sources":["../src/document-anchors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,QAAO;IACvC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAmBhE,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,MAAM,GAAI,IAAI,MAAM,KAAG,IAAuD,CAAA"}
+{"version":3,"file":"document-anchors.d.ts","sourceRoot":"","sources":["../src/document-anchors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,QAAO;IACvC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAuBhE,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,MAAM,GAAI,IAAI,MAAM,KAAG,IAAuD,CAAA"}

package/dist/document-anchors.js

@@ -8,13 +8,15 @@ export const createDocumentAnchors = () => {
         get: (kind, identity, label = identity) => {
             const key = JSON.stringify([kind, identity]);
             const previous = ids.get(key);
-            if (previous !== undefined)
+            if (previous !== undefined) {
                 return previous;
+            }
             const base = `scalar-${kind}-${label}`;
             let id = slugs.slug(base);
             // A literal suffix in a later name can collide with the slugger's numeric suffix.
-            while (used.has(id))
+            while (used.has(id)) {
                 id = slugs.slug(base);
+            }
             used.add(id);
             ids.set(key, id);
             return id;

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

@@ -1 +1 @@
-{"version":3,"file":"document-examples.d.ts","sourceRoot":"","sources":["../src/document-examples.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC/D,OAAO,EAAE,KAAK,aAAa,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAEjF,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,OAAO,mBAAmB,CAAA;IAC/B,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;CAC9F,CAAA;AAaD,uGAAuG;AACvG,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,CAAC,OAAO,qBAAqB,CAAC,KAAG,gBAqC1F,CAAA"}
+{"version":3,"file":"document-examples.d.ts","sourceRoot":"","sources":["../src/document-examples.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAEjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC/D,OAAO,EAAE,KAAK,aAAa,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAEjF,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,OAAO,mBAAmB,CAAA;IAC/B,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;CAC9F,CAAA;AAeD,uGAAuG;AACvG,eAAO,MAAM,sBAAsB,GAAI,SAAS,UAAU,CAAC,OAAO,qBAAqB,CAAC,KAAG,gBA4C1F,CAAA"}

package/dist/document-examples.js

@@ -4,8 +4,9 @@ import { getMarkdownExamples } from './get-markdown-examples.js';
 const bookkeeping = new Set(['$ref', '$ref-value', '$global', '$status', '__scalar_']);
 /** Sibling constraints make a reference a different example source from its target. */
 const identity = (source) => {
-    if (!isObject(source.schema))
+    if (!isObject(source.schema)) {
         return undefined;
+    }
     const schema = source.schema;
     const target = '$ref' in schema && Object.keys(schema).every((key) => bookkeeping.has(key)) ? getResolvedRef(schema) : schema;
     return isObject(target) ? target : schema;
@@ -20,12 +21,14 @@ export const createDocumentExamples = (anchors) => {
         get: (...args) => {
             const [source, ...settings] = args;
             const schema = identity(source);
-            if (!schema || source.example !== undefined || Object.keys(source.examples ?? {}).length)
+            if (!schema || source.example !== undefined || Object.keys(source.examples ?? {}).length) {
                 return getMarkdownExamples(...args);
+            }
             const scope = JSON.stringify(settings);
             const previous = cache.get(schema)?.get(scope);
-            if (previous)
+            if (previous) {
                 return previous;
+            }
             // Large APIs must not retain every generated object until the export finishes.
             if (cachedCount >= 256) {
                 cache.clear();
@@ -42,12 +45,14 @@ export const createDocumentExamples = (anchors) => {
             const schema = identity(source);
             const entries = schema ? (shown.get(schema) ?? new Map()) : new Map();
             const previous = entries.get(scope);
-            if (previous?.value === code.value)
+            if (previous?.value === code.value) {
                 return { id: previous.id, previous: true };
+            }
             const id = anchors.get('example', String(++nextId));
             entries.set(scope, { id, value: code.value });
-            if (schema)
+            if (schema) {
                 shown.set(schema, entries);
+            }
             return { id, previous: false };
         },
     };

package/dist/get-markdown-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAMA,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,gFAAgF;AAChF,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GAAG,CACA;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CACpB,CAAA;AAYD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,OAAO,EAAE,cAAoC,KAAG,MA2CjG,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,WAAW,MAAM,EACjB,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,EACrC,gBAAc,KACb,eAAe,EAyCjB,CAAA"}
+{"version":3,"file":"get-markdown-examples.d.ts","sourceRoot":"","sources":["../src/get-markdown-examples.ts"],"names":[],"mappings":"AAMA,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA;AAED,gFAAgF;AAChF,KAAK,eAAe,GAAG;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oFAAoF;IACpF,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,GAAG,CACA;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAClB;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CACpB,CAAA;AAYD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,OAAO,EAAE,cAAoC,KAAG,MAmEjG,CAAA;AAED,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,aAAa,EACrB,WAAW,MAAM,EACjB,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,EACrC,gBAAc,KACb,eAAe,EA6DjB,CAAA"}

package/dist/get-markdown-examples.js

@@ -17,35 +17,47 @@ const MAX_GENERATED_EXAMPLE_VALUES = 10_000;
 export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_VALUES) => {
     const counts = new WeakMap();
     const count = (input, level) => {
-        if (level > EXAMPLE_DEPTH || !isObject(input))
+        if (level > EXAMPLE_DEPTH || !isObject(input)) {
             return 1;
+        }
         const cached = counts.get(input)?.get(level);
-        if (cached !== undefined)
+        if (cached !== undefined) {
             return cached;
+        }
         const schema = getResolvedRef(input, mergeSiblingReferences);
-        if (!isObject(schema))
+        if (!isObject(schema)) {
             return 1;
+        }
         // Supplied examples bypass schema expansion in the generator too.
-        if (schema.example !== undefined || (Array.isArray(schema.examples) && schema.examples.length > 0))
+        if (schema.example !== undefined || (Array.isArray(schema.examples) && schema.examples.length > 0)) {
             return 1;
+        }
         let total = 1;
         const add = (child) => {
-            if (total <= limit)
+            if (total <= limit) {
                 total += count(child, level + 1);
+            }
         };
-        if (isObject(schema.properties))
+        if (isObject(schema.properties)) {
             Object.values(schema.properties).forEach(add);
-        if (isObject(schema.patternProperties))
+        }
+        if (isObject(schema.patternProperties)) {
             Object.values(schema.patternProperties).forEach(add);
-        if (isObject(schema.additionalProperties))
+        }
+        if (isObject(schema.additionalProperties)) {
             add(schema.additionalProperties);
-        if (schema.items !== undefined)
+        }
+        if (schema.items !== undefined) {
             add(schema.items);
-        if (Array.isArray(schema.prefixItems))
+        }
+        if (Array.isArray(schema.prefixItems)) {
             schema.prefixItems.forEach(add);
-        if (Array.isArray(schema.allOf))
+        }
+        if (Array.isArray(schema.allOf)) {
             schema.allOf.forEach(add);
-        const variants = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : [];
+        }
+        const anyOf = Array.isArray(schema.anyOf) ? schema.anyOf : [];
+        const variants = Array.isArray(schema.oneOf) ? schema.oneOf : anyOf;
         // Object and array generation can use the first variant, while other unions skip null.
         // A discriminator can choose any variant, so bound the largest candidate in that case.
         const nonNull = variants.find((variant) => {
@@ -57,8 +69,9 @@ export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_
             : [variants[0], nonNull];
         let variantCount = 0;
         for (const candidate of candidates) {
-            if (candidate !== undefined && total <= limit && variantCount <= limit)
+            if (candidate !== undefined && total <= limit && variantCount <= limit) {
                 variantCount = Math.max(variantCount, count(candidate, level + 1));
+            }
         }
         total += variantCount;
         const levels = counts.get(input) ?? new Map();
@@ -72,40 +85,51 @@ export const countGeneratedExampleValues = (root, limit = MAX_GENERATED_EXAMPLE_
 export const getMarkdownExamples = (source, mediaType, mode, openapiVersion = '3.2.0', 
 // Schema metadata can be upgraded while example fields still follow the original version.
 schemaOpenapiVersion = openapiVersion, linked = false) => {
-    if (source.example !== undefined)
+    if (source.example !== undefined) {
         return [{ value: source.example }];
+    }
     if (source.examples && Object.keys(source.examples).length) {
         return Object.entries(source.examples).flatMap(([name, reference]) => {
             const example = getResolvedRef(reference);
-            if (!isObject(example))
+            if (!isObject(example)) {
                 return [];
+            }
             const metadata = {
                 name,
                 summary: typeof example.summary === 'string' ? example.summary : undefined,
                 description: typeof example.description === 'string' ? example.description : undefined,
             };
-            if (example.value !== undefined)
+            if (example.value !== undefined) {
                 return [{ ...metadata, value: example.value }];
-            if (/^3\.2\./.test(openapiVersion) && typeof example.serializedValue === 'string')
+            }
+            if (/^3\.2\./.test(openapiVersion) && typeof example.serializedValue === 'string') {
                 return [{ ...metadata, serializedValue: example.serializedValue }];
-            if (typeof example.externalValue === 'string')
+            }
+            if (typeof example.externalValue === 'string') {
                 return [{ ...metadata, externalValue: example.externalValue }];
-            if (/^3\.2\./.test(openapiVersion) && example.dataValue !== undefined)
+            }
+            if (/^3\.2\./.test(openapiVersion) && example.dataValue !== undefined) {
                 return [{ ...metadata, dataValue: example.dataValue }];
+            }
             return [];
         });
     }
     const schema = getResolvedRef(source.schema, mergeSiblingReferences);
-    if (!isObject(schema))
+    if (!isObject(schema)) {
         return [];
-    if (schema.example !== undefined)
+    }
+    if (schema.example !== undefined) {
         return [{ value: schema.example }];
-    if (Array.isArray(schema.examples) && schema.examples.length)
+    }
+    if (Array.isArray(schema.examples) && schema.examples.length) {
         return schema.examples.map((value) => ({ value }));
-    if (linked)
+    }
+    if (linked) {
         return [];
-    if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES)
+    }
+    if (countGeneratedExampleValues(source.schema) > MAX_GENERATED_EXAMPLE_VALUES) {
         return [{ omitted: true }];
+    }
     if (isXmlMediaType(mediaType)) {
         const result = getXmlBodyExample(source.schema, undefined, {
             mode,

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

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

package/dist/load-document.js

@@ -40,8 +40,9 @@ const attachRefValues = (document, schemas = getSchemas(document), { detectOnly
             kind = kind && getChildKind(kind, key);
             position = Array.isArray(parent) ? position : position && getChildPosition(position, key);
             // Arbitrary extension and example data has not passed an OpenAPI object schema.
-            if (position === 'document' && kind === undefined)
+            if (position === 'document' && kind === undefined) {
                 position = undefined;
+            }
             parent = getValueByPath(parent, [key]).value;
         }
         const schema = getTargetSchema(position, kind);
@@ -78,15 +79,20 @@ const attachRefValues = (document, schemas = getSchemas(document), { detectOnly
             // support summary and description; casting them as their targets would add defaults.
             // Path Item Objects declare their own $ref field, so their siblings are cast normally.
             const reference = typeof value.$ref === 'string' ? value.$ref : undefined;
-            const cast = reference === undefined || schema === referenceTargetSchemas.pathItem
-                ? coerceValue(schema, value)
-                : position === 'schema'
-                    ? { ...coerceValue(SchemaObjectSchema, value), $ref: reference }
-                    : {
-                        $ref: reference,
-                        ...(typeof value.summary === 'string' ? { summary: value.summary } : {}),
-                        ...(typeof value.description === 'string' ? { description: value.description } : {}),
-                    };
+            let cast;
+            if (reference === undefined || schema === referenceTargetSchemas.pathItem) {
+                cast = coerceValue(schema, value);
+            }
+            else if (position === 'schema') {
+                cast = { ...coerceValue(SchemaObjectSchema, value), $ref: reference };
+            }
+            else {
+                cast = {
+                    $ref: reference,
+                    ...(typeof value.summary === 'string' ? { summary: value.summary } : {}),
+                    ...(typeof value.description === 'string' ? { description: value.description } : {}),
+                };
+            }
             if (fallback?.booleanSchemas) {
                 restoreBooleanSchemas(value, cast, position);
             }

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

@@ -1 +1 @@
-{"version":3,"file":"parse-description.d.ts","sourceRoot":"","sources":["../src/parse-description.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,WAAW,EAAE,MAAM,OAAO,CAAA;AAkF7D,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,CA4ClE,CAAA;AAED,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,GAAU,OAAO,WAAW,EAAE,EAAE,aAAa,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAe3G,CAAA"}
+{"version":3,"file":"parse-description.d.ts","sourceRoot":"","sources":["../src/parse-description.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuB,WAAW,EAAE,MAAM,OAAO,CAAA;AAsG7D,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,CAuDlE,CAAA;AAED,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,GAAU,OAAO,WAAW,EAAE,EAAE,aAAa,iBAAiB,KAAG,OAAO,CAAC,IAAI,CAkB3G,CAAA"}

package/dist/parse-description.js

@@ -10,8 +10,9 @@ const clean = (node) => {
         node.url = safeUrl(node.url);
     }
     if ('children' in node) {
-        for (const child of node.children)
+        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' &&
@@ -33,10 +34,12 @@ const clean = (node) => {
         if (node.children.length !== previousLength) {
             const first = node.children.at(0);
             const last = node.children.at(-1);
-            if (first?.type === 'text')
+            if (first?.type === 'text') {
                 first.value = first.value.trimStart();
-            if (last?.type === 'text')
+            }
+            if (last?.type === 'text') {
                 last.value = last.value.trimEnd();
+            }
         }
     }
     delete node.position;
@@ -47,24 +50,31 @@ const pruneDefinitions = (tree) => {
     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')
+        if (node.type === 'linkReference') {
             links.add(node.identifier);
-        if (node.type === 'footnoteReference')
+        }
+        if (node.type === 'footnoteReference') {
             footnotes.add(node.identifier);
-        if ('children' in node)
+        }
+        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)
+    for (const identifier of footnotes) {
         definitions.get(identifier)?.children.forEach(collect);
+    }
     tree.children = tree.children.filter((node) => {
-        if (node.type === 'definition')
+        if (node.type === 'definition') {
             return links.has(node.identifier);
-        if (node.type === 'footnoteDefinition')
+        }
+        if (node.type === 'footnoteDefinition') {
             return footnotes.has(node.identifier);
-        if (node.type === 'paragraph')
+        }
+        if (node.type === 'paragraph') {
             return node.children.some((child) => child.type !== 'text' || child.value.trim());
+        }
         return true;
     });
 };
@@ -78,8 +88,9 @@ export const createDescriptionParser = () => {
     const cache = new Map();
     const parse = async (value) => {
         // Most schema descriptions are one plain sentence. Parsing them costs more than the page's other text.
-        if (isPlainText(value))
+        if (isPlainText(value)) {
             return [{ type: 'paragraph', children: [{ type: 'text', value: value.trim() }] }];
+        }
         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)
@@ -93,26 +104,31 @@ export const createDescriptionParser = () => {
         const copy = { ...node };
         if ('identifier' in copy) {
             copy.identifier = `${prefix}${copy.identifier}`;
-            if ('label' in copy)
+            if ('label' in copy) {
                 copy.label = copy.identifier;
-            if ('referenceType' in copy)
+            }
+            if ('referenceType' in copy) {
                 copy.referenceType = 'full';
+            }
         }
-        if ('children' in copy)
+        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)
+            if (!value) {
                 return [];
+            }
             const prefix = `description-${state.nextId++}-`;
             const cached = cache.get(value) ?? parse(value);
             if (!cache.has(value)) {
-                if (cache.size >= 8192)
+                if (cache.size >= 8192) {
                     cache.clear();
+                }
                 cache.set(value, cached);
             }
             const nodes = await cached;
@@ -127,10 +143,12 @@ export const expandDescriptions = async (nodes, description) => {
     const found = [];
     const collect = (siblings) => {
         for (const node of siblings) {
-            if (node.type === 'descriptionPlaceholder')
+            if (node.type === 'descriptionPlaceholder') {
                 found.push({ siblings, node });
-            else if ('children' in node)
+            }
+            else if ('children' in node) {
                 collect(node.children);
+            }
         }
     };
     collect(nodes);

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

@@ -1 +1 @@
-{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,8DAA8D,CAAA;AAcrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AA+C7D,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,MAAM,CAAC,CAsPnB,CAAA"}
+{"version":3,"file":"render-document.d.ts","sourceRoot":"","sources":["../src/render-document.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,8DAA8D,CAAA;AAcrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAwD7D,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,QAAO,CAAC,CACzC,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,oBAAoB,KAC3B,OAAO,CAAC,MAAM,CAAC,CA0RnB,CAAA"}

package/dist/render-document.js

@@ -18,14 +18,17 @@ const serializer = unified()
     bullet: '-',
     join: [
         (left, right, parent) => {
-            if (!('spread' in parent))
+            if (!('spread' in parent)) {
                 return undefined;
+            }
             // Inside a tight list item, content after a nested list would otherwise continue its last item.
-            if (left.type === 'list' && right.type !== 'list')
+            if (left.type === 'list' && right.type !== 'list') {
                 return 1;
+            }
             // Code blocks in descriptions read better apart from the prose around them.
-            if (left.type === 'code' || right.type === 'code')
+            if (left.type === 'code' || right.type === 'code') {
                 return 1;
+            }
             return undefined;
         },
     ],
@@ -43,12 +46,14 @@ const renderShownModel = async (name, view, previous, description) => {
         ? [strong(text(view.title)), text(' ('), inlineCode(name), text(')')]
         : [inlineCode(name)];
     label.push(text(' — shown above'));
-    if (previous.name !== name)
+    if (previous.name !== name) {
         label.push(text(' as '), inlineCode(previous.name));
+    }
     label.push(text('.'));
     const blocks = [paragraph(...label)];
-    if (view.description && view.description !== previous.description)
+    if (view.description && view.description !== previous.description) {
         blocks.push(...(await description(view.description)));
+    }
     return item(...blocks);
 };
 /** Build Markdown directly, retaining caches only for this immutable document snapshot. */
@@ -81,8 +86,9 @@ export const createDocumentRenderer = () => {
             const entries = [];
             for (const [path, reference] of Object.entries(group.paths ?? {})) {
                 const pathItem = getResolvedPathItem(reference);
-                if (!pathItem)
+                if (!pathItem) {
                     continue;
+                }
                 forEachPathItemOperation(reference, (method, operation) => {
                     const label = `${formatOperationMethod(method)} ${path}`;
                     entries.push({
@@ -107,8 +113,9 @@ export const createDocumentRenderer = () => {
         const nodes = [];
         const sections = [];
         const flush = async () => {
-            if (!nodes.length)
+            if (!nodes.length) {
                 return;
+            }
             const children = nodes.splice(0);
             await expandDescriptions(children, description);
             sections.push(serializer.stringify({ type: 'root', children }).trimEnd());
@@ -116,62 +123,74 @@ export const createDocumentRenderer = () => {
         if (!single) {
             const { info } = document;
             const metadata = [field('OpenAPI Version', inlineCode(document.openapi))];
-            if (info.version)
+            if (info.version) {
                 metadata.push(field('API Version', inlineCode(info.version)));
-            if (info.termsOfService)
+            }
+            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)
+            if (info.license) {
                 metadata.push(field('License', info.license.url ? link(info.license.url, info.license.name ?? '') : text(info.license.name)));
+            }
             nodes.push(heading(1, text(info.title)), list(metadata), ...(await description(info.description)));
             if (whole) {
                 const contents = [];
                 for (const group of groups) {
-                    if (!group.entries.length)
+                    if (!group.entries.length) {
                         continue;
+                    }
                     contents.push(paragraph(strong(text(group.title))), list(group.entries.map(({ id, label }) => item(paragraph(link(`#${encodeURIComponent(id)}`, label))))));
                 }
                 if (destinations?.size) {
                     contents.push(paragraph(strong(text('Schemas'))), list([...destinations].map(([name, url]) => item(paragraph(link(url, name))))));
                 }
-                if (contents.length)
+                if (contents.length) {
                     nodes.push(heading(2, text('Contents')), ...contents);
+                }
             }
             if (document.servers?.length || (whole && document.servers !== undefined)) {
-                if (documentContext?.servers)
+                if (documentContext?.servers) {
                     nodes.push(anchor(documentContext.servers));
+                }
                 nodes.push(heading(2, text('Servers')));
                 const effectiveServers = document.servers?.length
                     ? document.servers
                     : [{ url: '/' }];
                 const servers = effectiveServers.map((server) => {
                     const nested = [];
-                    if (server.description)
+                    if (server.description) {
                         nested.push(field('Description', text(server.description)));
+                    }
                     const variables = Object.entries(server.variables ?? {});
-                    if (variables.length)
+                    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(')'), ...(whole && variable.enum?.length
                             ? [text(', possible values: '), inlineCode(variable.enum.join(', '))]
                             : []), text(variable.description ? `: ${variable.description}` : '')))))));
+                    }
                     const entry = field('URL', inlineCode(server.url));
-                    if (nested.length)
+                    if (nested.length) {
                         entry.children.push(list(nested));
+                    }
                     return entry;
                 });
                 nodes.push(list(servers));
             }
-            if (documentContext?.authentication)
+            if (documentContext?.authentication) {
                 nodes.push(anchor(documentContext.authentication));
+            }
             nodes.push(...(await renderSecurity(document.security, document.components?.securitySchemes, description, 2)));
             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)
+                    const title = /^3\.2\./.test(openapiVersion) ? (tag.summary ?? tag.name) : tag.name;
+                    nodes.push(heading(3, text(title)), ...(await description(tag.description)));
+                    if (tag.externalDocs) {
                         nodes.push(paragraph(link(tag.externalDocs.url, tag.externalDocs.description ?? tag.externalDocs.url)));
+                    }
                 }
             }
             await flush();
@@ -179,12 +198,14 @@ export const createDocumentRenderer = () => {
         for (const group of groups) {
             let hasOperations = false;
             for (const { path, pathItem, method, operation, id } of group.entries) {
-                if (!hasOperations && !single)
+                if (!hasOperations && !single) {
                     nodes.push(heading(2, text(group.title)));
+                }
                 hasOperations = true;
                 schemas.beginSection();
-                if (id)
+                if (id) {
                     nodes.push(anchor(id));
+                }
                 nodes.push(...(await renderOperation(document, path, method, pathItem, operation, group.webhook, {
                     description,
                     schemas,
@@ -200,11 +221,13 @@ export const createDocumentRenderer = () => {
         const renderModel = async (name, schema, level) => {
             const view = schemas.view(schema);
             const summary = schemas.summarize(schema);
-            if (whole)
+            if (whole) {
                 nodes.push(anchor(anchors.get('schema', name)));
+            }
             nodes.push(heading(level, text(view.title ?? name)));
-            if (summary.length)
+            if (summary.length) {
                 nodes.push(paragraph(strong(text('Type:')), text('\u00a0'), ...summary));
+            }
             nodes.push(...(await description(view.description)), ...schemas.render(schema, 0, [], { hideDetails: true, name }));
             if (view.type === 'object' || hasAuthoredExamples(view)) {
                 // A model page's own schema is bounded, so it gets a generated example even in linked mode.
@@ -223,13 +246,15 @@ export const createDocumentRenderer = () => {
             await renderModel(selected[0], selected[1], 1);
         }
         const dependencies = models.filter(([name]) => name !== options.model);
-        if (dependencies.length)
+        if (dependencies.length) {
             nodes.push(heading(2, text('Schemas')));
+        }
         // Models the page already expanded cost one line each, grouped into a single list.
         const shownAbove = [];
         const flushShownAbove = () => {
-            if (shownAbove.length)
+            if (shownAbove.length) {
                 nodes.push(list(shownAbove.splice(0)));
+            }
         };
         for (const [name, schema] of dependencies) {
             schemas.beginSection();

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

@@ -1 +1 @@
-{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAQ,WAAW,EAAE,MAAM,OAAO,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,EACrC,+BAIG;IACD,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,oFAAoF;IACpF,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACvB,KACL,OAAO,CAAC,WAAW,EAAE,CA8EvB,CAAA"}
+{"version":3,"file":"render-examples.d.ts","sourceRoot":"","sources":["../src/render-examples.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAQ,WAAW,EAAE,MAAM,OAAO,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,yBAAyB,CAAA;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,+EAA+E;AAC/E,eAAO,MAAM,cAAc,GACzB,QAAQ,aAAa,EACrB,aAAa,iBAAiB,EAC9B,kBAA8B,EAC9B,OAAO,MAAM,GAAG,OAAO,EACvB,uBAAwB,EAExB,6BAAqC,EACrC,+BAIG;IACD,yFAAyF;IACzF,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,oFAAoF;IACpF,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACvB,KACL,OAAO,CAAC,WAAW,EAAE,CAgFvB,CAAA"}