@umami/shiso 1.11.0 → 1.13.0

package/scripts/expand-openapi-navigation.mjs

@@ -0,0 +1,94 @@
+/** Expands { openapi } navigation entries into ordinary { page } entries. */
+
+const OPENAPI_KEYS = new Set(['openapi']);
+
+function isOpenApiItem(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && 'openapi' in value;
+}
+
+function assertOpenApiItem(item) {
+  const unknown = Object.keys(item).filter(key => !OPENAPI_KEYS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `Invalid navigation openapi entry: unknown ${unknown.length === 1 ? 'key' : 'keys'} ${unknown.map(key => `"${key}"`).join(', ')}.`,
+    );
+  }
+  if (item.openapi !== true && (typeof item.openapi !== 'string' || !item.openapi.trim())) {
+    throw new Error('Invalid navigation openapi entry: use true or a non-empty tag name.');
+  }
+}
+
+/** True when a navigation tree contains at least one { openapi } page entry. */
+export function hasOpenApiItems(navigation) {
+  if (Array.isArray(navigation)) return navigation.some(hasOpenApiItems);
+  if (!navigation || typeof navigation !== 'object') return false;
+  if (isOpenApiItem(navigation)) return true;
+  return Object.values(navigation).some(hasOpenApiItems);
+}
+
+function pageEntry(operation, directory) {
+  return {
+    page: `${directory}/${operation.id}`,
+    title: operation.summary || `${operation.method} ${operation.path}`,
+    method: operation.method,
+  };
+}
+
+function sortOperations(operations) {
+  return [...operations].sort(
+    (left, right) => left.path.localeCompare(right.path) || left.method.localeCompare(right.method),
+  );
+}
+
+function expandItem(item, { operations, directory }) {
+  assertOpenApiItem(item);
+
+  if (item.openapi === true) {
+    const tags = [];
+    for (const operation of operations) {
+      for (const tag of operation.tags) {
+        if (!tags.includes(tag)) tags.push(tag);
+      }
+    }
+    return tags.map(tag => ({
+      group: tag,
+      pages: sortOperations(operations.filter(operation => operation.tags.includes(tag))).map(
+        operation => pageEntry(operation, directory),
+      ),
+    }));
+  }
+
+  const tag = item.openapi.trim();
+  const matched = sortOperations(operations.filter(operation => operation.tags.includes(tag)));
+  if (!matched.length) {
+    throw new Error(`Navigation openapi entry "${tag}" matched no operations in the API spec.`);
+  }
+  return matched.map(operation => pageEntry(operation, directory));
+}
+
+/** Returns a config copy whose { openapi } entries are ordinary page objects. */
+export function expandOpenApiNavigation(config, { operations, directory }) {
+  function expandObject(value) {
+    if (Array.isArray(value)) return value.map(expandObject);
+    if (!value || typeof value !== 'object') return value;
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, child]) => {
+        if (key === 'pages' && Array.isArray(child)) {
+          const expanded = [];
+          for (const item of child) {
+            if (isOpenApiItem(item)) {
+              expanded.push(...expandItem(item, { operations, directory }));
+            } else {
+              expanded.push(expandObject(item));
+            }
+          }
+          return [key, expanded];
+        }
+        return [key, expandObject(child)];
+      }),
+    );
+  }
+
+  return { ...config, navigation: expandObject(config.navigation) };
+}

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 });
+        }
+      }
     }
   }