radiant-docs 0.1.34 → 0.1.38

package/template/src/lib/routes.ts

@@ -2,17 +2,20 @@ import {
   getConfig,
   type NavGroup,
   type NavPage,
+  type NavOpenApiPage,
   type NavMenuItem,
   type NavOpenApi,
   loadOpenApiSpec,
 } from "./validation";
-import { deriveTitleFromEntryId, slugify } from "./utils";
-import path from "node:path";
+import {
+  buildOpenApiEndpointSlug,
+  deriveTitleFromEntryId,
+  parseOpenApiEndpoint,
+  slugify,
+} from "./utils";
 import { getCollection } from "astro:content";
 
-// NOTE: You need to define NavPageItem to include strings, pages, and groups
-// Since the input array is already validated, we can use the types from validation.ts
-type NavPageItem = string | NavPage;
+type MdxNavPageItem = string | NavPage;
 
 // Base route interface
 export interface BaseRoute {
@@ -55,7 +58,7 @@ export function resolveMdxPageTitle(args: {
 }
 
 function processPageItem(
-  item: NavPageItem,
+  item: MdxNavPageItem,
   parentSlug: string = "",
   docs: any[],
 ): MdxRoute {
@@ -92,53 +95,106 @@ function processPageItem(
   };
 }
 
-function processGroup(
+type OpenApiOperationLookup = {
+  method: string;
+  path: string;
+  operation: any;
+};
+
+function findOpenApiOperation(args: {
+  openApiDoc: any;
+  endpointMethod: string;
+  endpointPath: string;
+}): OpenApiOperationLookup | null {
+  const paths = args.openApiDoc?.paths ?? {};
+  const targetMethod = args.endpointMethod.toLowerCase();
+  const targetPath = args.endpointPath.toLowerCase();
+
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+    if (pathStr.toLowerCase() !== targetPath) continue;
+
+    const operation = (pathItem as any)[targetMethod];
+    if (!operation) continue;
+
+    return {
+      method: targetMethod,
+      path: pathStr,
+      operation,
+    };
+  }
+
+  return null;
+}
+
+async function processOpenApiPageItem(
+  item: NavOpenApiPage,
+  parentSlug: string = "",
+): Promise<OpenApiRoute> {
+  const parsedEndpoint = parseOpenApiEndpoint(item.openapi.endpoint);
+  if (!parsedEndpoint) {
+    throw new Error(
+      `Invalid OpenAPI endpoint format "${item.openapi.endpoint}". Expected "METHOD /path".`,
+    );
+  }
+
+  const openApiDoc = await loadOpenApiSpec(item.openapi.source);
+  const matchedOperation = findOpenApiOperation({
+    openApiDoc,
+    endpointMethod: parsedEndpoint.method,
+    endpointPath: parsedEndpoint.path,
+  });
+
+  if (!matchedOperation) {
+    throw new Error(
+      `OpenAPI endpoint "${item.openapi.endpoint}" was not found in source "${item.openapi.source}".`,
+    );
+  }
+
+  const endpointSlug = buildOpenApiEndpointSlug(
+    matchedOperation.path,
+    matchedOperation.method,
+  );
+  const fullSlug = parentSlug ? `${parentSlug}/${endpointSlug}` : endpointSlug;
+  const title =
+    normalizeTitle(item.title) ??
+    normalizeTitle(matchedOperation.operation.summary) ??
+    `${matchedOperation.method.toUpperCase()} ${matchedOperation.path}`;
+
+  return {
+    type: "openapi",
+    slug: fullSlug,
+    filePath: item.openapi.source,
+    title,
+    openApiPath: matchedOperation.path,
+    openApiMethod: matchedOperation.method,
+  };
+}
+
+async function processGroup(
   group: NavGroup,
   parentSlug: string = "",
   docs: any[],
-): Route[] {
+): Promise<Route[]> {
   let routes: Route[] = [];
   const groupSlug = slugify(group.group);
   const currentPrefix = parentSlug ? `${parentSlug}/${groupSlug}` : groupSlug;
 
-  group.pages.forEach((item) => {
+  for (const item of group.pages) {
     // Check if it's a simple page or a page object
     if (typeof item === "string" || "page" in item) {
-      routes.push(processPageItem(item as NavPageItem, currentPrefix, docs));
+      routes.push(processPageItem(item, currentPrefix, docs));
     } else if ("group" in item) {
       // Nested group
       routes = routes.concat(
-        processGroup(item as NavGroup, currentPrefix, docs),
+        await processGroup(item as NavGroup, currentPrefix, docs),
       );
+    } else if ("openapi" in item) {
+      routes.push(await processOpenApiPageItem(item, currentPrefix));
     }
-  });
-
-  return routes;
-}
-
-// Helper function to parse endpoint string (same as in validation.ts)
-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 };
+  return routes;
 }
 
 // Helper function to check if an endpoint matches include/exclude filters
@@ -156,7 +212,7 @@ function shouldIncludeEndpoint(
   // If include is specified, only include matching endpoints
   if (include) {
     return include.some((entry) => {
-      const parsed = parseEndpointString(entry);
+      const parsed = parseOpenApiEndpoint(entry);
       if (!parsed) return false;
       return `${parsed.method} ${parsed.path}` === endpointKey;
     });
@@ -165,7 +221,7 @@ function shouldIncludeEndpoint(
   // If exclude is specified, exclude matching endpoints
   if (exclude) {
     return !exclude.some((entry) => {
-      const parsed = parseEndpointString(entry);
+      const parsed = parseOpenApiEndpoint(entry);
       if (!parsed) return false;
       return `${parsed.method} ${parsed.path}` === endpointKey;
     });
@@ -180,8 +236,6 @@ async function processOpenApiFile(
   parentSlug: string = "",
 ): Promise<OpenApiRoute[]> {
   const routes: OpenApiRoute[] = [];
-  const CWD = process.cwd();
-  const DOCS_DIR = path.join(CWD, "src/content/docs");
 
   // Extract file path and filter options
   let openApiPath: string;
@@ -232,15 +286,7 @@ async function processOpenApiFile(
         continue;
       }
 
-      // Generate slug from path and method (guaranteed to be unique)
-      // e.g., "/burgers" + "get" -> "burgers-get"
-      const pathSlug = pathStr
-        .replace(/^\//, "") // Remove leading slash
-        .replace(/\//g, "-") // Replace slashes with hyphens
-        .replace(/\{[^}]+\}/g, "param"); // Replace path params like {id} with "param"
-
-      const methodSlug = slugify(method);
-      const endpointSlug = pathSlug ? `${pathSlug}-${methodSlug}` : methodSlug;
+      const endpointSlug = buildOpenApiEndpointSlug(pathStr, method);
       const fullSlug = parentSlug
         ? `${parentSlug}/${endpointSlug}`
         : endpointSlug;
@@ -277,15 +323,17 @@ async function processMenuItem(
 
   // Process pages if they exist (pages array can contain pages and groups)
   if (submenu.pages) {
-    submenu.pages.forEach((item) => {
+    for (const item of submenu.pages) {
       if (typeof item === "string" || "page" in item) {
-        routes.push(processPageItem(item as NavPageItem, currentPrefix, docs));
+        routes.push(processPageItem(item, currentPrefix, docs));
       } else if ("group" in item) {
         routes = routes.concat(
-          processGroup(item as NavGroup, currentPrefix, docs),
+          await processGroup(item as NavGroup, currentPrefix, docs),
         );
+      } else if ("openapi" in item) {
+        routes.push(await processOpenApiPageItem(item, currentPrefix));
       }
-    });
+    }
   }
 
   // Process OpenAPI file if it exists
@@ -300,6 +348,31 @@ async function processMenuItem(
   return routes;
 }
 
+function assertUniqueRouteSlugs(routes: Route[]): void {
+  const seenBySlug = new Map<string, Route>();
+
+  for (const route of routes) {
+    const existing = seenBySlug.get(route.slug);
+    if (!existing) {
+      seenBySlug.set(route.slug, route);
+      continue;
+    }
+
+    const existingLabel =
+      existing.type === "mdx"
+        ? `mdx:${existing.filePath}`
+        : `openapi:${existing.filePath}:${existing.openApiMethod.toUpperCase()} ${existing.openApiPath}`;
+    const candidateLabel =
+      route.type === "mdx"
+        ? `mdx:${route.filePath}`
+        : `openapi:${route.filePath}:${route.openApiMethod.toUpperCase()} ${route.openApiPath}`;
+
+    throw new Error(
+      `Duplicate route slug "${route.slug}" generated by "${existingLabel}" and "${candidateLabel}".`,
+    );
+  }
+}
+
 export async function getAllRoutes(): Promise<Route[]> {
   // 1. Get the validated config directly
   const config = await getConfig();
@@ -314,13 +387,15 @@ export async function getAllRoutes(): Promise<Route[]> {
   // We use the XOR guarantee from validateNavigation (only one key exists)
   if (navigation.pages) {
     // Case 1: Pages array at the top level (can contain pages and groups)
-    navigation.pages.forEach((item) => {
+    for (const item of navigation.pages) {
       if (typeof item === "string" || "page" in item) {
-        allRoutes.push(processPageItem(item as NavPageItem, "", docs));
+        allRoutes.push(processPageItem(item, "", docs));
       } else if ("group" in item) {
-        allRoutes = allRoutes.concat(processGroup(item as NavGroup, "", docs));
+        allRoutes = allRoutes.concat(await processGroup(item as NavGroup, "", docs));
+      } else if ("openapi" in item) {
+        allRoutes.push(await processOpenApiPageItem(item, ""));
       }
-    });
+    }
   } else if (navigation.menu) {
     // Case 3: Menu object at the top level
     // Need to await all menu items since processMenuItem is now async
@@ -330,5 +405,6 @@ export async function getAllRoutes(): Promise<Route[]> {
     }
   }
 
+  assertUniqueRouteSlugs(allRoutes);
   return allRoutes;
 }

package/template/src/lib/static-asset-url.ts

@@ -0,0 +1,62 @@
+type AssetsPrefixValue = string | Record<string, string> | undefined;
+
+function normalizePrefix(value: string): string {
+  const normalized = value.trim().replace(/\/+$/, "");
+  if (!normalized) return normalized;
+  if (hasProtocol(normalized) || normalized.startsWith("//")) {
+    return normalized;
+  }
+  if (normalized.startsWith("/")) {
+    return normalized;
+  }
+  return `https://${normalized}`;
+}
+
+function resolveAssetsPrefix(value: AssetsPrefixValue): string | null {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return normalizePrefix(value);
+  }
+
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const fallback = value.fallback;
+  if (typeof fallback === "string" && fallback.trim().length > 0) {
+    return normalizePrefix(fallback);
+  }
+
+  for (const candidate of Object.values(value)) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return normalizePrefix(candidate);
+    }
+  }
+
+  return null;
+}
+
+function hasProtocol(url: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url);
+}
+
+export function resolveStaticAssetUrl(rawPath: string): string {
+  const value = rawPath.trim();
+  if (!value) return value;
+
+  if (hasProtocol(value) || value.startsWith("//")) {
+    return value;
+  }
+
+  const parsed = new URL(value, "https://radiant.invalid");
+  const normalizedPathname = parsed.pathname.startsWith("/")
+    ? parsed.pathname
+    : `/${parsed.pathname}`;
+
+  const prefix = resolveAssetsPrefix(import.meta.env.ASSETS_PREFIX);
+  if (!prefix) {
+    return `${normalizedPathname}${parsed.search}${parsed.hash}`;
+  }
+
+  const normalizedPrefixPath = `${prefix}/${normalizedPathname.replace(/^\/+/, "")}`;
+  return `${normalizedPrefixPath}${parsed.search}${parsed.hash}`;
+}

package/template/src/lib/utils.ts

@@ -79,3 +79,51 @@ export function buildMdxPageHref(args: {
     ? `/${normalizedGroupSlug}/${pageSlug}`
     : `/${pageSlug}`;
 }
+
+export function parseOpenApiEndpoint(
+  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 openApiPath = parts[1];
+
+  if (!openApiPath.startsWith("/")) {
+    openApiPath = `/${openApiPath}`;
+  }
+
+  return {
+    method,
+    path: openApiPath.toLowerCase(),
+  };
+}
+
+export function buildOpenApiEndpointSlug(pathStr: string, method: string): string {
+  const normalizedPath = pathStr.startsWith("/") ? pathStr : `/${pathStr}`;
+  const pathSlug = normalizedPath
+    .replace(/^\//, "")
+    .replace(/\//g, "-")
+    .replace(/\{[^}]+\}/g, "param");
+  const methodSlug = slugify(method);
+  return pathSlug ? `${pathSlug}-${methodSlug}` : methodSlug;
+}
+
+export function buildOpenApiEndpointHref(args: {
+  path: string;
+  method: string;
+  groupSlug?: string;
+}): string {
+  const endpointSlug = buildOpenApiEndpointSlug(args.path, args.method);
+  const normalizedGroupSlug = (args.groupSlug || "")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+
+  return normalizedGroupSlug
+    ? `/${normalizedGroupSlug}/${endpointSlug}`
+    : `/${endpointSlug}`;
+}

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/src/pages/404.astro

@@ -0,0 +1,44 @@
+---
+import { Icon } from "astro-icon/components";
+import Layout from "../layouts/Layout.astro";
+---
+
+<Layout
+  pageTitle="Page not found"
+  pageDescription="The page you requested could not be found."
+>
+  <section
+    class="mx-auto mt-8 h-full my-auto flex max-w-xl flex-col items-center gap-5 rounded-2xl bg-background px-6 py-10 text-center"
+  >
+    <p
+      class="font-mono text-sm font-medium tracking-[0.22em] text-neutral-500 uppercase dark:text-neutral-400 border px-1 py-px pr-0.5 rounded"
+    >
+      404
+    </p>
+    <h1
+      class="text-3xl font-semibold tracking-tight text-neutral-900 dark:text-neutral-50"
+    >
+      Page not found
+    </h1>
+    <p class="max-w-md text-sm text-neutral-600 dark:text-neutral-300">
+      The page may have moved, or the URL may be incorrect.
+    </p>
+    <div class="flex flex-wrap items-center justify-center gap-3">
+      <button
+        type="button"
+        class="inline-flex items-center justify-center gap-1.5 rounded-lg [corner-shape:superellipse(1.2)] border shadow-xs px-4 py-2 text-sm font-medium text-neutral-700/85 hover:text-neutral-700 cursor-pointer"
+        onclick="history.back()"
+      >
+        <Icon name="lucide:arrow-big-left-dash" class="size-4" />
+        Go back
+      </button>
+      <a
+        href="/"
+        class="inline-flex items-center justify-center gap-2 rounded-lg [corner-shape:superellipse(1.2)] border border-border px-4 py-2 text-sm font-[350] dark:font-[450] text-white bg-linear-to-b from-neutral-900/85 to-neutral-900 dark:from-neutral-100 dark:to-neutral-200 shadow-sm"
+      >
+        <Icon name="lucide:house" class="size-4" />
+        Take me home
+      </a>
+    </div>
+  </section>
+</Layout>