@umami/shiso 1.11.0 → 1.13.0

package/scripts/check-content.mjs

@@ -0,0 +1,358 @@
+/**
+ * Validates the content graph behind docs.json.
+ *
+ * Schema validation proves the configuration has the right shape; this pass
+ * proves that its page references, routes, links, anchors, and local assets
+ * describe a site that can actually be navigated.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { headingText } from './lib/mdast.mjs';
+import {
+  loadOpenApiSpec,
+  normalizeOperationKey,
+  normalizeOperations,
+  operationAnchors,
+} from './lib/openapi.mjs';
+import { createSlugger } from './lib/slug.mjs';
+import { loadDocsConfig } from './load-docs-config.mjs';
+import { loadShisoConfig } from './load-shiso-config.mjs';
+
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+const PAGE_EXTENSIONS = ['.mdx', '.md'];
+const parser = unified().use(remarkParse).use(remarkMdx).use(remarkFrontmatter).use(remarkGfm);
+
+function normalizePageReference(value) {
+  const fileSlug =
+    String(value || '')
+      .trim()
+      .replace(/\\/g, '/')
+      .replace(/^\/+/, '')
+      .replace(/^docs\//, '')
+      .replace(/\.mdx?$/i, '')
+      .replace(/\/+$/, '') || 'index';
+  const routeSlug = fileSlug === 'index' ? 'index' : fileSlug.replace(/\/index$/, '') || 'index';
+  return { fileSlug, routeSlug };
+}
+
+function normalizeRoute(value) {
+  const route = String(value || '/')
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/');
+  const withoutIndex = route === '/index' ? '/' : route.replace(/\/index$/, '') || '/';
+  return withoutIndex.length > 1 ? withoutIndex.replace(/\/+$/, '') : withoutIndex;
+}
+
+function pageRoute(routeSlug, docsPrefix) {
+  return normalizeRoute(routeSlug === 'index' ? docsPrefix || '/' : `${docsPrefix}/${routeSlug}`);
+}
+
+async function exists(filePath) {
+  try {
+    return (await fs.stat(filePath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function listFiles(directory) {
+  const files = [];
+  let entries;
+
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    const item = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(item)));
+    } else if (entry.isFile()) {
+      files.push(item);
+    }
+  }
+
+  return files;
+}
+
+function collectPageReferences(navigation) {
+  const references = [];
+
+  function visitContainer(container) {
+    if (!container || typeof container !== 'object') return;
+    if (Array.isArray(container.pages)) visitItems(container.pages);
+    for (const key of ['tabs', 'dropdowns', 'groups', 'versions', 'languages']) {
+      if (Array.isArray(container[key])) container[key].forEach(visitContainer);
+    }
+  }
+
+  function visitItems(items) {
+    for (const item of items) {
+      if (typeof item === 'string') {
+        references.push(item);
+      } else if (item && typeof item === 'object') {
+        if (typeof item.page === 'string') references.push(item.page);
+        if (typeof item.root === 'string') references.push(item.root);
+        if (Array.isArray(item.pages)) visitItems(item.pages);
+      }
+    }
+  }
+
+  visitContainer(navigation);
+  return references;
+}
+
+async function resolveFile(root, directory, slug, extensions) {
+  for (const extension of extensions) {
+    const candidate = path.resolve(root, directory, `${slug}${extension}`);
+    if (await exists(candidate)) return candidate;
+  }
+  return null;
+}
+
+function walk(node, visitor) {
+  visitor(node);
+  for (const child of node.children || []) walk(child, visitor);
+}
+
+function literalAttribute(node, name) {
+  const attribute = (node.attributes || []).find(item => item?.name === name);
+  return typeof attribute?.value === 'string' ? attribute.value : null;
+}
+
+function inspectMarkdown(source, filePath) {
+  const tree = parser.parse(source);
+  const slugger = createSlugger();
+  const anchors = new Set();
+  const targets = [];
+
+  walk(tree, node => {
+    if (node.type === 'heading') anchors.add(slugger.slug(headingText(node)));
+
+    if (node.type === 'link' && typeof node.url === 'string') {
+      targets.push({ kind: 'link', value: node.url, line: node.position?.start.line || 1 });
+    } else if (node.type === 'image' && typeof node.url === 'string') {
+      targets.push({ kind: 'asset', value: node.url, line: node.position?.start.line || 1 });
+    } else if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+      const href = literalAttribute(node, 'href');
+      const src = literalAttribute(node, 'src');
+      if (href) targets.push({ kind: 'link', value: href, line: node.position?.start.line || 1 });
+      if (src) targets.push({ kind: 'asset', value: src, line: node.position?.start.line || 1 });
+    }
+  });
+
+  const frontmatter = source.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] || '';
+  return {
+    filePath,
+    anchors,
+    targets,
+    title: /^title\s*:/m.test(frontmatter),
+    description: /^description\s*:/m.test(frontmatter),
+    openapi: frontmatter.match(/^openapi:\s*(.+)$/m)?.[1]?.trim(),
+  };
+}
+
+function diagnostic(relativePath, line, message) {
+  return `${relativePath.replace(/\\/g, '/')}:${line} ${message}`;
+}
+
+function splitTarget(raw) {
+  const value = raw.trim();
+  const hashIndex = value.indexOf('#');
+  const beforeHash = hashIndex >= 0 ? value.slice(0, hashIndex) : value;
+  return {
+    pathname: beforeHash.split('?')[0],
+    fragment: hashIndex >= 0 ? value.slice(hashIndex + 1) : '',
+  };
+}
+
+function isExternal(value) {
+  return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(value);
+}
+
+function resolveLinkRoute(rawPath, currentRoute) {
+  if (!rawPath) return currentRoute;
+  const value = rawPath.replace(/\.mdx?$/i, '');
+  if (value.startsWith('/')) return normalizeRoute(value);
+  return normalizeRoute(new URL(value, `https://shiso.invalid${currentRoute}`).pathname);
+}
+
+/** Returns content errors and non-fatal authoring warnings for one project. */
+export async function checkContent({ root = process.cwd(), config, shiso } = {}) {
+  const projectRoot = path.resolve(root);
+  const docsConfig = config ?? (await loadDocsConfig({ root: projectRoot })).config;
+  const engine = shiso ?? (await loadShisoConfig({ root: projectRoot })).config;
+  const errors = [];
+  const warnings = [];
+  const routes = new Map();
+  const pages = [];
+  const referencedFiles = new Set();
+
+  for (const reference of collectPageReferences(docsConfig.navigation)) {
+    const { fileSlug, routeSlug } = normalizePageReference(reference);
+    const filePath = await resolveFile(projectRoot, engine.contentDir, fileSlug, PAGE_EXTENSIONS);
+    const route = pageRoute(routeSlug, engine.docsPrefix);
+
+    if (!filePath) {
+      errors.push(
+        `docs.json references missing page "${fileSlug}" (expected ${engine.contentDir}/${fileSlug}.mdx or .md).`,
+      );
+      continue;
+    }
+
+    const previous = routes.get(route);
+    if (previous && previous !== filePath) {
+      errors.push(
+        `Route "${route}" is produced by both "${path.relative(projectRoot, previous)}" and "${path.relative(projectRoot, filePath)}".`,
+      );
+      continue;
+    }
+    if (referencedFiles.has(filePath)) {
+      errors.push(`Page "${fileSlug}" is referenced more than once in navigation.`);
+      continue;
+    }
+
+    routes.set(route, filePath);
+    referencedFiles.add(filePath);
+    pages.push({ route, filePath });
+  }
+
+  for (const item of docsConfig.pages || []) {
+    const route = normalizeRoute(item?.path);
+    const slug =
+      String(item?.page || 'index')
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/^\/+|\/+$/g, '')
+        .replace(/^pages\//, '')
+        .replace(/\.(?:mdx?|tsx)$/i, '') || 'index';
+    const filePath = await resolveFile(projectRoot, 'content/pages', slug, ['.tsx', '.mdx', '.md']);
+
+    if (!filePath) {
+      errors.push(
+        `docs.json references missing standalone page "${slug}" (expected content/pages/${slug}.tsx, .mdx, or .md).`,
+      );
+      continue;
+    }
+    if (routes.has(route)) {
+      errors.push(
+        `Standalone route "${route}" collides with "${path.relative(projectRoot, routes.get(route))}".`,
+      );
+      continue;
+    }
+    routes.set(route, filePath);
+    referencedFiles.add(filePath);
+    if (MARKDOWN_EXTENSIONS.has(path.extname(filePath))) pages.push({ route, filePath });
+  }
+
+  // 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 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;
+    if (operation) {
+      for (const anchor of operationAnchors(operation)) {
+        document.anchors.add(anchor);
+      }
+    }
+    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.`);
+  }
+
+  const publicRoot = path.resolve(projectRoot, 'public');
+  for (const page of pages) {
+    const document = documents.get(page.filePath);
+    const relative = path.relative(projectRoot, page.filePath);
+
+    for (const target of document.targets) {
+      if (!target.value || isExternal(target.value)) continue;
+      const { pathname, fragment } = splitTarget(target.value);
+
+      if (target.kind === 'asset') {
+        const assetPath = pathname.startsWith('/')
+          ? path.resolve(publicRoot, pathname.replace(/^\/+/, ''))
+          : path.resolve(path.dirname(page.filePath), pathname);
+        if (!(await exists(assetPath))) {
+          errors.push(
+            diagnostic(relative, target.line, `references missing asset "${target.value}".`),
+          );
+        }
+        continue;
+      }
+
+      const targetRoute = resolveLinkRoute(pathname, page.route);
+      const targetFile = routes.get(targetRoute);
+
+      if (!targetFile && pathname && /\.[a-z\d]+$/i.test(pathname) && !/\.mdx?$/i.test(pathname)) {
+        const publicFile = pathname.startsWith('/')
+          ? path.resolve(publicRoot, pathname.replace(/^\/+/, ''))
+          : path.resolve(path.dirname(page.filePath), pathname);
+        if (await exists(publicFile)) continue;
+      }
+
+      if (!targetFile) {
+        errors.push(diagnostic(relative, target.line, `links to unknown route "${target.value}".`));
+        continue;
+      }
+
+      if (fragment && MARKDOWN_EXTENSIONS.has(path.extname(targetFile))) {
+        const targetDocument = documents.get(targetFile);
+        let decoded = fragment;
+        try {
+          decoded = decodeURIComponent(fragment);
+        } catch {
+          // Report the original fragment below.
+        }
+        if (targetDocument && !targetDocument.anchors.has(decoded)) {
+          errors.push(
+            diagnostic(
+              relative,
+              target.line,
+              `links to missing anchor "#${fragment}" on "${targetRoute}".`,
+            ),
+          );
+        }
+      }
+    }
+  }
+
+  for (const redirect of docsConfig.redirects || []) {
+    if (
+      !isExternal(redirect.destination) &&
+      !routes.has(normalizeRoute(splitTarget(redirect.destination).pathname))
+    ) {
+      errors.push(
+        `Redirect "${redirect.source}" points to unknown route "${redirect.destination}".`,
+      );
+    }
+  }
+
+  const docsRoot = path.resolve(projectRoot, engine.contentDir);
+  for (const filePath of await listFiles(docsRoot)) {
+    if (MARKDOWN_EXTENSIONS.has(path.extname(filePath)) && !referencedFiles.has(filePath)) {
+      warnings.push(
+        `${path.relative(projectRoot, filePath).replace(/\\/g, '/')} is not referenced by navigation.`,
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/scripts/expand-navigation-globs.mjs

@@ -0,0 +1,277 @@
+/** 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 normalizePageReference(value) {
+  return String(value || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .replace(/^docs\//, '')
+    .replace(/\.mdx?$/i, '')
+    .replace(/\/+$/, '');
+}
+
+/** Collects manual page references without crossing a version/language scope boundary. */
+function collectExplicitPages(value, pages = new Set()) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === 'string') {
+        pages.add(normalizePageReference(item));
+      } else {
+        collectExplicitPages(item, pages);
+      }
+    }
+    return pages;
+  }
+
+  if (!value || typeof value !== 'object' || isGlobItem(value)) return pages;
+
+  if (typeof value.page === 'string') pages.add(normalizePageReference(value.page));
+  if (typeof value.root === 'string') pages.add(normalizePageReference(value.root));
+
+  for (const key of ['pages', 'groups', 'tabs', 'dropdowns']) {
+    if (Array.isArray(value[key])) collectExplicitPages(value[key], pages);
+  }
+
+  return pages;
+}
+
+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, explicitPages) {
+  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.`);
+  }
+
+  // Manual entries own their page's placement and presentation, regardless of
+  // whether they appear before or after the glob that would otherwise include it.
+  const discovered = matched.filter(candidate => !explicitPages.has(candidate.fileSlug));
+
+  const entries = await Promise.all(
+    discovered.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, explicitPages) {
+    if (Array.isArray(value)) {
+      return Promise.all(value.map(item => expandObject(item, explicitPages)));
+    }
+    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, explicitPages)));
+            } else {
+              expanded.push(await expandObject(item, explicitPages));
+            }
+          }
+          return [key, expanded];
+        }
+        return [key, await expandObject(child, explicitPages)];
+      }),
+    );
+    return Object.fromEntries(entries);
+  }
+
+  async function expandScope(scope) {
+    return expandObject(scope, collectExplicitPages(scope));
+  }
+
+  async function expandNavigation(navigation) {
+    if (Array.isArray(navigation.languages)) {
+      const languages = await Promise.all(
+        navigation.languages.map(async language => {
+          if (!Array.isArray(language.versions)) return expandScope(language);
+          return {
+            ...language,
+            versions: await Promise.all(language.versions.map(expandScope)),
+          };
+        }),
+      );
+      return { ...navigation, languages };
+    }
+
+    if (Array.isArray(navigation.versions)) {
+      return {
+        ...navigation,
+        versions: await Promise.all(navigation.versions.map(expandScope)),
+      };
+    }
+
+    return expandScope(navigation);
+  }
+
+  return { ...config, navigation: await expandNavigation(config.navigation) };
+}