Skip to content

3D engine that AI agents drive

5.2 KB
Raw Blame
// Checks what the site serves, not what the repository holds. Run `npm run prepare:release` first.
// 1. Every link in public/llms.txt and in the guides copied into public/ must point at a file the site serves
//    (public/ plus the pages in site/). `check-links.mjs` resolves against docs/, so it misses a guide the build never copies.
// 2. Every `/releases/<x.y.z>/` link in those files and in the learn pages must name a release that public/releases holds.
// Usage: node scripts/check-published-site.mjs
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { publishedDocuments } from './published-documents.mjs';
import { join, posix, relative } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';

const SITE_ORIGIN = 'https://crucible.codepawl.com';
const linkPattern = /(?:\]\(|href="|src="|\]: ?)(<?[^)"#\s>]+)/g;
const releaseLinkPattern = /\/releases\/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\//g;
const externalPattern = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
// Written by `prepare:release`, `build-pack-index.mjs` or the browser at run time, and an example path in the guide.
const generatedLinks = new Set(['/release.json', '/changelog.json', '/api-reference.json', './main.js']);

// Only the guides the build copies count. A stale file from an older build is not served.
function publishedTextNames() {
  return ['llms.txt', 'guide.md', 'gltf.md', ...publishedDocuments.filter((document) => document.endsWith('.md'))];
}

function publishedTextFiles(root) {
  return publishedTextNames().map((name) => join(root, 'public', name)).filter((path) => existsSync(path));
}

// A file the build should have written but did not leaves nothing to scan, which must not read as zero problems.
export function findMissingPublishedFiles(root) {
  return publishedTextNames()
    .filter((name) => !existsSync(join(root, 'public', name)))
    .map((name) => `public/${name} is missing. Run \`npm run prepare:release\` to write it.`);
}

// Example code in a guide names paths of the reader's own project, such as /src/main.js.
function withoutCodeBlocks(text) {
  return text.replace(/```[\s\S]*?```/g, '');
}

function learnPages(root) {
  const folder = join(root, 'docs/learn');
  if (!existsSync(folder)) return [];
  return readdirSync(folder).filter((name) => name.endsWith('.md')).map((name) => join(folder, name));
}

// The path a link asks the site for, or null for a link that leaves the site.
function sitePathOf(link) {
  if (link === SITE_ORIGIN) return '/';
  // The trailing slash keeps https://crucible.codepawl.com.other.host from counting as this site.
  if (link.startsWith(`${SITE_ORIGIN}/`)) return link.slice(SITE_ORIGIN.length);
  if (externalPattern.test(link)) return null;
  return link;
}

function siteServes(root, sitePath) {
  const clean = sitePath.split('?')[0];
  if (clean === '/' || clean === '') return true;
  const relativePath = clean.replace(/^\/+/, '');
  const candidates = [relativePath, `${relativePath}.html`, `${relativePath}.md`];
  // Pages in site/ are built to the output root under their own file name.
  return candidates.some((candidate) => existsSync(join(root, 'public', candidate)) || existsSync(join(root, 'site', candidate)));
}

export function findUnpublishedLinks(root) {
  const missing = [];
  for (const file of publishedTextFiles(root)) {
    const text = withoutCodeBlocks(readFileSync(file, 'utf8'));
    for (const match of text.matchAll(linkPattern)) {
      const link = match[1].replace(/^</, '');
      if (generatedLinks.has(link)) continue;
      const sitePath = sitePathOf(link);
      if (sitePath === null) continue;
      // A relative link is read from the served location of the file, which is the site root.
      const served = sitePath.startsWith('/') ? sitePath : posix.normalize(`/${sitePath}`);
      if (!siteServes(root, served)) missing.push(`${relative(root, file)} -> ${link}`);
    }
  }
  return missing;
}

export function findMissingReleaseLinks(root) {
  const missing = [];
  const files = [...publishedTextFiles(root), ...learnPages(root)];
  for (const file of files) {
    const text = readFileSync(file, 'utf8');
    for (const match of text.matchAll(releaseLinkPattern)) {
      if (!existsSync(join(root, 'public/releases', match[1]))) missing.push(`${relative(root, file)} -> /releases/${match[1]}/ is not in public/releases`);
    }
  }
  return missing;
}

const isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;

if (isMain) {
  const root = fileURLToPath(new URL('..', import.meta.url));
  if (!existsSync(join(root, 'public/release.json'))) {
    console.error('public/release.json is missing. Run `npm run prepare:release` first.');
    process.exit(1);
  }
  const problems = [...findMissingPublishedFiles(root), ...findUnpublishedLinks(root), ...findMissingReleaseLinks(root)];
  console.log(`${problems.length} missing files, or links to files or releases the site does not serve`);
  for (const problem of problems) console.log(problem);
  if (problems.length > 0) {
    console.log('Fix: add the guide to scripts/published-documents.mjs or link it on GitHub instead; for a release link use <version> and read it from release.json.');
  }
  process.exitCode = problems.length === 0 ? 0 : 1;
}