Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

10.7 KB
Raw Blame
#!/usr/bin/env node
// Prove data/guards.json describes the guards this repo actually runs.
//
// Why this exists. The guard set is the only automated checkpoint here: there is
// no CI, so a check that is not wired into an unavoidable path (prebuild, the
// gate, the deploy chain, the pre-push hook) protects nothing. Two failure modes
// followed from that, and both had already happened when this was written:
//
//   1. Guards nobody could find. Eight working audit scripts sat in scripts/
//      with no npm script, discoverable only by reading the directory. One of
//      them said in its own header that it was "wired as npm run audit:console"
//      when no such script existed.
//   2. Documentation that claims a guard runs somewhere it does not. That is
//      worse than silence: a reader stops looking for the coverage they think
//      they already have.
//
// So this checks BOTH directions, and treats the stage column as a claim to be
// verified rather than prose:
//
//   a. Every registry entry names a script that exists and an npm script that
//      exists, so nothing in the registry is aspirational.
//   b. Every check-*/audit-* script on disk is registered, or matches an exempt
//      pattern that states WHY it is not a guard. New guards cannot land
//      undocumented.
//   c. Every `stages` claim is true against the real npm scripts: a guard
//      claiming "gate" must appear in the gate chain, "prebuild" in prebuild,
//      "build:gcp" in that chain, and "pre-push" in the installed hook template.
//      This is the check that keeps docs/guards.md and /guards honest, because
//      both render this file.
//
// Deliberately conservative: it never guesses that a script "looks like" a
// guard beyond the check-/audit- naming convention, because a checker that
// reports false positives gets switched off, which is worse than no check.
//
// Run: node scripts/audit-guards.mjs   (wired as `npm run audit:guards`)

import { readFileSync, readdirSync, existsSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

import { normalizeProof } from './lib/guard-proofs.mjs';

const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const read = (rel) => readFileSync(path.join(root, rel), 'utf8');

const registry = JSON.parse(read('data/guards.json'));
const pkg = JSON.parse(read('package.json'));
const scripts = pkg.scripts || {};

const failures = [];
const note = (msg) => failures.push(msg);

// Prose the /guards page and docs/guards.md render verbatim. It is held to the
// CLAUDE.md typography rule here rather than by scripts/check-rules.mjs, which
// skips this file: the proof fixtures beside this prose must contain the banned
// patterns verbatim in order to prove the guards catch them, so a line-level
// scan of the registry reports the evidence as the offense. Splitting it this
// way keeps the reader-facing text under the rule and the fixtures exempt.
const prose = [];

// The stage a guard claims maps to a concrete place its name must appear.
// `prebuild` runs raw `node scripts/x.mjs` calls rather than npm scripts, so it
// is matched on the script path; the rest are npm chains.
const STAGE_SOURCES = {
	prebuild: { kind: 'path', chain: scripts.prebuild || '', label: 'the prebuild chain' },
	gate: { kind: 'npm', chain: scripts.gate || '', label: 'the gate chain' },
	'build:gcp': { kind: 'npm', chain: scripts['build:gcp'] || '', label: 'the build:gcp chain' },
	// The submit step is its own stage: a guard that can only judge a finished
	// artifact runs after build:gcp has produced dist/ and before the upload.
	'deploy:submit': { kind: 'npm', chain: scripts['deploy:gcp:submit'] || '', label: 'the deploy:gcp:submit chain' },
	'pre-push': { kind: 'hook', label: 'the pre-push hook template' },
	manual: { kind: 'none', label: 'nothing (on demand)' },
};

const hookTemplate = existsSync(path.join(root, 'scripts/setup-git-hooks.mjs'))
	? read('scripts/setup-git-hooks.mjs')
	: '';

const declaredStageIds = new Set((registry.stages || []).map((s) => s.id));
for (const id of Object.keys(STAGE_SOURCES)) {
	if (!declaredStageIds.has(id)) note(`stage \`${id}\` is verifiable but data/guards.json never describes it for readers`);
}

const registered = new Set();

for (const g of registry.guards || []) {
	const where = `guard \`${g.id}\``;

	if (!g.script || !existsSync(path.join(root, g.script))) {
		note(`${where} names script \`${g.script}\`, which does not exist`);
		continue;
	}
	registered.add(g.script);

	const npmNames = [g.npm, ...(g.npmAliases || [])].filter(Boolean);
	if (!npmNames.length) {
		note(`${where} has no npm script, so nobody can discover or run it without reading scripts/`);
	}
	for (const name of npmNames) {
		if (!scripts[name]) {
			note(`${where} claims \`npm run ${name}\`, which is missing from package.json`);
			continue;
		}
		if (!scripts[name].includes(g.script)) {
			note(`${where}: \`npm run ${name}\` does not actually run ${g.script}`);
		}
	}

	for (const field of ['title', 'protects', 'why']) {
		if (!g[field] || !String(g[field]).trim()) {
			note(`${where} is missing \`${field}\`, which /guards and docs/guards.md both render`);
		}
		prose.push([`${where} \`${field}\``, g[field]]);
	}

	// Every guard states the violation it must reject. Without one the registry
	// entry is an unverifiable claim, which is the exact thing
	// scripts/prove-guards.mjs exists to eliminate.
	try {
		const proof = normalizeProof(g);
		prose.push([`${where} proof ${proof.kind === 'live' ? 'reason' : 'summary'}`, proof.summary ?? proof.reason]);
		// A json op edits a file in place, so the file must exist in the working
		// tree the proof sandbox mirrors. A deleted target turns the proof into a
		// crash at apply time (public/event.json was retired and its proof kept
		// editing it), and nothing else catches that before a prove run.
		if (proof.kind === 'mutation') {
			for (const op of proof.violation.json) {
				if (!existsSync(path.join(root, op.file))) {
					note(
						`${where} proof edits ${op.file} in place, but that file does not exist, so the fixture can never apply. ` +
							'Rewrite the violation as a `write` of a complete file, or restore the target.',
					);
				}
			}
		}
	} catch (err) {
		note(`${where}: ${err.message}. Every guard must declare the violation it rejects (see docs/guards.md).`);
	}

	const stages = g.stages || [];
	if (!stages.length) note(`${where} declares no stages, so a reader cannot tell when it runs`);
	for (const stage of stages) {
		const src = STAGE_SOURCES[stage];
		if (!src) {
			note(`${where} claims unknown stage \`${stage}\` (known: ${Object.keys(STAGE_SOURCES).join(', ')})`);
			continue;
		}
		if (src.kind === 'none') continue;
		let wired = false;
		if (src.kind === 'path') wired = src.chain.includes(g.script);
		else if (src.kind === 'npm') wired = npmNames.some((n) => new RegExp(`npm run ${n}(\\s|$|&)`).test(src.chain));
		else if (src.kind === 'hook') wired = hookTemplate.includes(path.basename(g.script));
		if (!wired) {
			note(
				`${where} claims it runs in \`${stage}\` but it is not in ${src.label}. ` +
					`Wire it there, or correct the stage in data/guards.json.`,
			);
		}
	}
}

// Reverse direction: a guard on disk that nobody registered.
const exemptPatterns = (registry.exempt || []).map((e) => ({
	re: new RegExp(`^${String(e.pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')}$`),
	reason: e.reason,
}));
for (const e of registry.exempt || []) {
	if (!e.reason || !String(e.reason).trim()) note(`exempt pattern \`${e.pattern}\` gives no reason, so nobody can judge whether it still holds`);
}

const onDisk = readdirSync(path.join(root, 'scripts'))
	.filter((f) => /^(check|audit)-.*\.(mjs|js)$/.test(f))
	.map((f) => `scripts/${f}`);

for (const rel of onDisk) {
	if (registered.has(rel)) continue;
	if (exemptPatterns.some((p) => p.re.test(rel))) continue;
	note(
		`${rel} looks like a guard but is not in data/guards.json. ` +
			`Add it (with the stage it runs in), or add an exempt pattern saying why it is not one.`,
	);
}

// docs/guards.md is the prose companion to the registry, and its tables are
// hand-maintained: nothing generates them. That is fine as long as something
// notices when a guard lands in the registry and never reaches the page. On
// 2026-08-11 five had: sync-studio-openapi, audit-inline-handlers, audit-csp,
// check-event-window, and audit-play-failure-modes ran on real stages while the
// doc that claims to list every guard did not mention them at all. A reader
// auditing coverage from the doc would have concluded those areas were
// unguarded. Matching on the npm command (which the tables print in a code
// span) rather than on the title keeps this immune to prose edits.
{
	const docPath = 'docs/guards.md';
	if (!existsSync(path.join(root, docPath))) {
		note(`${docPath} is missing, but it is the page /docs/guards renders and this registry documents`);
	} else {
		const doc = read(docPath);
		const documented = new Set([...doc.matchAll(/`npm run ([a-z0-9:-]+)`/g)].map((m) => m[1]));
		for (const g of registry.guards || []) {
			const npmNames = [g.npm, ...(g.npmAliases || [])].filter(Boolean);
			if (!npmNames.length) continue;
			if (npmNames.some((n) => documented.has(n))) continue;
			note(
				`guard \`${g.id}\` is in the registry but no table in ${docPath} names \`npm run ${npmNames[0]}\`. ` +
					`Add a row for it, so the page that claims to list every guard actually does.`,
			);
		}
	}
}

// The published copy the /guards page fetches. data/ is never served, so the
// page reads public/guards.json; if the two drift, the page and docs/guards.md
// show different answers and neither looks wrong on its own.
{
	const publicPath = 'public/guards.json';
	if (!existsSync(path.join(root, publicPath))) {
		note(`${publicPath} is missing, so /guards has nothing to render. Run \`npm run build:guards\`.`);
	} else {
		const expected = `${JSON.stringify(registry, null, '\t')}\n`;
		if (read(publicPath) !== expected) {
			note(`${publicPath} is out of date with data/guards.json, so /guards would render stale content. Run \`npm run build:guards\`.`);
		}
	}
}

if (failures.length) {
	console.error(`[audit-guards] ${failures.length} problem(s) between data/guards.json and the repo:`);
	for (const f of failures) console.error(`[audit-guards]   ${f}`);
	console.error('[audit-guards] The registry is what docs/guards.md and /guards render, so drift here misleads every reader.');
	process.exit(1);
}

const counts = (registry.guards || []).reduce((acc, g) => {
	for (const s of g.stages || []) acc[s] = (acc[s] || 0) + 1;
	return acc;
}, {});
const summary = Object.entries(counts)
	.map(([k, v]) => `${k}:${v}`)
	.join(' ');
console.log(`[audit-guards] OK: ${registry.guards.length} guards registered, every stage claim verified (${summary})`);