Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(sandbox): add template audit ledger writer (#4957)

Ernestba306ff78c6a
diff --git a/apps/sandbox/src/app/(sandbox)/templates/page.tsx b/apps/sandbox/src/app/(sandbox)/templates/page.tsx
index 82f538508a..e699bbaf1d 100644
--- a/apps/sandbox/src/app/(sandbox)/templates/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/templates/page.tsx
@@ -3,7 +3,7 @@
/**
* @file Filterable template audit roster with live summary metrics and details.
* @input Generated page/block registries and the sandbox template audit data.
- * @output Page-prefiltered audit table with filter-aware stats and a drawer.
+ * @output Filter-aware audit table, drawer, and identity-bound audit prompts.
* @position Sandbox template catalog at /templates/.
*/
@@ -271,6 +271,7 @@ function CopyButton({text, label}: {text: string; label: string}) {
function promptFor(row: TemplateRow): string {
return templateAuditPrompt({
+ id: row.id,
name: row.name,
type: row.type,
codePath: row.codePath,
diff --git a/apps/sandbox/src/data/templateAudits.ts b/apps/sandbox/src/data/templateAudits.ts
index fad04af545..4463cfef7e 100644
--- a/apps/sandbox/src/data/templateAudits.ts
+++ b/apps/sandbox/src/data/templateAudits.ts
@@ -3,9 +3,11 @@
/**
* @file Template score-ledger schema, historical seed, and audit prompt.
* @input Recoverable merge-commit score claims plus the wiki template rubric.
- * @output Versioned template ledger consumed by the Templates audit page.
+ * @output Versioned template ledger and executable audit-recording prompt.
* @position Local seed and schema for the proposed wiki template ledger.
*
+ * SYNC: Keep this schema aligned with scripts/template-score-ledger.mjs.
+ *
* The page checks the expected wiki copy at runtime and falls back to this
* bundled seed, matching the component page's live-ledger behavior without
* claiming the still-unpublished wiki file is canonical. The seed preserves
@@ -621,6 +623,7 @@ export function isTemplateAuditLedger(
}
export interface TemplateAuditPromptInput {
+ id: string;
name: string;
type: 'Page' | 'Block';
codePath: string;
@@ -628,6 +631,7 @@ export interface TemplateAuditPromptInput {
}
export function templateAuditPrompt({
+ id,
name,
type,
codePath,
@@ -643,5 +647,7 @@ Metadata: ${docPath}
Work all seven rubric categories and use the rubric's grading output format. Inspect the rendered template in a real browser, capture the relevant states in light and dark, and include responsive viewport coverage for page templates. Cite exact file locations for every deduction. Do not infer unpublished evidence or award points for anything you did not measure.
-Return the complete scorecard, detailed findings, screenshot-test evidence, and the top three fixes. Format the record for the central template-scores.json ledger, using the identity "${type.toLowerCase()}/<slug>".`;
+Return the complete scorecard, detailed findings, screenshot-test evidence, and the top three fixes. Save the raw scorecard JSON to a file without the ledger-managed id or status fields. Then record and publish it with:
+
+node scripts/template-score-ledger.mjs --record ${id} --from <scorecard.json> --push`;
}
diff --git a/scripts/template-score-ledger.mjs b/scripts/template-score-ledger.mjs
new file mode 100644
index 0000000000..3c73fcd9cd
--- /dev/null
+++ b/scripts/template-score-ledger.mjs
@@ -0,0 +1,934 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Template audit ledger reader, writer, queue, stats, and wiki publisher.
+ * @input Template scorecards plus page/block templates under packages/cli/assets/templates.
+ * @output Validated template-scores.json updates, summaries, and optional wiki pushes.
+ * @position Standalone source of truth for recording template audits.
+ *
+ * SYNC: Keep this schema aligned with apps/sandbox/src/data/templateAudits.ts.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const TEMPLATE_LEDGER_FILENAME = 'template-scores.json';
+export const TEMPLATE_LEDGER_URL =
+ 'https://raw.githubusercontent.com/wiki/facebook/astryx/template-scores.json';
+export const WIKI_REMOTE = 'https://github.com/facebook/astryx.wiki.git';
+export const WIKI_BRANCH = 'master';
+export const TEMPLATE_AUDITS_PAGE_URL =
+ 'https://facebook.github.io/astryx/sandbox/templates/';
+export const LEDGER_FETCH_TIMEOUT_MS = 10_000;
+export const WIKI_CACHE_DIR = path.join(
+ os.tmpdir(),
+ 'astryx-template-score-ledger-wiki',
+);
+
+export const TEMPLATE_CATEGORIES = Object.freeze([
+ {id: 'component_purity', title: 'Astryx component purity', max: 30},
+ {id: 'icon_purity', title: 'Icon purity', max: 15},
+ {id: 'custom_css', title: 'Custom CSS', max: 15},
+ {id: 'layout_structure', title: 'Layout & structure', max: 15},
+ {id: 'doc_metadata', title: 'Doc metadata', max: 10},
+ {id: 'image_handling', title: 'Image handling', max: 5},
+ {id: 'code_quality', title: 'Code quality', max: 10},
+]);
+
+const CATEGORY_BY_ID = new Map(
+ TEMPLATE_CATEGORIES.map(category => [category.id, category]),
+);
+const CATEGORY_STATUSES = new Set([
+ 'published',
+ 'inferred',
+ 'intermediate',
+ 'unresolved',
+]);
+const AUDIT_STATUSES = new Set(['historical', 'current']);
+const LEDGER_FIELDS = new Set([
+ 'ledgerVersion',
+ 'rubricVersion',
+ 'updated',
+ 'about',
+ 'caveats',
+ 'templates',
+]);
+const AUDIT_FIELDS = new Set([
+ 'id',
+ 'score',
+ 'grade',
+ 'recordedGrade',
+ 'status',
+ 'lastAudited',
+ 'commit',
+ 'pr',
+ 'rubricVersion',
+ 'categories',
+ 'findings',
+ 'topFixes',
+ 'evidence',
+ 'notes',
+]);
+const SCORECARD_FIELDS = new Set(
+ [...AUDIT_FIELDS].filter(field => field !== 'id' && field !== 'status'),
+);
+const CATEGORY_FIELDS = new Set(['score', 'status', 'note']);
+const EVIDENCE_FIELDS = new Set(['label', 'href']);
+
+const USAGE = `
+Usage: node scripts/template-score-ledger.mjs <subcommand> [options]
+
+Subcommands
+ --queue Unaudited templates first, then oldest and lowest-scoring.
+ --stats Coverage and score summary.
+ --record <type/slug> Write one page or block template audit.
+
+Options
+ --ledger <path|url> Ledger source. Default: the wiki raw URL.
+ --record needs a local path, --dry-run, or --push.
+ --from <file|-> --record scorecard JSON; '-' reads stdin.
+ --limit <n> --queue row limit (default 5).
+ --allow-regression <why> Permit a lower score and put the reason in the commit.
+ --push Clone/refresh the wiki, commit, rebase, and push.
+ --dry-run Print the ledger diff and commit message; write nothing.
+ --json Machine-readable queue/stats output.
+`.trim();
+
+function isRecord(value) {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function assert(condition, message) {
+ if (!condition) throw new Error(message);
+}
+
+function assertNoUnknownFields(value, allowed, label) {
+ const unknown = Object.keys(value).filter(key => !allowed.has(key));
+ assert(
+ unknown.length === 0,
+ `${label}: unknown field(s): ${unknown.join(', ')}`,
+ );
+}
+
+function assertNonEmptyString(value, label) {
+ assert(
+ typeof value === 'string' && value.trim() !== '',
+ `${label} is required`,
+ );
+}
+
+export function templateGrade(score) {
+ if (score >= 90) return 'A';
+ if (score >= 75) return 'B';
+ if (score >= 60) return 'C';
+ if (score >= 40) return 'D';
+ return 'F';
+}
+
+export function isTemplateId(id) {
+ return (
+ typeof id === 'string' &&
+ /^(page|block)\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)
+ );
+}
+
+function validateCategory(value, id, auditId) {
+ assert(isRecord(value), `${auditId}: category ${id} must be an object`);
+ assertNoUnknownFields(value, CATEGORY_FIELDS, `${auditId}: category ${id}`);
+ const definition = CATEGORY_BY_ID.get(id);
+ assert(definition, `${auditId}: unknown category id "${id}"`);
+ assert(
+ value.score === null ||
+ (typeof value.score === 'number' &&
+ Number.isFinite(value.score) &&
+ value.score >= 0 &&
+ value.score <= definition.max),
+ `${auditId}: category ${id} score must be null or between 0 and ${definition.max}`,
+ );
+ assert(
+ CATEGORY_STATUSES.has(value.status),
+ `${auditId}: category ${id} has unknown status "${String(value.status)}"`,
+ );
+ assert(
+ value.note === undefined || typeof value.note === 'string',
+ `${auditId}: category ${id} note must be a string`,
+ );
+}
+
+function validateEvidence(value, auditId, index) {
+ assert(isRecord(value), `${auditId}: evidence ${index} must be an object`);
+ assertNoUnknownFields(
+ value,
+ EVIDENCE_FIELDS,
+ `${auditId}: evidence ${index}`,
+ );
+ assertNonEmptyString(value.label, `${auditId}: evidence ${index} label`);
+ assert(
+ value.href === undefined || typeof value.href === 'string',
+ `${auditId}: evidence ${index} href must be a string`,
+ );
+}
+
+export function validateAudit(value) {
+ assert(isRecord(value), 'template audit must be an object');
+ assertNoUnknownFields(value, AUDIT_FIELDS, 'template audit');
+ assert(isTemplateId(value.id), `invalid template id "${String(value.id)}"`);
+ assert(
+ typeof value.score === 'number' &&
+ Number.isFinite(value.score) &&
+ value.score >= 0 &&
+ value.score <= 100,
+ `${value.id}: score must be between 0 and 100`,
+ );
+ const expectedGrade = templateGrade(value.score);
+ assert(
+ value.grade === expectedGrade,
+ `${value.id}: grade ${String(value.grade)} contradicts score ${value.score}; expected ${expectedGrade}`,
+ );
+ assert(
+ AUDIT_STATUSES.has(value.status),
+ `${value.id}: status must be historical or current`,
+ );
+ assertNonEmptyString(value.lastAudited, `${value.id}: lastAudited`);
+ assertNonEmptyString(value.commit, `${value.id}: commit`);
+ assertNonEmptyString(value.rubricVersion, `${value.id}: rubricVersion`);
+ assert(
+ value.recordedGrade === undefined ||
+ typeof value.recordedGrade === 'string',
+ `${value.id}: recordedGrade must be a string`,
+ );
+ assert(
+ value.pr === undefined || (Number.isInteger(value.pr) && value.pr > 0),
+ `${value.id}: pr must be a positive integer`,
+ );
+ assert(
+ isRecord(value.categories),
+ `${value.id}: categories must be an object`,
+ );
+ for (const [id, category] of Object.entries(value.categories)) {
+ validateCategory(category, id, value.id);
+ }
+ if (value.status === 'current') {
+ const categoryIds = Object.keys(value.categories);
+ const missing = TEMPLATE_CATEGORIES.filter(
+ category => !Object.hasOwn(value.categories, category.id),
+ ).map(category => category.id);
+ assert(
+ categoryIds.length === TEMPLATE_CATEGORIES.length && missing.length === 0,
+ `${value.id}: current audits must include all seven categories` +
+ (missing.length ? `; missing ${missing.join(', ')}` : ''),
+ );
+ const categoryScores = TEMPLATE_CATEGORIES.map(
+ category => value.categories[category.id].score,
+ );
+ assert(
+ categoryScores.every(score => typeof score === 'number'),
+ `${value.id}: current audit category scores cannot be null`,
+ );
+ const categoryTotal = categoryScores.reduce((sum, score) => sum + score, 0);
+ assert(
+ Math.abs(categoryTotal - value.score) < 1e-9,
+ `${value.id}: category scores total ${categoryTotal}, not overall score ${value.score}`,
+ );
+ }
+ for (const field of ['findings', 'topFixes']) {
+ assert(
+ Array.isArray(value[field]),
+ `${value.id}: ${field} must be an array`,
+ );
+ assert(
+ value[field].every(item => typeof item === 'string'),
+ `${value.id}: ${field} entries must be strings`,
+ );
+ }
+ assert(
+ Array.isArray(value.evidence),
+ `${value.id}: evidence must be an array`,
+ );
+ value.evidence.forEach((item, index) =>
+ validateEvidence(item, value.id, index),
+ );
+ assert(
+ typeof value.notes === 'string',
+ `${value.id}: notes must be a string`,
+ );
+ return value;
+}
+
+export function validateLedger(value) {
+ assert(isRecord(value), 'template ledger must be an object');
+ assertNoUnknownFields(value, LEDGER_FIELDS, 'template ledger');
+ assert(
+ Number.isInteger(value.ledgerVersion) && value.ledgerVersion > 0,
+ 'template ledger: ledgerVersion must be a positive integer',
+ );
+ assertNonEmptyString(value.rubricVersion, 'template ledger: rubricVersion');
+ assertNonEmptyString(value.updated, 'template ledger: updated');
+ assert(
+ value.about === undefined || typeof value.about === 'string',
+ 'template ledger: about must be a string',
+ );
+ assert(
+ value.caveats === undefined ||
+ (Array.isArray(value.caveats) &&
+ value.caveats.every(caveat => typeof caveat === 'string')),
+ 'template ledger: caveats must be an array of strings',
+ );
+ assert(
+ Array.isArray(value.templates),
+ 'template ledger: templates must be an array',
+ );
+ value.templates.forEach(validateAudit);
+ const ids = value.templates.map(audit => audit.id);
+ assert(
+ new Set(ids).size === ids.length,
+ 'template ledger: duplicate template ids',
+ );
+ return value;
+}
+
+const isUrl = source => /^https?:\/\//.test(source);
+
+export async function loadLedger(
+ source,
+ {timeoutMs = LEDGER_FETCH_TIMEOUT_MS} = {},
+) {
+ try {
+ let text;
+ if (isUrl(source)) {
+ const response = await fetch(source, {
+ redirect: 'follow',
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ if (!response.ok) {
+ throw new Error(`HTTP ${response.status} ${response.statusText}`);
+ }
+ text = await response.text();
+ } else {
+ text = fs.readFileSync(source, 'utf8');
+ }
+ return {ledger: validateLedger(JSON.parse(text)), error: null};
+ } catch (error) {
+ const message =
+ error.name === 'TimeoutError'
+ ? `no response within ${timeoutMs}ms`
+ : error.message;
+ return {ledger: null, error: `${source}: ${message}`};
+ }
+}
+
+function findFilesRecursive(dir, pattern) {
+ if (!fs.existsSync(dir)) return [];
+ const files = [];
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+ const absolute = path.join(dir, entry.name);
+ if (entry.isDirectory())
+ files.push(...findFilesRecursive(absolute, pattern));
+ else if (pattern.test(entry.name)) files.push(absolute);
+ }
+ return files;
+}
+
+export function listTemplates(repoRoot = ROOT) {
+ const templateRoot = path.join(
+ repoRoot,
+ 'packages',
+ 'cli',
+ 'assets',
+ 'templates',
+ );
+ const pageRoot = path.join(templateRoot, 'pages');
+ const blockRoot = path.join(templateRoot, 'blocks');
+ const roster = [];
+
+ if (fs.existsSync(pageRoot)) {
+ for (const entry of fs.readdirSync(pageRoot, {withFileTypes: true})) {
+ if (!entry.isDirectory()) continue;
+ const code = path.join(pageRoot, entry.name, 'page.tsx');
+ const doc = path.join(pageRoot, entry.name, 'template.doc.mjs');
+ if (!fs.existsSync(code) || !fs.existsSync(doc)) continue;
+ roster.push({
+ id: `page/${entry.name}`,
+ type: 'page',
+ slug: entry.name,
+ codePath: path.relative(repoRoot, code),
+ docPath: path.relative(repoRoot, doc),
+ });
+ }
+ }
+
+ for (const doc of findFilesRecursive(blockRoot, /\.doc\.mjs$/)) {
+ const slug = path.basename(doc, '.doc.mjs');
+ const code = path.join(path.dirname(doc), `${slug}.tsx`);
+ if (!fs.existsSync(code)) continue;
+ roster.push({
+ id: `block/${slug}`,
+ type: 'block',
+ slug,
+ codePath: path.relative(repoRoot, code),
+ docPath: path.relative(repoRoot, doc),
+ });
+ }
+
+ return roster.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function buildRoster(ledger, templates = listTemplates()) {
+ validateLedger(ledger);
+ const byId = new Map(ledger.templates.map(audit => [audit.id, audit]));
+ const roster = templates.map(template => ({
+ ...template,
+ live: true,
+ audit: byId.get(template.id) ?? null,
+ }));
+ const liveIds = new Set(roster.map(row => row.id));
+ for (const audit of ledger.templates) {
+ if (liveIds.has(audit.id)) continue;
+ const [type, slug] = audit.id.split('/');
+ roster.push({id: audit.id, type, slug, live: false, audit});
+ }
+ return roster.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function buildQueue(roster, limit = Infinity) {
+ const unaudited = roster
+ .filter(row => row.live && !row.audit)
+ .sort((a, b) => a.id.localeCompare(b.id))
+ .map(row => ({id: row.id, why: 'never audited'}));
+ const audited = roster
+ .filter(row => row.audit)
+ .sort((a, b) => {
+ const byDate = String(a.audit.lastAudited).localeCompare(
+ String(b.audit.lastAudited),
+ );
+ if (byDate !== 0) return byDate;
+ if (a.audit.score !== b.audit.score) return a.audit.score - b.audit.score;
+ return a.id.localeCompare(b.id);
+ })
+ .map(row => ({
+ id: row.id,
+ why:
+ `audited ${row.audit.lastAudited} · ${row.audit.grade} ` +
+ `${row.audit.score.toFixed(1)}${row.live ? '' : ' · NO LONGER IN THE ROSTER'}`,
+ }));
+ return [...unaudited, ...audited].slice(0, limit);
+}
+
+export function buildStats(roster) {
+ const live = roster.filter(row => row.live);
+ const audited = live.filter(row => row.audit);
+ const scores = audited.map(row => row.audit.score);
+ const grades = {A: 0, B: 0, C: 0, D: 0, F: 0};
+ for (const row of audited) grades[row.audit.grade] += 1;
+ const byType = {};
+ for (const type of ['page', 'block']) {
+ const rows = live.filter(row => row.type === type);
+ byType[type] = {
+ total: rows.length,
+ audited: rows.filter(row => row.audit).length,
+ };
+ }
+ return {
+ total: live.length,
+ audited: audited.length,
+ unaudited: live.length - audited.length,
+ percentAudited: live.length
+ ? Math.round((audited.length / live.length) * 1000) / 10
+ : 0,
+ meanScore: scores.length
+ ? Math.round(
+ (scores.reduce((sum, score) => sum + score, 0) / scores.length) * 10,
+ ) / 10
+ : null,
+ grades,
+ byType,
+ oldestAudit: audited.map(row => row.audit.lastAudited).sort()[0] ?? null,
+ newestAudit:
+ audited
+ .map(row => row.audit.lastAudited)
+ .sort()
+ .at(-1) ?? null,
+ orphanRows: roster.filter(row => !row.live).map(row => row.id),
+ };
+}
+
+export function applyScorecard(existing, scorecard, {id}) {
+ assert(isTemplateId(id), `invalid template id "${String(id)}"`);
+ assert(isRecord(scorecard), `${id}: scorecard must be an object`);
+ assertNoUnknownFields(scorecard, SCORECARD_FIELDS, `${id}: scorecard`);
+
+ const next = {
+ id,
+ score: null,
+ grade: null,
+ status: 'current',
+ lastAudited: null,
+ commit: null,
+ rubricVersion: null,
+ categories: {},
+ findings: [],
+ topFixes: [],
+ evidence: [],
+ notes: '',
+ ...structuredClone(scorecard),
+ id,
+ status: 'current',
+ };
+
+ if (!Object.hasOwn(scorecard, 'grade'))
+ next.grade = templateGrade(next.score);
+ return validateAudit(next);
+}
+
+export function commitMessage(entry, {regression = null} = {}) {
+ const subject =
+ `template scores: ${entry.id} ${entry.grade} (${entry.score.toFixed(1)}), ` +
+ `rubric ${entry.rubricVersion}`;
+ if (!regression) return {subject, body: ''};
+ return {
+ subject,
+ body: [
+ `Regression allowed: ${regression.reason}`,
+ '',
+ `Score ${regression.from.toFixed(1)} → ${entry.score.toFixed(1)}.`,
+ ].join('\n'),
+ };
+}
+
+function git(cwd, ...argv) {
+ return execFileSync('git', argv, {
+ cwd,
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ }).trim();
+}
+
+function tryGit(cwd, ...argv) {
+ try {
+ return {ok: true, out: git(cwd, ...argv)};
+ } catch (error) {
+ const out = `${error.stdout || ''}\n${error.stderr || ''}`.trim();
+ return {ok: false, out: out || error.message};
+ }
+}
+
+export function ensureWikiClone(dir = WIKI_CACHE_DIR, remote = WIKI_REMOTE) {
+ if (fs.existsSync(path.join(dir, '.git'))) {
+ git(dir, 'remote', 'set-url', 'origin', remote);
+ git(dir, 'fetch', '--depth', '1', 'origin', WIKI_BRANCH);
+ } else {
+ fs.rmSync(dir, {recursive: true, force: true});
+ git(
+ os.tmpdir(),
+ 'clone',
+ '--depth',
+ '1',
+ '--branch',
+ WIKI_BRANCH,
+ remote,
+ dir,
+ );
+ }
+ git(dir, 'checkout', '-B', WIKI_BRANCH, `origin/${WIKI_BRANCH}`);
+ git(dir, 'reset', '--hard', `origin/${WIKI_BRANCH}`);
+ git(dir, 'clean', '-fd');
+ return dir;
+}
+
+export function repoFromWikiRemote(remote = WIKI_REMOTE) {
+ const match = /github\.com[/:]([^/]+)\/(.+?)\.wiki(\.git)?$/.exec(remote);
+ return match ? `${match[1]}/${match[2]}` : 'facebook/astryx';
+}
+
+export function wikiCommitUrl(sha, remote = WIKI_REMOTE) {
+ return `https://github.com/${repoFromWikiRemote(remote)}/wiki/_compare/${sha}`;
+}
+
+function requireGitIdentity(dir) {
+ const name = tryGit(dir, 'config', 'user.name');
+ const email = tryGit(dir, 'config', 'user.email');
+ if (!name.ok || !name.out || !email.ok || !email.out) {
+ throw new Error(
+ 'no git identity configured — set user.name and user.email before --push',
+ );
+ }
+}
+
+function unifiedDiff(before, after, label) {
+ const dir = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'template-score-ledger-diff-'),
+ );
+ try {
+ const a = path.join(dir, 'a');
+ const b = path.join(dir, 'b');
+ fs.writeFileSync(a, before);
+ fs.writeFileSync(b, after);
+ try {
+ execFileSync(
+ 'diff',
+ ['-u', '--label', `a/${label}`, '--label', `b/${label}`, a, b],
+ {encoding: 'utf8'},
+ );
+ return '';
+ } catch (error) {
+ if (error.status === 1) return String(error.stdout);
+ throw error;
+ }
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+}
+
+export function commitAndPush(dir, file, apply, {attempts = 2} = {}) {
+ const root = fs.realpathSync(dir);
+ const target = fs.realpathSync(file);
+ const relative = path.relative(root, target) || path.basename(target);
+ requireGitIdentity(root);
+ let lastFailure = null;
+
+ for (let attempt = 1; attempt <= attempts; attempt++) {
+ const applied = apply();
+ fs.writeFileSync(target, applied.text);
+ const dirtyOthers = [
+ ...git(root, 'diff', '--name-only', 'HEAD').split('\n'),
+ ...git(root, 'ls-files', '--others', '--exclude-standard').split('\n'),
+ ]
+ .filter(Boolean)
+ .filter(fileName => fileName !== relative);
+ if (dirtyOthers.length) {
+ throw new Error(
+ `the wiki working copy has unrelated changes (${dirtyOthers.join(', ')})`,
+ );
+ }
+
+ git(root, 'add', '--', relative);
+ const {subject, body} = applied.message;
+ const commitArgs = ['commit', '-m', subject];
+ if (body) commitArgs.push('-m', body);
+ const committed = tryGit(root, ...commitArgs);
+ if (!committed.ok) {
+ throw new Error(`could not commit the ledger: ${committed.out}`);
+ }
+
+ const pulled = tryGit(root, 'pull', '--rebase', 'origin', WIKI_BRANCH);
+ if (!pulled.ok) {
+ tryGit(root, 'rebase', '--abort');
+ lastFailure = pulled.out;
+ if (attempt < attempts) {
+ console.log(
+ 'template-score-ledger: the wiki moved under us — re-applying onto the new tip.',
+ );
+ git(root, 'fetch', '--depth', '1', 'origin', WIKI_BRANCH);
+ git(root, 'reset', '--hard', `origin/${WIKI_BRANCH}`);
+ continue;
+ }
+ break;
+ }
+
+ const pushed = tryGit(root, 'push', 'origin', `HEAD:${WIKI_BRANCH}`);
+ if (pushed.ok) {
+ const sha = git(root, 'rev-parse', 'HEAD');
+ return {sha, url: wikiCommitUrl(sha), applied};
+ }
+ lastFailure = pushed.out;
+ const raced = /non-fast-forward|fetch first|rejected|stale info/i.test(
+ pushed.out,
+ );
+ if (!raced || attempt >= attempts) break;
+ console.log(
+ 'template-score-ledger: push rejected — re-applying and retrying once.',
+ );
+ git(root, 'fetch', '--depth', '1', 'origin', WIKI_BRANCH);
+ git(root, 'reset', '--hard', `origin/${WIKI_BRANCH}`);
+ }
+
+ throw new Error(
+ `could not push the ledger after ${attempts} attempt(s): ${lastFailure}\n` +
+ 'Nothing was published. If this is an auth failure, run `gh auth setup-git`.',
+ );
+}
+
+function parseArgs(argv) {
+ const args = {_: []};
+ for (let index = 0; index < argv.length; index++) {
+ const argument = argv[index];
+ if (!argument.startsWith('--')) {
+ args._.push(argument);
+ continue;
+ }
+ const key = argument.slice(2);
+ const next = argv[index + 1];
+ if (next === undefined || next.startsWith('--')) args[key] = true;
+ else {
+ args[key] = next;
+ index += 1;
+ }
+ }
+ return args;
+}
+
+function flagValue(value) {
+ return value === true || value === false || value == null ? null : value;
+}
+
+async function readLedgerForCommand(args) {
+ const source = flagValue(args.ledger) || TEMPLATE_LEDGER_URL;
+ const result = await loadLedger(source);
+ if (!result.ledger) throw new Error(result.error);
+ return result.ledger;
+}
+
+async function cmdQueue(args) {
+ let ledger;
+ try {
+ ledger = await readLedgerForCommand(args);
+ } catch (error) {
+ console.error(`template-score-ledger: ${error.message}`);
+ return 1;
+ }
+ const parsedLimit = Number.parseInt(flagValue(args.limit) || '5', 10);
+ const limit =
+ Number.isInteger(parsedLimit) && parsedLimit > 0 ? parsedLimit : 5;
+ const queue = buildQueue(buildRoster(ledger), limit);
+ if (args.json) console.log(JSON.stringify(queue, null, 2));
+ else if (queue.length === 0) console.log('No templates in the queue.');
+ else
+ queue.forEach((row, index) =>
+ console.log(`${index + 1}. ${row.id} — ${row.why}`),
+ );
+ return 0;
+}
+
+async function cmdStats(args) {
+ let ledger;
+ try {
+ ledger = await readLedgerForCommand(args);
+ } catch (error) {
+ console.error(`template-score-ledger: ${error.message}`);
+ return 1;
+ }
+ const stats = buildStats(buildRoster(ledger));
+ if (args.json) console.log(JSON.stringify(stats, null, 2));
+ else {
+ console.log(
+ `Template audit ledger — v${ledger.ledgerVersion}, rubric v${ledger.rubricVersion}`,
+ );
+ console.log(
+ ` Audited: ${stats.audited}/${stats.total} (${stats.percentAudited}%)`,
+ );
+ console.log(
+ ` Mean: ${stats.meanScore === null ? '—' : stats.meanScore.toFixed(1)}`,
+ );
+ console.log(
+ ` Grades: ${Object.entries(stats.grades)
+ .map(([grade, count]) => `${grade} ${count}`)
+ .join(' · ')}`,
+ );
+ console.log(
+ ` Pages: ${stats.byType.page.audited}/${stats.byType.page.total}`,
+ );
+ console.log(
+ ` Blocks: ${stats.byType.block.audited}/${stats.byType.block.total}`,
+ );
+ }
+ return 0;
+}
+
+async function cmdRecord(args) {
+ const id = flagValue(args.record);
+ if (!isTemplateId(id)) {
+ console.error(
+ 'template-score-ledger --record: pass a template id such as page/centered-hero or block/AppShellShowcase',
+ );
+ return 1;
+ }
+ const source = flagValue(args.from);
+ if (!source) {
+ console.error(
+ 'template-score-ledger --record: --from <scorecard.json|-> is required',
+ );
+ return 1;
+ }
+
+ let scorecard;
+ try {
+ scorecard = JSON.parse(
+ source === '-'
+ ? fs.readFileSync(0, 'utf8')
+ : fs.readFileSync(source, 'utf8'),
+ );
+ } catch (error) {
+ console.error(
+ `template-score-ledger --record: could not read ${source} — ${error.message}`,
+ );
+ return 1;
+ }
+
+ if (args['allow-regression'] === true) {
+ console.error(
+ 'template-score-ledger --record: --allow-regression needs a reason',
+ );
+ return 1;
+ }
+
+ const push = Boolean(args.push);
+ const dryRun = Boolean(args['dry-run']);
+ let ledgerPath = flagValue(args.ledger);
+ let repoDir = null;
+ if (ledgerPath && isUrl(ledgerPath)) {
+ console.error(
+ 'template-score-ledger --record: --ledger must be a local path; use --push for the wiki',
+ );
+ return 1;
+ }
+ try {
+ if (!ledgerPath) {
+ if (!push && !dryRun) {
+ console.error(
+ 'template-score-ledger --record: pass --push, --dry-run, or --ledger <path>',
+ );
+ return 1;
+ }
+ repoDir = ensureWikiClone();
+ ledgerPath = path.join(repoDir, TEMPLATE_LEDGER_FILENAME);
+ } else if (push) {
+ const top = tryGit(
+ path.dirname(path.resolve(ledgerPath)),
+ 'rev-parse',
+ '--show-toplevel',
+ );
+ if (!top.ok) {
+ console.error(
+ 'template-score-ledger --record: --push requires the ledger to be inside a wiki git clone',
+ );
+ return 1;
+ }
+ repoDir = top.out;
+ }
+ } catch (error) {
+ console.error(`template-score-ledger --record: ${error.message}`);
+ return 1;
+ }
+
+ const rosterIds = new Set(listTemplates().map(template => template.id));
+ if (!rosterIds.has(id)) {
+ console.log(
+ `template-score-ledger: warning — ${id} is not in the current page/block roster; recording anyway.`,
+ );
+ }
+
+ const applyOnce = () => {
+ if (!fs.existsSync(ledgerPath)) {
+ throw new Error(
+ `${TEMPLATE_LEDGER_FILENAME} does not exist; refusing to create a partial one-row ledger. ` +
+ 'Bootstrap the wiki file from the bundled 25-row historical seed, then retry.',
+ );
+ }
+ const raw = fs.readFileSync(ledgerPath, 'utf8');
+ const ledger = validateLedger(JSON.parse(raw));
+ const index = ledger.templates.findIndex(audit => audit.id === id);
+ const before = index === -1 ? null : ledger.templates[index];
+ const after = applyScorecard(before, scorecard, {id});
+ let regression = null;
+ if (before && after.score < before.score) {
+ const reason = flagValue(args['allow-regression']);
+ if (!reason) {
+ throw new Error(
+ `refusing — score decreased ${before.score} -> ${after.score}; re-run with --allow-regression "<why>"`,
+ );
+ }
+ regression = {reason: String(reason), from: before.score};
+ }
+ if (index === -1) ledger.templates.push(after);
+ else ledger.templates[index] = after;
+ ledger.templates.sort((a, b) => a.id.localeCompare(b.id));
+ ledger.updated = new Date().toISOString().slice(0, 10);
+ validateLedger(ledger);
+ return {
+ before,
+ after,
+ regression,
+ raw,
+ text: `${JSON.stringify(ledger, null, 2)}\n`,
+ message: commitMessage(after, {regression}),
+ };
+ };
+
+ let applied;
+ try {
+ applied = applyOnce();
+ } catch (error) {
+ console.error(`template-score-ledger --record: ${error.message}`);
+ return 1;
+ }
+
+ if (dryRun) {
+ console.log(
+ unifiedDiff(applied.raw, applied.text, TEMPLATE_LEDGER_FILENAME) ||
+ `(${TEMPLATE_LEDGER_FILENAME} is already unchanged)`,
+ );
+ console.log('--- commit message ---');
+ console.log(applied.message.subject);
+ if (applied.message.body) console.log(`\n${applied.message.body}`);
+ console.log(
+ 'template-score-ledger: --dry-run — nothing written or pushed.',
+ );
+ return 0;
+ }
+
+ if (push) {
+ try {
+ const result = commitAndPush(repoDir, ledgerPath, applyOnce);
+ applied = result.applied;
+ console.log(
+ `template-score-ledger: recorded ${id} — ${applied.after.grade} ` +
+ `${applied.after.score.toFixed(1)} and pushed ${result.sha.slice(0, 10)}`,
+ );
+ console.log(` commit: ${result.url}`);
+ console.log(` live on: ${TEMPLATE_AUDITS_PAGE_URL}`);
+ return 0;
+ } catch (error) {
+ console.error(`template-score-ledger --record: ${error.message}`);
+ return 1;
+ }
+ }
+
+ fs.writeFileSync(ledgerPath, applied.text);
+ console.log(`template-score-ledger: recorded ${id} in ${ledgerPath}`);
+ console.log(
+ 'template-score-ledger: not published — commit the wiki or use --push.',
+ );
+ return 0;
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ if (args.help || args.h) {
+ console.log(USAGE);
+ return 0;
+ }
+ if (args.queue) return cmdQueue(args);
+ if (args.stats) return cmdStats(args);
+ if (args.record) return cmdRecord(args);
+ console.log(USAGE);
+ return 1;
+}
+
+if (
+ process.argv[1] &&
+ fileURLToPath(import.meta.url) === path.resolve(process.argv[1])
+) {
+ main().then(
+ code => process.exit(code),
+ error => {
+ console.error(`template-score-ledger: ${error.message}`);
+ process.exit(1);
+ },
+ );
+}
diff --git a/scripts/template-score-ledger.test.mjs b/scripts/template-score-ledger.test.mjs
new file mode 100644
index 0000000000..dec671cf9b
--- /dev/null
+++ b/scripts/template-score-ledger.test.mjs
@@ -0,0 +1,723 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Focused unit and integration tests for the template score ledger.
+ * @input The template-score-ledger module, the checked-in template roster, and
+ * temporary local wiki repositories.
+ * @output Assertions for schema validation, recording, reporting, and safe
+ * concurrent publication.
+ * @position Regression coverage for scripts/template-score-ledger.mjs.
+ */
+
+import {execFileSync} from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {describe, expect, it} from 'vitest';
+
+import {
+ TEMPLATE_CATEGORIES,
+ TEMPLATE_LEDGER_FILENAME,
+ TEMPLATE_LEDGER_URL,
+ WIKI_BRANCH,
+ WIKI_REMOTE,
+ applyScorecard,
+ buildQueue,
+ buildRoster,
+ buildStats,
+ commitMessage,
+ ensureWikiClone,
+ listTemplates,
+ templateGrade,
+ validateLedger,
+} from './template-score-ledger.mjs';
+
+const REPO_ROOT = path.resolve(import.meta.dirname, '..');
+const SCRIPT = path.join(REPO_ROOT, 'scripts', 'template-score-ledger.mjs');
+
+const categoriesForScore = score => {
+ let remaining = score;
+ return Object.fromEntries(
+ TEMPLATE_CATEGORIES.map(category => {
+ const points = Math.min(category.max, Math.max(0, remaining));
+ remaining -= points;
+ return [category.id, {score: points, status: 'published'}];
+ }),
+ );
+};
+
+const audit = (overrides = {}) => {
+ const score = overrides.score ?? 81;
+ return {
+ id: 'page/centered-hero',
+ score,
+ grade: templateGrade(score),
+ status: 'current',
+ lastAudited: '2026-08-11',
+ commit: 'abc1234567',
+ rubricVersion: '1',
+ categories: categoriesForScore(score),
+ findings: ['One raw wrapper remains.'],
+ topFixes: ['Replace the wrapper with Stack.'],
+ evidence: [{label: 'Rendered audit', href: 'https://example.com/audit'}],
+ notes: 'Audited at HEAD.',
+ ...overrides,
+ };
+};
+
+const scorecard = (overrides = {}) => {
+ const score = overrides.score ?? 81;
+ return {
+ score,
+ lastAudited: '2026-08-11',
+ commit: 'abc1234567',
+ rubricVersion: '1',
+ categories: categoriesForScore(score),
+ findings: ['One raw wrapper remains.'],
+ topFixes: ['Replace the wrapper with Stack.'],
+ evidence: [{label: 'Rendered audit'}],
+ notes: 'Audited at HEAD.',
+ ...overrides,
+ };
+};
+
+const ledgerWith = (...templates) => ({
+ ledgerVersion: 1,
+ rubricVersion: '1',
+ updated: '2026-08-11',
+ templates,
+});
+
+describe('the public ledger contract', () => {
+ it('uses the one wiki file and branch shared by every write path', () => {
+ expect(TEMPLATE_LEDGER_FILENAME).toBe('template-scores.json');
+ expect(TEMPLATE_LEDGER_URL).toBe(
+ 'https://raw.githubusercontent.com/wiki/facebook/astryx/template-scores.json',
+ );
+ expect(WIKI_REMOTE).toBe('https://github.com/facebook/astryx.wiki.git');
+ expect(WIKI_BRANCH).toBe('master');
+ expect(ensureWikiClone).toBeTypeOf('function');
+ });
+
+ it('uses the rubric grade boundaries', () => {
+ expect(
+ [100, 90, 89.9, 75, 74.9, 60, 59.9, 40, 39.9, 0].map(templateGrade),
+ ).toEqual(['A', 'A', 'B', 'B', 'C', 'C', 'D', 'D', 'F', 'F']);
+ });
+
+ it('carries the complete 100-point category vocabulary', () => {
+ expect(TEMPLATE_CATEGORIES.map(category => category.id)).toEqual([
+ 'component_purity',
+ 'icon_purity',
+ 'custom_css',
+ 'layout_structure',
+ 'doc_metadata',
+ 'image_handling',
+ 'code_quality',
+ ]);
+ expect(
+ TEMPLATE_CATEGORIES.reduce((sum, category) => sum + category.max, 0),
+ ).toBe(100);
+ });
+});
+
+describe('strict ledger validation', () => {
+ it('returns a valid ledger', () => {
+ const ledger = ledgerWith(audit());
+ expect(validateLedger(ledger)).toBe(ledger);
+ });
+
+ it('rejects unknown top-level, row, category, and category-detail fields', () => {
+ expect(() => validateLedger({...ledgerWith(), typo: true})).toThrow(
+ /unknown.*typo/i,
+ );
+ expect(() => validateLedger(ledgerWith(audit({socre: 81})))).toThrow(
+ /unknown.*socre/i,
+ );
+ expect(() =>
+ validateLedger(
+ ledgerWith(
+ audit({
+ categories: {component_purty: {score: 26, status: 'published'}},
+ }),
+ ),
+ ),
+ ).toThrow(/unknown category.*component_purty/i);
+ expect(() =>
+ validateLedger(
+ ledgerWith(
+ audit({
+ categories: {
+ component_purity: {score: 26, status: 'published', points: 30},
+ },
+ }),
+ ),
+ ),
+ ).toThrow(/unknown.*points/i);
+ });
+
+ it('rejects malformed and duplicate template ids', () => {
+ expect(() =>
+ validateLedger(ledgerWith(audit({id: 'pages/centered-hero'}))),
+ ).toThrow(/invalid template id/i);
+ expect(() => validateLedger(ledgerWith(audit(), audit()))).toThrow(
+ /duplicate.*id/i,
+ );
+ });
+
+ it('rejects a grade that contradicts the score', () => {
+ expect(() =>
+ validateLedger(ledgerWith(audit({score: 89, grade: 'A'}))),
+ ).toThrow(/grade.*contradicts.*score|expected B/i);
+ });
+
+ it('requires every current category and an exact category total', () => {
+ expect(() =>
+ validateLedger(
+ ledgerWith(
+ audit({
+ categories: {component_purity: {score: 26, status: 'published'}},
+ }),
+ ),
+ ),
+ ).toThrow(/all seven categories|missing/i);
+ expect(() =>
+ validateLedger(ledgerWith(audit({categories: categoriesForScore(80)}))),
+ ).toThrow(/total 80.*overall score 81/i);
+ expect(
+ validateLedger(
+ ledgerWith(
+ audit({
+ status: 'historical',
+ categories: {component_purity: {score: 26, status: 'published'}},
+ }),
+ ),
+ ).templates[0].status,
+ ).toBe('historical');
+ });
+
+ it('rejects invalid category status and points outside the category maximum', () => {
+ expect(() =>
+ validateLedger(
+ ledgerWith(
+ audit({
+ categories: {component_purity: {score: 26, status: 'estimated'}},
+ }),
+ ),
+ ),
+ ).toThrow(/category.*status|estimated/i);
+ expect(() =>
+ validateLedger(
+ ledgerWith(
+ audit({
+ categories: {image_handling: {score: 6, status: 'published'}},
+ }),
+ ),
+ ),
+ ).toThrow(/image_handling.*5|maximum.*5/i);
+ });
+
+ it('requires the arrays and evidence shape instead of coercing them', () => {
+ expect(() => validateLedger(ledgerWith(audit({findings: 'none'})))).toThrow(
+ /findings/i,
+ );
+ expect(() =>
+ validateLedger(
+ ledgerWith(audit({evidence: [{href: 'https://example.com'}]})),
+ ),
+ ).toThrow(/evidence.*label|label/i);
+ });
+});
+
+describe('scorecard application', () => {
+ it('derives grade and defaults optional current-audit fields', () => {
+ const row = applyScorecard(
+ null,
+ {
+ score: 92,
+ lastAudited: '2026-08-12',
+ commit: 'def1234567',
+ rubricVersion: '1',
+ categories: categoriesForScore(92),
+ },
+ {id: 'block/PowerSearchShowcase'},
+ );
+ expect(row).toEqual({
+ id: 'block/PowerSearchShowcase',
+ score: 92,
+ grade: 'A',
+ status: 'current',
+ lastAudited: '2026-08-12',
+ commit: 'def1234567',
+ rubricVersion: '1',
+ categories: categoriesForScore(92),
+ findings: [],
+ topFixes: [],
+ evidence: [],
+ notes: '',
+ });
+ });
+
+ it('replaces a historical payload and re-derives the grade', () => {
+ const row = applyScorecard(
+ audit({
+ score: 95,
+ recordedGrade: 'Legacy A',
+ pr: 42,
+ findings: ['Stale historical finding.'],
+ }),
+ scorecard({score: 65}),
+ {id: 'page/centered-hero'},
+ );
+ expect(row.grade).toBe('C');
+ expect(row.findings).toEqual(['One raw wrapper remains.']);
+ expect(row).not.toHaveProperty('recordedGrade');
+ expect(row).not.toHaveProperty('pr');
+ });
+
+ it('rejects unknown fields, contradictory grades, and missing required provenance', () => {
+ expect(() =>
+ applyScorecard(null, scorecard({socre: 81}), {id: 'page/centered-hero'}),
+ ).toThrow(/unknown.*socre/i);
+ expect(() =>
+ applyScorecard(null, scorecard({grade: 'A'}), {id: 'page/centered-hero'}),
+ ).toThrow(/grade.*contradicts.*score|expected B/i);
+ for (const field of ['score', 'lastAudited', 'commit', 'rubricVersion']) {
+ const partial = scorecard();
+ delete partial[field];
+ expect(
+ () => applyScorecard(null, partial, {id: 'page/centered-hero'}),
+ field,
+ ).toThrow(new RegExp(field, 'i'));
+ }
+ });
+});
+
+describe('template ids, roster, queue, and stats', () => {
+ it('discovers sorted, unique page and block ids with their code and docs', () => {
+ const templates = listTemplates(REPO_ROOT);
+ const ids = templates.map(template => template.id);
+ expect(ids).toEqual([...ids].sort((a, b) => a.localeCompare(b)));
+ expect(new Set(ids).size).toBe(ids.length);
+ expect(ids).toContain('page/centered-hero');
+ expect(ids).toContain('block/PowerSearchShowcase');
+ expect(ids.every(id => /^(page|block)\/[^/]+$/.test(id))).toBe(true);
+
+ expect(
+ templates.find(template => template.id === 'page/centered-hero'),
+ ).toMatchObject({
+ type: 'page',
+ slug: 'centered-hero',
+ codePath: expect.stringMatching(/centered-hero\/page\.tsx$/),
+ docPath: expect.stringMatching(/centered-hero\/template\.doc\.mjs$/),
+ });
+ expect(
+ templates.find(template => template.id === 'block/PowerSearchShowcase'),
+ ).toMatchObject({
+ type: 'block',
+ slug: 'PowerSearchShowcase',
+ codePath: expect.stringMatching(/PowerSearch\/PowerSearchShowcase\.tsx$/),
+ docPath: expect.stringMatching(
+ /PowerSearch\/PowerSearchShowcase\.doc\.mjs$/,
+ ),
+ });
+ });
+
+ const templates = [
+ {
+ id: 'block/AlphaShowcase',
+ type: 'block',
+ slug: 'AlphaShowcase',
+ codePath: '/tmp/AlphaShowcase.tsx',
+ docPath: '/tmp/AlphaShowcase.doc.mjs',
+ },
+ {
+ id: 'page/zeta',
+ type: 'page',
+ slug: 'zeta',
+ codePath: '/tmp/zeta/page.tsx',
+ docPath: '/tmp/zeta/template.doc.mjs',
+ },
+ {
+ id: 'page/beta',
+ type: 'page',
+ slug: 'beta',
+ codePath: '/tmp/beta/page.tsx',
+ docPath: '/tmp/beta/template.doc.mjs',
+ },
+ ];
+ const ledger = ledgerWith(
+ audit({id: 'page/zeta', lastAudited: '2026-07-01'}),
+ audit({id: 'page/beta', score: 42, grade: 'D', lastAudited: '2026-06-01'}),
+ audit({id: 'page/deleted', score: 95, grade: 'A'}),
+ );
+
+ it('joins live templates to scores and preserves orphan rows for cleanup', () => {
+ const roster = buildRoster(ledger, templates);
+ expect(roster.find(row => row.id === 'block/AlphaShowcase')).toMatchObject({
+ live: true,
+ audit: null,
+ });
+ expect(roster.find(row => row.id === 'page/zeta').audit.score).toBe(81);
+ expect(roster.find(row => row.id === 'page/deleted').live).toBe(false);
+ });
+
+ it('queues unaudited templates first, then oldest audits, and honours the limit', () => {
+ const queue = buildQueue(buildRoster(ledger, templates));
+ expect(queue[0]).toMatchObject({
+ id: 'block/AlphaShowcase',
+ why: 'never audited',
+ });
+ expect(queue.slice(1, 3).map(row => row.id)).toEqual([
+ 'page/beta',
+ 'page/zeta',
+ ]);
+ expect(buildQueue(buildRoster(ledger, templates), 2)).toHaveLength(2);
+ });
+
+ it('summarises coverage, grades, and page/block coverage', () => {
+ const stats = buildStats(buildRoster(ledger, templates));
+ expect(stats).toMatchObject({
+ total: 3,
+ audited: 2,
+ unaudited: 1,
+ percentAudited: expect.closeTo(66.7, 1),
+ grades: {A: 0, B: 1, C: 0, D: 1, F: 0},
+ byType: {
+ page: {total: 2, audited: 2},
+ block: {total: 1, audited: 0},
+ },
+ });
+ });
+});
+
+describe('commit messages', () => {
+ it('names the full id, derived grade, score, and rubric version', () => {
+ expect(commitMessage(audit()).subject).toBe(
+ 'template scores: page/centered-hero B (81.0), rubric 1',
+ );
+ });
+
+ it('keeps an allowed regression reason in the commit body, not the row schema', () => {
+ const row = audit({score: 75, grade: 'B'});
+ const message = commitMessage(row, {
+ regression: {
+ reason: 're-audited after the rubric tightened',
+ from: 95,
+ },
+ });
+ expect(message.body).toContain(
+ 'Regression allowed: re-audited after the rubric tightened',
+ );
+ expect(message.body).toMatch(/95\.0.*75\.0/s);
+ expect(row).not.toHaveProperty('regression');
+ });
+});
+
+const git = (cwd, ...argv) =>
+ execFileSync('git', argv, {
+ cwd,
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ }).trim();
+
+function cli(argv, {cwd = REPO_ROOT, input, env} = {}) {
+ try {
+ const out = execFileSync(process.execPath, [SCRIPT, ...argv], {
+ cwd,
+ input,
+ encoding: 'utf8',
+ env: {...process.env, ...env},
+ stdio: ['pipe', 'pipe', 'pipe'],
+ });
+ return {code: 0, out};
+ } catch (error) {
+ return {
+ code: error.status ?? 1,
+ out: `${error.stdout || ''}${error.stderr || ''}`,
+ };
+ }
+}
+
+function identify(directory) {
+ git(directory, 'config', 'user.name', 'Template Ledger Test');
+ git(directory, 'config', 'user.email', '[email protected]');
+}
+
+function makeWiki(seedLedger) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'template-ledger-wiki-'));
+ const bare = path.join(root, 'wiki.git');
+ const seed = path.join(root, 'seed');
+ const clone = path.join(root, 'clone');
+
+ git(root, 'init', '--bare', '--initial-branch=master', bare);
+ git(root, 'clone', bare, seed);
+ identify(seed);
+ fs.writeFileSync(
+ path.join(seed, TEMPLATE_LEDGER_FILENAME),
+ `${JSON.stringify(seedLedger, null, 2)}\n`,
+ );
+ git(seed, 'add', '-A');
+ git(seed, 'commit', '-m', 'seed');
+ git(seed, 'push', 'origin', WIKI_BRANCH);
+
+ git(root, 'clone', '--depth', '1', `file://${bare}`, clone);
+ identify(clone);
+ return {
+ root,
+ bare,
+ clone,
+ ledger: path.join(clone, TEMPLATE_LEDGER_FILENAME),
+ };
+}
+
+const readLedger = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+const remoteLedger = bare =>
+ JSON.parse(git(bare, 'show', `${WIKI_BRANCH}:${TEMPLATE_LEDGER_FILENAME}`));
+
+describe('--record', () => {
+ it('records an id from stdin into a local ledger', () => {
+ const wiki = makeWiki(ledgerWith());
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ ],
+ {input: JSON.stringify(scorecard())},
+ );
+ expect(result.code, result.out).toBe(0);
+ expect(readLedger(wiki.ledger).templates).toContainEqual(
+ audit({evidence: [{label: 'Rendered audit'}]}),
+ );
+ });
+
+ it('refuses a score regression and leaves the ledger byte-for-byte unchanged', () => {
+ const wiki = makeWiki(ledgerWith(audit({score: 95, grade: 'A'})));
+ const before = fs.readFileSync(wiki.ledger, 'utf8');
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ ],
+ {input: JSON.stringify(scorecard({score: 75}))},
+ );
+ expect(result.code).toBe(1);
+ expect(result.out).toMatch(/refus|regress|decreas/i);
+ expect(fs.readFileSync(wiki.ledger, 'utf8')).toBe(before);
+ });
+
+ it('allows a reasoned regression without adding an out-of-schema field', () => {
+ const wiki = makeWiki(ledgerWith(audit({score: 95, grade: 'A'})));
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ '--allow-regression',
+ 'rubric tightened after screenshot review',
+ ],
+ {input: JSON.stringify(scorecard({score: 75}))},
+ );
+ expect(result.code, result.out).toBe(0);
+ const row = readLedger(wiki.ledger).templates[0];
+ expect(row).toMatchObject({score: 75, grade: 'B'});
+ expect(row).not.toHaveProperty('regression');
+ });
+
+ it('rejects a bare --allow-regression because the explanation is required', () => {
+ const wiki = makeWiki(ledgerWith(audit({score: 95, grade: 'A'})));
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ '--allow-regression',
+ ],
+ {input: JSON.stringify(scorecard({score: 75}))},
+ );
+ expect(result.code).toBe(1);
+ expect(result.out).toMatch(/needs? a reason/i);
+ });
+
+ it('--dry-run prints the diff and commit message without changing the file', () => {
+ const wiki = makeWiki(ledgerWith());
+ const before = fs.readFileSync(wiki.ledger, 'utf8');
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ '--dry-run',
+ ],
+ {input: JSON.stringify(scorecard())},
+ );
+ expect(result.code, result.out).toBe(0);
+ expect(result.out).toContain('--- a/template-scores.json');
+ expect(result.out).toContain('+ "id": "page/centered-hero"');
+ expect(result.out).toContain(
+ 'template scores: page/centered-hero B (81.0), rubric 1',
+ );
+ expect(result.out).toMatch(/nothing written/i);
+ expect(fs.readFileSync(wiki.ledger, 'utf8')).toBe(before);
+ });
+
+ it('refuses to create a partial ledger at a nonexistent local path', () => {
+ const root = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'template-ledger-missing-'),
+ );
+ const ledger = path.join(root, TEMPLATE_LEDGER_FILENAME);
+ const result = cli(
+ ['--record', 'page/centered-hero', '--from', '-', '--ledger', ledger],
+ {input: JSON.stringify(scorecard())},
+ );
+ expect(result.code).toBe(1);
+ expect(result.out).toMatch(/refusing to create a partial one-row ledger/i);
+ expect(fs.existsSync(ledger)).toBe(false);
+ });
+});
+
+describe('--record --push', () => {
+ it('commits and pushes the single ledger file', () => {
+ const wiki = makeWiki(ledgerWith());
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ '--push',
+ ],
+ {input: JSON.stringify(scorecard())},
+ );
+ expect(result.code, result.out).toBe(0);
+ expect(remoteLedger(wiki.bare).templates.map(row => row.id)).toEqual([
+ 'page/centered-hero',
+ ]);
+ expect(git(wiki.clone, 'log', '-1', '--format=%s')).toBe(
+ 'template scores: page/centered-hero B (81.0), rubric 1',
+ );
+ });
+
+ it('refuses to commit without a configured git identity', () => {
+ const wiki = makeWiki(ledgerWith());
+ git(wiki.clone, 'config', '--unset', 'user.name');
+ git(wiki.clone, 'config', '--unset', 'user.email');
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ '--push',
+ ],
+ {
+ input: JSON.stringify(scorecard()),
+ env: {GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null'},
+ },
+ );
+ expect(result.code).toBe(1);
+ expect(result.out).toContain('no git identity');
+ });
+
+ it('refuses to sweep unrelated wiki changes into the ledger commit', () => {
+ const wiki = makeWiki(ledgerWith());
+ fs.writeFileSync(
+ path.join(wiki.clone, 'Home.md'),
+ 'unfinished wiki edit\n',
+ );
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ '--push',
+ ],
+ {input: JSON.stringify(scorecard())},
+ );
+ expect(result.code).toBe(1);
+ expect(result.out).toContain('unrelated changes');
+ });
+
+ it('re-applies onto the winner and preserves both records after a push race', () => {
+ const wiki = makeWiki(ledgerWith());
+ const competing = ledgerWith(
+ audit({
+ id: 'block/PowerSearchShowcase',
+ score: 92,
+ grade: 'A',
+ lastAudited: '2026-08-10',
+ }),
+ );
+ const competingFile = path.join(wiki.root, 'competing.json');
+ fs.writeFileSync(competingFile, `${JSON.stringify(competing, null, 2)}\n`);
+
+ const hook = path.join(wiki.bare, 'hooks', 'update');
+ fs.writeFileSync(
+ hook,
+ [
+ '#!/bin/sh',
+ 'set -e',
+ 'marker="$(git rev-parse --git-dir)/raced"',
+ '[ -f "$marker" ] && exit 0',
+ 'touch "$marker"',
+ 'export GIT_AUTHOR_NAME="Other Agent" GIT_AUTHOR_EMAIL="[email protected]"',
+ 'export GIT_COMMITTER_NAME="Other Agent" GIT_COMMITTER_EMAIL="[email protected]"',
+ 'GIT_INDEX_FILE="$(mktemp)"; export GIT_INDEX_FILE',
+ `blob=$(git hash-object -w -- ${JSON.stringify(competingFile).slice(1, -1)})`,
+ 'git read-tree master',
+ 'git update-index --add --cacheinfo 100644,$blob,template-scores.json',
+ 'tree=$(git write-tree)',
+ 'commit=$(git commit-tree $tree -p master -m "template scores: block/PowerSearchShowcase A (92.0), rubric 1")',
+ 'git update-ref refs/heads/master $commit',
+ 'echo "rejected: non-fast-forward (simulated race)" >&2',
+ 'exit 1',
+ ].join('\n'),
+ );
+ fs.chmodSync(hook, 0o755);
+
+ const result = cli(
+ [
+ '--record',
+ 'page/centered-hero',
+ '--from',
+ '-',
+ '--ledger',
+ wiki.ledger,
+ '--push',
+ ],
+ {input: JSON.stringify(scorecard())},
+ );
+ expect(result.code, result.out).toBe(0);
+ expect(result.out).toMatch(/retrying once|re-applying/i);
+ expect(
+ remoteLedger(wiki.bare)
+ .templates.map(row => row.id)
+ .sort(),
+ ).toEqual(['block/PowerSearchShowcase', 'page/centered-hero']);
+ });
+});