radiant-docs 0.1.61 → 0.1.63

package/template/src/lib/mdx/remark-resolve-internal-links.ts

@@ -9,10 +9,12 @@ import {
   resolveDocsHref,
   type DocsConfig,
   type NavGroup,
+  type NavMenu,
   type NavMenuItem,
   type NavOpenApi,
   type NavOpenApiPage,
   type NavPage,
+  type NavTabItem,
 } from "../validation";
 import { prependBasePath, withBasePath } from "../base-path";
 import {
@@ -26,6 +28,11 @@ import {
 } from "../utils";
 
 type MdxNavItem = string | NavPage | NavGroup | NavOpenApiPage;
+type NavigationContentContainer = {
+  pages?: MdxNavItem[];
+  menu?: NavMenu;
+  openapi?: string | NavOpenApi;
+};
 
 type AuxiliaryPageRef = {
   filePath: string;
@@ -36,9 +43,24 @@ type DocsConfigWithAuxiliaryRefs = DocsConfig & {
   auxiliaryPageRefs?: AuxiliaryPageRef[];
 };
 
+type OpenApiEndpointLinkRef = {
+  source?: string;
+  method: string;
+  path: string;
+  endpoint: string;
+};
+
+type OpenApiEndpointRouteTarget = OpenApiEndpointLinkRef & {
+  source: string;
+  targetKey: string;
+};
+
 type ResolvedRouteIndex = {
   canonicalHrefByFilePath: Map<string, string>;
   allHrefsByFilePath: Map<string, string[]>;
+  canonicalHrefByOpenApiEndpointKey: Map<string, string>;
+  allHrefsByOpenApiEndpointKey: Map<string, string[]>;
+  openApiEndpointTargetsByEndpoint: Map<string, OpenApiEndpointRouteTarget[]>;
   validRoutePaths: Set<string>;
   allDocsFilePaths: Set<string>;
   routeSlugs: ReturnType<typeof createRouteSlugRegistry>;
@@ -76,10 +98,24 @@ const HTTP_METHODS = [
   "options",
   "trace",
 ];
+const HTTP_METHOD_SET = new Set<string>(HTTP_METHODS);
 
 let cachedRouteIndex: ResolvedRouteIndex | null = null;
 let cachedConfig: DocsConfig | null = null;
 
+function isUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function containsPathTraversal(value: string): boolean {
+  return value.replace(/\\/g, "/").split("/").includes("..");
+}
+
 function normalizeDocsFilePath(value: string): string {
   let normalized = value.replace(/\\/g, "/").trim();
   if (!normalized) return "";
@@ -94,6 +130,102 @@ function normalizeDocsFilePath(value: string): string {
   return posixNormalized === "." ? "" : posixNormalized;
 }
 
+function normalizeOpenApiLinkSource(source: string): string {
+  const trimmedSource = source.trim();
+  if (isUrl(trimmedSource)) {
+    return trimmedSource;
+  }
+
+  let normalizedSource = trimmedSource.replace(/\\/g, "/").trim();
+  normalizedSource = normalizedSource.replace(/^\/+/, "").replace(/\/+$/, "");
+  normalizedSource = normalizedSource.replace(/^src\/content\/docs\//, "");
+
+  const posixNormalized = path.posix
+    .normalize(`/${normalizedSource}`)
+    .replace(/^\/+/, "");
+
+  return posixNormalized === "." ? "" : posixNormalized;
+}
+
+function formatOpenApiEndpoint(
+  method: string,
+  endpointPath: string,
+): string {
+  return `${method.toUpperCase()} ${endpointPath.toLowerCase()}`;
+}
+
+function formatOpenApiEndpointTargetKey(
+  source: string,
+  method: string,
+  endpointPath: string,
+): string {
+  return `${normalizeOpenApiLinkSource(source)}\0${formatOpenApiEndpoint(
+    method,
+    endpointPath,
+  )}`;
+}
+
+function parseOpenApiEndpointLinkEndpoint(
+  endpointStr: string,
+): Pick<OpenApiEndpointLinkRef, "method" | "path" | "endpoint"> | null {
+  const trimmed = endpointStr.trim();
+  const parts = trimmed.split(/\s+/);
+
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const method = parts[0].toUpperCase();
+  const endpointPath = parts[1];
+  if (
+    !HTTP_METHOD_SET.has(method.toLowerCase()) ||
+    !endpointPath.startsWith("/")
+  ) {
+    return null;
+  }
+
+  const normalizedPath = endpointPath.toLowerCase();
+  return {
+    method,
+    path: normalizedPath,
+    endpoint: formatOpenApiEndpoint(method, normalizedPath),
+  };
+}
+
+function parseOpenApiEndpointLinkHref(
+  href: string,
+): OpenApiEndpointLinkRef | null {
+  const trimmedHref = href.trim();
+  if (!trimmedHref) return null;
+
+  const hashIndex = trimmedHref.indexOf("#");
+  if (hashIndex > 0) {
+    const rawSource = trimmedHref.slice(0, hashIndex).trim();
+    if (!isUrl(rawSource) && containsPathTraversal(rawSource)) {
+      return null;
+    }
+
+    const source = normalizeOpenApiLinkSource(rawSource);
+    if (!source) {
+      return null;
+    }
+
+    const parsedEndpoint = parseOpenApiEndpointLinkEndpoint(
+      trimmedHref.slice(hashIndex + 1),
+    );
+    if (!parsedEndpoint) {
+      return null;
+    }
+
+    return {
+      source,
+      ...parsedEndpoint,
+    };
+  }
+
+  return parseOpenApiEndpointLinkEndpoint(trimmedHref);
+}
+
 function normalizeRoutePath(value: string): string {
   const trimmed = value.trim();
   if (!trimmed || trimmed === "/") {
@@ -208,6 +340,38 @@ function addMdxRoute(args: {
   args.index.allHrefsByFilePath.set(normalizedFilePath, aliases);
 }
 
+function createOpenApiEndpointRouteTarget(args: {
+  source: string;
+  method: string;
+  endpointPath: string;
+}): OpenApiEndpointRouteTarget {
+  const source = normalizeOpenApiLinkSource(args.source);
+  const endpoint = formatOpenApiEndpoint(args.method, args.endpointPath);
+
+  return {
+    source,
+    method: args.method.toUpperCase(),
+    path: args.endpointPath.toLowerCase(),
+    endpoint,
+    targetKey: formatOpenApiEndpointTargetKey(
+      source,
+      args.method,
+      args.endpointPath,
+    ),
+  };
+}
+
+function addOpenApiEndpointTargetToMap(
+  map: Map<string, OpenApiEndpointRouteTarget[]>,
+  target: OpenApiEndpointRouteTarget,
+): void {
+  const targets = map.get(target.endpoint) ?? [];
+  if (!targets.some((candidate) => candidate.targetKey === target.targetKey)) {
+    targets.push(target);
+  }
+  map.set(target.endpoint, targets);
+}
+
 function addOpenApiEndpointRoute(args: {
   index: ResolvedRouteIndex;
   parentSlug: string;
@@ -232,10 +396,30 @@ function addOpenApiEndpointRoute(args: {
     }),
     identity: `openapi:${args.source}:${args.method.toUpperCase()} ${args.endpointPath.toLowerCase()}`,
   }).slug;
-  addValidRoutePath(
+  const href = addValidRoutePath(
     args.index,
     prependBasePath(`/${registeredSlug}`),
   );
+  const target = createOpenApiEndpointRouteTarget({
+    source: args.source,
+    method: args.method,
+    endpointPath: args.endpointPath,
+  });
+
+  if (!args.index.canonicalHrefByOpenApiEndpointKey.has(target.targetKey)) {
+    args.index.canonicalHrefByOpenApiEndpointKey.set(target.targetKey, href);
+  }
+
+  const aliases =
+    args.index.allHrefsByOpenApiEndpointKey.get(target.targetKey) ?? [];
+  if (!aliases.includes(href)) {
+    aliases.push(href);
+  }
+  args.index.allHrefsByOpenApiEndpointKey.set(target.targetKey, aliases);
+  addOpenApiEndpointTargetToMap(
+    args.index.openApiEndpointTargetsByEndpoint,
+    target,
+  );
 }
 
 function addAuxiliaryPageRef(
@@ -414,27 +598,69 @@ async function processMenuItems(args: {
   index: ResolvedRouteIndex;
   homePath: string | null;
   items: NavMenuItem[];
+  parentSlug?: string;
 }): Promise<void> {
   for (const menuItem of args.items) {
     const menuSlug = slugify(menuItem.label);
-    const parentSlug = menuSlug;
+    const parentSlug = args.parentSlug
+      ? `${args.parentSlug}/${menuSlug}`
+      : menuSlug;
+
+    await processNavigationContent({
+      index: args.index,
+      parentSlug,
+      homePath: args.homePath,
+      item: menuItem,
+    });
+  }
+}
 
-    if (Array.isArray(menuItem.submenu.pages)) {
-      await processPages({
-        index: args.index,
-        parentSlug,
-        homePath: args.homePath,
-        items: menuItem.submenu.pages as MdxNavItem[],
-      });
-    }
+async function processTabItems(args: {
+  index: ResolvedRouteIndex;
+  homePath: string | null;
+  items: NavTabItem[];
+}): Promise<void> {
+  for (const tabItem of args.items) {
+    const tabSlug = slugify(tabItem.slug || tabItem.label);
+    await processNavigationContent({
+      index: args.index,
+      parentSlug: tabSlug,
+      homePath: args.homePath,
+      item: tabItem,
+    });
+  }
+}
 
-    if (menuItem.submenu.openapi) {
-      await processOpenApiFile({
-        index: args.index,
-        parentSlug,
-        openApiPathOrConfig: menuItem.submenu.openapi,
-      });
-    }
+async function processNavigationContent(args: {
+  index: ResolvedRouteIndex;
+  parentSlug: string;
+  homePath: string | null;
+  item: NavigationContentContainer;
+}): Promise<void> {
+  if (Array.isArray(args.item.pages)) {
+    await processPages({
+      index: args.index,
+      parentSlug: args.parentSlug,
+      homePath: args.homePath,
+      items: args.item.pages as MdxNavItem[],
+    });
+  }
+
+  if (args.item.menu?.items) {
+    await processMenuItems({
+      index: args.index,
+      parentSlug: args.parentSlug,
+      homePath: args.homePath,
+      items: args.item.menu.items,
+    });
+  }
+
+  if (args.item.openapi) {
+    await processOpenApiFile({
+      index: args.index,
+      parentSlug: args.parentSlug,
+      openApiPathOrConfig: args.item.openapi,
+    });
   }
 }
 
@@ -444,6 +670,12 @@ async function buildRouteIndex(
   const index: ResolvedRouteIndex = {
     canonicalHrefByFilePath: new Map<string, string>(),
     allHrefsByFilePath: new Map<string, string[]>(),
+    canonicalHrefByOpenApiEndpointKey: new Map<string, string>(),
+    allHrefsByOpenApiEndpointKey: new Map<string, string[]>(),
+    openApiEndpointTargetsByEndpoint: new Map<
+      string,
+      OpenApiEndpointRouteTarget[]
+    >(),
     validRoutePaths: new Set<string>(),
     allDocsFilePaths: new Set<string>(),
     routeSlugs: createRouteSlugRegistry(),
@@ -473,6 +705,14 @@ async function buildRouteIndex(
     });
   }
 
+  if (config.navigation.tabs?.items) {
+    await processTabItems({
+      index,
+      homePath,
+      items: config.navigation.tabs.items,
+    });
+  }
+
   const rootOpenApi = (config.navigation as any).openapi;
   if (
     typeof rootOpenApi === "string" ||
@@ -527,12 +767,89 @@ function buildInternalLinkRewriteError(args: {
   );
 }
 
+function formatOpenApiEndpointSourceList(
+  targets: OpenApiEndpointRouteTarget[],
+): string {
+  const sources = [...new Set(targets.map((target) => target.source))];
+  return sources.map((source) => `"${source}"`).join(", ");
+}
+
+function resolveOpenApiEndpointLinkToCanonicalHref(args: {
+  rawHref: string;
+  endpointLink: OpenApiEndpointLinkRef;
+  currentDocFilePath: string | null;
+  routeIndex: ResolvedRouteIndex;
+  warn: (message: string) => void;
+}): string {
+  const target =
+    args.endpointLink.source !== undefined
+      ? {
+          source: args.endpointLink.source,
+          targetKey: formatOpenApiEndpointTargetKey(
+            args.endpointLink.source,
+            args.endpointLink.method,
+            args.endpointLink.path,
+          ),
+        }
+      : (() => {
+          const targets =
+            args.routeIndex.openApiEndpointTargetsByEndpoint.get(
+              args.endpointLink.endpoint,
+            ) ?? [];
+          if (targets.length === 1) {
+            return targets[0];
+          }
+
+          throw buildInternalLinkRewriteError({
+            rawHref: args.rawHref,
+            currentDocFilePath: args.currentDocFilePath,
+            detail:
+              targets.length > 1
+                ? `The endpoint "${args.endpointLink.endpoint}" is ambiguous across OpenAPI sources (${formatOpenApiEndpointSourceList(
+                    targets,
+                  )}).`
+                : `No generated OpenAPI endpoint route matched "${args.endpointLink.endpoint}".`,
+          });
+        })();
+
+  const canonicalHref =
+    args.routeIndex.canonicalHrefByOpenApiEndpointKey.get(target.targetKey);
+  if (!canonicalHref) {
+    throw buildInternalLinkRewriteError({
+      rawHref: args.rawHref,
+      currentDocFilePath: args.currentDocFilePath,
+      detail: `The OpenAPI endpoint "${args.endpointLink.endpoint}" from "${target.source}" did not resolve to a canonical route.`,
+    });
+  }
+
+  const aliases =
+    args.routeIndex.allHrefsByOpenApiEndpointKey.get(target.targetKey) ?? [];
+  if (aliases.length > 1) {
+    args.warn(
+      `[INTERNAL_LINK_WARNING] "${args.rawHref}" matched OpenAPI endpoint "${args.endpointLink.endpoint}" in "${target.source}", which has multiple URLs (${aliases.join(", ")}). Rewriting to canonical URL "${canonicalHref}".`,
+    );
+  }
+
+  return withBasePath(canonicalHref);
+}
+
 function resolveLinkToCanonicalHref(args: {
   rawHref: string;
   currentDocFilePath: string | null;
   routeIndex: ResolvedRouteIndex;
   warn: (message: string) => void;
 }): string | null {
+  const endpointLink = parseOpenApiEndpointLinkHref(args.rawHref);
+  if (endpointLink) {
+    return resolveOpenApiEndpointLinkToCanonicalHref({
+      rawHref: args.rawHref,
+      endpointLink,
+      currentDocFilePath: args.currentDocFilePath,
+      routeIndex: args.routeIndex,
+      warn: args.warn,
+    });
+  }
+
   const resolvedHref = resolveDocsHref(args.rawHref);
   if (resolvedHref.kind === "ignored" || resolvedHref.kind === "local-asset") {
     return null;

package/template/src/lib/proxy-allowed-origins.mjs

@@ -0,0 +1,189 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+
+export function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value).trim());
+}
+
+function collectOpenApiSourcesFromNavigation(navigationNode, target) {
+  if (!isRecord(navigationNode)) {
+    return;
+  }
+
+  const openApiConfig = navigationNode.openapi;
+  if (typeof openApiConfig === "string") {
+    const trimmed = openApiConfig.trim();
+    if (trimmed) {
+      target.add(trimmed);
+    }
+  } else if (
+    isRecord(openApiConfig) &&
+    typeof openApiConfig.source === "string"
+  ) {
+    const trimmed = openApiConfig.source.trim();
+    if (trimmed) {
+      target.add(trimmed);
+    }
+  }
+
+  const menu = navigationNode.menu;
+  if (isRecord(menu) && Array.isArray(menu.items)) {
+    for (const menuItem of menu.items) {
+      if (!isRecord(menuItem)) {
+        continue;
+      }
+      collectOpenApiSourcesFromNavigation(menuItem, target);
+    }
+  }
+
+  const tabs = navigationNode.tabs;
+  if (isRecord(tabs) && Array.isArray(tabs.items)) {
+    for (const tabItem of tabs.items) {
+      if (!isRecord(tabItem)) {
+        continue;
+      }
+      collectOpenApiSourcesFromNavigation(tabItem, target);
+    }
+  }
+}
+
+function resolveServerTemplateUrl(rawUrl, rawVariables) {
+  let unresolved = false;
+  const variables = isRecord(rawVariables) ? rawVariables : null;
+
+  const resolved = rawUrl.replace(/\{([^}]+)\}/g, (_match, tokenName) => {
+    if (!variables) {
+      unresolved = true;
+      return "";
+    }
+
+    const variableConfig = variables[tokenName];
+    if (
+      !isRecord(variableConfig) ||
+      typeof variableConfig.default !== "string"
+    ) {
+      unresolved = true;
+      return "";
+    }
+
+    const defaultValue = variableConfig.default.trim();
+    if (!defaultValue) {
+      unresolved = true;
+      return "";
+    }
+
+    return defaultValue;
+  });
+
+  if (unresolved) {
+    return null;
+  }
+
+  return resolved;
+}
+
+export function normalizeAllowedOrigin(rawUrl) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return null;
+  }
+
+  if (parsed.protocol !== "https:") {
+    return null;
+  }
+
+  if (!parsed.hostname || parsed.username || parsed.password) {
+    return null;
+  }
+
+  return parsed.origin.toLowerCase();
+}
+
+async function loadOpenApiSpec(source, { docsDir, fetchImpl }) {
+  let fileContent;
+
+  if (isHttpUrl(source)) {
+    const response = await fetchImpl(source);
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch OpenAPI spec (${response.status} ${response.statusText})`,
+      );
+    }
+    fileContent = await response.text();
+  } else {
+    const absolutePath = path.join(docsDir, source);
+    fileContent = await fs.readFile(absolutePath, "utf8");
+  }
+
+  const trimmed = fileContent.trim();
+  if (trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html")) {
+    throw new Error("OpenAPI source returned HTML instead of JSON or YAML");
+  }
+
+  try {
+    return JSON.parse(fileContent);
+  } catch {
+    return YAML.parse(fileContent);
+  }
+}
+
+export async function buildAllowedOrigins({
+  cwd = process.cwd(),
+  docsDir = path.join(cwd, "src/content/docs"),
+  docsConfigPath = path.join(docsDir, "docs.json"),
+  fetchImpl = fetch,
+  onSourceError = undefined,
+} = {}) {
+  const docsConfigRaw = await fs.readFile(docsConfigPath, "utf8");
+  const docsConfig = JSON.parse(docsConfigRaw);
+
+  if (!isRecord(docsConfig) || !isRecord(docsConfig.navigation)) {
+    return [];
+  }
+
+  const sources = new Set();
+  collectOpenApiSourcesFromNavigation(docsConfig.navigation, sources);
+  if (sources.size === 0) {
+    return [];
+  }
+
+  const allowedOrigins = new Set();
+
+  for (const source of sources) {
+    try {
+      const spec = await loadOpenApiSpec(source, { docsDir, fetchImpl });
+      const servers =
+        isRecord(spec) && Array.isArray(spec.servers) ? spec.servers : [];
+
+      for (const server of servers) {
+        if (!isRecord(server) || typeof server.url !== "string") {
+          continue;
+        }
+
+        const resolvedUrl = resolveServerTemplateUrl(
+          server.url,
+          server.variables,
+        );
+        if (!resolvedUrl) {
+          continue;
+        }
+
+        const normalizedOrigin = normalizeAllowedOrigin(resolvedUrl);
+        if (normalizedOrigin) {
+          allowedOrigins.add(normalizedOrigin);
+        }
+      }
+    } catch (error) {
+      onSourceError?.(source, error);
+    }
+  }
+
+  return Array.from(allowedOrigins).sort();
+}