radiant-docs 0.1.0

package/template/src/lib/routes.ts

@@ -0,0 +1,316 @@
+import {
+  getConfig,
+  type NavGroup,
+  type NavPage,
+  type NavMenuItem,
+  type NavOpenApi,
+  loadOpenApiSpec,
+} from "./validation";
+import { deriveTitleFromEntryId, slugify } from "./utils";
+import path from "node:path";
+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;
+
+// Base route interface
+export interface BaseRoute {
+  slug: string;
+  title: string;
+}
+
+// MDX route
+export interface MdxRoute extends BaseRoute {
+  type: "mdx";
+  filePath: string; // e.g., "quickstart" or "writing-content/text"
+}
+
+// OpenAPI route
+export interface OpenApiRoute extends BaseRoute {
+  type: "openapi";
+  filePath: string; // e.g., "open-api/open-api.json"
+  openApiPath: string; // e.g., "/burgers"
+  openApiMethod: string; // e.g., "get"
+}
+
+// Discriminated union
+export type Route = MdxRoute | OpenApiRoute;
+
+function processPageItem(
+  item: NavPageItem,
+  parentSlug: string = "",
+  docs: any[]
+): MdxRoute {
+  const filePath = typeof item === "string" ? item : item.page;
+  const filename = filePath.split("/").pop() || filePath;
+  const pageSlug = slugify(filename);
+  const fullSlug = parentSlug ? `${parentSlug}/${pageSlug}` : pageSlug;
+
+  // Find the entry matching this filePath
+  const entry = docs.find((doc: any) => {
+    const docPath = doc.id.replace(/\.mdx$/, "");
+    return docPath === filePath;
+  });
+
+  if (!entry) {
+    throw new Error(
+      `Could not find content collection entry for path: ${filePath}`
+    );
+  }
+
+  // Get title from frontmatter
+  const title = entry.data.title || deriveTitleFromEntryId(entry.filePath);
+
+  return {
+    type: "mdx",
+    slug: fullSlug,
+    filePath: filePath,
+    title: title,
+  };
+}
+
+function processGroup(
+  group: NavGroup,
+  parentSlug: string = "",
+  docs: any[]
+): Route[] {
+  let routes: Route[] = [];
+  const groupSlug = slugify(group.group);
+  const currentPrefix = parentSlug ? `${parentSlug}/${groupSlug}` : groupSlug;
+
+  group.pages.forEach((item) => {
+    // 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));
+    } else if ("group" in item) {
+      // Nested group
+      routes = routes.concat(
+        processGroup(item as NavGroup, currentPrefix, docs)
+      );
+    }
+  });
+
+  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 };
+}
+
+// Helper function to check if an endpoint matches include/exclude filters
+function shouldIncludeEndpoint(
+  method: string,
+  pathStr: string,
+  include?: string[],
+  exclude?: string[]
+): boolean {
+  // Normalize for comparison
+  const normalizedMethod = method.toUpperCase();
+  const normalizedPath = pathStr.toLowerCase();
+  const endpointKey = `${normalizedMethod} ${normalizedPath}`;
+
+  // If include is specified, only include matching endpoints
+  if (include) {
+    return include.some((entry) => {
+      const parsed = parseEndpointString(entry);
+      if (!parsed) return false;
+      return `${parsed.method} ${parsed.path}` === endpointKey;
+    });
+  }
+
+  // If exclude is specified, exclude matching endpoints
+  if (exclude) {
+    return !exclude.some((entry) => {
+      const parsed = parseEndpointString(entry);
+      if (!parsed) return false;
+      return `${parsed.method} ${parsed.path}` === endpointKey;
+    });
+  }
+
+  // If neither include nor exclude, include all endpoints
+  return true;
+}
+
+async function processOpenApiFile(
+  openApiPathOrConfig: string | NavOpenApi,
+  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;
+  let include: string[] | undefined;
+  let exclude: string[] | undefined;
+
+  if (typeof openApiPathOrConfig === "string") {
+    openApiPath = openApiPathOrConfig;
+  } else {
+    openApiPath = openApiPathOrConfig.source;
+    include = openApiPathOrConfig.include;
+    exclude = openApiPathOrConfig.exclude;
+  }
+
+  // Load and parse the OpenAPI file using the shared function
+  let openApiDoc: any;
+  try {
+    openApiDoc = await loadOpenApiSpec(openApiPath);
+  } catch (error) {
+    // If loading fails (e.g., file doesn't exist or URL is invalid), return empty routes
+    return routes;
+  }
+
+  // Extract paths from the OpenAPI document
+  const paths = openApiDoc.paths || {};
+  const httpMethods = [
+    "get",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "head",
+    "options",
+    "trace",
+  ];
+
+  // Iterate through each path
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+
+    // Iterate through each HTTP method in the path
+    for (const method of httpMethods) {
+      const operation = (pathItem as any)[method];
+      if (!operation) continue;
+
+      // Check if this endpoint should be included based on filters
+      if (!shouldIncludeEndpoint(method, pathStr, include, exclude)) {
+        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 fullSlug = parentSlug
+        ? `${parentSlug}/${endpointSlug}`
+        : endpointSlug;
+
+      // Use summary for title (more user-friendly), fallback to path + method
+      const title = operation.summary || `${method.toUpperCase()} ${pathStr}`;
+
+      routes.push({
+        type: "openapi",
+        slug: fullSlug,
+        filePath: openApiPath,
+        title: title,
+        openApiPath: pathStr,
+        openApiMethod: method,
+      });
+    }
+  }
+
+  return routes;
+}
+
+async function processMenuItem(
+  menuItem: NavMenuItem,
+  parentSlug: string = "",
+  docs: any[]
+): Promise<Route[]> {
+  let routes: Route[] = [];
+  const menuItemSlug = slugify(menuItem.label);
+  const currentPrefix = parentSlug
+    ? `${parentSlug}/${menuItemSlug}`
+    : menuItemSlug;
+
+  const submenu = menuItem.submenu;
+
+  // Process pages if they exist
+  if (submenu.pages) {
+    submenu.pages.forEach((page) => {
+      routes.push(processPageItem(page, currentPrefix, docs));
+    });
+  }
+
+  // Process groups if they exist
+  if (submenu.groups) {
+    submenu.groups.forEach((group) => {
+      routes = routes.concat(processGroup(group, currentPrefix, docs));
+    });
+  }
+
+  // Process OpenAPI file if it exists
+  if (submenu.openapi) {
+    const openApiRoutes = await processOpenApiFile(
+      submenu.openapi,
+      currentPrefix
+    );
+    routes = routes.concat(openApiRoutes);
+  }
+
+  return routes;
+}
+
+export async function getAllRoutes(): Promise<Route[]> {
+  // 1. Get the validated config directly
+  const config = await getConfig();
+  const navigation = config.navigation;
+
+  // 2. Load the docs collection to access frontmatter
+  const docs = await getCollection("docs");
+
+  let allRoutes: Route[] = [];
+
+  // 3. Identify the active navigation container (pages, groups, or menu)
+  // We use the XOR guarantee from validateNavigation (only one key exists)
+  if (navigation.pages) {
+    // Case 1: Simple pages array at the top level
+    navigation.pages.forEach((item) => {
+      // items are guaranteed to be string | NavPage
+      allRoutes.push(processPageItem(item, "", docs));
+    });
+  } else if (navigation.groups) {
+    // Case 2: Groups array at the top level
+    navigation.groups.forEach((group) => {
+      // items are guaranteed to be NavGroup
+      allRoutes = allRoutes.concat(processGroup(group, "", docs));
+    });
+  } else if (navigation.menu) {
+    // Case 3: Menu object at the top level
+    // Need to await all menu items since processMenuItem is now async
+    for (const menuItem of navigation.menu.items) {
+      const menuItemRoutes = await processMenuItem(menuItem, "", docs);
+      allRoutes = allRoutes.concat(menuItemRoutes);
+    }
+  }
+
+  return allRoutes;
+}

package/template/src/lib/utils.ts

@@ -0,0 +1,59 @@
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkRehype from "remark-rehype";
+import rehypeStringify from "rehype-stringify";
+import path from "node:path";
+
+export function slugify(text: string): string {
+  if (typeof text !== "string") {
+    return "";
+  }
+  return text
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^\w\-]+/g, "")
+    .replace(/\-\-+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "");
+}
+
+export async function renderMarkdown(markdown: string): Promise<string> {
+  if (!markdown) return "";
+
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkGfm) // GitHub Flavored Markdown (for lists, etc.)
+    .use(remarkRehype, { allowDangerousHtml: false })
+    .use(rehypeStringify)
+    .process(markdown);
+
+  return result.toString();
+}
+
+export const methodColors: Record<string, string> = {
+  get: "bg-blue-50 dark:bg-blue-900 text-blue-700/70 dark:text-blue-200 border-blue-700/10",
+  post: "bg-green-50 dark:bg-green-900 text-green-700/70 dark:text-green-200 border-green-700/10",
+  put: "bg-orange-50 dark:bg-orange-900 text-orange-700/70 dark:text-orange-700/10 border-orange-700/10",
+  patch:
+    "bg-yellow-50 dark:bg-yellow-900 text-yellow-700/70 dark:text-yellow-700/10 border-yellow-700/10",
+  delete:
+    "bg-red-50 dark:bg-red-900 text-red-700/70 dark:text-red-700/10 border-red-700/10",
+};
+
+export function deriveTitleFromEntryId(filePath: string): string {
+  const filename = path.basename(filePath);
+  const raw = filename.replace(/\.(md|mdx)$/i, "");
+
+  // Capitalize and replace dashes
+  return (
+    raw
+      .split(/[-_]/)
+      .map((segment) => {
+        if (!segment) return segment;
+        return segment.charAt(0).toUpperCase() + segment.slice(1);
+      })
+      .join(" ")
+      .trim() || "Untitled"
+  );
+}