radiant-docs-validator 0.1.0

package/dist/index.js

@@ -0,0 +1,2035 @@
+import {
+  docsSchema
+} from "./chunk-SXKC5VM6.js";
+import {
+  DEFAULT_SHIKI_DARK_THEME,
+  DEFAULT_SHIKI_LIGHT_THEME,
+  SHIKI_BUNDLED_THEME_NAMES,
+  isBundledShikiThemeName
+} from "./chunk-652XVPHE.js";
+
+// src/validator.ts
+import fs from "fs";
+import { createRequire } from "module";
+import path from "path";
+import pkg from "@stoplight/spectral-core";
+import { oas } from "@stoplight/spectral-rulesets";
+import { compile } from "@mdx-js/mdx";
+import yaml from "yaml";
+var { Spectral } = pkg;
+var DOCS_DIR = "";
+var CONFIG_PATH = "";
+var require2 = createRequire(import.meta.url);
+function assertConfigured() {
+  if (!DOCS_DIR) {
+    throw new Error(
+      "Docs validator has not been configured. Call configureDocsValidator({ docsRoot }) before validating docs."
+    );
+  }
+}
+function configureDocsValidator({
+  docsRoot
+}) {
+  const nextDocsDir = path.resolve(docsRoot);
+  if (DOCS_DIR === nextDocsDir) {
+    return;
+  }
+  DOCS_DIR = nextDocsDir;
+  CONFIG_PATH = path.join(DOCS_DIR, "docs.json");
+  iconSets.clear();
+  openApiSpecCache.clear();
+  configCache = null;
+  lastMtime = 0;
+}
+var iconSets = /* @__PURE__ */ new Map();
+function isUrl(str) {
+  try {
+    const url = new URL(str);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function getIconSet(prefix) {
+  if (iconSets.has(prefix)) return iconSets.get(prefix);
+  try {
+    const iconsPath = require2.resolve(`@iconify-json/${prefix}/icons.json`);
+    const iconsData = JSON.parse(fs.readFileSync(iconsPath, "utf-8"));
+    const set = new Set(Object.keys(iconsData.icons));
+    iconSets.set(prefix, set);
+    return set;
+  } catch (error) {
+    console.error(`Failed to load icon set for prefix "${prefix}":`, error);
+    return null;
+  }
+}
+function validateIcon(icon, currentPath) {
+  if (icon === void 0 || icon === null) return;
+  if (typeof icon !== "string") {
+    throwConfigError("Icon must be a string.", currentPath);
+  }
+  if (isUrl(icon)) {
+    return;
+  }
+  if (icon.includes(":")) {
+    const parts = icon.split(":");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+      throwConfigError(
+        `Invalid library icon format: "${icon}". Icons must follow the "library-prefix:name" format (e.g., "lucide:home") or be a local path.`,
+        currentPath
+      );
+    }
+    const [prefix, name] = parts;
+    const icons = getIconSet(prefix);
+    if (icons) {
+      if (!icons.has(name)) {
+        throwConfigError(
+          `Invalid icon name: "${name}" for library "${prefix}". Is this a typo?`,
+          currentPath
+        );
+      }
+    } else {
+      throwConfigError(
+        `Invalid icon library: "${prefix}". Is this package installed in @iconify-json?`,
+        currentPath
+      );
+    }
+    return;
+  }
+  const localRelativePath = icon.startsWith("/") ? icon.slice(1) : icon;
+  const localPath = path.join(DOCS_DIR, localRelativePath);
+  if (!fs.existsSync(localPath)) {
+    throwConfigError(
+      `Icon not found: "${icon}". Local icons must exist in your repository. Did you mean to use an library icon like "lucide:home"?`,
+      currentPath
+    );
+  }
+}
+var AVAILABLE_COMPONENTS = [
+  "Callout",
+  "Tabs",
+  "Tab",
+  "Steps",
+  "Step",
+  "Accordion",
+  "AccordionGroup",
+  "Card",
+  "Column",
+  "Columns",
+  "Image",
+  "CodeGroup",
+  "ComponentPreview"
+];
+var INTERNAL_ONLY_COMPONENTS = /* @__PURE__ */ new Set(["ComponentPreview"]);
+var BASE_COLOR_OPTIONS = [
+  "slate",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone",
+  "taupe",
+  "mauve",
+  "mist",
+  "olive"
+];
+var DEFAULT_THEME_COLOR_LIGHT = "#171717";
+var DEFAULT_THEME_COLOR_DARK = "#f5f5f5";
+var throwConfigError = (message, currentPath) => {
+  const location = currentPath.length > 0 ? ` (at: ${currentPath.join(".")})` : "";
+  throw new Error(`${message}${location}
+`);
+};
+function checkType(value, type, currentPath, label) {
+  if (value === void 0 || value === null) return;
+  if (type === "array") {
+    if (!Array.isArray(value))
+      throwConfigError(`${label} must be an array.`, currentPath);
+  } else if (type === "object") {
+    if (typeof value !== "object" || value === null)
+      throwConfigError(`${label} must be an object.`, currentPath);
+  } else {
+    if (typeof value !== type)
+      throwConfigError(`${label} must be a ${type}.`, currentPath);
+  }
+}
+function normalizeHexColor(value, currentPath, label) {
+  checkType(value, "string", currentPath, label);
+  if (typeof value !== "string") {
+    throwConfigError(`${label} must be a string.`, currentPath);
+  }
+  const trimmedValue = value.trim();
+  if (trimmedValue.length === 0) {
+    throwConfigError(`${label} cannot be empty.`, currentPath);
+  }
+  const normalizedValue = trimmedValue.startsWith("#") ? trimmedValue : `#${trimmedValue}`;
+  if (!/^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{4}|[A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/.test(
+    normalizedValue
+  )) {
+    throwConfigError(
+      `${label} must be a valid hex color (for example: #1d4ed8).`,
+      currentPath
+    );
+  }
+  return normalizedValue.toLowerCase();
+}
+function normalizeThemeColorConfig(value, currentPath, label) {
+  if (typeof value === "string") {
+    return normalizeHexColor(value, currentPath, label);
+  }
+  checkType(value, "object", currentPath, label);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throwConfigError(
+      `${label} must be a string or an object with light/dark values.`,
+      currentPath
+    );
+  }
+  const colorByMode = value;
+  const allowedKeys = /* @__PURE__ */ new Set(["light", "dark"]);
+  for (const key of Object.keys(colorByMode)) {
+    if (!allowedKeys.has(key)) {
+      throwConfigError(`${label} object only supports 'light' and 'dark'.`, [
+        ...currentPath,
+        key
+      ]);
+    }
+  }
+  const light = colorByMode.light !== void 0 ? normalizeHexColor(colorByMode.light, [...currentPath, "light"], label) : void 0;
+  const dark = colorByMode.dark !== void 0 ? normalizeHexColor(colorByMode.dark, [...currentPath, "dark"], label) : void 0;
+  if (light === void 0 && dark === void 0) {
+    throwConfigError(
+      `${label} object must include 'light', 'dark', or both.`,
+      currentPath
+    );
+  }
+  return {
+    ...light !== void 0 ? { light } : {},
+    ...dark !== void 0 ? { dark } : {}
+  };
+}
+function normalizeNavTagConfig(value, currentPath, label) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string") {
+    const trimmedText2 = value.trim();
+    if (trimmedText2.length === 0) {
+      throwConfigError(`${label} cannot be empty.`, currentPath);
+    }
+    return trimmedText2;
+  }
+  checkType(value, "object", currentPath, label);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throwConfigError(
+      `${label} must be a string or an object with text and optional color.`,
+      currentPath
+    );
+  }
+  const tagConfig = value;
+  const allowedKeys = /* @__PURE__ */ new Set(["text", "color"]);
+  for (const key of Object.keys(tagConfig)) {
+    if (!allowedKeys.has(key)) {
+      throwConfigError(`${label} object only supports 'text' and 'color'.`, [
+        ...currentPath,
+        key
+      ]);
+    }
+  }
+  checkType(tagConfig.text, "string", [...currentPath, "text"], `${label} text`);
+  if (typeof tagConfig.text !== "string") {
+    throwConfigError(`${label} text must be a string.`, [
+      ...currentPath,
+      "text"
+    ]);
+  }
+  const trimmedText = tagConfig.text.trim();
+  if (trimmedText.length === 0) {
+    throwConfigError(`${label} text cannot be empty.`, [
+      ...currentPath,
+      "text"
+    ]);
+  }
+  const color = tagConfig.color !== void 0 ? normalizeThemeColorConfig(
+    tagConfig.color,
+    [...currentPath, "color"],
+    `${label} color`
+  ) : void 0;
+  return {
+    text: trimmedText,
+    ...color !== void 0 ? { color } : {}
+  };
+}
+function normalizeHexColorArray(value, currentPath, label) {
+  checkType(value, "array", currentPath, label);
+  if (!Array.isArray(value)) {
+    throwConfigError(`${label} must be an array.`, currentPath);
+  }
+  const colors = value;
+  if (colors.length < 1 || colors.length > 4) {
+    throwConfigError(`${label} must include 1 to 4 colors.`, currentPath);
+  }
+  return colors.map(
+    (color, index) => normalizeHexColor(color, [...currentPath, index], `${label} ${index + 1}`)
+  );
+}
+function normalizeSeedValue(value, currentPath, label) {
+  checkType(value, "string", currentPath, label);
+  if (typeof value !== "string") {
+    throwConfigError(`${label} must be a string.`, currentPath);
+  }
+  const trimmedValue = value.trim();
+  if (trimmedValue.length === 0) {
+    throwConfigError(`${label} cannot be empty.`, currentPath);
+  }
+  return trimmedValue;
+}
+function validateFileExistence(filePath, currentPath) {
+  const fullPath = path.join(DOCS_DIR, `${filePath}.mdx`);
+  if (!fs.existsSync(fullPath)) {
+    throwConfigError(
+      `Referenced file not found. Expected: ${filePath}`,
+      currentPath
+    );
+  }
+}
+function normalizeDocsPagePath(value, currentPath, label = "Page path") {
+  checkType(value, "string", currentPath, label);
+  const trimmedPath = value.trim();
+  if (trimmedPath === "") {
+    throwConfigError(`${label} cannot be an empty string`, currentPath);
+  }
+  if (isUrl(trimmedPath)) {
+    throwConfigError(
+      `${label} must reference a documentation page path, not a URL`,
+      currentPath
+    );
+  }
+  const normalizedPath = trimmedPath.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (normalizedPath === "") {
+    throwConfigError(`${label} cannot be '/'`, currentPath);
+  }
+  return normalizedPath;
+}
+function splitHrefPathAndSuffix(href) {
+  const match = href.match(/^([^?#]*)(.*)$/);
+  return {
+    pathname: match?.[1] ?? href,
+    suffix: match?.[2] ?? ""
+  };
+}
+function normalizeInternalPageHref(href, currentPath, label) {
+  const trimmedHref = href.trim();
+  if (trimmedHref === "") {
+    throwConfigError(`${label} cannot be an empty string`, currentPath);
+  }
+  if (isUrl(trimmedHref)) {
+    return null;
+  }
+  if (!trimmedHref.startsWith("/")) {
+    throwConfigError(
+      `${label} must be either a valid URL (http:// or https://) or an internal path (starting with /)`,
+      currentPath
+    );
+  }
+  const { pathname, suffix } = splitHrefPathAndSuffix(trimmedHref);
+  const normalizedPathname = pathname.replace(/\/{2,}/g, "/");
+  if (normalizedPathname === "/" || normalizedPathname === "") {
+    return null;
+  }
+  const filePath = normalizeDocsPagePath(
+    normalizedPathname,
+    currentPath,
+    label
+  );
+  validateFileExistence(filePath, currentPath);
+  return {
+    filePath,
+    href: `/${filePath}`,
+    linkHref: `/${filePath}${suffix}`
+  };
+}
+var openApiSpecCache = /* @__PURE__ */ new Map();
+async function loadOpenApiSpec(filePathOrUrl) {
+  assertConfigured();
+  if (openApiSpecCache.has(filePathOrUrl)) {
+    return openApiSpecCache.get(filePathOrUrl);
+  }
+  const isUrlPath = isUrl(filePathOrUrl);
+  let fileContent;
+  if (isUrlPath) {
+    try {
+      const response = await fetch(filePathOrUrl);
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`
+        );
+      }
+      fileContent = await response.text();
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch OpenAPI spec from URL: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  } else {
+    const fullPath = path.join(DOCS_DIR, filePathOrUrl);
+    fileContent = fs.readFileSync(fullPath, "utf-8");
+  }
+  const trimmedContent = fileContent.trim();
+  if (trimmedContent.startsWith("<!DOCTYPE") || trimmedContent.startsWith("<html")) {
+    throw new Error(
+      "The URL does not return a valid OpenAPI specification. The URL appears to return HTML instead of JSON or YAML."
+    );
+  }
+  let parsedSpec;
+  try {
+    if (filePathOrUrl.endsWith(".json") || isUrlPath && filePathOrUrl.includes(".json")) {
+      parsedSpec = JSON.parse(fileContent);
+    } else {
+      const yaml2 = await import("yaml");
+      parsedSpec = yaml2.parse(fileContent);
+    }
+  } catch (parseError) {
+    if (parseError instanceof SyntaxError) {
+      throw new Error(
+        `The URL does not return a valid OpenAPI specification. Failed to parse as JSON or YAML: ${parseError.message}`
+      );
+    }
+    throw parseError;
+  }
+  openApiSpecCache.set(filePathOrUrl, parsedSpec);
+  return parsedSpec;
+}
+async function validateOpenApiFile(filePathOrUrl, currentPath) {
+  const isUrlPath = isUrl(filePathOrUrl);
+  if (!isUrlPath) {
+    const validExtensions = [".json", ".yaml", ".yml"];
+    const hasValidExtension = validExtensions.some(
+      (ext) => filePathOrUrl.toLowerCase().endsWith(ext)
+    );
+    if (!hasValidExtension) {
+      throwConfigError(
+        `OpenAPI file must have a valid extension (.json, .yaml, or .yml). Found: ${filePathOrUrl}`,
+        currentPath
+      );
+    }
+    const fullPath = path.join(DOCS_DIR, filePathOrUrl);
+    if (!fs.existsSync(fullPath)) {
+      throwConfigError(
+        `Referenced OpenAPI file not found. Expected: ${filePathOrUrl}`,
+        currentPath
+      );
+    }
+  } else {
+    try {
+      const url = new URL(filePathOrUrl);
+      if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throwConfigError(
+          `OpenAPI URL must use http:// or https:// protocol. Found: ${filePathOrUrl}`,
+          currentPath
+        );
+      }
+    } catch (error) {
+      throwConfigError(
+        `Invalid OpenAPI URL format: ${filePathOrUrl}`,
+        currentPath
+      );
+    }
+  }
+  try {
+    const document = await loadOpenApiSpec(filePathOrUrl);
+    const tolerantRuleset = {
+      ...oas,
+      rules: {
+        ...oas.rules,
+        "oas3-schema": {
+          ...oas.rules["oas3-schema"],
+          severity: 1
+        },
+        "oas2-schema": {
+          ...oas.rules["oas2-schema"],
+          severity: 1
+        }
+      }
+    };
+    const spectral = new Spectral();
+    spectral.setRuleset(tolerantRuleset);
+    let results = await spectral.run(document);
+    const blockingResults = results.filter(
+      (result) => result.code === "unrecognized-format"
+    );
+    if (blockingResults.length > 0) {
+      const errorMessages = blockingResults.slice(0, 5).map((result) => {
+        const pathStr = result.path.length > 0 ? result.path.join(".") : "root";
+        return `${result.message} (at ${pathStr})`;
+      });
+      const errorText = errorMessages.join("; ");
+      const moreErrors = blockingResults.length > 5 ? ` (and ${blockingResults.length - 5} more errors)` : "";
+      throwConfigError(
+        `Invalid OpenAPI specification: ${errorText}${moreErrors}`,
+        currentPath
+      );
+    }
+    const nonBlockingResults = results.filter(
+      (result) => result.severity !== 0
+    );
+    if (nonBlockingResults.length > 0) {
+      const warningMessages = nonBlockingResults.slice(0, 5).map((result) => {
+        const pathStr = result.path.length > 0 ? result.path.join(".") : "root";
+        return `${result.message} (at ${pathStr})`;
+      });
+      const warningText = warningMessages.join("; ");
+      const moreWarnings = nonBlockingResults.length > warningMessages.length ? ` (and ${nonBlockingResults.length - warningMessages.length} more warnings)` : "";
+      const sourcePath = currentPath.length > 0 ? ` (at: ${currentPath.join(".")})` : "";
+      console.warn(
+        `[OPENAPI_VALIDATION_WARNING] ${warningText}${moreWarnings}${sourcePath}`
+      );
+    }
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throwConfigError(
+        `Failed to parse OpenAPI file: ${error.message}`,
+        currentPath
+      );
+    } else if (error instanceof Error) {
+      const baseMessage = error.message || String(error);
+      const prefixedMessage = baseMessage.startsWith(
+        "Invalid OpenAPI specification:"
+      ) ? baseMessage : `Invalid OpenAPI specification: ${baseMessage}`;
+      throwConfigError(prefixedMessage, currentPath);
+    } else {
+      throwConfigError(
+        `Invalid OpenAPI specification: ${String(error)}`,
+        currentPath
+      );
+    }
+  }
+}
+function extractAvailableEndpoints(openApiDoc) {
+  const endpoints = /* @__PURE__ */ new Set();
+  const paths = openApiDoc.paths || {};
+  const httpMethods = [
+    "get",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "head",
+    "options",
+    "trace"
+  ];
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+    for (const method of httpMethods) {
+      const operation = pathItem[method];
+      if (operation) {
+        const normalizedMethod = method.toUpperCase();
+        const normalizedPath = pathStr.toLowerCase();
+        endpoints.add(`${normalizedMethod} ${normalizedPath}`);
+      }
+    }
+  }
+  return endpoints;
+}
+function parseEndpointString(endpointStr) {
+  const trimmed = endpointStr.trim();
+  const parts = trimmed.split(/\s+/);
+  if (parts.length !== 2) {
+    return null;
+  }
+  const method = parts[0].toUpperCase();
+  let path2 = parts[1];
+  if (!path2.startsWith("/")) {
+    path2 = "/" + path2;
+  }
+  const normalizedPath = path2.toLowerCase();
+  return { method, path: normalizedPath };
+}
+async function validateNavOpenApiPage(navOpenApiPage, currentPath) {
+  checkType(navOpenApiPage, "object", currentPath, "Open API page");
+  if (typeof navOpenApiPage.source !== "string") {
+    throwConfigError(
+      "Open API page must include a 'source' property that is a string.",
+      [...currentPath, "source"]
+    );
+  }
+  if (typeof navOpenApiPage.endpoint !== "string") {
+    throwConfigError(
+      `Open API page must include an 'endpoint' property that is a string in the format "METHOD /path".`,
+      [...currentPath, "endpoint"]
+    );
+  }
+  const parsedEndpoint = parseEndpointString(navOpenApiPage.endpoint);
+  if (!parsedEndpoint) {
+    throwConfigError(
+      `Open API page endpoint must be in the format "METHOD /path". Found: ${navOpenApiPage.endpoint}`,
+      [...currentPath, "endpoint"]
+    );
+  }
+  await validateOpenApiFile(navOpenApiPage.source, [...currentPath, "source"]);
+  const openApiDoc = await loadOpenApiSpec(navOpenApiPage.source);
+  const availableEndpoints = extractAvailableEndpoints(openApiDoc);
+  const endpointKey = `${parsedEndpoint.method} ${parsedEndpoint.path}`;
+  if (!availableEndpoints.has(endpointKey)) {
+    throwConfigError(
+      `Open API page endpoint does not match any endpoint in the OpenAPI spec. Found: ${navOpenApiPage.endpoint}. Expected format: "METHOD /path".`,
+      [...currentPath, "endpoint"]
+    );
+  }
+}
+async function validateNavigationNode(item, currentPath, groupDepth = 0) {
+  if (typeof item === "string") {
+    const normalizedPath = normalizeDocsPagePath(item, currentPath);
+    validateFileExistence(normalizedPath, currentPath);
+    return;
+  }
+  checkType(item, "object", currentPath, "Navigation item");
+  const isGroup = "group" in item;
+  const isPage = "page" in item;
+  const isOpenApiPage = "openapi" in item;
+  const typeCount = [isGroup, isPage, isOpenApiPage].filter(Boolean).length;
+  if (typeCount !== 1) {
+    throwConfigError(
+      "Object must contain exactly one key: 'page', 'group', or 'openapi'.",
+      currentPath
+    );
+  }
+  if (isGroup) {
+    const path2 = [...currentPath];
+    if (groupDepth >= 2) {
+      throwConfigError("Groups can only be nested up to 2 levels deep.", path2);
+    }
+    checkType(item.group, "string", [...path2, "group"], "Group name");
+    checkType(item.expanded, "boolean", [...path2, "expanded"], "Expanded");
+    validateIcon(item.icon, [...path2, "icon"]);
+    item.tag = normalizeNavTagConfig(item.tag, [...path2, "tag"], "Group tag");
+    if (!item.pages)
+      throwConfigError("Group must have a 'pages' array.", [...path2, "pages"]);
+    checkType(item.pages, "array", [...path2, "pages"], "Group pages");
+    for (const [i, child] of item.pages.entries()) {
+      if (typeof child === "string") {
+        const childPath = [...path2, "pages", i];
+        const normalizedPagePath = normalizeDocsPagePath(child, childPath);
+        item.pages[i] = normalizedPagePath;
+        validateFileExistence(normalizedPagePath, childPath);
+        continue;
+      }
+      await validateNavigationNode(
+        child,
+        [...path2, "pages", i],
+        groupDepth + 1
+      );
+    }
+    return;
+  }
+  if (isPage) {
+    const path2 = [...currentPath];
+    const normalizedPagePath = normalizeDocsPagePath(item.page, [
+      ...path2,
+      "page"
+    ]);
+    item.page = normalizedPagePath;
+    validateFileExistence(normalizedPagePath, [...path2, "page"]);
+    validateIcon(item.icon, [...path2, "icon"]);
+    checkType(item.title, "string", [...path2, "title"], "Page title");
+    item.tag = normalizeNavTagConfig(item.tag, [...path2, "tag"], "Page tag");
+    if ("expanded" in item)
+      throwConfigError("Page items cannot have 'expanded'.", [
+        ...path2,
+        "expanded"
+      ]);
+    if ("pages" in item)
+      throwConfigError("Page items cannot have children.", [...path2, "pages"]);
+    return;
+  }
+  if (isOpenApiPage) {
+    const path2 = [...currentPath];
+    if ("icon" in item) {
+      throwConfigError(
+        "Open API page items cannot have an 'icon'. Method badges are displayed automatically.",
+        [...path2, "icon"]
+      );
+    }
+    await validateNavOpenApiPage(item.openapi, [...path2, "openapi"]);
+    checkType(item.title, "string", [...path2, "title"], "Open API page title");
+    item.tag = normalizeNavTagConfig(
+      item.tag,
+      [...path2, "tag"],
+      "Open API page tag"
+    );
+    if ("expanded" in item)
+      throwConfigError("Open API page items cannot have 'expanded'.", [
+        ...path2,
+        "expanded"
+      ]);
+    if ("pages" in item)
+      throwConfigError("Open API page items cannot have children.", [
+        ...path2,
+        "pages"
+      ]);
+    if ("group" in item)
+      throwConfigError("Open API page items cannot have 'group'.", [
+        ...path2,
+        "group"
+      ]);
+    if ("page" in item)
+      throwConfigError("Open API page items cannot have 'page'.", [
+        ...path2,
+        "page"
+      ]);
+    return;
+  }
+}
+function getFirstPagePathFromPageItems(items) {
+  for (const item of items) {
+    if (typeof item === "string") {
+      return item;
+    }
+    if ("page" in item) {
+      return item.page;
+    }
+    if ("group" in item) {
+      const nestedPath = getFirstPagePathFromPageItems(item.pages);
+      if (nestedPath) {
+        return nestedPath;
+      }
+    }
+  }
+  return void 0;
+}
+function getFirstPagePathFromNavigation(navigation) {
+  if (navigation.pages) {
+    return getFirstPagePathFromPageItems(navigation.pages);
+  }
+  if (navigation.menu) {
+    for (const menuItem of navigation.menu.items) {
+      const submenuPages = menuItem.submenu.pages;
+      if (!submenuPages) {
+        continue;
+      }
+      const firstPath = getFirstPagePathFromPageItems(submenuPages);
+      if (firstPath) {
+        return firstPath;
+      }
+    }
+  }
+  return void 0;
+}
+async function validateNavOpenApi(navOpenApi, currentPath) {
+  checkType(navOpenApi, "object", currentPath, "Open API object");
+  if (typeof navOpenApi.source !== "string") {
+    throwConfigError(
+      "Open API object must have an 'source' property that is a string.",
+      [...currentPath, "source"]
+    );
+  }
+  await validateOpenApiFile(navOpenApi.source, [...currentPath, "source"]);
+  const hasInclude = "include" in navOpenApi;
+  const hasExclude = "exclude" in navOpenApi;
+  if (hasInclude && hasExclude) {
+    throwConfigError(
+      "Open API object cannot have both 'include' and 'exclude' properties. They are mutually exclusive.",
+      currentPath
+    );
+  }
+  if (!hasInclude && !hasExclude) {
+    return;
+  }
+  const openApiDoc = await loadOpenApiSpec(navOpenApi.source);
+  const availableEndpoints = extractAvailableEndpoints(openApiDoc);
+  if (hasInclude) {
+    checkType(
+      navOpenApi.include,
+      "array",
+      [...currentPath, "include"],
+      "Include array"
+    );
+    if (navOpenApi.include.length === 0) {
+      throwConfigError("Include array cannot be empty.", [
+        ...currentPath,
+        "include"
+      ]);
+    }
+    for (const [i, entry] of navOpenApi.include.entries()) {
+      if (typeof entry !== "string") {
+        throwConfigError(
+          `Include entry at index ${i} must be a string in the format "METHOD /path".`,
+          [...currentPath, "include", i]
+        );
+      }
+      const parsed = parseEndpointString(entry);
+      if (!parsed) {
+        throwConfigError(
+          `Include entry at index ${i} must be in the format "METHOD /path". Found: ${entry}`,
+          [...currentPath, "include", i]
+        );
+      }
+      const endpointKey = `${parsed?.method} ${parsed?.path}`;
+      if (!availableEndpoints.has(endpointKey)) {
+        throwConfigError(
+          `Include entry at index ${i} does not match any endpoint in the OpenAPI spec. Found: ${entry}. Expected format: "METHOD /path".`,
+          [...currentPath, "include", i]
+        );
+      }
+    }
+  }
+  if (hasExclude) {
+    checkType(
+      navOpenApi.exclude,
+      "array",
+      [...currentPath, "exclude"],
+      "Exclude array"
+    );
+    if (navOpenApi.exclude.length === 0) {
+      throwConfigError("Exclude array cannot be empty.", [
+        ...currentPath,
+        "exclude"
+      ]);
+    }
+    for (const [i, entry] of navOpenApi.exclude.entries()) {
+      if (typeof entry !== "string") {
+        throwConfigError(
+          `Exclude entry at index ${i} must be a string in the format "METHOD /path".`,
+          [...currentPath, "exclude", i]
+        );
+      }
+      const parsed = parseEndpointString(entry);
+      if (!parsed) {
+        throwConfigError(
+          `Exclude entry at index ${i} must be in the format "METHOD /path" (e.g., "get /burgers"). Found: ${entry}`,
+          [...currentPath, "exclude", i]
+        );
+      }
+      const endpointKey = `${parsed?.method} ${parsed?.path}`;
+      if (!availableEndpoints.has(endpointKey)) {
+        throwConfigError(
+          `Exclude entry at index ${i} does not match any endpoint in the OpenAPI spec. Found: ${entry}. Expected format: "METHOD /path" (case-insensitive).`,
+          [...currentPath, "exclude", i]
+        );
+      }
+    }
+  }
+}
+async function validateNavMenuItem(item, currentPath) {
+  checkType(item, "object", currentPath, "Menu item");
+  validateIcon(item.icon, [...currentPath, "icon"]);
+  if (!item.label) {
+    throwConfigError("Menu item must have a 'label' property.", [
+      ...currentPath,
+      "label"
+    ]);
+  }
+  checkType(item.label, "string", [...currentPath, "label"], "Label");
+  if (!item.submenu) {
+    throwConfigError("Menu item must have a 'submenu' property.", [
+      ...currentPath,
+      "submenu"
+    ]);
+  }
+  checkType(item.submenu, "object", [...currentPath, "submenu"], "Submenu");
+  const submenu = item.submenu;
+  const submenuKeys = Object.keys(submenu);
+  const validSubmenuKeys = ["pages", "openapi"];
+  const presentSubmenuKeys = submenuKeys.filter(
+    (key) => validSubmenuKeys.includes(key)
+  );
+  const invalidSubmenuKeys = submenuKeys.filter(
+    (key) => !validSubmenuKeys.includes(key)
+  );
+  if (submenuKeys.length !== 1) {
+    if (submenuKeys.length === 0) {
+      throwConfigError(
+        `Submenu must contain exactly one key (${validSubmenuKeys.join(
+          ", "
+        )}). Found no keys.`,
+        [...currentPath, "submenu"]
+      );
+    } else {
+      throwConfigError(
+        `Submenu must contain exactly one key (${validSubmenuKeys.join(
+          ", "
+        )}). Found ${submenuKeys.length} key(s): ${submenuKeys.join(", ")}.`,
+        [...currentPath, "submenu"]
+      );
+    }
+  }
+  if (presentSubmenuKeys.length !== 1) {
+    const invalidKey = invalidSubmenuKeys[0];
+    throwConfigError(
+      `Submenu must contain exactly one key (${validSubmenuKeys.join(
+        ", "
+      )}). Found invalid key: ${invalidKey}.`,
+      [...currentPath, "submenu"]
+    );
+  }
+  const submenuKey = presentSubmenuKeys[0];
+  const submenuValue = submenu[submenuKey];
+  if (submenuKey === "pages") {
+    checkType(
+      submenuValue,
+      "array",
+      [...currentPath, "submenu", "pages"],
+      "Submenu pages"
+    );
+    const pages = submenuValue ?? [];
+    for (const [i, item2] of pages.entries()) {
+      const itemPath = [...currentPath, "submenu", "pages", i];
+      if (typeof item2 === "string") {
+        const normalizedPagePath = normalizeDocsPagePath(item2, itemPath);
+        submenuValue[i] = normalizedPagePath;
+        validateFileExistence(normalizedPagePath, itemPath);
+      } else {
+        await validateNavigationNode(item2, itemPath);
+      }
+    }
+  }
+  if (submenuKey === "openapi") {
+    if (typeof submenuValue === "string") {
+      await validateOpenApiFile(submenuValue, [
+        ...currentPath,
+        "submenu",
+        "openapi"
+      ]);
+    } else if (typeof submenuValue === "object") {
+      await validateNavOpenApi(submenuValue, [
+        ...currentPath,
+        "submenu",
+        "openapi"
+      ]);
+    } else {
+      throwConfigError(
+        "OpenAPI must be either a string (file path or hosted file) or an object.",
+        [...currentPath, "submenu", "openapi"]
+      );
+    }
+  }
+}
+async function validateNavMenu(menu, currentPath) {
+  checkType(menu, "object", currentPath, "Menu");
+  if (menu.type !== void 0) {
+    if (menu.type !== "dropdown" && menu.type !== "segmented") {
+      throwConfigError(
+        "Menu type must be 'dropdown' or 'segmented' if provided. Defaults to 'dropdown'",
+        [...currentPath, "type"]
+      );
+    }
+  }
+  checkType(menu.label, "string", [...currentPath, "label"], "Menu label");
+  if (!menu.items) {
+    throwConfigError("Menu must have an 'items' array.", [
+      ...currentPath,
+      "items"
+    ]);
+  }
+  checkType(menu.items, "array", [...currentPath, "items"], "Menu items");
+  for (const [i, item] of menu.items.entries()) {
+    await validateNavMenuItem(item, [...currentPath, "items", i]);
+  }
+}
+function validateNavbarItem(item, currentPath) {
+  if (item === void 0) return null;
+  checkType(item, "object", currentPath, "Navbar item");
+  if (typeof item.text !== "string") {
+    throwConfigError("Navbar item must have a 'text' property.", [
+      ...currentPath,
+      "text"
+    ]);
+  }
+  if (typeof item.href !== "string") {
+    throwConfigError("Navbar item must have an 'href' property.", [
+      ...currentPath,
+      "href"
+    ]);
+  }
+  const hiddenPageRoute = normalizeInternalPageHref(
+    item.href,
+    [...currentPath, "href"],
+    "Navbar item href"
+  );
+  if (hiddenPageRoute) {
+    item.href = hiddenPageRoute.linkHref;
+  }
+  validateIcon(item.icon, [...currentPath, "icon"]);
+  if (item.color !== void 0) {
+    if (currentPath[0] !== "navbar" || currentPath[1] !== "primary") {
+      throwConfigError(
+        "Navbar item color is only supported on navbar.primary.",
+        [...currentPath, "color"]
+      );
+    }
+    item.color = normalizeThemeColorConfig(
+      item.color,
+      [...currentPath, "color"],
+      "Navbar primary color"
+    );
+  }
+  return hiddenPageRoute;
+}
+function validateTitle(title) {
+  checkType(title, "string", ["title"], "Title");
+  if (!title) throwConfigError("Title is missing.", ["title"]);
+}
+function validateLogoPaddingValue(value, currentPath, label) {
+  if (value === void 0) return;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throwConfigError(`${label} must be a finite number.`, currentPath);
+  }
+  const numericValue = value;
+  if (numericValue < 0) {
+    throwConfigError(`${label} cannot be negative.`, currentPath);
+  }
+}
+function validateLogoImagePath(imagePath, currentPath, label) {
+  const validExtensions = [".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif"];
+  const hasValidExtension = validExtensions.some(
+    (ext) => imagePath.toLowerCase().endsWith(ext)
+  );
+  if (!hasValidExtension) {
+    throwConfigError(
+      `${label} must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif)`,
+      currentPath
+    );
+  }
+  const normalizedPath = imagePath.startsWith("/") ? imagePath.slice(1) : imagePath;
+  const fullPath = path.join(DOCS_DIR, normalizedPath);
+  if (!fs.existsSync(fullPath)) {
+    throwConfigError(
+      `${label} file not found. Expected: ${normalizedPath}`,
+      currentPath
+    );
+  }
+}
+function validateAssistantIconSource(iconSource, currentPath) {
+  checkType(iconSource, "string", currentPath, "Assistant icon source");
+  if (typeof iconSource !== "string") {
+    throwConfigError("Assistant icon source must be a string.", currentPath);
+  }
+  const trimmedSource = iconSource.trim();
+  if (trimmedSource.length === 0) {
+    throwConfigError("Assistant icon source cannot be empty.", currentPath);
+  }
+  if (isUrl(trimmedSource)) {
+    throwConfigError(
+      "Assistant icon source must be a local image path relative to docs.json.",
+      currentPath
+    );
+  }
+  if (trimmedSource.includes(":")) {
+    throwConfigError(
+      `Invalid assistant icon source: "${trimmedSource}". Assistant icons must be local image files, not Iconify icon names.`,
+      currentPath
+    );
+  }
+  if (trimmedSource.startsWith("//") || trimmedSource.startsWith("#") || trimmedSource.startsWith("?") || trimmedSource.startsWith("./") || trimmedSource.startsWith("../")) {
+    throwConfigError(
+      "Assistant icon source must be a local image path relative to docs.json.",
+      currentPath
+    );
+  }
+  const parsed = new URL(trimmedSource, "https://docs.invalid/");
+  const validExtensions = [
+    ".svg",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".gif",
+    ".ico",
+    ".avif"
+  ];
+  const hasValidExtension = validExtensions.some(
+    (ext) => parsed.pathname.toLowerCase().endsWith(ext)
+  );
+  if (!hasValidExtension) {
+    throwConfigError(
+      "Assistant icon source must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif, .ico, .avif).",
+      currentPath
+    );
+  }
+  const normalizedPath = parsed.pathname.replace(/^\/+/, "");
+  const fullPath = path.join(DOCS_DIR, normalizedPath);
+  if (!fs.existsSync(fullPath)) {
+    throwConfigError(
+      `Assistant icon source file not found. Expected: ${normalizedPath}`,
+      currentPath
+    );
+  }
+  return trimmedSource;
+}
+function validateLogoVariant(variant, currentPath, mode) {
+  if (variant === void 0) return;
+  if (typeof variant === "string") {
+    validateLogoImagePath(variant, currentPath, `Logo ${mode}`);
+    return;
+  }
+  if (typeof variant !== "object" || variant === null || Array.isArray(variant)) {
+    throwConfigError(
+      `Logo ${mode} must be a string path or an object with 'image' and optional 'padding'.`,
+      currentPath
+    );
+  }
+  const supportedKeys = /* @__PURE__ */ new Set(["image", "padding"]);
+  for (const key of Object.keys(variant)) {
+    if (!supportedKeys.has(key)) {
+      throwConfigError(
+        `Logo ${mode} object only supports 'image' and 'padding'.`,
+        [...currentPath, key]
+      );
+    }
+  }
+  if (typeof variant.image !== "string") {
+    throwConfigError(`Logo ${mode} object must include an 'image' string.`, [
+      ...currentPath,
+      "image"
+    ]);
+  }
+  validateLogoImagePath(
+    variant.image,
+    [...currentPath, "image"],
+    `Logo ${mode} image`
+  );
+  if (variant.padding === void 0) return;
+  if (typeof variant.padding !== "object" || variant.padding === null || Array.isArray(variant.padding)) {
+    throwConfigError(
+      `Logo ${mode} padding must be an object with optional 'top' and 'bottom'.`,
+      [...currentPath, "padding"]
+    );
+  }
+  const paddingKeys = Object.keys(variant.padding);
+  for (const key of paddingKeys) {
+    if (key !== "top" && key !== "bottom") {
+      throwConfigError(
+        `Logo ${mode} padding only supports 'top' and 'bottom'.`,
+        [...currentPath, "padding", key]
+      );
+    }
+  }
+  validateLogoPaddingValue(
+    variant.padding.top,
+    [...currentPath, "padding", "top"],
+    `Logo ${mode} padding top`
+  );
+  validateLogoPaddingValue(
+    variant.padding.bottom,
+    [...currentPath, "padding", "bottom"],
+    `Logo ${mode} padding bottom`
+  );
+}
+function validateLogo(logo) {
+  if (logo === void 0) return;
+  checkType(logo, "object", ["logo"], "Logo configuration");
+  validateLogoVariant(logo.light, ["logo", "light"], "light");
+  validateLogoVariant(logo.dark, ["logo", "dark"], "dark");
+  if (logo.href !== void 0) {
+    checkType(logo.href, "string", ["logo", "href"], "Logo href");
+    const trimmedHref = logo.href.trim();
+    if (trimmedHref === "") {
+      throwConfigError("Logo href cannot be an empty string", ["logo", "href"]);
+    }
+    const isUrl2 = trimmedHref.startsWith("http://") || trimmedHref.startsWith("https://");
+    const isInternalPath = trimmedHref.startsWith("/");
+    if (!isUrl2 && !isInternalPath) {
+      throwConfigError(
+        "Logo href must be either a valid URL (http:// or https://) or an internal path (starting with /)",
+        ["logo", "href"]
+      );
+    }
+  }
+  if (logo.pill !== void 0) {
+    if (typeof logo.pill === "string") {
+      if (logo.pill.trim() === "") {
+        throwConfigError(
+          "Logo pill text cannot be an empty string. Use false to hide the pill.",
+          ["logo", "pill"]
+        );
+      }
+    } else if (logo.pill !== false) {
+      throwConfigError("Logo pill must be a string or false.", [
+        "logo",
+        "pill"
+      ]);
+    }
+  }
+}
+function validateTheme(theme) {
+  if (theme === void 0) return;
+  checkType(theme, "object", ["theme"], "Theme configuration");
+  if (typeof theme !== "object" || theme === null || Array.isArray(theme)) {
+    throwConfigError("Theme configuration must be an object.", ["theme"]);
+  }
+  const normalizeBaseColor = (value, currentPath, label) => {
+    checkType(value, "string", currentPath, label);
+    if (typeof value !== "string") {
+      throwConfigError(`${label} must be a string.`, currentPath);
+    }
+    const normalizedBaseColor = value.trim().toLowerCase();
+    if (normalizedBaseColor.length === 0) {
+      throwConfigError(`${label} cannot be empty.`, currentPath);
+    }
+    if (!BASE_COLOR_OPTIONS.includes(normalizedBaseColor)) {
+      throwConfigError(
+        `${label} must be one of: ${BASE_COLOR_OPTIONS.join(", ")}.`,
+        currentPath
+      );
+    }
+    return normalizedBaseColor;
+  };
+  if (theme.baseColor !== void 0) {
+    if (typeof theme.baseColor === "string") {
+      theme.baseColor = normalizeBaseColor(
+        theme.baseColor,
+        ["theme", "baseColor"],
+        "Theme base color"
+      );
+    } else {
+      checkType(
+        theme.baseColor,
+        "object",
+        ["theme", "baseColor"],
+        "Theme base color"
+      );
+      if (typeof theme.baseColor !== "object" || theme.baseColor === null || Array.isArray(theme.baseColor)) {
+        throwConfigError(
+          "Theme base color must be a string or an object with light/dark values.",
+          ["theme", "baseColor"]
+        );
+      }
+      const baseColorByMode = theme.baseColor;
+      const allowedKeys2 = /* @__PURE__ */ new Set(["light", "dark"]);
+      for (const key of Object.keys(baseColorByMode)) {
+        if (!allowedKeys2.has(key)) {
+          throwConfigError(
+            "Theme base color object only supports 'light' and 'dark'.",
+            ["theme", "baseColor", key]
+          );
+        }
+      }
+      const light2 = baseColorByMode.light !== void 0 ? normalizeBaseColor(
+        baseColorByMode.light,
+        ["theme", "baseColor", "light"],
+        "Theme base color light"
+      ) : void 0;
+      const dark2 = baseColorByMode.dark !== void 0 ? normalizeBaseColor(
+        baseColorByMode.dark,
+        ["theme", "baseColor", "dark"],
+        "Theme base color dark"
+      ) : void 0;
+      if (!light2 && !dark2) {
+        throwConfigError(
+          "Theme base color object must include 'light', 'dark', or both.",
+          ["theme", "baseColor"]
+        );
+      }
+      const resolvedLight = light2 ?? "neutral";
+      const resolvedDark = dark2 ?? "neutral";
+      theme.baseColor = {
+        light: resolvedLight,
+        dark: resolvedDark
+      };
+    }
+  }
+  const normalizeShikiThemeName = (value, currentPath, label) => {
+    checkType(value, "string", currentPath, label);
+    if (typeof value !== "string") {
+      throwConfigError(`${label} must be a string.`, currentPath);
+    }
+    const normalizedThemeName = value.trim().toLowerCase();
+    if (normalizedThemeName.length === 0) {
+      throwConfigError(`${label} cannot be empty.`, currentPath);
+    }
+    if (!isBundledShikiThemeName(normalizedThemeName)) {
+      throwConfigError(
+        `${label} must be a bundled Shiki theme name. Supported themes include: ${SHIKI_BUNDLED_THEME_NAMES.join(", ")}.`,
+        currentPath
+      );
+    }
+    return normalizedThemeName;
+  };
+  if (theme.code !== void 0) {
+    checkType(theme.code, "object", ["theme", "code"], "Theme code");
+    if (typeof theme.code !== "object" || theme.code === null || Array.isArray(theme.code)) {
+      throwConfigError("Theme code must be an object.", ["theme", "code"]);
+    }
+    const codeTheme = theme.code;
+    const allowedCodeKeys = /* @__PURE__ */ new Set(["syntaxTheme"]);
+    for (const key of Object.keys(codeTheme)) {
+      if (!allowedCodeKeys.has(key)) {
+        throwConfigError(
+          "Theme code configuration only supports 'syntaxTheme'.",
+          ["theme", "code", key]
+        );
+      }
+    }
+    if (codeTheme.syntaxTheme !== void 0) {
+      if (typeof codeTheme.syntaxTheme === "string") {
+        const themeName = normalizeShikiThemeName(
+          codeTheme.syntaxTheme,
+          ["theme", "code", "syntaxTheme"],
+          "Theme code syntax theme"
+        );
+        codeTheme.syntaxTheme = {
+          light: themeName,
+          dark: themeName
+        };
+      } else {
+        checkType(
+          codeTheme.syntaxTheme,
+          "object",
+          ["theme", "code", "syntaxTheme"],
+          "Theme code syntax theme"
+        );
+        if (typeof codeTheme.syntaxTheme !== "object" || codeTheme.syntaxTheme === null || Array.isArray(codeTheme.syntaxTheme)) {
+          throwConfigError(
+            "Theme code syntax theme must be a string or an object with light/dark values.",
+            ["theme", "code", "syntaxTheme"]
+          );
+        }
+        const syntaxThemeByMode = codeTheme.syntaxTheme;
+        const allowedSyntaxThemeKeys = /* @__PURE__ */ new Set(["light", "dark"]);
+        for (const key of Object.keys(syntaxThemeByMode)) {
+          if (!allowedSyntaxThemeKeys.has(key)) {
+            throwConfigError(
+              "Theme code syntax theme object only supports 'light' and 'dark'.",
+              ["theme", "code", "syntaxTheme", key]
+            );
+          }
+        }
+        const light2 = syntaxThemeByMode.light !== void 0 ? normalizeShikiThemeName(
+          syntaxThemeByMode.light,
+          ["theme", "code", "syntaxTheme", "light"],
+          "Theme code syntax theme light"
+        ) : void 0;
+        const dark2 = syntaxThemeByMode.dark !== void 0 ? normalizeShikiThemeName(
+          syntaxThemeByMode.dark,
+          ["theme", "code", "syntaxTheme", "dark"],
+          "Theme code syntax theme dark"
+        ) : void 0;
+        if (!light2 && !dark2) {
+          throwConfigError(
+            "Theme code syntax theme object must include 'light', 'dark', or both.",
+            ["theme", "code", "syntaxTheme"]
+          );
+        }
+        codeTheme.syntaxTheme = {
+          light: light2 ?? DEFAULT_SHIKI_LIGHT_THEME,
+          dark: dark2 ?? DEFAULT_SHIKI_DARK_THEME
+        };
+      }
+    }
+  }
+  if (theme.tag !== void 0) {
+    checkType(theme.tag, "object", ["theme", "tag"], "Theme tag");
+    if (typeof theme.tag !== "object" || theme.tag === null || Array.isArray(theme.tag)) {
+      throwConfigError("Theme tag must be an object.", ["theme", "tag"]);
+    }
+    const tagTheme = theme.tag;
+    const allowedTagKeys = /* @__PURE__ */ new Set(["color"]);
+    for (const key of Object.keys(tagTheme)) {
+      if (!allowedTagKeys.has(key)) {
+        throwConfigError("Theme tag configuration only supports 'color'.", [
+          "theme",
+          "tag",
+          key
+        ]);
+      }
+    }
+    if (tagTheme.color !== void 0) {
+      tagTheme.color = normalizeThemeColorConfig(
+        tagTheme.color,
+        ["theme", "tag", "color"],
+        "Theme tag color"
+      );
+    }
+  }
+  if (theme.card !== void 0) {
+    checkType(theme.card, "object", ["theme", "card"], "Theme card");
+    if (typeof theme.card !== "object" || theme.card === null || Array.isArray(theme.card)) {
+      throwConfigError("Theme card must be an object.", ["theme", "card"]);
+    }
+    const cardTheme = theme.card;
+    const allowedCardKeys = /* @__PURE__ */ new Set(["cover", "button"]);
+    for (const key of Object.keys(cardTheme)) {
+      if (!allowedCardKeys.has(key)) {
+        throwConfigError(
+          "Theme card configuration only supports 'cover' and 'button'.",
+          ["theme", "card", key]
+        );
+      }
+    }
+    if (cardTheme.cover !== void 0) {
+      checkType(
+        cardTheme.cover,
+        "object",
+        ["theme", "card", "cover"],
+        "Theme card cover"
+      );
+      if (typeof cardTheme.cover !== "object" || cardTheme.cover === null || Array.isArray(cardTheme.cover)) {
+        throwConfigError("Theme card cover must be an object.", [
+          "theme",
+          "card",
+          "cover"
+        ]);
+      }
+      const coverTheme = cardTheme.cover;
+      const allowedCoverKeys = /* @__PURE__ */ new Set(["colors", "colorSeed"]);
+      for (const key of Object.keys(coverTheme)) {
+        if (!allowedCoverKeys.has(key)) {
+          throwConfigError(
+            "Theme card cover configuration only supports 'colors' and 'colorSeed'.",
+            ["theme", "card", "cover", key]
+          );
+        }
+      }
+      if (coverTheme.colors !== void 0) {
+        coverTheme.colors = normalizeHexColorArray(
+          coverTheme.colors,
+          ["theme", "card", "cover", "colors"],
+          "Theme card cover colors"
+        );
+      }
+      if (coverTheme.colorSeed !== void 0) {
+        coverTheme.colorSeed = normalizeSeedValue(
+          coverTheme.colorSeed,
+          ["theme", "card", "cover", "colorSeed"],
+          "Theme card cover color seed"
+        );
+      }
+    }
+    if (cardTheme.button !== void 0) {
+      checkType(
+        cardTheme.button,
+        "object",
+        ["theme", "card", "button"],
+        "Theme card button"
+      );
+      if (typeof cardTheme.button !== "object" || cardTheme.button === null || Array.isArray(cardTheme.button)) {
+        throwConfigError("Theme card button must be an object.", [
+          "theme",
+          "card",
+          "button"
+        ]);
+      }
+      const buttonTheme = cardTheme.button;
+      const allowedButtonKeys = /* @__PURE__ */ new Set(["color"]);
+      for (const key of Object.keys(buttonTheme)) {
+        if (!allowedButtonKeys.has(key)) {
+          throwConfigError(
+            "Theme card button configuration only supports 'color'.",
+            ["theme", "card", "button", key]
+          );
+        }
+      }
+      if (buttonTheme.color !== void 0) {
+        buttonTheme.color = normalizeThemeColorConfig(
+          buttonTheme.color,
+          ["theme", "card", "button", "color"],
+          "Theme card button color"
+        );
+      }
+    }
+  }
+  if (theme.themeColor === void 0) {
+    return;
+  }
+  if (typeof theme.themeColor === "string") {
+    theme.themeColor = normalizeHexColor(
+      theme.themeColor,
+      ["theme", "themeColor"],
+      "Theme color"
+    );
+    return;
+  }
+  checkType(theme.themeColor, "object", ["theme", "themeColor"], "Theme color");
+  if (typeof theme.themeColor !== "object" || theme.themeColor === null || Array.isArray(theme.themeColor)) {
+    throwConfigError(
+      "Theme color must be a string or an object with light/dark values.",
+      ["theme", "themeColor"]
+    );
+  }
+  const themeColorByMode = theme.themeColor;
+  const allowedKeys = /* @__PURE__ */ new Set(["light", "dark"]);
+  for (const key of Object.keys(themeColorByMode)) {
+    if (!allowedKeys.has(key)) {
+      throwConfigError("Theme color object only supports 'light' and 'dark'.", [
+        "theme",
+        "themeColor",
+        key
+      ]);
+    }
+  }
+  const light = themeColorByMode.light !== void 0 ? normalizeHexColor(
+    themeColorByMode.light,
+    ["theme", "themeColor", "light"],
+    "Theme color light"
+  ) : void 0;
+  const dark = themeColorByMode.dark !== void 0 ? normalizeHexColor(
+    themeColorByMode.dark,
+    ["theme", "themeColor", "dark"],
+    "Theme color dark"
+  ) : void 0;
+  if (!light && !dark) {
+    throwConfigError(
+      "Theme color object must include 'light', 'dark', or both.",
+      ["theme", "themeColor"]
+    );
+  }
+  theme.themeColor = {
+    ...light !== void 0 ? { light } : {},
+    ...dark !== void 0 ? { dark } : {}
+  };
+}
+function validateAssistant(assistant) {
+  if (assistant === void 0) return;
+  checkType(assistant, "object", ["assistant"], "Assistant configuration");
+  if (typeof assistant !== "object" || assistant === null || Array.isArray(assistant)) {
+    throwConfigError("Assistant configuration must be an object.", [
+      "assistant"
+    ]);
+  }
+  const allowedAssistantKeys = /* @__PURE__ */ new Set([
+    "button",
+    "navbarButton",
+    "heading",
+    "questions",
+    "icon"
+  ]);
+  for (const key of Object.keys(assistant)) {
+    if (!allowedAssistantKeys.has(key)) {
+      throwConfigError(
+        "Assistant configuration only supports 'button', 'navbarButton', 'heading', 'questions', and 'icon'.",
+        ["assistant", key]
+      );
+    }
+  }
+  if (assistant.button !== void 0) {
+    checkType(
+      assistant.button,
+      "object",
+      ["assistant", "button"],
+      "Assistant button configuration"
+    );
+    if (typeof assistant.button !== "object" || assistant.button === null || Array.isArray(assistant.button)) {
+      throwConfigError("Assistant button configuration must be an object.", [
+        "assistant",
+        "button"
+      ]);
+    }
+    const allowedButtonKeys = /* @__PURE__ */ new Set(["size", "color"]);
+    for (const key of Object.keys(assistant.button)) {
+      if (!allowedButtonKeys.has(key)) {
+        throwConfigError(
+          "Assistant button configuration only supports 'size' and 'color'.",
+          ["assistant", "button", key]
+        );
+      }
+    }
+    if (assistant.button.size !== void 0) {
+      checkType(
+        assistant.button.size,
+        "string",
+        ["assistant", "button", "size"],
+        "Assistant button size"
+      );
+      if (typeof assistant.button.size !== "string") {
+        throwConfigError("Assistant button size must be a string.", [
+          "assistant",
+          "button",
+          "size"
+        ]);
+      }
+      const trimmedSize = assistant.button.size.trim();
+      if (trimmedSize !== "small" && trimmedSize !== "default") {
+        throwConfigError(
+          "Assistant button size must be either 'small' or 'default'.",
+          ["assistant", "button", "size"]
+        );
+      }
+      assistant.button.size = trimmedSize;
+    }
+    if (assistant.button.color !== void 0) {
+      assistant.button.color = normalizeThemeColorConfig(
+        assistant.button.color,
+        ["assistant", "button", "color"],
+        "Assistant button color"
+      );
+    }
+  }
+  if (assistant.navbarButton !== void 0) {
+    checkType(
+      assistant.navbarButton,
+      "object",
+      ["assistant", "navbarButton"],
+      "Assistant navbar button configuration"
+    );
+    if (typeof assistant.navbarButton !== "object" || assistant.navbarButton === null || Array.isArray(assistant.navbarButton)) {
+      throwConfigError(
+        "Assistant navbar button configuration must be an object.",
+        ["assistant", "navbarButton"]
+      );
+    }
+    const allowedNavbarButtonKeys = /* @__PURE__ */ new Set(["enabled", "text", "color"]);
+    for (const key of Object.keys(assistant.navbarButton)) {
+      if (!allowedNavbarButtonKeys.has(key)) {
+        throwConfigError(
+          "Assistant navbar button configuration only supports 'enabled', 'text', and 'color'.",
+          ["assistant", "navbarButton", key]
+        );
+      }
+    }
+    if (assistant.navbarButton.enabled !== void 0) {
+      checkType(
+        assistant.navbarButton.enabled,
+        "boolean",
+        ["assistant", "navbarButton", "enabled"],
+        "Assistant navbar button enabled"
+      );
+      if (typeof assistant.navbarButton.enabled !== "boolean") {
+        throwConfigError(
+          "Assistant navbar button enabled must be a boolean.",
+          ["assistant", "navbarButton", "enabled"]
+        );
+      }
+    }
+    if (assistant.navbarButton.text !== void 0) {
+      checkType(
+        assistant.navbarButton.text,
+        "string",
+        ["assistant", "navbarButton", "text"],
+        "Assistant navbar button text"
+      );
+      if (typeof assistant.navbarButton.text !== "string") {
+        throwConfigError("Assistant navbar button text must be a string.", [
+          "assistant",
+          "navbarButton",
+          "text"
+        ]);
+      }
+      const trimmedText = assistant.navbarButton.text.trim();
+      if (trimmedText.length === 0) {
+        throwConfigError("Assistant navbar button text cannot be empty.", [
+          "assistant",
+          "navbarButton",
+          "text"
+        ]);
+      }
+      assistant.navbarButton.text = trimmedText;
+    }
+    if (assistant.navbarButton.color !== void 0) {
+      assistant.navbarButton.color = normalizeThemeColorConfig(
+        assistant.navbarButton.color,
+        ["assistant", "navbarButton", "color"],
+        "Assistant navbar button color"
+      );
+    }
+  }
+  if (assistant.heading !== void 0) {
+    checkType(
+      assistant.heading,
+      "string",
+      ["assistant", "heading"],
+      "Assistant heading"
+    );
+    if (typeof assistant.heading !== "string") {
+      throwConfigError("Assistant heading must be a string.", [
+        "assistant",
+        "heading"
+      ]);
+    }
+    const trimmedHeading = assistant.heading.trim();
+    if (trimmedHeading.length === 0) {
+      throwConfigError("Assistant heading cannot be empty.", [
+        "assistant",
+        "heading"
+      ]);
+    }
+    assistant.heading = trimmedHeading;
+  }
+  if (assistant.questions !== void 0) {
+    checkType(
+      assistant.questions,
+      "array",
+      ["assistant", "questions"],
+      "Assistant questions"
+    );
+    if (!Array.isArray(assistant.questions)) {
+      throwConfigError("Assistant questions must be an array.", [
+        "assistant",
+        "questions"
+      ]);
+    }
+    if (assistant.questions.length > 3) {
+      throwConfigError("Assistant questions can include at most 3 questions.", [
+        "assistant",
+        "questions"
+      ]);
+    }
+    assistant.questions = assistant.questions.map((question, index) => {
+      checkType(
+        question,
+        "string",
+        ["assistant", "questions", String(index)],
+        "Assistant question"
+      );
+      if (typeof question !== "string") {
+        throwConfigError("Assistant question must be a string.", [
+          "assistant",
+          "questions",
+          String(index)
+        ]);
+      }
+      const trimmedQuestion = question.trim();
+      if (trimmedQuestion.length === 0) {
+        throwConfigError(
+          "Assistant question cannot be empty.",
+          ["assistant", "questions", String(index)]
+        );
+      }
+      return trimmedQuestion;
+    });
+  }
+  if (assistant.icon === void 0) return;
+  checkType(
+    assistant.icon,
+    "object",
+    ["assistant", "icon"],
+    "Assistant icon"
+  );
+  if (typeof assistant.icon !== "object" || assistant.icon === null || Array.isArray(assistant.icon)) {
+    throwConfigError("Assistant icon must be an object.", [
+      "assistant",
+      "icon"
+    ]);
+  }
+  const allowedIconKeys = /* @__PURE__ */ new Set(["src"]);
+  for (const key of Object.keys(assistant.icon)) {
+    if (!allowedIconKeys.has(key)) {
+      throwConfigError(
+        "Assistant icon only supports 'src'.",
+        ["assistant", "icon", key]
+      );
+    }
+  }
+  if (assistant.icon.src === void 0) {
+    throwConfigError(
+      "Assistant icon must include 'src'.",
+      ["assistant", "icon"]
+    );
+  }
+  if (assistant.icon.src !== void 0) {
+    assistant.icon.src = validateAssistantIconSource(
+      assistant.icon.src,
+      ["assistant", "icon", "src"]
+    );
+  }
+}
+function validateHome(home) {
+  if (home === void 0) return void 0;
+  const normalizedHome = normalizeDocsPagePath(home, ["home"], "Home path");
+  validateFileExistence(normalizedHome, ["home"]);
+  return normalizedHome;
+}
+function validateNavbar(navbar) {
+  const hiddenPageRoutes = [];
+  if (navbar === void 0) return hiddenPageRoutes;
+  checkType(navbar, "object", ["navbar"], "Navbar configuration");
+  checkType(navbar.blur, "boolean", ["navbar", "blur"], "Navbar blur setting");
+  const primaryPageRoute = validateNavbarItem(navbar.primary, [
+    "navbar",
+    "primary"
+  ]);
+  if (primaryPageRoute) hiddenPageRoutes.push(primaryPageRoute);
+  const secondaryPageRoute = validateNavbarItem(navbar.secondary, [
+    "navbar",
+    "secondary"
+  ]);
+  if (secondaryPageRoute) hiddenPageRoutes.push(secondaryPageRoute);
+  if (navbar.links !== void 0) {
+    checkType(navbar.links, "array", ["navbar", "links"], "Navbar links");
+    if (navbar.links.length > 3) {
+      throwConfigError("Navbar links cannot have more than 3 items.", [
+        "navbar",
+        "links"
+      ]);
+    }
+    navbar.links.forEach((link, i) => {
+      const hiddenPageRoute = validateNavbarItem(link, ["navbar", "links", i]);
+      if (hiddenPageRoute) hiddenPageRoutes.push(hiddenPageRoute);
+    });
+  }
+  return hiddenPageRoutes;
+}
+function validateFooter(footer) {
+  const hiddenPageRoutes = [];
+  if (footer === void 0) return hiddenPageRoutes;
+  checkType(footer, "object", ["footer"], "Footer configuration");
+  if (footer.socials !== void 0) {
+    checkType(
+      footer.socials,
+      "object",
+      ["footer", "socials"],
+      "Footer socials"
+    );
+    const validSocials = [
+      "x",
+      "website",
+      "facebook",
+      "youtube",
+      "discord",
+      "slack",
+      "github",
+      "linkedin",
+      "instagram",
+      "hacker-news",
+      "medium",
+      "telegram",
+      "bluesky",
+      "threads",
+      "reddit",
+      "podcast"
+    ];
+    for (const [key, value] of Object.entries(footer.socials)) {
+      if (!validSocials.includes(key)) {
+        throwConfigError(
+          `Invalid social platform: ${key}. Valid options are: ${validSocials.join(
+            ", "
+          )}`,
+          ["footer", "socials", key]
+        );
+      }
+      checkType(
+        value,
+        "string",
+        ["footer", "socials", key],
+        `Social link for ${key}`
+      );
+      if (!isUrl(value)) {
+        throwConfigError(`Social link for ${key} must be a valid URL.`, [
+          "footer",
+          "socials",
+          key
+        ]);
+      }
+    }
+  }
+  if (footer.links !== void 0) {
+    checkType(footer.links, "array", ["footer", "links"], "Footer links");
+    footer.links.forEach((link, i) => {
+      checkType(link, "object", ["footer", "links", i], "Footer link");
+      if (typeof link.text !== "string") {
+        throwConfigError("Footer link must have a 'text' property.", [
+          "footer",
+          "links",
+          i,
+          "text"
+        ]);
+      }
+      if (typeof link.href !== "string") {
+        throwConfigError("Footer link must have an 'href' property.", [
+          "footer",
+          "links",
+          i,
+          "href"
+        ]);
+      }
+      const hiddenPageRoute = normalizeInternalPageHref(
+        link.href,
+        ["footer", "links", i, "href"],
+        "Footer link href"
+      );
+      if (hiddenPageRoute) {
+        link.href = hiddenPageRoute.linkHref;
+        hiddenPageRoutes.push(hiddenPageRoute);
+      }
+    });
+  }
+  return hiddenPageRoutes;
+}
+async function validateNavigation(navigation) {
+  checkType(navigation, "object", ["navigation"], "Navigation");
+  const keys = Object.keys(navigation);
+  const validKeys = ["pages", "menu", "openapi"];
+  const navKeys = keys.filter((key) => validKeys.includes(key));
+  if (navKeys.length !== 1) {
+    throwConfigError(
+      `Navigation must contain exactly one top-level item (${validKeys.join(
+        ", "
+      )}). Found ${navKeys.length}.`,
+      ["navigation"]
+    );
+  }
+  const navKey = navKeys[0];
+  const navValue = navigation[navKey];
+  if (navKey === "menu") {
+    await validateNavMenu(navValue, ["navigation", "menu"]);
+  } else {
+    checkType(
+      navValue,
+      "array",
+      ["navigation", navKey],
+      `Navigation container '${navKey}'`
+    );
+    for (const [i, item] of navValue.entries()) {
+      const itemPath = ["navigation", navKey, i];
+      if (typeof item === "string") {
+        const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
+        navValue[i] = normalizedPagePath;
+        validateFileExistence(normalizedPagePath, itemPath);
+      } else {
+        await validateNavigationNode(item, itemPath);
+      }
+    }
+  }
+}
+async function validateConfig(config) {
+  validateTitle(config.title);
+  validateLogo(config.logo);
+  validateTheme(config.theme);
+  validateAssistant(config.assistant);
+  await validateNavigation(config.navigation);
+  config.home = validateHome(config.home);
+  if (config.home === void 0) {
+    const fallbackHome = getFirstPagePathFromNavigation(config.navigation);
+    if (!fallbackHome) {
+      throwConfigError(
+        "Home is undefined and no documentation page exists in navigation to use as fallback.",
+        ["home"]
+      );
+    }
+    config.home = fallbackHome;
+  }
+  const hiddenPageRoutes = [
+    ...validateNavbar(config.navbar),
+    ...validateFooter(config.footer)
+  ];
+  const dedupedHiddenPageRoutes = /* @__PURE__ */ new Map();
+  for (const route of hiddenPageRoutes) {
+    dedupedHiddenPageRoutes.set(route.href, route);
+  }
+  config.hiddenPageRoutes = Array.from(dedupedHiddenPageRoutes.values());
+  if (config.playground !== void 0) {
+    checkType(config.playground, "object", ["playground"], "Playground");
+    if (config.playground.proxy !== void 0) {
+      checkType(
+        config.playground.proxy,
+        "boolean",
+        ["playground", "proxy"],
+        "Proxy"
+      );
+    }
+  }
+  return config;
+}
+var configCache = null;
+var lastMtime = 0;
+async function getConfig() {
+  assertConfigured();
+  if (!fs.existsSync(CONFIG_PATH)) {
+    throw new Error(
+      "[USER_ERROR]: Invalid docs.json: `docs.json` missing at root of documentation repo."
+    );
+  }
+  const stats = fs.statSync(CONFIG_PATH);
+  if (configCache && stats.mtimeMs === lastMtime) {
+    return configCache;
+  }
+  lastMtime = stats.mtimeMs;
+  configCache = (async () => {
+    const fileContent = fs.readFileSync(CONFIG_PATH, "utf-8");
+    let config;
+    try {
+      config = JSON.parse(fileContent);
+    } catch (e) {
+      throw new Error(
+        `[USER_ERROR]: Invalid docs.json: Invalid JSON syntax: ${e instanceof Error ? e.message : e}`
+      );
+    }
+    try {
+      const validatedConfig = await validateConfig(config);
+      return validatedConfig;
+    } catch (error) {
+      throw new Error(
+        `[USER_ERROR]: Invalid docs.json: ${error instanceof Error ? error.message : error}`
+      );
+    }
+  })();
+  return configCache;
+}
+function validateComponentUsage(content) {
+  const contentWithoutFrontmatter = content.replace(/^---[\s\S]*?---\n?/, "");
+  const allowedComponentSet = new Set(AVAILABLE_COMPONENTS);
+  const contentWithoutCode = contentWithoutFrontmatter.replace(/````[\s\S]*?````/g, "").replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "").replace(/\{\s*(['"`])(?:\\.|(?!\1)[\s\S])*?\1\s*\}/g, "");
+  const componentRegex = /<([A-Z][a-zA-Z0-9]*)/g;
+  let match;
+  const unknownComponents = [];
+  while ((match = componentRegex.exec(contentWithoutCode)) !== null) {
+    const componentName = match[1];
+    if (!allowedComponentSet.has(componentName)) {
+      if (!unknownComponents.includes(componentName)) {
+        unknownComponents.push(componentName);
+      }
+    }
+  }
+  if (unknownComponents.length > 0) {
+    const componentList = unknownComponents.map((c) => `<${c}>`).join(", ");
+    const visibleComponents = AVAILABLE_COMPONENTS.filter(
+      (component) => !INTERNAL_ONLY_COMPONENTS.has(component)
+    );
+    throw new Error(
+      `Unknown component(s): ${componentList}. Available components are: ${visibleComponents.join(", ")}. If writing ABOUT a component, use literal backticks: \`<ComponentName>\` or a JSX string: \`{'<ComponentName />'}\`.`
+    );
+  }
+}
+function getMdxFiles(dir) {
+  let results = [];
+  const list = fs.readdirSync(dir);
+  list.forEach((file) => {
+    file = path.resolve(dir, file);
+    const stat = fs.statSync(file);
+    if (stat && stat.isDirectory()) {
+      results = results.concat(getMdxFiles(file));
+    } else if (file.endsWith(".mdx")) {
+      results.push(file);
+    }
+  });
+  return results;
+}
+async function validateMdxContent() {
+  assertConfigured();
+  const files = getMdxFiles(DOCS_DIR);
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, "utf-8");
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      if (match) {
+        const frontmatter = yaml.parse(match[1]);
+        const result = docsSchema.safeParse(frontmatter);
+        if (!result.success) {
+          const issue = result.error.issues[0];
+          const pathStr = issue.path.join(".");
+          throw new Error(
+            `Frontmatter validation failed: ${issue.message} (at: ${pathStr})`
+          );
+        }
+      }
+      validateComponentUsage(content);
+      await compile(content, { jsx: true });
+    } catch (e) {
+      const relativePath = path.relative(DOCS_DIR, file);
+      const location = e.line ? `:${e.line}:${e.column}` : "";
+      const reason = e.reason || e.message;
+      throw new Error(
+        `[USER_ERROR]: Invalid MDX in ${relativePath}${location} -> ${reason}`
+      );
+    }
+  }
+}
+export {
+  BASE_COLOR_OPTIONS,
+  DEFAULT_SHIKI_DARK_THEME,
+  DEFAULT_SHIKI_LIGHT_THEME,
+  DEFAULT_THEME_COLOR_DARK,
+  DEFAULT_THEME_COLOR_LIGHT,
+  SHIKI_BUNDLED_THEME_NAMES,
+  configureDocsValidator,
+  docsSchema,
+  getConfig,
+  isBundledShikiThemeName,
+  loadOpenApiSpec,
+  validateMdxContent
+};