radiant-docs-validator 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -163,11 +163,11 @@ type Footer = {
     socials?: Partial<Record<SocialPlatform, string>>;
     links?: FooterLink[];
 };
-type DocsPageHrefResolution = {
+type DocsHrefResolution = {
     kind: "ignored";
 } | {
     kind: "invalid";
-    reason: "not-root-absolute" | "generated-route" | "empty-target";
+    reason: "not-root-absolute" | "generated-route" | "empty-target" | "path-traversal";
     href: string;
     pathname: string;
     suffix: string;
@@ -179,10 +179,21 @@ type DocsPageHrefResolution = {
     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 function resolveDocsPageHref(href: string): DocsPageHrefResolution;
+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 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 };
+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,14 +289,19 @@ function validateFileExistence(filePath, currentPath) {
     );
   }
 }
-function normalizeDocsFilePath(value) {
+function normalizeDocsRootFilePath(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 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();
@@ -1986,6 +1991,35 @@ 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;
@@ -1996,54 +2030,67 @@ function isIgnoredHref(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 isPublishableStaticAssetPath(filePath) {
+  return PUBLISHABLE_STATIC_ASSET_EXTENSION_SET.has(getHrefExtension(filePath));
 }
-function resolveDocsPageHref(href) {
+function resolveDocsHref(href) {
   const { pathname, suffix } = splitHrefPathAndSuffix(href);
   const baseHref = pathname.trim();
-  if (!isDocsPageLikeHref(baseHref)) {
+  if (isIgnoredHref(baseHref)) {
     return { kind: "ignored" };
   }
-  const filePath = normalizeDocsFilePath(baseHref);
+  const normalizedRootFilePath = normalizeDocsRootFilePath(baseHref);
   const baseResult = {
     href,
     pathname: baseHref,
     suffix,
-    filePath
+    filePath: normalizedRootFilePath
   };
+  if (containsPathTraversal(baseHref)) {
+    return {
+      kind: "invalid",
+      reason: "path-traversal",
+      ...baseResult
+    };
+  }
   if (!baseHref.startsWith("/")) {
     return {
       kind: "invalid",
       reason: "not-root-absolute",
       ...baseResult,
-      suggestedHref: filePath ? `/${filePath}` : void 0
+      suggestedHref: normalizedRootFilePath ? `/${normalizedRootFilePath}` : void 0
     };
   }
-  const extension = getHrefExtension(baseHref);
-  if (extension && !DOCS_PAGE_SOURCE_EXTENSIONS.has(extension)) {
+  if (!normalizedRootFilePath) {
     return {
       kind: "invalid",
-      reason: "generated-route",
+      reason: "empty-target",
       ...baseResult
     };
   }
-  if (!filePath) {
+  const extension = getHrefExtension(baseHref);
+  if (DOCS_PAGE_ROUTE_EXTENSIONS.has(extension)) {
     return {
       kind: "invalid",
-      reason: "empty-target",
+      reason: "generated-route",
       ...baseResult
     };
   }
+  if (!extension || DOCS_PAGE_SOURCE_EXTENSIONS.has(extension)) {
+    return {
+      kind: "docs-page",
+      ...baseResult,
+      filePath: normalizeDocsFilePath(baseHref)
+    };
+  }
   return {
-    kind: "docs-page",
-    ...baseResult
+    kind: "local-asset",
+    ...baseResult,
+    extension,
+    publishable: isPublishableStaticAssetPath(normalizedRootFilePath)
   };
 }
+var resolveDocsPageHref = resolveDocsHref;
 function addRoutableDocsFilePath(routableFilePaths, filePath) {
   if (typeof filePath !== "string") return;
   const normalizedFilePath = normalizeDocsFilePath(filePath);
@@ -2104,7 +2151,7 @@ function buildDocsLinkIndex(config, files) {
   };
 }
 function validateDocsRootAbsoluteHref(args) {
-  const resolvedHref = resolveDocsPageHref(args.href);
+  const resolvedHref = resolveDocsHref(args.href);
   if (resolvedHref.kind === "ignored") return;
   if (resolvedHref.kind === "invalid") {
     if (resolvedHref.reason === "not-root-absolute") {
@@ -2118,10 +2165,34 @@ function validateDocsRootAbsoluteHref(args) {
         `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;
   }
@@ -2150,7 +2221,16 @@ function createInternalLinkValidationPlugin(args) {
         validateDocsRootAbsoluteHref({
           href: node.url,
           sourceFile: args.sourceFile,
-          linkIndex: args.linkIndex
+          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") {
@@ -2161,12 +2241,15 @@ function createInternalLinkValidationPlugin(args) {
       for (const attribute of element.attributes) {
         const hrefAttribute = attribute;
         if (hrefAttribute.type !== "mdxJsxAttribute") continue;
-        if (hrefAttribute.name !== "href") 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
+          linkIndex: args.linkIndex,
+          expectedTarget: hrefAttribute.name === "src" ? "asset" : "link"
         });
       }
     });
@@ -2232,12 +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,6 +1,6 @@
 {
   "name": "radiant-docs-validator",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Shared validation for Radiant documentation repositories",
   "type": "module",
   "scripts": {