3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// Checks that every relative link in the markdown and HTML files points at a file.
// Usage: node scripts/check-links.mjs the repository checkout
// node scripts/check-links.mjs --package the packed npm archive, as a coding agent reads it in node_modules
// A link resolves against its own folder, the root, `site/`, `public/` or `docs/`, because the site serves
// the pages, the docs and the public folder from one origin. The archive has no `public/`, so only the other bases apply.
import { execFileSync, execSync } from 'node:child_process';
import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, relative, resolve } from 'node:path';
const skippedFolders = new Set(['node_modules', '.git', '.claude', 'build', 'dist', 'artifacts', 'coverage']);
const linkPattern = /(?:\]\(|href="|src=")([^)"#\s]+)/g;
// `release.json` is generated by `npm run prepare:release`. `./main.js` is an example path inside the guide.
const knownGeneratedLinks = new Set(['/release.json', '/changelog.json', './main.js']);
const externalPattern = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
// Files git tracks or would track. Git-ignored build output such as `public/guide.md` is not checked.
// Returns null outside a git checkout (the packed archive), where every file is checked.
function listNonIgnoredFiles(root) {
try {
const output = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
return new Set(output.split('\0').filter(Boolean).map((name) => resolve(root, name)));
} catch {
return null;
}
}
function collectFiles(folder, found) {
for (const name of readdirSync(folder)) {
if (skippedFolders.has(name)) continue;
const path = join(folder, name);
if (statSync(path).isDirectory()) collectFiles(path, found);
else if (/\.(md|html)$/.test(name)) found.push(path);
}
return found;
}
function linkResolves(root, file, link) {
const withoutQuery = link.split('?')[0];
const rootBases = [root, join(root, 'site'), join(root, 'public'), join(root, 'docs')];
const targets = withoutQuery.startsWith('/')
? rootBases.map((base) => join(base, withoutQuery))
: [resolve(dirname(file), withoutQuery), ...rootBases.map((base) => join(base, withoutQuery))];
return targets.some((target) => [target, `${target}.html`, `${target}.md`].some((candidate) => existsSync(candidate)));
}
function findBrokenLinks(root) {
const visible = listNonIgnoredFiles(root);
const files = collectFiles(root, []).filter((file) => !visible || visible.has(resolve(file)));
const broken = [];
for (const file of files) {
const text = readFileSync(file, 'utf8');
for (const match of text.matchAll(linkPattern)) {
const link = match[1];
if (externalPattern.test(link) || knownGeneratedLinks.has(link)) continue;
if (!linkResolves(root, file, link)) broken.push(`${relative(root, file)} -> ${link}`);
}
}
return { checked: files.length, broken };
}
// Packs without lifecycle scripts, so run `npm run prepare:release` first when `build/` is stale.
function unpackArchive(workFolder) {
const packed = JSON.parse(execSync(`npm pack --ignore-scripts --json --pack-destination "${workFolder}"`, { encoding: 'utf8' }));
const entry = Array.isArray(packed) ? packed[0] : Object.values(packed)[0];
// A relative name with `cwd` keeps GNU tar from reading `C:` in a Windows path as a host name.
execFileSync('tar', ['-xzf', entry.filename], { cwd: workFolder });
return join(workFolder, 'package');
}
const checkArchive = process.argv.includes('--package');
let root = process.cwd();
let workFolder;
if (checkArchive) {
workFolder = mkdtempSync(join(tmpdir(), 'crucible-links-'));
root = unpackArchive(workFolder);
}
const { checked, broken } = findBrokenLinks(root);
if (workFolder) rmSync(workFolder, { recursive: true, force: true });
console.log(`${checked} files checked${checkArchive ? ' in the packed archive' : ''}, ${broken.length} broken links`);
for (const entry of broken) console.log(entry);
process.exitCode = broken.length === 0 ? 0 : 1;