Skip to content

3D engine that AI agents drive

4.2 KB
Raw Blame
// 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;