radiant-docs 0.1.54 → 0.1.57

package/template/src/lib/mdx/remark-code-block-component.ts

@@ -74,7 +74,6 @@ type NodeWithChildren = {
 
 const COMPONENT_PREVIEW_NAME = "ComponentPreview";
 const COMPONENT_PREVIEW_BLOCK_NAME = "ComponentPreviewBlock";
-const COMPONENT_PREVIEW_LANGUAGES = new Set(["jsx", "tsx", "mdx"]);
 const INTERNAL_CODE_BLOCK_NAME = "CodeBlockInternal";
 
 const FILE_EXTENSION_BY_LANGUAGE: Record<string, string> = {
@@ -412,25 +411,7 @@ function transformCodeBlockNodes(tree: Root): void {
     }
 
     if (isInsideComponentPreview) {
-      if (!COMPONENT_PREVIEW_LANGUAGES.has(normalizedLanguage)) {
-        throw new Error(
-          `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Fenced code blocks must use jsx, tsx, or mdx language (received "${language}")`,
-        );
-      }
-
-      let previewChildren: unknown[] = [];
-      try {
-        previewChildren = parseComponentPreviewChildren(rawCode);
-      } catch (error) {
-        const reason =
-          error instanceof Error && error.message.trim().length > 0
-            ? ` -> ${error.message}`
-            : "";
-        throw new Error(
-          `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Failed to parse fenced code block as MDX content${reason}`,
-        );
-      }
-
+      const previewChildren = parseComponentPreviewChildren(rawCode);
       const previewAttributes = attributes.filter(
         (attribute) => attribute.name !== "inCodeGroup",
       );

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

@@ -6,6 +6,7 @@ import { visitParents } from "unist-util-visit-parents";
 import {
   getConfig,
   loadOpenApiSpec,
+  resolveDocsHref,
   type DocsConfig,
   type HiddenPageRoute,
   type NavGroup,
@@ -16,8 +17,11 @@ import {
 } from "../validation";
 import { prependBasePath, withBasePath } from "../base-path";
 import {
-  buildMdxPageHref,
-  buildOpenApiEndpointHref,
+  buildMdxPageFallbackSlug,
+  buildMdxPageSlug,
+  buildOpenApiEndpointSlug,
+  buildOpenApiEndpointFallbackSlug,
+  createRouteSlugRegistry,
   parseOpenApiEndpoint,
   slugify,
 } from "../utils";
@@ -29,11 +33,7 @@ type ResolvedRouteIndex = {
   allHrefsByFilePath: Map<string, string[]>;
   validRoutePaths: Set<string>;
   allDocsFilePaths: Set<string>;
-};
-
-type LinkSplit = {
-  base: string;
-  suffix: string;
+  routeSlugs: ReturnType<typeof createRouteSlugRegistry>;
 };
 
 type VFileLike = {
@@ -48,11 +48,16 @@ type MdxJsxAttributeNode = {
 };
 
 type MdxJsxElementNode = {
+  name?: string | null;
   attributes?: unknown[];
 };
 
+type EstreeNode = {
+  type?: string;
+  [key: string]: unknown;
+};
+
 const DOCS_ROOT = path.resolve(process.cwd(), "src/content/docs");
-const EXTERNAL_PROTOCOL_REGEX = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
 const HTTP_METHODS = [
   "get",
   "post",
@@ -92,44 +97,6 @@ function normalizeRoutePath(value: string): string {
   return normalized || "/";
 }
 
-function splitHref(url: string): LinkSplit {
-  const match = url.match(/^([^?#]*)(.*)$/);
-  return {
-    base: match?.[1] ?? url,
-    suffix: match?.[2] ?? "",
-  };
-}
-
-function isLikelyExternalOrNonPageHref(baseHref: string): boolean {
-  if (!baseHref) return true;
-  if (baseHref.startsWith("#")) return true;
-  if (baseHref.startsWith("?")) return true;
-  if (baseHref.startsWith("//")) return true;
-  return EXTERNAL_PROTOCOL_REGEX.test(baseHref);
-}
-
-function normalizeForFileResolution(baseHref: string): string {
-  let normalized = baseHref.replace(/\\/g, "/").trim();
-  if (!normalized) return "";
-
-  const docsPathMarker = "/src/content/docs/";
-  const markerIndex = normalized.indexOf(docsPathMarker);
-  if (markerIndex >= 0) {
-    normalized = `/${normalized.slice(markerIndex + docsPathMarker.length)}`;
-  }
-
-  normalized = normalized.replace(/^\/?src\/content\/docs\//, "/");
-  normalized = normalized.replace(/\.(md|mdx)$/i, "");
-  normalized = normalized.replace(/\/+$/, "");
-  normalized = normalized.replace(/\/{2,}/g, "/");
-
-  return normalized;
-}
-
-function isExplicitRelativeTarget(value: string): boolean {
-  return value.startsWith("./") || value.startsWith("../");
-}
-
 function getCurrentDocFilePath(filePath: string | undefined): string | null {
   if (!filePath) return null;
 
@@ -181,63 +148,6 @@ function collectDocsFilePaths(directory: string): string[] {
   return results;
 }
 
-function buildFilePathCandidates(args: {
-  baseHref: string;
-  currentDocFilePath: string | null;
-}): string[] {
-  const rawBase = normalizeForFileResolution(args.baseHref);
-  if (!rawBase) return [];
-
-  const candidates = new Set<string>();
-
-  if (rawBase.startsWith("/")) {
-    const absoluteCandidate = normalizeDocsFilePath(rawBase);
-    if (absoluteCandidate) {
-      candidates.add(absoluteCandidate);
-    }
-    return Array.from(candidates);
-  }
-
-  const currentDocDir = args.currentDocFilePath
-    ? path.posix.dirname(args.currentDocFilePath)
-    : "";
-
-  const relativeCandidate = normalizeDocsFilePath(
-    path.posix.resolve("/", currentDocDir, rawBase).slice(1),
-  );
-  if (relativeCandidate) {
-    candidates.add(relativeCandidate);
-  }
-
-  if (!isExplicitRelativeTarget(rawBase)) {
-    const rootCandidate = normalizeDocsFilePath(rawBase);
-    if (rootCandidate) {
-      candidates.add(rootCandidate);
-    }
-  }
-
-  return Array.from(candidates);
-}
-
-function shouldEnforceInternalRouteValidation(baseHref: string): boolean {
-  const normalized = normalizeForFileResolution(baseHref);
-  if (!normalized) {
-    return false;
-  }
-
-  const extension = path.posix.extname(normalized).toLowerCase();
-  if (!extension) {
-    return true;
-  }
-
-  return (
-    extension === ".md" ||
-    extension === ".mdx" ||
-    extension === ".html" ||
-    extension === ".htm"
-  );
-}
-
 function addValidRoutePath(index: ResolvedRouteIndex, href: string): string {
   const normalized = normalizeRoutePath(href);
   index.validRoutePaths.add(normalized);
@@ -253,12 +163,21 @@ function addMdxRoute(args: {
   const normalizedFilePath = normalizeDocsFilePath(args.filePath);
   if (!normalizedFilePath) return;
 
-  const navHref = addValidRoutePath(
-    args.index,
-    buildMdxPageHref({
+  const preferredSlug = buildMdxPageSlug({
+    filePath: normalizedFilePath,
+    groupSlug: args.groupSlug,
+  });
+  const registeredSlug = args.index.routeSlugs.register({
+    preferredSlug,
+    fallbackSlug: buildMdxPageFallbackSlug({
       filePath: normalizedFilePath,
       groupSlug: args.groupSlug,
     }),
+    identity: `mdx:${normalizedFilePath}`,
+  }).slug;
+  const navHref = addValidRoutePath(
+    args.index,
+    prependBasePath(`/${registeredSlug}`),
   );
 
   if (!args.index.canonicalHrefByFilePath.has(normalizedFilePath)) {
@@ -284,16 +203,30 @@ function addMdxRoute(args: {
 function addOpenApiEndpointRoute(args: {
   index: ResolvedRouteIndex;
   parentSlug: string;
+  source: string;
   method: string;
   endpointPath: string;
 }): void {
-  addValidRoutePath(
-    args.index,
-    buildOpenApiEndpointHref({
+  const endpointSlug = buildOpenApiEndpointSlug(args.endpointPath, args.method);
+  const normalizedParentSlug = args.parentSlug
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+  const preferredSlug = normalizedParentSlug
+    ? `${normalizedParentSlug}/${endpointSlug}`
+    : endpointSlug;
+  const registeredSlug = args.index.routeSlugs.register({
+    preferredSlug,
+    fallbackSlug: buildOpenApiEndpointFallbackSlug({
+      source: args.source,
       path: args.endpointPath,
       method: args.method,
       groupSlug: args.parentSlug,
     }),
+    identity: `openapi:${args.source}:${args.method.toUpperCase()} ${args.endpointPath.toLowerCase()}`,
+  }).slug;
+  addValidRoutePath(
+    args.index,
+    prependBasePath(`/${registeredSlug}`),
   );
 }
 
@@ -384,6 +317,7 @@ async function processOpenApiFile(args: {
       addOpenApiEndpointRoute({
         index: args.index,
         parentSlug: args.parentSlug,
+        source: openApiSource,
         method,
         endpointPath: pathStr,
       });
@@ -402,6 +336,7 @@ function processOpenApiPage(args: {
   addOpenApiEndpointRoute({
     index: args.index,
     parentSlug: args.parentSlug,
+    source: args.item.openapi.source,
     method: parsed.method,
     endpointPath: parsed.path,
   });
@@ -497,6 +432,7 @@ async function buildRouteIndex(
     allHrefsByFilePath: new Map<string, string[]>(),
     validRoutePaths: new Set<string>(),
     allDocsFilePaths: new Set<string>(),
+    routeSlugs: createRouteSlugRegistry(),
   };
 
   for (const docFilePath of collectDocsFilePaths(DOCS_ROOT)) {
@@ -526,32 +462,22 @@ async function buildRouteIndex(
   const rootOpenApi = (config.navigation as any).openapi;
   if (
     typeof rootOpenApi === "string" ||
-    (rootOpenApi && typeof rootOpenApi === "object")
+    (rootOpenApi &&
+      typeof rootOpenApi === "object" &&
+      !Array.isArray(rootOpenApi))
   ) {
     await processOpenApiFile({
       index,
       parentSlug: "",
       openApiPathOrConfig: rootOpenApi,
     });
-  } else if (Array.isArray(rootOpenApi)) {
-    for (const openApiItem of rootOpenApi) {
-      if (
-        typeof openApiItem !== "string" &&
-        (!openApiItem || typeof openApiItem !== "object")
-      ) {
-        continue;
-      }
-
-      await processOpenApiFile({
-        index,
-        parentSlug: "",
-        openApiPathOrConfig: openApiItem as string | NavOpenApi,
-      });
-    }
   }
 
   if (homePath) {
-    addValidRoutePath(index, prependBasePath("/"));
+    addHiddenPageRoute(index, {
+      filePath: homePath,
+      href: "/",
+    });
   }
 
   for (const hiddenPageRoute of config.hiddenPageRoutes ?? []) {
@@ -572,38 +498,18 @@ async function getRouteIndex(): Promise<ResolvedRouteIndex> {
   return cachedRouteIndex;
 }
 
-function buildInvalidInternalLinkError(args: {
-  baseHref: string;
+function buildInternalLinkRewriteError(args: {
+  rawHref: string;
   currentDocFilePath: string | null;
-  filePathCandidates: string[];
-  existingFilePathCandidates: string[];
+  detail: string;
 }): Error {
   const sourceFile = args.currentDocFilePath
     ? `${args.currentDocFilePath}.mdx`
     : "the current MDX file";
 
-  if (args.existingFilePathCandidates.length > 0) {
-    const existingFiles = args.existingFilePathCandidates
-      .map((candidate) => `"${candidate}.mdx"`)
-      .join(", ");
-
-    return new Error(
-      `[USER_ERROR]: Invalid internal link "${args.baseHref}" in ${sourceFile}. ` +
-        `The target file exists (${existingFiles}), but it is not a routable docs page. ` +
-        `Add it to docs.json navigation, set it as the home page, or link to it from the navbar or footer so it is included in the built site.`,
-    );
-  }
-
-  const candidateHint =
-    args.filePathCandidates.length > 0
-      ? ` Tried file path candidates: ${args.filePathCandidates
-          .map((candidate) => `"${candidate}"`)
-          .join(", ")}.`
-      : "";
-
   return new Error(
-    `[USER_ERROR]: Invalid internal link "${args.baseHref}" in ${sourceFile}. ` +
-      `No matching docs page file was found. Create the target .mdx file or update the link.${candidateHint}`,
+    `[RADIANT_INTERNAL_ERROR]: Docs link rewrite failed for "${args.rawHref}" in ${sourceFile}. ` +
+      `${args.detail} This should have been caught by radiant-docs-validator before build.`,
   );
 }
 
@@ -613,71 +519,52 @@ function resolveLinkToCanonicalHref(args: {
   routeIndex: ResolvedRouteIndex;
   warn: (message: string) => void;
 }): string | null {
-  const parts = splitHref(args.rawHref);
-  const baseHref = parts.base.trim();
-  if (isLikelyExternalOrNonPageHref(baseHref)) {
+  const resolvedHref = resolveDocsHref(args.rawHref);
+  if (resolvedHref.kind === "ignored" || resolvedHref.kind === "local-asset") {
     return null;
   }
 
-  const normalizedBaseRoute = normalizeRoutePath(baseHref);
-  const normalizedBaseRouteWithBase = normalizeRoutePath(
-    baseHref.startsWith("/")
-      ? withBasePath(normalizedBaseRoute)
-      : prependBasePath(normalizedBaseRoute),
-  );
-  if (args.routeIndex.validRoutePaths.has(normalizedBaseRouteWithBase)) {
-    if (
-      baseHref.startsWith("/") &&
-      normalizedBaseRoute === normalizedBaseRouteWithBase
-    ) {
-      return null;
-    }
-
-    return `${normalizedBaseRouteWithBase}${parts.suffix}`;
-  }
-
-  if (args.routeIndex.validRoutePaths.has(normalizedBaseRoute)) {
-    const publicRoute = normalizeRoutePath(withBasePath(normalizedBaseRoute));
-    if (baseHref.startsWith("/") && normalizedBaseRoute === publicRoute) {
-      return null;
-    }
-
-    return `${publicRoute}${parts.suffix}`;
-  }
-
-  const filePathCandidates = buildFilePathCandidates({
-    baseHref,
-    currentDocFilePath: args.currentDocFilePath,
-  });
-
-  for (const filePath of filePathCandidates) {
-    const canonicalHref = args.routeIndex.canonicalHrefByFilePath.get(filePath);
-    if (!canonicalHref) continue;
+  if (resolvedHref.kind === "invalid") {
+    const suggestion =
+      "suggestedHref" in resolvedHref && resolvedHref.suggestedHref
+        ? ` Suggested href: "${resolvedHref.suggestedHref}".`
+        : "";
 
-    const aliases = args.routeIndex.allHrefsByFilePath.get(filePath) ?? [];
-    if (aliases.length > 1) {
-      args.warn(
-        `[INTERNAL_LINK_WARNING] "${baseHref}" matched "${filePath}", which has multiple URLs (${aliases.join(", ")}). Rewriting to canonical URL "${canonicalHref}".`,
-      );
-    }
-
-    return `${withBasePath(canonicalHref)}${parts.suffix}`;
+    throw buildInternalLinkRewriteError({
+      rawHref: args.rawHref,
+      currentDocFilePath: args.currentDocFilePath,
+      detail:
+        `The href was classified as invalid during rewrite (${resolvedHref.reason}).` +
+        suggestion,
+    });
   }
 
-  if (shouldEnforceInternalRouteValidation(baseHref)) {
-    const existingFilePathCandidates = filePathCandidates.filter((filePath) =>
-      args.routeIndex.allDocsFilePaths.has(filePath),
+  const canonicalHref = args.routeIndex.canonicalHrefByFilePath.get(
+    resolvedHref.filePath,
+  );
+  if (!canonicalHref) {
+    const targetFileExists = args.routeIndex.allDocsFilePaths.has(
+      resolvedHref.filePath,
     );
 
-    throw buildInvalidInternalLinkError({
-      baseHref,
+    throw buildInternalLinkRewriteError({
+      rawHref: args.rawHref,
       currentDocFilePath: args.currentDocFilePath,
-      filePathCandidates,
-      existingFilePathCandidates,
+      detail: targetFileExists
+        ? `The target file "${resolvedHref.filePath}.mdx" exists but did not resolve to a canonical route.`
+        : `The target file "${resolvedHref.filePath}.mdx" was not found in the docs route index.`,
     });
   }
 
-  return null;
+  const aliases =
+    args.routeIndex.allHrefsByFilePath.get(resolvedHref.filePath) ?? [];
+  if (aliases.length > 1) {
+    args.warn(
+      `[INTERNAL_LINK_WARNING] "${resolvedHref.pathname}" matched "${resolvedHref.filePath}", which has multiple URLs (${aliases.join(", ")}). Rewriting to canonical URL "${canonicalHref}".`,
+    );
+  }
+
+  return `${withBasePath(canonicalHref)}${resolvedHref.suffix}`;
 }
 
 export const remarkResolveInternalLinks: Plugin<[], Root> = () => {
@@ -685,6 +572,13 @@ export const remarkResolveInternalLinks: Plugin<[], Root> = () => {
     const routeIndex = await getRouteIndex();
     const vfile = file as VFileLike;
     const currentDocFilePath = getCurrentDocFilePath(vfile.path);
+    if (
+      currentDocFilePath &&
+      !routeIndex.canonicalHrefByFilePath.has(currentDocFilePath)
+    ) {
+      return;
+    }
+
     const emittedWarnings = new Set<string>();
 
     const warnOnce = (message: string, place: unknown): void => {
@@ -734,6 +628,58 @@ export const remarkResolveInternalLinks: Plugin<[], Root> = () => {
           hrefAttribute.value = rewrittenHref;
         }
       }
+
+      if (element.name !== "Card") return;
+
+      const buttonAttribute = element.attributes.find((attribute) => {
+        const candidate = attribute as MdxJsxAttributeNode;
+        return candidate.type === "mdxJsxAttribute" && candidate.name === "button";
+      }) as MdxJsxAttributeNode | undefined;
+      const program = (
+        buttonAttribute?.value as { data?: { estree?: EstreeNode } } | undefined
+      )?.data?.estree;
+      const body = program?.body;
+      if (!Array.isArray(body) || body.length !== 1) return;
+
+      const statement = body[0] as EstreeNode;
+      const expression = statement.expression as EstreeNode | undefined;
+      if (
+        statement.type !== "ExpressionStatement" ||
+        expression?.type !== "ObjectExpression" ||
+        !Array.isArray(expression.properties)
+      ) {
+        return;
+      }
+
+      const hrefProperty = expression.properties.find((propertyValue) => {
+        const property = propertyValue as EstreeNode;
+        const key = property.key as EstreeNode | undefined;
+        return (
+          property.type === "Property" &&
+          property.computed !== true &&
+          (key?.type === "Identifier" || key?.type === "Literal") &&
+          (key.name === "href" || key.value === "href")
+        );
+      }) as EstreeNode | undefined;
+      const hrefValue = hrefProperty?.value as EstreeNode | undefined;
+      if (
+        hrefValue?.type !== "Literal" ||
+        typeof hrefValue.value !== "string"
+      ) {
+        return;
+      }
+
+      const rewrittenHref = resolveLinkToCanonicalHref({
+        rawHref: hrefValue.value,
+        currentDocFilePath,
+        routeIndex,
+        warn: (message) => warnOnce(message, node),
+      });
+
+      if (rewrittenHref && rewrittenHref !== hrefValue.value) {
+        hrefValue.value = rewrittenHref;
+        hrefValue.raw = JSON.stringify(rewrittenHref);
+      }
     };
 
     visitParents(tree, "mdxJsxFlowElement", (node) => {