validate-mdx-links 1.0.0

package/dist/bin.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * @file This script validates the internal links in the MDX files.
+ * Note that it does not validate external links (e.g. to GitHub).
+ *
+ * Usage:
+ * validate-mdx-links --cwd <path> --files "content/**\/*.mdx" --verbose
+ */
+import { parseArgs } from "node:util";
+import { validateMdxLinks, printErrors } from "./index.js";
+const args = parseArgs({
+    options: {
+        cwd: { type: "string", default: process.cwd() },
+        files: { type: "string" },
+        verbose: { type: "boolean", default: false },
+        help: { type: "boolean", default: false },
+    },
+    strict: true,
+});
+if (args.values.help) {
+    console.log('Usage: validate-mdx-links --cwd <path> --files "content/**/*.mdx" --verbose');
+    process.exit(0);
+}
+if (!args.values.files) {
+    console.error("No files passed. Please pass the --files option.");
+    process.exit(1);
+}
+try {
+    const errors = await validateMdxLinks({
+        cwd: args.values.cwd,
+        files: args.values.files,
+    });
+    if (errors.length > 0) {
+        printErrors(errors);
+        process.exit(1);
+    }
+    console.log("No broken links found!");
+    process.exit(0);
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+}

package/dist/index.js

@@ -0,0 +1,56 @@
+import { globSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { scanURLs, validateFiles, } from "next-validate-link";
+export { printErrors } from "next-validate-link";
+export async function validateMdxLinks({ cwd = process.cwd(), files: filesGlob, verbose = false, }) {
+    const originalCwd = process.cwd();
+    process.chdir(cwd);
+    const files = globSync(filesGlob);
+    if (files.length === 0) {
+        process.chdir(originalCwd);
+        throw new Error("No files found matching the glob pattern");
+    }
+    else if (verbose) {
+        console.log(`Found ${files.length} markdown files to validate.\n`);
+    }
+    const scanned = await scanURLs();
+    console.log("\n" +
+        "Scanned routes from the file system:\n" +
+        [...scanned.urls.keys(), ...scanned.fallbackUrls.map((x) => x.url)]
+            .map((x) => `"${x}"`)
+            .join(", ") +
+        "\n");
+    const validations = await validateFiles(files, { scanned });
+    const withoutFalsePositives = await Promise.all(validations.map(async ({ file, detected }) => {
+        const filteredDetected = [];
+        for (const error of detected) {
+            let link = error[0];
+            if (link.startsWith("./") || link.startsWith("../")) {
+                // If there is a hash #id, we don't parse the file to find the heading,
+                // just assume it exists and check if the file exists.
+                link = link.split("#")[0] || "";
+                // relative links inside of JSX lose the .mdx extension
+                if (!link.endsWith(".mdx")) {
+                    link = `${link}.mdx`;
+                }
+                const path = resolve(dirname(file), link);
+                const stats = await stat(path).catch(() => false);
+                if (stats) {
+                    // file exists, the error is a false positive
+                    continue;
+                }
+            }
+            filteredDetected.push(error);
+        }
+        if (filteredDetected.length === 0) {
+            return null;
+        }
+        return {
+            file,
+            detected: filteredDetected,
+        };
+    }));
+    process.chdir(originalCwd);
+    return withoutFalsePositives.filter((validation) => validation !== null);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "validate-mdx-links",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "validate-mdx-links": "./dist/bin.js"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "author": {
+    "name": "Piotr Monwid-Olechnowicz",
+    "email": "hasparus@gmail.com",
+    "url": "https://haspar.us"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "next-validate-link": "^1.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/bin.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+/**
+ * @file This script validates the internal links in the MDX files.
+ * Note that it does not validate external links (e.g. to GitHub).
+ *
+ * Usage:
+ * validate-mdx-links --cwd <path> --files "content/**\/*.mdx" --verbose
+ */
+import { parseArgs } from "node:util";
+import { validateMdxLinks, printErrors } from "./index.js";
+
+const args = parseArgs({
+  options: {
+    cwd: { type: "string", default: process.cwd() },
+    files: { type: "string" },
+    verbose: { type: "boolean", default: false },
+    help: { type: "boolean", default: false },
+  },
+  strict: true,
+});
+
+if (args.values.help) {
+  console.log(
+    'Usage: validate-mdx-links --cwd <path> --files "content/**/*.mdx" --verbose'
+  );
+  process.exit(0);
+}
+
+if (!args.values.files) {
+  console.error("No files passed. Please pass the --files option.");
+  process.exit(1);
+}
+
+try {
+  const errors = await validateMdxLinks({
+    cwd: args.values.cwd,
+    files: args.values.files,
+  });
+
+  if (errors.length > 0) {
+    printErrors(errors);
+    process.exit(1);
+  }
+
+  console.log("No broken links found!");
+  process.exit(0);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+import { globSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import {
+  scanURLs,
+  validateFiles,
+  type DetectedError,
+} from "next-validate-link";
+
+export { printErrors } from "next-validate-link";
+
+export type ValidationResult = {
+  file: string;
+  detected: DetectedError[];
+};
+
+export interface ValidateMdxLinksOptions {
+  cwd?: string;
+  files: string;
+  verbose?: boolean;
+}
+
+export async function validateMdxLinks({
+  cwd = process.cwd(),
+  files: filesGlob,
+  verbose = false,
+}: ValidateMdxLinksOptions): Promise<ValidationResult[]> {
+  const originalCwd = process.cwd();
+  process.chdir(cwd);
+
+  const files = globSync(filesGlob);
+  if (files.length === 0) {
+    process.chdir(originalCwd);
+    throw new Error("No files found matching the glob pattern");
+  } else if (verbose) {
+    console.log(`Found ${files.length} markdown files to validate.\n`);
+  }
+
+  const scanned = await scanURLs();
+
+  console.log(
+    "\n" +
+      "Scanned routes from the file system:\n" +
+      [...scanned.urls.keys(), ...scanned.fallbackUrls.map((x) => x.url)]
+        .map((x) => `"${x}"`)
+        .join(", ") +
+      "\n"
+  );
+
+  const validations = await validateFiles(files, { scanned });
+
+  const withoutFalsePositives = await Promise.all(
+    validations.map(async ({ file, detected }) => {
+      const filteredDetected: DetectedError[] = [];
+
+      for (const error of detected) {
+        let link = error[0];
+
+        if (link.startsWith("./") || link.startsWith("../")) {
+          // If there is a hash #id, we don't parse the file to find the heading,
+          // just assume it exists and check if the file exists.
+          link = link.split("#")[0] || "";
+
+          // relative links inside of JSX lose the .mdx extension
+          if (!link.endsWith(".mdx")) {
+            link = `${link}.mdx`;
+          }
+
+          const path = resolve(dirname(file), link);
+          const stats = await stat(path).catch(() => false);
+
+          if (stats) {
+            // file exists, the error is a false positive
+            continue;
+          }
+        }
+
+        filteredDetected.push(error);
+      }
+
+      if (filteredDetected.length === 0) {
+        return null;
+      }
+
+      return {
+        file,
+        detected: filteredDetected,
+      };
+    })
+  );
+
+  process.chdir(originalCwd);
+
+  return withoutFalsePositives.filter(
+    (validation): validation is NonNullable<typeof validation> =>
+      validation !== null
+  );
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "outDir": "./dist"
+  }
+}