chore: add script to check generated d.ts jsdoc links

Author: ukorvl

.github/actions/build/action.yaml

@@ -33,3 +33,7 @@ runs:
         cd lib
         npm run check-exports
       shell: bash
+
+    - name: Check generated jsdoc links
+      run: npm run check:jsdoc-links
+      shell: bash

.github/actions/lint/action.yaml

@@ -29,3 +29,7 @@ runs:
         git config --global --add safe.directory "$(pwd)"
         npm run lint:commits
       shell: bash
+
+    - name: Check markdown links
+      run: npm run check:md-links
+      shell: bash

lib/src/markers/Markers.tsx

@@ -19,8 +19,8 @@ const MarkersRenderFunction = (
  * @param props - The properties for the markers.
  * @param ref - The ref to access the markers API.
  * @returns A React component that renders the markers.
- * @see {@link https://tradingview.github.io/lightweight-charts/tutorials/how_to/series-markers | Markers documentation}
- * @see {@link https://tradingview.github.io/lightweight-charts/docs/markers | TradingView documentation for markers}
+ * @see {@link https://ukorvl.github.io/lightweight-charts-react-components/docs/markers | Documentation for Markers}
+ * @see {@link https://tradingview.github.io/lightweight-charts/tutorials/how_to/series-markers | TradingView documentation for markers}
  * @example
  * ```tsx
  * <Markers

package-lock.json

@@ -5,7 +5,8 @@
     "lint": "eslint . --ext .ts,.tsx",
     "lint:fix": "eslint . --ext .ts,.tsx --fix",
     "lint:commits": "bash ./scripts/lint-commits.sh",
-    "lint:md-links": "node ./scripts/check-md-links.mts",
+    "check:md-links": "node ./scripts/check-md-links.mts",
+    "check:jsdoc-links": "node ./scripts/check-jsdoc-links.mts",
     "format": "prettier --check './**/*.{ts,tsx,json,mjs,md}'",
     "format:fix": "prettier --write './**/*.{ts,tsx,json,mjs,md}'",
     "dev": "concurrently \"npm run dev -w lib\" \"npm run dev -w examples\" --kill-others --success last",
@@ -36,6 +37,7 @@
     "@testing-library/react": "^16.3.0",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^24.0.13",
+    "chalk": "^5.5.0",
     "concurrently": "^9.1.2",
     "dotenv": "^17.2.0",
     "eslint": "^9.28.0",
@@ -53,6 +55,7 @@
     "lint-staged": "^15.5.2",
     "markdown-it-anchor": "^9.2.0",
     "npm-run-all": "^4.1.5",
+    "p-limit": "^6.2.0",
     "prettier": "^3.6.2",
     "simple-git-hooks": "^2.11.1",
     "size-limit": "^11.2.0",
@@ -93,7 +96,8 @@
       "lib/rslib.config.ts",
       "lib/tests/**",
       "scripts/check-md-links.mts",
-      "examples/scripts/prelhci.ts"
+      "examples/scripts/prelhci.ts",
+      "scripts/check-jsdoc-links.mts"
     ],
     "ignoreBinaries": [
       "lint-staged",
@@ -102,9 +106,9 @@
     ]
   },
   "optionalDependencies": {
-    "@rollup/rollup-linux-x64-gnu": "4.37.0",
-    "@rspack/binding-linux-x64-gnu": "1.3.0",
     "@ast-grep/napi-linux-x64-gnu": "0.36.2",
-    "@esbuild/linux-x64": "0.25.8"
+    "@esbuild/linux-x64": "0.25.8",
+    "@rollup/rollup-linux-x64-gnu": "4.37.0",
+    "@rspack/binding-linux-x64-gnu": "1.3.0"
   }
 }

package.json

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+/**
+ * This script checks external links in generated jsdoc files.
+ */
+
+import { readFile } from "fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import pLimit from "p-limit";
+import ts from "typescript";
+
+/** Key is domain name, value is an array of links, using Set to avoid duplicates */
+type LinksMap = Map<string, Set<string>>;
+
+const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+const rootDir = path.join(scriptDir, "..");
+const libOutputDir = path.join(rootDir, "lib", "dist");
+const fileName = "index.d.ts";
+const potentiallyDTSBundleFile = path.join(libOutputDir, fileName);
+
+const limitPerTCPConnection = pLimit(10);
+
+/** Avoid throwing errors to check all links even if one of them is broken, push errors to an array instead */
+const scriptErrors: string[] = [];
+
+// TODO: remove after deploying docs page
+const ignoreDomains = new Set(["ukorvl.github.io"]);
+
+const sourceFile = ts.createSourceFile(
+  potentiallyDTSBundleFile,
+  await readFile(potentiallyDTSBundleFile, "utf8"),
+  ts.ScriptTarget.ESNext,
+  true,
+  ts.ScriptKind.TS
+);
+
+const extractUrlsFromSeeTag = (tag: ts.JSDocTag): string[] => {
+  const results: string[] = [];
+
+  if (!Array.isArray(tag.comment)) return results;
+
+  for (const fragment of tag.comment) {
+    if ("name" in fragment && fragment.name) {
+      const prefix = ts.isIdentifier(fragment.name)
+        ? fragment.name.escapedText.toString()
+        : "";
+
+      const full = prefix + fragment.text;
+      const [url] = full.split("|");
+
+      if (url.trim().startsWith("http")) {
+        results.push(url.trim());
+      }
+    }
+
+    if (!("name" in fragment) && typeof fragment.text === "string") {
+      const possibleUrl = fragment.text.trim();
+
+      if (possibleUrl.startsWith("http")) {
+        results.push(possibleUrl);
+      }
+
+      if (possibleUrl.startsWith("://")) {
+        results.push("https" + possibleUrl);
+      }
+    }
+  }
+
+  return results;
+};
+
+const main = async () => {
+  const linksMap: LinksMap = new Map();
+
+  const visitNode = (node: ts.Node) => {
+    const tags = ts.getJSDocTags(node);
+
+    for (const tag of tags) {
+      if (tag.tagName.escapedText === "see" && tag.comment) {
+        const urls = extractUrlsFromSeeTag(tag);
+
+        for (const url of urls) {
+          const urlObj = new URL(url);
+          const domain = urlObj.hostname;
+
+          if (ignoreDomains.has(domain)) {
+            continue;
+          }
+
+          if (!linksMap.has(domain)) {
+            linksMap.set(domain, new Set());
+          }
+
+          linksMap.get(domain)?.add(url);
+        }
+      }
+    }
+
+    ts.forEachChild(node, visitNode);
+  };
+
+  visitNode(sourceFile);
+
+  const domains = Array.from(linksMap.keys());
+
+  return Promise.all(
+    domains.map(domain => {
+      const links = Array.from(linksMap.get(domain) || []);
+
+      return limitPerTCPConnection(async () => {
+        for (const link of links) {
+          try {
+            const response = await fetch(link, { method: "HEAD" });
+
+            if (!response.ok) {
+              scriptErrors.push(`Invalid link: ${link} (status: ${response.status})`);
+            }
+          } catch (error) {
+            scriptErrors.push(`Error fetching link: ${link} (${error})`);
+          }
+        }
+      });
+    })
+  );
+};
+
+main()
+  .then(() => {
+    if (scriptErrors.length > 0) {
+      console.log(
+        chalk.red.bold(
+          `Found ${scriptErrors.length} errors in ${potentiallyDTSBundleFile}:`
+        )
+      );
+      scriptErrors.forEach(error => console.error(`- ${error}`));
+      process.exit(1);
+    } else {
+      console.log(chalk.green(`All links in ${potentiallyDTSBundleFile} are valid.`));
+      process.exit(0);
+    }
+  })
+  .catch(error => {
+    console.error(
+      `An error occurred while checking jsdoc links in ${potentiallyDTSBundleFile}:`,
+      error
+    );
+    process.exit(1);
+  });