A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file verify-doc-links.mjs
* @brief Guard against dead internal documentation links.
*
* Walks the built site and resolves every in-site `/docs/...` link against the
* files the build actually emitted. A guide that links to a page someone
* renamed — or an old URL whose `redirects` entry was dropped — fails here
* instead of shipping a 404. Run after `astro build`, from `docs/astro/`:
*
* node scripts/verify-doc-links.mjs
*
* Redirect pages count as real destinations: an old address stays valid as long
* as the build still emits its redirect stub.
*/
import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join, relative, sep } from 'node:path';
const here = dirname(fileURLToPath(import.meta.url));
const DIST = join(here, '..', 'dist');
const BASE = '/docs';
/** Root-relative paths that legitimately sit outside the docs base. */
const EXTERNAL_ROOTS = ['/favicon', '/_astro/', '/pagefind/', '/sitemap'];
/** Every .html file the build emitted. */
function htmlFiles(dir) {
const out = [];
for (const e of readdirSync(dir, { withFileTypes: true })) {
const p = join(dir, e.name);
if (e.isDirectory()) out.push(...htmlFiles(p));
else if (e.name.endsWith('.html')) out.push(p);
}
return out;
}
/** The file a `/docs/...` path is served from, or null if nothing emits it. */
function pageFile(urlPath) {
const rel = urlPath.slice(BASE.length).replace(/^\/+/, '').replace(/\/+$/, '');
// The Doxygen C++ API is merged in by the site build script, not by Astro.
if (rel.startsWith('api/')) return 'external';
const asDir = join(DIST, ...rel.split('/'), 'index.html');
if (existsSync(asDir)) return asDir;
const asFile = join(DIST, ...rel.split('/'));
if (existsSync(asFile) && statSync(asFile).isFile()) return asFile;
return null;
}
/** Heading ids a page offers, so `#anchor` links are checked too — a heading's
* slug is not guessable by hand ("Bodies & colliders" is `bodies--colliders`,
* with two hyphens), which makes hand-written anchors quietly wrong. */
const idCache = new Map();
function idsOf(file) {
let ids = idCache.get(file);
if (!ids) {
ids = new Set();
const html = readFileSync(file, 'utf8');
for (const m of html.matchAll(/\sid="([^"]+)"/g)) ids.add(m[1]);
idCache.set(file, ids);
}
return ids;
}
function main() {
if (!existsSync(DIST)) {
console.error(`no build to check at ${DIST} — run \`npm run build\` first`);
process.exit(1);
}
const pages = htmlFiles(DIST);
const dead = new Map(); // target -> pages that link to it
let checked = 0;
for (const page of pages) {
// The generated TypeScript API is TypeDoc's own link graph, not ours — in
// every locale it gets mirrored into (hence a segment test, not a prefix).
if (relative(DIST, page).split(sep).includes('api-ts')) continue;
const html = readFileSync(page, 'utf8');
// Every page on this site lives under /docs. A root-relative href that does
// not is a typo that no amount of resolving will fix — `/zh-cn/docs/x/` for
// `/docs/zh-cn/x/` renders as a link off the site, and checking only
// well-formed ones is how two of those survived.
for (const m of html.matchAll(/href="(\/(?!docs\/)[^"?:]*)"/g)) {
const target = m[1];
if (target === '/' || EXTERNAL_ROOTS.some((p) => target.startsWith(p))) continue;
checked++;
const problem = `${target} (root-relative, but every page is under ${BASE})`;
if (!dead.has(problem)) dead.set(problem, new Set());
dead.get(problem).add(relative(DIST, page).replaceAll(sep, '/'));
}
for (const m of html.matchAll(/href="(\/docs\/[^"?]*)"/g)) {
const [path, fragment] = m[1].split('#');
checked++;
const file = pageFile(path);
let problem = null;
if (!file) problem = m[1];
else if (fragment && file !== 'external' && !idsOf(file).has(decodeURIComponent(fragment))) {
problem = `${path}#${fragment} (page exists, no such heading)`;
}
if (!problem) continue;
if (!dead.has(problem)) dead.set(problem, new Set());
dead.get(problem).add(relative(DIST, page).replaceAll(sep, '/'));
}
}
console.log(`checked ${checked} internal links across ${pages.length} pages`);
if (dead.size === 0) {
console.log('all internal links resolve');
return;
}
console.error(`\n${dead.size} dead link target(s):`);
for (const [target, from] of dead) {
console.error(` ${target}`);
for (const f of [...from].slice(0, 5)) console.error(` linked from ${f}`);
if (from.size > 5) console.error(` …and ${from.size - 5} more`);
}
process.exit(1);
}
main();