starlight-links-validator 0.2.0 → 0.4.0

package/index.ts

@@ -1,4 +1,5 @@
 import type { AstroIntegration } from 'astro'
+import { AstroError } from 'astro/errors'
 
 import { remarkStarlightLinksValidator } from './libs/remark'
 import { logErrors, validateLinks } from './libs/validation'
@@ -18,13 +19,16 @@ export default function starlightLinksValidatorIntegration(): AstroIntegration {
           },
         })
       },
-      'astro:build:done': ({ pages }) => {
-        const errors = validateLinks(pages)
+      'astro:build:done': ({ dir, pages }) => {
+        const errors = validateLinks(pages, dir)
 
         logErrors(errors)
 
         if (errors.size > 0) {
-          throw new Error('Links validation failed.')
+          throw new AstroError(
+            'Links validation failed.',
+            `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/HiDeoo/starlight-links-validator/issues/new/choose.`,
+          )
         }
       },
     },

package/libs/remark.ts

@@ -85,7 +85,6 @@ export const remarkStarlightLinksValidator: Plugin<[], Root> = function () {
         case 'html': {
           const htmlTree = fromHtml(node.value, { fragment: true })
 
-          // @ts-expect-error - https://github.com/microsoft/TypeScript/issues/51188
           visit(htmlTree, (htmlNode: Nodes) => {
             if (hasProperty(htmlNode, 'id') && typeof htmlNode.properties.id === 'string') {
               fileHeadings.push(htmlNode.properties.id)

package/libs/validation.ts

@@ -1,8 +1,11 @@
+import { statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
 import { bgGreen, black, bold, cyan, dim, red } from 'kleur/colors'
 
 import { getValidationData, type Headings } from './remark'
 
-export function validateLinks(pages: PageData[]): ValidationErrors {
+export function validateLinks(pages: PageData[], outputDir: URL): ValidationErrors {
   process.stdout.write(`\n${bgGreen(black(` validating links `))}\n`)
 
   const { headings, links } = getValidationData()
@@ -15,7 +18,7 @@ export function validateLinks(pages: PageData[]): ValidationErrors {
       if (link.startsWith('#')) {
         validateSelfAnchor(errors, link, filePath, headings)
       } else {
-        validateLink(errors, link, filePath, headings, allPages)
+        validateLink(errors, link, filePath, headings, allPages, outputDir)
       }
     }
   }
@@ -36,10 +39,10 @@ export function logErrors(errors: ValidationErrors) {
       red(
         `Found ${errorCount} invalid ${pluralize(errorCount, 'link')} in ${errors.size} ${pluralize(
           errors.size,
-          'file'
-        )}.`
-      )
-    )}\n\n`
+          'file',
+        )}.`,
+      ),
+    )}\n\n`,
   )
 
   for (const [file, links] of errors) {
@@ -58,7 +61,14 @@ export function logErrors(errors: ValidationErrors) {
 /**
  * Validate a link to another internal page that may or may not have a hash.
  */
-function validateLink(errors: ValidationErrors, link: string, filePath: string, headings: Headings, pages: Pages) {
+function validateLink(
+  errors: ValidationErrors,
+  link: string,
+  filePath: string,
+  headings: Headings,
+  pages: Pages,
+  outputDir: URL,
+) {
   const sanitizedLink = link.replace(/^\//, '')
   const segments = sanitizedLink.split('#')
 
@@ -67,7 +77,13 @@ function validateLink(errors: ValidationErrors, link: string, filePath: string,
 
   if (path === undefined) {
     throw new Error('Failed to validate a link with no path.')
-  } else if (path.length > 0 && !path.endsWith('/')) {
+  }
+
+  if (isValidAsset(path, outputDir)) {
+    return
+  }
+
+  if (path.length > 0 && !path.endsWith('/')) {
     path += '/'
   }
 
@@ -100,6 +116,21 @@ function validateSelfAnchor(errors: ValidationErrors, hash: string, filePath: st
   }
 }
 
+/**
+ * Check if a link is a valid asset in the build output directory.
+ */
+function isValidAsset(path: string, outputDir: URL) {
+  const filePath = fileURLToPath(new URL(path, outputDir))
+
+  try {
+    const stats = statSync(filePath)
+
+    return stats.isFile()
+  } catch {
+    return false
+  }
+}
+
 function addError(errors: ValidationErrors, filePath: string, link: string) {
   const fileErrors = errors.get(filePath) ?? []
   fileErrors.push(link)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-links-validator",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Astro integration for Starlight to validate internal links.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
@@ -14,25 +14,26 @@
     "hast-util-from-html": "2.0.1",
     "hast-util-has-property": "3.0.0",
     "kleur": "4.1.5",
-    "mdast-util-to-string": "3.2.0",
-    "unist-util-visit": "4.1.2"
+    "mdast-util-to-string": "4.0.0",
+    "unist-util-visit": "5.0.0"
   },
   "devDependencies": {
-    "@types/hast": "3.0.0",
-    "@types/mdast": "3.0.11",
-    "@types/node": "18.16.18",
-    "astro": "2.10.9",
-    "mdast-util-mdx-jsx": "2.1.4",
+    "@astrojs/starlight": "0.10.1",
+    "@types/hast": "3.0.1",
+    "@types/mdast": "4.0.0",
+    "@types/node": "18.17.18",
+    "astro": "3.1.1",
+    "mdast-util-mdx-jsx": "3.0.0",
     "typescript": "5.1.3",
-    "unified": "10.1.2",
+    "unified": "11.0.3",
     "vitest": "0.32.2"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.0.1",
-    "astro": ">=2.5.0"
+    "@astrojs/starlight": ">=0.9.0",
+    "astro": ">=3.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.14.1"
   },
   "packageManager": "pnpm@8.6.3",
   "publishConfig": {