Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
/**
* audit-links.mjs — static link & route integrity audit for the whole site.
*
* Crawls every navigable target across pages/, public/ and src/ — `href`,
* `action`, `data-href`/`data-route`/`data-link`, JS `location`/`window.open`
* navigations, and internal `fetch()` targets — then resolves each one against
* the real routing model so a dead path can never ship unseen:
*
* • internal clean URL (/marketplace, /u/:id …) → must resolve to a specific
* vercel.json route OR a real source file (pages/**, public/**). The two
* catch-alls (/(.*) and the asset glob) are NOT treated as proof — they only
* serve a literal file, so existence is checked directly.
* • internal /api/* → must resolve to a vercel route or an api/ handler file.
* • stub hrefs (#, "", javascript:void(0)) → flagged; never allowed to ship.
* • dangling routes — a vercel route whose .html dest has no source file.
* • external http(s) links → collected; liveness checked only with --external
* (network) so the default run is deterministic and offline/CI-safe.
*
* Dynamic targets (template literals with ${…}, string concatenation) are
* reported separately as "skipped" rather than guessed — they're not failures.
*
* Usage:
* node scripts/audit-links.mjs # offline integrity audit (gate)
* node scripts/audit-links.mjs --external # also probe external links (slow)
* node scripts/audit-links.mjs --json # machine-readable report to stdout
* node scripts/audit-links.mjs --report # write reports/link-audit-*.json
*
* Exit code is non-zero when broken internal links, stub hrefs, or dangling
* routes are found — so it can gate CI. External failures only warn.
*/
import { readFileSync, existsSync, statSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs';
import { resolve, join, dirname, extname } from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(__dirname, '..');
const args = new Set(process.argv.slice(2));
const CHECK_EXTERNAL = args.has('--external');
const AS_JSON = args.has('--json');
const WRITE_REPORT = args.has('--report');
// ── Filesystem walk ──────────────────────────────────────────────────────────
function walk(dir, exts, out = []) {
let entries;
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
return out;
}
for (const e of entries) {
if (e.name.startsWith('.') || e.name === 'node_modules') continue;
const full = join(dir, e.name);
if (e.isDirectory()) walk(full, exts, out);
else if (exts.has(extname(e.name))) out.push(full);
}
return out;
}
function fileExists(p) {
try {
return statSync(p).isFile();
} catch {
return false;
}
}
// ── Route table from vercel.json ─────────────────────────────────────────────
const vercel = JSON.parse(readFileSync(join(ROOT, 'vercel.json'), 'utf8'));
const ASSET_CATCHALL = '/(.*\\.(?:svg|png|jpg|jpeg|gif|webp|avif|ico|woff2|woff|ttf|otf|glb|gltf|hdr|exr|ktx2|basis|bin))$';
const isCatchAll = (src) => src === '/(.*)' || src === ASSET_CATCHALL;
const isRedirect = (r) => typeof r.status === 'number' && r.status >= 300 && r.status < 400;
// The terminal `{"src":"/(?!_vercel/).*","status":404,"dest":"/404.html"}` rewrite
// is the miss handler, not a destination. It carries a dest and its src is not the
// literal `/(.*)` catch-all, so without this it entered the route table, matched
// every path, and made every root-absolute link resolve: the broken-link count
// read 0 because nothing could ever be counted, not because nothing was broken.
const isErrorFallback = (r) => typeof r.status === 'number' && r.status >= 400;
// Specific routes that resolve a request to something: a rewrite (dest) OR a
// 3xx redirect to a real page. Both are valid link destinations.
const destRoutes = (vercel.routes || []).filter(
(r) => (r.dest || isRedirect(r)) && !isCatchAll(r.src) && !isErrorFallback(r)
);
const compiledRoutes = destRoutes.map((r) => {
let s = r.src;
if (!s.startsWith('^')) s = '^' + s;
if (!s.endsWith('$')) s = s + '$';
let re = null;
try {
re = new RegExp(s);
} catch {
re = null;
}
return { re, dest: r.dest, src: r.src };
});
function matchRoute(path) {
for (const r of compiledRoutes) {
if (r.re && r.re.test(path)) return r;
}
return null;
}
// Content trees that live at the repo root and are copied into dist/ verbatim by
// the closeBundle plugins in vite.config.js (copy-docs, copy-blog, copy-src-to-
// dist, the avatar-sdk mirror). `/blog/a-post.html` has no vercel route because
// the slug route only matches extensionless paths, so without these the whole
// blog reads as broken while production serves every one of them.
const BUILD_COPIED_ROOTS = ['blog', 'docs', 'pump-fun-skills', 'avatar-sdk'];
// Emitted at build time, so there is no source file to point at. vite-plugin-pwa
// writes the web manifest from the `manifest` block in vite.config.js, which is
// what the 250 pages linking `/manifest.webmanifest` actually get, and
// scripts/write-build-info.mjs writes dist/build-info.json, the static file the
// build stamps the running commit into and /api/version reads back.
const GENERATED_TARGETS = new Set(['/manifest.webmanifest', '/build-info.json']);
// Route dests written by a build step rather than committed, so they are absent
// in any tree that has not built and present in one that has. Left unlisted, the
// dangling check passes only where a stale build artifact happens to survive,
// which is the opposite of what this audit is for.
// /news/index.html: scripts/build-news.mjs, run from `prebuild`; public/news/
// is gitignored. scripts/verify-routes.mjs models the same file from
// data/rss/items.json, and check:dist runs after the build to confirm it landed.
const GENERATED_DESTS = new Set(['/news/index.html']);
// Does a clean path resolve to a real source file (what the catch-all serves)?
function fileForCleanPath(path) {
const p = path.replace(/^\/+/, '').replace(/\/+$/, '');
if (p === '') return 'pages/desktop.html'; // root is the web desktop; /classic keeps the old homepage
// /src/** and /node_modules/** are served straight from the repo by vite in dev
// and rewritten to hashed assets at build time — resolve against the real tree.
if (p.startsWith('src/') || p.startsWith('node_modules/')) {
return fileExists(join(ROOT, p)) ? p : null;
}
if (BUILD_COPIED_ROOTS.includes(p.split('/')[0])) {
for (const c of [p, p + '.html', join(p, 'index.html')]) {
if (fileExists(join(ROOT, c))) return c;
}
return null;
}
const candidates = [
join('public', p),
join('public', p + '.html'),
join('public', p, 'index.html'),
join('pages', p + '.html'),
join('pages', p, 'index.html'),
join('pages', p), // already has extension (e.g. /foo.html)
];
for (const c of candidates) {
if (fileExists(join(ROOT, c))) return c;
}
return null;
}
// Resolve a relative (non-/) link against the directory of the file it lives in.
function fileForRelative(rel, baseDir) {
const cleaned = rel.replace(/\/+$/, '');
const base = join(ROOT, baseDir);
const candidates = [
join(base, cleaned),
join(base, cleaned + '.html'),
join(base, cleaned, 'index.html'),
];
return candidates.some((c) => fileExists(c));
}
function apiResolves(path) {
// vercel route maps it, or an api/ handler file exists.
if (matchRoute(path)) return true;
const p = path.replace(/^\/+/, '');
const bases = [join(ROOT, p), join(ROOT, p + '.js'), join(ROOT, p, 'index.js')];
return bases.some((b) => fileExists(b));
}
// ── Resolve a single internal target ─────────────────────────────────────────
function resolveInternal(rawTarget, baseDir) {
const target = rawTarget.split('#')[0].split('?')[0];
if (target === '') return { ok: true }; // pure #anchor / query on current page
if (GENERATED_TARGETS.has(target)) return { ok: true, via: 'build output' };
// Relative path (not root-absolute) → resolve against the file's own directory.
if (!target.startsWith('/')) {
return fileForRelative(target, baseDir) ? { ok: true } : { ok: false, kind: 'relative' };
}
if (target.startsWith('/api/')) {
return apiResolves(target) ? { ok: true } : { ok: false, kind: 'api' };
}
const route = matchRoute(target);
if (route) {
// Route maps it — confirm an html dest's source actually exists (dangling check
// happens separately; here a matched route is enough to call the link reachable).
return { ok: true, via: route.src };
}
const file = fileForCleanPath(target);
if (file) return { ok: true, via: file };
return { ok: false, kind: 'page' };
}
// ── Target extraction ────────────────────────────────────────────────────────
const STUB_VALUES = new Set(['#', '', 'javascript:void(0)', 'javascript:void(0);', 'javascript:;', 'javascript:']);
// Self-origins: a link written as an absolute URL back to our own domain is really
// an internal route — resolve it locally instead of probing the live deploy (which
// lags source and yields false 404s). This also surfaces genuinely wrong self-links.
const SELF_ORIGINS = /^https?:\/\/(?:www\.)?(?:three\.ws|3d-agent\.vercel\.app)(\/[^\s]*)?$/i;
function classifyTarget(value) {
const v = (value || '').trim();
if (STUB_VALUES.has(v.toLowerCase())) return { type: 'stub', value: v };
// javascript:void(0) is a stub; any other javascript: URL runs real code → scheme.
// cursor:, vscode: and vscode-insiders: are the editors' MCP install deep links
// (/connect): they open a local app, so there is nothing to resolve or probe.
if (/^(mailto:|tel:|sms:|data:|blob:|javascript:|cursor:|vscode:|vscode-insiders:)/i.test(v)) return { type: 'scheme', value: v };
// Dynamic FIRST — a template-literal/concatenated URL is not a concrete target,
// even when it starts with https:// (e.g. `https://solscan.io/tx/${sig}`).
if (v.includes('${') || /["'`]\s*\+/.test(v) || v.includes('+ ')) return { type: 'dynamic', value: v };
const self = v.match(SELF_ORIGINS);
if (self) return { type: 'internal', value: self[1] || '/' };
if (/^https?:\/\//i.test(v)) return { type: 'external', value: v };
if (/^\/\//.test(v)) return { type: 'external', value: 'https:' + v };
if (v.startsWith('#')) return { type: 'anchor', value: v };
if (v.startsWith('/') || /^[\w.-]/.test(v)) return { type: 'internal', value: v };
return { type: 'dynamic', value: v };
}
// Lookbehind blocks `data-action`/`reaction`/etc. from matching the bare `action`
// attribute — only a real navigable attribute (preceded by whitespace or tag-open).
const htmlAttrRe = /(?<![\w-])(?:href|formaction|action|data-href|data-route|data-link|data-target-href)\s*=\s*("([^"]*)"|'([^']*)')/gi;
// The `href:` alternative targets an object-literal property (`{ href: '/x' }`).
// The lookbehind keeps it off a *property read* followed by a ternary colon -
// `new URL(x, origin).href : ''` is a value expression, not a navigation.
const jsNavRe = /(\.href\s*=|location\.(?:assign|replace)\s*\(|window\.open\s*\(|(?<![.\w$])href\s*:|\bnavigateTo\s*\(|\brouteTo\s*\()\s*("([^"]*)"|'([^']*)'|`([^`$]*)`)/gi;
// `navigateTo(...)` / `routeTo(...)` read as router calls only when the router is
// the site's. A page that declares its OWN function of that name is switching an
// in-page section by key, not by path: pages/pump-dashboard.html hands its
// navigateTo() a cockpit key ('config', 'watches') and renders `#config`. Those
// keys are not files, so resolving them against the filesystem invents a broken
// link out of working code, and does it selectively: 'animations' happened to
// collide with pages/animations.html and passed, while 'config' failed the gate.
const localRouterRe = /(?:function\s+(?:navigateTo|routeTo)\s*\(|(?:const|let|var)\s+(?:navigateTo|routeTo)\s*=)/;
const routerCallRe = /^(?:navigateTo|routeTo)\s*\(/;
const fetchRe = /\bfetch\s*\(\s*("([^"]*)"|'([^']*)'|`([^`$]*)`)/gi;
// A string literal immediately followed by `+` is only the *head* of a computed
// URL (`dot.href = '#' + section.id`, `fetch('/login?next=' + to)`). Its path
// prefix is still worth resolving, that catches a renamed route, but it can
// never be a stub: the part that makes the target real is the concatenated tail.
function concatenatedAfter(content, endIndex) {
let i = endIndex;
while (i < content.length && (content[i] === ' ' || content[i] === '\t')) i++;
return content[i] === '+';
}
// Prose in a comment is not a link. A comment explaining why a control became a
// button, quoting the href="#" it replaced, must not read back as that stub.
//
// This needs a real forward pass, not a backwards search for the nearest `/*`:
// a line comment mentioning `/api/coin/*` would open a block comment that never
// closes, and every finding below it in the file would vanish. Tracking strings,
// template literals (with `${…}` nesting) and regex literals keeps the scanner
// in sync, so a comment is only a comment when it actually starts in code.
// A `/` here starts a regex literal, not a division: nothing that could end an
// operand precedes it. Getting this wrong only risks re-syncing on the next
// quote, never a false comment.
const REGEX_PRECEDERS = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '^', '~', '<', '>', 'return']);
function skipQuoted(content, i, quote) {
i++;
while (i < content.length) {
const ch = content[i];
if (ch === '\\') i += 2;
else if (ch === quote || ch === '\n') return i + 1; // newline: unterminated, re-sync
else i++;
}
return i;
}
function skipRegexLiteral(content, i) {
i++;
let inClass = false;
while (i < content.length) {
const ch = content[i];
if (ch === '\\') i += 2;
else if (ch === '\n') return i + 1; // unterminated, re-sync
else if (ch === '[') { inClass = true; i++; }
else if (ch === ']') { inClass = false; i++; }
else if (ch === '/' && !inClass) return i + 1;
else i++;
}
return i;
}
// Byte mask of the file: 1 where a character sits inside a JS comment.
function commentMask(content) {
const mask = new Uint8Array(content.length);
const stack = [{ mode: 'code', depth: 0 }];
let prev = '';
let i = 0;
while (i < content.length) {
const top = stack[stack.length - 1];
const ch = content[i];
if (top.mode === 'template') {
if (ch === '\\') i += 2;
else if (ch === '`') { stack.pop(); i++; }
else if (ch === '$' && content[i + 1] === '{') { stack.push({ mode: 'code', depth: 0 }); i += 2; }
else i++;
continue;
}
if (ch === '/' && content[i + 1] === '/') {
const nl = content.indexOf('\n', i);
const stop = nl === -1 ? content.length : nl;
mask.fill(1, i, stop);
i = stop;
continue;
}
if (ch === '/' && content[i + 1] === '*') {
const close = content.indexOf('*/', i + 2);
const stop = close === -1 ? content.length : close + 2;
mask.fill(1, i, stop);
i = stop;
continue;
}
if (ch === '"' || ch === "'") { i = skipQuoted(content, i, ch); prev = 'x'; continue; }
if (ch === '`') { stack.push({ mode: 'template', depth: 0 }); i++; continue; }
if (ch === '/' && REGEX_PRECEDERS.has(prev)) { i = skipRegexLiteral(content, i); prev = 'x'; continue; }
if (ch === '{') { top.depth++; prev = ch; i++; continue; }
if (ch === '}') {
if (top.depth === 0 && stack.length > 1) { stack.pop(); i++; continue; }
top.depth--; prev = ch; i++; continue;
}
if (!/\s/.test(ch)) prev = ch;
i++;
}
return mask;
}
function lineOf(content, index) {
let line = 1;
for (let i = 0; i < index && i < content.length; i++) if (content[i] === '\n') line++;
return line;
}
const findings = {
brokenInternal: [],
stubs: [],
external: new Map(), // url -> [{file,line}]
dynamic: 0,
scanned: 0,
};
// A JS assignment like `el.href = "/x"` is matched by both the attribute pass and
// the navigation pass. Same file, same line, same target is one link, not two.
const seen = new Set();
function record(target, file, line, isPrefix = false) {
const rel = file.replace(ROOT + '/', '');
const dedupeKey = `${rel}:${line}:${target}`;
if (seen.has(dedupeKey)) return;
seen.add(dedupeKey);
const baseDir = dirname(rel); // for resolving relative links from this file's dir
const c = classifyTarget(target);
if (c.type === 'stub') {
if (isPrefix) findings.dynamic++; // head of a computed URL, not a dead target
else findings.stubs.push({ file: rel, line, value: c.value });
return;
}
if (c.type === 'external') {
// `href = 'http://' + cap[0]` is an origin being assembled, not a link to
// the bare scheme. An internal prefix below stays worth resolving (its path
// head still catches a renamed route); a bare origin resolves to nothing.
if (isPrefix) {
findings.dynamic++;
return;
}
const list = findings.external.get(c.value) || [];
list.push({ file: rel, line });
findings.external.set(c.value, list);
return;
}
if (c.type === 'internal') {
const r = resolveInternal(c.value, baseDir);
if (!r.ok) findings.brokenInternal.push({ file: rel, line, value: c.value, kind: r.kind });
return;
}
if (c.type === 'dynamic') findings.dynamic++;
// scheme / anchor → fine
}
// Third-party/minified bundles whose internals aren't our navigable links.
// Scoped to the real vendored trees: `public/three/` is the shipped three.js
// runtime, while `src/three/` is OUR $THREE access SDK and must stay audited.
const VENDOR_RE = /(?:^public\/three\/|\bvendor\b|\.min\.js$|wasm_wrapper)/;
// Most of this app's markup is rendered from JS template strings, so the same
// `href="…"` attributes live inside .js as inside .html. Scan them there too, but
// with a narrower attribute set than the HTML pass: a bare `action="…"` in JS is
// far more often a plain variable (`const action = 'delete'`) than a form target.
const jsAttrRe = /(?<![\w-])(?:href|data-href|data-route|data-link|data-target-href)\s*=\s*("([^"]*)"|'([^']*)')/gi;
// An HTML file's inert regions: a rendered code sample (`<pre>`/`<code>`) is text
// on the page, not navigation, and an `<!-- -->` comment is not markup at all.
// A docs page quoting `action="Summarize"` inside a JSX sample must not read back
// as a form target, exactly as a JS comment quoting an href must not read back as
// a link.
const htmlInertRe = /<(pre|code)\b[^>]*>[\s\S]*?<\/\1>|<!--[\s\S]*?-->/gi;
// An inline <script> body is JS, so JS rules apply inside it: its comments are
// comments, and `a.href = '#' + doc` is the head of a computed anchor.
const scriptRe = /<script\b[^>]*>([\s\S]*?)<\/script>/gi;
// `<link rel="preconnect" href="https://fonts.gstatic.com">` names an origin to
// open a socket to, not a document to navigate to. Probing it as a link reports
// the font API root as a dead 404 forever, on pages whose fonts load fine. The
// stylesheet request itself is a separate <link> and stays audited. These hints
// also appear inside JS template strings (api/discover-detail.js renders one),
// so both mask paths apply it.
const linkHintRe = /<link\b[^>]*\brel\s*=\s*["']?(?:preconnect|dns-prefetch)\b[^>]*>/gi;
function maskLinkHints(content, mask) {
linkHintRe.lastIndex = 0;
let m;
while ((m = linkHintRe.exec(content))) mask.fill(1, m.index, m.index + m[0].length);
return mask;
}
function htmlMask(content) {
const mask = new Uint8Array(content.length);
let m;
htmlInertRe.lastIndex = 0;
while ((m = htmlInertRe.exec(content))) mask.fill(1, m.index, m.index + m[0].length);
scriptRe.lastIndex = 0;
while ((m = scriptRe.exec(content))) {
const bodyStart = m.index + m[0].length - '</script>'.length - m[1].length;
const sub = commentMask(m[1]);
for (let i = 0; i < sub.length; i++) if (sub[i]) mask[bodyStart + i] = 1;
}
return mask;
}
function scanFile(file) {
const rel = file.replace(ROOT + '/', '');
if (VENDOR_RE.test(rel)) return; // skip vendored libs — not our link surface
const content = readFileSync(file, 'utf8');
const isJs = /\.m?js$/.test(file);
const mask = maskLinkHints(content, isJs ? commentMask(content) : htmlMask(content));
const inComment = (index) => mask[index] === 1;
findings.scanned++;
// Page-local router (see localRouterRe): its calls carry section keys, not paths.
const ownsRouter = localRouterRe.test(content);
let m;
const attrRe = isJs ? jsAttrRe : htmlAttrRe;
attrRe.lastIndex = 0;
while ((m = attrRe.exec(content))) {
if (inComment(m.index)) continue;
// `dot.href = '#' + section.id` is the head of a computed anchor, not a stub.
// True in an inline <script> as much as in a .js file; a real markup
// attribute is never followed by a `+`, so the test is safe on both.
const isPrefix = concatenatedAfter(content, m.index + m[0].length);
record(m[2] ?? m[3] ?? '', file, lineOf(content, m.index), isPrefix);
}
jsNavRe.lastIndex = 0;
while ((m = jsNavRe.exec(content))) {
const target = m[3] ?? m[4] ?? m[5] ?? '';
// `window.open('')` opens a blank tab the caller then writes into, a real
// pattern, not a link to nowhere.
if (target === '' && /^window\.open/i.test(m[1])) continue;
// `{ href: '' }` in an object literal is the ABSENCE of a link, and every
// consumer of a link-descriptor object in this repo guards on it before
// rendering an anchor. That is the opposite of markup: `<a href="">` is a
// live element that navigates to the current URL, which is why the empty
// string stays a stub everywhere else. Only the object-literal form is
// exempt, so a real `el.href = ''` assignment is still reported.
if (target === '' && /href\s*:$/i.test(m[1])) continue;
// A section key handed to this file's own navigateTo()/routeTo() is not a
// navigable target; count it as skipped rather than resolving it as a path.
if (ownsRouter && routerCallRe.test(m[1])) { findings.dynamic++; continue; }
if (inComment(m.index)) continue;
record(target, file, lineOf(content, m.index), concatenatedAfter(content, m.index + m[0].length));
}
fetchRe.lastIndex = 0;
while ((m = fetchRe.exec(content))) {
// Masked exactly like the two scanners above. This one skipped the check,
// so a module's own header comment explaining what NOT to call was read as
// a call: the line warning against raw `fetch('/api…')` was reported as a
// broken link to `/api…`, a path no code ever requests.
if (inComment(m.index)) continue;
const t = m[2] ?? m[3] ?? m[4] ?? '';
if (t.startsWith('/')) record(t, file, lineOf(content, m.index)); // only internal fetches
}
}
// ── Dangling-route check: vercel route → missing source file ─────────────────
function danglingRoutes() {
const out = [];
for (const r of destRoutes) {
if (!r.dest) continue; // redirect route — no file to dangle
const dest = r.dest.split('?')[0];
if (!dest.endsWith('.html')) continue;
if (dest.includes('$')) continue; // dest uses a capture group — resolved per-request
if (GENERATED_DESTS.has(dest)) continue; // written by a build step, see above
const p = dest.replace(/^\/+/, '');
// pages/ and public/ cover most dests, but a few top-level content trees
// (docs/, blog/) sit directly at the repo root as siblings of pages/ —
// check there too, or every one of their vercel.json routes false-positives
// as dangling despite serving real 200s in production.
const exists =
fileExists(join(ROOT, 'pages', p)) ||
fileExists(join(ROOT, 'public', p)) ||
fileExists(join(ROOT, p));
if (!exists) out.push({ src: r.src, dest: r.dest });
}
return out;
}
// ── External liveness (opt-in) ───────────────────────────────────────────────
// A bare `fetch` sends no User-Agent that any CDN recognizes, so Cloudflare and
// friends answer with a TLS reset or an interstitial. That read back as a dead
// link for pages a browser opens fine (t.me, solflare.com, ibm.com), which is
// worse than no report: a list that is mostly false positives gets ignored, and
// the real 404 hiding in it ships. Ask for the page the way a browser does.
const PROBE_HEADERS = {
'user-agent':
'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36',
accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
'accept-language': 'en-US,en;q=0.9',
};
// x.com serves a logged-out `/status/<id>` page as a 404 to every client that
// does not run its JS, including a real browser with cookies cleared. The probe
// therefore cannot tell a live post from a deleted one there, so it must not
// claim either. Profiles and every other path still get probed normally.
const UNPROBEABLE_RE = /^https?:\/\/(?:www\.)?(?:x|twitter)\.com\/[^/]+\/status\//i;
// 401/403/429/405 mean the host answered but bot-blocks automated probes, so the
// page exists. Only 404/410/5xx and DNS/timeout failures are truly dead.
const aliveStatus = (s) => s < 400 || [401, 403, 405, 429].includes(s);
// A HEAD is cheap but some hosts route it differently from a GET: alibabacloud
// sends one to a geo-router that 500s while the GET loads the page. A 404, an
// explicit method rejection, or any 5xx therefore earns one GET before the link
// is called dead. 403 is deliberately absent: it already reads as alive, and
// re-asking a bot-blocking CDN with a GET trades that answer for a reset.
const retryWithGet = (s) => s === 404 || s === 405 || s === 501 || s >= 500;
// undici caps response headers at 16 KB and throws past it. The host answered,
// so the page is there; only the probe could not read the preamble.
const ANSWERED_ANYWAY = new Set(['UND_ERR_HEADERS_OVERFLOW']);
function errorCode(e) {
if (e.name === 'AbortError') return 'timeout';
const code = e.cause?.code || e.cause?.name;
return code ? `error:${code}` : 'error';
}
async function probeExternal(urls) {
const dead = [];
const queue = urls.filter((u) => !UNPROBEABLE_RE.test(u));
// Eight at a time, not twelve: the probe shares one egress with whatever else
// this machine is doing, and a saturated pool shows up as ETIMEDOUT on live
// hosts, which is exactly the false positive this whole pass exists to kill.
const CONCURRENCY = 8;
async function worker() {
while (queue.length) {
const url = queue.shift();
const once = async (method) => {
const ctrl = new AbortController();
const t = setTimeout(() => ctrl.abort(), 15000);
try {
const res = await fetch(url, { method, redirect: 'follow', signal: ctrl.signal, headers: PROBE_HEADERS });
return { status: res.status };
} catch (e) {
if (ANSWERED_ANYWAY.has(e.cause?.code)) return { status: 200 };
return { error: errorCode(e) };
} finally {
clearTimeout(t);
}
};
let res = await once('HEAD');
// A network error is as often this machine's egress as the host, and a
// method rejection says nothing about the page, so both earn a GET. The
// GET answers the actual question, but a GET that itself fails to connect
// must not overwrite an answer the host already gave. A failed retry gets
// one more attempt after a pause, since a saturated pool clears on its own.
if (res.error || retryWithGet(res.status)) {
let retry = await once('GET');
if (retry.error) {
await new Promise((r) => setTimeout(r, 1500));
retry = await once('GET');
}
if (!retry.error) res = retry;
}
if (res.error) dead.push({ url, status: res.error });
else if (!aliveStatus(res.status)) dead.push({ url, status: res.status });
}
}
await Promise.all(Array.from({ length: CONCURRENCY }, worker));
return dead;
}
// ── Run ──────────────────────────────────────────────────────────────────────
const exts = new Set(['.html', '.js', '.mjs']);
// Every tree vercel.json can route a request into. `docs/`, `blog/` and `chat/`
// sit at the repo root as siblings of `pages/` and serve real 200s in production
// (see the dangling-route check below, which already resolves dests there), so a
// dead link in one of them ships exactly as visibly as a dead link in `pages/`.
const LINK_SURFACES = ['pages', 'public', 'src', 'docs', 'blog', 'chat'];
const files = LINK_SURFACES.flatMap((d) => walk(join(ROOT, d), exts));
for (const f of files) scanFile(f);
const dangling = danglingRoutes();
const externalUrls = [...findings.external.keys()];
let externalDead = [];
if (CHECK_EXTERNAL) externalDead = await probeExternal(externalUrls);
const report = {
scannedFiles: findings.scanned,
brokenInternal: findings.brokenInternal,
stubs: findings.stubs,
danglingRoutes: dangling,
externalCount: externalUrls.length,
externalDead,
dynamicSkipped: findings.dynamic,
};
if (AS_JSON) {
console.log(JSON.stringify(report, null, 2));
} else {
const line = (s = '') => console.log(s);
line(`Link audit: scanned ${findings.scanned} files`);
line('');
line(`Broken internal links : ${findings.brokenInternal.length}`);
for (const b of findings.brokenInternal.slice(0, 60)) line(` ✗ ${b.value} (${b.kind}) — ${b.file}:${b.line}`);
if (findings.brokenInternal.length > 60) line(` … +${findings.brokenInternal.length - 60} more`);
line('');
line(`Stub hrefs (#, void(0)) : ${findings.stubs.length}`);
for (const s of findings.stubs.slice(0, 40)) line(` ✗ "${s.value}" — ${s.file}:${s.line}`);
if (findings.stubs.length > 40) line(` … +${findings.stubs.length - 40} more`);
line('');
line(`Dangling routes (→ missing file) : ${dangling.length}`);
for (const d of dangling) line(` ✗ ${d.src} → ${d.dest}`);
line('');
line(`External links collected : ${externalUrls.length}`);
if (CHECK_EXTERNAL) {
line(`Dead external links : ${externalDead.length}`);
for (const d of externalDead) line(` ✗ [${d.status}] ${d.url}`);
} else {
line(' (run with --external to probe liveness)');
}
line('');
line(`Dynamic targets skipped : ${findings.dynamic}`);
}
if (WRITE_REPORT) {
mkdirSync(join(ROOT, 'reports'), { recursive: true });
const out = join(ROOT, 'reports', `link-audit-${Date.now()}.json`);
writeFileSync(out, JSON.stringify(report, null, 2));
console.log(`\nReport: ${out.replace(ROOT + '/', '')}`);
}
const hardFails = findings.brokenInternal.length + findings.stubs.length + dangling.length;
if (hardFails > 0) process.exitCode = 1;