@umami/shiso 1.11.0 → 1.12.0

package/scripts/expand-navigation-globs.mjs

@@ -0,0 +1,208 @@
+/** Expands { glob } navigation entries into ordinary { page } entries. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+const CONTENT_EXTENSIONS = new Set(['.md', '.mdx']);
+const GLOB_KEYS = new Set(['glob', 'exclude']);
+
+async function listContentFiles(directory) {
+  const files = [];
+  let entries;
+
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT') return files;
+    throw error;
+  }
+
+  for (const entry of entries) {
+    const item = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listContentFiles(item)));
+    } else if (entry.isFile() && CONTENT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+      files.push(item);
+    }
+  }
+
+  return files;
+}
+
+function globPattern(value) {
+  const pattern = String(value || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/\/+$/, '');
+
+  if (!pattern || pattern.startsWith('/') || pattern.split('/').includes('..')) {
+    throw new Error(`Invalid navigation glob "${value}": use a relative path inside contentDir.`);
+  }
+
+  return pattern;
+}
+
+function globRegex(pattern) {
+  let source = '^';
+
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+
+    if (character === '*' && pattern[index + 1] === '*') {
+      if (pattern[index + 2] === '/') {
+        source += '(?:.*/)?';
+        index += 2;
+      } else {
+        source += '.*';
+        index += 1;
+      }
+    } else if (character === '*') {
+      source += '[^/]*';
+    } else if (character === '?') {
+      source += '[^/]';
+    } else {
+      source += character.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+    }
+  }
+
+  return new RegExp(`${source}$`);
+}
+
+function navigationFrontmatter(source, sourcePath) {
+  const block = source.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] || '';
+  if (!block) return {};
+
+  try {
+    const values = parseYaml(block);
+    return values && typeof values === 'object' && !Array.isArray(values) ? values : {};
+  } catch (error) {
+    throw new Error(`Could not parse frontmatter in "${sourcePath}": ${error.message}`);
+  }
+}
+
+function isGlobItem(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && 'glob' in value;
+}
+
+function assertGlobItem(item) {
+  if (typeof item.glob !== 'string' || !item.glob.trim()) {
+    throw new Error('Invalid navigation glob: "glob" must be a non-empty string.');
+  }
+  const unknown = Object.keys(item).filter(key => !GLOB_KEYS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `Invalid navigation glob "${item.glob}": unknown ${unknown.length === 1 ? 'key' : 'keys'} ${unknown.map(key => `"${key}"`).join(', ')}.`,
+    );
+  }
+  if (item.exclude !== undefined && !Array.isArray(item.exclude)) {
+    throw new Error(`Invalid navigation glob "${item.glob}": "exclude" must be an array.`);
+  }
+  if (item.exclude?.some(pattern => typeof pattern !== 'string' || !pattern.trim())) {
+    throw new Error(
+      `Invalid navigation glob "${item.glob}": every "exclude" entry must be a non-empty string.`,
+    );
+  }
+}
+
+function pageCandidate(contentRoot, filePath) {
+  const relativeFile = path.relative(contentRoot, filePath).replace(/\\/g, '/');
+  const fileSlug = relativeFile.replace(/\.mdx?$/i, '');
+  return { filePath, relativeFile, fileSlug };
+}
+
+function matches(candidate, pattern) {
+  const target = /\.mdx?$/i.test(pattern) ? candidate.relativeFile : candidate.fileSlug;
+  return globRegex(pattern).test(target);
+}
+
+async function expandGlob(item, candidates, projectRoot) {
+  assertGlobItem(item);
+  const pattern = globPattern(item.glob);
+  const exclusions = (item.exclude || []).map(globPattern);
+  const matched = candidates.filter(
+    candidate =>
+      matches(candidate, pattern) && !exclusions.some(exclusion => matches(candidate, exclusion)),
+  );
+
+  if (!matched.length) {
+    throw new Error(`Navigation glob "${pattern}" matched no Markdown or MDX files.`);
+  }
+
+  const entries = await Promise.all(
+    matched.map(async candidate => {
+      const source = await fs.readFile(candidate.filePath, 'utf8');
+      const sourcePath = path.relative(projectRoot, candidate.filePath).replace(/\\/g, '/');
+      const frontmatter = navigationFrontmatter(source, sourcePath);
+      const title =
+        typeof frontmatter.sidebarTitle === 'string' && frontmatter.sidebarTitle
+          ? frontmatter.sidebarTitle
+          : typeof frontmatter.title === 'string' && frontmatter.title
+            ? frontmatter.title
+            : undefined;
+
+      return {
+        page: candidate.fileSlug,
+        ...(title ? { title } : {}),
+        ...(frontmatter.hidden === true ? { hidden: true } : {}),
+        order: typeof frontmatter.order === 'number' ? frontmatter.order : Number.POSITIVE_INFINITY,
+      };
+    }),
+  );
+
+  entries.sort((left, right) => left.order - right.order || left.page.localeCompare(right.page));
+  return entries.map(({ order: _order, ...entry }) => entry);
+}
+
+/** True when a navigation tree contains at least one { glob } page entry. */
+export function hasNavigationGlobs(navigation) {
+  if (Array.isArray(navigation)) return navigation.some(hasNavigationGlobs);
+  if (!navigation || typeof navigation !== 'object') return false;
+  if (isGlobItem(navigation)) return true;
+  return Object.values(navigation).some(hasNavigationGlobs);
+}
+
+/** Returns a config copy whose navigation globs are ordinary page objects. */
+export async function expandNavigationGlobs(config, { root, contentDir }) {
+  if (!hasNavigationGlobs(config.navigation)) return config;
+
+  const projectRoot = path.resolve(root);
+  const contentRoot = path.resolve(projectRoot, contentDir);
+  const files = await listContentFiles(contentRoot);
+  const candidates = files.map(filePath => pageCandidate(contentRoot, filePath));
+  const duplicateSlugs = candidates.filter(
+    (candidate, index) =>
+      candidates.findIndex(item => item.fileSlug === candidate.fileSlug) !== index,
+  );
+
+  if (duplicateSlugs.length) {
+    throw new Error(
+      `Navigation globs found both .md and .mdx for "${duplicateSlugs[0].fileSlug}" in ${contentDir}.`,
+    );
+  }
+
+  async function expandObject(value) {
+    if (Array.isArray(value)) return Promise.all(value.map(expandObject));
+    if (!value || typeof value !== 'object') return value;
+
+    const entries = await Promise.all(
+      Object.entries(value).map(async ([key, child]) => {
+        if (key === 'pages' && Array.isArray(child)) {
+          const expanded = [];
+          for (const item of child) {
+            if (isGlobItem(item)) {
+              expanded.push(...(await expandGlob(item, candidates, projectRoot)));
+            } else {
+              expanded.push(await expandObject(item));
+            }
+          }
+          return [key, expanded];
+        }
+        return [key, await expandObject(child)];
+      }),
+    );
+    return Object.fromEntries(entries);
+  }
+
+  return { ...config, navigation: await expandObject(config.navigation) };
+}

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