starlight-links-validator 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # starlight-links-validator
 
+## 0.17.0
+
+### Minor Changes
+
+- [#108](https://github.com/HiDeoo/starlight-links-validator/pull/108) [`82f8ec5`](https://github.com/HiDeoo/starlight-links-validator/commit/82f8ec5cff97d5b9e343440666a3bb67de216b00) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for [excluding](https://starlight-links-validator.vercel.app/configuration#exclude) links from validation using a function.
+
+  When using the function syntax, the function should return `true` for any link that should be excluded from validation or `false` otherwise. The function will be called for each link to validate and will receive an object containing various properties to help determine whether to exclude the link or not.
+
+  Check out the [`exclude` configuration option](https://starlight-links-validator.vercel.app/configuration#exclude) documentation for more details and examples.
+
 ## 0.16.0
 
 ### Minor Changes

package/index.ts

@@ -61,13 +61,38 @@ const starlightLinksValidatorOptionsSchema = z
      */
     errorOnLocalLinks: z.boolean().default(true),
     /**
-     * Defines a list of links or glob patterns that should be excluded from validation.
+     * Defines a list of links or glob patterns that should be excluded from validation or a function that will be
+     * called for each link to determine if it should be excluded from validation or not.
      *
-     * The links in this list will be ignored by the plugin and will not be validated.
+     * The links in this list or links where the function returns `true` will be ignored by the plugin and will not be
+     * validated.
      *
      * @default []
      */
-    exclude: z.array(z.string()).default([]),
+    exclude: z
+      .union([
+        z.array(z.string()),
+        z
+          .function()
+          .args(
+            z.object({
+              /**
+               * The absolute path to the file where the link is defined.
+               */
+              file: z.string(),
+              /**
+               * The link to validate as authored in the content.
+               */
+              link: z.string(),
+              /**
+               * The slug of the page where the link is defined.
+               */
+              slug: z.string(),
+            }),
+          )
+          .returns(z.boolean()),
+      ])
+      .default([]),
     /**
      * Defines the policy for external links with an origin matching the Astro `site` option.
      *

package/libs/i18n.ts

@@ -1,5 +1,5 @@
 import { ensureLeadingSlash, ensureTrailingSlash, stripLeadingSlash } from './path'
-import type { Headings } from './remark'
+import type { ValidationData } from './remark'
 import type { StarlightUserConfig } from './validation'
 
 export function getLocaleConfig(config: StarlightUserConfig): LocaleConfig | undefined {
@@ -30,7 +30,7 @@ export function getLocaleConfig(config: StarlightUserConfig): LocaleConfig | und
 
 export function getFallbackHeadings(
   path: string,
-  headings: Headings,
+  validationData: ValidationData,
   localeConfig: LocaleConfig | undefined,
   base: string,
 ): string[] | undefined {
@@ -48,7 +48,7 @@ export function getFallbackHeadings(
           (localeConfig.defaultLocale === '' ? localeConfig.defaultLocale : `${localeConfig.defaultLocale}/`),
       )
 
-      return headings.get(fallbackPath === '' ? '/' : fallbackPath)
+      return validationData.get(fallbackPath === '' ? '/' : fallbackPath)?.headings
     }
   }
 

package/libs/remark.ts

@@ -25,10 +25,8 @@ const builtInComponents: StarlightLinksValidatorOptions['components'] = [
   ['LinkCard', 'href'],
 ]
 
-// All the headings keyed by file path.
-const headings: Headings = new Map()
-// All the internal links keyed by file path.
-const links: Links = new Map()
+// All the validation data keyed by file path.
+const data: ValidationData = new Map()
 
 export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidatorConfig], Root> = function (config) {
   const { base, options, srcDir } = config
@@ -40,8 +38,11 @@ export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidato
   return (tree, file) => {
     if (file.data.astro?.frontmatter?.['draft']) return
 
+    const originalPath = file.history[0]
+    if (!originalPath) throw new Error('Missing file path to validate links.')
+
     const slugger = new GitHubSlugger()
-    const filePath = normalizeFilePath(base, srcDir, file.history[0])
+    const filePath = normalizeFilePath(base, srcDir, originalPath)
     const slug: string | undefined =
       typeof file.data.astro?.frontmatter?.['slug'] === 'string' ? file.data.astro.frontmatter['slug'] : undefined
 
@@ -155,13 +156,16 @@ export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidato
       }
     })
 
-    headings.set(getFilePath(base, filePath, slug), fileHeadings)
-    links.set(getFilePath(base, filePath, slug), fileLinks)
+    data.set(getFilePath(base, filePath, slug), {
+      file: originalPath,
+      headings: fileHeadings,
+      links: fileLinks,
+    })
   }
 }
 
-export function getValidationData() {
-  return { headings, links }
+export function getValidationData(): ValidationData {
+  return data
 }
 
 function getLinkToValidate(link: string, { options, site }: RemarkStarlightLinksValidatorConfig): Link | undefined {
@@ -202,11 +206,7 @@ function getFilePath(base: string, filePath: string, slug: string | undefined) {
   return filePath
 }
 
-function normalizeFilePath(base: string, srcDir: URL, filePath?: string) {
-  if (!filePath) {
-    throw new Error('Missing file path to validate links.')
-  }
-
+function normalizeFilePath(base: string, srcDir: URL, filePath: string) {
   const path = nodePath
     .relative(nodePath.join(fileURLToPath(srcDir), 'content/docs'), filePath)
     .replace(/\.\w+$/, '')
@@ -234,8 +234,17 @@ export interface RemarkStarlightLinksValidatorConfig {
   srcDir: URL
 }
 
-export type Headings = Map<string, string[]>
-export type Links = Map<string, Link[]>
+export type ValidationData = Map<
+  string,
+  {
+    // The absolute path to the file.
+    file: string
+    // All the headings.
+    headings: string[]
+    // All the internal links.
+    links: Link[]
+  }
+>
 
 export interface Link {
   error?: ValidationErrorType

package/libs/validation.ts

@@ -11,7 +11,7 @@ import type { StarlightLinksValidatorOptions } from '..'
 
 import { getFallbackHeadings, getLocaleConfig, isInconsistentLocaleLink, type LocaleConfig } from './i18n'
 import { ensureTrailingSlash, stripLeadingSlash, stripTrailingSlash } from './path'
-import { getValidationData, type Headings, type Link } from './remark'
+import { getValidationData, type Link, type ValidationData } from './remark'
 
 export const ValidationErrorType = {
   InconsistentLocale: 'inconsistent locale',
@@ -36,7 +36,7 @@ export function validateLinks(
   process.stdout.write(`\n${bgGreen(black(` validating links `))}\n`)
 
   const localeConfig = getLocaleConfig(starlightConfig)
-  const { headings, links } = getValidationData()
+  const validationData = getValidationData()
   const allPages: Pages = new Set(
     pages.map((page) =>
       ensureTrailingSlash(
@@ -49,19 +49,19 @@ export function validateLinks(
 
   const errors: ValidationErrors = new Map()
 
-  for (const [filePath, fileLinks] of links) {
+  for (const [filePath, { links: fileLinks }] of validationData) {
     for (const link of fileLinks) {
       const validationContext: ValidationContext = {
         astroConfig,
         customPages,
         errors,
         filePath,
-        headings,
         link,
         localeConfig,
         options,
         outputDir,
         pages: allPages,
+        validationData,
       }
 
       if (link.raw.startsWith('#') || link.raw.startsWith('?')) {
@@ -194,23 +194,29 @@ function validateLink(context: ValidationContext) {
   }
 }
 
-function getFileHeadings(path: string, { astroConfig, headings, localeConfig, options }: ValidationContext) {
-  let heading = headings.get(path === '' ? '/' : path)
+function getFileHeadings(path: string, { astroConfig, localeConfig, options, validationData }: ValidationContext) {
+  let headings = validationData.get(path === '' ? '/' : path)?.headings
 
-  if (!options.errorOnFallbackPages && !heading && localeConfig) {
-    heading = getFallbackHeadings(path, headings, localeConfig, astroConfig.base)
+  if (!options.errorOnFallbackPages && !headings && localeConfig) {
+    headings = getFallbackHeadings(path, validationData, localeConfig, astroConfig.base)
   }
 
-  return heading
+  return headings
 }
 
 /**
  * Validate a link to an hash in the same page.
  */
-function validateSelfHash({ errors, link, filePath, headings }: ValidationContext) {
+function validateSelfHash(context: ValidationContext) {
+  const { errors, link, filePath, validationData } = context
+
+  if (isExcludedLink(link, context)) {
+    return
+  }
+
   const hash = link.raw.split('#')[1] ?? link.raw
   const sanitizedHash = hash.replace(/^#/, '')
-  const fileHeadings = headings.get(filePath)
+  const fileHeadings = validationData.get(filePath)?.headings
 
   if (!fileHeadings) {
     throw new Error(`Failed to find headings for the file at '${filePath}'.`)
@@ -248,8 +254,17 @@ function isValidAsset(path: string, context: ValidationContext) {
 /**
  * Check if a link is excluded from validation by the user.
  */
-function isExcludedLink(link: Link, context: ValidationContext) {
-  return picomatch(context.options.exclude)(stripQueryString(link.raw))
+function isExcludedLink(link: Link, { filePath, options, validationData }: ValidationContext) {
+  if (Array.isArray(options.exclude)) return picomatch(options.exclude)(stripQueryString(link.raw))
+
+  const file = validationData.get(filePath)?.file
+  if (!file) throw new Error('Missing file path to check exclusion.')
+
+  return options.exclude({
+    file,
+    link: link.raw,
+    slug: stripTrailingSlash(filePath),
+  })
 }
 
 function stripQueryString(path: string): string {
@@ -294,12 +309,12 @@ interface ValidationContext {
   customPages: Set<string>
   errors: ValidationErrors
   filePath: string
-  headings: Headings
   link: Link
   localeConfig: LocaleConfig | undefined
   options: StarlightLinksValidatorOptions
   outputDir: URL
   pages: Pages
+  validationData: ValidationData
 }
 
 export type StarlightUserConfig = Omit<StarlightUserConfigWithPlugins, 'plugins'>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-links-validator",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "MIT",
   "description": "Starlight plugin to validate internal links.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",