radiant-docs 0.1.0

package/template/src/lib/validation.ts

@@ -0,0 +1,1097 @@
+import fs from "node:fs";
+import path from "node:path";
+import pkg from "@stoplight/spectral-core";
+const { Spectral } = pkg;
+import { oas } from "@stoplight/spectral-rulesets";
+import { compile } from "@mdx-js/mdx";
+import yaml from "yaml";
+import { docsSchema } from "./frontmatter-schema";
+
+// --- Configuration Constants ---
+const CWD = process.cwd();
+const DOCS_DIR = path.join(CWD, "src/content/docs");
+const CONFIG_PATH = path.join(DOCS_DIR, "docs.json");
+
+// Define the list of available user components for MDX
+const AVAILABLE_COMPONENTS = [
+  "Callout",
+  "Tabs",
+  "Tab",
+  "Steps",
+  "Step",
+  "Accordian",
+  "AccordianGroup",
+];
+
+export type NavPage = { page: string; icon?: string; tag?: string };
+export type NavGroup = {
+  group: string;
+  pages: (string | NavPage | NavGroup)[];
+  icon?: string;
+  expanded?: boolean; // need to add this logic
+  tag?: string;
+};
+export type NavOpenApi = {
+  source: string;
+  include?: string[];
+  exclude?: string[];
+};
+export type NavigationItem = {
+  pages?: (string | NavPage)[];
+  groups?: NavGroup[];
+  menu?: NavMenu;
+  openapi?: string | NavOpenApi;
+};
+
+export type NavMenuItem = {
+  label: string;
+  submenu: Omit<NavigationItem, "menu">;
+  icon?: string;
+};
+export type NavMenu = {
+  type?: "dropdown" | "collapsible";
+  label?: string;
+  items: NavMenuItem[];
+};
+export type NavbarItem = {
+  text: string;
+  href: string;
+  icon?: string;
+};
+export type Logo = {
+  light?: string;
+  dark?: string;
+  href?: string;
+};
+export type DocsConfig = {
+  title: string;
+  logo?: Logo;
+  home?: string;
+  navigation: NavigationItem;
+  navbar?: {
+    blur?: boolean;
+    primary?: NavbarItem;
+    secondary?: NavbarItem;
+    links?: NavbarItem[];
+  };
+};
+type Path = (string | number)[];
+
+// --- 1. Error Utility ---
+
+const throwConfigError = (message: string, currentPath: Path): never => {
+  const location =
+    currentPath.length > 0 ? ` (at: ${currentPath.join(".")})` : "";
+  throw new Error(`${message}${location}\n`);
+};
+
+// --- 2. Core Validation Logic (Recursive and Structural) ---
+
+// Helper for basic type checks, allowing undefined for optional keys
+function checkType(
+  value: any,
+  type: "string" | "boolean" | "array" | "object",
+  currentPath: Path,
+  label: string
+): void {
+  if (value === undefined) 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 validateFileExistence(filePath: string, currentPath: Path): void {
+  // Assuming relative path from DOCS_DIR and .mdx extension
+  const fullPath = path.join(DOCS_DIR, `${filePath}.mdx`);
+
+  if (!fs.existsSync(fullPath)) {
+    throwConfigError(
+      `Referenced file not found. Expected: ${filePath}`,
+      currentPath
+    );
+  }
+}
+
+// Helper function to check if a string is a URL
+function isUrl(str: string): boolean {
+  try {
+    const url = new URL(str);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+// Cache for OpenAPI specs (key: filePathOrUrl, value: parsed spec)
+const openApiSpecCache = new Map<string, any>();
+
+// Helper function to load and parse OpenAPI spec
+export async function loadOpenApiSpec(filePathOrUrl: string): Promise<any> {
+  // Check cache first
+  if (openApiSpecCache.has(filePathOrUrl)) {
+    return openApiSpecCache.get(filePathOrUrl);
+  }
+
+  const isUrlPath = isUrl(filePathOrUrl);
+
+  let fileContent: string;
+
+  if (isUrlPath) {
+    // Fetch from URL
+    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 {
+    // Read from local file
+    const fullPath = path.join(DOCS_DIR, filePathOrUrl);
+    fileContent = fs.readFileSync(fullPath, "utf-8");
+  }
+
+  // Detect HTML content (common mistake: URL returns HTML page instead of spec)
+  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."
+    );
+  }
+
+  // Determine format and parse
+  let parsedSpec: any;
+  try {
+    if (
+      filePathOrUrl.endsWith(".json") ||
+      (isUrlPath && filePathOrUrl.includes(".json"))
+    ) {
+      parsedSpec = JSON.parse(fileContent);
+    } else {
+      const yaml = await import("yaml");
+      parsedSpec = yaml.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;
+  }
+
+  // Cache the parsed spec
+  openApiSpecCache.set(filePathOrUrl, parsedSpec);
+
+  return parsedSpec;
+}
+
+async function validateOpenApiFile(filePathOrUrl: string, currentPath: Path) {
+  const isUrlPath = isUrl(filePathOrUrl);
+
+  if (!isUrlPath) {
+    // For local files, validate extension and existence
+    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 {
+    // For URLs, validate that it's a valid HTTP/HTTPS URL
+    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
+      );
+    }
+  }
+
+  // Validate the OpenAPI spec using Spectral (works for both files and URLs)
+  try {
+    const document = await loadOpenApiSpec(filePathOrUrl);
+
+    const basicRuleset = {
+      formats: oas.formats,
+      rules: {
+        "oas3-schema": oas.rules["oas3-schema"],
+      },
+    };
+
+    const spectral = new Spectral();
+
+    spectral.setRuleset(basicRuleset);
+
+    let results = await spectral.run(document);
+
+    if (results.length > 0) {
+      // Format validation errors - show first few errors
+      const errorMessages = results
+        .slice(0, 5) // Limit to first 5 errors
+        .map((result) => {
+          const pathStr =
+            result.path.length > 0 ? result.path.join(".") : "root";
+          return `${result.message} (at ${pathStr})`;
+        });
+
+      const errorText = errorMessages.join("; ");
+      const moreErrors =
+        results.length > 5 ? ` (and ${results.length - 5} more errors)` : "";
+
+      throwConfigError(
+        `Invalid OpenAPI specification: ${errorText}${moreErrors}`,
+        currentPath
+      );
+    }
+  } catch (error) {
+    // Handle parsing errors separately from validation errors
+    if (error instanceof SyntaxError) {
+      throwConfigError(
+        `Failed to parse OpenAPI file: ${error.message}`,
+        currentPath
+      );
+    } else if (error instanceof Error) {
+      throwConfigError(
+        `Invalid OpenAPI specification: ${error.message}`,
+        currentPath
+      );
+    } else {
+      throwConfigError(
+        `Invalid OpenAPI specification: ${String(error)}`,
+        currentPath
+      );
+    }
+  }
+}
+
+function extractAvailableEndpoints(openApiDoc: any): Set<string> {
+  const endpoints = new Set<string>();
+  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 as any)[method];
+      if (operation) {
+        // Store as "METHOD /path" (uppercase method, lowercase path)
+        const normalizedMethod = method.toUpperCase();
+        const normalizedPath = pathStr.toLowerCase();
+        endpoints.add(`${normalizedMethod} ${normalizedPath}`);
+      }
+    }
+  }
+
+  return endpoints;
+}
+
+// Helper function to parse endpoint string (e.g., "get /burgers" or "POST /burgers")
+function parseEndpointString(
+  endpointStr: string
+): { method: string; path: string } | null {
+  const trimmed = endpointStr.trim();
+  const parts = trimmed.split(/\s+/);
+
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const method = parts[0].toUpperCase();
+  let path = parts[1];
+
+  // Ensure path starts with /
+  if (!path.startsWith("/")) {
+    path = "/" + path;
+  }
+
+  // Normalize path to lowercase for comparison
+  const normalizedPath = path.toLowerCase();
+
+  return { method, path: normalizedPath };
+}
+
+function validateNavigationNode(item: any, currentPath: Path): void {
+  // A) Base Case: Simple string path
+  if (typeof item === "string") {
+    validateFileExistence(item, currentPath);
+    return;
+  }
+
+  // B) Must be an object
+  checkType(item, "object", currentPath, "Navigation item");
+
+  // Determine item type by key presence (Strict XOR enforcement)
+  const isGroup = "group" in item;
+  const isPage = "page" in item;
+
+  const typeCount = [isGroup, isPage].filter(Boolean).length;
+  if (typeCount !== 1) {
+    throwConfigError(
+      "Object must contain exactly one key: 'page' or 'group'.",
+      currentPath
+    );
+  }
+
+  // --- Validate Group (Recursive) ---
+  if (isGroup) {
+    const path = [...currentPath];
+    checkType(item.group, "string", [...path, "group"], "Group name");
+
+    // C.2: THE EXPANDED CHECK (Kept clean)
+    checkType(item.expanded, "boolean", [...path, "expanded"], "Expanded");
+
+    // Check if pages array exists and validate children
+    if (!item.pages)
+      throwConfigError("Group must have a 'pages' array.", [...path, "pages"]);
+    checkType(item.pages, "array", [...path, "pages"], "Group pages");
+
+    item.pages.forEach((child: any, i: number) => {
+      validateNavigationNode(child, [...path, "pages", i]); // Recursive call
+    });
+    return;
+  }
+
+  // --- Validate Page ---
+  if (isPage) {
+    const path = [...currentPath];
+    checkType(item.page, "string", [...path, "page"], "Page path");
+
+    validateFileExistence(item.page, [...path, "page"]);
+
+    // Check D.2/D.3: Page cannot have group properties
+    if ("expanded" in item)
+      throwConfigError("Page items cannot have 'expanded'.", [
+        ...path,
+        "expanded",
+      ]);
+    if ("pages" in item)
+      throwConfigError("Page items cannot have children.", [...path, "pages"]);
+    return;
+  }
+}
+
+async function validateNavOpenApi(
+  navOpenApi: any,
+  currentPath: Path
+): Promise<void> {
+  checkType(navOpenApi, "object", currentPath, "Open API object");
+
+  // Required: source (must be a string)
+  if (typeof navOpenApi.source !== "string") {
+    throwConfigError(
+      "Open API object must have an 'source' property that is a string.",
+      [...currentPath, "source"]
+    );
+  }
+
+  // Validate the OpenAPI file exists and is valid
+  await validateOpenApiFile(navOpenApi.source, [...currentPath, "source"]);
+
+  // Check mutual exclusivity of include and exclude
+  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 neither include nor exclude is present, that's valid (all endpoints will be included)
+  if (!hasInclude && !hasExclude) {
+    return;
+  }
+
+  // Load the OpenAPI spec to validate against
+  const openApiDoc = await loadOpenApiSpec(navOpenApi.source);
+  const availableEndpoints = extractAvailableEndpoints(openApiDoc);
+
+  // Validate include array
+  if (hasInclude) {
+    checkType(
+      navOpenApi.include,
+      "array",
+      [...currentPath, "include"],
+      "Include array"
+    );
+
+    if (navOpenApi.include.length === 0) {
+      throwConfigError("Include array cannot be empty.", [
+        ...currentPath,
+        "include",
+      ]);
+    }
+
+    // Validate each entry
+    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]
+        );
+      }
+
+      // Check if endpoint exists in the OpenAPI spec
+      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]
+        );
+      }
+    }
+  }
+
+  // Validate exclude array
+  if (hasExclude) {
+    checkType(
+      navOpenApi.exclude,
+      "array",
+      [...currentPath, "exclude"],
+      "Exclude array"
+    );
+
+    if (navOpenApi.exclude.length === 0) {
+      throwConfigError("Exclude array cannot be empty.", [
+        ...currentPath,
+        "exclude",
+      ]);
+    }
+
+    // Validate each entry
+    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]
+        );
+      }
+
+      // Check if endpoint exists in the OpenAPI spec
+      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: NavMenuItem, currentPath: Path) {
+  checkType(item, "object", currentPath, "Menu item");
+
+  checkType(item.icon, "string", [...currentPath, "icon"], "Menu item icon");
+
+  // Required: label
+  if (!item.label) {
+    throwConfigError("Menu item must have a 'label' property.", [
+      ...currentPath,
+      "label",
+    ]);
+  }
+  checkType(item.label, "string", [...currentPath, "label"], "Label");
+
+  // Required: submenu
+  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", "groups", "openapi"];
+  const presentSubmenuKeys = submenuKeys.filter((key) =>
+    validSubmenuKeys.includes(key)
+  );
+  const invalidSubmenuKeys = submenuKeys.filter(
+    (key) => !validSubmenuKeys.includes(key)
+  );
+
+  // Submenu must have exactly one key total
+  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"]
+      );
+    }
+  }
+
+  // Check if the single key is valid
+  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 as keyof Omit<NavigationItem, "menu">];
+
+  // Validate pages array
+  if (submenuKey === "pages") {
+    checkType(
+      submenuValue,
+      "array",
+      [...currentPath, "submenu", "pages"],
+      "Submenu pages"
+    );
+    (submenuValue as NavigationItem["pages"])?.forEach(
+      (page: string | NavPage, i: number) => {
+        if (typeof page === "string") {
+          validateFileExistence(page, [...currentPath, "submenu", "pages", i]);
+        } else {
+          validateNavigationNode(page, [...currentPath, "submenu", "pages", i]);
+        }
+      }
+    );
+  }
+
+  // Validate groups array
+  if (submenuKey === "groups") {
+    checkType(
+      submenuValue,
+      "array",
+      [...currentPath, "submenu", "groups"],
+      "Submenu groups"
+    );
+    (submenuValue as NavigationItem["groups"])?.forEach(
+      (group: NavGroup, i: number) => {
+        validateNavigationNode(group, [...currentPath, "submenu", "groups", i]);
+      }
+    );
+  }
+
+  // Validate openapi - can be string or NavOpenApi object
+  if (submenuKey === "openapi") {
+    if (typeof submenuValue === "string") {
+      // Simple string case - validate file exists and is valid
+      await validateOpenApiFile(submenuValue, [
+        ...currentPath,
+        "submenu",
+        "openapi",
+      ]);
+    } else if (typeof submenuValue === "object") {
+      // NavOpenApi object case - validate structure and include/exclude
+      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: any, currentPath: Path) {
+  checkType(menu, "object", currentPath, "Menu");
+
+  // Optional: type
+  if (menu.type !== undefined) {
+    if (menu.type !== "dropdown" && menu.type !== "collapsible") {
+      throwConfigError(
+        "Menu type must be 'dropdown' or 'collapsible' if provided. Defaults to 'dropdown'",
+        [...currentPath, "type"]
+      );
+    }
+  }
+
+  // Optional: label
+  checkType(menu.label, "string", [...currentPath, "label"], "Menu label");
+
+  // Required: items
+  if (!menu.items) {
+    throwConfigError("Menu must have an 'items' array.", [
+      ...currentPath,
+      "items",
+    ]);
+  }
+  checkType(menu.items, "array", [...currentPath, "items"], "Menu items");
+
+  // Validate each menu item
+  for (const [i, item] of menu.items.entries()) {
+    await validateNavMenuItem(item, [...currentPath, "items", i]);
+  }
+}
+
+function validateNavbarItem(item: any, currentPath: Path): void {
+  // Check if object exists, otherwise we skip (it's optional)
+  if (item === undefined) return;
+
+  checkType(item, "object", currentPath, "Navbar item");
+
+  // Required properties
+  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",
+    ]);
+  }
+
+  // Optional property
+  checkType(item.icon, "string", [...currentPath, "icon"], "Navbar icon");
+}
+
+// --- Top-Level Validation Functions (Your Clean API) ---
+
+function validateTitle(title: DocsConfig["title"]) {
+  checkType(title, "string", ["title"], "Title");
+  if (!title) throwConfigError("Title is missing.", ["title"]);
+}
+
+function validateLogo(logo: DocsConfig["logo"]) {
+  // Logo is optional, so if it's undefined, we're done
+  if (logo === undefined) return;
+
+  // If logo is provided, it must be an object
+  checkType(logo, "object", ["logo"], "Logo configuration");
+
+  // Validate 'light' logo if provided
+  if (logo.light !== undefined) {
+    checkType(logo.light, "string", ["logo", "light"], "Logo light path");
+
+    // Validate file extension
+    const validExtensions = [".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif"];
+    const hasValidExtension = validExtensions.some((ext) =>
+      logo.light!.toLowerCase().endsWith(ext)
+    );
+    if (!hasValidExtension) {
+      throwConfigError(
+        "Logo light must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif)",
+        ["logo", "light"]
+      );
+    }
+
+    // Validate file exists in content/docs folder
+    // Normalize path: remove leading slash if present
+    const normalizedPath = logo.light.startsWith("/")
+      ? logo.light.slice(1)
+      : logo.light;
+    const fullPath = path.join(DOCS_DIR, normalizedPath);
+
+    if (!fs.existsSync(fullPath)) {
+      throwConfigError(
+        `Logo light file not found. Expected: ${normalizedPath} (relative to content/docs folder)`,
+        ["logo", "light"]
+      );
+    }
+  }
+
+  // Validate 'dark' logo if provided
+  if (logo.dark !== undefined) {
+    checkType(logo.dark, "string", ["logo", "dark"], "Logo dark path");
+
+    // Validate file extension
+    const validExtensions = [".svg", ".png", ".jpg", ".jpeg", ".webp", ".gif"];
+    const hasValidExtension = validExtensions.some((ext) =>
+      logo.dark!.toLowerCase().endsWith(ext)
+    );
+    if (!hasValidExtension) {
+      throwConfigError(
+        "Logo dark must be a valid image file (.svg, .png, .jpg, .jpeg, .webp, .gif)",
+        ["logo", "dark"]
+      );
+    }
+
+    // Validate file exists in content/docs folder
+    // Normalize path: remove leading slash if present
+    const normalizedPath = logo.dark.startsWith("/")
+      ? logo.dark.slice(1)
+      : logo.dark;
+    const fullPath = path.join(DOCS_DIR, normalizedPath);
+
+    if (!fs.existsSync(fullPath)) {
+      throwConfigError(
+        `Logo dark file not found. Expected: ${normalizedPath} (relative to content/docs folder)`,
+        ["logo", "dark"]
+      );
+    }
+  }
+
+  // Validate 'href' if provided
+  if (logo.href !== undefined) {
+    checkType(logo.href, "string", ["logo", "href"], "Logo href");
+
+    // Validate it's either a valid URL or a valid internal path
+    // Internal paths should start with /
+    // External URLs should start with http:// or https://
+    const trimmedHref = logo.href.trim();
+
+    if (trimmedHref === "") {
+      throwConfigError("Logo href cannot be an empty string", ["logo", "href"]);
+    }
+
+    // Check if it's a URL
+    const isUrl =
+      trimmedHref.startsWith("http://") || trimmedHref.startsWith("https://");
+
+    // Check if it's an internal path (starts with /)
+    const isInternalPath = trimmedHref.startsWith("/");
+
+    if (!isUrl && !isInternalPath) {
+      throwConfigError(
+        "Logo href must be either a valid URL (http:// or https://) or an internal path (starting with /)",
+        ["logo", "href"]
+      );
+    }
+  }
+}
+
+function validateHome(home: DocsConfig["home"]) {
+  checkType(home, "string", ["home"], "Home path");
+}
+
+function validateNavbar(navbar: DocsConfig["navbar"]) {
+  if (navbar === undefined) return; // Navbar itself is optional
+
+  checkType(navbar, "object", ["navbar"], "Navbar configuration");
+
+  // Validate 'blur'
+  checkType(navbar.blur, "boolean", ["navbar", "blur"], "Navbar blur setting");
+
+  // Validate 'primary' item
+  validateNavbarItem(navbar.primary, ["navbar", "primary"]);
+
+  // Validate 'secondary' item
+  validateNavbarItem(navbar.secondary, ["navbar", "secondary"]);
+
+  // Validate 'links' array
+  if (navbar.links !== undefined) {
+    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: any, i: number) => {
+      validateNavbarItem(link, ["navbar", "links", i]);
+    });
+  }
+}
+
+async function validateNavigation(navigation: DocsConfig["navigation"]) {
+  checkType(navigation, "object", ["navigation"], "Navigation");
+
+  const keys = Object.keys(navigation);
+  const validKeys = ["pages", "groups", "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 as any)[navKey];
+
+  // Handle "menu" as an object, "pages" and "groups" as arrays
+  if (navKey === "menu") {
+    await validateNavMenu(navValue, ["navigation", "menu"]);
+  } else {
+    // Validate the container itself is an array for pages/groups
+    checkType(
+      navValue,
+      "array",
+      ["navigation", navKey],
+      `Navigation container '${navKey}'`
+    );
+
+    // Route to Recursive Structural Validation
+    navValue.forEach((item: NavigationItem, i: number) => {
+      validateNavigationNode(item, ["navigation", navKey, i]);
+    });
+  }
+}
+
+// --- Config Runner ---
+
+async function validateConfig(config: any): Promise<DocsConfig> {
+  // Execute top-level checks sequentially
+  validateTitle(config.title);
+  validateLogo(config.logo);
+  validateHome(config.home);
+  validateNavbar(config.navbar);
+  await validateNavigation(config.navigation);
+
+  return config as DocsConfig;
+}
+
+let configCache: Promise<DocsConfig> | null = null;
+let lastMtime: number = 0;
+
+export async function getConfig(): Promise<DocsConfig> {
+  // 1. Check if docs.json exists
+  if (!fs.existsSync(CONFIG_PATH)) {
+    throw new Error(
+      "[USER_ERROR]: Invalid docs.json: docs.json missing at root of documentation repo."
+    );
+  }
+
+  // 2. Check if docs.json has changed
+  const stats = fs.statSync(CONFIG_PATH);
+  if (configCache && stats.mtimeMs === lastMtime) {
+    return configCache;
+  }
+
+  // 3. If docs.json changed or first run, update cache
+  lastMtime = stats.mtimeMs;
+  configCache = (async () => {
+    const fileContent = fs.readFileSync(CONFIG_PATH, "utf-8");
+    let config: any;
+    try {
+      config = JSON.parse(fileContent);
+    } catch (e) {
+      throw new Error(
+        `[USER_ERROR]: Invalid docs.json: Invalid JSON syntax: ${
+          e instanceof Error ? e.message : e
+        }`
+      );
+    }
+    // ---
+
+    // The custom validation is executed here
+    try {
+      const validatedConfig = await validateConfig(config);
+      return validatedConfig;
+    } catch (error) {
+      // Catch the custom error thrown by throwConfigError and re-throw it.
+      throw new Error(
+        `[USER_ERROR]: Invalid docs.json: ${
+          error instanceof Error ? error.message : error
+        }`
+      );
+    }
+  })();
+
+  return configCache;
+}
+
+// Validate that only known components are used in MDX content
+function validateComponentUsage(content: string): void {
+  // Remove frontmatter before checking
+  const contentWithoutFrontmatter = content.replace(/^---[\s\S]*?---\n?/, "");
+
+  // Extract imported component names from MDX import statements
+  // Matches: import ComponentName from "..." or import { ComponentName } from "..."
+  const importedComponents: string[] = [];
+  const defaultImportRegex = /import\s+([A-Z][a-zA-Z0-9]*)\s+from/g;
+  const namedImportRegex = /import\s*\{([^}]+)\}\s*from/g;
+
+  let importMatch;
+  while (
+    (importMatch = defaultImportRegex.exec(contentWithoutFrontmatter)) !== null
+  ) {
+    importedComponents.push(importMatch[1]);
+  }
+  while (
+    (importMatch = namedImportRegex.exec(contentWithoutFrontmatter)) !== null
+  ) {
+    // Parse named imports like { Foo, Bar as Baz }
+    const names = importMatch[1].split(",").map((n) => {
+      const parts = n.trim().split(/\s+as\s+/);
+      return parts[parts.length - 1].trim(); // Use the alias if present
+    });
+    importedComponents.push(...names.filter((n) => /^[A-Z]/.test(n)));
+  }
+
+  // Combine available components with imported ones
+  const allowedComponents = [...AVAILABLE_COMPONENTS, ...importedComponents];
+
+  // Remove code blocks, inline code, and JSX string expressions to avoid false positives
+  const contentWithoutCode = contentWithoutFrontmatter
+    .replace(/````[\s\S]*?````/g, "") // 4-backtick code blocks (check first, they're longer)
+    .replace(/```[\s\S]*?```/g, "") // fenced code blocks
+    .replace(/`[^`]+`/g, "") // inline code
+    .replace(/\{['"][^'"]*['"]\}/g, ""); // JSX string expressions like {'<Component />'}
+
+  // Find all JSX component tags (PascalCase tags)
+  // Matches: <ComponentName, <ComponentName>, <ComponentName />, etc.
+  const componentRegex = /<([A-Z][a-zA-Z0-9]*)/g;
+  let match;
+
+  const unknownComponents: string[] = [];
+
+  while ((match = componentRegex.exec(contentWithoutCode)) !== null) {
+    const componentName = match[1];
+    if (!allowedComponents.includes(componentName)) {
+      // Avoid duplicate entries
+      if (!unknownComponents.includes(componentName)) {
+        unknownComponents.push(componentName);
+      }
+    }
+  }
+
+  if (unknownComponents.length > 0) {
+    const componentList = unknownComponents.map((c) => `<${c}>`).join(", ");
+    throw new Error(
+      `Unknown component(s): ${componentList}. ` +
+        `Available components are: ${AVAILABLE_COMPONENTS.join(", ")}. ` +
+        `If writing ABOUT a component, use backticks: \`<ComponentName>\` or JSX strings: {'<ComponentName />'}`
+    );
+  }
+}
+
+// Helper to recursively find MDX files
+function getMdxFiles(dir: string): string[] {
+  let results: string[] = [];
+  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;
+}
+
+// MDX Validation Function
+export async function validateMdxContent() {
+  const files = getMdxFiles(DOCS_DIR);
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, "utf-8");
+
+      // Check for Frontmatter
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+      if (match) {
+        // Parse only if it exists
+        const frontmatter = yaml.parse(match[1]);
+
+        // Validate against shared schema
+        const result = docsSchema.safeParse(frontmatter);
+
+        if (!result.success) {
+          const issue = result.error.issues[0];
+          const pathStr = issue.path.join(".");
+          // Throw clean error
+          throw new Error(
+            `Frontmatter validation failed: ${issue.message} (at: ${pathStr})`
+          );
+        }
+      }
+
+      // Validate component usage BEFORE compiling
+      validateComponentUsage(content);
+
+      // Compile just to check syntax
+      await compile(content, { jsx: true });
+    } catch (e: any) {
+      const relativePath = path.relative(DOCS_DIR, file);
+      const location = e.line ? `:${e.line}:${e.column}` : "";
+      const reason = e.reason || e.message;
+
+      // Throw clean error
+      throw new Error(
+        `[USER_ERROR]: Invalid MDX in ${relativePath}${location} -> ${reason}`
+      );
+    }
+  }
+}