radiant-docs 0.1.56 → 0.1.57

package/template/src/lib/routes.ts

@@ -9,11 +9,16 @@ import {
   loadOpenApiSpec,
 } from "./validation";
 import {
+  buildMdxPageFallbackSlug,
+  buildMdxPageSlug,
   buildOpenApiEndpointSlug,
+  buildOpenApiEndpointFallbackSlug,
+  createRouteSlugRegistry,
   deriveTitleFromEntryId,
   parseOpenApiEndpoint,
   slugify,
 } from "./utils";
+import { prependBasePath, withBasePath } from "./base-path";
 import { getCollection } from "astro:content";
 
 type MdxNavPageItem = string | NavPage;
@@ -21,6 +26,9 @@ type MdxNavPageItem = string | NavPage;
 // Base route interface
 export interface BaseRoute {
   slug: string;
+  preferredSlug: string;
+  fallbackSlug?: string;
+  routeIdentity: string;
   title: string;
   hidden?: boolean;
 }
@@ -56,7 +64,9 @@ export function resolveMdxPageTitle(args: {
   const frontmatterTitle = normalizeTitle(args.entry?.data?.title);
   const docsJsonTitle = normalizeTitle(args.docsTitle);
 
-  return frontmatterTitle || docsJsonTitle || deriveTitleFromEntryId(args.filePath);
+  return (
+    frontmatterTitle || docsJsonTitle || deriveTitleFromEntryId(args.filePath)
+  );
 }
 
 function processPageItem(
@@ -65,9 +75,10 @@ function processPageItem(
   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;
+  const preferredSlug = buildMdxPageSlug({
+    filePath,
+    groupSlug: parentSlug,
+  });
 
   // Find the entry matching this filePath
   const entry = docs.find((doc: any) => {
@@ -91,16 +102,19 @@ function processPageItem(
 
   return {
     type: "mdx",
-    slug: fullSlug,
+    slug: preferredSlug,
+    preferredSlug,
+    fallbackSlug: buildMdxPageFallbackSlug({
+      filePath,
+      groupSlug: parentSlug,
+    }),
+    routeIdentity: `mdx:${filePath}`,
     filePath: filePath,
     title: title,
   };
 }
 
-function processHiddenPageRoute(
-  route: HiddenPageRoute,
-  docs: any[],
-): MdxRoute {
+function processHiddenPageRoute(route: HiddenPageRoute, docs: any[]): MdxRoute {
   const entry = docs.find((doc: any) => {
     const docPath = doc.id.replace(/\.mdx$/, "");
     return docPath === route.filePath;
@@ -117,6 +131,12 @@ function processHiddenPageRoute(
   return {
     type: "mdx",
     slug,
+    preferredSlug: slug,
+    fallbackSlug: buildMdxPageFallbackSlug({
+      filePath: route.filePath,
+      groupSlug: "",
+    }),
+    routeIdentity: `mdx:${route.filePath}`,
     filePath: route.filePath,
     title: resolveMdxPageTitle({
       entry,
@@ -195,6 +215,14 @@ async function processOpenApiPageItem(
   return {
     type: "openapi",
     slug: fullSlug,
+    preferredSlug: fullSlug,
+    fallbackSlug: buildOpenApiEndpointFallbackSlug({
+      source: item.openapi.source,
+      path: matchedOperation.path,
+      method: matchedOperation.method,
+      groupSlug: parentSlug,
+    }),
+    routeIdentity: `openapi:${item.openapi.source}:${matchedOperation.method.toUpperCase()} ${matchedOperation.path.toLowerCase()}`,
     filePath: item.openapi.source,
     title,
     openApiPath: matchedOperation.path,
@@ -328,6 +356,14 @@ async function processOpenApiFile(
       routes.push({
         type: "openapi",
         slug: fullSlug,
+        preferredSlug: fullSlug,
+        fallbackSlug: buildOpenApiEndpointFallbackSlug({
+          source: openApiPath,
+          path: pathStr,
+          method,
+          groupSlug: parentSlug,
+        }),
+        routeIdentity: `openapi:${openApiPath}:${method.toUpperCase()} ${pathStr.toLowerCase()}`,
         filePath: openApiPath,
         title: title,
         openApiPath: pathStr,
@@ -379,29 +415,28 @@ async function processMenuItem(
   return routes;
 }
 
-function assertUniqueRouteSlugs(routes: Route[]): void {
-  const seenBySlug = new Map<string, Route>();
+function resolveRouteSlugs(routes: Route[]): Route[] {
+  const registry = createRouteSlugRegistry();
+  const resolvedRoutes: Route[] = [];
 
   for (const route of routes) {
-    const existing = seenBySlug.get(route.slug);
-    if (!existing) {
-      seenBySlug.set(route.slug, route);
+    const registered = registry.register({
+      preferredSlug: route.preferredSlug,
+      fallbackSlug: route.fallbackSlug,
+      identity: route.routeIdentity,
+    });
+
+    if (registered.duplicate) {
       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(
-      `[USER_ERROR]: Invalid docs.json: Duplicate route slug "${route.slug}" generated by "${existingLabel}" and "${candidateLabel}". Remove one of the duplicate references or change navigation structure so each route resolves to a unique URL.`,
-    );
+    resolvedRoutes.push({
+      ...route,
+      slug: registered.slug,
+    });
   }
+
+  return resolvedRoutes;
 }
 
 export async function getAllRoutes(): Promise<Route[]> {
@@ -422,7 +457,9 @@ export async function getAllRoutes(): Promise<Route[]> {
       if (typeof item === "string" || "page" in item) {
         allRoutes.push(processPageItem(item, "", docs));
       } else if ("group" in item) {
-        allRoutes = allRoutes.concat(await processGroup(item as NavGroup, "", docs));
+        allRoutes = allRoutes.concat(
+          await processGroup(item as NavGroup, "", docs),
+        );
       } else if ("openapi" in item) {
         allRoutes.push(await processOpenApiPageItem(item, ""));
       }
@@ -434,6 +471,9 @@ export async function getAllRoutes(): Promise<Route[]> {
       const menuItemRoutes = await processMenuItem(menuItem, "", docs);
       allRoutes = allRoutes.concat(menuItemRoutes);
     }
+  } else if (navigation.openapi) {
+    const openApiRoutes = await processOpenApiFile(navigation.openapi, "");
+    allRoutes = allRoutes.concat(openApiRoutes);
   }
 
   for (const hiddenPageRoute of config.hiddenPageRoutes ?? []) {
@@ -453,6 +493,87 @@ export async function getAllRoutes(): Promise<Route[]> {
     allRoutes.push(hiddenRoute);
   }
 
-  assertUniqueRouteSlugs(allRoutes);
-  return allRoutes;
+  return resolveRouteSlugs(allRoutes);
+}
+
+export async function getMdxRouteHref(args: {
+  filePath: string;
+  groupSlug?: string;
+  homePath?: string;
+  preferredSlug?: string;
+}): Promise<string> {
+  if (!args.preferredSlug && args.homePath && args.filePath === args.homePath) {
+    return prependBasePath("/");
+  }
+
+  const preferredSlug =
+    args.preferredSlug?.replace(/^\/+/, "").replace(/\/+$/, "") ||
+    buildMdxPageSlug({
+      filePath: args.filePath,
+      groupSlug: args.groupSlug,
+    });
+  const routes = await getAllRoutes();
+  const route = routes.find(
+    (candidate) =>
+      candidate.type === "mdx" &&
+      candidate.filePath === args.filePath &&
+      candidate.preferredSlug === preferredSlug,
+  );
+
+  return prependBasePath(`/${route?.slug ?? preferredSlug}`);
+}
+
+export async function resolveConfiguredHref(
+  href: string,
+  hiddenPageRoutes: HiddenPageRoute[] | undefined,
+): Promise<string> {
+  const normalizedHref = href.replace(/^\/+/, "").replace(/\/+$/, "");
+  const hiddenPageRoute = hiddenPageRoutes?.find(
+    (route) => route.href.replace(/^\/+/, "").replace(/\/+$/, "") === normalizedHref,
+  );
+
+  if (!hiddenPageRoute) {
+    return withBasePath(href);
+  }
+
+  return getMdxRouteHref({
+    filePath: hiddenPageRoute.filePath,
+    preferredSlug: hiddenPageRoute.href,
+  });
+}
+
+export async function getOpenApiEndpointRouteHref(args: {
+  source: string;
+  path: string;
+  method: string;
+  groupSlug?: string;
+}): Promise<string> {
+  const endpointSlug = buildOpenApiEndpointSlug(args.path, args.method);
+  const normalizedGroupSlug = (args.groupSlug || "")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+  const preferredSlug = normalizedGroupSlug
+    ? `${normalizedGroupSlug}/${endpointSlug}`
+    : endpointSlug;
+  const config = await getConfig();
+  const routes = await getAllRoutes();
+  const visibleRoutes = routes.filter((candidate) => !candidate.hidden);
+  const route = routes.find(
+    (candidate) =>
+      candidate.type === "openapi" &&
+      candidate.filePath === args.source &&
+      candidate.openApiMethod.toLowerCase() === args.method.toLowerCase() &&
+      candidate.openApiPath.toLowerCase() === args.path.toLowerCase() &&
+      candidate.preferredSlug === preferredSlug,
+  );
+
+  if (
+    route &&
+    !config.home &&
+    visibleRoutes[0] === route
+  ) {
+    return prependBasePath("/");
+  }
+
+  return prependBasePath(`/${route?.slug ?? preferredSlug}`);
 }

package/template/src/lib/utils.ts

@@ -61,6 +61,38 @@ export function deriveTitleFromEntryId(filePath: string): string {
   );
 }
 
+function normalizeSlugPath(value: string): string {
+  return value.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+export function buildMdxPageSlug(args: {
+  filePath: string;
+  groupSlug?: string;
+}): string {
+  const filename = path.basename(args.filePath);
+  const pageSlug = slugify(filename);
+  const normalizedGroupSlug = normalizeSlugPath(args.groupSlug || "");
+
+  return normalizedGroupSlug ? `${normalizedGroupSlug}/${pageSlug}` : pageSlug;
+}
+
+export function buildMdxPageFallbackSlug(args: {
+  filePath: string;
+  groupSlug?: string;
+}): string {
+  const pathSlug = args.filePath
+    .split(/[\\/]+/)
+    .map((segment) => slugify(segment.replace(/\.(md|mdx)$/i, "")))
+    .filter(Boolean)
+    .join("-");
+  const normalizedGroupSlug = normalizeSlugPath(args.groupSlug || "");
+  const fallbackSlug = pathSlug || buildMdxPageSlug(args);
+
+  return normalizedGroupSlug
+    ? `${normalizedGroupSlug}/${fallbackSlug}`
+    : fallbackSlug;
+}
+
 export function buildMdxPageHref(args: {
   filePath: string;
   groupSlug?: string;
@@ -70,15 +102,7 @@ export function buildMdxPageHref(args: {
     return prependBasePath("/");
   }
 
-  const filename = path.basename(args.filePath);
-  const pageSlug = slugify(filename);
-  const normalizedGroupSlug = (args.groupSlug || "")
-    .replace(/^\/+/, "")
-    .replace(/\/+$/, "");
-
-  const href = normalizedGroupSlug
-    ? `/${normalizedGroupSlug}/${pageSlug}`
-    : `/${pageSlug}`;
+  const href = `/${buildMdxPageSlug(args)}`;
 
   return prependBasePath(href);
 }
@@ -119,15 +143,35 @@ export function buildOpenApiEndpointSlug(
   return pathSlug ? `${pathSlug}-${methodSlug}` : methodSlug;
 }
 
+export function buildOpenApiEndpointFallbackSlug(args: {
+  source: string;
+  path: string;
+  method: string;
+  groupSlug?: string;
+}): string {
+  const sourceSlug =
+    args.source
+      .replace(/\.(json|ya?ml)$/i, "")
+      .split(/[\\/]+/)
+      .map((segment) => slugify(segment))
+      .filter(Boolean)
+      .join("-") || "openapi";
+  const endpointSlug = buildOpenApiEndpointSlug(args.path, args.method);
+  const normalizedGroupSlug = normalizeSlugPath(args.groupSlug || "");
+  const fallbackSlug = `${sourceSlug}-${endpointSlug}`;
+
+  return normalizedGroupSlug
+    ? `${normalizedGroupSlug}/${fallbackSlug}`
+    : fallbackSlug;
+}
+
 export function buildOpenApiEndpointHref(args: {
   path: string;
   method: string;
   groupSlug?: string;
 }): string {
   const endpointSlug = buildOpenApiEndpointSlug(args.path, args.method);
-  const normalizedGroupSlug = (args.groupSlug || "")
-    .replace(/^\/+/, "")
-    .replace(/\/+$/, "");
+  const normalizedGroupSlug = normalizeSlugPath(args.groupSlug || "");
 
   const href = normalizedGroupSlug
     ? `/${normalizedGroupSlug}/${endpointSlug}`
@@ -135,3 +179,74 @@ export function buildOpenApiEndpointHref(args: {
 
   return prependBasePath(href);
 }
+
+export type RouteSlugRegistration = {
+  preferredSlug: string;
+  fallbackSlug?: string;
+  identity: string;
+};
+
+export function createRouteSlugRegistry() {
+  const slugIdentityBySlug = new Map<string, string>();
+  const slugByExactRoute = new Map<string, string>();
+
+  function normalizeCandidate(value: string | undefined): string {
+    const normalized = normalizeSlugPath(value || "");
+    return normalized || "page";
+  }
+
+  function nextAvailableSlug(baseSlug: string): string {
+    let index = 2;
+    let candidate = baseSlug;
+
+    while (slugIdentityBySlug.has(candidate)) {
+      candidate = `${baseSlug}-${index}`;
+      index += 1;
+    }
+
+    return candidate;
+  }
+
+  return {
+    register({ preferredSlug, fallbackSlug, identity }: RouteSlugRegistration) {
+      const preferred = normalizeCandidate(preferredSlug);
+      const exactKey = `${preferred}\0${identity}`;
+      const existingExactSlug = slugByExactRoute.get(exactKey);
+
+      if (existingExactSlug) {
+        return {
+          slug: existingExactSlug,
+          duplicate: true,
+        };
+      }
+
+      const preferredIdentity = slugIdentityBySlug.get(preferred);
+      if (!preferredIdentity) {
+        slugIdentityBySlug.set(preferred, identity);
+        slugByExactRoute.set(exactKey, preferred);
+        return {
+          slug: preferred,
+          duplicate: false,
+        };
+      }
+
+      if (preferredIdentity === identity) {
+        slugByExactRoute.set(exactKey, preferred);
+        return {
+          slug: preferred,
+          duplicate: true,
+        };
+      }
+
+      const fallbackBase = normalizeCandidate(fallbackSlug || preferred);
+      const resolvedSlug = nextAvailableSlug(fallbackBase);
+      slugIdentityBySlug.set(resolvedSlug, identity);
+      slugByExactRoute.set(exactKey, resolvedSlug);
+
+      return {
+        slug: resolvedSlug,
+        duplicate: false,
+      };
+    },
+  };
+}