@mintlify/link-rot 3.0.0 → 3.0.2

package/.eslintignore

@@ -0,0 +1 @@
+dist/

package/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@mintlify/eslint-config-typescript"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/link-rot",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Static checking for broken internal links",
   "engines": {
     "node": ">=18.0.0"
@@ -26,11 +26,12 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "exports": {
+    ".": {
+      "static-checking": "./dist/static-checking",
+      "link-renaming": "./dist/link-renaming"
+    }
+  },
   "scripts": {
     "prepare": "npm run build",
     "build": "tsc",

package/src/link-renaming/index.ts

@@ -0,0 +1,3 @@
+import { renameFileAndUpdateLinksInContent } from "./renameFileAndUpdateLinksInContent.js";
+
+export default renameFileAndUpdateLinksInContent;

package/src/link-renaming/renameFileAndUpdateLinksInContent.ts

@@ -0,0 +1,62 @@
+import { existsSync, lstatSync, renameSync } from "fs";
+import { normalize, parse, ParsedPath } from "path";
+import renameInternalLinksInPage from "./renameInternalLinksInPage.js";
+import { isValidPage, removeFileExtension, getPagePaths } from "../prebuild.js";
+
+/**
+ * Renames a link in the file system. If the link is a directory, all links within the directory will be renamed as well.
+ * @param existingDir - The existing directory or file to rename
+ * @param newDirName - The new directory or file name
+ * @param force
+ */
+export const renameFileAndUpdateLinksInContent = async (
+  existingDir: string,
+  newDirName: string,
+  force = false
+) => {
+  existingDir = normalize(existingDir);
+  newDirName = normalize(newDirName);
+  const existingDirParsed: ParsedPath = parse(existingDir);
+  const newDirParsed: ParsedPath = parse(newDirName);
+  if (!existsSync(existingDir)) {
+    throw new Error("File or folder does not exist at " + existingDir);
+  }
+  if (!force && existsSync(newDirName)) {
+    throw new Error(
+      "File or folder exists at " + newDirName + ". Use --force to overwrite."
+    );
+  }
+
+  const isDirectory = lstatSync(existingDir).isDirectory();
+  if (!isDirectory) {
+    if (!isValidPage(existingDirParsed)) {
+      throw new Error("File to rename must be an MDX or Markdown file.");
+    }
+    if (!isValidPage(newDirParsed)) {
+      throw new Error("New file name must be an MDX or Markdown file.");
+    }
+  }
+  renameSync(existingDir, newDirName);
+  console.log(`Renamed ${existingDir} to ${newDirName}.`);
+
+  const existingLink = removeFileExtension(existingDirParsed);
+  const newLink = removeFileExtension(newDirParsed);
+  const pagesInDirectory = getPagePaths(process.cwd());
+  const renameLinkPromises: Promise<void>[] = [];
+  pagesInDirectory.forEach((filePath: string) => {
+    renameLinkPromises.push(
+      (async () => {
+        const numRenamedLinks = await renameInternalLinksInPage(
+          filePath,
+          existingLink,
+          newLink
+        );
+        if (numRenamedLinks > 0) {
+          console.log(`Renamed ${numRenamedLinks} link(s) in ${filePath}`);
+        }
+      })()
+    );
+  });
+  await Promise.all(renameLinkPromises);
+  return;
+};

package/src/link-renaming/renameInternalLinksInPage.ts

@@ -0,0 +1,69 @@
+/**
+ * @typedef {import('remark-mdx')}
+ */
+import fs from "fs-extra";
+import type { Root } from "mdast";
+import { normalize } from "path";
+import { remark } from "remark";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import { visit } from "unist-util-visit";
+
+/**
+ * Go through fileContent and replace all links that match existingLink with
+ * newLink
+ */
+const getContentWithRenamedInternalLinks = async (
+  fileContent: string,
+  existingLink: string,
+  newLink: string
+) => {
+  let numRenamedLinks = 0;
+  const remarkMdxReplaceLinks = () => {
+    return (tree: Root) => {
+      visit(tree, (node) => {
+        // ![]() format
+        if (
+          node.type === "link" &&
+          node.url &&
+          normalize(node.url) === existingLink
+        ) {
+          node.url = newLink;
+          numRenamedLinks++;
+        }
+        return;
+      });
+    };
+  };
+  const file = await remark()
+    .use(remarkMdx)
+    .use(remarkGfm)
+    .use(remarkFrontmatter, ["yaml", "toml"])
+    .use(remarkMdxReplaceLinks)
+    .process(fileContent);
+  return {
+    numRenamedLinks,
+    newContent: String(file),
+  };
+};
+
+const renameInternalLinksInPage = async (
+  filePath: string,
+  existingLink: string,
+  newLink: string
+): Promise<number> => {
+  const fileContent = fs.readFileSync(filePath).toString();
+  const { numRenamedLinks, newContent } =
+    await getContentWithRenamedInternalLinks(
+      fileContent,
+      existingLink,
+      newLink
+    );
+  fs.outputFileSync(filePath, newContent, {
+    flag: "w",
+  });
+  return numRenamedLinks;
+};
+
+export default renameInternalLinksInPage;

package/src/prebuild.ts

@@ -0,0 +1,64 @@
+import path, { ParsedPath } from "path";
+import { getFileList } from "@mintlify/prebuild";
+
+// TODO refactor to prebuild package
+const NODE_MODULES_DIRECTORY = "/node_modules";
+const SUPPORTED_PAGE_EXTENSIONS = [".mdx", ".md"];
+const SUPPORTED_MEDIA_EXTENSIONS = [
+  "jpeg",
+  "jpg",
+  "jfif",
+  "pjpeg",
+  "pjp",
+  "png",
+  "svg",
+  "svgz",
+  "ico",
+  "webp",
+  "gif",
+  "apng",
+  "avif",
+  "bmp",
+  "mp4",
+];
+
+export const isNotNodeModule = (filePath: ParsedPath) =>
+  !filePath.dir.startsWith(NODE_MODULES_DIRECTORY);
+
+export const isValidPage = (filePath: ParsedPath) =>
+  SUPPORTED_PAGE_EXTENSIONS.includes(filePath.ext);
+
+export const isValidMedia = (filePath: ParsedPath) =>
+  SUPPORTED_MEDIA_EXTENSIONS.includes(filePath.ext);
+
+export const isValidLink = (filePath: ParsedPath) =>
+  isValidPage(filePath) || isValidMedia(filePath);
+
+export const normalizeFilePaths = (fileList: string[]) =>
+  fileList.map(path.normalize).map(path.parse);
+
+export const filterNodeModules = (fileList: string[]) =>
+  normalizeFilePaths(fileList).filter(isNotNodeModule);
+
+export const filterPages = (fileList: string[]) =>
+  filterNodeModules(fileList).filter(isValidPage);
+
+export const filterMedia = (fileList: string[]) =>
+  filterNodeModules(fileList).filter(isValidMedia);
+
+export const filterLinks = (fileList: string[]) =>
+  filterNodeModules(fileList).filter(isValidLink);
+
+export const getFullPath = (filePath: ParsedPath) =>
+  path.join(filePath.dir, filePath.name + filePath.ext);
+
+export const removeFileExtension = (filePath: ParsedPath) =>
+  path.join(filePath.dir, filePath.name);
+
+export const removeLeadingSlash = (filePathString: string) => {
+  const hasLeadingSlash = filePathString.startsWith("/");
+  return hasLeadingSlash ? filePathString.slice(1) : filePathString;
+};
+
+export const getPagePaths = (dirName: string) =>
+  filterPages(getFileList(dirName)).map(getFullPath).map(removeLeadingSlash);

package/src/static-checking/crawlPages.ts

@@ -0,0 +1 @@
+export {};

package/src/static-checking/getBrokenInternalLinks.ts

@@ -0,0 +1,19 @@
+import { getValidInternalLinks } from "./getValidInternalLinks.js";
+import { getUsedInternalLinksInSite } from "./getUsedInternalLinks.js";
+import Chalk from "chalk";
+
+export const getBrokenInternalLinks = async (dirName: string, print = true) => {
+  const usedLinksPerFile = await getUsedInternalLinksInSite(dirName);
+  const validLinks = getValidInternalLinks(dirName);
+  const allBrokenLinks: string[] = [];
+  Object.entries(usedLinksPerFile).forEach(([fileName, usedLinks]) => {
+    const brokenLinks = usedLinks.filter((link) => !validLinks.has(link));
+    if (brokenLinks.length === 0) return;
+    allBrokenLinks.push(...brokenLinks);
+    if (!print) return;
+    console.group(`${Chalk.yellow(`Broken links in ${fileName}`)}:`);
+    console.log(brokenLinks.join("\n"));
+    console.groupEnd();
+  });
+  return allBrokenLinks;
+};

package/src/static-checking/getUsedInternalLinks.ts

@@ -0,0 +1,96 @@
+import isAbsoluteUrl from "is-absolute-url";
+import fs from "fs-extra";
+import type { Root } from "mdast";
+import type { MdxJsxFlowElement } from "mdast-util-mdx-jsx";
+import { remark } from "remark";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import { visit } from "unist-util-visit";
+import {
+  getFullPath,
+  getPagePaths,
+  normalizeFilePaths,
+  removeLeadingSlash,
+} from "../prebuild.js";
+import path from "path";
+
+const isDataString = (str: string) => str.startsWith("data:");
+
+export const getUsedInternalLinksInPage = async (content: string) => {
+  const links: string[] = [];
+  const visitLinks = () => {
+    return (tree: Root) => {
+      visit(tree, (node) => {
+        if (
+          // ![]() format
+          (node.type === "link" || node.type === "image") &&
+          node.url &&
+          !isAbsoluteUrl(node.url) &&
+          !isDataString(node.url)
+        ) {
+          links.push(node.url);
+          return;
+        }
+        const mdxJsxFlowElement = node as MdxJsxFlowElement;
+        if (
+          mdxJsxFlowElement.name === "img" ||
+          mdxJsxFlowElement.name === "source"
+        ) {
+          const srcAttrIndex = mdxJsxFlowElement.attributes.findIndex(
+            (attr) => attr.type === "mdxJsxAttribute" && attr.name === "src"
+          );
+          const nodeUrl = mdxJsxFlowElement.attributes[srcAttrIndex].value;
+          if (
+            srcAttrIndex !== -1 &&
+            typeof nodeUrl === "string" &&
+            !isAbsoluteUrl(nodeUrl) &&
+            !isDataString(nodeUrl)
+          ) {
+            links.push(nodeUrl);
+          }
+        } else if (mdxJsxFlowElement.name === "a") {
+          const hrefAttrIndex = mdxJsxFlowElement.attributes.findIndex(
+            (attr) => attr.type === "mdxJsxAttribute" && attr.name === "href"
+          );
+          const nodeUrl = mdxJsxFlowElement.attributes[hrefAttrIndex].value;
+          if (
+            hrefAttrIndex !== -1 &&
+            typeof nodeUrl === "string" &&
+            !isAbsoluteUrl(nodeUrl) &&
+            !isDataString(nodeUrl)
+          ) {
+            links.push(nodeUrl);
+          }
+        }
+      });
+      return tree;
+    };
+  };
+  await remark()
+    .use(remarkMdx)
+    .use(remarkGfm)
+    .use(remarkFrontmatter, ["yaml", "toml"])
+    .use(visitLinks)
+    .process(content);
+  return normalizeFilePaths(links).map(getFullPath).map(removeLeadingSlash);
+};
+
+export const getUsedInternalLinksInSite = async (dirName: string) => {
+  const dirChildren = getPagePaths(dirName);
+  const getLinksPromises: Promise<void>[] = [];
+  const usedLinksInSite: Record<string, string[]> = {};
+  dirChildren.forEach((filePath) => {
+    getLinksPromises.push(
+      (async () => {
+        const fileContent = fs
+          .readFileSync(path.join(dirName, filePath))
+          .toString();
+        const usedLinksInPage = await getUsedInternalLinksInPage(fileContent);
+        usedLinksInSite[filePath] = usedLinksInPage;
+      })()
+    );
+  });
+  await Promise.all(getLinksPromises);
+  return usedLinksInSite;
+};

package/src/static-checking/getValidInternalLinks.ts

@@ -0,0 +1,13 @@
+import { getFileList } from "@mintlify/prebuild";
+import {
+  filterLinks,
+  removeFileExtension,
+  removeLeadingSlash,
+} from "../prebuild.js";
+
+export const getValidInternalLinks = (dirName: string) =>
+  new Set(
+    filterLinks(getFileList(dirName))
+      .map(removeFileExtension)
+      .map(removeLeadingSlash)
+  );

package/src/static-checking/index.ts

@@ -0,0 +1,8 @@
+export {
+  getUsedInternalLinksInPage,
+  getUsedInternalLinksInSite,
+} from "./getUsedInternalLinks";
+export { getValidInternalLinks } from "./getValidInternalLinks";
+
+import { getBrokenInternalLinks } from "./getBrokenInternalLinks";
+export default getBrokenInternalLinks;

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@mintlify/ts-config",
+  "compilerOptions": {
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "target": "es2022",
+    "outDir": "dist",
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"]
+}