radiant-docs 0.1.34 → 0.1.37

package/template/src/lib/validation.ts

@@ -125,9 +125,18 @@ export type NavPage = {
   tag?: string;
   title?: string;
 };
+export type NavOpenApiPageRef = {
+  source: string;
+  endpoint: string;
+};
+export type NavOpenApiPage = {
+  openapi: NavOpenApiPageRef;
+  title?: string;
+  tag?: string;
+};
 export type NavGroup = {
   group: string;
-  pages: (string | NavPage | NavGroup)[];
+  pages: (string | NavPage | NavGroup | NavOpenApiPage)[];
   icon?: string | null;
   expanded?: boolean; // need to add this logic
   tag?: string;
@@ -138,7 +147,7 @@ export type NavOpenApi = {
   exclude?: string[];
 };
 export type NavigationItem = {
-  pages?: (string | NavPage | NavGroup)[];
+  pages?: (string | NavPage | NavGroup | NavOpenApiPage)[];
   menu?: NavMenu;
   openapi?: string | NavOpenApi;
 };
@@ -553,11 +562,53 @@ function parseEndpointString(
   return { method, path: normalizedPath };
 }
 
-function validateNavigationNode(
+async function validateNavOpenApiPage(
+  navOpenApiPage: any,
+  currentPath: Path,
+): Promise<void> {
+  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: any,
   currentPath: Path,
   groupDepth: number = 0,
-): void {
+): Promise<void> {
   // A) Base Case: Simple string path
   if (typeof item === "string") {
     const normalizedPath = normalizeDocsPagePath(item, currentPath);
@@ -571,11 +622,12 @@ function validateNavigationNode(
   // Determine item type by key presence (Strict XOR enforcement)
   const isGroup = "group" in item;
   const isPage = "page" in item;
+  const isOpenApiPage = "openapi" in item;
 
-  const typeCount = [isGroup, isPage].filter(Boolean).length;
+  const typeCount = [isGroup, isPage, isOpenApiPage].filter(Boolean).length;
   if (typeCount !== 1) {
     throwConfigError(
-      "Object must contain exactly one key: 'page' or 'group'.",
+      "Object must contain exactly one key: 'page', 'group', or 'openapi'.",
       currentPath,
     );
   }
@@ -601,17 +653,17 @@ function validateNavigationNode(
       throwConfigError("Group must have a 'pages' array.", [...path, "pages"]);
     checkType(item.pages, "array", [...path, "pages"], "Group pages");
 
-    item.pages.forEach((child: any, i: number) => {
+    for (const [i, child] of item.pages.entries()) {
       if (typeof child === "string") {
         const childPath = [...path, "pages", i];
         const normalizedPagePath = normalizeDocsPagePath(child, childPath);
         item.pages[i] = normalizedPagePath;
         validateFileExistence(normalizedPagePath, childPath);
-        return;
+        continue;
       }
 
-      validateNavigationNode(child, [...path, "pages", i], groupDepth + 1);
-    });
+      await validateNavigationNode(child, [...path, "pages", i], groupDepth + 1);
+    }
     return;
   }
 
@@ -640,10 +692,47 @@ function validateNavigationNode(
       throwConfigError("Page items cannot have children.", [...path, "pages"]);
     return;
   }
+
+  if (isOpenApiPage) {
+    const path = [...currentPath];
+
+    if ("icon" in item) {
+      throwConfigError(
+        "Open API page items cannot have an 'icon'. Method badges are displayed automatically.",
+        [...path, "icon"],
+      );
+    }
+
+    await validateNavOpenApiPage(item.openapi, [...path, "openapi"]);
+    checkType(item.title, "string", [...path, "title"], "Open API page title");
+    checkType(item.tag, "string", [...path, "tag"], "Open API page tag");
+
+    if ("expanded" in item)
+      throwConfigError("Open API page items cannot have 'expanded'.", [
+        ...path,
+        "expanded",
+      ]);
+    if ("pages" in item)
+      throwConfigError("Open API page items cannot have children.", [
+        ...path,
+        "pages",
+      ]);
+    if ("group" in item)
+      throwConfigError("Open API page items cannot have 'group'.", [
+        ...path,
+        "group",
+      ]);
+    if ("page" in item)
+      throwConfigError("Open API page items cannot have 'page'.", [
+        ...path,
+        "page",
+      ]);
+    return;
+  }
 }
 
 function getFirstPagePathFromPageItems(
-  items: (string | NavPage | NavGroup)[],
+  items: (string | NavPage | NavGroup | NavOpenApiPage)[],
 ): string | undefined {
   for (const item of items) {
     if (typeof item === "string") {
@@ -890,19 +979,18 @@ async function validateNavMenuItem(item: NavMenuItem, currentPath: Path) {
       [...currentPath, "submenu", "pages"],
       "Submenu pages",
     );
-    (submenuValue as NavigationItem["pages"])?.forEach(
-      (item: string | NavPage | NavGroup, i: number) => {
-        const itemPath = [...currentPath, "submenu", "pages", i];
-        if (typeof item === "string") {
-          const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
-          (submenuValue as (string | NavPage | NavGroup)[])[i] =
-            normalizedPagePath;
-          validateFileExistence(normalizedPagePath, itemPath);
-        } else {
-          validateNavigationNode(item, itemPath);
-        }
-      },
-    );
+    const pages = (submenuValue as NavigationItem["pages"]) ?? [];
+    for (const [i, item] of pages.entries()) {
+      const itemPath = [...currentPath, "submenu", "pages", i];
+      if (typeof item === "string") {
+        const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
+        (submenuValue as (string | NavPage | NavGroup | NavOpenApiPage)[])[i] =
+          normalizedPagePath;
+        validateFileExistence(normalizedPagePath, itemPath);
+      } else {
+        await validateNavigationNode(item, itemPath);
+      }
+    }
   }
 
   // Validate openapi - can be string or NavOpenApi object
@@ -1326,16 +1414,16 @@ async function validateNavigation(navigation: DocsConfig["navigation"]) {
     );
 
     // Route to Recursive Structural Validation
-    navValue.forEach((item: NavigationItem, i: number) => {
+    for (const [i, item] of navValue.entries()) {
       const itemPath = ["navigation", navKey, i] as Path;
       if (typeof item === "string") {
         const normalizedPagePath = normalizeDocsPagePath(item, itemPath);
         navValue[i] = normalizedPagePath;
         validateFileExistence(normalizedPagePath, itemPath);
       } else {
-        validateNavigationNode(item, itemPath);
+        await validateNavigationNode(item, itemPath);
       }
-    });
+    }
   }
 }
 

package/template/scripts/rewrite-static-asset-host.mjs

@@ -1,408 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-const CWD = process.cwd();
-const DIST_DIR = path.join(CWD, "dist");
-const LOCAL_ORIGIN = "https://radiant.invalid";
-
-const STATIC_EXTENSIONS = new Set([
-  ".avif",
-  ".css",
-  ".eot",
-  ".gif",
-  ".ico",
-  ".jpeg",
-  ".jpg",
-  ".js",
-  ".json",
-  ".mjs",
-  ".mp4",
-  ".otf",
-  ".pdf",
-  ".png",
-  ".svg",
-  ".ttf",
-  ".txt",
-  ".wasm",
-  ".webmanifest",
-  ".webp",
-  ".woff",
-  ".woff2",
-  ".xml",
-]);
-
-const STATIC_PATH_PREFIXES = ["/_astro/", "/_og/", "/pagefind/"];
-
-function normalizeHostUrl(input) {
-  const withScheme = /^https?:\/\//i.test(input) ? input : `https://${input}`;
-  return new URL(withScheme);
-}
-
-function normalizePrefix(input) {
-  return input.replace(/^\/+/, "").replace(/\/+$/, "");
-}
-
-function findFilesByExtension(dir, extension, files = []) {
-  if (!fs.existsSync(dir)) return files;
-
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
-
-    if (entry.isDirectory()) {
-      findFilesByExtension(fullPath, extension, files);
-      continue;
-    }
-
-    if (entry.isFile() && entry.name.endsWith(extension)) {
-      files.push(fullPath);
-    }
-  }
-
-  return files;
-}
-
-function htmlBasePathname(filePath) {
-  const relative = path.relative(DIST_DIR, filePath).replace(/\\/g, "/");
-  if (relative === "index.html") return "/";
-
-  if (relative.endsWith("/index.html")) {
-    return `/${relative.slice(0, -"index.html".length)}`;
-  }
-
-  const slashIndex = relative.lastIndexOf("/");
-  if (slashIndex === -1) return "/";
-  return `/${relative.slice(0, slashIndex + 1)}`;
-}
-
-function decodeValue(value) {
-  return value.trim().replace(/&/g, "&");
-}
-
-function isSkippableUrl(value) {
-  return (
-    !value ||
-    value.startsWith("data:") ||
-    value.startsWith("blob:") ||
-    value.startsWith("mailto:") ||
-    value.startsWith("tel:") ||
-    value.startsWith("javascript:") ||
-    value.startsWith("//")
-  );
-}
-
-function isStaticAssetPath(pathname) {
-  const normalizedPath = pathname.toLowerCase();
-  if (STATIC_PATH_PREFIXES.some((prefix) => normalizedPath.startsWith(prefix))) {
-    return true;
-  }
-
-  const extension = path.extname(normalizedPath);
-  return STATIC_EXTENSIONS.has(extension);
-}
-
-function withPrefix(pathname, prefix) {
-  const normalizedPathname = pathname.startsWith("/") ? pathname : `/${pathname}`;
-  if (
-    normalizedPathname === `/${prefix}` ||
-    normalizedPathname.startsWith(`/${prefix}/`)
-  ) {
-    return normalizedPathname;
-  }
-
-  return `/${prefix}${normalizedPathname}`.replace(/\/+/g, "/");
-}
-
-function rewriteSingleUrl(value, filePath, hostUrl, prefix) {
-  const decoded = decodeValue(value);
-  if (isSkippableUrl(decoded)) {
-    return { value, changed: false };
-  }
-
-  let parsed;
-  try {
-    parsed = new URL(decoded, `${LOCAL_ORIGIN}${htmlBasePathname(filePath)}`);
-  } catch {
-    return { value, changed: false };
-  }
-
-  if (parsed.origin === hostUrl.origin) {
-    const prefixedPathname = withPrefix(parsed.pathname, prefix);
-    if (prefixedPathname === parsed.pathname) {
-      return { value, changed: false };
-    }
-
-    const updated = `${hostUrl.origin}${prefixedPathname}${parsed.search}${parsed.hash}`;
-    return {
-      value: updated.replace(/&/g, "&"),
-      changed: true,
-    };
-  }
-
-  if (parsed.origin !== LOCAL_ORIGIN) {
-    return { value, changed: false };
-  }
-
-  if (!isStaticAssetPath(parsed.pathname)) {
-    return { value, changed: false };
-  }
-
-  const prefixedPathname = withPrefix(parsed.pathname, prefix);
-  const updated = `${hostUrl.origin}${prefixedPathname}${parsed.search}${parsed.hash}`;
-
-  return {
-    value: updated.replace(/&/g, "&"),
-    changed: updated !== decoded,
-  };
-}
-
-function rewriteSrcset(value, filePath, hostUrl, prefix) {
-  const candidates = value.split(",");
-  let changed = false;
-
-  const rewritten = candidates.map((candidate) => {
-    const trimmed = candidate.trim();
-    if (!trimmed) return candidate;
-
-    const whitespaceIndex = trimmed.search(/\s/);
-    const urlPart =
-      whitespaceIndex === -1 ? trimmed : trimmed.slice(0, whitespaceIndex);
-    const descriptor = whitespaceIndex === -1 ? "" : trimmed.slice(whitespaceIndex);
-
-    const rewrittenCandidate = rewriteSingleUrl(urlPart, filePath, hostUrl, prefix);
-    if (rewrittenCandidate.changed) changed = true;
-
-    return `${rewrittenCandidate.value}${descriptor}`;
-  });
-
-  return {
-    value: changed ? rewritten.join(", ") : value,
-    changed,
-  };
-}
-
-function rewriteAttribute(html, filePath, tagName, attribute, hostUrl, prefix) {
-  const pattern = new RegExp(
-    `(<${tagName}\\b[^>]*\\b${attribute}\\s*=\\s*["'])([^"']*)(["'][^>]*>)`,
-    "gi",
-  );
-
-  let changed = false;
-
-  const rewritten = html.replace(pattern, (full, before, value, after) => {
-    const result =
-      attribute === "srcset"
-        ? rewriteSrcset(value, filePath, hostUrl, prefix)
-        : rewriteSingleUrl(value, filePath, hostUrl, prefix);
-
-    if (!result.changed) return full;
-    changed = true;
-    return `${before}${result.value}${after}`;
-  });
-
-  return { html: rewritten, changed };
-}
-
-function rewriteMetaImageContent(html, propertyName, hostUrl, prefix) {
-  const patterns = [
-    new RegExp(
-      `(<meta\\s+[^>]*property\\s*=\\s*["']${propertyName}["'][^>]*\\bcontent\\s*=\\s*["'])([^"']*)(["'][^>]*>)`,
-      "gi",
-    ),
-    new RegExp(
-      `(<meta\\s+[^>]*\\bcontent\\s*=\\s*["'])([^"']*)(["'][^>]*property\\s*=\\s*["']${propertyName}["'][^>]*>)`,
-      "gi",
-    ),
-  ];
-
-  let changed = false;
-  let nextHtml = html;
-
-  for (const pattern of patterns) {
-    nextHtml = nextHtml.replace(pattern, (full, before, value, after) => {
-      const result = rewriteSingleUrl(value, DIST_DIR, hostUrl, prefix);
-      if (!result.changed) return full;
-      changed = true;
-      return `${before}${result.value}${after}`;
-    });
-  }
-
-  return { html: nextHtml, changed };
-}
-
-function rewriteMetaNameContent(html, name, hostUrl, prefix) {
-  const patterns = [
-    new RegExp(
-      `(<meta\\s+[^>]*name\\s*=\\s*["']${name}["'][^>]*\\bcontent\\s*=\\s*["'])([^"']*)(["'][^>]*>)`,
-      "gi",
-    ),
-    new RegExp(
-      `(<meta\\s+[^>]*\\bcontent\\s*=\\s*["'])([^"']*)(["'][^>]*name\\s*=\\s*["']${name}["'][^>]*>)`,
-      "gi",
-    ),
-  ];
-
-  let changed = false;
-  let nextHtml = html;
-
-  for (const pattern of patterns) {
-    nextHtml = nextHtml.replace(pattern, (full, before, value, after) => {
-      const result = rewriteSingleUrl(value, DIST_DIR, hostUrl, prefix);
-      if (!result.changed) return full;
-      changed = true;
-      return `${before}${result.value}${after}`;
-    });
-  }
-
-  return { html: nextHtml, changed };
-}
-
-function rewriteInlinePagefindRuntimeImports(html, filePath, hostUrl, prefix) {
-  const pattern =
-    /(["'])(https?:\/\/[^"'`)]*\/pagefind\/pagefind\.js(?:\?[^"'`)]*)?|\/pagefind\/pagefind\.js(?:\?[^"'`)]*)?)\1/g;
-  let changed = false;
-
-  const rewritten = html.replace(pattern, (full, quote, urlValue) => {
-    const result = rewriteSingleUrl(urlValue, filePath, hostUrl, prefix);
-    if (!result.changed) return full;
-
-    changed = true;
-    return `${quote}${result.value}${quote}`;
-  });
-
-  return { html: rewritten, changed };
-}
-
-function rewriteCssUrls(css, filePath, hostUrl, prefix) {
-  const pattern = /url\(\s*(['"]?)([^"')]+)\1\s*\)/gi;
-  let changed = false;
-
-  const rewritten = css.replace(pattern, (full, quote, value) => {
-    const result = rewriteSingleUrl(value, filePath, hostUrl, prefix);
-    if (!result.changed) return full;
-
-    changed = true;
-    return `url(${quote}${result.value}${quote})`;
-  });
-
-  return { css: rewritten, changed };
-}
-
-function main() {
-  const staticAssetHostInput = process.env.STATIC_ASSET_HOST?.trim();
-  const staticAssetPrefixInput =
-    process.env.R2_BUCKET_PREFIX?.trim() ??
-    process.env.STATIC_ASSET_PREFIX?.trim();
-
-  if (!staticAssetHostInput) {
-    console.log(
-      "Skipping static asset host rewrite: STATIC_ASSET_HOST is not configured.",
-    );
-    return;
-  }
-
-  if (!staticAssetPrefixInput) {
-    console.log(
-      "Skipping static asset host rewrite: R2_BUCKET_PREFIX or STATIC_ASSET_PREFIX is not configured.",
-    );
-    return;
-  }
-
-  if (!fs.existsSync(DIST_DIR)) {
-    console.warn("Skipping static asset host rewrite: dist directory not found.");
-    return;
-  }
-
-  const hostUrl = normalizeHostUrl(staticAssetHostInput);
-  const prefix = normalizePrefix(staticAssetPrefixInput);
-  const htmlFiles = findFilesByExtension(DIST_DIR, ".html").sort();
-
-  if (htmlFiles.length === 0) {
-    console.warn("Skipping static asset host rewrite: no HTML files found in dist.");
-    return;
-  }
-
-  let updatedHtmlCount = 0;
-  let updatedCssCount = 0;
-
-  for (const htmlFile of htmlFiles) {
-    const sourceHtml = fs.readFileSync(htmlFile, "utf8");
-    let nextHtml = sourceHtml;
-    let fileChanged = false;
-
-    const rewrites = [
-      ["link", "href"],
-      ["script", "src"],
-      ["img", "src"],
-      ["img", "srcset"],
-      ["source", "src"],
-      ["source", "srcset"],
-      ["video", "src"],
-      ["video", "poster"],
-      ["audio", "src"],
-    ];
-
-    for (const [tagName, attribute] of rewrites) {
-      const result = rewriteAttribute(
-        nextHtml,
-        htmlFile,
-        tagName,
-        attribute,
-        hostUrl,
-        prefix,
-      );
-      nextHtml = result.html;
-      fileChanged = fileChanged || result.changed;
-    }
-
-    const ogResult = rewriteMetaImageContent(
-      nextHtml,
-      "og:image",
-      hostUrl,
-      prefix,
-    );
-    nextHtml = ogResult.html;
-    fileChanged = fileChanged || ogResult.changed;
-
-    const twitterResult = rewriteMetaNameContent(
-      nextHtml,
-      "twitter:image",
-      hostUrl,
-      prefix,
-    );
-    nextHtml = twitterResult.html;
-    fileChanged = fileChanged || twitterResult.changed;
-
-    const pagefindImportResult = rewriteInlinePagefindRuntimeImports(
-      nextHtml,
-      htmlFile,
-      hostUrl,
-      prefix,
-    );
-    nextHtml = pagefindImportResult.html;
-    fileChanged = fileChanged || pagefindImportResult.changed;
-
-    if (fileChanged) {
-      fs.writeFileSync(htmlFile, nextHtml, "utf8");
-      updatedHtmlCount += 1;
-    }
-  }
-
-  const cssFiles = findFilesByExtension(DIST_DIR, ".css").sort();
-
-  for (const cssFile of cssFiles) {
-    const sourceCss = fs.readFileSync(cssFile, "utf8");
-    const result = rewriteCssUrls(sourceCss, cssFile, hostUrl, prefix);
-
-    if (!result.changed) continue;
-
-    fs.writeFileSync(cssFile, result.css, "utf8");
-    updatedCssCount += 1;
-  }
-
-  console.log(
-    `✅ Static asset host rewrite complete. Updated HTML ${updatedHtmlCount}/${htmlFiles.length}, CSS ${updatedCssCount}/${cssFiles.length}.`,
-  );
-}
-
-main();