starlight-links-validator 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # starlight-links-validator
 
+## 0.14.2
+
+### Patch Changes
+
+- [#85](https://github.com/HiDeoo/starlight-links-validator/pull/85) [`57fdb1b`](https://github.com/HiDeoo/starlight-links-validator/commit/57fdb1b2f85f023e4b053480fd9ea5adb69a9e2a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Improves error message for invalid links to custom pages.
+
+## 0.14.1
+
+### Patch Changes
+
+- [#82](https://github.com/HiDeoo/starlight-links-validator/pull/82) [`b3cbee8`](https://github.com/HiDeoo/starlight-links-validator/commit/b3cbee83fb54f5bd6dd06b01bb8397758c081752) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes regresion introduced in version [`0.14.0`](https://github.com/HiDeoo/starlight-links-validator/releases/tag/starlight-links-validator%400.14.0) of the plugin regarding validation of links to pages with [custom IDs/slugs](https://docs.astro.build/en/guides/content-collections/#defining-custom-ids).
+
+  Note that you must use at least Astro version [`5.1.1`](https://github.com/withastro/astro/releases/tag/astro%405.1.1) to benefit from this fix.
+
+- [#80](https://github.com/HiDeoo/starlight-links-validator/pull/80) [`876cb50`](https://github.com/HiDeoo/starlight-links-validator/commit/876cb5094d10a56a1be04b7cdc27e4f89fb1b681) Thanks [@lukekarrys](https://github.com/lukekarrys)! - Fixes validation issues for pages ending in `index`, e.g. `module_index`.
+
 ## 0.14.0
 
 ### Minor Changes

package/index.ts

@@ -1,8 +1,10 @@
 import type { StarlightPlugin } from '@astrojs/starlight/types'
+import type { IntegrationResolvedRoute } from 'astro'
 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 { logErrors, validateLinks } from './libs/validation'
 
@@ -72,6 +74,8 @@ export default function starlightLinksValidatorPlugin(
     name: 'starlight-links-validator-plugin',
     hooks: {
       setup({ addIntegration, astroConfig, config: starlightConfig, logger }) {
+        let routes: IntegrationResolvedRoute[] = []
+
         addIntegration({
           name: 'starlight-links-validator-integration',
           hooks: {
@@ -90,13 +94,32 @@ export default function starlightLinksValidatorPlugin(
                 },
               })
             },
-            'astro:build:done': ({ dir, pages }) => {
-              const errors = validateLinks(pages, dir, astroConfig, starlightConfig, options.data)
+            'astro:routes:resolved': (params) => {
+              routes = params.routes
+            },
+            'astro:build:done': ({ dir, pages, assets }) => {
+              const customPages = new Set<string>()
 
-              logErrors(logger, errors)
+              for (const [pattern, urls] of assets) {
+                const route = routes.find((route) => route.pattern === pattern)
+                if (!route || route.origin !== 'project') continue
+
+                for (const url of urls) {
+                  customPages.add(pathnameToSlug(url.pathname.replace(astroConfig.outDir.pathname, '')))
+                }
+              }
+
+              const errors = validateLinks(pages, customPages, dir, astroConfig, starlightConfig, options.data)
+
+              const hasInvalidLinkToCustomPage = logErrors(logger, errors)
 
               if (errors.size > 0) {
-                throwPluginError('Links validation failed.')
+                throwPluginError(
+                  'Links validation failed.',
+                  hasInvalidLinkToCustomPage
+                    ? 'Some invalid links point to custom pages which cannot be validated, see the `exclude` option for more informations at https://starlight-links-validator.vercel.app/configuration#exclude'
+                    : undefined,
+                )
               }
             },
           },
@@ -106,11 +129,13 @@ export default function starlightLinksValidatorPlugin(
   }
 }
 
-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`,
-  )
+function throwPluginError(message: string, additionalHint?: string): never {
+  let hint = 'See the error report above for more informations.\n\n'
+  if (additionalHint) hint += `${additionalHint}\n\n`
+  hint +=
+    'If you believe this is a bug, please file an issue at https://github.com/HiDeoo/starlight-links-validator/issues/new/choose'
+
+  throw new AstroError(message, hint)
 }
 
 type StarlightLinksValidatorUserOptions = z.input<typeof starlightLinksValidatorOptionsSchema>

package/libs/path.ts

@@ -1,3 +1,5 @@
+const htmlExtension = '.html'
+
 export function ensureLeadingSlash(path: string): string {
   return path.startsWith('/') ? path : `/${path}`
 }
@@ -9,3 +11,28 @@ export function ensureTrailingSlash(path: string): string {
 export function stripLeadingSlash(path: string) {
   return path.replace(/^\//, '')
 }
+
+export function stripTrailingSlash(path: string) {
+  return path.replace(/\/$/, '')
+}
+
+export function pathnameToSlug(pathname: string): string {
+  const base = stripTrailingSlash(import.meta.env.BASE_URL)
+
+  if (pathname.startsWith(base)) {
+    pathname = pathname.replace(base, '')
+  }
+
+  const segments = pathname.split('/')
+
+  if (segments.at(-1) === 'index.html') {
+    segments.pop()
+  } else if (segments.at(-1)?.endsWith(htmlExtension)) {
+    const last = segments.pop()
+    if (last) {
+      segments.push(last.slice(0, -1 * htmlExtension.length))
+    }
+  }
+
+  return segments.filter(Boolean).join('/')
+}

package/libs/remark.ts

@@ -178,7 +178,7 @@ function normalizeFilePath(base: string, srcDir: URL, filePath?: string) {
   const path = nodePath
     .relative(nodePath.join(fileURLToPath(srcDir), 'content/docs'), filePath)
     .replace(/\.\w+$/, '')
-    .replace(/index$/, '')
+    .replace(/(^|[/\\])index$/, '')
     .replace(/[/\\]?$/, '/')
     .split(/[/\\]/)
     .map((segment) => slug(segment))

package/libs/validation.ts

@@ -10,13 +10,14 @@ import picomatch from 'picomatch'
 import type { StarlightLinksValidatorOptions } from '..'
 
 import { getFallbackHeadings, getLocaleConfig, isInconsistentLocaleLink, type LocaleConfig } from './i18n'
-import { ensureTrailingSlash, stripLeadingSlash } from './path'
+import { ensureTrailingSlash, stripLeadingSlash, stripTrailingSlash } from './path'
 import { getValidationData, type Headings } from './remark'
 
 export const ValidationErrorType = {
   InconsistentLocale: 'inconsistent locale',
   InvalidHash: 'invalid hash',
   InvalidLink: 'invalid link',
+  InvalidLinkToCustomPage: 'invalid link to custom page',
   LocalLink: 'local link',
   RelativeLink: 'relative link',
   TrailingSlashMissing: 'missing trailing slash',
@@ -25,6 +26,7 @@ export const ValidationErrorType = {
 
 export function validateLinks(
   pages: PageData[],
+  customPages: Set<string>,
   outputDir: URL,
   astroConfig: AstroConfig,
   starlightConfig: StarlightUserConfig,
@@ -50,6 +52,7 @@ export function validateLinks(
     for (const link of fileLinks) {
       const validationContext: ValidationContext = {
         astroConfig,
+        customPages,
         errors,
         filePath,
         headings,
@@ -92,6 +95,8 @@ export function logErrors(pluginLogger: AstroIntegrationLogger, errors: Validati
     ),
   )
 
+  let hasInvalidLinkToCustomPage = false
+
   for (const [file, validationErrors] of errors) {
     logger.info(`${red('▶')} ${blue(file)}`)
 
@@ -101,17 +106,20 @@ export function logErrors(pluginLogger: AstroIntegrationLogger, errors: Validati
           ` - ${validationError.type}`,
         )}`,
       )
+      hasInvalidLinkToCustomPage = validationError.type === ValidationErrorType.InvalidLinkToCustomPage
     }
   }
 
   process.stdout.write('\n')
+
+  return hasInvalidLinkToCustomPage
 }
 
 /**
  * Validate a link to another internal page that may or may not have a hash.
  */
 function validateLink(context: ValidationContext) {
-  const { astroConfig, errors, filePath, link, localeConfig, options, pages } = context
+  const { astroConfig, customPages, errors, filePath, link, localeConfig, options, pages } = context
 
   if (isExcludedLink(link, context)) {
     return
@@ -153,7 +161,14 @@ function validateLink(context: ValidationContext) {
   const fileHeadings = getFileHeadings(sanitizedPath, context)
 
   if (!isValidPage || !fileHeadings) {
-    addError(errors, filePath, link, ValidationErrorType.InvalidLink)
+    addError(
+      errors,
+      filePath,
+      link,
+      customPages.has(stripTrailingSlash(sanitizedPath))
+        ? ValidationErrorType.InvalidLinkToCustomPage
+        : ValidationErrorType.InvalidLink,
+    )
     return
   }
 
@@ -271,6 +286,7 @@ type Pages = Set<PageData['pathname']>
 
 interface ValidationContext {
   astroConfig: AstroConfig
+  customPages: Set<string>
   errors: ValidationErrors
   filePath: string
   headings: Headings

package/package.json

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