feat: add support for validating emitted file assets

Author: HiDeoo

packages/starlight-links-validator/index.ts

@@ -18,8 +18,8 @@ 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)
 

packages/starlight-links-validator/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)
       }
     }
   }
@@ -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)

packages/starlight-links-validator/tests/fixtures/base/public/favicon.svg

@@ -31,3 +31,6 @@ some content
     test
   </a>
 </div>
+
+<a href="/icon.svg">Link to invalid asset</a>
+<a href="/guidelines/ui.pdf">Link to another invalid asset</a>

packages/starlight-links-validator/tests/fixtures/base/public/guidelines/dummy.pdf

@@ -20,6 +20,8 @@ title: Test
 - [Link to invalid anchor in this page](#links)
 - [Link to valid anchor in another MDX page](/guides/example/#some-links)
 - [Link to invalid anchor in another MDX page](/guides/example/#links)
+- [Link to invalid asset](/icon.svg)
+- [Link to another invalid asset](/guidelines/ui.pdf)
 
 <div id="aDiv">
 some content

packages/starlight-links-validator/tests/fixtures/with-invalid-links/src/content/docs/guides/example.mdx

@@ -34,3 +34,6 @@ some content
     test text
   </a>
 </div>
+
+<a href="/favicon.svg">Link to an asset</a>
+<a href="/guidelines/dummy.pdf">Link to another asset</a>

packages/starlight-links-validator/tests/fixtures/with-invalid-links/src/content/docs/test.md

@@ -21,6 +21,8 @@ title: Index
 
 - [Link to anchor in this page](#some-links)
 - [Link to anchor in another MDX page](/guides/example/#some-links)
+- [Link to an asset](/favicon.svg)
+- [Link to another asset](/guidelines/dummy.pdf)
 
 ## A more `complex` heading
 

packages/starlight-links-validator/tests/fixtures/with-valid-links/src/content/docs/guides/example.mdx

@@ -18,6 +18,7 @@ export async function loadFixture(name: string) {
 
     // Copy the base fixture files.
     await cp(join(baseFixturePath, 'src'), join(testPath, 'src'), { recursive: true })
+    await cp(join(baseFixturePath, 'public'), join(testPath, 'public'), { recursive: true })
 
     // Copy the fixture under test files that may override the base fixture files.
     await cp(join(fixturePath, 'src'), join(testPath, 'src'), { force: true, recursive: true })

packages/starlight-links-validator/tests/fixtures/with-valid-links/src/content/docs/index.md

@@ -16,7 +16,7 @@ test('should not build with invalid links', async () => {
   try {
     await loadFixture('with-invalid-links')
   } catch (error) {
-    expect(error).toMatch(/Found 14 invalid links in 3 files./)
+    expect(error).toMatch(/Found 18 invalid links in 3 files./)
 
     expect(error).toMatch(
       new RegExp(`▶ test/
@@ -27,6 +27,8 @@ test('should not build with invalid links', async () => {
   ├─ /unknown/#title
   ├─ #links
   ├─ /guides/example/#links
+  ├─ /icon.svg
+  ├─ /guidelines/ui.pdf
   └─ #anotherDiv`)
     )
 
@@ -35,7 +37,9 @@ test('should not build with invalid links', async () => {
   ├─ #links
   ├─ /unknown/#links
   ├─ /unknown
-  └─ #anotherBlock`)
+  ├─ #anotherBlock
+  ├─ /icon.svg
+  └─ /guidelines/ui.pdf`)
     )
 
     expect(error).toMatch(