Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

3.5 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, `public/` or `docs/`, because the site serves
// 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;

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, '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 files = collectFiles(root, []);
  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(), '67js-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;