starlight-links-validator 0.1.1 → 0.3.0

package/index.ts

@@ -0,0 +1,32 @@
+import type { AstroIntegration } from 'astro'
+
+import { remarkStarlightLinksValidator } from './libs/remark'
+import { logErrors, validateLinks } from './libs/validation'
+
+export default function starlightLinksValidatorIntegration(): AstroIntegration {
+  return {
+    name: 'starlight-links-validator',
+    hooks: {
+      'astro:config:setup': ({ command, updateConfig }) => {
+        if (command !== 'build') {
+          return
+        }
+
+        updateConfig({
+          markdown: {
+            remarkPlugins: [remarkStarlightLinksValidator],
+          },
+        })
+      },
+      'astro:build:done': ({ dir, pages }) => {
+        const errors = validateLinks(pages, dir)
+
+        logErrors(errors)
+
+        if (errors.size > 0) {
+          throw new Error('Links validation failed.')
+        }
+      },
+    },
+  }
+}

package/libs/remark.ts

@@ -0,0 +1,149 @@
+import 'mdast-util-mdx-jsx'
+
+import nodePath from 'node:path'
+
+import { slug } from 'github-slugger'
+import type { Nodes } from 'hast'
+import { fromHtml } from 'hast-util-from-html'
+import { hasProperty } from 'hast-util-has-property'
+import type { Root } from 'mdast'
+import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from 'mdast-util-mdx-jsx'
+import { toString } from 'mdast-util-to-string'
+import type { Plugin } from 'unified'
+import { visit } from 'unist-util-visit'
+
+// 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 () {
+  return (tree, file) => {
+    const filePath = normalizeFilePath(file.history[0])
+
+    const fileHeadings: string[] = []
+    const fileLinks: string[] = []
+
+    visit(tree, ['heading', 'html', 'link', 'mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
+      // https://github.com/syntax-tree/mdast#nodes
+      // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+      switch (node.type) {
+        case 'heading': {
+          const content = toString(node)
+
+          if (content.length === 0) {
+            break
+          }
+
+          fileHeadings.push(slug(content))
+
+          break
+        }
+        case 'link': {
+          if (isInternalLink(node.url)) {
+            fileLinks.push(node.url)
+          }
+
+          break
+        }
+        case 'mdxJsxFlowElement': {
+          for (const attribute of node.attributes) {
+            if (isMdxIdAttribute(attribute)) {
+              fileHeadings.push(attribute.value)
+            }
+          }
+
+          if (node.name !== 'a') {
+            break
+          }
+
+          for (const attribute of node.attributes) {
+            if (
+              attribute.type !== 'mdxJsxAttribute' ||
+              attribute.name !== 'href' ||
+              typeof attribute.value !== 'string'
+            ) {
+              continue
+            }
+
+            if (isInternalLink(attribute.value)) {
+              fileLinks.push(attribute.value)
+            }
+          }
+
+          break
+        }
+        case 'mdxJsxTextElement': {
+          for (const attribute of node.attributes) {
+            if (isMdxIdAttribute(attribute)) {
+              fileHeadings.push(attribute.value)
+            }
+          }
+
+          break
+        }
+        case 'html': {
+          const htmlTree = fromHtml(node.value, { fragment: true })
+
+          // @ts-expect-error - https://github.com/microsoft/TypeScript/issues/51188
+          visit(htmlTree, (htmlNode: Nodes) => {
+            if (hasProperty(htmlNode, 'id') && typeof htmlNode.properties.id === 'string') {
+              fileHeadings.push(htmlNode.properties.id)
+            }
+
+            if (
+              htmlNode.type === 'element' &&
+              htmlNode.tagName === 'a' &&
+              hasProperty(htmlNode, 'href') &&
+              typeof htmlNode.properties.href === 'string' &&
+              isInternalLink(htmlNode.properties.href)
+            ) {
+              fileLinks.push(htmlNode.properties.href)
+            }
+          })
+
+          break
+        }
+      }
+    })
+
+    headings.set(filePath, fileHeadings)
+    links.set(filePath, fileLinks)
+  }
+}
+
+export function getValidationData() {
+  return { headings, links }
+}
+
+function isInternalLink(link: string) {
+  return nodePath.isAbsolute(link) || link.startsWith('#')
+}
+
+function normalizeFilePath(filePath?: string) {
+  if (!filePath) {
+    throw new Error('Missing file path to validate links.')
+  }
+
+  return nodePath
+    .relative(nodePath.join(process.cwd(), 'src/content/docs'), filePath)
+    .replace(/\.\w+$/, '')
+    .replace(/index$/, '')
+    .replace(/\/?$/, '/')
+    .split('/')
+    .map((segment) => slug(segment))
+    .join('/')
+}
+
+function isMdxIdAttribute(attribute: MdxJsxAttribute | MdxJsxExpressionAttribute): attribute is MdxIdAttribute {
+  return attribute.type === 'mdxJsxAttribute' && attribute.name === 'id' && typeof attribute.value === 'string'
+}
+
+export type Headings = Map<string, string[]>
+export type Links = Map<string, string[]>
+
+interface MdxIdAttribute {
+  name: 'id'
+  type: 'mdxJsxAttribute'
+  value: string
+}

package/libs/validation.ts

@@ -0,0 +1,152 @@
+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[], outputDir: URL): ValidationErrors {
+  process.stdout.write(`\n${bgGreen(black(` validating links `))}\n`)
+
+  const { headings, links } = getValidationData()
+  const allPages: Pages = new Set(pages.map((page) => page.pathname))
+
+  const errors: ValidationErrors = new Map()
+
+  for (const [filePath, fileLinks] of links) {
+    for (const link of fileLinks) {
+      if (link.startsWith('#')) {
+        validateSelfAnchor(errors, link, filePath, headings)
+      } else {
+        validateLink(errors, link, filePath, headings, allPages, outputDir)
+      }
+    }
+  }
+
+  return errors
+}
+
+export function logErrors(errors: ValidationErrors) {
+  if (errors.size === 0) {
+    process.stdout.write(dim('All internal links are valid.\n\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`
+  )
+
+  for (const [file, links] of errors) {
+    process.stderr.write(`${red('▶')} ${file}\n`)
+
+    for (const [index, link] of links.entries()) {
+      process.stderr.write(`  ${cyan(`${index < links.length - 1 ? '├' : '└'}─`)} ${link}\n`)
+    }
+
+    process.stdout.write(dim('\n'))
+  }
+
+  process.stdout.write(dim('\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
+) {
+  const sanitizedLink = link.replace(/^\//, '')
+  const segments = sanitizedLink.split('#')
+
+  let path = segments[0]
+  const hash = segments[1]
+
+  if (path === undefined) {
+    throw new Error('Failed to validate a link with no path.')
+  }
+
+  if (isValidAsset(path, outputDir)) {
+    return
+  }
+
+  if (path.length > 0 && !path.endsWith('/')) {
+    path += '/'
+  }
+
+  const isValidPage = pages.has(path)
+  const fileHeadings = headings.get(path === '' ? '/' : path)
+
+  if (!isValidPage || !fileHeadings) {
+    addError(errors, filePath, link)
+    return
+  }
+
+  if (hash && !fileHeadings.includes(hash)) {
+    addError(errors, filePath, link)
+  }
+}
+
+/**
+ * Validate a link to an anchor in the same page.
+ */
+function validateSelfAnchor(errors: ValidationErrors, hash: string, filePath: string, headings: Headings) {
+  const sanitizedHash = hash.replace(/^#/, '')
+  const fileHeadings = headings.get(filePath)
+
+  if (!fileHeadings) {
+    throw new Error(`Failed to find headings for the file at '${filePath}'.`)
+  }
+
+  if (!fileHeadings.includes(sanitizedHash)) {
+    addError(errors, filePath, hash)
+  }
+}
+
+/**
+ * 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)
+
+  errors.set(filePath, fileErrors)
+}
+
+function pluralize(count: number, singular: string) {
+  return count === 1 ? singular : `${singular}s`
+}
+
+// The invalid links keyed by file path.
+type ValidationErrors = Map<string, string[]>
+
+interface PageData {
+  pathname: string
+}
+
+type Pages = Set<PageData['pathname']>

package/package.json

@@ -1,37 +1,28 @@
 {
   "name": "starlight-links-validator",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "Astro integration for Starlight to validate internal links.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
   "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
   "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "default": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
+    ".": "./index.ts",
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "github-slugger": "2.0.0",
+    "hast-util-from-html": "2.0.1",
+    "hast-util-has-property": "3.0.0",
     "kleur": "4.1.5",
     "mdast-util-to-string": "3.2.0",
     "unist-util-visit": "4.1.2"
   },
   "devDependencies": {
+    "@types/hast": "3.0.0",
     "@types/mdast": "3.0.11",
     "@types/node": "18.16.18",
+    "astro": "2.10.9",
     "mdast-util-mdx-jsx": "2.1.4",
-    "tsup": "7.0.0",
     "typescript": "5.1.3",
     "unified": "10.1.2",
     "vitest": "0.32.2"
@@ -48,9 +39,6 @@
     "access": "public"
   },
   "sideEffects": false,
-  "files": [
-    "dist"
-  ],
   "keywords": [
     "starlight",
     "links",
@@ -65,8 +53,6 @@
   },
   "bugs": "https://github.com/HiDeoo/starlight-links-validator/issues",
   "scripts": {
-    "dev": "tsup --watch",
-    "build": "tsup && cp dist/index.d.ts dist/index.d.cts",
     "test": "vitest",
     "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0 && tsc --noEmit"
   }

package/dist/index.cjs

@@ -1,11 +0,0 @@
-"use strict";var z=Object.create;var d=Object.defineProperty;var H=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var A=Object.getPrototypeOf,F=Object.prototype.hasOwnProperty;var S=(t,i)=>{for(var n in i)d(t,n,{get:i[n],enumerable:!0})},u=(t,i,n,r)=>{if(i&&typeof i=="object"||typeof i=="function")for(let e of M(i))!F.call(t,e)&&e!==n&&d(t,e,{get:()=>i[e],enumerable:!(r=H(i,e))||r.enumerable});return t};var D=(t,i,n)=>(n=t!=null?z(A(t)):{},u(i||!t||!t.__esModule?d(n,"default",{value:t,enumerable:!0}):n,t)),I=t=>u(d({},"__esModule",{value:!0}),t);var j={};S(j,{default:()=>V});module.exports=I(j);var G=require("mdast-util-mdx-jsx"),c=D(require("path"),1),h=require("github-slugger"),k=require("mdast-util-to-string"),w=require("unist-util-visit"),v=new Map,E=new Map,$=function(){return(t,i)=>{let n=J(i.history[0]),r=[],e=[];(0,w.visit)(t,["heading","link","mdxJsxFlowElement"],s=>{switch(s.type){case"heading":{let a=(0,k.toString)(s);if(a.length===0)break;r.push((0,h.slug)(a));break}case"link":{m(s.url)&&e.push(s.url);break}case"mdxJsxFlowElement":{if(s.name!=="a")break;for(let a of s.attributes)a.type!=="mdxJsxAttribute"||a.name!=="href"||typeof a.value!="string"||m(a.value)&&e.push(a.value);break}}}),v.set(n,r),E.set(n,e)}};function b(){return{headings:v,links:E}}function m(t){return c.default.isAbsolute(t)||t.startsWith("#")}function J(t){if(!t)throw new Error("Missing file path to validate links.");return c.default.relative(c.default.join(process.cwd(),"src/content/docs"),t).replace(/\.\w+$/,"").replace(/index$/,"").replace(/\/?$/,"/")}var o=require("kleur/colors");function L(t){process.stdout.write(`
-${(0,o.bgGreen)((0,o.black)(" validating links "))}
-`);let{headings:i,links:n}=b(),r=new Set(t.map(s=>s.pathname)),e=new Map;for(let[s,a]of n)for(let l of a)l.startsWith("#")?R(e,l,s,i):W(e,l,s,i,r);return e}function y(t){if(t.size===0){process.stdout.write((0,o.dim)(`All internal links are valid.
-
-`));return}let i=[...t.values()].reduce((n,r)=>n+r.length,0);process.stderr.write(`${(0,o.bold)((0,o.red)(`Found ${i} invalid ${x(i,"link")} in ${t.size} ${x(t.size,"file")}.`))}
-
-`);for(let[n,r]of t){process.stderr.write(`${(0,o.red)("\u25B6")} ${n}
-`);for(let[e,s]of r.entries())process.stderr.write(`  ${(0,o.cyan)(`${e<r.length-1?"\u251C":"\u2514"}\u2500`)} ${s}
-`);process.stdout.write((0,o.dim)(`
-`))}process.stdout.write((0,o.dim)(`
-`))}function W(t,i,n,r,e){let a=i.replace(/^\//,"").split("#"),l=a[0],f=a[1];if(l===void 0)throw new Error("Failed to validate a link with no path.");l.length>0&&!l.endsWith("/")&&(l+="/");let P=e.has(l),p=r.get(l===""?"/":l);if(!P||!p){g(t,n,i);return}f&&!p.includes(f)&&g(t,n,i)}function R(t,i,n,r){let e=i.replace(/^#/,""),s=r.get(n);if(!s)throw new Error(`Failed to find headings for the file at '${n}'.`);s.includes(e)||g(t,n,i)}function g(t,i,n){let r=t.get(i)??[];r.push(n),t.set(i,r)}function x(t,i){return t===1?i:`${i}s`}function V(){return{name:"starlight-links-validator",hooks:{"astro:config:setup":({command:t,updateConfig:i})=>{t==="build"&&i({markdown:{remarkPlugins:[$]}})},"astro:build:done":({pages:t})=>{let i=L(t);if(y(i),i.size>0)throw new Error("Links validation failed.")}}}}

package/dist/index.d.cts

@@ -1,5 +0,0 @@
-import { AstroIntegration } from 'astro';
-
-declare function starlightLinksValidatorIntegration(): AstroIntegration;
-
-export { starlightLinksValidatorIntegration as default };

package/dist/index.d.ts

@@ -1,5 +0,0 @@
-import { AstroIntegration } from 'astro';
-
-declare function starlightLinksValidatorIntegration(): AstroIntegration;
-
-export { starlightLinksValidatorIntegration as default };

package/dist/index.js

@@ -1,11 +0,0 @@
-import"mdast-util-mdx-jsx";import l from"node:path";import{slug as x}from"github-slugger";import{toString as L}from"mdast-util-to-string";import{visit as y}from"unist-util-visit";var u=new Map,m=new Map,h=function(){return(t,i)=>{let n=V(i.history[0]),e=[],s=[];y(t,["heading","link","mdxJsxFlowElement"],r=>{switch(r.type){case"heading":{let o=L(r);if(o.length===0)break;e.push(x(o));break}case"link":{p(r.url)&&s.push(r.url);break}case"mdxJsxFlowElement":{if(r.name!=="a")break;for(let o of r.attributes)o.type!=="mdxJsxAttribute"||o.name!=="href"||typeof o.value!="string"||p(o.value)&&s.push(o.value);break}}}),u.set(n,e),m.set(n,s)}};function k(){return{headings:u,links:m}}function p(t){return l.isAbsolute(t)||t.startsWith("#")}function V(t){if(!t)throw new Error("Missing file path to validate links.");return l.relative(l.join(process.cwd(),"src/content/docs"),t).replace(/\.\w+$/,"").replace(/index$/,"").replace(/\/?$/,"/")}import{bgGreen as P,black as z,bold as H,cyan as M,dim as d,red as w}from"kleur/colors";function E(t){process.stdout.write(`
-${P(z(" validating links "))}
-`);let{headings:i,links:n}=k(),e=new Set(t.map(r=>r.pathname)),s=new Map;for(let[r,o]of n)for(let a of o)a.startsWith("#")?F(s,a,r,i):A(s,a,r,i,e);return s}function $(t){if(t.size===0){process.stdout.write(d(`All internal links are valid.
-
-`));return}let i=[...t.values()].reduce((n,e)=>n+e.length,0);process.stderr.write(`${H(w(`Found ${i} invalid ${v(i,"link")} in ${t.size} ${v(t.size,"file")}.`))}
-
-`);for(let[n,e]of t){process.stderr.write(`${w("\u25B6")} ${n}
-`);for(let[s,r]of e.entries())process.stderr.write(`  ${M(`${s<e.length-1?"\u251C":"\u2514"}\u2500`)} ${r}
-`);process.stdout.write(d(`
-`))}process.stdout.write(d(`
-`))}function A(t,i,n,e,s){let o=i.replace(/^\//,"").split("#"),a=o[0],g=o[1];if(a===void 0)throw new Error("Failed to validate a link with no path.");a.length>0&&!a.endsWith("/")&&(a+="/");let b=s.has(a),f=e.get(a===""?"/":a);if(!b||!f){c(t,n,i);return}g&&!f.includes(g)&&c(t,n,i)}function F(t,i,n,e){let s=i.replace(/^#/,""),r=e.get(n);if(!r)throw new Error(`Failed to find headings for the file at '${n}'.`);r.includes(s)||c(t,n,i)}function c(t,i,n){let e=t.get(i)??[];e.push(n),t.set(i,e)}function v(t,i){return t===1?i:`${i}s`}function S(){return{name:"starlight-links-validator",hooks:{"astro:config:setup":({command:t,updateConfig:i})=>{t==="build"&&i({markdown:{remarkPlugins:[h]}})},"astro:build:done":({pages:t})=>{let i=E(t);if($(i),i.size>0)throw new Error("Links validation failed.")}}}}export{S as default};