@umami/shiso 1.10.0 → 1.12.0

package/scripts/generate-openapi.mjs

@@ -0,0 +1,117 @@
+/**
+ * Emits .shiso/openapi.generated.ts: every normalized operation from the
+ * project's OpenAPI spec, with code samples and response examples highlighted
+ * by Shiki at build time so no highlighter ships to the browser.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHighlighter, hastToHtml } from 'shiki';
+import { loadOpenApiSpec, normalizeOperations } from './lib/openapi.mjs';
+
+// Keep in sync with DEFAULT_CODE_THEME in src/lib/code-blocks.ts (asserted by
+// tests/openapi.test.mjs).
+export const DEFAULT_OPENAPI_THEME = { light: 'github-light', dark: 'github-dark' };
+
+const EMPTY_MODULE = `// Generated by @umami/shiso. Do not edit by hand.
+import type { NormalizedOperation } from '@/lib/types';
+
+export const OPENAPI_OPERATIONS: Record<string, NormalizedOperation> = {};
+`;
+
+let highlighterPromise;
+
+async function getHighlighter(theme) {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({ themes: [theme.light, theme.dark], langs: [] });
+  }
+  return highlighterPromise;
+}
+
+async function highlight(highlighter, source, lang, theme) {
+  if (!highlighter.getLoadedLanguages().includes(lang)) {
+    await highlighter.loadLanguage(lang);
+  }
+
+  const hast = highlighter.codeToHast(source, {
+    lang,
+    themes: theme,
+    defaultColor: false,
+  });
+  const code = hast.children[0]?.children?.[0];
+  const children = code?.children || [];
+  const lineCount = children.filter(node => node.tagName === 'span').length;
+
+  return { html: hastToHtml({ type: 'root', children }), lineCount };
+}
+
+async function highlightOperation(operation, highlighter, theme) {
+  const samples = [];
+  for (const sample of operation.samples) {
+    samples.push({
+      ...sample,
+      ...(await highlight(highlighter, sample.source, sample.language, theme)),
+    });
+  }
+
+  const responses = [];
+  for (const response of operation.responses) {
+    responses.push(
+      response.example
+        ? {
+            ...response,
+            exampleHtml: (await highlight(highlighter, response.example, 'json', theme)).html,
+          }
+        : response,
+    );
+  }
+
+  const requestBody =
+    operation.requestBody?.example !== undefined
+      ? {
+          ...operation.requestBody,
+          exampleHtml: (await highlight(highlighter, operation.requestBody.example, 'json', theme))
+            .html,
+        }
+      : operation.requestBody;
+
+  return { ...operation, samples, responses, requestBody };
+}
+
+async function writeIfChanged(output, contents) {
+  const existing = await fs.readFile(output, 'utf8').catch(() => undefined);
+  if (existing === contents) return;
+  await fs.mkdir(path.dirname(output), { recursive: true });
+  await fs.writeFile(output, contents);
+}
+
+/** Generates the openapi data module for the project, or an empty fallback. */
+export async function generateOpenApiModule({
+  root,
+  config,
+  theme = DEFAULT_OPENAPI_THEME,
+  output,
+}) {
+  if (!config?.api?.spec) {
+    await writeIfChanged(output, EMPTY_MODULE);
+    return { operations: 0 };
+  }
+
+  const { spec } = await loadOpenApiSpec({ root, specPath: config.api.spec });
+  const operations = normalizeOperations(spec);
+  const highlighter = await getHighlighter(theme);
+  const record = {};
+
+  for (const operation of operations) {
+    record[operation.key] = await highlightOperation(operation, highlighter, theme);
+  }
+
+  const contents = `// Generated by @umami/shiso. Do not edit by hand.
+import type { NormalizedOperation } from '@/lib/types';
+
+export const OPENAPI_OPERATIONS: Record<string, NormalizedOperation> = ${JSON.stringify(record, null, 2)};
+`;
+
+  await writeIfChanged(output, contents);
+  return { operations: operations.length };
+}

package/scripts/generate-search-index.mjs

@@ -22,6 +22,12 @@ import remarkMdx from 'remark-mdx';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
 import { headingText } from './lib/mdast.mjs';
+import {
+  loadOpenApiSpec,
+  normalizeOperationKey,
+  normalizeOperations,
+  operationSearchSections,
+} from './lib/openapi.mjs';
 import { createSlugger, slugifyId } from './lib/slug.mjs';
 import { loadDocsConfig } from './load-docs-config.mjs';
 import { loadShisoConfig } from './load-shiso-config.mjs';
@@ -141,7 +147,13 @@ function collectVisiblePages(container, pages = [], hidden = false) {
   return pages;
 }
 
-/** Frontmatter is YAML, but search only needs the title line. */
+/** Frontmatter is YAML, but search only needs single lines from it. */
+function frontmatterOpenApi(tree) {
+  const yaml = tree.children?.find(node => node.type === 'yaml');
+  const match = yaml?.value?.match(/^openapi:\s*(.+)$/m);
+  return match ? match[1].trim() : undefined;
+}
+
 function frontmatterTitle(tree) {
   const yaml = tree.children?.find(node => node.type === 'yaml');
   const match = yaml?.value?.match(/^title:\s*(.+)$/m);
@@ -211,6 +223,16 @@ export async function generateSearchIndex({
   const seen = new Set();
   const records = [];
 
+  // Pages bound to an API operation get synthesized sections from the spec, so
+  // parameters and responses are searchable even though they render from data.
+  let operationsByKey;
+  if (docsJson.api?.spec) {
+    const { spec } = await loadOpenApiSpec({ root, specPath: docsJson.api.spec });
+    operationsByKey = new Map(
+      normalizeOperations(spec).map(operation => [operation.key, operation]),
+    );
+  }
+
   for (const scope of collectScopes(docsJson.navigation || {})) {
     // Single-scope sites omit scope fields so their index stays unchanged.
     const scopeFields =
@@ -249,6 +271,14 @@ export async function generateSearchIndex({
       for (const { heading, id, text } of collectSections(tree)) {
         records.push({ url, page, heading, id, text, ...scopeFields });
       }
+
+      const operationKey = normalizeOperationKey(frontmatterOpenApi(tree));
+      const operation = operationKey ? operationsByKey?.get(operationKey) : undefined;
+      if (operation) {
+        for (const { heading, id, text } of operationSearchSections(operation)) {
+          records.push({ url, page, heading, id, text, ...scopeFields });
+        }
+      }
     }
   }