Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
feat(check): add doc-links checker for internal markdown references
diegosouzapw0ccc1f0d601d
diff --git a/scripts/check/check-doc-links.mjs b/scripts/check/check-doc-links.mjsnew file mode 100644index 0000000000..c25583266d--- /dev/null+++ b/scripts/check/check-doc-links.mjs@@ -0,0 +1,223 @@+#!/usr/bin/env node+/**+ * OmniRoute — internal documentation link checker.+ *+ * Scans every Markdown file under `docs/` (excluding mirrored translations,+ * screenshots, exported diagrams, and superpowers plans) for relative or+ * project-rooted internal links and verifies the referenced files exist on+ * disk. External URLs (http/https/mailto), telephone links, and pure+ * anchor-only links (#section) are ignored.+ *+ * Supported syntaxes:+ * - Markdown links: [label](path "optional title")+ * - Reference links: [label]: path "optional title"+ * - HTML anchors: <a href="path">+ * - HTML image refs: <img src="path">+ *+ * Usage:+ * node scripts/check/check-doc-links.mjs # strict (CI gate)+ * node scripts/check/check-doc-links.mjs --report # human report, exit 0+ * node scripts/check/check-doc-links.mjs --json # JSON to stdout+ *+ * Exit codes:+ * 0 ok (or --report mode)+ * 1 one or more broken internal links detected+ */++import fs from "node:fs";+import path from "node:path";+import process from "node:process";+import { fileURLToPath } from "node:url";++const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));+const REPO_ROOT = path.resolve(SCRIPT_DIR, "..", "..");+const DOCS_ROOT = path.join(REPO_ROOT, "docs");++const EXCLUDE_PREFIXES = [+ path.join(DOCS_ROOT, "i18n") + path.sep,+ path.join(DOCS_ROOT, "screenshots") + path.sep,+ path.join(DOCS_ROOT, "superpowers") + path.sep,+ path.join(DOCS_ROOT, "diagrams", "exported") + path.sep,+];++function parseArgs(argv) {+ const opts = { report: false, json: false };+ for (const arg of argv.slice(2)) {+ if (arg === "--report") opts.report = true;+ else if (arg === "--json") opts.json = true;+ else if (arg === "--help" || arg === "-h") {+ console.log(+ [+ "Usage: node scripts/check/check-doc-links.mjs [options]",+ "",+ " --report Print findings and exit 0 regardless",+ " --json Emit JSON report to stdout",+ ].join("\n")+ );+ process.exit(0);+ }+ }+ return opts;+}++function walkDocs(dir, out) {+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {+ const full = path.join(dir, entry.name);+ if (entry.isDirectory()) {+ const prefixed = full + path.sep;+ if (EXCLUDE_PREFIXES.some((p) => prefixed.startsWith(p))) continue;+ walkDocs(full, out);+ } else if (entry.isFile() && full.endsWith(".md")) {+ if (EXCLUDE_PREFIXES.some((p) => full.startsWith(p))) continue;+ out.push(full);+ }+ }+}++function isExternal(target) {+ return (+ /^[a-z][a-z0-9+.-]*:/i.test(target) || // http:, https:, mailto:, tel:, data:, ftp: ...+ target.startsWith("//")+ );+}++function stripFragmentAndQuery(target) {+ let value = target;+ const hashAt = value.indexOf("#");+ if (hashAt !== -1) value = value.slice(0, hashAt);+ const queryAt = value.indexOf("?");+ if (queryAt !== -1) value = value.slice(0, queryAt);+ return value;+}++function extractLinks(content) {+ const links = [];+ // Strip fenced code blocks to avoid false positives.+ const sanitized = content.replace(/```[\s\S]*?```/g, (m) => " ".repeat(m.length));+ const lines = sanitized.split(/\r?\n/);++ for (let i = 0; i < lines.length; i++) {+ const line = lines[i];+ const lineNumber = i + 1;++ // Markdown inline links: [text](target) — supports nested parens minimally.+ const inlineRe = /(!?)\[(?:[^\]]*)\]\(([^)\s]+(?:\s+"[^"]*")?)\)/g;+ let match;+ while ((match = inlineRe.exec(line)) !== null) {+ const raw = match[2].replace(/\s+"[^"]*"$/, "").trim();+ if (raw) links.push({ target: raw, line: lineNumber });+ }++ // Reference-style links: [label]: target ("optional title")+ const refRe = /^\s{0,3}\[[^\]]+\]:\s+([^\s]+)(?:\s+"[^"]*")?\s*$/;+ const refMatch = line.match(refRe);+ if (refMatch) links.push({ target: refMatch[1], line: lineNumber });++ // HTML href / src+ const htmlRe = /\b(?:href|src)\s*=\s*"([^"]+)"/g;+ while ((match = htmlRe.exec(line)) !== null) {+ links.push({ target: match[1], line: lineNumber });+ }+ }++ return links;+}++function resolveTarget(sourceFile, target) {+ // /docs/foo.md, /foo, /reference/ENVIRONMENT.md → project-rooted.+ if (target.startsWith("/")) {+ return path.join(REPO_ROOT, target.replace(/^\/+/, ""));+ }+ // Otherwise resolve against the source file's directory.+ return path.resolve(path.dirname(sourceFile), target);+}++function probeExists(absPath) {+ if (fs.existsSync(absPath)) return true;+ // Allow links omitting `.md` (some doc viewers do this).+ if (!path.extname(absPath) && fs.existsSync(`${absPath}.md`)) return true;+ // Allow directory links resolving to an index/README.+ if (fs.existsSync(path.join(absPath, "README.md"))) return true;+ if (fs.existsSync(path.join(absPath, "index.md"))) return true;+ return false;+}++function main() {+ const opts = parseArgs(process.argv);++ if (!fs.existsSync(DOCS_ROOT)) {+ console.error("[doc-links] FAIL — docs/ directory not found");+ process.exit(1);+ }++ const files = [];+ walkDocs(DOCS_ROOT, files);++ /** @type {Array<{source:string, line:number, target:string, reason:string}>} */+ const broken = [];+ let checkedLinks = 0;++ for (const file of files) {+ const content = fs.readFileSync(file, "utf8");+ const links = extractLinks(content);+ for (const { target, line } of links) {+ if (!target) continue;+ if (target.startsWith("#")) continue; // anchor-only+ if (isExternal(target)) continue;+ const clean = stripFragmentAndQuery(target);+ if (!clean) continue; // e.g. "?query" alone — ignore+ checkedLinks++;+ const abs = resolveTarget(file, clean);+ if (!probeExists(abs)) {+ broken.push({+ source: path.relative(REPO_ROOT, file),+ line,+ target,+ reason: "missing",+ });+ }+ }+ }++ if (opts.json) {+ process.stdout.write(+ JSON.stringify(+ {+ ok: broken.length === 0,+ scannedFiles: files.length,+ checkedLinks,+ broken,+ },+ null,+ 2+ ) + "\n"+ );+ process.exit(broken.length && !opts.report ? 1 : 0);+ }++ console.log(`[doc-links] scanned ${files.length} docs, checked ${checkedLinks} internal links`);++ if (broken.length === 0) {+ console.log("[doc-links] PASS — no broken internal links");+ process.exit(0);+ }++ // Group by source for readability.+ const bySource = new Map();+ for (const entry of broken) {+ if (!bySource.has(entry.source)) bySource.set(entry.source, []);+ bySource.get(entry.source).push(entry);+ }++ console.log(`[doc-links] FAIL — ${broken.length} broken link(s) in ${bySource.size} file(s):`);+ for (const [source, entries] of bySource) {+ console.log(`\n ${source}`);+ for (const entry of entries) {+ console.log(` line ${entry.line}: ${entry.target}`);+ }+ }++ process.exit(opts.report ? 0 : 1);+}++main();