starlight-links-validator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present, HiDeoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+<div align="center">
+  <h1>starlight-links-validator 🦺</h1>
+  <p>Astro integration for Starlight 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>
+  </p>
+</div>
+
+<div align="center">
+  <a href="https://github.com/HiDeoo/starlight-links-validator/actions/workflows/integration.yml">
+    <img alt="Integration Status" src="https://github.com/HiDeoo/starlight-links-validator/actions/workflows/integration.yml/badge.svg" />
+  </a>
+  <a href="https://github.com/HiDeoo/starlight-links-validator/blob/main/LICENSE">
+    <img alt="License" src="https://badgen.net/github/license/HiDeoo/starlight-links-validator" />
+  </a>
+  <br />
+</div>
+
+## Features
+
+An [Astro](https://astro.build) integration for [Starlight](https://starlight.astro.build) Starlight to validate **_internal_** links in Markdown and MDX files.
+
+- Validate internal links to other pages
+- Validate internal links to anchors in other pages
+- Validate internal links to anchors in the same page
+- 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.
+
+See [LICENSE](https://github.com/HiDeoo/starlight-links-validator/blob/main/LICENSE) for more information.

package/dist/index.cjs

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

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "starlight-links-validator",
+  "version": "0.1.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"
+      }
+    }
+  },
+  "dependencies": {
+    "github-slugger": "2.0.0",
+    "kleur": "4.1.5",
+    "unist-util-visit": "4.1.2"
+  },
+  "devDependencies": {
+    "@types/mdast": "3.0.11",
+    "@types/node": "18.16.18",
+    "mdast-util-mdx-jsx": "2.1.4",
+    "tsup": "7.0.0",
+    "typescript": "5.1.3",
+    "unified": "10.1.2",
+    "vitest": "0.32.2"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.0.1",
+    "astro": ">=2.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@8.6.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "starlight",
+    "links",
+    "validation",
+    "astro",
+    "astro-integration"
+  ],
+  "homepage": "https://github.com/HiDeoo/starlight-links-validator",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HiDeoo/starlight-links-validator.git"
+  },
+  "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"
+  }
+}