starlight-links-validator 0.4.2 → 0.5.1

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
   <h1>starlight-links-validator 🦺</h1>
-  <p>Astro integration for Starlight to validate internal links.</p>
+  <p>Starlight plugin to validate internal links.</p>
   <p>
-    <a href="https://i.imgur.com/EgiTGeR.png" title="Screenshot of starlight-links-validator">
-      <img alt="Screenshot of starlight-links-validator" src="https://i.imgur.com/EgiTGeR.png" width="520" />
+    <a href="https://github.com/HiDeoo/starlight-links-validator/assets/494699/fe5f797a-8089-4271-b090-7158bb053dfa" title="Screenshot of starlight-links-validator">
+      <img alt="Screenshot of starlight-links-validator" src="https://github.com/HiDeoo/starlight-links-validator/assets/494699/fe5f797a-8089-4271-b090-7158bb053dfa" width="520" />
     </a>
   </p>
 </div>
@@ -18,9 +18,13 @@
   <br />
 </div>
 
+## Getting Started
+
+Want to get started immediately? Check out the [getting started guide](https://starlight-links-validator.vercel.app/getting-started/).
+
 ## Features
 
-An [Astro](https://astro.build) integration for [Starlight](https://starlight.astro.build) Starlight to validate **_internal_** links in Markdown and MDX files.
+A [Starlight](https://starlight.astro.build) plugin to validate **_internal_** links in Markdown and MDX files.
 
 - Validate internal links to other pages
 - Validate internal links to anchors in other pages
@@ -28,38 +32,6 @@ An [Astro](https://astro.build) integration for [Starlight](https://starlight.as
 - Ignore external links
 - Run only during a production build
 
-## Installation
-
-Install the Starlight Links Validator integration using your favorite package manager, e.g. with [pnpm](https://pnpm.io):
-
-```shell
-pnpm add starlight-links-validator
-```
-
-Update your [Astro configuration](https://docs.astro.build/en/guides/configuring-astro/#supported-config-file-types) to include the Starlight Links Validator integration **_before_** the Starlight integration:
-
-```diff
-  import starlight from '@astrojs/starlight'
-  import { defineConfig } from 'astro/config'
-+ import starlightLinksValidator from 'starlight-links-validator'
-
-  export default defineConfig({
-    // …
-    integrations: [
-+     starlightLinksValidator(),
-      starlight({
-        sidebar: [
-          {
-            label: 'Guides',
-            items: [{ label: 'Example Guide', link: '/guides/example/' }],
-          },
-        ],
-        title: 'My Docs',
-      }),
-    ],
-  })
-```
-
 ## License
 
 Licensed under the MIT License, Copyright © HiDeoo.

package/index.ts

@@ -1,36 +1,90 @@
-import type { AstroIntegration } from 'astro'
+import type { StarlightPlugin } from '@astrojs/starlight/types'
 import { AstroError } from 'astro/errors'
+import { z } from 'astro/zod'
 
 import { remarkStarlightLinksValidator } from './libs/remark'
 import { logErrors, validateLinks } from './libs/validation'
 
-export default function starlightLinksValidatorIntegration(): AstroIntegration {
+const starlightLinksValidatorOptionsSchema = z
+  .object({
+    /**
+     * Defines whether the plugin should error on fallback pages.
+     *
+     * If you do not expect to have all pages translated in all configured locales and want to use the fallback pages
+     * feature built-in into Starlight, you should set this option to `false`.
+     *
+     * @default true
+     * @see https://starlight.astro.build/guides/i18n/#fallback-content
+     */
+    errorOnFallbackPages: z.boolean().default(true),
+    /**
+     * Defines whether the plugin should error on inconsistent locale links.
+     *
+     * When set to `true`, the plugin will error on links that are pointing to a page in a different locale.
+     *
+     * @default false
+     */
+    errorOnInconsistentLocale: z.boolean().default(false),
+    /**
+     * Defines whether the plugin should error on internal relative links.
+     *
+     * When set to `false`, the plugin will ignore relative links (e.g. `./foo` or `../bar`).
+     *
+     * @default true
+     */
+    errorOnRelativeLinks: z.boolean().default(true),
+  })
+  .default({})
+
+export default function starlightLinksValidatorPlugin(
+  userOptions?: StarlightLinksValidatorUserOptions,
+): StarlightPlugin {
+  const options = starlightLinksValidatorOptionsSchema.safeParse(userOptions)
+
+  if (!options.success) {
+    throwPluginError('Invalid options passed to the starlight-links-validator plugin.')
+  }
+
   return {
-    name: 'starlight-links-validator',
+    name: 'starlight-links-validator-plugin',
     hooks: {
-      'astro:config:setup': ({ command, updateConfig }) => {
-        if (command !== 'build') {
-          return
-        }
-
-        updateConfig({
-          markdown: {
-            remarkPlugins: [remarkStarlightLinksValidator],
-          },
-        })
-      },
-      'astro:build:done': ({ dir, pages }) => {
-        const errors = validateLinks(pages, dir)
+      setup({ addIntegration, astroConfig, config: starlightConfig, logger }) {
+        addIntegration({
+          name: 'starlight-links-validator-integration',
+          hooks: {
+            'astro:config:setup': ({ command, updateConfig }) => {
+              if (command !== 'build') {
+                return
+              }
 
-        logErrors(errors)
+              updateConfig({
+                markdown: {
+                  remarkPlugins: [[remarkStarlightLinksValidator, astroConfig.base]],
+                },
+              })
+            },
+            'astro:build:done': ({ dir, pages }) => {
+              const errors = validateLinks(pages, dir, astroConfig.base, starlightConfig, options.data)
 
-        if (errors.size > 0) {
-          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.`,
-          )
-        }
+              logErrors(logger, errors)
+
+              if (errors.size > 0) {
+                throwPluginError('Links validation failed.')
+              }
+            },
+          },
+        })
       },
     },
   }
 }
+
+function throwPluginError(message: string): never {
+  throw new AstroError(
+    message,
+    `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.`,
+  )
+}
+
+type StarlightLinksValidatorUserOptions = z.input<typeof starlightLinksValidatorOptionsSchema>
+export type StarlightLinksValidatorOptions = z.output<typeof starlightLinksValidatorOptionsSchema>

package/libs/i18n.ts

@@ -0,0 +1,78 @@
+import { ensureLeadingSlash, ensureTrailingSlash } from './path'
+import type { Headings } from './remark'
+import type { StarlightUserConfig } from './validation'
+
+export function getLocaleConfig(config: StarlightUserConfig): LocaleConfig | undefined {
+  if (!config.locales || Object.keys(config.locales).length === 0) return
+
+  let defaultLocale = config.defaultLocale
+  const locales: string[] = []
+
+  for (const [dir, locale] of Object.entries(config.locales)) {
+    if (!locale) continue
+
+    if (dir === 'root') {
+      if (!locale.lang) continue
+
+      defaultLocale = ''
+    }
+
+    locales.push(dir)
+  }
+
+  if (defaultLocale === undefined) return
+
+  return {
+    defaultLocale,
+    locales,
+  }
+}
+
+export function getFallbackHeadings(
+  path: string,
+  headings: Headings,
+  localeConfig: LocaleConfig | undefined,
+): string[] | undefined {
+  if (!localeConfig) return
+
+  for (const locale of localeConfig.locales) {
+    if (path.startsWith(`${locale}/`)) {
+      const fallbackPath = path.replace(
+        new RegExp(`^${locale}/`),
+        localeConfig.defaultLocale === '' ? localeConfig.defaultLocale : `${localeConfig.defaultLocale}/`,
+      )
+
+      return headings.get(fallbackPath === '' ? '/' : fallbackPath)
+    }
+  }
+
+  return
+}
+
+export function isInconsistentLocaleLink(path: string, link: string, localeConfig: LocaleConfig) {
+  const pathLocale = getLocale(path, localeConfig)
+  const linkLocale = getLocale(link, localeConfig)
+
+  if (pathLocale !== undefined || linkLocale !== undefined) {
+    return pathLocale !== linkLocale
+  }
+
+  return false
+}
+
+function getLocale(path: string, localeConfig: LocaleConfig) {
+  const normalizedPath = ensureTrailingSlash(ensureLeadingSlash(path))
+
+  for (const locale of localeConfig.locales) {
+    if (normalizedPath.startsWith(`/${locale}/`)) {
+      return locale
+    }
+  }
+
+  return
+}
+
+export interface LocaleConfig {
+  defaultLocale: string
+  locales: string[]
+}

package/libs/path.ts

@@ -0,0 +1,11 @@
+export function ensureLeadingSlash(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`
+}
+
+export function ensureTrailingSlash(path: string): string {
+  return path.endsWith('/') ? path : `${path}/`
+}
+
+export function stripLeadingSlash(path: string) {
+  return path.replace(/^\//, '')
+}

package/libs/remark.ts

@@ -12,15 +12,17 @@ import { toString } from 'mdast-util-to-string'
 import type { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
 
+import { stripLeadingSlash } from './path'
+
 // 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<[], Root> = function () {
+export const remarkStarlightLinksValidator: Plugin<[base: string], Root> = function (base) {
   return (tree, file) => {
     const slugger = new GitHubSlugger()
-    const filePath = normalizeFilePath(file.history[0])
+    const filePath = normalizeFilePath(base, file.history[0])
 
     const fileHeadings: string[] = []
     const fileLinks: string[] = []
@@ -131,22 +133,28 @@ export function getValidationData() {
 }
 
 function isInternalLink(link: string) {
-  return nodePath.isAbsolute(link) || link.startsWith('#')
+  return nodePath.isAbsolute(link) || link.startsWith('#') || link.startsWith('.')
 }
 
-function normalizeFilePath(filePath?: string) {
+function normalizeFilePath(base: string, filePath?: string) {
   if (!filePath) {
     throw new Error('Missing file path to validate links.')
   }
 
-  return nodePath
+  const path = nodePath
     .relative(nodePath.join(process.cwd(), 'src/content/docs'), filePath)
     .replace(/\.\w+$/, '')
     .replace(/index$/, '')
-    .replace(/\/?$/, '/')
+    .replace(/[/\\]?$/, '/')
     .split(/[/\\]/)
     .map((segment) => slug(segment))
     .join('/')
+
+  if (base !== '/') {
+    return nodePath.posix.join(stripLeadingSlash(base), path)
+  }
+
+  return path
 }
 
 function isMdxIdAttribute(attribute: MdxJsxAttribute | MdxJsxExpressionAttribute): attribute is MdxIdAttribute {

package/libs/validation.ts

@@ -1,24 +1,60 @@
 import { statSync } from 'node:fs'
+import { posix } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { bgGreen, black, bold, cyan, dim, red } from 'kleur/colors'
+import type { StarlightPlugin } from '@astrojs/starlight/types'
+import type { AstroIntegrationLogger } from 'astro'
+import { bgGreen, black, blue, dim, green, red } from 'kleur/colors'
 
+import type { StarlightLinksValidatorOptions } from '..'
+
+import { getFallbackHeadings, getLocaleConfig, isInconsistentLocaleLink, type LocaleConfig } from './i18n'
+import { ensureTrailingSlash, stripLeadingSlash } from './path'
 import { getValidationData, type Headings } from './remark'
 
-export function validateLinks(pages: PageData[], outputDir: URL): ValidationErrors {
+export const ValidationErrorType = {
+  InconsistentLocale: 'inconsistent locale',
+  InvalidAnchor: 'invalid anchor',
+  InvalidLink: 'invalid link',
+  RelativeLink: 'relative link',
+} as const
+
+export function validateLinks(
+  pages: PageData[],
+  outputDir: URL,
+  base: string,
+  starlightConfig: StarlightUserConfig,
+  options: StarlightLinksValidatorOptions,
+): ValidationErrors {
   process.stdout.write(`\n${bgGreen(black(` validating links `))}\n`)
 
+  const localeConfig = getLocaleConfig(starlightConfig)
   const { headings, links } = getValidationData()
-  const allPages: Pages = new Set(pages.map((page) => page.pathname))
+  const allPages: Pages = new Set(
+    pages.map((page) =>
+      ensureTrailingSlash(base === '/' ? page.pathname : posix.join(stripLeadingSlash(base), page.pathname)),
+    ),
+  )
 
   const errors: ValidationErrors = new Map()
 
   for (const [filePath, fileLinks] of links) {
     for (const link of fileLinks) {
+      const validationContext: ValidationContext = {
+        errors,
+        filePath,
+        headings,
+        link,
+        localeConfig,
+        options,
+        outputDir,
+        pages: allPages,
+      }
+
       if (link.startsWith('#')) {
-        validateSelfAnchor(errors, link, filePath, headings)
+        validateSelfAnchor(validationContext)
       } else {
-        validateLink(errors, link, filePath, headings, allPages, outputDir)
+        validateLink(validationContext)
       }
     }
   }
@@ -26,49 +62,46 @@ export function validateLinks(pages: PageData[], outputDir: URL): ValidationErro
   return errors
 }
 
-export function logErrors(errors: ValidationErrors) {
+export function logErrors(pluginLogger: AstroIntegrationLogger, errors: ValidationErrors) {
+  const logger = pluginLogger.fork('')
+
   if (errors.size === 0) {
-    process.stdout.write(dim('All internal links are valid.\n\n'))
+    logger.info(green('✓ All internal links are valid.\n'))
     return
   }
 
   const errorCount = [...errors.values()].reduce((acc, links) => acc + links.length, 0)
 
-  process.stderr.write(
-    `${bold(
-      red(
-        `Found ${errorCount} invalid ${pluralize(errorCount, 'link')} in ${errors.size} ${pluralize(
-          errors.size,
-          'file',
-        )}.`,
-      ),
-    )}\n\n`,
+  logger.error(
+    red(
+      `✗ Found ${errorCount} invalid ${pluralize(errorCount, 'link')} in ${errors.size} ${pluralize(
+        errors.size,
+        'file',
+      )}.`,
+    ),
   )
 
-  for (const [file, links] of errors) {
-    process.stderr.write(`${red('▶')} ${file}\n`)
+  for (const [file, validationErrors] of errors) {
+    logger.info(`${red('▶')} ${blue(file)}`)
 
-    for (const [index, link] of links.entries()) {
-      process.stderr.write(`  ${cyan(`${index < links.length - 1 ? '├' : '└'}─`)} ${link}\n`)
+    for (const [index, validationError] of validationErrors.entries()) {
+      logger.info(
+        `  ${blue(`${index < validationErrors.length - 1 ? '├' : '└'}─`)} ${validationError.link}${dim(
+          ` - ${validationError.type}`,
+        )}`,
+      )
     }
-
-    process.stdout.write(dim('\n'))
   }
 
-  process.stdout.write(dim('\n'))
+  process.stdout.write('\n')
 }
 
 /**
  * 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,
-  outputDir: URL,
-) {
+function validateLink(context: ValidationContext) {
+  const { errors, filePath, link, localeConfig, options, outputDir, pages } = context
+
   const sanitizedLink = link.replace(/^\//, '')
   const segments = sanitizedLink.split('#')
 
@@ -79,32 +112,53 @@ function validateLink(
     throw new Error('Failed to validate a link with no path.')
   }
 
-  if (isValidAsset(path, outputDir)) {
+  if (path.startsWith('.')) {
+    if (options.errorOnRelativeLinks) {
+      addError(errors, filePath, link, ValidationErrorType.RelativeLink)
+    }
+
     return
   }
 
-  if (path.length > 0 && !path.endsWith('/')) {
-    path += '/'
+  if (isValidAsset(path, outputDir)) {
+    return
   }
 
+  path = ensureTrailingSlash(path)
+
   const isValidPage = pages.has(path)
-  const fileHeadings = headings.get(path === '' ? '/' : path)
+  const fileHeadings = getFileHeadings(path, context)
 
   if (!isValidPage || !fileHeadings) {
-    addError(errors, filePath, link)
+    addError(errors, filePath, link, ValidationErrorType.InvalidLink)
+    return
+  }
+
+  if (options.errorOnInconsistentLocale && localeConfig && isInconsistentLocaleLink(filePath, link, localeConfig)) {
+    addError(errors, filePath, link, ValidationErrorType.InconsistentLocale)
     return
   }
 
   if (hash && !fileHeadings.includes(hash)) {
-    addError(errors, filePath, link)
+    addError(errors, filePath, link, ValidationErrorType.InvalidAnchor)
   }
 }
 
+function getFileHeadings(path: string, { headings, localeConfig, options }: ValidationContext) {
+  let heading = headings.get(path === '' ? '/' : path)
+
+  if (!options.errorOnFallbackPages && !heading && localeConfig) {
+    heading = getFallbackHeadings(path, headings, localeConfig)
+  }
+
+  return heading
+}
+
 /**
  * Validate a link to an anchor in the same page.
  */
-function validateSelfAnchor(errors: ValidationErrors, hash: string, filePath: string, headings: Headings) {
-  const sanitizedHash = hash.replace(/^#/, '')
+function validateSelfAnchor({ errors, link, filePath, headings }: ValidationContext) {
+  const sanitizedHash = link.replace(/^#/, '')
   const fileHeadings = headings.get(filePath)
 
   if (!fileHeadings) {
@@ -112,7 +166,7 @@ function validateSelfAnchor(errors: ValidationErrors, hash: string, filePath: st
   }
 
   if (!fileHeadings.includes(sanitizedHash)) {
-    addError(errors, filePath, hash)
+    addError(errors, filePath, link, 'invalid anchor')
   }
 }
 
@@ -131,9 +185,9 @@ function isValidAsset(path: string, outputDir: URL) {
   }
 }
 
-function addError(errors: ValidationErrors, filePath: string, link: string) {
+function addError(errors: ValidationErrors, filePath: string, link: string, type: ValidationErrorType) {
   const fileErrors = errors.get(filePath) ?? []
-  fileErrors.push(link)
+  fileErrors.push({ link, type })
 
   errors.set(filePath, fileErrors)
 }
@@ -142,11 +196,31 @@ function pluralize(count: number, singular: string) {
   return count === 1 ? singular : `${singular}s`
 }
 
-// The invalid links keyed by file path.
-type ValidationErrors = Map<string, string[]>
+// The validation errors keyed by file path.
+type ValidationErrors = Map<string, ValidationError[]>
+
+export type ValidationErrorType = (typeof ValidationErrorType)[keyof typeof ValidationErrorType]
+
+interface ValidationError {
+  link: string
+  type: ValidationErrorType
+}
 
 interface PageData {
   pathname: string
 }
 
 type Pages = Set<PageData['pathname']>
+
+interface ValidationContext {
+  errors: ValidationErrors
+  filePath: string
+  headings: Headings
+  link: string
+  localeConfig: LocaleConfig | undefined
+  options: StarlightLinksValidatorOptions
+  outputDir: URL
+  pages: Pages
+}
+
+export type StarlightUserConfig = Parameters<StarlightPlugin['hooks']['setup']>['0']['config']

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "starlight-links-validator",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "license": "MIT",
-  "description": "Astro integration for Starlight to validate internal links.",
+  "description": "Starlight plugin to validate internal links.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
   "type": "module",
   "exports": {
@@ -18,19 +18,19 @@
     "unist-util-visit": "5.0.0"
   },
   "devDependencies": {
-    "@astrojs/starlight": "0.10.1",
-    "@types/hast": "3.0.1",
-    "@types/mdast": "4.0.0",
+    "@astrojs/starlight": "0.15.0",
+    "@types/hast": "3.0.3",
+    "@types/mdast": "4.0.3",
     "@types/node": "18.17.18",
-    "astro": "3.1.1",
+    "astro": "4.0.4",
     "mdast-util-mdx-jsx": "3.0.0",
     "typescript": "5.1.3",
-    "unified": "11.0.3",
-    "vitest": "0.32.2"
+    "unified": "11.0.4",
+    "vitest": "1.0.4"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.9.0",
-    "astro": ">=3.0.0"
+    "@astrojs/starlight": ">=0.15.0",
+    "astro": ">=4.0.0"
   },
   "engines": {
     "node": ">=18.14.1"
@@ -42,10 +42,10 @@
   "sideEffects": false,
   "keywords": [
     "starlight",
+    "plugin",
     "links",
     "validation",
-    "astro",
-    "astro-integration"
+    "astro"
   ],
   "homepage": "https://github.com/HiDeoo/starlight-links-validator",
   "repository": {
@@ -55,6 +55,6 @@
   "bugs": "https://github.com/HiDeoo/starlight-links-validator/issues",
   "scripts": {
     "test": "vitest",
-    "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0 && tsc --noEmit"
+    "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
   }
 }