radiant-docs-validator 0.1.0 → 0.1.3

package/dist/index.d.ts

@@ -163,8 +163,26 @@ type Footer = {
     socials?: Partial<Record<SocialPlatform, string>>;
     links?: FooterLink[];
 };
+type DocsPageHrefResolution = {
+    kind: "ignored";
+} | {
+    kind: "invalid";
+    reason: "not-root-absolute" | "generated-route" | "empty-target";
+    href: string;
+    pathname: string;
+    suffix: string;
+    filePath: string;
+    suggestedHref?: string;
+} | {
+    kind: "docs-page";
+    href: string;
+    pathname: string;
+    suffix: string;
+    filePath: string;
+};
 declare function loadOpenApiSpec(filePathOrUrl: string): Promise<any>;
 declare function getConfig(): Promise<DocsConfig>;
+declare function resolveDocsPageHref(href: string): DocsPageHrefResolution;
 declare function validateMdxContent(): Promise<void>;
 
-export { type AssistantButtonConfig, type AssistantButtonSize, type AssistantConfig, type AssistantIcon, type AssistantNavbarButtonConfig, BASE_COLOR_OPTIONS, type BaseColorByMode, type BaseColorOption, type CardButtonTheme, type CardCoverTheme, type CardTheme, type CodeSyntaxThemeConfig, type CodeTheme, DEFAULT_THEME_COLOR_DARK, DEFAULT_THEME_COLOR_LIGHT, type DocsConfig, type DocsTheme, type DocsValidatorOptions, type Footer, type FooterLink, type HiddenPageRoute, type Logo, type LogoVariant, type NavGroup, type NavMenu, type NavMenuItem, type NavOpenApi, type NavOpenApiPage, type NavOpenApiPageRef, type NavPage, type NavTag, type NavbarItem, type NavigationItem, type SocialPlatform, type TagTheme, type ThemeColorByMode, configureDocsValidator, getConfig, loadOpenApiSpec, validateMdxContent };
+export { type AssistantButtonConfig, type AssistantButtonSize, type AssistantConfig, type AssistantIcon, type AssistantNavbarButtonConfig, BASE_COLOR_OPTIONS, type BaseColorByMode, type BaseColorOption, type CardButtonTheme, type CardCoverTheme, type CardTheme, type CodeSyntaxThemeConfig, type CodeTheme, DEFAULT_THEME_COLOR_DARK, DEFAULT_THEME_COLOR_LIGHT, type DocsConfig, type DocsPageHrefResolution, type DocsTheme, type DocsValidatorOptions, type Footer, type FooterLink, type HiddenPageRoute, type Logo, type LogoVariant, type NavGroup, type NavMenu, type NavMenuItem, type NavOpenApi, type NavOpenApiPage, type NavOpenApiPageRef, type NavPage, type NavTag, type NavbarItem, type NavigationItem, type SocialPlatform, type TagTheme, type ThemeColorByMode, configureDocsValidator, getConfig, loadOpenApiSpec, resolveDocsPageHref, validateMdxContent };

package/dist/index.js

@@ -289,6 +289,14 @@ function validateFileExistence(filePath, currentPath) {
     );
   }
 }
+function normalizeDocsFilePath(value) {
+  let normalized = value.replace(/\\/g, "/").trim();
+  if (!normalized) return "";
+  normalized = normalized.replace(/^\/+/, "").replace(/\/+$/, "");
+  normalized = normalized.replace(/\.(md|mdx)$/i, "");
+  const posixNormalized = path.posix.normalize(`/${normalized}`).replace(/^\/+/, "");
+  return posixNormalized === "." ? "" : posixNormalized;
+}
 function normalizeDocsPagePath(value, currentPath, label = "Page path") {
   checkType(value, "string", currentPath, label);
   const trimmedPath = value.trim();
@@ -1975,6 +1983,195 @@ function validateComponentUsage(content) {
     );
   }
 }
+var EXTERNAL_PROTOCOL_REGEX = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+var DOCS_PAGE_SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".mdx"]);
+var DOCS_PAGE_ROUTE_EXTENSIONS = /* @__PURE__ */ new Set([".htm", ".html"]);
+function isIgnoredHref(pathname) {
+  if (!pathname) return true;
+  if (pathname.startsWith("#")) return true;
+  if (pathname.startsWith("?")) return true;
+  if (pathname.startsWith("//")) return true;
+  return EXTERNAL_PROTOCOL_REGEX.test(pathname);
+}
+function getHrefExtension(pathname) {
+  return path.posix.extname(pathname.replace(/\\/g, "/")).toLowerCase();
+}
+function isDocsPageLikeHref(pathname) {
+  if (isIgnoredHref(pathname)) return false;
+  const extension = getHrefExtension(pathname);
+  if (!extension) return true;
+  if (DOCS_PAGE_SOURCE_EXTENSIONS.has(extension)) return true;
+  return DOCS_PAGE_ROUTE_EXTENSIONS.has(extension);
+}
+function resolveDocsPageHref(href) {
+  const { pathname, suffix } = splitHrefPathAndSuffix(href);
+  const baseHref = pathname.trim();
+  if (!isDocsPageLikeHref(baseHref)) {
+    return { kind: "ignored" };
+  }
+  const filePath = normalizeDocsFilePath(baseHref);
+  const baseResult = {
+    href,
+    pathname: baseHref,
+    suffix,
+    filePath
+  };
+  if (!baseHref.startsWith("/")) {
+    return {
+      kind: "invalid",
+      reason: "not-root-absolute",
+      ...baseResult,
+      suggestedHref: filePath ? `/${filePath}` : void 0
+    };
+  }
+  const extension = getHrefExtension(baseHref);
+  if (extension && !DOCS_PAGE_SOURCE_EXTENSIONS.has(extension)) {
+    return {
+      kind: "invalid",
+      reason: "generated-route",
+      ...baseResult
+    };
+  }
+  if (!filePath) {
+    return {
+      kind: "invalid",
+      reason: "empty-target",
+      ...baseResult
+    };
+  }
+  return {
+    kind: "docs-page",
+    ...baseResult
+  };
+}
+function addRoutableDocsFilePath(routableFilePaths, filePath) {
+  if (typeof filePath !== "string") return;
+  const normalizedFilePath = normalizeDocsFilePath(filePath);
+  if (normalizedFilePath) {
+    routableFilePaths.add(normalizedFilePath);
+  }
+}
+function collectRoutablePageItems(routableFilePaths, items) {
+  if (!Array.isArray(items)) return;
+  for (const item of items) {
+    if (typeof item === "string") {
+      addRoutableDocsFilePath(routableFilePaths, item);
+      continue;
+    }
+    if (!item || typeof item !== "object") continue;
+    if ("page" in item) {
+      addRoutableDocsFilePath(routableFilePaths, item.page);
+      continue;
+    }
+    if ("group" in item) {
+      collectRoutablePageItems(
+        routableFilePaths,
+        item.pages
+      );
+    }
+  }
+}
+function collectRoutableNavigationPages(routableFilePaths, config) {
+  collectRoutablePageItems(
+    routableFilePaths,
+    config.navigation.pages
+  );
+  for (const item of config.navigation.menu?.items ?? []) {
+    collectRoutablePageItems(
+      routableFilePaths,
+      item.submenu.pages
+    );
+  }
+}
+function buildDocsLinkIndex(config, files) {
+  const allDocsFilePaths = /* @__PURE__ */ new Set();
+  const routableDocsFilePaths = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const relativePath = path.relative(DOCS_DIR, file);
+    const normalizedFilePath = normalizeDocsFilePath(relativePath);
+    if (normalizedFilePath) {
+      allDocsFilePaths.add(normalizedFilePath);
+    }
+  }
+  collectRoutableNavigationPages(routableDocsFilePaths, config);
+  addRoutableDocsFilePath(routableDocsFilePaths, config.home);
+  for (const route of config.hiddenPageRoutes ?? []) {
+    addRoutableDocsFilePath(routableDocsFilePaths, route.filePath);
+  }
+  return {
+    allDocsFilePaths,
+    routableDocsFilePaths
+  };
+}
+function validateDocsRootAbsoluteHref(args) {
+  const resolvedHref = resolveDocsPageHref(args.href);
+  if (resolvedHref.kind === "ignored") return;
+  if (resolvedHref.kind === "invalid") {
+    if (resolvedHref.reason === "not-root-absolute") {
+      const suggestion = resolvedHref.suggestedHref ? ` Use "${resolvedHref.suggestedHref}" instead.` : "";
+      throw new Error(
+        `Invalid internal link "${args.href}" in ${args.sourceFile}. Docs page links must be docs-root absolute paths like "/guides/quickstart".${suggestion}`
+      );
+    }
+    if (resolvedHref.reason === "generated-route") {
+      throw new Error(
+        `Invalid internal link "${args.href}" in ${args.sourceFile}. Docs page links must point to MDX source paths from the docs root, not generated HTML routes. Use a path like "/guides/quickstart" or "/guides/quickstart.mdx".`
+      );
+    }
+    throw new Error(
+      `Invalid internal link "${args.href}" in ${args.sourceFile}. Docs page links must point to a docs page file from the docs root, such as "/guides/quickstart".`
+    );
+  }
+  if (args.linkIndex.routableDocsFilePaths.has(resolvedHref.filePath)) {
+    return;
+  }
+  if (args.linkIndex.allDocsFilePaths.has(resolvedHref.filePath)) {
+    throw new Error(
+      `Invalid internal link "${args.href}" in ${args.sourceFile}. The target file exists ("${resolvedHref.filePath}.mdx"), 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.`
+    );
+  }
+  throw new Error(
+    `Invalid internal link "${args.href}" in ${args.sourceFile}. No matching docs page file was found. Expected "${resolvedHref.filePath}.mdx" under the docs root.`
+  );
+}
+function visitMdxTree(node, visitor) {
+  if (!node || typeof node !== "object") return;
+  const typedNode = node;
+  visitor(node);
+  if (!Array.isArray(typedNode.children)) return;
+  for (const child of typedNode.children) {
+    visitMdxTree(child, visitor);
+  }
+}
+function createInternalLinkValidationPlugin(args) {
+  return () => (tree) => {
+    visitMdxTree(tree, (node) => {
+      if ((node.type === "link" || node.type === "definition") && typeof node.url === "string") {
+        validateDocsRootAbsoluteHref({
+          href: node.url,
+          sourceFile: args.sourceFile,
+          linkIndex: args.linkIndex
+        });
+      }
+      if (node.type !== "mdxJsxFlowElement" && node.type !== "mdxJsxTextElement") {
+        return;
+      }
+      const element = node;
+      if (!Array.isArray(element.attributes)) return;
+      for (const attribute of element.attributes) {
+        const hrefAttribute = attribute;
+        if (hrefAttribute.type !== "mdxJsxAttribute") continue;
+        if (hrefAttribute.name !== "href") continue;
+        if (typeof hrefAttribute.value !== "string") continue;
+        validateDocsRootAbsoluteHref({
+          href: hrefAttribute.value,
+          sourceFile: args.sourceFile,
+          linkIndex: args.linkIndex
+        });
+      }
+    });
+  };
+}
 function getMdxFiles(dir) {
   let results = [];
   const list = fs.readdirSync(dir);
@@ -1983,7 +2180,7 @@ function getMdxFiles(dir) {
     const stat = fs.statSync(file);
     if (stat && stat.isDirectory()) {
       results = results.concat(getMdxFiles(file));
-    } else if (file.endsWith(".mdx")) {
+    } else if (/\.(md|mdx)$/i.test(file)) {
       results.push(file);
     }
   });
@@ -1991,8 +2188,11 @@ function getMdxFiles(dir) {
 }
 async function validateMdxContent() {
   assertConfigured();
+  const config = await getConfig();
   const files = getMdxFiles(DOCS_DIR);
+  const linkIndex = buildDocsLinkIndex(config, files);
   for (const file of files) {
+    const relativePath = path.relative(DOCS_DIR, file);
     try {
       const content = fs.readFileSync(file, "utf-8");
       const match = content.match(/^---\n([\s\S]*?)\n---/);
@@ -2008,9 +2208,16 @@ async function validateMdxContent() {
         }
       }
       validateComponentUsage(content);
-      await compile(content, { jsx: true });
+      await compile(content, {
+        jsx: true,
+        remarkPlugins: [
+          createInternalLinkValidationPlugin({
+            sourceFile: relativePath,
+            linkIndex
+          })
+        ]
+      });
     } catch (e) {
-      const relativePath = path.relative(DOCS_DIR, file);
       const location = e.line ? `:${e.line}:${e.column}` : "";
       const reason = e.reason || e.message;
       throw new Error(
@@ -2031,5 +2238,6 @@ export {
   getConfig,
   isBundledShikiThemeName,
   loadOpenApiSpec,
+  resolveDocsPageHref,
   validateMdxContent
 };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "radiant-docs-validator",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Shared validation for Radiant documentation repositories",
   "type": "module",
   "scripts": {
     "build": "tsup src/index.ts src/frontmatter-schema.ts src/shiki-theme-config.ts --format esm --dts --clean",
+    "test": "npm run build && node --test test/*.test.mjs",
     "prepublishOnly": "npm run build",
     "release": "node scripts/release.js"
   },