starlight-links-validator 0.14.3 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # starlight-links-validator
 
+## 0.15.0
+
+### Minor Changes
+
+- [#93](https://github.com/HiDeoo/starlight-links-validator/pull/93) [`6d7174b`](https://github.com/HiDeoo/starlight-links-validator/commit/6d7174bcc6a2bb39f287a50bbdda29a6af4c16c8) Thanks [@HiDeoo](https://github.com/HiDeoo)! - ⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now version `0.32.0`.
+
+  Please use the `@astrojs/upgrade` command to upgrade your project:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+- [#100](https://github.com/HiDeoo/starlight-links-validator/pull/100) [`b238cb7`](https://github.com/HiDeoo/starlight-links-validator/commit/b238cb7bd3db5f8fe848c317ba52d5ab44eb853e) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds a new [`sameSitePolicy` option](https://starlight-links-validator.vercel.app/configuration#samesitepolicy) to configure how external links pointing to the same origin as the one configured in the [Astro `site` option](https://docs.astro.build/en/reference/configuration-reference/#site) should be handled.
+
+  The current default behavior to ignore all external links remains unchanged. This new option allows to error on such links so they can be rewritten without the origin or to validate them as if they were internal links.
+
+- [#100](https://github.com/HiDeoo/starlight-links-validator/pull/100) [`b238cb7`](https://github.com/HiDeoo/starlight-links-validator/commit/b238cb7bd3db5f8fe848c317ba52d5ab44eb853e) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds a new [`components`](https://starlight-links-validator.vercel.app/configuration#components) option to define additional components and their props to validate as links on top of the built-in `<LinkButton>` and `<LinkCard>` Starlight components.
+
+### Patch Changes
+
+- [#99](https://github.com/HiDeoo/starlight-links-validator/pull/99) [`56ea78c`](https://github.com/HiDeoo/starlight-links-validator/commit/56ea78cefa40f554f88a32181daae1a82ec2fa9a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes validation issue with the [Astro `base` option](https://docs.astro.build/en/reference/configuration-reference/#base) and the [`errorOnFallbackPages` plugin option](https://starlight-links-validator.vercel.app/configuration#erroronfallbackpages) set to `false` in a multilingual project.
+
 ## 0.14.3
 
 ### Patch Changes

package/index.ts

@@ -4,12 +4,22 @@ import { AstroError } from 'astro/errors'
 import { z } from 'astro/zod'
 
 import { clearContentLayerCache } from './libs/astro'
-import { pathnameToSlug } from './libs/path'
-import { remarkStarlightLinksValidator } from './libs/remark'
+import { pathnameToSlug, stripTrailingSlash } from './libs/path'
+import { remarkStarlightLinksValidator, type RemarkStarlightLinksValidatorConfig } from './libs/remark'
 import { logErrors, validateLinks } from './libs/validation'
 
 const starlightLinksValidatorOptionsSchema = z
   .object({
+    /**
+     * Defines a list of additional components and their props that should be validated as links.
+     *
+     * By default, the plugin will only validate links defined in the `href` prop of the `<LinkButton>` and `<LinkCard>`
+     * built-in Starlight components.
+     * Adding custom components to this list will allow the plugin to validate links in those components as well.
+     *
+     * @default []
+     */
+    components: z.tuple([z.string(), z.string()]).array().default([]),
     /**
      * Defines whether the plugin should error on fallback pages.
      *
@@ -58,6 +68,20 @@ const starlightLinksValidatorOptionsSchema = z
      * @default []
      */
     exclude: z.array(z.string()).default([]),
+    /**
+     * Defines the policy for external links with an origin matching the Astro `site` option.
+     *
+     * By default, all external links are ignored and not validated by the plugin.
+     * Setting this option to `error` will make the plugin error on external links with an origin matching the Astro
+     * `site` option and hint that the link can be rewritten without the origin.
+     * Setting this option to `validate` will make the plugin validate external links with an origin matching the Astro
+     * `site` option as if they were internal links.
+     *
+     * @default 'ignore'
+     * @see https://docs.astro.build/en/reference/configuration-reference/#site
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/origin
+     */
+    sameSitePolicy: z.enum(['error', 'ignore', 'validate']).default('ignore'),
   })
   .default({})
 
@@ -73,8 +97,9 @@ export default function starlightLinksValidatorPlugin(
   return {
     name: 'starlight-links-validator-plugin',
     hooks: {
-      setup({ addIntegration, astroConfig, config: starlightConfig, logger }) {
+      'config:setup'({ addIntegration, astroConfig, config: starlightConfig, logger }) {
         let routes: IntegrationResolvedRoute[] = []
+        const site = astroConfig.site ? stripTrailingSlash(astroConfig.site) : undefined
 
         addIntegration({
           name: 'starlight-links-validator-integration',
@@ -89,7 +114,15 @@ export default function starlightLinksValidatorPlugin(
               updateConfig({
                 markdown: {
                   remarkPlugins: [
-                    [remarkStarlightLinksValidator, { base: astroConfig.base, srcDir: astroConfig.srcDir }],
+                    [
+                      remarkStarlightLinksValidator,
+                      {
+                        base: astroConfig.base,
+                        options: options.data,
+                        site,
+                        srcDir: astroConfig.srcDir,
+                      } satisfies RemarkStarlightLinksValidatorConfig,
+                    ],
                   ],
                 },
               })
@@ -111,7 +144,7 @@ export default function starlightLinksValidatorPlugin(
 
               const errors = validateLinks(pages, customPages, dir, astroConfig, starlightConfig, options.data)
 
-              const hasInvalidLinkToCustomPage = logErrors(logger, errors)
+              const hasInvalidLinkToCustomPage = logErrors(logger, errors, site)
 
               if (errors.size > 0) {
                 throwPluginError(

package/libs/i18n.ts

@@ -1,4 +1,4 @@
-import { ensureLeadingSlash, ensureTrailingSlash } from './path'
+import { ensureLeadingSlash, ensureTrailingSlash, stripLeadingSlash } from './path'
 import type { Headings } from './remark'
 import type { StarlightUserConfig } from './validation'
 
@@ -32,14 +32,20 @@ export function getFallbackHeadings(
   path: string,
   headings: Headings,
   localeConfig: LocaleConfig | undefined,
+  base: string,
 ): string[] | undefined {
   if (!localeConfig) return
 
+  const isPathWithBase = base !== '/'
+  const normalizedBase = isPathWithBase ? ensureTrailingSlash(stripLeadingSlash(base)) : ''
+  const normalizedPath = isPathWithBase ? path.replace(normalizedBase, '') : path
+
   for (const locale of localeConfig.locales) {
-    if (path.startsWith(`${locale}/`)) {
+    if (normalizedPath.startsWith(`${locale}/`)) {
       const fallbackPath = path.replace(
-        new RegExp(`^${locale}/`),
-        localeConfig.defaultLocale === '' ? localeConfig.defaultLocale : `${localeConfig.defaultLocale}/`,
+        new RegExp(`^${normalizedBase}${locale}/`),
+        normalizedBase +
+          (localeConfig.defaultLocale === '' ? localeConfig.defaultLocale : `${localeConfig.defaultLocale}/`),
       )
 
       return headings.get(fallbackPath === '' ? '/' : fallbackPath)

package/libs/remark.ts

@@ -3,6 +3,7 @@ import 'mdast-util-mdx-jsx'
 import nodePath from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import type { AstroConfig } from 'astro'
 import GitHubSlugger, { slug } from 'github-slugger'
 import type { Nodes } from 'hast'
 import { fromHtml } from 'hast-util-from-html'
@@ -14,17 +15,28 @@ import { toString } from 'mdast-util-to-string'
 import type { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
 
+import type { StarlightLinksValidatorOptions } from '..'
+
 import { ensureTrailingSlash, stripLeadingSlash } from './path'
+import { ValidationErrorType } from './validation'
+
+const builtInComponents: StarlightLinksValidatorOptions['components'] = [
+  ['LinkButton', 'href'],
+  ['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()
 
-export const remarkStarlightLinksValidator: Plugin<[{ base: string; srcDir: URL }], Root> = function ({
-  base,
-  srcDir,
-}) {
+export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidatorConfig], Root> = function (config) {
+  const { base, options, srcDir } = config
+
+  const linkComponents: Record<string, string> = Object.fromEntries(
+    [...builtInComponents, ...options.components].map(([name, attribute]) => [name, attribute]),
+  )
+
   return (tree, file) => {
     if (file.data.astro?.frontmatter?.['draft']) return
 
@@ -34,7 +46,7 @@ export const remarkStarlightLinksValidator: Plugin<[{ base: string; srcDir: URL
       typeof file.data.astro?.frontmatter?.['slug'] === 'string' ? file.data.astro.frontmatter['slug'] : undefined
 
     const fileHeadings: string[] = []
-    const fileLinks: string[] = []
+    const fileLinks: Link[] = []
     const fileDefinitions = new Map<string, string>()
 
     visit(tree, 'definition', (node) => {
@@ -64,18 +76,17 @@ export const remarkStarlightLinksValidator: Plugin<[{ base: string; srcDir: URL
           break
         }
         case 'link': {
-          if (shouldValidateLink(node.url)) {
-            fileLinks.push(node.url)
-          }
+          const link = getLinkToValidate(node.url, config)
+          if (link) fileLinks.push(link)
 
           break
         }
         case 'linkReference': {
           const definition = fileDefinitions.get(node.identifier)
+          if (!definition) break
 
-          if (definition && shouldValidateLink(definition)) {
-            fileLinks.push(definition)
-          }
+          const link = getLinkToValidate(definition, config)
+          if (link) fileLinks.push(link)
 
           break
         }
@@ -86,22 +97,27 @@ export const remarkStarlightLinksValidator: Plugin<[{ base: string; srcDir: URL
             }
           }
 
-          if (node.name !== 'a' && node.name !== 'LinkCard' && node.name !== 'LinkButton') {
+          if (!node.name) {
+            break
+          }
+
+          const componentProp = linkComponents[node.name]
+
+          if (node.name !== 'a' && !componentProp) {
             break
           }
 
           for (const attribute of node.attributes) {
             if (
               attribute.type !== 'mdxJsxAttribute' ||
-              attribute.name !== 'href' ||
+              attribute.name !== (componentProp ?? 'href') ||
               typeof attribute.value !== 'string'
             ) {
               continue
             }
 
-            if (shouldValidateLink(attribute.value)) {
-              fileLinks.push(attribute.value)
-            }
+            const link = getLinkToValidate(attribute.value, config)
+            if (link) fileLinks.push(link)
           }
 
           break
@@ -127,10 +143,10 @@ export const remarkStarlightLinksValidator: Plugin<[{ base: string; srcDir: URL
               htmlNode.type === 'element' &&
               htmlNode.tagName === 'a' &&
               hasProperty(htmlNode, 'href') &&
-              typeof htmlNode.properties.href === 'string' &&
-              shouldValidateLink(htmlNode.properties.href)
+              typeof htmlNode.properties.href === 'string'
             ) {
-              fileLinks.push(htmlNode.properties.href)
+              const link = getLinkToValidate(htmlNode.properties.href, config)
+              if (link) fileLinks.push(link)
             }
           })
 
@@ -148,17 +164,31 @@ export function getValidationData() {
   return { headings, links }
 }
 
-function shouldValidateLink(link: string) {
+function getLinkToValidate(link: string, { options, site }: RemarkStarlightLinksValidatorConfig): Link | undefined {
+  const linkTovalidate = { raw: link }
+
   if (!isAbsoluteUrl(link)) {
-    return true
+    return linkTovalidate
   }
 
   try {
     const url = new URL(link)
 
+    if (options.sameSitePolicy !== 'ignore' && url.origin === site) {
+      if (options.sameSitePolicy === 'error') {
+        return { ...linkTovalidate, error: ValidationErrorType.SameSite }
+      } else {
+        let transformed = link.replace(url.origin, '')
+        if (!transformed) transformed = '/'
+        return { ...linkTovalidate, transformed }
+      }
+    }
+
     return url.hostname === 'localhost' || url.hostname === '127.0.0.1'
+      ? { ...linkTovalidate, error: ValidationErrorType.LocalLink }
+      : undefined
   } catch {
-    return false
+    return undefined
   }
 }
 
@@ -195,8 +225,21 @@ function isMdxIdAttribute(attribute: MdxJsxAttribute | MdxJsxExpressionAttribute
   return attribute.type === 'mdxJsxAttribute' && attribute.name === 'id' && typeof attribute.value === 'string'
 }
 
+export interface RemarkStarlightLinksValidatorConfig {
+  base: string
+  options: StarlightLinksValidatorOptions
+  site: AstroConfig['site']
+  srcDir: URL
+}
+
 export type Headings = Map<string, string[]>
-export type Links = Map<string, string[]>
+export type Links = Map<string, Link[]>
+
+export interface Link {
+  error?: ValidationErrorType
+  raw: string
+  transformed?: string
+}
 
 interface MdxIdAttribute {
   name: 'id'

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 } from './remark'
+import { getValidationData, type Headings, type Link } from './remark'
 
 export const ValidationErrorType = {
   InconsistentLocale: 'inconsistent locale',
@@ -20,6 +20,7 @@ export const ValidationErrorType = {
   InvalidLinkToCustomPage: 'invalid link to custom page',
   LocalLink: 'local link',
   RelativeLink: 'relative link',
+  SameSite: '{{site}} can be omitted',
   TrailingSlashMissing: 'missing trailing slash',
   TrailingSlashForbidden: 'forbidden trailing slash',
 } as const
@@ -63,7 +64,7 @@ export function validateLinks(
         pages: allPages,
       }
 
-      if (link.startsWith('#') || link.startsWith('?')) {
+      if (link.raw.startsWith('#') || link.raw.startsWith('?')) {
         if (options.errorOnInvalidHashes) {
           validateSelfHash(validationContext)
         }
@@ -76,7 +77,7 @@ export function validateLinks(
   return errors
 }
 
-export function logErrors(pluginLogger: AstroIntegrationLogger, errors: ValidationErrors) {
+export function logErrors(pluginLogger: AstroIntegrationLogger, errors: ValidationErrors, site: AstroConfig['site']) {
   const logger = pluginLogger.fork('')
 
   if (errors.size === 0) {
@@ -103,7 +104,7 @@ export function logErrors(pluginLogger: AstroIntegrationLogger, errors: Validati
     for (const [index, validationError] of validationErrors.entries()) {
       logger.info(
         `  ${blue(`${index < validationErrors.length - 1 ? '├' : '└'}─`)} ${validationError.link}${dim(
-          ` - ${validationError.type}`,
+          ` - ${formatValidationError(validationError, site)}`,
         )}`,
       )
       hasInvalidLinkToCustomPage = validationError.type === ValidationErrorType.InvalidLinkToCustomPage
@@ -125,15 +126,13 @@ function validateLink(context: ValidationContext) {
     return
   }
 
-  if (/^https?:\/\//.test(link)) {
-    if (options.errorOnLocalLinks) {
-      addError(errors, filePath, link, ValidationErrorType.LocalLink)
-    }
-
+  if (link.error) {
+    addError(errors, filePath, link, link.error)
     return
   }
 
-  const sanitizedLink = link.replace(/^\//, '')
+  const linkToValidate = link.transformed ?? link.raw
+  const sanitizedLink = linkToValidate.replace(/^\//, '')
   const segments = sanitizedLink.split('#')
 
   const path = segments[0]
@@ -143,7 +142,7 @@ function validateLink(context: ValidationContext) {
     throw new Error('Failed to validate a link with no path.')
   }
 
-  if (path.startsWith('.') || (!link.startsWith('/') && !link.startsWith('?'))) {
+  if (path.startsWith('.') || (!linkToValidate.startsWith('/') && !linkToValidate.startsWith('?'))) {
     if (options.errorOnRelativeLinks) {
       addError(errors, filePath, link, ValidationErrorType.RelativeLink)
     }
@@ -172,7 +171,7 @@ function validateLink(context: ValidationContext) {
     return
   }
 
-  if (options.errorOnInconsistentLocale && localeConfig && isInconsistentLocaleLink(filePath, link, localeConfig)) {
+  if (options.errorOnInconsistentLocale && localeConfig && isInconsistentLocaleLink(filePath, link.raw, localeConfig)) {
     addError(errors, filePath, link, ValidationErrorType.InconsistentLocale)
     return
   }
@@ -195,11 +194,11 @@ function validateLink(context: ValidationContext) {
   }
 }
 
-function getFileHeadings(path: string, { headings, localeConfig, options }: ValidationContext) {
+function getFileHeadings(path: string, { astroConfig, headings, localeConfig, options }: ValidationContext) {
   let heading = headings.get(path === '' ? '/' : path)
 
   if (!options.errorOnFallbackPages && !heading && localeConfig) {
-    heading = getFallbackHeadings(path, headings, localeConfig)
+    heading = getFallbackHeadings(path, headings, localeConfig, astroConfig.base)
   }
 
   return heading
@@ -209,7 +208,7 @@ function getFileHeadings(path: string, { headings, localeConfig, options }: Vali
  * Validate a link to an hash in the same page.
  */
 function validateSelfHash({ errors, link, filePath, headings }: ValidationContext) {
-  const hash = link.split('#')[1] ?? link
+  const hash = link.raw.split('#')[1] ?? link.raw
   const sanitizedHash = hash.replace(/^#/, '')
   const fileHeadings = headings.get(filePath)
 
@@ -249,17 +248,17 @@ function isValidAsset(path: string, context: ValidationContext) {
 /**
  * Check if a link is excluded from validation by the user.
  */
-function isExcludedLink(link: string, context: ValidationContext) {
-  return picomatch(context.options.exclude)(link)
+function isExcludedLink(link: Link, context: ValidationContext) {
+  return picomatch(context.options.exclude)(link.raw)
 }
 
 function stripQueryString(path: string): string {
   return path.split('?')[0] ?? path
 }
 
-function addError(errors: ValidationErrors, filePath: string, link: string, type: ValidationErrorType) {
+function addError(errors: ValidationErrors, filePath: string, link: Link, type: ValidationErrorType) {
   const fileErrors = errors.get(filePath) ?? []
-  fileErrors.push({ link, type })
+  fileErrors.push({ link: link.raw, type })
 
   errors.set(filePath, fileErrors)
 }
@@ -268,6 +267,12 @@ function pluralize(count: number, singular: string) {
   return count === 1 ? singular : `${singular}s`
 }
 
+function formatValidationError(error: ValidationError, site: AstroConfig['site']) {
+  if (error.type !== ValidationErrorType.SameSite || !site) return error.type
+
+  return error.type.replace('{{site}}', site)
+}
+
 // The validation errors keyed by file path.
 type ValidationErrors = Map<string, ValidationError[]>
 
@@ -290,7 +295,7 @@ interface ValidationContext {
   errors: ValidationErrors
   filePath: string
   headings: Headings
-  link: string
+  link: Link
   localeConfig: LocaleConfig | undefined
   options: StarlightLinksValidatorOptions
   outputDir: URL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-links-validator",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "license": "MIT",
   "description": "Starlight plugin to validate internal links.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
@@ -31,7 +31,7 @@
     "vitest": "2.1.6"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.15.0"
+    "@astrojs/starlight": ">=0.32.0"
   },
   "engines": {
     "node": ">=18.17.1"