@umami/shiso 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umami/shiso",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {
@@ -38,7 +38,6 @@
     "docs.schema.json",
     "mdx.config.ts",
     "vite.config.ts",
-    "CHANGELOG.md",
     "README.md"
   ],
   "scripts": {

package/scripts/check-content.mjs

@@ -13,12 +13,14 @@ import remarkMdx from 'remark-mdx';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
 import { headingText } from './lib/mdast.mjs';
+import { hasPlayground, operationAnchors, schemaAnchors } from './lib/openapi.mjs';
 import {
-  loadOpenApiSpec,
-  normalizeOperationKey,
-  normalizeOperations,
-  operationAnchors,
-} from './lib/openapi.mjs';
+  isAmbiguousOperation,
+  isAmbiguousSchema,
+  loadApiProject,
+  lookupOperation,
+  lookupSchema,
+} from './lib/openapi-project.mjs';
 import { createSlugger } from './lib/slug.mjs';
 import { loadDocsConfig } from './load-docs-config.mjs';
 import { loadShisoConfig } from './load-shiso-config.mjs';
@@ -157,7 +159,18 @@ function inspectMarkdown(source, filePath) {
     targets,
     title: /^title\s*:/m.test(frontmatter),
     description: /^description\s*:/m.test(frontmatter),
-    openapi: frontmatter.match(/^openapi:\s*(.+)$/m)?.[1]?.trim(),
+    openapi: frontmatter
+      .match(/^openapi:\s*(.+)$/m)?.[1]
+      ?.trim()
+      .replace(/^["']|["']$/g, ''),
+    openapiSchema: frontmatter
+      .match(/^openapi-schema:\s*(.+)$/m)?.[1]
+      ?.trim()
+      .replace(/^["']|["']$/g, ''),
+    playground: frontmatter
+      .match(/^playground:\s*(.+)$/m)?.[1]
+      ?.trim()
+      .replace(/^["']|["']$/g, ''),
   };
 }
 
@@ -256,25 +269,39 @@ export async function checkContent({ root = process.cwd(), config, shiso } = {})
 
   // Generated OpenAPI sections render at runtime, so their anchors come from
   // the spec rather than from markdown headings.
-  let openApiByKey;
-  if (docsConfig.api?.spec) {
-    const { spec } = await loadOpenApiSpec({ root: projectRoot, specPath: docsConfig.api.spec });
-    openApiByKey = new Map(normalizeOperations(spec).map(operation => [operation.key, operation]));
-  }
+  const project = docsConfig.api?.spec
+    ? await loadApiProject({ root: projectRoot, api: docsConfig.api })
+    : undefined;
 
   const documents = new Map();
   for (const page of pages) {
     const source = await fs.readFile(page.filePath, 'utf8');
     const document = inspectMarkdown(source, page.filePath);
-    const operationKey = normalizeOperationKey(document.openapi);
-    const operation = operationKey ? openApiByKey?.get(operationKey) : undefined;
+    const relative = path.relative(projectRoot, page.filePath).replace(/\\/g, '/');
+    const operation = project ? lookupOperation(project, document.openapi) : undefined;
+    const schema = project ? lookupSchema(project, document.openapiSchema) : undefined;
     if (operation) {
-      for (const anchor of operationAnchors(operation)) {
+      const playground = !operation.webhook && hasPlayground(docsConfig.api, document.playground);
+      for (const anchor of operationAnchors(operation, { playground })) {
         document.anchors.add(anchor);
       }
+    } else if (document.openapi) {
+      errors.push(
+        project && isAmbiguousOperation(project, document.openapi)
+          ? `${relative} binds "openapi: ${document.openapi}", which several specs define; prefix it with the spec, e.g. "openapi: ${project.specs[0].id} ${document.openapi}".`
+          : `${relative} binds "openapi: ${document.openapi}", which matches no operation in ${project ? 'the API spec' : 'an API spec (docs.json has no api.spec)'}.`,
+      );
+    }
+    if (schema) {
+      for (const anchor of schemaAnchors(schema)) document.anchors.add(anchor);
+    } else if (document.openapiSchema) {
+      errors.push(
+        project && isAmbiguousSchema(project, document.openapiSchema)
+          ? `${relative} binds "openapi-schema: ${document.openapiSchema}", which several specs define; prefix it with the spec.`
+          : `${relative} binds "openapi-schema: ${document.openapiSchema}", which matches no schema in ${project ? 'the API spec' : 'an API spec (docs.json has no api.spec)'}.`,
+      );
     }
     documents.set(page.filePath, document);
-    const relative = path.relative(projectRoot, page.filePath).replace(/\\/g, '/');
     if (!document.title) warnings.push(`${relative} has no frontmatter title.`);
     if (!document.description) warnings.push(`${relative} has no frontmatter description.`);
   }

package/scripts/expand-openapi-navigation.mjs

@@ -26,48 +26,74 @@ export function hasOpenApiItems(navigation) {
   return Object.values(navigation).some(hasOpenApiItems);
 }
 
+const WEBHOOKS_GROUP = 'Webhooks';
+
 function pageEntry(operation, directory) {
   return {
-    page: `${directory}/${operation.id}`,
-    title: operation.summary || `${operation.method} ${operation.path}`,
-    method: operation.method,
+    page: operation.pageRef || `${directory}/${operation.id}`,
+    title:
+      operation.summary ||
+      (operation.webhook ? operation.path : `${operation.method} ${operation.path}`),
+    method: operation.webhook ? 'WEBHOOK' : operation.method,
   };
 }
 
+/** Untagged webhooks collect under a "Webhooks" group; tagged ones join their tag. */
+function operationTags(operation) {
+  const tagged = operation.tags.filter(tag => tag !== 'default');
+  if (tagged.length) return tagged;
+  return operation.webhook ? [WEBHOOKS_GROUP] : operation.tags;
+}
+
+function tagGroups(operations, directory) {
+  const tags = [];
+  for (const operation of operations) {
+    for (const tag of operationTags(operation)) {
+      if (!tags.includes(tag)) tags.push(tag);
+    }
+  }
+  return tags.map(tag => ({
+    group: tag,
+    pages: sortOperations(
+      operations.filter(operation => operationTags(operation).includes(tag)),
+    ).map(operation => pageEntry(operation, directory)),
+  }));
+}
+
 function sortOperations(operations) {
   return [...operations].sort(
     (left, right) => left.path.localeCompare(right.path) || left.method.localeCompare(right.method),
   );
 }
 
-function expandItem(item, { operations, directory }) {
+function expandItem(item, { operations, directory, specs = [] }) {
   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),
-      ),
-    }));
+    return tagGroups(operations, directory);
+  }
+
+  const value = item.openapi.trim();
+
+  // A configured spec path or URL expands into that spec's tag groups.
+  if (specs.some(spec => spec.id === value)) {
+    return tagGroups(
+      operations.filter(operation => operation.spec === value),
+      directory,
+    );
   }
 
-  const tag = item.openapi.trim();
-  const matched = sortOperations(operations.filter(operation => operation.tags.includes(tag)));
+  const matched = sortOperations(
+    operations.filter(operation => operationTags(operation).includes(value)),
+  );
   if (!matched.length) {
-    throw new Error(`Navigation openapi entry "${tag}" matched no operations in the API spec.`);
+    throw new Error(`Navigation openapi entry "${value}" 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 }) {
+export function expandOpenApiNavigation(config, { operations, directory, specs }) {
   function expandObject(value) {
     if (Array.isArray(value)) return value.map(expandObject);
     if (!value || typeof value !== 'object') return value;
@@ -78,7 +104,7 @@ export function expandOpenApiNavigation(config, { operations, directory }) {
           const expanded = [];
           for (const item of child) {
             if (isOpenApiItem(item)) {
-              expanded.push(...expandItem(item, { operations, directory }));
+              expanded.push(...expandItem(item, { operations, directory, specs }));
             } else {
               expanded.push(expandObject(item));
             }

package/scripts/generate-openapi.mjs

@@ -7,16 +7,17 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createHighlighter, hastToHtml } from 'shiki';
-import { loadOpenApiSpec, normalizeOperations } from './lib/openapi.mjs';
+import { loadApiProject } from './lib/openapi-project.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';
+import type { NormalizedOperation, SchemaPage } from '@/lib/types';
 
 export const OPENAPI_OPERATIONS: Record<string, NormalizedOperation> = {};
+export const OPENAPI_SCHEMAS: Record<string, SchemaPage> = {};
 `;
 
 let highlighterPromise;
@@ -97,21 +98,45 @@ export async function generateOpenApiModule({
     return { operations: 0 };
   }
 
-  const { spec } = await loadOpenApiSpec({ root, specPath: config.api.spec });
-  const operations = normalizeOperations(spec);
+  const project = await loadApiProject({ root, api: config.api });
   const highlighter = await getHighlighter(theme);
-  const record = {};
-
-  for (const operation of operations) {
-    record[operation.key] = await highlightOperation(operation, highlighter, theme);
+  const operations = {};
+  const schemas = {};
+
+  // Both the bare and the spec-qualified key resolve to the same object; bare
+  // keys that several specs share are omitted so pages must qualify them.
+  const highlighted = new Map();
+  for (const [key, operation] of project.operationsByKey) {
+    if (!operation) continue;
+    if (!highlighted.has(operation)) {
+      highlighted.set(operation, await highlightOperation(operation, highlighter, theme));
+    }
+    operations[key] = highlighted.get(operation);
+  }
+  for (const [key, schema] of project.schemasByKey) {
+    if (!schema) continue;
+    if (!highlighted.has(schema)) {
+      highlighted.set(
+        schema,
+        schema.example
+          ? {
+              ...schema,
+              exampleHtml: (await highlight(highlighter, schema.example, 'json', theme)).html,
+            }
+          : schema,
+      );
+    }
+    schemas[key] = highlighted.get(schema);
   }
 
   const contents = `// Generated by @umami/shiso. Do not edit by hand.
-import type { NormalizedOperation } from '@/lib/types';
+import type { NormalizedOperation, SchemaPage } from '@/lib/types';
+
+export const OPENAPI_OPERATIONS: Record<string, NormalizedOperation> = ${JSON.stringify(operations, null, 2)};
 
-export const OPENAPI_OPERATIONS: Record<string, NormalizedOperation> = ${JSON.stringify(record, null, 2)};
+export const OPENAPI_SCHEMAS: Record<string, SchemaPage> = ${JSON.stringify(schemas, null, 2)};
 `;
 
   await writeIfChanged(output, contents);
-  return { operations: operations.length };
+  return { operations: project.operations.length, schemas: project.schemas.length };
 }

package/scripts/generate-search-index.mjs

@@ -22,12 +22,8 @@ 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 { operationSearchSections, schemaSearchSections } from './lib/openapi.mjs';
+import { loadApiProject, lookupOperation, lookupSchema } from './lib/openapi-project.mjs';
 import { createSlugger, slugifyId } from './lib/slug.mjs';
 import { loadDocsConfig } from './load-docs-config.mjs';
 import { loadShisoConfig } from './load-shiso-config.mjs';
@@ -148,10 +144,10 @@ function collectVisiblePages(container, pages = [], hidden = false) {
 }
 
 /** Frontmatter is YAML, but search only needs single lines from it. */
-function frontmatterOpenApi(tree) {
+function frontmatterField(tree, name) {
   const yaml = tree.children?.find(node => node.type === 'yaml');
-  const match = yaml?.value?.match(/^openapi:\s*(.+)$/m);
-  return match ? match[1].trim() : undefined;
+  const match = yaml?.value?.match(new RegExp(`^${name}:\\s*(.+)$`, 'm'));
+  return match ? match[1].trim().replace(/^["']|["']$/g, '') : undefined;
 }
 
 function frontmatterTitle(tree) {
@@ -225,13 +221,9 @@ export async function generateSearchIndex({
 
   // 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]),
-    );
-  }
+  const project = docsJson.api?.spec
+    ? await loadApiProject({ root, api: docsJson.api })
+    : undefined;
 
   for (const scope of collectScopes(docsJson.navigation || {})) {
     // Single-scope sites omit scope fields so their index stays unchanged.
@@ -272,13 +264,22 @@ export async function generateSearchIndex({
         records.push({ url, page, heading, id, text, ...scopeFields });
       }
 
-      const operationKey = normalizeOperationKey(frontmatterOpenApi(tree));
-      const operation = operationKey ? operationsByKey?.get(operationKey) : undefined;
+      const operation = project
+        ? lookupOperation(project, frontmatterField(tree, 'openapi'))
+        : undefined;
       if (operation) {
         for (const { heading, id, text } of operationSearchSections(operation)) {
           records.push({ url, page, heading, id, text, ...scopeFields });
         }
       }
+      const schema = project
+        ? lookupSchema(project, frontmatterField(tree, 'openapi-schema'))
+        : undefined;
+      if (schema) {
+        for (const { heading, id, text } of schemaSearchSections(schema)) {
+          records.push({ url, page, heading, id, text, ...scopeFields });
+        }
+      }
     }
   }
 

package/scripts/lib/openapi-project.mjs

@@ -0,0 +1,197 @@
+/**
+ * Loads every OpenAPI spec a project configures and indexes the result.
+ *
+ * `api.spec` accepts one path or URL, or a list of them. Each spec becomes a
+ * set of operations (and webhooks) plus named schemas; with several specs the
+ * endpoint pages of each land in their own subdirectory and frontmatter keys
+ * may be qualified with the spec ("users.yaml GET /users") to disambiguate.
+ * Remote specs are fetched on load and cached under .shiso so a build still
+ * succeeds when the URL is unreachable.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import {
+  DEFAULT_API_DIRECTORY,
+  loadOpenApiSpec,
+  normalizeOperationKey,
+  normalizeOperations,
+  normalizeSchemaKey,
+  normalizeSchemas,
+  resolveApiDirectory,
+} from './openapi.mjs';
+import { slugify } from './slug.mjs';
+
+const REMOTE = /^https?:\/\//i;
+const remoteCache = new Map();
+
+export function isRemoteSpec(source) {
+  return REMOTE.test(String(source || ''));
+}
+
+/** Normalizes api.spec into an ordered list of spec sources. */
+export function apiSpecSources(api) {
+  const raw = api?.spec;
+  const list = Array.isArray(raw) ? raw : raw ? [raw] : [];
+  const sources = list.map(item => (typeof item === 'string' ? item.trim() : '')).filter(Boolean);
+  if (new Set(sources).size !== sources.length) {
+    throw new Error('api.spec lists the same spec more than once.');
+  }
+  return sources;
+}
+
+/** Folder name for one spec's endpoint pages on a multi-spec site. */
+export function specDirectorySlug(source) {
+  const base = isRemoteSpec(source)
+    ? new URL(source).pathname.split('/').filter(Boolean).pop() || new URL(source).hostname
+    : source.replace(/\\/g, '/').split('/').pop();
+  return slugify(base.replace(/\.(json|ya?ml)$/i, '').replace(/\./g, '-'), 'api');
+}
+
+function validateSpecDocument(spec, label) {
+  if (!spec || typeof spec !== 'object' || typeof spec.openapi !== 'string') {
+    throw new Error(`"${label}" is not an OpenAPI document: missing the "openapi" version field.`);
+  }
+  if (!spec.openapi.startsWith('3.')) {
+    throw new Error(
+      `Unsupported OpenAPI version "${spec.openapi}" in "${label}": Shiso supports OpenAPI 3.0 and 3.1.`,
+    );
+  }
+}
+
+async function loadRemoteSpec({ root, url, fetchImpl = globalThis.fetch }) {
+  const cacheDir = path.join(path.resolve(root), '.shiso', 'openapi-cache');
+  const cachePath = path.join(cacheDir, `${slugify(url, 'spec')}.txt`);
+  // One download per project and process: dev-server reloads reuse the copy.
+  const memoryKey = `${cacheDir}|${url}`;
+
+  if (remoteCache.has(memoryKey)) return { spec: remoteCache.get(memoryKey), specPath: cachePath };
+
+  let source;
+  let fetchError;
+  try {
+    if (typeof fetchImpl !== 'function') throw new Error('fetch is not available');
+    const response = await fetchImpl(url, { headers: { Accept: 'application/json, text/yaml' } });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    source = await response.text();
+    await fs.mkdir(cacheDir, { recursive: true });
+    await fs.writeFile(cachePath, source);
+  } catch (error) {
+    fetchError = error;
+    source = await fs.readFile(cachePath, 'utf8').catch(() => undefined);
+    if (source === undefined) {
+      throw new Error(`Could not download OpenAPI spec "${url}": ${error.message}`);
+    }
+    console.warn(
+      `Could not download OpenAPI spec "${url}" (${error.message}); using the cached copy.`,
+    );
+  }
+
+  let spec;
+  try {
+    spec = parseYaml(source);
+  } catch (error) {
+    throw new Error(`Could not parse OpenAPI spec "${url}": ${error.message}`);
+  }
+  validateSpecDocument(spec, url);
+  if (!fetchError) remoteCache.set(memoryKey, spec);
+  return { spec, specPath: cachePath };
+}
+
+/**
+ * Loads and indexes every configured spec. Returns the specs, all operations
+ * (each carrying `spec`, `directory`, and `pageRef`), all schemas, and lookup
+ * maps keyed by both the bare key ("GET /users") and the spec-qualified key
+ * ("users.yaml GET /users"). Bare keys shared by several specs are recorded
+ * in `ambiguous` and resolve to nothing, so pages must qualify them.
+ */
+export async function loadApiProject({ root, api, fetchImpl } = {}) {
+  const sources = apiSpecSources(api);
+  const directory = resolveApiDirectory(api);
+  const multi = sources.length > 1;
+  const specs = [];
+  const operations = [];
+  const schemas = [];
+
+  for (const source of sources) {
+    const loaded = isRemoteSpec(source)
+      ? await loadRemoteSpec({ root, url: source, fetchImpl })
+      : await loadOpenApiSpec({ root, specPath: source });
+    const specDirectory = multi ? `${directory}/${specDirectorySlug(source)}` : directory;
+    const ownOperations = normalizeOperations(loaded.spec, { specId: source }).map(operation => ({
+      ...operation,
+      directory: specDirectory,
+      pageRef: `${specDirectory}/${operation.id}`,
+    }));
+    specs.push({
+      id: source,
+      spec: loaded.spec,
+      specPath: loaded.specPath,
+      remote: isRemoteSpec(source),
+      directory: specDirectory,
+      title: loaded.spec.info?.title,
+    });
+    operations.push(...ownOperations);
+    schemas.push(...normalizeSchemas(loaded.spec, { specId: source }));
+  }
+
+  const operationsByKey = new Map();
+  const schemasByKey = new Map();
+  const ambiguous = new Set();
+  const index = (map, key, value) => {
+    if (map.has(key)) {
+      ambiguous.add(key);
+      map.set(key, undefined);
+    } else if (!ambiguous.has(key)) {
+      map.set(key, value);
+    }
+  };
+
+  for (const operation of operations) {
+    index(operationsByKey, operation.key, operation);
+    operationsByKey.set(`${operation.spec} ${operation.key}`, operation);
+  }
+  for (const schema of schemas) {
+    index(schemasByKey, schema.key, schema);
+    schemasByKey.set(`${schema.spec} ${schema.key}`, schema);
+  }
+
+  return {
+    specs,
+    directory,
+    multi,
+    operations,
+    schemas,
+    operationsByKey,
+    schemasByKey,
+    ambiguous,
+    specPaths: specs.filter(spec => !spec.remote).map(spec => spec.specPath),
+  };
+}
+
+/** Resolves an `openapi:` frontmatter value against a loaded project. */
+export function lookupOperation(project, value) {
+  const key = normalizeOperationKey(value);
+  return key ? project.operationsByKey.get(key) : undefined;
+}
+
+/** Resolves an `openapi-schema:` frontmatter value against a loaded project. */
+export function lookupSchema(project, value) {
+  const key = normalizeSchemaKey(value);
+  return key ? project.schemasByKey.get(key) : undefined;
+}
+
+/** True when an `openapi:` value names an operation that several specs define. */
+export function isAmbiguousOperation(project, value) {
+  const key = normalizeOperationKey(value);
+  return !!key && project.ambiguous.has(key);
+}
+
+/** True when an `openapi-schema:` value names a schema that several specs define. */
+export function isAmbiguousSchema(project, value) {
+  const key = normalizeSchemaKey(value);
+  return !!key && project.ambiguous.has(key);
+}
+
+export { DEFAULT_API_DIRECTORY };