@twango/twiki 0.0.0-stage → 0.1.1

package/site/tooling/build.ts

@@ -0,0 +1,407 @@
+import { resolveProject } from './lib/project-config';
+import { mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { publicAssetManifest } from './lib/public-assets';
+import { buildMode, runEditionBuilds } from './lib/edition-builds';
+
+const site = path.resolve(import.meta.dir, '..');
+const options = process.argv.slice(2);
+if (
+	options.length > 1 ||
+	options.some((value) => !['--app', '--content', '--static'].includes(value))
+)
+	throw new Error('Use --app, --content, --static, or no option for the complete SSR build');
+if (options[0] === '--static') {
+	process.env.VITE_STATIC_EXPORT = 'true';
+	delete process.env.WISCONSIN_APP_STATIC_DIR;
+	delete process.env.WISCONSIN_SKIP_CONTENT;
+	const mode = buildMode();
+	if (mode !== 'serial') await isolatedBuild(mode);
+	else serialBuild();
+} else await runtimeBuild(options[0] === '--app');
+
+async function command(
+	binary: string,
+	args: string[],
+	environment: NodeJS.ProcessEnv,
+	signal: AbortSignal
+) {
+	signal.throwIfAborted();
+	const child = spawn(binary, args, {
+		cwd: site,
+		env: environment,
+		stdio: 'inherit',
+		detached: process.platform !== 'win32'
+	});
+	let stopping: Promise<void> | undefined;
+	const stop = () => {
+		if (stopping || !child.pid) return;
+		const send = (kind: NodeJS.Signals) => {
+			try {
+				if (process.platform === 'win32') child.kill(kind);
+				else process.kill(-child.pid!, kind);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error;
+			}
+		};
+		send('SIGTERM');
+		stopping = new Promise((resolve) =>
+			setTimeout(() => {
+				send('SIGKILL');
+				resolve();
+			}, 2000)
+		);
+	};
+	signal.addEventListener('abort', stop, { once: true });
+	try {
+		await new Promise<void>((resolve, reject) => {
+			child.once('error', reject);
+			child.once('close', (code, killed) =>
+				code === 0 ? resolve() : reject(new Error(`Build command failed (${code ?? killed})`))
+			);
+		});
+	} finally {
+		await stopping;
+		signal.removeEventListener('abort', stop);
+	}
+	signal.throwIfAborted();
+}
+
+async function runtimeBuild(appOnly: boolean) {
+	const started = performance.now();
+	const abort = new AbortController();
+	const interrupt = () => abort.abort(new Error('Build interrupted'));
+	process.on('SIGINT', interrupt);
+	process.on('SIGTERM', interrupt);
+	let staging: string | undefined;
+	try {
+		const app = await import('./lib/application-cache');
+		const { captureAssetInventory, assetContentType, validateAssetInventory } =
+			await import('./lib/deployment-manifest');
+		const { captureAssetHashes, flushAssetHashCache } = await import('./lib/asset-hash-cache');
+		const { prepareWorker, loadPreparedWorker, buildDeploymentSnapshot } =
+			await import('./lib/deployment-prepare');
+		const { readDeploymentConfig } = await import('./lib/deployment-config');
+		const packaging = await import('./lib/runtime-packaging');
+		const { contentInputFingerprint } = await import('./lib/dev-state');
+		const environment = app.applicationEnvironment();
+		const identity = app.applicationCacheIdentity(site, environment);
+		const contentRepo = resolveProject(site).root;
+		const contentInputs = appOnly ? '' : contentInputFingerprint(contentRepo, identity.identity);
+		let cached = app.loadApplicationCache(site, identity);
+		if (cached)
+			try {
+				validateAssetInventory(
+					JSON.parse(
+						readFileSync(path.join(cached.directory, 'kit/application-assets.json'), 'utf8')
+					),
+					identity.identity
+				);
+			} catch {
+				cached = undefined;
+			}
+		const appStarted = performance.now();
+		if (!cached) {
+			mkdirSync(path.join(site, 'build'), { recursive: true });
+			const temporary = mkdtempSync(path.join(site, 'build/.application-build-'));
+			const previous = path.join(temporary, 'previous');
+			const output = path.join(site, 'build/.svelte-kit');
+			let moved = false,
+				preserve = false;
+			try {
+				app.prepareApplicationStatic(site, path.join(temporary, 'static'));
+				try {
+					renameSync(output, previous);
+					moved = true;
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+				}
+				await command(
+					'bun',
+					['x', 'vite', 'build'],
+					{
+						...environment,
+						WISCONSIN_APP_STATIC_DIR: path.join(temporary, 'static'),
+						WISCONSIN_APPLICATION_VERSION: identity.applicationVersion
+					},
+					abort.signal
+				);
+				await prepareWorker(site, path.join(output, 'prepared-worker'));
+				const inventory = await captureAssetInventory(
+					path.join(output, 'cloudflare'),
+					identity.identity,
+					{
+						resolveAsset: async (absolute, filename) => ({
+							...captureAssetHashes(site, absolute),
+							contentType: assetContentType(filename)
+						})
+					}
+				);
+				writeFileSync(path.join(output, 'application-assets.json'), JSON.stringify(inventory));
+				if (app.applicationCacheIdentity(site, environment).identity !== identity.identity)
+					throw new Error('Application inputs changed during compilation');
+				cached = app.saveApplicationCache(site, identity);
+			} finally {
+				rmSync(output, { recursive: true, force: true });
+				if (moved)
+					try {
+						renameSync(previous, output);
+					} catch (error) {
+						preserve = true;
+						throw new Error('Previous application output preserved for recovery', { cause: error });
+					}
+				if (!preserve) rmSync(temporary, { recursive: true, force: true });
+			}
+			console.log(
+				`build: application compiled in ${((performance.now() - appStarted) / 1000).toFixed(2)}s`
+			);
+		} else
+			console.log(
+				`build: application reused in ${((performance.now() - appStarted) / 1000).toFixed(2)}s`
+			);
+		abort.signal.throwIfAborted();
+		if (appOnly) {
+			flushAssetHashCache(site);
+			console.log(`build: app completed in ${((performance.now() - started) / 1000).toFixed(2)}s`);
+			return;
+		}
+		mkdirSync(path.join(site, 'build'), { recursive: true });
+		staging = mkdtempSync(path.join(site, 'build/.runtime-build-'));
+		const product = path.join(staging, 'kit');
+		app.stageApplication(cached!, product);
+		const appInventory = validateAssetInventory(
+			JSON.parse(readFileSync(path.join(product, 'application-assets.json'), 'utf8')),
+			identity.identity
+		);
+		const editions: import('./lib/runtime-packaging').CapturedEdition[] = [];
+		for (const edition of ['public', 'full'] as const) {
+			const editionStarted = performance.now();
+			const selected = {
+				...environment,
+				WISCONSIN_CONTENT_REPO: contentRepo,
+				VITE_PUBLIC_EDITION: String(edition === 'public')
+			};
+			await command('bun', ['tooling/prepare.ts'], selected, abort.signal);
+			const search = path.join(staging, `search-${edition}`);
+			await command('node', ['tooling/search.js', search], selected, abort.signal);
+			editions.push(
+				packaging.captureRuntimeEdition(site, edition, path.join(staging, edition), search)
+			);
+			console.log(
+				`build: ${edition} content completed in ${((performance.now() - editionStarted) / 1000).toFixed(2)}s`
+			);
+		}
+		if (
+			app.applicationCacheIdentity(site, environment).identity !== identity.identity ||
+			contentInputFingerprint(contentRepo, identity.identity) !== contentInputs
+		)
+			throw new Error(
+				'Source or course content changed during the build; refusing mixed snapshots'
+			);
+		abort.signal.throwIfAborted();
+		const packed = packaging.packageRuntime(
+			site,
+			path.join(product, 'cloudflare'),
+			identity.applicationVersion,
+			editions,
+			appInventory
+		);
+		const config = readDeploymentConfig(site);
+		const worker = await loadPreparedWorker(path.join(product, 'prepared-worker'), config);
+		writeFileSync(
+			path.join(product, 'deployment.json'),
+			JSON.stringify(buildDeploymentSnapshot(worker, packed.inventory, config, packed.provenance))
+		);
+		if (
+			app.applicationCacheIdentity(site, environment).identity !== identity.identity ||
+			contentInputFingerprint(contentRepo, identity.identity) !== contentInputs
+		)
+			throw new Error(
+				'Source or course content changed during packaging; refusing mixed snapshots'
+			);
+		abort.signal.throwIfAborted();
+		packaging.promoteRuntimeProduct(site, product);
+		flushAssetHashCache(site);
+		console.log(
+			`publishing: ${packed.publicRoutes} public SSR routes; edition data remains private`
+		);
+		console.log(`build: all completed in ${((performance.now() - started) / 1000).toFixed(2)}s`);
+	} finally {
+		if (staging) rmSync(staging, { recursive: true, force: true });
+		process.removeListener('SIGINT', interrupt);
+		process.removeListener('SIGTERM', interrupt);
+	}
+}
+
+function serialBuild() {
+	const output = path.join(site, 'build/.svelte-kit/cloudflare');
+	const staged = path.join(site, 'build/generated/public-site');
+	const manifestPath = path.join(site, 'build/generated/public-assets.json');
+	let publicAssets: Record<string, string> = {};
+	mkdirSync(path.dirname(manifestPath), { recursive: true });
+	writeFileSync(manifestPath, '{}');
+	rmSync(staged, { recursive: true, force: true });
+
+	const started = performance.now();
+
+	function build(publicEdition: boolean) {
+		const started = performance.now();
+		const result = spawnSync('bun', ['x', 'vite', 'build'], {
+			cwd: site,
+			stdio: 'inherit',
+			env: {
+				...process.env,
+				NODE_ENV: process.env.NODE_ENV ?? 'production',
+				VITE_PUBLIC_EDITION: String(publicEdition)
+			}
+		});
+		if (result.status !== 0)
+			throw new Error(`${publicEdition ? 'Public' : 'Full'} build failed`, {
+				cause: result.error
+			});
+		console.log(
+			`build: ${publicEdition ? 'public' : 'full'} completed in ${((performance.now() - started) / 1000).toFixed(2)}s`
+		);
+	}
+
+	{
+		build(true);
+		const pages = JSON.parse(
+			readFileSync(path.join(site, 'build/generated/public-routes.json'), 'utf8')
+		);
+		const content = JSON.parse(
+			readFileSync(path.join(site, 'build/generated/content-manifest.json'), 'utf8')
+		);
+		for (const asset of content.htmlAssets) {
+			pages[`/${asset}`] = `${asset}.html`;
+			pages[`/${asset}.html`] = `${asset}.html`;
+		}
+		const fileEntries = JSON.parse(
+			readFileSync(path.join(site, 'src/lib/generated/file-entries.json'), 'utf8')
+		);
+		publicAssets = publicAssetManifest(output, pages, fileEntries);
+		// Both editions live on the same filesystem. Move the public tree aside
+		// before the full adapter recreates its output, without copying every asset.
+		renameSync(output, staged);
+		console.log(
+			`publishing: ${Object.keys(pages).length} public pages; ${fileEntries.length} file routes share one shell; history remains private`
+		);
+	}
+	build(false);
+	renameSync(staged, path.join(output, '_published'));
+	writeFileSync(manifestPath, JSON.stringify(publicAssets));
+
+	console.log(`build: all completed in ${((performance.now() - started) / 1000).toFixed(2)}s`);
+}
+
+async function isolatedBuild(mode: 'parallel' | 'isolated-serial') {
+	const started = performance.now();
+	const abort = new AbortController();
+	const interrupt = () => abort.abort(new Error('Build interrupted by SIGINT'));
+	const terminate = () => abort.abort(new Error('Build interrupted by SIGTERM'));
+	process.on('SIGINT', interrupt);
+	process.on('SIGTERM', terminate);
+	let workspace:
+		| { publicSite: string; fullSite: string; cleanup: () => void | Promise<void> }
+		| undefined;
+	let cleanupSeconds = 0;
+	let succeeded = false;
+	try {
+		const [
+			{ createBuildWorkspaces, mergeBuildCaches },
+			{ assembleBuilds },
+			{ applicationVersion },
+			{ contentInputFingerprint }
+		] = await Promise.all([
+			import('./lib/build-workspace'),
+			import('./lib/build-assembly'),
+			import('./lib/app-version.js'),
+			import('./lib/dev-state')
+		]);
+		const contentRepo = resolveProject(site).root;
+		const versionEnvironment: NodeJS.ProcessEnv = {
+			...process.env,
+			NODE_ENV: process.env.NODE_ENV ?? 'production'
+		};
+		delete versionEnvironment.WISCONSIN_APPLICATION_VERSION;
+		const version = applicationVersion(site, versionEnvironment);
+		const contentInputs = contentInputFingerprint(contentRepo, version);
+		abort.signal.throwIfAborted();
+		workspace = await createBuildWorkspaces(site, contentRepo);
+		abort.signal.throwIfAborted();
+		const benchmarks = path.join(site, 'build/benchmarks');
+		mkdirSync(benchmarks, { recursive: true, mode: 0o700 });
+		const logDirectory = mkdtempSync(path.join(benchmarks, 'edition-'));
+		const setupSeconds = (performance.now() - started) / 1000;
+		console.log(`build: ${mode} setup in ${setupSeconds.toFixed(2)}s; logs: ${logDirectory}`);
+		const buildStarted = performance.now();
+		const editions = await runEditionBuilds(workspace, {
+			mode,
+			contentRepo,
+			applicationVersion: version,
+			logDirectory,
+			signal: abort.signal
+		});
+		const buildSpanSeconds = (performance.now() - buildStarted) / 1000;
+		abort.signal.throwIfAborted();
+		const validationStarted = performance.now();
+		if (
+			applicationVersion(site, versionEnvironment) !== version ||
+			contentInputFingerprint(contentRepo, version) !== contentInputs
+		)
+			throw new Error(
+				'Source or course content changed during the build; refusing to assemble mixed editions'
+			);
+		const validationSeconds = (performance.now() - validationStarted) / 1000;
+		const mergeStarted = performance.now();
+		mergeBuildCaches(
+			workspace.publicSite,
+			workspace.fullSite,
+			path.join(workspace.fullSite, 'build/generated/cache')
+		);
+		const cacheMergeSeconds = (performance.now() - mergeStarted) / 1000;
+		const assemblyStarted = performance.now();
+		const publication = assembleBuilds(site, workspace.publicSite, workspace.fullSite);
+		const assemblySeconds = (performance.now() - assemblyStarted) / 1000;
+		console.log(
+			`publishing: ${publication.publicPages} public pages; ${publication.fileRoutes} file routes share one shell; history remains private`
+		);
+		const cleanupStarted = performance.now();
+		await workspace.cleanup();
+		workspace = undefined;
+		cleanupSeconds = (performance.now() - cleanupStarted) / 1000;
+		const totalSeconds = (performance.now() - started) / 1000;
+		console.log(`build: all completed in ${totalSeconds.toFixed(2)}s`);
+		console.log(
+			`build: metrics ${JSON.stringify({
+				mode,
+				setupSeconds,
+				...editions,
+				buildSpanSeconds,
+				validationSeconds,
+				cacheMergeSeconds,
+				assemblySeconds,
+				cleanupSeconds,
+				totalSeconds,
+				logs: {
+					public: path.join(logDirectory, 'public.log'),
+					full: path.join(logDirectory, 'full.log')
+				}
+			})}`
+		);
+		succeeded = true;
+	} finally {
+		if (workspace) {
+			const cleanupStarted = performance.now();
+			await workspace.cleanup();
+			cleanupSeconds = (performance.now() - cleanupStarted) / 1000;
+		}
+		process.removeListener('SIGINT', interrupt);
+		process.removeListener('SIGTERM', terminate);
+		if (!succeeded)
+			console.log(
+				`build: ${mode} failed after ${((performance.now() - started) / 1000).toFixed(2)}s; cleanup ${cleanupSeconds.toFixed(2)}s`
+			);
+	}
+}

package/site/tooling/cache.ts

@@ -0,0 +1,133 @@
+import { execFileSync } from 'node:child_process';
+import {
+	appendFileSync,
+	cpSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { compilerCacheFiles } from './lib/cache-selection';
+
+const mode = process.argv[2];
+if (mode === 'plan' || mode === 'save-products' || mode === 'restore-products') {
+	const { planProductCaches, transferProductCaches } = await import('./lib/product-cache');
+	const { resolve } = await import('node:path');
+	const options: import('./lib/product-cache').ProductOptions = {};
+	let planFile: string | undefined;
+	for (let i = 3; i < process.argv.length; i++) {
+		const argument = process.argv[i];
+		if (argument === '--restore') options.restore = true;
+		else if (argument === '--group') options.group = process.argv[++i];
+		else if (argument === '--namespace') {
+			const namespace = process.argv[++i];
+			if (!['production', 'benchmark'].includes(namespace))
+				throw new Error('Invalid product namespace');
+			options.namespace = namespace as import('./lib/product-cache').ProductNamespace;
+		} else if (argument === '--kind') {
+			const kind = process.argv[++i];
+			if (!['global', 'course', 'search', 'application'].includes(kind))
+				throw new Error('Invalid product kind');
+			options.kind = kind as import('./lib/product-cache').ProductKind;
+		} else if (argument === '--plan-file') planFile = process.argv[++i];
+		else throw new Error('Invalid product-cache argument');
+	}
+	const result =
+		mode === 'plan'
+			? await planProductCaches(process.cwd(), options)
+			: await transferProductCaches(
+					process.cwd(),
+					mode === 'save-products' ? 'save' : 'restore',
+					process.env.BUILD_CACHE_KEY,
+					options
+				);
+	const json = JSON.stringify(result);
+	if (planFile) {
+		mkdirSync(path.dirname(resolve(planFile)), { recursive: true });
+		writeFileSync(resolve(planFile), json + '\n', { mode: 0o600 });
+	} else console.log(json);
+	process.exit(0);
+}
+if (mode !== 'restore' && mode !== 'save') throw new Error('Expected restore or save');
+const secret = process.env.BUILD_CACHE_KEY;
+const cache = path.resolve('build/generated/cache');
+const encrypted = path.resolve('build/generated/compiler-cache.gpg');
+if (!secret) {
+	console.log(
+		mode === 'restore'
+			? 'BUILD_CACHE_KEY is missing; building cold'
+			: 'BUILD_CACHE_KEY is missing; skipping cache save'
+	);
+	process.exit(0);
+}
+if (mode === 'restore' && !existsSync(encrypted)) {
+	console.log('No compatible cache archive was restored; building cold');
+	process.exit(0);
+}
+
+const temporary = mkdtempSync(path.join(tmpdir(), 'wisconsin-cache-'));
+const archive = path.join(temporary, 'cache.tar.gz');
+const status = path.join(temporary, 'status');
+const env = { ...process.env, GNUPGHOME: temporary };
+const run = (command: string, args: string[]) =>
+	execFileSync(command, args, {
+		env,
+		input: command === 'gpg' ? secret + '\n' : undefined,
+		stdio: 'pipe'
+	});
+const gpg = [
+	'--batch',
+	'--yes',
+	'--pinentry-mode',
+	'loopback',
+	'--no-symkey-cache',
+	'--passphrase-fd',
+	'0'
+];
+
+try {
+	if (mode === 'restore') {
+		run('gpg', [...gpg, '--status-file', status, '--output', archive, '--decrypt', encrypted]);
+		if (!readFileSync(status, 'utf8').split('\n').includes('[GNUPG:] GOODMDC'))
+			throw new Error('Cache integrity was not verified');
+		const staged = path.join(temporary, 'unpacked');
+		mkdirSync(staged);
+		run('tar', ['-xzf', archive, '-C', staged, '--no-same-owner']);
+		mkdirSync(cache, { recursive: true });
+		cpSync(staged, cache, { recursive: true });
+		console.log('Compiler cache archive restored; each stage validates its own inputs');
+	} else {
+		const files = compilerCacheFiles(cache);
+		const list = path.join(temporary, 'files');
+		writeFileSync(list, files.map((file) => file + '\0').join(''));
+		run('tar', ['-czf', archive, '-C', cache, '--null', '--files-from', list]);
+		run('gpg', [
+			...gpg,
+			'--symmetric',
+			'--cipher-algo',
+			'AES256',
+			'--compress-algo',
+			'none',
+			'--output',
+			encrypted,
+			archive
+		]);
+		if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, 'ready=true\n');
+		console.log(`Compiler cache encrypted (${files.length} current files)`);
+	}
+} catch {
+	console.log(
+		mode === 'restore'
+			? 'Cache could not be verified; building cold'
+			: 'Cache encryption failed; skipping cache save'
+	);
+} finally {
+	try {
+		run('gpgconf', ['--kill', 'gpg-agent']);
+	} catch {}
+	rmSync(temporary, { recursive: true, force: true });
+}

package/site/tooling/check-diagrams.ts

@@ -0,0 +1,164 @@
+import { resolveProject } from './lib/project-config';
+import { markdownFiles } from './lib/markdown-files';
+export { markdownFiles } from './lib/markdown-files';
+import { preserveCurrency } from './lib/currency';
+import { stripObsidianComments } from './lib/comments';
+/** Validate Markdown math and render Mermaid with the site's installed engines. */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import { visit } from 'unist-util-visit';
+import katex, { type KatexOptions } from 'katex';
+import { chromium, type Browser, type Page } from '@playwright/test';
+
+export interface Expression {
+	kind: 'math' | 'mermaid';
+	value: string;
+	line: number;
+	column: number;
+	display: boolean;
+}
+
+export function expressions(markdown: string): Expression[] {
+	// Keep original line/column positions while excluding metadata and OFM comments.
+	const blank = (s: string) => s.replace(/[^\r\n]/g, ' ');
+	const source = stripObsidianComments(
+		markdown.replace(/^---\r?\n[\s\S]*?\r?\n(?:---|\.\.\.)(?:\r?\n|$)/, blank),
+		true
+	);
+	const tree = unified().use(remarkParse).use(remarkGfm).use(remarkMath).parse(source);
+	preserveCurrency(source)(tree);
+	const result: Expression[] = [];
+	visit(tree, (node) => {
+		if (
+			node.type === 'math' ||
+			node.type === 'inlineMath' ||
+			(node.type === 'code' && node.lang === 'mermaid')
+		) {
+			result.push({
+				kind: node.type === 'code' ? 'mermaid' : 'math',
+				value: node.value,
+				line: node.position?.start.line ?? 1,
+				column: node.position?.start.column ?? 1,
+				display: node.type === 'math'
+			});
+		}
+	});
+	return result;
+}
+
+export function checkMath(
+	expression: Expression,
+	macros: NonNullable<KatexOptions['macros']> = {}
+): void {
+	katex.renderToString(expression.value, {
+		throwOnError: true,
+		displayMode: expression.display,
+		output: 'html',
+		macros,
+		strict: 'ignore' // match the site's permissive rendering of supported extensions
+	});
+}
+
+export async function mermaidPage(browser: Browser): Promise<Page> {
+	const page = await browser.newPage();
+	// Notes need no network access to render. Keep any diagram links local/inert.
+	await page.route('**/*', (route) => route.abort());
+	await page.setContent('<!doctype html><html><body></body></html>');
+	const entry = import.meta.resolve('mermaid');
+	await page.addScriptTag({
+		path: path.join(path.dirname(fileURLToPath(entry)), 'mermaid.min.js')
+	});
+	return page;
+}
+
+export async function checkMermaid(page: Page, source: string): Promise<void> {
+	await page.evaluate(async (text) => {
+		const mermaid = (window as unknown as { mermaid: typeof import('mermaid').default }).mermaid;
+		mermaid.initialize({ startOnLoad: false, securityLevel: 'loose', theme: 'base' });
+		await mermaid.parse(text);
+		const { svg } = await mermaid.render('validation-diagram', text);
+		if (!svg.includes('<svg')) throw new Error('Mermaid produced no SVG');
+		document.body.replaceChildren();
+	}, source);
+}
+
+async function main() {
+	const args = process.argv.slice(2);
+	if (args.includes('--help')) {
+		console.log(
+			'Usage: bun run check:diagrams [Markdown files or Git directories...]\nDefaults to all content, including untracked non-ignored notes.'
+		);
+		return;
+	}
+	const content = resolveProject().contentDir;
+	const files = markdownFiles(args.length ? args : [content]);
+	if (!files.length) throw new Error('No Markdown files found');
+	let math = 0,
+		mermaid = 0,
+		failures = 0;
+	let browser: Browser | undefined;
+	let page: Page | undefined;
+	try {
+		for (const file of files) {
+			const macros: NonNullable<KatexOptions['macros']> = {};
+			for (const expression of expressions(readFileSync(file, 'utf8'))) {
+				if (expression.kind === 'mermaid' && !browser) {
+					// Browser setup failures are infrastructure errors, not errors in every note.
+					browser = await chromium.launch();
+					page = await mermaidPage(browser);
+				}
+				try {
+					if (expression.kind === 'math') {
+						math++;
+						checkMath(expression, macros);
+					} else {
+						mermaid++;
+						// Bound pathological diagrams; replace the page after any failure.
+						let timer: ReturnType<typeof setTimeout> | undefined;
+						try {
+							await Promise.race([
+								checkMermaid(page!, expression.value),
+								new Promise<never>((_, reject) => {
+									timer = setTimeout(
+										() => reject(new Error('Mermaid render exceeded 15 seconds')),
+										15_000
+									);
+								})
+							]);
+						} finally {
+							clearTimeout(timer);
+						}
+					}
+				} catch (error) {
+					failures++;
+					const message = error instanceof Error ? error.message : String(error);
+					console.error(
+						`${path.relative(process.cwd(), file)}:${expression.line}:${expression.column}: ${expression.kind}: ${message.split(/\n\s+at /)[0].replace(/\s+/g, ' ')}`
+					);
+					if (expression.kind === 'mermaid') {
+						await page!.close();
+						page = await mermaidPage(browser!);
+					}
+				}
+			}
+		}
+	} finally {
+		await browser?.close();
+	}
+	console.log(
+		`Checked ${files.length} Markdown files: ${math} math expressions, ${mermaid} Mermaid diagrams; ${failures} errors.`
+	);
+	if (failures) process.exitCode = 1;
+}
+
+if (import.meta.main) {
+	main().catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	});
+}