radiant-docs-validator 0.1.0 → 0.1.4

package/dist/index.d.ts

@@ -163,8 +163,37 @@ type Footer = {
     socials?: Partial<Record<SocialPlatform, string>>;
     links?: FooterLink[];
 };
+type DocsHrefResolution = {
+    kind: "ignored";
+} | {
+    kind: "invalid";
+    reason: "not-root-absolute" | "generated-route" | "empty-target" | "path-traversal";
+    href: string;
+    pathname: string;
+    suffix: string;
+    filePath: string;
+    suggestedHref?: string;
+} | {
+    kind: "docs-page";
+    href: string;
+    pathname: string;
+    suffix: string;
+    filePath: string;
+} | {
+    kind: "local-asset";
+    href: string;
+    pathname: string;
+    suffix: string;
+    filePath: string;
+    extension: string;
+    publishable: boolean;
+};
 declare function loadOpenApiSpec(filePathOrUrl: string): Promise<any>;
 declare function getConfig(): Promise<DocsConfig>;
+declare const PUBLISHABLE_STATIC_ASSET_EXTENSIONS: readonly [".avif", ".csv", ".doc", ".docx", ".gif", ".ico", ".jpeg", ".jpg", ".mp3", ".mp4", ".ogg", ".pdf", ".png", ".ppt", ".pptx", ".svg", ".tsv", ".txt", ".wav", ".webm", ".webp", ".xls", ".xlsx", ".zip"];
+declare function isPublishableStaticAssetPath(filePath: string): boolean;
+declare function resolveDocsHref(href: string): DocsHrefResolution;
+declare const resolveDocsPageHref: typeof resolveDocsHref;
 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 DocsHrefResolution, 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, PUBLISHABLE_STATIC_ASSET_EXTENSIONS, type SocialPlatform, type TagTheme, type ThemeColorByMode, configureDocsValidator, getConfig, isPublishableStaticAssetPath, loadOpenApiSpec, resolveDocsHref, resolveDocsPageHref, validateMdxContent };

package/dist/index.js

@@ -289,6 +289,19 @@ function validateFileExistence(filePath, currentPath) {
     );
   }
 }
+function normalizeDocsRootFilePath(value) {
+  let normalized = value.replace(/\\/g, "/").trim();
+  if (!normalized) return "";
+  normalized = normalized.replace(/^\/+/, "").replace(/\/+$/, "");
+  const posixNormalized = path.posix.normalize(`/${normalized}`).replace(/^\/+/, "");
+  return posixNormalized === "." ? "" : posixNormalized;
+}
+function normalizeDocsFilePath(value) {
+  return normalizeDocsRootFilePath(value).replace(/\.(md|mdx)$/i, "");
+}
+function containsPathTraversal(value) {
+  return value.replace(/\\/g, "/").split("/").includes("..");
+}
 function normalizeDocsPagePath(value, currentPath, label = "Page path") {
   checkType(value, "string", currentPath, label);
   const trimmedPath = value.trim();
@@ -1975,6 +1988,273 @@ 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"]);
+var PUBLISHABLE_STATIC_ASSET_EXTENSIONS = [
+  ".avif",
+  ".csv",
+  ".doc",
+  ".docx",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".mp3",
+  ".mp4",
+  ".ogg",
+  ".pdf",
+  ".png",
+  ".ppt",
+  ".pptx",
+  ".svg",
+  ".tsv",
+  ".txt",
+  ".wav",
+  ".webm",
+  ".webp",
+  ".xls",
+  ".xlsx",
+  ".zip"
+];
+var PUBLISHABLE_STATIC_ASSET_EXTENSION_SET = new Set(
+  PUBLISHABLE_STATIC_ASSET_EXTENSIONS
+);
+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 isPublishableStaticAssetPath(filePath) {
+  return PUBLISHABLE_STATIC_ASSET_EXTENSION_SET.has(getHrefExtension(filePath));
+}
+function resolveDocsHref(href) {
+  const { pathname, suffix } = splitHrefPathAndSuffix(href);
+  const baseHref = pathname.trim();
+  if (isIgnoredHref(baseHref)) {
+    return { kind: "ignored" };
+  }
+  const normalizedRootFilePath = normalizeDocsRootFilePath(baseHref);
+  const baseResult = {
+    href,
+    pathname: baseHref,
+    suffix,
+    filePath: normalizedRootFilePath
+  };
+  if (containsPathTraversal(baseHref)) {
+    return {
+      kind: "invalid",
+      reason: "path-traversal",
+      ...baseResult
+    };
+  }
+  if (!baseHref.startsWith("/")) {
+    return {
+      kind: "invalid",
+      reason: "not-root-absolute",
+      ...baseResult,
+      suggestedHref: normalizedRootFilePath ? `/${normalizedRootFilePath}` : void 0
+    };
+  }
+  if (!normalizedRootFilePath) {
+    return {
+      kind: "invalid",
+      reason: "empty-target",
+      ...baseResult
+    };
+  }
+  const extension = getHrefExtension(baseHref);
+  if (DOCS_PAGE_ROUTE_EXTENSIONS.has(extension)) {
+    return {
+      kind: "invalid",
+      reason: "generated-route",
+      ...baseResult
+    };
+  }
+  if (!extension || DOCS_PAGE_SOURCE_EXTENSIONS.has(extension)) {
+    return {
+      kind: "docs-page",
+      ...baseResult,
+      filePath: normalizeDocsFilePath(baseHref)
+    };
+  }
+  return {
+    kind: "local-asset",
+    ...baseResult,
+    extension,
+    publishable: isPublishableStaticAssetPath(normalizedRootFilePath)
+  };
+}
+var resolveDocsPageHref = resolveDocsHref;
+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 = resolveDocsHref(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".`
+      );
+    }
+    if (resolvedHref.reason === "path-traversal") {
+      throw new Error(
+        `Invalid local URL "${args.href}" in ${args.sourceFile}. Local URLs cannot contain ".." path traversal segments.`
+      );
+    }
+    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 (resolvedHref.kind === "local-asset") {
+    const fullAssetPath = path.join(DOCS_DIR, resolvedHref.filePath);
+    if (!fs.existsSync(fullAssetPath) || !fs.statSync(fullAssetPath).isFile()) {
+      throw new Error(
+        `Invalid local asset "${args.href}" in ${args.sourceFile}. No matching file was found. Expected "${resolvedHref.filePath}" under the docs root.`
+      );
+    }
+    if (!resolvedHref.publishable) {
+      throw new Error(
+        `Invalid local asset "${args.href}" in ${args.sourceFile}. Files with extension "${resolvedHref.extension}" are not published as docs assets.`
+      );
+    }
+    return;
+  }
+  if (args.expectedTarget === "asset") {
+    throw new Error(
+      `Invalid local asset "${args.href}" in ${args.sourceFile}. Asset references must include a supported file extension.`
+    );
+  }
+  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,
+          expectedTarget: "link"
+        });
+      }
+      if (node.type === "image" && typeof node.url === "string") {
+        validateDocsRootAbsoluteHref({
+          href: node.url,
+          sourceFile: args.sourceFile,
+          linkIndex: args.linkIndex,
+          expectedTarget: "asset"
+        });
+      }
+      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" && hrefAttribute.name !== "src") {
+          continue;
+        }
+        if (typeof hrefAttribute.value !== "string") continue;
+        validateDocsRootAbsoluteHref({
+          href: hrefAttribute.value,
+          sourceFile: args.sourceFile,
+          linkIndex: args.linkIndex,
+          expectedTarget: hrefAttribute.name === "src" ? "asset" : "link"
+        });
+      }
+    });
+  };
+}
 function getMdxFiles(dir) {
   let results = [];
   const list = fs.readdirSync(dir);
@@ -1983,7 +2263,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 +2271,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 +2291,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(
@@ -2025,11 +2315,15 @@ export {
   DEFAULT_SHIKI_LIGHT_THEME,
   DEFAULT_THEME_COLOR_DARK,
   DEFAULT_THEME_COLOR_LIGHT,
+  PUBLISHABLE_STATIC_ASSET_EXTENSIONS,
   SHIKI_BUNDLED_THEME_NAMES,
   configureDocsValidator,
   docsSchema,
   getConfig,
   isBundledShikiThemeName,
+  isPublishableStaticAssetPath,
   loadOpenApiSpec,
+  resolveDocsHref,
+  resolveDocsPageHref,
   validateMdxContent
 };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "radiant-docs-validator",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "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"
   },