radiant-docs 0.1.37 → 0.1.39

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

@@ -0,0 +1,639 @@
+import path from "node:path";
+import type { Link, Root } from "mdast";
+import type { Plugin } from "unified";
+import { visitParents } from "unist-util-visit-parents";
+import {
+  getConfig,
+  loadOpenApiSpec,
+  type DocsConfig,
+  type NavGroup,
+  type NavMenuItem,
+  type NavOpenApi,
+  type NavOpenApiPage,
+  type NavPage,
+} from "../validation";
+import {
+  buildMdxPageHref,
+  buildOpenApiEndpointSlug,
+  parseOpenApiEndpoint,
+  slugify,
+} from "../utils";
+
+type MdxNavItem = string | NavPage | NavGroup | NavOpenApiPage;
+
+type ResolvedRouteIndex = {
+  canonicalHrefByFilePath: Map<string, string>;
+  allHrefsByFilePath: Map<string, string[]>;
+  validRoutePaths: Set<string>;
+};
+
+type LinkSplit = {
+  base: string;
+  suffix: string;
+};
+
+type VFileLike = {
+  path?: string;
+  message?: (reason: string, place?: unknown) => void;
+};
+
+type MdxJsxAttributeNode = {
+  type?: string;
+  name?: string;
+  value?: unknown;
+};
+
+type MdxJsxElementNode = {
+  attributes?: 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",
+  "put",
+  "delete",
+  "patch",
+  "head",
+  "options",
+  "trace",
+];
+
+let cachedRouteIndex: ResolvedRouteIndex | null = null;
+let cachedConfig: DocsConfig | null = null;
+
+function normalizeDocsFilePath(value: string): string {
+  let normalized = value.replace(/\\/g, "/").trim();
+  if (!normalized) return "";
+
+  normalized = normalized.replace(/^\/+/, "").replace(/\/+$/, "");
+  normalized = normalized.replace(/^src\/content\/docs\//, "");
+  normalized = normalized.replace(/\.(md|mdx)$/i, "");
+
+  const posixNormalized = path.posix
+    .normalize(`/${normalized}`)
+    .replace(/^\/+/, "");
+  return posixNormalized === "." ? "" : posixNormalized;
+}
+
+function normalizeRoutePath(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed || trimmed === "/") {
+    return "/";
+  }
+
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const normalized = path.posix.normalize(withLeadingSlash).replace(/\/+$/, "");
+  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;
+
+  const absoluteFilePath = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(process.cwd(), filePath);
+  const relativePath = path.relative(DOCS_ROOT, absoluteFilePath);
+
+  if (
+    !relativePath ||
+    relativePath.startsWith("..") ||
+    path.isAbsolute(relativePath)
+  ) {
+    return null;
+  }
+
+  return normalizeDocsFilePath(relativePath);
+}
+
+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);
+  return normalized;
+}
+
+function addMdxRoute(args: {
+  index: ResolvedRouteIndex;
+  filePath: string;
+  groupSlug: string;
+  homePath: string | null;
+}): void {
+  const normalizedFilePath = normalizeDocsFilePath(args.filePath);
+  if (!normalizedFilePath) return;
+
+  const navHref = addValidRoutePath(
+    args.index,
+    buildMdxPageHref({
+      filePath: normalizedFilePath,
+      groupSlug: args.groupSlug,
+    }),
+  );
+
+  if (!args.index.canonicalHrefByFilePath.has(normalizedFilePath)) {
+    args.index.canonicalHrefByFilePath.set(normalizedFilePath, navHref);
+  }
+
+  const aliases = args.index.allHrefsByFilePath.get(normalizedFilePath) ?? [];
+  if (!aliases.includes(navHref)) {
+    aliases.push(navHref);
+  }
+
+  if (args.homePath && normalizedFilePath === args.homePath) {
+    addValidRoutePath(args.index, "/");
+    if (!aliases.includes("/")) {
+      aliases.unshift("/");
+    }
+    args.index.canonicalHrefByFilePath.set(normalizedFilePath, "/");
+  }
+
+  args.index.allHrefsByFilePath.set(normalizedFilePath, aliases);
+}
+
+function addOpenApiEndpointRoute(args: {
+  index: ResolvedRouteIndex;
+  parentSlug: string;
+  method: string;
+  endpointPath: string;
+}): void {
+  const endpointSlug = buildOpenApiEndpointSlug(args.endpointPath, args.method);
+  const fullSlug = args.parentSlug
+    ? `${args.parentSlug}/${endpointSlug}`
+    : endpointSlug;
+  addValidRoutePath(args.index, fullSlug);
+}
+
+function shouldIncludeEndpoint(
+  method: string,
+  pathStr: string,
+  include?: string[],
+  exclude?: string[],
+): boolean {
+  const normalizedMethod = method.toUpperCase();
+  const normalizedPath = pathStr.toLowerCase();
+  const endpointKey = `${normalizedMethod} ${normalizedPath}`;
+
+  if (include) {
+    return include.some((entry) => {
+      const parsed = parseOpenApiEndpoint(entry);
+      if (!parsed) return false;
+      return `${parsed.method} ${parsed.path}` === endpointKey;
+    });
+  }
+
+  if (exclude) {
+    return !exclude.some((entry) => {
+      const parsed = parseOpenApiEndpoint(entry);
+      if (!parsed) return false;
+      return `${parsed.method} ${parsed.path}` === endpointKey;
+    });
+  }
+
+  return true;
+}
+
+async function processOpenApiFile(args: {
+  index: ResolvedRouteIndex;
+  parentSlug: string;
+  openApiPathOrConfig: string | NavOpenApi;
+}): Promise<void> {
+  let openApiSource: string;
+  let include: string[] | undefined;
+  let exclude: string[] | undefined;
+
+  if (typeof args.openApiPathOrConfig === "string") {
+    openApiSource = args.openApiPathOrConfig;
+  } else {
+    openApiSource = args.openApiPathOrConfig.source;
+    include = args.openApiPathOrConfig.include;
+    exclude = args.openApiPathOrConfig.exclude;
+  }
+
+  let openApiDoc: any;
+  try {
+    openApiDoc = await loadOpenApiSpec(openApiSource);
+  } catch {
+    return;
+  }
+
+  const paths = openApiDoc?.paths ?? {};
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+
+    for (const method of HTTP_METHODS) {
+      const operation = (pathItem as any)[method];
+      if (!operation) continue;
+
+      if (!shouldIncludeEndpoint(method, pathStr, include, exclude)) {
+        continue;
+      }
+
+      addOpenApiEndpointRoute({
+        index: args.index,
+        parentSlug: args.parentSlug,
+        method,
+        endpointPath: pathStr,
+      });
+    }
+  }
+}
+
+function processOpenApiPage(args: {
+  index: ResolvedRouteIndex;
+  parentSlug: string;
+  item: NavOpenApiPage;
+}): void {
+  const parsed = parseOpenApiEndpoint(args.item.openapi.endpoint);
+  if (!parsed) return;
+
+  addOpenApiEndpointRoute({
+    index: args.index,
+    parentSlug: args.parentSlug,
+    method: parsed.method,
+    endpointPath: parsed.path,
+  });
+}
+
+async function processPages(args: {
+  index: ResolvedRouteIndex;
+  parentSlug: string;
+  homePath: string | null;
+  items: MdxNavItem[];
+}): Promise<void> {
+  for (const item of args.items) {
+    if (typeof item === "string") {
+      addMdxRoute({
+        index: args.index,
+        filePath: item,
+        groupSlug: args.parentSlug,
+        homePath: args.homePath,
+      });
+      continue;
+    }
+
+    if ("page" in item) {
+      const pageItem = item as NavPage;
+      addMdxRoute({
+        index: args.index,
+        filePath: pageItem.page,
+        groupSlug: args.parentSlug,
+        homePath: args.homePath,
+      });
+      continue;
+    }
+
+    if ("group" in item) {
+      const group = item as NavGroup;
+      const groupSlug = slugify(group.group);
+      const nextPrefix = args.parentSlug
+        ? `${args.parentSlug}/${groupSlug}`
+        : groupSlug;
+
+      await processPages({
+        index: args.index,
+        parentSlug: nextPrefix,
+        homePath: args.homePath,
+        items: group.pages as MdxNavItem[],
+      });
+      continue;
+    }
+
+    if ("openapi" in item) {
+      processOpenApiPage({
+        index: args.index,
+        parentSlug: args.parentSlug,
+        item: item as NavOpenApiPage,
+      });
+    }
+  }
+}
+
+async function processMenuItems(args: {
+  index: ResolvedRouteIndex;
+  homePath: string | null;
+  items: NavMenuItem[];
+}): Promise<void> {
+  for (const menuItem of args.items) {
+    const menuSlug = slugify(menuItem.label);
+    const parentSlug = menuSlug;
+
+    if (Array.isArray(menuItem.submenu.pages)) {
+      await processPages({
+        index: args.index,
+        parentSlug,
+        homePath: args.homePath,
+        items: menuItem.submenu.pages as MdxNavItem[],
+      });
+    }
+
+    if (menuItem.submenu.openapi) {
+      await processOpenApiFile({
+        index: args.index,
+        parentSlug,
+        openApiPathOrConfig: menuItem.submenu.openapi,
+      });
+    }
+  }
+}
+
+async function buildRouteIndex(config: DocsConfig): Promise<ResolvedRouteIndex> {
+  const index: ResolvedRouteIndex = {
+    canonicalHrefByFilePath: new Map<string, string>(),
+    allHrefsByFilePath: new Map<string, string[]>(),
+    validRoutePaths: new Set<string>(),
+  };
+
+  const homePath =
+    typeof config.home === "string" ? normalizeDocsFilePath(config.home) : null;
+
+  if (Array.isArray(config.navigation.pages)) {
+    await processPages({
+      index,
+      parentSlug: "",
+      homePath,
+      items: config.navigation.pages as MdxNavItem[],
+    });
+  }
+
+  if (config.navigation.menu?.items) {
+    await processMenuItems({
+      index,
+      homePath,
+      items: config.navigation.menu.items,
+    });
+  }
+
+  const rootOpenApi = (config.navigation as any).openapi;
+  if (typeof rootOpenApi === "string" || (rootOpenApi && typeof rootOpenApi === "object")) {
+    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, "/");
+  }
+
+  return index;
+}
+
+async function getRouteIndex(): Promise<ResolvedRouteIndex> {
+  const config = await getConfig();
+  if (cachedRouteIndex && cachedConfig === config) {
+    return cachedRouteIndex;
+  }
+
+  cachedConfig = config;
+  cachedRouteIndex = await buildRouteIndex(config);
+  return cachedRouteIndex;
+}
+
+function buildInvalidInternalLinkError(args: {
+  baseHref: string;
+  currentDocFilePath: string | null;
+  filePathCandidates: string[];
+}): Error {
+  const sourceFile = args.currentDocFilePath
+    ? `${args.currentDocFilePath}.mdx`
+    : "the current MDX file";
+
+  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}. ` +
+      `Link must match an existing docs URL or resolve to a docs page file in navigation.${candidateHint}`,
+  );
+}
+
+function resolveLinkToCanonicalHref(args: {
+  rawHref: string;
+  currentDocFilePath: string | null;
+  routeIndex: ResolvedRouteIndex;
+  warn: (message: string) => void;
+}): string | null {
+  const parts = splitHref(args.rawHref);
+  const baseHref = parts.base.trim();
+  if (isLikelyExternalOrNonPageHref(baseHref)) {
+    return null;
+  }
+
+  const normalizedBaseRoute = normalizeRoutePath(baseHref);
+  if (args.routeIndex.validRoutePaths.has(normalizedBaseRoute)) {
+    if (baseHref.startsWith("/")) {
+      return null;
+    }
+
+    return `${normalizedBaseRoute}${parts.suffix}`;
+  }
+
+  const filePathCandidates = buildFilePathCandidates({
+    baseHref,
+    currentDocFilePath: args.currentDocFilePath,
+  });
+
+  for (const filePath of filePathCandidates) {
+    const canonicalHref = args.routeIndex.canonicalHrefByFilePath.get(filePath);
+    if (!canonicalHref) continue;
+
+    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 `${canonicalHref}${parts.suffix}`;
+  }
+
+  if (shouldEnforceInternalRouteValidation(baseHref)) {
+    throw buildInvalidInternalLinkError({
+      baseHref,
+      currentDocFilePath: args.currentDocFilePath,
+      filePathCandidates,
+    });
+  }
+
+  return null;
+}
+
+export const remarkResolveInternalLinks: Plugin<[], Root> = () => {
+  return async (tree, file) => {
+    const routeIndex = await getRouteIndex();
+    const vfile = file as VFileLike;
+    const currentDocFilePath = getCurrentDocFilePath(vfile.path);
+    const emittedWarnings = new Set<string>();
+
+    const warnOnce = (message: string, place: unknown): void => {
+      if (emittedWarnings.has(message)) return;
+      emittedWarnings.add(message);
+      if (typeof vfile.message === "function") {
+        vfile.message(message, place);
+      }
+    };
+
+    visitParents(tree, "link", (node) => {
+      const linkNode = node as Link;
+      if (typeof linkNode.url !== "string") return;
+
+      const rewrittenHref = resolveLinkToCanonicalHref({
+        rawHref: linkNode.url,
+        currentDocFilePath,
+        routeIndex,
+        warn: (message) => warnOnce(message, node),
+      });
+
+      if (rewrittenHref && rewrittenHref !== linkNode.url) {
+        linkNode.url = rewrittenHref;
+      }
+    });
+
+    const rewriteMdxJsxHrefAttributes = (node: unknown): void => {
+      const element = node as MdxJsxElementNode;
+      if (!Array.isArray(element.attributes)) {
+        return;
+      }
+
+      for (const attribute of element.attributes) {
+        const hrefAttribute = attribute as MdxJsxAttributeNode;
+        if (hrefAttribute.type !== "mdxJsxAttribute") continue;
+        if (hrefAttribute.name !== "href") continue;
+        if (typeof hrefAttribute.value !== "string") continue;
+
+        const rewrittenHref = resolveLinkToCanonicalHref({
+          rawHref: hrefAttribute.value,
+          currentDocFilePath,
+          routeIndex,
+          warn: (message) => warnOnce(message, node),
+        });
+
+        if (rewrittenHref && rewrittenHref !== hrefAttribute.value) {
+          hrefAttribute.value = rewrittenHref;
+        }
+      }
+    };
+
+    visitParents(tree, "mdxJsxFlowElement", (node) => {
+      rewriteMdxJsxHrefAttributes(node);
+    });
+
+    visitParents(tree, "mdxJsxTextElement", (node) => {
+      rewriteMdxJsxHrefAttributes(node);
+    });
+  };
+};
+
+export default remarkResolveInternalLinks;

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>