Skip to content

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

TypeScript

Component score ledger: audit scores in the wiki, a ratchet, and a browsable page (#4875)

Cindy Zhange92bed9c554b
diff --git a/apps/sandbox/next-env.d.ts b/apps/sandbox/next-env.d.ts
index 588c55e81b..830fb594ca 100644
--- a/apps/sandbox/next-env.d.ts
+++ b/apps/sandbox/next-env.d.ts
@@ -1,7 +1,6 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
/// <reference types="next" />
/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/apps/sandbox/package.json b/apps/sandbox/package.json
index c95b24734d..71de1a7021 100644
--- a/apps/sandbox/package.json
+++ b/apps/sandbox/package.json
@@ -7,7 +7,8 @@
"generate:changelog": "node scripts/generate-changelog.js",
"generate:cli": "node scripts/generate-cli-registry.mjs",
"generate:xle": "node scripts/generate-xle-registry.mjs && node scripts/generate-xle-tokenizer.mjs",
- "generate": "node ../../scripts/sync-templates.js && pnpm generate:changelog && pnpm generate:cli && node scripts/generate-foundation-docs.mjs && pnpm generate:xle",
+ "generate:scores": "node scripts/generate-score-ledger.mjs",
+ "generate": "node ../../scripts/sync-templates.js && pnpm generate:changelog && pnpm generate:cli && node scripts/generate-foundation-docs.mjs && pnpm generate:xle && pnpm generate:scores",
"dev": "pnpm generate && (node ../../scripts/sync-templates.js --watch & next dev)",
"build": "pnpm generate && next build",
"start": "next start",
diff --git a/apps/sandbox/scripts/generate-score-ledger.mjs b/apps/sandbox/scripts/generate-score-ledger.mjs
new file mode 100644
index 0000000000..ec64ccc5a8
--- /dev/null
+++ b/apps/sandbox/scripts/generate-score-ledger.mjs
@@ -0,0 +1,195 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file generate-score-ledger.mjs
+ * @description Generates apps/sandbox/src/generated/componentScores.ts — the
+ * ROSTER of components (read from packages/core/src and packages/lab/src by
+ * the canonical predicate in scripts/score-ledger.mjs) plus a build-time
+ * SNAPSHOT of the audit ledger fetched from the wiki.
+ * @input packages/{core,lab}/src, and the wiki ledger over the network.
+ * @output src/generated/componentScores.ts
+ * @position Sandbox build step, run by `pnpm generate`.
+ *
+ * The two halves come from different places on purpose. The roster is the
+ * packages: a component added today shows up as TBD tomorrow with nobody
+ * maintaining a list. The scores are the wiki: an auditor records one with a
+ * wiki push and no pull request.
+ *
+ * The snapshot exists only so the page is never blank, and so the page still
+ * works when the wiki is unreachable. The page re-fetches the same URL
+ * client-side at runtime, so a score recorded after this build shows up
+ * without a rebuild — and the page labels which of the two you are reading.
+ * If the fetch here fails — offline build, wiki down — the snapshot is null
+ * and the page relies on the live fetch alone; it never fails the build.
+ *
+ * SYNC: When the ledger schema changes, update scripts/score-ledger.mjs and the
+ * Component-Audit-Rubric wiki page too.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {
+ AUDIT_PROMPT,
+ DEFAULT_LEDGER_URL,
+ DEFAULT_REPO,
+ LEDGER_FETCH_TIMEOUT_MS,
+ SECTION_TITLES,
+ SECTION_WEIGHTS,
+ listComponents,
+} from '../../../scripts/score-ledger.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const OUT_DIR = path.resolve(__dirname, '..', 'src', 'generated');
+const OUT_FILE = path.join(OUT_DIR, 'componentScores.ts');
+
+const roster = listComponents(REPO_ROOT);
+
+let snapshot = null;
+let snapshotFetchedAt = null;
+try {
+ // Bounded on purpose. A 404 or a refused connection lands in the catch
+ // immediately, but a STALLED connection would not: a bare fetch inherits
+ // undici's defaults, whose headers timeout is measured in minutes. This step
+ // is on the critical path of every sandbox build, including the stable
+ // /sandbox/ deploy from main, so "never fail the build over this" has to
+ // cover hanging too — five seconds is generous for one small static file.
+ const res = await fetch(DEFAULT_LEDGER_URL, {
+ redirect: 'follow',
+ signal: AbortSignal.timeout(5000),
+ });
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ const parsed = JSON.parse(await res.text());
+ if (!Array.isArray(parsed.components)) throw new Error('missing a components array');
+ snapshot = parsed;
+ snapshotFetchedAt = new Date().toISOString();
+ console.log(
+ `componentScores: snapshot of ${parsed.components.length} audited component(s) from the wiki`,
+ );
+} catch (e) {
+ // Never fail the build over this — and never hang it either. The page
+ // fetches the same URL at runtime and says which copy it is showing.
+ const why = e.name === 'TimeoutError' ? 'no response within 5000ms' : e.message;
+ console.warn(
+ `componentScores: could not snapshot the ledger (${why}) — the page will rely on its runtime fetch.`,
+ );
+}
+
+const banner = `// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * GENERATED FILE — do not edit.
+ * Regenerate: node apps/sandbox/scripts/generate-score-ledger.mjs
+ *
+ * \`roster\` is read from packages/{core,lab}/src by the canonical component
+ * predicate. \`snapshot\` is a build-time copy of the wiki ledger, used only
+ * until the page's runtime fetch of LEDGER_URL resolves.
+ */
+`;
+
+const source = `${banner}
+export interface LedgerBlock {
+ /** Rubric rule id, e.g. \`A8\` or \`T6\`. */
+ id: string;
+ summary: string;
+ section?: string;
+ evidence?: string;
+ /** The \`hardening\` issue filed for this BLOCK, or null if none is filed. */
+ issue: number | null;
+}
+
+export interface LedgerSection {
+ score: number | null;
+ weight: number;
+ state: 'scored' | 'limited' | 'not_measured' | 'na' | 'unpublished';
+ note?: string | null;
+ blocks?: LedgerBlock[];
+}
+
+export interface LedgerEntry {
+ component: string;
+ package: string;
+ status: 'audited';
+ score: number | null;
+ grade: 'A' | 'B' | 'C' | 'D' | 'F' | null;
+ sections: Record<string, LedgerSection>;
+ blocks: {count: number; open: LedgerBlock[]};
+ distinct_defects: number | null;
+ fixes: number | null;
+ nits: number | null;
+ lastAudited: string | null;
+ rubricVersion: string | null;
+ mode: string | null;
+ commit: string | null;
+ evidence?: Array<{label: string; path?: string; note?: string}>;
+ notes?: string;
+}
+
+export interface Ledger {
+ ledgerVersion: number;
+ rubricVersion: string;
+ updated: string;
+ about?: string;
+ caveats?: string[];
+ components: LedgerEntry[];
+}
+
+export interface RosterEntry {
+ component: string;
+ package: string;
+}
+
+/** The wiki ledger, fetched client-side so the page never needs a rebuild. */
+export const LEDGER_URL = ${JSON.stringify(DEFAULT_LEDGER_URL)};
+
+/**
+ * How long the page waits for that fetch before falling back to the snapshot.
+ * Shared with the CLI so there is one number: a stalled connection never
+ * rejects on its own, and a page stuck on "checking" is the same dishonesty
+ * the freshness indicator exists to prevent.
+ */
+export const LEDGER_FETCH_TIMEOUT_MS = ${JSON.stringify(LEDGER_FETCH_TIMEOUT_MS)};
+
+/** Where audit issues live. */
+export const REPO = ${JSON.stringify(DEFAULT_REPO)};
+
+export const RUBRIC_URL = ${JSON.stringify(
+ `https://github.com/${DEFAULT_REPO}/wiki/Component-Audit-Rubric`,
+)};
+
+/**
+ * The ledger file in the wiki. It is the ONLY stored form of the scores —
+ * there is no generated table page to link at, on purpose: a second copy goes
+ * stale the moment the JSON changes without a regeneration.
+ */
+export const LEDGER_WIKI_URL = ${JSON.stringify(DEFAULT_LEDGER_URL)};
+
+/** The paste-to-an-agent request for an audit. Shared with the CLI. */
+export const AUDIT_PROMPT = ${JSON.stringify(AUDIT_PROMPT)};
+
+export const SECTION_TITLES: Record<string, string> = ${JSON.stringify(SECTION_TITLES, null, 2)};
+
+export const SECTION_WEIGHTS: Record<string, number> = ${JSON.stringify(SECTION_WEIGHTS, null, 2)};
+
+/** Every component in packages/{core,lab}/src, by the canonical predicate. */
+export const roster: RosterEntry[] = ${JSON.stringify(roster, null, 2)};
+
+/**
+ * Build-time copy of the ledger, used ONLY until the runtime fetch resolves and
+ * as the fallback when it fails. Null when the build could not reach the wiki.
+ * The page says which of the two it is showing — a stale page that looks live
+ * is worse than one that admits it.
+ */
+export const snapshot: Ledger | null = ${JSON.stringify(snapshot, null, 2)};
+
+/** When the snapshot above was taken, so the fallback can date itself. */
+export const snapshotFetchedAt: string | null = ${JSON.stringify(snapshotFetchedAt)};
+`;
+
+fs.mkdirSync(OUT_DIR, {recursive: true});
+fs.writeFileSync(OUT_FILE, source);
+console.log(
+ `componentScores: wrote ${path.relative(REPO_ROOT, OUT_FILE)} — ${roster.length} components in the roster`,
+);
diff --git a/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
new file mode 100644
index 0000000000..94f0f34cfd
--- /dev/null
+++ b/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
@@ -0,0 +1,570 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useEffect, useMemo, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {VStack, HStack} from '@astryxdesign/core/Layout';
+import {Text, Heading} from '@astryxdesign/core/Text';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {Button} from '@astryxdesign/core/Button';
+import {Badge} from '@astryxdesign/core/Badge';
+import type {BadgeVariant} from '@astryxdesign/core/Badge';
+import {Card} from '@astryxdesign/core/Card';
+import {Link} from '@astryxdesign/core/Link';
+import {Code} from '@astryxdesign/core/Code';
+import {Table, proportional, pixel} from '@astryxdesign/core/Table';
+import type {TableColumn} from '@astryxdesign/core/Table';
+
+import {
+ AUDIT_PROMPT,
+ LEDGER_FETCH_TIMEOUT_MS,
+ LEDGER_URL,
+ LEDGER_WIKI_URL,
+ REPO,
+ RUBRIC_URL,
+ SECTION_TITLES,
+ roster,
+ snapshot,
+ snapshotFetchedAt,
+ type Ledger,
+ type LedgerBlock,
+ type LedgerEntry,
+} from '../../../../generated/componentScores';
+
+// =============================================================================
+// Row model — the roster joined with whatever the ledger knows
+// =============================================================================
+
+interface ScoreRow extends Record<string, unknown> {
+ id: string;
+ component: string;
+ package: string;
+ audited: boolean;
+ score: number | null;
+ grade: string | null;
+ blocks: number;
+ blockList: LedgerBlock[];
+ lastAudited: string | null;
+ rubricVersion: string | null;
+ weakest: string | null;
+ entry: LedgerEntry | null;
+}
+
+const GRADE_VARIANT: Record<string, BadgeVariant> = {
+ A: 'success',
+ B: 'success',
+ C: 'warning',
+ D: 'warning',
+ F: 'error',
+};
+
+/** The lowest section carrying a published per-section score. */
+function weakestSection(entry: LedgerEntry): string | null {
+ let worst: {id: string; score: number} | null = null;
+ for (const [id, section] of Object.entries(entry.sections || {})) {
+ if (section.state !== 'scored' || typeof section.score !== 'number') {
+ continue;
+ }
+ if (!worst || section.score < worst.score) {
+ worst = {id, score: section.score};
+ }
+ }
+ return worst
+ ? `${SECTION_TITLES[worst.id] ?? worst.id} (${worst.score}/5)`
+ : null;
+}
+
+function buildRows(ledger: Ledger | null): ScoreRow[] {
+ const byId = new Map<string, LedgerEntry>();
+ for (const entry of ledger?.components ?? []) {
+ byId.set(`${entry.package}/${entry.component}`, entry);
+ }
+
+ return roster
+ .map(item => {
+ const entry = byId.get(`${item.package}/${item.component}`) ?? null;
+ return {
+ // `Chat` exists in both core and lab, so the row key is the pair.
+ id: `${item.package}/${item.component}`,
+ component: item.component,
+ package: item.package,
+ audited: entry != null,
+ score: entry?.score ?? null,
+ grade: entry?.grade ?? null,
+ blocks: entry?.blocks?.count ?? 0,
+ blockList: entry?.blocks?.open ?? [],
+ lastAudited: entry?.lastAudited ?? null,
+ rubricVersion: entry?.rubricVersion ?? null,
+ weakest: entry ? weakestSection(entry) : null,
+ entry,
+ };
+ })
+ .sort(
+ (a, b) =>
+ a.component.localeCompare(b.component) ||
+ a.package.localeCompare(b.package),
+ );
+}
+
+// =============================================================================
+// Copy-to-clipboard
+// =============================================================================
+
+function CopyButton({
+ text,
+ label = 'Copy',
+ size = 'sm',
+}: {
+ text: string;
+ label?: string;
+ size?: 'sm' | 'md';
+}) {
+ const [copied, setCopied] = useState(false);
+ return (
+ <Button
+ variant="secondary"
+ size={size}
+ label={copied ? 'Copied' : label}
+ onClick={() => {
+ void navigator.clipboard.writeText(text).then(() => {
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1600);
+ });
+ }}
+ />
+ );
+}
+
+/** The audit request for one component, with the placeholder filled in. */
+const promptFor = (component: string) =>
+ AUDIT_PROMPT.replaceAll('<Component>', component);
+
+// =============================================================================
+// Freshness
+// =============================================================================
+
+/**
+ * Which copy is on screen, said out loud. A stale page that looks live is worse
+ * than one that admits it, so this is a Badge next to the numbers rather than a
+ * line of small print underneath them.
+ */
+function FreshnessBadge({
+ source,
+ updated,
+}: {
+ source: LedgerSource;
+ updated: string | null;
+}) {
+ const snapshotDate = snapshotFetchedAt?.slice(0, 10) ?? null;
+ const state = {
+ loading: {
+ variant: 'neutral' as BadgeVariant,
+ label: 'Checking the wiki…',
+ detail:
+ 'Reading the ledger from the wiki. The build-time copy is showing meanwhile.',
+ },
+ live: {
+ variant: 'success' as BadgeVariant,
+ label: 'Live',
+ detail: updated
+ ? `Fetched from the wiki ledger just now; the ledger was last written ${updated}.`
+ : 'Fetched from the wiki ledger just now.',
+ },
+ snapshot: {
+ variant: 'warning' as BadgeVariant,
+ label: snapshotDate ? `Snapshot from ${snapshotDate}` : 'Snapshot',
+ detail:
+ 'The wiki could not be reached, so this is the copy taken when the site was built. ' +
+ 'Scores recorded since then are not on this page.',
+ },
+ none: {
+ variant: 'error' as BadgeVariant,
+ label: 'No ledger',
+ detail:
+ 'Neither the live fetch nor a build-time snapshot resolved. Every component reads TBD — ' +
+ 'that is this page failing, not 118 unaudited components.',
+ },
+ }[source];
+
+ return (
+ <HStack gap={2} vAlign="center" wrap="wrap">
+ <Badge variant={state.variant} label={state.label} />
+ <Text type="supporting" color="secondary">
+ {state.detail}
+ </Text>
+ </HStack>
+ );
+}
+
+// =============================================================================
+// No sticky header — a Table limitation, measured
+//
+// 118 rows want a pinned header, and Table has no `isHeaderSticky`. A sticky
+// `<th>` cannot supply one from outside the component either, because
+// `position: sticky` resolves against the nearest scroll container and Table's
+// scroll wrapper is unconditionally one in BOTH axes: it sets `overflow-x:
+// auto` (which it needs, so a wide table survives 390px), and that forces the
+// block axis to compute to `auto` too. `overflow-y: clip` does not escape it —
+// paired with `auto` it computes to `hidden`, which is still a scroll
+// container. Measured in Chromium, not reasoned about: with the page scrolled
+// 1200px the header sat at -907, unpinned, either way.
+//
+// So the header can only pin while the WRAPPER is the vertical scroller — i.e.
+// while the table has a capped height, which is the nested-scrollbar shape we
+// deliberately removed. Page-scroll and a sticky header are mutually exclusive
+// until Table grows the prop. Left undone rather than hand-rolled around; see
+// the PR description.
+// =============================================================================
+
+// =============================================================================
+// Page
+// =============================================================================
+
+type Filter = 'all' | 'audited' | 'tbd' | 'blocks';
+
+const FILTERS: Array<{value: Filter; label: string}> = [
+ {value: 'all', label: 'All'},
+ {value: 'audited', label: 'Audited'},
+ {value: 'tbd', label: 'TBD'},
+ {value: 'blocks', label: 'With open BLOCKs'},
+];
+
+/**
+ * Which copy of the ledger is on screen. `loading` matters: without it the page
+ * claims "snapshot" for the few hundred milliseconds before the fetch lands,
+ * which is the same lie in the other direction.
+ */
+type LedgerSource = 'loading' | 'live' | 'snapshot' | 'none';
+
+export default function ComponentScoresPage() {
+ const [ledger, setLedger] = useState<Ledger | null>(snapshot);
+ const [source, setSource] = useState<LedgerSource>('loading');
+ const [query, setQuery] = useState('');
+ const [filter, setFilter] = useState<Filter>('all');
+
+ // The ledger is a wiki file served with `access-control-allow-origin: *`, so
+ // this page reads current scores without a rebuild. The build-time snapshot
+ // is only there so nothing is ever blank while this resolves — and so the
+ // page still works when the wiki is unreachable.
+ //
+ // `no-store`: raw.githubusercontent serves the ledger with `max-age=300`, so
+ // the default cache would happily hand back a five-minute-old copy and the
+ // page would call it live. A page that says "live" has to have asked.
+ //
+ // Bounded, for the same reason the indicator exists at all: a stalled
+ // connection never rejects, so without this the badge would sit on
+ // "Checking the wiki…" forever rather than admitting it is showing the
+ // snapshot. One controller serves both the timeout and unmount.
+ useEffect(() => {
+ let cancelled = false;
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), LEDGER_FETCH_TIMEOUT_MS);
+
+ fetch(LEDGER_URL, {cache: 'no-store', signal: controller.signal})
+ .then(res =>
+ res.ok ? res.json() : Promise.reject(new Error(String(res.status))),
+ )
+ .then((data: Ledger) => {
+ if (cancelled) {
+ return;
+ }
+ if (!Array.isArray(data.components)) {
+ throw new Error('not a ledger');
+ }
+ setLedger(data);
+ setSource('live');
+ })
+ .catch(() => {
+ if (!cancelled) {
+ setSource(snapshot ? 'snapshot' : 'none');
+ }
+ })
+ .finally(() => clearTimeout(timer));
+
+ return () => {
+ cancelled = true;
+ clearTimeout(timer);
+ controller.abort();
+ };
+ }, []);
+
+ const rows = useMemo(() => buildRows(ledger), [ledger]);
+
+ const stats = useMemo(() => {
+ const audited = rows.filter(r => r.audited);
+ const grades: Record<string, number> = {A: 0, B: 0, C: 0, D: 0, F: 0};
+ for (const r of audited) {
+ if (r.grade && r.grade in grades) {
+ grades[r.grade] += 1;
+ }
+ }
+ return {
+ total: rows.length,
+ audited: audited.length,
+ percent: rows.length
+ ? Math.round((audited.length / rows.length) * 1000) / 10
+ : 0,
+ grades,
+ openBlocks: audited.reduce((sum, r) => sum + r.blocks, 0),
+ filedIssues: audited.reduce(
+ (sum, r) => sum + r.blockList.filter(b => b.issue).length,
+ 0,
+ ),
+ };
+ }, [rows]);
+
+ const visible = useMemo(() => {
+ const q = query.trim().toLowerCase();
+ return rows.filter(r => {
+ if (q && !r.component.toLowerCase().includes(q)) {
+ return false;
+ }
+ if (filter === 'audited') {
+ return r.audited;
+ }
+ if (filter === 'tbd') {
+ return !r.audited;
+ }
+ if (filter === 'blocks') {
+ return r.blocks > 0;
+ }
+ return true;
+ });
+ }, [rows, query, filter]);
+
+ const columns: TableColumn<ScoreRow>[] = [
+ {
+ key: 'component',
+ header: 'Component',
+ width: proportional(3),
+ renderCell: (row: ScoreRow) => (
+ <VStack gap={1}>
+ <Text weight="medium">{row.component}</Text>
+ <Text type="supporting" color="secondary">
+ {row.package}
+ </Text>
+ </VStack>
+ ),
+ },
+ {
+ key: 'grade',
+ header: 'Grade',
+ width: pixel(88),
+ renderCell: (row: ScoreRow) =>
+ row.grade ? (
+ <Badge
+ variant={GRADE_VARIANT[row.grade] ?? 'neutral'}
+ label={row.grade}
+ />
+ ) : (
+ <Badge label="TBD" />
+ ),
+ },
+ {
+ key: 'score',
+ header: 'Score',
+ width: pixel(80),
+ renderCell: (row: ScoreRow) => (
+ <Text>
+ {typeof row.score === 'number' ? row.score.toFixed(1) : '—'}
+ </Text>
+ ),
+ },
+ {
+ key: 'blocks',
+ header: 'Open BLOCKs',
+ width: proportional(2),
+ renderCell: (row: ScoreRow) => {
+ if (!row.audited) {
+ return <Text color="secondary">—</Text>;
+ }
+ if (row.blocks === 0) {
+ return <Text>0</Text>;
+ }
+ const filed = row.blockList.filter(b => b.issue);
+ const unattributed = row.blocks - row.blockList.length;
+ return (
+ <HStack gap={2} vAlign="center" wrap="wrap">
+ <Badge variant="error" label={String(row.blocks)} />
+ {filed.map(block => (
+ <Link
+ key={`${row.id}-${block.id}`}
+ href={`https://github.com/${REPO}/issues/${block.issue}`}
+ isExternalLink
+ type="supporting">
+ {block.id} #{block.issue}
+ </Link>
+ ))}
+ {row.blockList
+ .filter(b => !b.issue)
+ .map(block => (
+ <Text
+ key={`${row.id}-${block.id}`}
+ type="supporting"
+ color="secondary">
+ {block.id} (no issue)
+ </Text>
+ ))}
+ {unattributed > 0 ? (
+ <Text type="supporting" color="secondary">
+ +{unattributed} unattributed
+ </Text>
+ ) : null}
+ </HStack>
+ );
+ },
+ },
+ {
+ key: 'weakest',
+ header: 'Weakest section',
+ width: proportional(2),
+ renderCell: (row: ScoreRow) => (
+ <Text type="supporting" color="secondary">
+ {row.weakest ?? '—'}
+ </Text>
+ ),
+ },
+ {
+ key: 'lastAudited',
+ header: 'Last audited',
+ width: pixel(136),
+ renderCell: (row: ScoreRow) =>
+ row.audited ? (
+ <VStack gap={1}>
+ <Text type="supporting">{row.lastAudited}</Text>
+ <Text type="supporting" color="secondary">
+ rubric v{row.rubricVersion}
+ </Text>
+ </VStack>
+ ) : (
+ <Text type="supporting" color="secondary">
+ never
+ </Text>
+ ),
+ },
+ {
+ key: 'action',
+ header: 'Audit',
+ // Wide enough for the button plus the cell's own padding: at pixel(150)
+ // the 162px control was clipped on every row.
+ width: pixel(190),
+ renderCell: (row: ScoreRow) => (
+ <CopyButton
+ text={promptFor(row.component)}
+ label={row.audited ? 'Copy re-audit prompt' : 'Copy audit prompt'}
+ />
+ ),
+ },
+ ];
+
+ return (
+ // AppShell renders sandbox pages with `contentPadding={0}`, so the page owns
+ // its own gutters — without them the content ran flush to both viewport
+ // edges and the last column's button was clipped off the right. `maxWidth`
+ // caps the measure: unconstrained, the table stretched to 2300px on a
+ // 2560px monitor, which puts a component's name and its grade a foot apart.
+ <VStack gap={5} padding={6} maxWidth={1600} width="100%">
+ <VStack gap={2} maxWidth="72ch">
+ <Heading level={1}>Component scores</Heading>
+ <Text>
+ Every component in <Code>packages/core/src</Code> and{' '}
+ <Code>packages/lab/src</Code>, joined with the audit ledger kept in{' '}
+ <Link href={LEDGER_WIKI_URL} isExternalLink>
+ the wiki
+ </Link>
+ . <strong>TBD</strong> means nobody has audited it yet — not that the
+ component is bad.
+ </Text>
+ <Link href={RUBRIC_URL} isExternalLink>
+ How components are graded, and how to get one audited
+ </Link>
+ </VStack>
+
+ <VStack gap={2}>
+ <HStack gap={6} wrap="wrap" vAlign="center">
+ <Stat label="Audited" value={`${stats.audited} / ${stats.total}`} />
+ <Stat label="Coverage" value={`${stats.percent}%`} />
+ <Stat label="Open BLOCKs" value={String(stats.openBlocks)} />
+ <Stat
+ label="BLOCKs with an issue"
+ value={String(stats.filedIssues)}
+ />
+ <Stat
+ label="Grades"
+ value={`A ${stats.grades.A} · B ${stats.grades.B} · C ${stats.grades.C} · D ${stats.grades.D} · F ${stats.grades.F}`}
+ />
+ </HStack>
+ <FreshnessBadge source={source} updated={ledger?.updated ?? null} />
+ </VStack>
+
+ <VStack gap={3}>
+ <HStack gap={3} vAlign="end" wrap="wrap">
+ <TextInput
+ label="Filter components"
+ isLabelHidden
+ placeholder="Filter components…"
+ value={query}
+ onChange={setQuery}
+ />
+ {FILTERS.map(({value, label}) => (
+ <Button
+ key={value}
+ size="sm"
+ variant={filter === value ? 'primary' : 'ghost'}
+ label={label}
+ onClick={() => setFilter(value)}
+ />
+ ))}
+ <Text type="supporting" color="secondary">
+ {visible.length} of {rows.length}
+ </Text>
+ </HStack>
+
+ <Table<ScoreRow>
+ data={visible}
+ columns={columns}
+ idKey="id"
+ density="balanced"
+ dividers="rows"
+ hasHover
+ />
+ </VStack>
+
+ {ledger?.caveats?.length ? (
+ <Card>
+ <VStack gap={3}>
+ <Heading level={2}>Caveats on the recorded rows</Heading>
+ <VStack gap={2}>
+ {ledger.caveats.map(caveat => (
+ <Text key={caveat} type="supporting" color="secondary">
+ {caveat}
+ </Text>
+ ))}
+ </VStack>
+ </VStack>
+ </Card>
+ ) : null}
+ </VStack>
+ );
+}
+
+function Stat({label, value}: {label: string; value: string}) {
+ return (
+ <VStack gap={1}>
+ <Text type="supporting" color="secondary">
+ {label}
+ </Text>
+ <Text type="large" xstyle={styles.statValue}>
+ {value}
+ </Text>
+ </VStack>
+ );
+}
+
+const styles = stylex.create({
+ statValue: {
+ fontVariantNumeric: 'tabular-nums',
+ },
+});
diff --git a/apps/sandbox/src/app/SandboxNav.tsx b/apps/sandbox/src/app/SandboxNav.tsx
index f78dad6ef3..5a31fabe67 100644
--- a/apps/sandbox/src/app/SandboxNav.tsx
+++ b/apps/sandbox/src/app/SandboxNav.tsx
@@ -10,7 +10,8 @@ import {DropdownMenu} from '@astryxdesign/core/DropdownMenu';
import {Text} from '@astryxdesign/core/Text';
import {useThemeControls, SANDBOX_THEMES} from './providers';
import type {ThemeMode} from '@astryxdesign/core/theme';
-import {categories} from './sandboxPages';
+import type {IconName, IconType} from '@astryxdesign/core/Icon';
+import {categories, topLevelPages} from './sandboxPages';
import {
HomeIcon,
WrenchIcon,
@@ -34,6 +35,24 @@ const categoryIcons: Record<
tools: WrenchIcon,
};
+/**
+ * Icons for `topLevelPages`, kept here so that module stays JSX-free — the
+ * same split the categories already use.
+ *
+ * These are icon *types* and semantic *names*, never rendered elements.
+ * `SideNavItem` passes its icon through `renderIconSlot`, which applies the
+ * nav's `size: 'sm'` and its selected/disabled colour to a component type or a
+ * registry name — but hands a ReactNode straight to the DOM untouched. An
+ * `<Icon />` element here therefore renders unsized and uncoloured: a ~400px
+ * black glyph over the whole sidebar. `scores` is a registry name (T17), not a
+ * hand-written SVG.
+ */
+const topLevelIcons: Record<string, IconType | IconName> = {
+ home: HomeIcon,
+ templates: AppWindowIcon,
+ scores: 'checkDouble',
+};
+
const styles = stylex.create({
header: {
display: 'flex',
@@ -126,20 +145,20 @@ export function SandboxNav() {
return (
<SideNav header={<SandboxHeader />}>
<SideNavSection title="Home" isHeaderHidden>
- <SideNavItem
- label="Home"
- href="/"
- isSelected={pathname === '/'}
- as={Link}
- icon={HomeIcon}
- />
- <SideNavItem
- label="Official Templates"
- href="/templates/"
- isSelected={pathname === '/templates/'}
- as={Link}
- icon={AppWindowIcon}
- />
+ {topLevelPages.map(page => (
+ <SideNavItem
+ key={page.href}
+ label={page.label}
+ href={page.href}
+ isSelected={
+ page.matchesChildren
+ ? pathname.startsWith(page.href)
+ : pathname === page.href
+ }
+ as={Link}
+ icon={topLevelIcons[page.icon]}
+ />
+ ))}
</SideNavSection>
<SideNavSection title="Projects">
{categories
diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.ts
index f4836090e5..c2f11f6d50 100644
--- a/apps/sandbox/src/app/sandboxPages.ts
+++ b/apps/sandbox/src/app/sandboxPages.ts
@@ -44,6 +44,40 @@ export interface SandboxCategory {
pages: SandboxPage[];
}
+/**
+ * Sidebar entries that sit ABOVE the `Projects` section, alongside Home —
+ * destinations in their own right rather than pages inside a category.
+ *
+ * These used to be written out in `SandboxNav`; they are data so the next one
+ * is an entry here rather than another branch in the nav component. `icon` is
+ * a key into that file's icon map for the same reason the categories use one:
+ * this module stays JSX-free.
+ */
+export interface SandboxTopLevelPage {
+ /** Label shown in the sidebar */
+ label: string;
+ /** Route path (with trailing slash) */
+ href: string;
+ /** Key into SandboxNav's icon map */
+ icon: string;
+ /**
+ * Match child routes too. Home must not (`/` prefixes everything); a section
+ * with sub-pages should.
+ */
+ matchesChildren?: boolean;
+}
+
+export const topLevelPages: SandboxTopLevelPage[] = [
+ {label: 'Home', href: '/', icon: 'home'},
+ {label: 'Official Templates', href: '/templates/', icon: 'templates'},
+ {
+ label: 'Component Scores',
+ href: '/pages/component-scores/',
+ icon: 'scores',
+ matchesChildren: true,
+ },
+];
+
export const categories: SandboxCategory[] = [
{
label: 'Components & Patterns',
diff --git a/scripts/score-ledger.mjs b/scripts/score-ledger.mjs
new file mode 100644
index 0000000000..edcdbc45be
--- /dev/null
+++ b/scripts/score-ledger.mjs
@@ -0,0 +1,1779 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file score-ledger.mjs
+ * @description The component score ledger — read, record, queue and ratchet the
+ * per-component audit scores produced by the Component Audit Rubric.
+ * @input Subcommand flags (see USAGE below) plus `--ledger <path|url>`.
+ * @output Human-readable summaries on stdout, an updated ledger JSON with
+ * `--record` (pushed to the wiki with `--push`), and a non-zero exit from
+ * `--check` when the ratchet trips.
+ * @position Standalone CLI, and the module every other surface imports.
+ *
+ * Two halves, deliberately separate:
+ * - the ROSTER (which components exist) is derived from the packages here,
+ * by the canonical predicate below — rubric decision #15;
+ * - the SCORES live in the wiki, in `component-scores.json`, because
+ * recording a score must not require a pull request.
+ * A component with no ledger entry is unaudited. Nothing has to maintain a
+ * list of unaudited components: the roster is the packages.
+ *
+ * `component-scores.json` is the ONLY stored form of the ledger. There is no
+ * generated Markdown table: a second copy of the same numbers goes stale the
+ * moment the JSON changes without a regeneration, and a stale score that
+ * looks current is worse than one you have to click through for. The single
+ * view is the sandbox page, which fetches this JSON at runtime.
+ *
+ * SYNC: When the schema changes, update the Component-Audit-Rubric wiki page
+ * and apps/sandbox/scripts/generate-score-ledger.mjs.
+ */
+
+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)), '..');
+
+/** The one stored form of the ledger, at the root of the wiki repo. */
+export const LEDGER_FILENAME = 'component-scores.json';
+
+/** Where the scores live when no `--ledger` is given. */
+export const DEFAULT_LEDGER_URL =
+ 'https://raw.githubusercontent.com/wiki/facebook/astryx/component-scores.json';
+
+/** The wiki repo the ledger lives in — what `--push` clones. */
+export const WIKI_REMOTE = 'https://github.com/facebook/astryx.wiki.git';
+
+/** The wiki's default branch. Not `main`. */
+export const WIKI_BRANCH = 'master';
+
+/**
+ * The one place the ledger is readable by a human: the sandbox page, which
+ * fetches the JSON at runtime. Deployed from `main` by .github/workflows/
+ * deploy.yml to the stable (unversioned) GitHub Pages path — /pr/<n>/ paths
+ * are PR previews and must never be linked from anything durable.
+ */
+export const SCORES_PAGE_URL =
+ 'https://facebook.github.io/astryx/sandbox/pages/component-scores/';
+
+const USAGE = `
+Usage: node scripts/score-ledger.mjs <subcommand> [options]
+
+Subcommands
+ --check Ratchet / standing report for the components a PR touches.
+ --queue The auditor's work queue: unaudited first, then
+ oldest-audited, then lowest-scoring.
+ --stats Distribution summary on the terminal.
+ --record <Component> Write one component's scorecard into the ledger.
+ --file-issues <Component>
+ File one GitHub issue per open BLOCK that has none,
+ via gh, and write the numbers back into the ledger.
+
+Options
+ --ledger <path|url> Ledger source. Default: the wiki raw URL.
+ --record needs a local path, or --push.
+ --base-ledger <path|url> Baseline ledger for --check; enables the ratchet.
+ --components <a,b,c> --check: components to check.
+ --analysis <file> --check: analysis.json from .github/scripts/analyze-pr.js.
+ --limit <n> --queue: how many rows (default 5).
+ --package <core|lab> --record: package, if the predicate cannot resolve it.
+ --from <file|-> --record: scorecard JSON ('-' reads stdin).
+ --allow-regression <why> --record: permit a score drop or a new BLOCK.
+ --push --record/--file-issues: clone the wiki, apply, commit
+ and push. Without --ledger it uses a cached shallow
+ clone; the commit message names the component, the
+ grade and the rubric version.
+ --dry-run --record: print the diff and the commit message and
+ push nothing. --file-issues: print the issues,
+ create nothing.
+ --repo <owner/name> --file-issues: default facebook/astryx.
+ --json Machine-readable output where it applies.
+`.trim();
+
+// ---------------------------------------------------------------------------
+// The rubric's vocabulary. These ids, weights and bands are the rubric's, not
+// this script's — changing one here changes what the ledger claims to measure.
+// ---------------------------------------------------------------------------
+
+/** Section id -> weight, summing to 100. Rubric §2, "Overall grade". */
+export const SECTION_WEIGHTS = Object.freeze({
+ a11y: 16,
+ theming: 14,
+ api: 14,
+ behavior: 12,
+ design_objective: 6,
+ design_rendered: 4,
+ testing: 8,
+ code_health: 8,
+ docs: 8,
+ i18n_rtl: 5,
+ responsive: 5,
+});
+
+/** Section id -> the rubric's own heading. */
+export const SECTION_TITLES = Object.freeze({
+ a11y: '§1 Accessibility & operable paths',
+ theming: '§2 Theming & token integrity',
+ api: '§3 Public API contract',
+ behavior: '§4 Behavior correctness & states',
+ design_objective: '§5a Design conventions — objective',
+ design_rendered: '§5b Design conventions — rendered',
+ testing: '§6 Testing & verification',
+ code_health: '§7 Code health (React & DOM)',
+ docs: '§8 Docs, Storybook & docsite',
+ i18n_rtl: '§9 i18n & RTL',
+ responsive: '§10 Responsive & touch',
+});
+
+export const SECTION_IDS = Object.freeze(Object.keys(SECTION_WEIGHTS));
+
+/**
+ * Section states.
+ * scored — a number was produced from evidence.
+ * limited — fewer than 1/3 of the section's items gave a non-vacuous
+ * verdict; reported for information, weight redistributed.
+ * not_measured — nobody looked (the §5b screenshot gate). Never 0.
+ * na — structurally inapplicable, with a reason.
+ * unpublished — the section WAS audited and is inside `score`, but the audit
+ * of record published only the total. Not one of the rubric's
+ * four states: it exists for the seeded rows, whose calibration
+ * record reported totals only. Inventing the per-section split
+ * would be fabrication, and `not_measured` would be a lie in
+ * the other direction — it would claim nobody looked.
+ */
+export const SECTION_STATES = Object.freeze([
+ 'scored',
+ 'limited',
+ 'not_measured',
+ 'na',
+ 'unpublished',
+]);
+
+/** Rubric §2 grade bands. */
+export const GRADE_BANDS = Object.freeze([
+ {grade: 'A', min: 90},
+ {grade: 'B', min: 80},
+ {grade: 'C', min: 70},
+ {grade: 'D', min: 60},
+ {grade: 'F', min: 0},
+]);
+
+/**
+ * Letter for a score. Any open BLOCK caps the overall grade at C regardless of
+ * arithmetic (rubric §2, grade table).
+ */
+export function gradeFor(score, openBlocks = 0) {
+ if (typeof score !== 'number') return null;
+ const band = GRADE_BANDS.find(b => score >= b.min);
+ const letter = band ? band.grade : 'F';
+ if (openBlocks > 0 && (letter === 'A' || letter === 'B')) return 'C';
+ return letter;
+}
+
+// ---------------------------------------------------------------------------
+// The canonical component predicate — rubric decision #15.
+//
+// "Any sweep over packages/core/src/*/ also hits hooks, theme, utils, i18n,
+// __tests__, SizeContext, InteractiveRoleContext, NavItem. Ship one canonical
+// predicate so all four modes agree on the denominator."
+//
+// This is that predicate. It is structural, not a name list, so a new
+// context-only or styles-only directory is excluded the day it lands.
+// ---------------------------------------------------------------------------
+
+/** Directories under a package src that are infrastructure, never components. */
+export const NON_COMPONENT_DIRS = Object.freeze(
+ new Set(['hooks', 'theme', 'utils', 'i18n', '__tests__']),
+);
+
+/** A file that renders: PascalCase `.tsx`, not a test, story, doc or perf file. */
+const RENDERING_FILE = /^[A-Z][A-Za-z0-9]*\.tsx$/;
+
+/** Packages the ledger covers, with the src dir the predicate sweeps. */
+export const LEDGER_PACKAGES = Object.freeze([
+ {name: 'core', src: 'packages/core/src'},
+ {name: 'lab', src: 'packages/lab/src'},
+]);
+
+/**
+ * Is `dirName`, directly under `srcDir`, a component directory?
+ *
+ * A component directory:
+ * 1. is not one of the infrastructure directories (hooks/theme/utils/i18n/__tests__);
+ * 2. is PascalCase — infrastructure is lowercase by convention;
+ * 3. contains at least one top-level PascalCase `.tsx` file, i.e. something
+ * that actually renders.
+ *
+ * Rule 3 does the real work. It excludes:
+ * - `NavItem` — only `navItemStyles.stylex.ts`, a shared style module;
+ * - `SizeContext` and `InteractiveRoleContext` — `.ts` context modules with a
+ * `.test.tsx` but nothing that renders.
+ * It deliberately does NOT require `index.ts` or a `.doc.mjs`: an unexported or
+ * undocumented component is still a component, and the ledger's job is to say
+ * so rather than to hide it.
+ *
+ * @param {string} srcDir absolute path to `packages/<pkg>/src`
+ * @param {string} dirName the directory entry name
+ * @returns {boolean}
+ */
+export function isComponentDirectory(srcDir, dirName) {
+ if (NON_COMPONENT_DIRS.has(dirName)) return false;
+ if (!/^[A-Z]/.test(dirName)) return false;
+ let entries;
+ try {
+ entries = fs.readdirSync(path.join(srcDir, dirName), {withFileTypes: true});
+ } catch {
+ return false;
+ }
+ return entries.some(e => e.isFile() && RENDERING_FILE.test(e.name));
+}
+
+/**
+ * Every component in the covered packages, sorted by name. This is the ledger's
+ * denominator: it is read from the packages, never from a checked-in list.
+ * @param {string} [repoRoot]
+ * @returns {{component: string, package: string}[]}
+ */
+export function listComponents(repoRoot = ROOT) {
+ const out = [];
+ for (const pkg of LEDGER_PACKAGES) {
+ const srcDir = path.join(repoRoot, pkg.src);
+ let entries;
+ try {
+ entries = fs.readdirSync(srcDir, {withFileTypes: true});
+ } catch {
+ continue;
+ }
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ if (!isComponentDirectory(srcDir, entry.name)) continue;
+ out.push({component: entry.name, package: pkg.name});
+ }
+ }
+ return out.sort((a, b) => a.component.localeCompare(b.component));
+}
+
+// ---------------------------------------------------------------------------
+// Ledger IO
+// ---------------------------------------------------------------------------
+
+const isUrl = source => /^https?:\/\//.test(source);
+
+/**
+ * How long to wait for the wiki before giving up on it.
+ *
+ * A bare `fetch()` inherits undici's defaults, whose headers timeout is
+ * measured in minutes. The failure this guards is not an error — a 404 or a
+ * refused connection already lands in the catch below — but a STALL: a
+ * connection that opens and then goes quiet. Unbounded, that hangs a CI build
+ * or a terminal instead of falling through to the path that already handles
+ * "no ledger". Generous for a static file of a few tens of KB.
+ */
+export const LEDGER_FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * Read a ledger from a path or an http(s) URL.
+ * Never throws: a fetch, timeout or parse failure resolves to
+ * `{ledger: null, error}` so a caller in CI can degrade to a warning instead of
+ * failing a pull request on network flake or on the wiki being momentarily
+ * unavailable.
+ */
+export async function loadLedger(source, {timeoutMs = LEDGER_FETCH_TIMEOUT_MS} = {}) {
+ try {
+ let text;
+ if (isUrl(source)) {
+ const res = await fetch(source, {
+ redirect: 'follow',
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+ text = await res.text();
+ } else {
+ text = fs.readFileSync(source, 'utf8');
+ }
+ const ledger = JSON.parse(text);
+ if (!ledger || !Array.isArray(ledger.components)) {
+ throw new Error('not a ledger: missing a `components` array');
+ }
+ return {ledger, error: null};
+ } catch (error) {
+ // `AbortSignal.timeout` rejects with a TimeoutError whose message is just
+ // "The operation was aborted" — say what actually happened instead.
+ const message =
+ error.name === 'TimeoutError'
+ ? `no response within ${timeoutMs}ms`
+ : error.message;
+ return {ledger: null, error: `${source}: ${message}`};
+ }
+}
+
+/**
+ * A component's identity is its package AND its name: `Chat` exists in both
+ * `core` and `lab`, so a name-keyed ledger silently conflates two different
+ * components — and would ratchet one against the other.
+ */
+export const entryId = e => `${e.package || 'unknown'}/${e.component}`;
+
+/**
+ * Index a ledger by `package/Component`, with a secondary multimap by bare
+ * name for callers (analyze-pr.js, `--record <Component>`) that only have one.
+ * @returns {{byId: Map<string, object>, byName: Map<string, object[]>}}
+ */
+export function indexLedger(ledger) {
+ const byId = new Map();
+ const byName = new Map();
+ for (const entry of ledger.components) {
+ byId.set(entryId(entry), entry);
+ const list = byName.get(entry.component) || [];
+ list.push(entry);
+ byName.set(entry.component, list);
+ }
+ return {byId, byName};
+}
+
+/**
+ * Resolve a bare component name against the live roster. A name that exists in
+ * two packages resolves to two components — the caller must handle both, not
+ * pick one.
+ */
+export function resolveName(name, components = listComponents()) {
+ return components.filter(c => c.component === name);
+}
+
+/**
+ * Join the live roster with the ledger.
+ * Every live component gets a row; `entry` is null when nobody has audited it.
+ * A ledger row with no live component is surfaced too (`live: false`) rather
+ * than silently dropped — that is how a rename or deletion shows up.
+ */
+export function buildRoster(ledger, components = listComponents()) {
+ const {byId} = indexLedger(ledger);
+ const roster = components.map(c => ({
+ id: `${c.package}/${c.component}`,
+ component: c.component,
+ package: c.package,
+ live: true,
+ entry: byId.get(`${c.package}/${c.component}`) || null,
+ }));
+ const liveIds = new Set(roster.map(r => r.id));
+ for (const entry of ledger.components) {
+ if (liveIds.has(entryId(entry))) continue;
+ roster.push({
+ id: entryId(entry),
+ component: entry.component,
+ package: entry.package || 'unknown',
+ live: false,
+ entry,
+ });
+ }
+ return roster.sort(
+ (a, b) => a.component.localeCompare(b.component) || a.package.localeCompare(b.package),
+ );
+}
+
+/** Normalize one section entry, filling the rubric weight and defaults. */
+export function readSection(entry, id) {
+ const raw = (entry && entry.sections && entry.sections[id]) || null;
+ return {
+ score: raw && raw.score !== undefined ? raw.score : null,
+ weight: raw && raw.weight !== undefined ? raw.weight : SECTION_WEIGHTS[id],
+ state: raw && raw.state ? raw.state : 'not_measured',
+ blocks: (raw && raw.blocks) || [],
+ note: (raw && raw.note) || null,
+ };
+}
+
+export const openBlockCount = entry =>
+ entry && entry.blocks && typeof entry.blocks.count === 'number'
+ ? entry.blocks.count
+ : 0;
+
+export const blockList = entry => (entry && entry.blocks && entry.blocks.open) || [];
+
+const isAudited = entry => !!entry && entry.status === 'audited';
+
+/** The repo that carries audit issues. */
+export const DEFAULT_REPO = 'facebook/astryx';
+
+/** `A8` -> ``[`A8`](https://github.com/…/issues/123)`` when the BLOCK is filed. */
+export function blockLink(block, repo = DEFAULT_REPO) {
+ const label = `\`${block.id}\``;
+ return block.issue
+ ? `${label} ([#${block.issue}](https://github.com/${repo}/issues/${block.issue}))`
+ : `${label} (no issue filed)`;
+}
+
+/** Open BLOCKs that have been filed as issues, as `#123` links. */
+export function issueLinks(entry, repo = DEFAULT_REPO) {
+ return blockList(entry)
+ .filter(b => b.issue)
+ .map(b => `[#${b.issue}](https://github.com/${repo}/issues/${b.issue})`);
+}
+
+// ---------------------------------------------------------------------------
+// --check — the ratchet
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare one component's proposed entry against its baseline entry.
+ *
+ * The rules, in the order they are applied:
+ * 1. No head entry, or head is `unaudited` -> pass. There is no baseline;
+ * the first audit sets it. A PR is NEVER blocked for touching a component
+ * nobody has audited.
+ * 2. No base entry, or base is `unaudited` -> pass, "first audit".
+ * 3. `rubricVersion` differs -> `incomparable`. The two numbers
+ * came off different scales, so the delta is meaningless. This does NOT
+ * fail; it asks for a re-audit under the head version.
+ * 4. A new BLOCK appears -> fail, even if the score is flat
+ * or higher. A BLOCK is categorically different from points. A rise in
+ * `blocks.count` with no new id counts as a new BLOCK.
+ * 5. Score decreased -> fail.
+ * 6. Otherwise -> pass.
+ */
+export function compareEntry(component, baseEntry, headEntry) {
+ const result = {
+ component,
+ verdict: 'pass',
+ reason: '',
+ baseScore: baseEntry ? (baseEntry.score ?? null) : null,
+ headScore: headEntry ? (headEntry.score ?? null) : null,
+ baseBlocks: openBlockCount(baseEntry),
+ headBlocks: openBlockCount(headEntry),
+ newBlocks: [],
+ };
+
+ if (!isAudited(headEntry)) {
+ result.reason = headEntry
+ ? 'unaudited — no baseline, the first audit sets it'
+ : 'not in the ledger — unaudited, no baseline';
+ return result;
+ }
+ if (!isAudited(baseEntry)) {
+ result.reason = 'first audit — no prior score to ratchet against';
+ return result;
+ }
+
+ if ((baseEntry.rubricVersion || null) !== (headEntry.rubricVersion || null)) {
+ result.verdict = 'incomparable';
+ result.reason =
+ 'incomparable — rubric version changed ' +
+ `(${baseEntry.rubricVersion || 'none'} -> ${headEntry.rubricVersion || 'none'}); ` +
+ `re-audit this entry under ${headEntry.rubricVersion || 'the new version'}`;
+ return result;
+ }
+
+ const baseIds = new Set(blockList(baseEntry).map(b => b.id));
+ const newBlocks = blockList(headEntry).filter(b => !baseIds.has(b.id));
+ result.newBlocks = newBlocks;
+
+ // A count that rises without a named id is still a new BLOCK: an entry may
+ // name only a subset of its BLOCKs, so the count is the authority.
+ const countRose = result.headBlocks > result.baseBlocks;
+
+ if (newBlocks.length > 0 || countRose) {
+ result.verdict = 'fail';
+ result.reason = newBlocks.length
+ ? `new BLOCK: ${newBlocks.map(b => `${b.id} (${b.summary})`).join('; ')}`
+ : `open BLOCK count rose ${result.baseBlocks} -> ${result.headBlocks}`;
+ return result;
+ }
+
+ if (
+ typeof result.headScore === 'number' &&
+ typeof result.baseScore === 'number' &&
+ result.headScore < result.baseScore
+ ) {
+ result.verdict = 'fail';
+ result.reason = `score decreased ${result.baseScore} -> ${result.headScore}`;
+ return result;
+ }
+
+ result.reason =
+ typeof result.headScore === 'number' &&
+ typeof result.baseScore === 'number' &&
+ result.headScore > result.baseScore
+ ? `improved ${result.baseScore} -> ${result.headScore}`
+ : 'unchanged';
+ return result;
+}
+
+/**
+ * Run the ratchet over a set of components, given as bare names or as
+ * `{component, package}` pairs. A bare name that exists in two packages yields
+ * one result per package rather than an arbitrary pick.
+ */
+export function runRatchet(components, baseLedger, headLedger, roster = null) {
+ const base = baseLedger ? indexLedger(baseLedger) : {byId: new Map(), byName: new Map()};
+ const head = indexLedger(headLedger);
+ const live = roster || listComponents();
+
+ const targets = [];
+ for (const item of components) {
+ if (typeof item === 'object') {
+ targets.push(item);
+ continue;
+ }
+ const matches = resolveName(item, live);
+ if (matches.length > 0) {
+ targets.push(...matches);
+ continue;
+ }
+ // Not a live component. It may still have a ledger row (a rename, say);
+ // otherwise check it as an unknown, which passes.
+ const rows = head.byName.get(item) || [];
+ if (rows.length > 0) targets.push(...rows.map(e => ({component: item, package: e.package})));
+ else targets.push({component: item, package: null});
+ }
+
+ const seen = new Set();
+ const results = [];
+ for (const t of targets) {
+ const id = `${t.package || 'unknown'}/${t.component}`;
+ if (seen.has(id)) continue;
+ seen.add(id);
+ const label = resolveName(t.component, live).length > 1 ? id : t.component;
+ results.push(
+ compareEntry(label, base.byId.get(id) || null, head.byId.get(id) || null),
+ );
+ }
+ return {results, failed: results.some(r => r.verdict === 'fail')};
+}
+
+/**
+ * Standing for one component when there is no baseline to compare against:
+ * where it sits today, and whether this change just made its audit stale.
+ */
+export function standingFor(component, entry, repo = DEFAULT_REPO) {
+ if (!isAudited(entry)) {
+ return {
+ component,
+ status: 'unaudited',
+ verdict: 'no baseline — judged on merits',
+ line: null,
+ };
+ }
+ const blocks = openBlockCount(entry);
+ const links = issueLinks(entry, repo);
+ return {
+ component,
+ status: 'audited',
+ verdict: 'known debt, unchanged',
+ score: entry.score,
+ grade: entry.grade,
+ blocks,
+ line:
+ `**${entry.grade}** ${fmtScore(entry.score)} · ` +
+ (blocks === 0
+ ? 'no open BLOCKs'
+ : `${blocks} recorded BLOCK${blocks === 1 ? '' : 's'}` +
+ (links.length ? ` (${links.join(', ')})` : '')) +
+ ` · audited ${entry.lastAudited} under rubric v${entry.rubricVersion}`,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// --queue
+// ---------------------------------------------------------------------------
+
+/**
+ * The auditor's work queue: unaudited first (alphabetical), then audited
+ * oldest-first, then lowest-scoring. Coverage grows before anything is
+ * re-audited, and the weakest components come back around soonest.
+ */
+export function buildQueue(roster, limit = Infinity) {
+ const unaudited = roster
+ .filter(r => r.live && !isAudited(r.entry))
+ .sort((a, b) => a.component.localeCompare(b.component))
+ .map(r => ({component: r.component, package: r.package, why: 'never audited'}));
+
+ const audited = roster
+ .filter(r => isAudited(r.entry))
+ .sort((a, b) => {
+ const byDate = String(a.entry.lastAudited || '').localeCompare(
+ String(b.entry.lastAudited || ''),
+ );
+ if (byDate !== 0) return byDate;
+ const as = a.entry.score ?? Infinity;
+ const bs = b.entry.score ?? Infinity;
+ if (as !== bs) return as - bs;
+ return a.component.localeCompare(b.component);
+ })
+ .map(r => ({
+ component: r.component,
+ package: r.package,
+ why:
+ `audited ${r.entry.lastAudited} · ${r.entry.grade} ${fmtScore(r.entry.score)} · ` +
+ `${openBlockCount(r.entry)} open BLOCK${openBlockCount(r.entry) === 1 ? '' : 's'}` +
+ (r.live ? '' : ' · NO LONGER IN THE PACKAGES'),
+ }));
+
+ return [...unaudited, ...audited].slice(0, limit);
+}
+
+// ---------------------------------------------------------------------------
+// --stats
+// ---------------------------------------------------------------------------
+
+export function buildStats(roster) {
+ const live = roster.filter(r => r.live);
+ const audited = roster.filter(r => isAudited(r.entry));
+ const grades = {A: 0, B: 0, C: 0, D: 0, F: 0};
+ for (const r of audited) if (r.entry.grade in grades) grades[r.entry.grade]++;
+
+ const sections = {};
+ for (const id of SECTION_IDS) {
+ const states = {scored: 0, limited: 0, not_measured: 0, na: 0, unpublished: 0};
+ const scores = [];
+ for (const r of audited) {
+ const s = readSection(r.entry, id);
+ if (s.state in states) states[s.state]++;
+ if (s.state === 'scored' && typeof s.score === 'number') scores.push(s.score);
+ }
+ sections[id] = {
+ weight: SECTION_WEIGHTS[id],
+ states,
+ mean: scores.length
+ ? Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 100) / 100
+ : null,
+ n: scores.length,
+ };
+ }
+
+ const dates = audited.map(r => r.entry.lastAudited).filter(Boolean).sort();
+ const scores = audited.map(r => r.entry.score).filter(n => typeof n === 'number');
+
+ return {
+ total: live.length,
+ audited: audited.length,
+ unaudited: live.length - audited.filter(r => r.live).length,
+ percentAudited: live.length
+ ? Math.round((audited.filter(r => r.live).length / live.length) * 1000) / 10
+ : 0,
+ byPackage: LEDGER_PACKAGES.reduce((acc, p) => {
+ const inPkg = live.filter(r => r.package === p.name);
+ acc[p.name] = {
+ total: inPkg.length,
+ audited: inPkg.filter(r => isAudited(r.entry)).length,
+ };
+ return acc;
+ }, {}),
+ grades,
+ openBlocks: audited.reduce((sum, r) => sum + openBlockCount(r.entry), 0),
+ componentsWithBlocks: audited.filter(r => openBlockCount(r.entry) > 0).length,
+ meanScore: scores.length
+ ? Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 10) / 10
+ : null,
+ oldestAudit: dates[0] || null,
+ newestAudit: dates[dates.length - 1] || null,
+ rubricVersions: [
+ ...new Set(audited.map(r => r.entry.rubricVersion).filter(Boolean)),
+ ].sort(),
+ orphanRows: roster.filter(r => !r.live).map(r => r.component),
+ sections,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Small shared formatters
+// ---------------------------------------------------------------------------
+
+/** The lowest `scored` section — the one an auditor should attack next. */
+export function weakestSection(entry) {
+ let worst = null;
+ for (const id of SECTION_IDS) {
+ const s = readSection(entry, id);
+ if (s.state !== 'scored' || typeof s.score !== 'number') continue;
+ if (!worst || s.score < worst.score) worst = {id, score: s.score};
+ }
+ return worst;
+}
+
+function fmtScore(n) {
+ return typeof n === 'number' ? n.toFixed(1) : '—';
+}
+
+/**
+ * The paste-to-an-agent request for an audit. One string, exported so the
+ * sandbox page and the CLI cannot drift.
+ */
+export const AUDIT_PROMPT = `Audit the Astryx component <Component> against the Component Audit Rubric:
+https://github.com/facebook/astryx/wiki/Component-Audit-Rubric
+
+Grade the whole component, not a diff — follow the rubric's "Grading a whole
+component" section. Work every section, cite the rule id for each finding
+(A8, T6, P2 …), and capture screenshots of every state in light and dark by
+driving a real browser against Storybook. If you skip the screenshots, report
+the rendered-design section as not_measured rather than scoring it — never
+guess, and never score it zero.
+
+Then record the result, per the rubric's "Recording an audit" section. One
+command: it clones the wiki, applies the ratchet, commits and pushes.
+
+ <your scorecard JSON> | node scripts/score-ledger.mjs --record <Component> \\
+ --from - --push
+
+Only record what you actually measured.`;
+
+// ---------------------------------------------------------------------------
+// --push — the wiki write path
+//
+// CI cannot write this ledger: scoring is judgment, so the writer is always a
+// human or an agent running an audit. A write path that takes six steps gets
+// skipped, and the rubric says an audit that isn't recorded didn't happen — so
+// recording has to be ONE command.
+// ---------------------------------------------------------------------------
+
+/** The reused shallow clone. One per user, not one per run. */
+export const WIKI_CACHE_DIR = path.join(os.tmpdir(), 'astryx-score-ledger-wiki');
+
+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 (e) {
+ const out = `${e.stdout || ''}\n${e.stderr || ''}`.trim();
+ return {ok: false, out: out || e.message};
+ }
+}
+
+/**
+ * A shallow clone of the wiki, cached between runs so recording a score is not
+ * a fresh clone every time.
+ *
+ * It is hard-reset to the remote tip before it is handed back. A working copy
+ * left dirty by a crashed run must never ride along on the next agent's commit
+ * — the cache is an optimisation, never a state carrier.
+ */
+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;
+}
+
+/** The repo a wiki remote belongs to, for building URLs. */
+export function repoFromWikiRemote(remote = WIKI_REMOTE) {
+ const m = /github\.com[/:]([^/]+)\/(.+?)\.wiki(\.git)?$/.exec(remote);
+ return m ? `${m[1]}/${m[2]}` : DEFAULT_REPO;
+}
+
+/** GitHub renders a single wiki commit at `/wiki/_compare/<sha>`. */
+export function wikiCommitUrl(sha, remote = WIKI_REMOTE) {
+ return `https://github.com/${repoFromWikiRemote(remote)}/wiki/_compare/${sha}`;
+}
+
+/**
+ * The commit message for a recorded score. Cindy's format, with the package
+ * added only when the bare name is ambiguous — `Chat` exists in core and lab,
+ * and a message that does not say which one is a message you cannot read back.
+ */
+export function commitMessage(entry, {regression = null, ambiguous = false} = {}) {
+ const name = ambiguous ? `${entry.package}/${entry.component}` : entry.component;
+ const subject =
+ `scores: ${name} ${entry.grade} (${fmtScore(entry.score)}), ` +
+ `rubric ${entry.rubricVersion}`;
+ if (!regression) return {subject, body: ''};
+ const body = [
+ `Regression allowed: ${regression.reason}`,
+ '',
+ `Score ${fmtScore(regression.from.score)} → ${fmtScore(entry.score)}, ` +
+ `open BLOCKs ${regression.from.blocks} → ${openBlockCount(entry)}.`,
+ ].join('\n');
+ return {subject, body};
+}
+
+/** A unified diff of two in-memory versions, so --dry-run touches no file. */
+function unifiedDiff(before, after, label) {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), '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 (e) {
+ // `diff` exits 1 when the files differ. That is the expected path.
+ if (e.status === 1) return String(e.stdout);
+ throw e;
+ }
+ } finally {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+}
+
+/** Refuse to commit on behalf of nobody. A public repo keeps real authorship. */
+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. ' +
+ 'The wiki is public and the commit is attributed to whoever pushes it.',
+ );
+ }
+}
+
+/**
+ * Commit the applied ledger and push it, re-applying rather than forcing when
+ * another agent got there first.
+ *
+ * Several agents can record concurrently. Rebasing one JSON edit onto another
+ * conflicts far more often than it merges, so a non-fast-forward is not fought:
+ * the local commit is thrown away, the tree is reset to the remote tip, and
+ * `apply` runs again against what the other agent actually recorded. That is
+ * the only correct answer — the second writer has to be ratcheted against the
+ * first writer's numbers, not against the ones they started from.
+ *
+ * `apply` re-reads the ledger from disk and returns the text to write, so the
+ * retry is a real re-evaluation and not a replay of a stale result.
+ */
+function commitAndPush(dir, file, apply, {attempts = 2} = {}) {
+ // Resolve both sides: on macOS the temp dir is a symlink, so the path git
+ // reports for the work tree and the path we were handed disagree, and the
+ // ledger looks like a file outside the repo.
+ const root = fs.realpathSync(dir);
+ const target = fs.realpathSync(file);
+ requireGitIdentity(root);
+ const rel = path.relative(root, target) || path.basename(target);
+ let lastFailure = null;
+
+ for (let attempt = 1; attempt <= attempts; attempt++) {
+ const applied = apply();
+ fs.writeFileSync(target, applied.text);
+
+ // `git status --porcelain` is not safe to parse here: the leading status
+ // column is whitespace for an unstaged edit, and trimming it shifts the
+ // path. Ask for paths directly instead.
+ const dirtyOthers = [
+ ...git(root, 'diff', '--name-only', 'HEAD').split('\n'),
+ ...git(root, 'ls-files', '--others', '--exclude-standard').split('\n'),
+ ]
+ .filter(Boolean)
+ .filter(p => p !== rel);
+ if (dirtyOthers.length) {
+ throw new Error(
+ `the wiki working copy has unrelated changes (${dirtyOthers.join(', ')}) — ` +
+ 'refusing to push them. Clean the clone and re-run.',
+ );
+ }
+
+ git(root, 'add', '--', rel);
+ 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) {
+ // A conflicted rebase means someone else edited the same rows. Abort and
+ // re-apply onto their version rather than resolving JSON by hand.
+ tryGit(root, 'rebase', '--abort');
+ lastFailure = pulled.out;
+ if (attempt < attempts) {
+ console.log('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('score-ledger: push rejected as non-fast-forward — 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`.',
+ );
+}
+
+// ---------------------------------------------------------------------------
+// --record
+// ---------------------------------------------------------------------------
+
+const SCORECARD_FIELDS = new Set([
+ 'status',
+ 'score',
+ 'grade',
+ 'sections',
+ 'blocks',
+ 'distinct_defects',
+ 'fixes',
+ 'nits',
+ 'lastAudited',
+ 'rubricVersion',
+ 'mode',
+ 'commit',
+ 'evidence',
+ 'notes',
+]);
+
+/**
+ * Merge a scorecard into a ledger entry and validate it.
+ * Unknown keys are rejected rather than silently stored — a typo in a field
+ * name would otherwise produce a row that reads fine and measures nothing.
+ */
+export function applyScorecard(existing, scorecard, {component, pkg}) {
+ const unknown = Object.keys(scorecard).filter(k => !SCORECARD_FIELDS.has(k));
+ if (unknown.length) {
+ throw new Error(`unknown scorecard field(s): ${unknown.join(', ')}`);
+ }
+ const next = {
+ component,
+ package: (existing && existing.package) || pkg,
+ status: 'audited',
+ score: null,
+ grade: null,
+ sections: {},
+ blocks: {count: 0, open: []},
+ distinct_defects: null,
+ fixes: null,
+ nits: null,
+ lastAudited: null,
+ rubricVersion: null,
+ mode: null,
+ commit: null,
+ evidence: [],
+ ...(existing || {}),
+ ...scorecard,
+ };
+ if (!next.package) throw new Error(`${component}: no package — pass --package`);
+ if (next.status !== 'audited') {
+ throw new Error(
+ `${component}: the ledger holds audited components only — an unaudited component ` +
+ 'simply has no row. Remove the entry instead.',
+ );
+ }
+ if (typeof next.score !== 'number') {
+ throw new Error(`${component}: an audited entry needs a numeric score`);
+ }
+ const expected = gradeFor(next.score, openBlockCount(next));
+ // `grade` is derived from `score`, so it must never be inherited across a
+ // re-record: a scorecard that lowers the score without restating the grade
+ // would otherwise carry the old letter forward and fail as a contradiction.
+ if (!('grade' in scorecard)) next.grade = null;
+ if (!next.grade) next.grade = expected;
+ if (next.grade !== expected) {
+ throw new Error(
+ `${component}: grade ${next.grade} contradicts score ${next.score} with ` +
+ `${openBlockCount(next)} open BLOCK(s) — expected ${expected} ` +
+ '(any open BLOCK caps the grade at C)',
+ );
+ }
+ if (!next.rubricVersion) throw new Error(`${component}: rubricVersion is required`);
+ if (!next.lastAudited) throw new Error(`${component}: lastAudited is required`);
+ if (!next.mode) throw new Error(`${component}: mode is required (N/P/O/R)`);
+ for (const [id, section] of Object.entries(next.sections || {})) {
+ if (!(id in SECTION_WEIGHTS)) {
+ throw new Error(`${component}: unknown section id "${id}"`);
+ }
+ if (section.state && !SECTION_STATES.includes(section.state)) {
+ throw new Error(`${component}: unknown section state "${section.state}"`);
+ }
+ if (section.weight === undefined) section.weight = SECTION_WEIGHTS[id];
+ }
+ for (const b of blockList(next)) {
+ if (!b || typeof b.id !== 'string' || typeof b.summary !== 'string') {
+ throw new Error(`${component}: every BLOCK needs {id, summary} (issue optional)`);
+ }
+ if (b.issue !== undefined && b.issue !== null && !Number.isInteger(b.issue)) {
+ throw new Error(`${component}: BLOCK ${b.id} issue must be an integer or null`);
+ }
+ if (b.issue === undefined) b.issue = null;
+ }
+ if (blockList(next).length > openBlockCount(next)) {
+ throw new Error(
+ `${component}: ${blockList(next).length} BLOCKs listed but blocks.count is ` +
+ `${openBlockCount(next)}`,
+ );
+ }
+ return next;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+ const args = {_: []};
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (!a.startsWith('--')) {
+ args._.push(a);
+ continue;
+ }
+ const key = a.slice(2);
+ const next = argv[i + 1];
+ if (next === undefined || next.startsWith('--')) {
+ args[key] = true;
+ } else {
+ args[key] = next;
+ i++;
+ }
+ }
+ return args;
+}
+
+const flagValue = v => (typeof v === 'string' ? v : null);
+
+function componentsFromArgs(args) {
+ const known = new Set(listComponents().map(c => c.component));
+ if (flagValue(args.components)) {
+ return args.components.split(',').map(s => s.trim()).filter(Boolean);
+ }
+ if (flagValue(args.analysis)) {
+ const analysis = JSON.parse(fs.readFileSync(args.analysis, 'utf8'));
+ const names = [
+ ...(analysis.newComponents || []),
+ ...(analysis.modifiedComponents || []),
+ ];
+ // analyze-pr.js has a looser notion of a component (it keeps NavItem,
+ // SizeContext and InteractiveRoleContext, and it covers charts). Filter its
+ // output through the canonical predicate so the ledger's denominator stays
+ // the rubric's.
+ return [...new Set(names)].filter(n => known.has(n)).sort();
+ }
+ return [];
+}
+
+async function cmdCheck(args) {
+ const components = componentsFromArgs(args);
+ if (components.length === 0) {
+ console.log(
+ 'score-ledger: this change touches no component in packages/{core,lab}/src — nothing to check.',
+ );
+ return 0;
+ }
+
+ const {ledger, error} = await loadLedger(flagValue(args.ledger) || DEFAULT_LEDGER_URL);
+ if (!ledger) {
+ // Never fail a pull request because the ledger could not be read. The
+ // ledger lives in the wiki; a fetch failure is infrastructure, not a
+ // regression.
+ console.log(
+ `::warning::score-ledger: could not read the ledger (${error}) — skipping the check.`,
+ );
+ return 0;
+ }
+
+ let baseLedger = null;
+ if (flagValue(args['base-ledger'])) {
+ const loaded = await loadLedger(args['base-ledger']);
+ if (!loaded.ledger) {
+ console.log(
+ `::warning::score-ledger: could not read the base ledger (${loaded.error}) — ` +
+ 'reporting standing only.',
+ );
+ } else {
+ baseLedger = loaded.ledger;
+ }
+ }
+
+ const lines = [];
+ let exitCode = 0;
+
+ if (baseLedger) {
+ const {results, failed} = runRatchet(components, baseLedger, ledger);
+ lines.push('## Component score ratchet', '');
+ lines.push('| Component | Base | Head | Verdict | Detail |');
+ lines.push('|---|---|---|---|---|');
+ for (const r of results) {
+ const icon =
+ r.verdict === 'fail'
+ ? '🔴 fail'
+ : r.verdict === 'incomparable'
+ ? '⚠️ incomparable'
+ : '✅ pass';
+ lines.push(
+ `| ${r.component} | ${fmtScore(r.baseScore)} (${r.baseBlocks} BLOCK) | ` +
+ `${fmtScore(r.headScore)} (${r.headBlocks} BLOCK) | ${icon} | ${r.reason} |`,
+ );
+ }
+ lines.push('');
+ for (const r of results) {
+ if (r.verdict === 'fail') {
+ lines.push(
+ `🔴 **${r.component}: ${r.reason}.** Score ${fmtScore(r.baseScore)} → ` +
+ `${fmtScore(r.headScore)}, open BLOCKs ${r.baseBlocks} → ${r.headBlocks}.`,
+ );
+ } else if (r.verdict === 'incomparable') {
+ lines.push(`⚠️ **${r.component}: ${r.reason}.**`);
+ }
+ }
+ exitCode = failed ? 1 : 0;
+ } else {
+ // No baseline to ratchet against: the ledger lives in the wiki and a pull
+ // request cannot change it. Mode R judges the diff, not the component, so
+ // this branch reports and never fails — and it stays quiet about debt the
+ // contributor inherited.
+ const {byId} = indexLedger(ledger);
+ const live = listComponents();
+ const standings = components.flatMap(name => {
+ const matches = resolveName(name, live);
+ const targets = matches.length ? matches : [{component: name, package: null}];
+ return targets.map(t => {
+ const label = matches.length > 1 ? `${t.package}/${t.component}` : t.component;
+ return standingFor(label, byId.get(`${t.package}/${t.component}`) || null);
+ });
+ });
+ const audited = standings.filter(s => s.status === 'audited');
+ if (audited.length === 0) {
+ console.log(
+ `score-ledger: ${components.length} component(s) touched, none with a recorded audit — ` +
+ 'no baseline, judged on merits. Nothing to report.',
+ );
+ return 0;
+ }
+ lines.push('## Component scores — recorded baselines', '');
+ lines.push(
+ 'For information. These are **recorded baselines, not findings against this pull ' +
+ 'request** — the ledger lives in the wiki, so a PR cannot change it, and nothing here ' +
+ 'blocks. A check only ever fails on a regression this diff caused: a new BLOCK, or a ' +
+ 'lower score. Anything already on the row is known debt with its own issue.',
+ );
+ lines.push('');
+ lines.push('| Component | Recorded | Status |');
+ lines.push('|---|---|---|');
+ for (const st of audited) {
+ lines.push(`| ${st.component} | ${st.line} | known debt, unchanged |`);
+ }
+ const unaudited = standings.filter(s => s.status !== 'audited');
+ if (unaudited.length) {
+ lines.push('');
+ lines.push(
+ `${unaudited.length} other component${unaudited.length === 1 ? '' : 's'} in this diff ` +
+ `${unaudited.length === 1 ? 'has' : 'have'} no audit on record — no baseline, judged on ` +
+ `merits. See [the component scores page](${SCORES_PAGE_URL}) to request one.`,
+ );
+ }
+ lines.push('');
+ }
+
+ const text = lines.join('\n');
+ console.log(text);
+ if (process.env.GITHUB_STEP_SUMMARY) {
+ fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${text}\n`);
+ }
+ return exitCode;
+}
+
+async function withLedger(args, fn) {
+ const source = flagValue(args.ledger) || DEFAULT_LEDGER_URL;
+ const {ledger, error} = await loadLedger(source);
+ if (!ledger) {
+ console.error(`score-ledger: ${error}`);
+ return 1;
+ }
+ return fn(ledger, buildRoster(ledger));
+}
+
+async function cmdQueue(args) {
+ return withLedger(args, (ledger, roster) => {
+ const limit = flagValue(args.limit) ? Number(args.limit) : 5;
+ const queue = buildQueue(roster, limit);
+ if (args.json) {
+ console.log(JSON.stringify(queue, null, 2));
+ return 0;
+ }
+ console.log(`Audit queue — next ${queue.length}:`);
+ for (const [i, e] of queue.entries()) {
+ console.log(
+ ` ${String(i + 1).padStart(2)}. ${e.component} (${e.package}) — ${e.why}`,
+ );
+ }
+ return 0;
+ });
+}
+
+async function cmdStats(args) {
+ return withLedger(args, (ledger, roster) => {
+ const stats = buildStats(roster);
+ if (args.json) {
+ console.log(JSON.stringify(stats, null, 2));
+ return 0;
+ }
+ const g = stats.grades;
+ console.log(
+ `Component score ledger — v${ledger.ledgerVersion}, current rubric v${ledger.rubricVersion}`,
+ );
+ console.log('');
+ console.log(
+ ` Components: ${stats.total} (${stats.audited} audited, ${stats.unaudited} unaudited — ${stats.percentAudited}%)`,
+ );
+ console.log(
+ ` core ${stats.byPackage.core.audited}/${stats.byPackage.core.total} · ` +
+ `lab ${stats.byPackage.lab.audited}/${stats.byPackage.lab.total}`,
+ );
+ console.log(` Grades: A ${g.A} · B ${g.B} · C ${g.C} · D ${g.D} · F ${g.F}`);
+ console.log(` Mean score: ${fmtScore(stats.meanScore)} (audited only)`);
+ console.log(
+ ` Open BLOCKs: ${stats.openBlocks} across ${stats.componentsWithBlocks} components`,
+ );
+ console.log(
+ ` Audit dates: oldest ${stats.oldestAudit || '—'} · newest ${stats.newestAudit || '—'}`,
+ );
+ console.log(` Rubric vers.: ${stats.rubricVersions.join(', ') || '—'}`);
+ if (stats.orphanRows.length) {
+ console.log(` Orphan rows: ${stats.orphanRows.join(', ')} (no live component)`);
+ }
+ console.log('');
+ console.log(' Sections (audited rows only)');
+ for (const id of SECTION_IDS) {
+ const s = stats.sections[id];
+ const st = s.states;
+ console.log(
+ ` ${SECTION_TITLES[id].padEnd(38)} w${String(s.weight).padStart(2)} ` +
+ `mean ${s.mean === null ? ' —' : s.mean.toFixed(2)} (n=${s.n}) ` +
+ `scored ${st.scored} · limited ${st.limited} · not_measured ${st.not_measured} · ` +
+ `na ${st.na} · unpublished ${st.unpublished}`,
+ );
+ }
+ return 0;
+ });
+}
+
+/**
+ * Record one component's scorecard.
+ *
+ * The whole point of `--push` is that this is ONE command: resolve the
+ * component, clone or refresh the wiki, apply the scorecard under the ratchet,
+ * commit, rebase onto whatever landed meanwhile, push, and print where it went.
+ * Nothing is pushed unless the apply came out clean.
+ */
+async function cmdRecord(args) {
+ const component = flagValue(args.record);
+ if (!component) {
+ console.error('score-ledger --record <Component>: the component name is required');
+ return 1;
+ }
+
+ // Read the scorecard exactly once: stdin cannot be read twice, and the push
+ // retry re-applies this same scorecard onto a newer ledger.
+ const src = flagValue(args.from);
+ if (!src) {
+ console.error('score-ledger --record: --from <scorecard.json|-> is required');
+ return 1;
+ }
+ let scorecard;
+ try {
+ const text = src === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(src, 'utf8');
+ scorecard = JSON.parse(text);
+ } catch (e) {
+ console.error(
+ `score-ledger --record: could not read a scorecard from ${src === '-' ? 'stdin' : src} — ${e.message}`,
+ );
+ return 1;
+ }
+
+ const matches = resolveName(component);
+ const ambiguous = matches.length > 1;
+ if (ambiguous && !flagValue(args.package)) {
+ console.error(
+ `score-ledger --record: ${component} exists in ${matches.map(m => m.package).join(' and ')} — ` +
+ 'pass --package to say which one.',
+ );
+ return 1;
+ }
+ const live = matches[0];
+ if (!live) {
+ console.log(
+ `score-ledger: warning — ${component} is not a component directory in ` +
+ 'packages/{core,lab}/src under the canonical predicate. Recording anyway.',
+ );
+ }
+ const pkg = flagValue(args.package) || (live && live.package) || null;
+ if (!pkg) {
+ console.error(
+ `score-ledger --record: cannot resolve a package for ${component} — pass --package <core|lab>.`,
+ );
+ return 1;
+ }
+
+ if (args['allow-regression'] === true) {
+ console.error(
+ 'score-ledger --record: --allow-regression needs a reason — --allow-regression "<why>". ' +
+ 'It is recorded on the row and in the commit message.',
+ );
+ return 1;
+ }
+
+ // Where the file is. --push (and --dry-run, which needs a baseline to diff
+ // against) will fetch the wiki for you; without either you point at your own
+ // clone, as before.
+ 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(
+ 'score-ledger --record: --ledger must be a local path — recording writes the file. ' +
+ 'Drop it and pass --push to have the wiki cloned for you.',
+ );
+ return 1;
+ }
+ try {
+ if (!ledgerPath) {
+ if (!push && !dryRun) {
+ console.error(
+ 'score-ledger --record: pass --push (clone the wiki, apply, commit and push) or ' +
+ '--ledger <path> pointing at component-scores.json in your own clone.',
+ );
+ return 1;
+ }
+ repoDir = ensureWikiClone();
+ ledgerPath = path.join(repoDir, LEDGER_FILENAME);
+ console.log(`score-ledger: wiki clone at ${repoDir} (${WIKI_REMOTE}, ${WIKI_BRANCH})`);
+ } else if (push) {
+ const top = tryGit(path.dirname(path.resolve(ledgerPath)), 'rev-parse', '--show-toplevel');
+ if (!top.ok) {
+ console.error(
+ `score-ledger --record: --push needs ${ledgerPath} to live in a git clone of the wiki ` +
+ `(${top.out}). Drop --ledger to use the cached clone instead.`,
+ );
+ return 1;
+ }
+ repoDir = top.out;
+ }
+ } catch (e) {
+ console.error(`score-ledger --record: could not prepare the wiki clone — ${e.message}`);
+ return 1;
+ }
+
+ /**
+ * Apply the scorecard to whatever is on disk RIGHT NOW and return the text to
+ * write. Re-run on a push race so the ratchet judges this audit against the
+ * numbers the other writer just published, not the ones we started from.
+ */
+ const applyOnce = () => {
+ const raw = fs.readFileSync(ledgerPath, 'utf8');
+ const ledger = JSON.parse(raw);
+ if (!Array.isArray(ledger.components)) {
+ throw new Error(`${ledgerPath} is not a ledger — no components array`);
+ }
+ const before = indexLedger(ledger).byId.get(`${pkg}/${component}`) || null;
+ const after = applyScorecard(before, scorecard, {component, pkg});
+
+ // The wiki takes no pull request, so the ratchet has to bite here.
+ //
+ // `incomparable` (the rubric version changed) is the right verdict for a
+ // PR-time check — an author must not be failed for a rubric change they had
+ // nothing to do with. At RECORD time it is not: it would let any score be
+ // written over any other simply by bumping `rubricVersion`, which is the
+ // one field the writer controls. So a record that moves the numbers the
+ // wrong way needs its reason stated whether or not the scales match; the
+ // verdict just changes what the reason has to explain.
+ const verdict = compareEntry(component, before, after);
+ const movedBackwards =
+ before != null &&
+ isAudited(before) &&
+ (openBlockCount(after) > openBlockCount(before) ||
+ (typeof before.score === 'number' &&
+ typeof after.score === 'number' &&
+ after.score < before.score));
+ const needsReason = verdict.verdict === 'fail' || movedBackwards;
+
+ let regression = null;
+ if (needsReason) {
+ if (!args['allow-regression']) {
+ const why =
+ verdict.verdict === 'fail'
+ ? verdict.reason
+ : `${verdict.reason}, and the numbers went down ` +
+ `(${fmtScore(before.score)} → ${fmtScore(after.score)}, open BLOCKs ` +
+ `${openBlockCount(before)} → ${openBlockCount(after)})`;
+ throw new Error(
+ `refusing — ${why}. If the regression is real and intended, re-run with ` +
+ '--allow-regression "<why>": the reason is recorded on the row and in the commit ' +
+ 'message.',
+ );
+ }
+ regression = {
+ reason: String(args['allow-regression']),
+ from: {
+ score: before.score,
+ blocks: openBlockCount(before),
+ },
+ recordedAt: new Date().toISOString().slice(0, 10),
+ };
+ after.regression = regression;
+ }
+
+ const idx = ledger.components.findIndex(e => entryId(e) === entryId(after));
+ if (idx === -1) ledger.components.push(after);
+ else ledger.components[idx] = after;
+ ledger.components.sort(
+ (a, b) =>
+ a.component.localeCompare(b.component) ||
+ String(a.package).localeCompare(String(b.package)),
+ );
+ ledger.updated = new Date().toISOString().slice(0, 10);
+
+ return {
+ before,
+ after,
+ verdict,
+ regression,
+ raw,
+ text: `${JSON.stringify(ledger, null, 2)}\n`,
+ message: commitMessage(after, {regression, ambiguous}),
+ };
+ };
+
+ let applied;
+ try {
+ applied = applyOnce();
+ } catch (e) {
+ // Guard rail: an apply that did not come out clean never reaches git.
+ console.error(`score-ledger --record: ${e.message}`);
+ return 1;
+ }
+
+ if (dryRun) {
+ const diff = unifiedDiff(applied.raw, applied.text, LEDGER_FILENAME);
+ console.log(diff || `(${LEDGER_FILENAME} is already exactly this — no change)`);
+ console.log('--- commit message ---');
+ console.log(applied.message.subject);
+ if (applied.message.body) console.log(`\n${applied.message.body}`);
+ console.log('----------------------');
+ console.log('score-ledger: --dry-run — nothing written, nothing committed, nothing pushed.');
+ warnOnRecord(component, applied);
+ return 0;
+ }
+
+ if (push) {
+ let result;
+ try {
+ result = commitAndPush(repoDir, ledgerPath, applyOnce);
+ } catch (e) {
+ console.error(`score-ledger --record: ${e.message}`);
+ return 1;
+ }
+ applied = result.applied;
+ console.log(
+ `score-ledger: recorded ${component} — ${applied.after.grade} ${applied.after.score} ` +
+ `(${applied.verdict.reason || 'new entry'}) and pushed ${result.sha.slice(0, 10)}`,
+ );
+ console.log(` commit: ${result.url}`);
+ console.log(` live on: ${SCORES_PAGE_URL}`);
+ } else {
+ fs.writeFileSync(ledgerPath, applied.text);
+ console.log(
+ `score-ledger: recorded ${component} — ${applied.after.grade} ${applied.after.score} ` +
+ `(${applied.verdict.reason || 'new entry'}) in ${ledgerPath}`,
+ );
+ console.log(
+ 'score-ledger: not published — commit and push the wiki yourself, or re-run with --push.',
+ );
+ }
+
+ warnOnRecord(component, applied);
+ return 0;
+}
+
+/**
+ * Everything worth saying about a row that was just written. Warnings, never
+ * failures: the score is recorded either way, and an auditor who is told what
+ * is missing fixes it far more often than one whose write was rejected.
+ */
+function warnOnRecord(component, {before, after}) {
+ // Every BLOCK is supposed to carry the issue it was filed as; that is where
+ // the page's links come from.
+ const unfiled = blockList(after).filter(b => !b.issue);
+ if (unfiled.length) {
+ console.log(
+ `::warning::score-ledger: ${unfiled.length} BLOCK(s) on ${component} have no issue ` +
+ `(${unfiled.map(b => b.id).join(', ')}). File them — ` +
+ `node scripts/score-ledger.mjs --file-issues ${component} --push`,
+ );
+ }
+ const unattributed = openBlockCount(after) - blockList(after).length;
+ if (unattributed > 0) {
+ console.log(
+ `::warning::score-ledger: ${component} counts ${openBlockCount(after)} open BLOCKs but ` +
+ `names ${blockList(after).length}. An unnamed BLOCK cannot be filed, linked, or closed.`,
+ );
+ }
+ // "A resolved BLOCK that leaves the recorded score unchanged means either the
+ // fix or the audit is wrong" — rubric, Closing the loop.
+ if (
+ before &&
+ isAudited(before) &&
+ openBlockCount(after) < openBlockCount(before) &&
+ after.score === before.score &&
+ before.rubricVersion === after.rubricVersion
+ ) {
+ console.log(
+ `::warning::score-ledger: ${component} cleared ` +
+ `${openBlockCount(before) - openBlockCount(after)} BLOCK(s) but the score did not move ` +
+ `(${fmtScore(before.score)}). Clearing a BLOCK lifts that section's ceiling — either the ` +
+ 'fix or the audit is wrong. Re-check before you push.',
+ );
+ }
+}
+
+/**
+ * The body of an audit issue. Everything whoever picks it up needs, because
+ * they will not have the audit open: the ledger row, the rule and section, the
+ * rubric version, the evidence, the fix — and the closing protocol.
+ */
+export function issueBody(component, entry, block, repo = DEFAULT_REPO) {
+ const section = block.section ? ` (${block.section})` : '';
+ return [
+ `Found by a component audit of **${component}**, mode ${entry.mode}, ` +
+ `rubric **v${entry.rubricVersion}**, at commit \`${entry.commit || 'unknown'}\`.`,
+ '',
+ `- **Rule:** \`${block.id}\`${section} — see the [Component Audit Rubric]` +
+ `(https://github.com/${repo}/wiki/Component-Audit-Rubric).`,
+ `- **Ledger row:** [${component} on the component scores page](${SCORES_PAGE_URL}) — recorded ` +
+ `${entry.grade} ${entry.score} with ${openBlockCount(entry)} open BLOCK(s).`,
+ `- **Finding:** ${block.summary}`,
+ block.evidence ? `- **Evidence:** ${block.evidence}` : null,
+ block.fix ? `- **Fix:** ${block.fix}` : null,
+ '',
+ '### Closing protocol',
+ '',
+ 'Resolving this requires:',
+ '',
+ `1. Re-run the audit for ${component} after the fix — the whole component, ` +
+ "not the diff (the rubric's \"Grading a whole component\" section).",
+ '2. Put the visual results in the PR description — before/after screenshots of the ' +
+ 'affected states. The rendered-design section is graded from those.',
+ '3. Update the ledger with the new score and clear this BLOCK ' +
+ `(\`<scorecard> | node scripts/score-ledger.mjs --record ${component} --from - --push\`).`,
+ '4. Close this issue linking that PR.',
+ '',
+ "If the recorded score doesn't move, either the fix or the audit is wrong.",
+ ]
+ .filter(l => l !== null)
+ .join('\n');
+}
+
+/**
+ * File one `hardening` issue per unfiled BLOCK and write the numbers back.
+ * Idempotent: a BLOCK that already carries an issue number is left alone, and a
+ * linked issue that was closed while the BLOCK persists is reopened rather than
+ * re-filed.
+ *
+ * This mutates the ledger too, so it takes the same `--push` write path — the
+ * numbers are useless until they are on the row the page reads.
+ */
+async function cmdFileIssues(args) {
+ const component = flagValue(args['file-issues']);
+ if (!component) {
+ console.error('score-ledger --file-issues <Component>: the component name is required');
+ return 1;
+ }
+ const push = Boolean(args.push);
+ let ledgerPath = flagValue(args.ledger);
+ let repoDir = null;
+ if (ledgerPath && isUrl(ledgerPath)) {
+ console.error('score-ledger --file-issues: --ledger must be a local path — it writes back.');
+ return 1;
+ }
+ try {
+ if (!ledgerPath) {
+ if (!push && !args['dry-run']) {
+ console.error(
+ 'score-ledger --file-issues: pass --push (clone the wiki, file, commit and push) or ' +
+ '--ledger <path> pointing at component-scores.json in your own clone.',
+ );
+ return 1;
+ }
+ repoDir = ensureWikiClone();
+ ledgerPath = path.join(repoDir, LEDGER_FILENAME);
+ console.log(`score-ledger: wiki clone at ${repoDir} (${WIKI_REMOTE}, ${WIKI_BRANCH})`);
+ } else if (push) {
+ const top = tryGit(path.dirname(path.resolve(ledgerPath)), 'rev-parse', '--show-toplevel');
+ if (!top.ok) {
+ console.error(
+ `score-ledger --file-issues: --push needs ${ledgerPath} to live in a git clone of the ` +
+ `wiki (${top.out}).`,
+ );
+ return 1;
+ }
+ repoDir = top.out;
+ }
+ } catch (e) {
+ console.error(`score-ledger --file-issues: could not prepare the wiki clone — ${e.message}`);
+ return 1;
+ }
+
+ const repo = flagValue(args.repo) || DEFAULT_REPO;
+ const {ledger, error} = await loadLedger(ledgerPath);
+ if (!ledger) {
+ console.error(`score-ledger: ${error}`);
+ return 1;
+ }
+ const matches = resolveName(component);
+ const pkg = flagValue(args.package) || (matches.length === 1 ? matches[0].package : null);
+ if (!pkg) {
+ console.error(
+ `score-ledger --file-issues: pass --package for ${component} (it resolves to ` +
+ `${matches.length} components).`,
+ );
+ return 1;
+ }
+ const entry = indexLedger(ledger).byId.get(`${pkg}/${component}`);
+ if (!isAudited(entry)) {
+ console.error(`score-ledger: ${component} has no audited row — record it first.`);
+ return 1;
+ }
+
+ const gh = (...argv) =>
+ execFileSync('gh', argv, {encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']}).trim();
+
+ const filed = [];
+ for (const block of blockList(entry)) {
+ if (block.issue) {
+ // Idempotent: never re-file. Reopen if the issue was closed while the
+ // BLOCK is still on the row.
+ if (args['dry-run']) {
+ console.log(` ${block.id}: already filed as #${block.issue} — skipping`);
+ continue;
+ }
+ try {
+ const state = gh('issue', 'view', String(block.issue), '--repo', repo, '--json', 'state', '--jq', '.state');
+ if (state === 'CLOSED') {
+ gh('issue', 'reopen', String(block.issue), '--repo', repo, '--comment',
+ `Reopening: \`${block.id}\` is still an open BLOCK on the ${component} ledger row.`);
+ console.log(` ${block.id}: reopened #${block.issue}`);
+ } else {
+ console.log(` ${block.id}: already filed as #${block.issue}`);
+ }
+ } catch (e) {
+ console.log(`::warning::score-ledger: could not check issue #${block.issue}: ${e.message}`);
+ }
+ continue;
+ }
+ const title = `[audit] ${component}: ${block.summary}`;
+ const body = issueBody(component, entry, block, repo);
+ if (args['dry-run']) {
+ console.log(`\n--- would file ---\n${title}\n\n${body}\n`);
+ continue;
+ }
+ const url = gh('issue', 'create', '--repo', repo, '--title', title, '--label', 'hardening', '--body', body);
+ const number = Number(url.split('/').pop());
+ if (!Number.isInteger(number)) {
+ console.error(`score-ledger: could not parse an issue number out of "${url}"`);
+ return 1;
+ }
+ block.issue = number;
+ filed.push({id: block.id, number});
+ console.log(` ${block.id}: filed #${number} — ${url}`);
+ }
+
+ if (!filed.length) {
+ if (args['dry-run']) console.log('score-ledger: --dry-run — no issue was created.');
+ return 0;
+ }
+
+ ledger.updated = new Date().toISOString().slice(0, 10);
+ const subject =
+ `scores: ${component} — link ${filed.length} audit issue` +
+ `${filed.length === 1 ? '' : 's'} (${filed.map(f => `${f.id} #${f.number}`).join(', ')})`;
+
+ if (!push) {
+ fs.writeFileSync(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`);
+ console.log(`score-ledger: wrote ${ledgerPath} — commit and push it, or re-run with --push.`);
+ return 0;
+ }
+
+ /**
+ * Re-read and re-stamp, rather than replaying the text we computed above: on
+ * a push race the tree is reset to someone else's newer ledger, and writing
+ * our pre-race copy over it would silently drop their record. Stamping issue
+ * numbers onto whatever is on disk merges cleanly by construction.
+ */
+ const applyIssueNumbers = () => {
+ const fresh = JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
+ const row = indexLedger(fresh).byId.get(`${pkg}/${component}`);
+ if (!isAudited(row)) {
+ throw new Error(
+ `${component} no longer has an audited row in the wiki ledger — not stamping issue ` +
+ 'numbers onto a row that moved out from under us.',
+ );
+ }
+ const numbers = new Map(filed.map(f => [f.id, f.number]));
+ for (const block of blockList(row)) {
+ const n = numbers.get(block.id);
+ if (n && !block.issue) block.issue = n;
+ }
+ fresh.updated = new Date().toISOString().slice(0, 10);
+ return {text: `${JSON.stringify(fresh, null, 2)}\n`, message: {subject, body: ''}};
+ };
+
+ try {
+ const result = commitAndPush(repoDir, ledgerPath, applyIssueNumbers);
+ console.log(`score-ledger: pushed ${result.sha.slice(0, 10)}`);
+ console.log(` commit: ${result.url}`);
+ } catch (e) {
+ console.error(`score-ledger --file-issues: ${e.message}`);
+ console.error(
+ `The issues were filed (${filed.map(f => `#${f.number}`).join(', ')}) but the ledger was ` +
+ 'not pushed. Re-run with --push to link them — filing is idempotent.',
+ );
+ return 1;
+ }
+ return 0;
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ if (args.help || args.h) {
+ console.log(USAGE);
+ return 0;
+ }
+ if (args.check) return cmdCheck(args);
+ if (args.queue) return cmdQueue(args);
+ if (args.stats) return cmdStats(args);
+ if (args.record) return cmdRecord(args);
+ if (args['file-issues']) return cmdFileIssues(args);
+ console.log(USAGE);
+ return 1;
+}
+
+// Only run when invoked directly, so tests can import the pure functions.
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+ main().then(
+ code => process.exit(code),
+ err => {
+ console.error(`score-ledger: ${err.message}`);
+ process.exit(1);
+ },
+ );
+}
diff --git a/scripts/score-ledger.test.mjs b/scripts/score-ledger.test.mjs
new file mode 100644
index 0000000000..6f879e329c
--- /dev/null
+++ b/scripts/score-ledger.test.mjs
@@ -0,0 +1,930 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file score-ledger.test.mjs
+ * Unit tests for the component score ledger — chiefly the ratchet, whose whole
+ * job is to fail on a regression this diff caused and on nothing else.
+ *
+ * The behaviours pinned here are the ones a contributor feels:
+ * - an unaudited component never blocks;
+ * - debt already on the row never blocks;
+ * - a new BLOCK blocks even when the total went up;
+ * - a rubric-version change is `incomparable`, not a failure;
+ * - an unreadable ledger passes.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+import http from 'node:http';
+
+import {describe, it, expect} from 'vitest';
+
+import {
+ SCORES_PAGE_URL,
+ SECTION_WEIGHTS,
+ SECTION_IDS,
+ applyScorecard,
+ blockLink,
+ buildQueue,
+ buildRoster,
+ buildStats,
+ commitMessage,
+ compareEntry,
+ gradeFor,
+ isComponentDirectory,
+ issueBody,
+ listComponents,
+ LEDGER_FETCH_TIMEOUT_MS,
+ loadLedger,
+ repoFromWikiRemote,
+ resolveName,
+ runRatchet,
+ weakestSection,
+ wikiCommitUrl,
+} from './score-ledger.mjs';
+
+const REPO_ROOT = path.resolve(import.meta.dirname, '..');
+
+/** A minimal audited entry. */
+const entry = (over = {}) => ({
+ component: 'Button',
+ package: 'core',
+ status: 'audited',
+ score: 70,
+ grade: 'C',
+ sections: {},
+ blocks: {count: 0, open: []},
+ distinct_defects: 1,
+ fixes: null,
+ nits: null,
+ lastAudited: '2026-08-01',
+ rubricVersion: '1.2',
+ mode: 'O',
+ commit: 'abc1234567',
+ evidence: [],
+ ...over,
+});
+
+const withBlocks = (...blocks) => ({
+ count: blocks.length,
+ open: blocks.map(b => (typeof b === 'string' ? {id: b, summary: b, issue: null} : b)),
+});
+
+// ---------------------------------------------------------------------------
+
+describe('the ratchet', () => {
+ it('passes an unaudited component — no baseline, judged on merits', () => {
+ const r = compareEntry('Toast', null, null);
+ expect(r.verdict).toBe('pass');
+ expect(r.reason).toMatch(/unaudited/);
+ // Nothing that reads as an accusation against the pull request.
+ expect(r.reason).not.toMatch(/BLOCK|fail|regress/i);
+ });
+
+ it('passes when only the head is unaudited', () => {
+ expect(compareEntry('Button', entry(), null).verdict).toBe('pass');
+ });
+
+ it('passes the first audit — there is nothing to ratchet against', () => {
+ const r = compareEntry('Button', null, entry({score: 41}));
+ expect(r.verdict).toBe('pass');
+ expect(r.reason).toMatch(/first audit/);
+ });
+
+ it('passes known debt that did not change', () => {
+ const base = entry({score: 62.6, blocks: withBlocks('A11', 'T6')});
+ const head = entry({score: 62.6, blocks: withBlocks('A11', 'T6')});
+ const r = compareEntry('Button', base, head);
+ expect(r.verdict).toBe('pass');
+ expect(r.reason).toBe('unchanged');
+ expect(r.newBlocks).toEqual([]);
+ });
+
+ it('passes an improvement', () => {
+ const r = compareEntry(
+ 'Button',
+ entry({score: 62.6, blocks: withBlocks('A11')}),
+ entry({score: 75, blocks: withBlocks('A11')}),
+ );
+ expect(r.verdict).toBe('pass');
+ expect(r.reason).toMatch(/improved 62\.6 -> 75/);
+ });
+
+ it('fails a score decrease', () => {
+ const r = compareEntry('Button', entry({score: 70}), entry({score: 69.9}));
+ expect(r.verdict).toBe('fail');
+ expect(r.reason).toBe('score decreased 70 -> 69.9');
+ });
+
+ it('fails a new BLOCK even when the score went UP', () => {
+ const r = compareEntry(
+ 'Button',
+ entry({score: 62.6, blocks: withBlocks('A11')}),
+ entry({
+ score: 88,
+ grade: 'C',
+ blocks: withBlocks('A11', {id: 'T6', summary: 'elevation is unthemeable', issue: 99}),
+ }),
+ );
+ expect(r.verdict).toBe('fail');
+ expect(r.reason).toMatch(/new BLOCK: T6/);
+ expect(r.newBlocks.map(b => b.id)).toEqual(['T6']);
+ });
+
+ it('names only the NEW BLOCK, never the inherited ones', () => {
+ const r = compareEntry(
+ 'SideNav',
+ entry({blocks: withBlocks('A13', 'I2')}),
+ entry({blocks: withBlocks('A13', 'I2', 'D13')}),
+ );
+ expect(r.reason).toContain('D13');
+ expect(r.reason).not.toContain('A13');
+ expect(r.reason).not.toContain('I2');
+ });
+
+ it('fails when the BLOCK count rises with no named id — the count is the authority', () => {
+ const r = compareEntry(
+ 'Tooltip',
+ entry({blocks: {count: 4, open: [{id: 'A8', summary: 'no touch path', issue: 3885}]}}),
+ entry({blocks: {count: 5, open: [{id: 'A8', summary: 'no touch path', issue: 3885}]}}),
+ );
+ expect(r.verdict).toBe('fail');
+ expect(r.reason).toMatch(/count rose 4 -> 5/);
+ });
+
+ it('reports `incomparable` on a rubric-version change and does NOT fail', () => {
+ const r = compareEntry(
+ 'Button',
+ entry({score: 62.6, rubricVersion: '1.1'}),
+ entry({score: 41, rubricVersion: '1.2'}),
+ );
+ expect(r.verdict).toBe('incomparable');
+ expect(r.verdict).not.toBe('fail');
+ expect(r.reason).toMatch(/incomparable — rubric version changed \(1\.1 -> 1\.2\)/);
+ expect(r.reason).toMatch(/re-audit/);
+ });
+
+ it('does not fail on a version change even when a new BLOCK appears — the scales differ', () => {
+ const r = compareEntry(
+ 'Button',
+ entry({rubricVersion: '1.1', blocks: withBlocks('A11')}),
+ entry({rubricVersion: '1.2', blocks: withBlocks('A11', 'D13')}),
+ );
+ expect(r.verdict).toBe('incomparable');
+ });
+
+ it('runRatchet fails the run when any component regressed', () => {
+ const base = {components: [entry({component: 'Button'}), entry({component: 'Badge'})]};
+ const head = {
+ components: [entry({component: 'Button'}), entry({component: 'Badge', score: 10})],
+ };
+ const {results, failed} = runRatchet(['Button', 'Badge'], base, head);
+ expect(failed).toBe(true);
+ expect(results.find(r => r.component === 'Button').verdict).toBe('pass');
+ expect(results.find(r => r.component === 'Badge').verdict).toBe('fail');
+ });
+
+ it('runRatchet passes when a touched component is absent from both ledgers', () => {
+ const {failed, results} = runRatchet(['Toast'], {components: []}, {components: []});
+ expect(failed).toBe(false);
+ expect(results[0].verdict).toBe('pass');
+ });
+});
+
+describe('a component is a package AND a name', () => {
+ // `Chat` ships in both core and lab. A name-keyed ledger would ratchet one
+ // against the other, which is worse than not measuring either.
+ it('resolves a name that exists in two packages to both components', () => {
+ const matches = resolveName('Chat', listComponents(REPO_ROOT));
+ expect(matches.map(m => m.package).sort()).toEqual(['core', 'lab']);
+ });
+
+ it('keeps the two apart in the ratchet — a lab score cannot fail a core PR', () => {
+ const base = {
+ components: [
+ entry({component: 'Chat', package: 'core', score: 80, grade: 'B'}),
+ entry({component: 'Chat', package: 'lab', score: 80, grade: 'B'}),
+ ],
+ };
+ const head = {
+ components: [
+ entry({component: 'Chat', package: 'core', score: 80, grade: 'B'}),
+ entry({component: 'Chat', package: 'lab', score: 40, grade: 'F'}),
+ ],
+ };
+ const {results} = runRatchet(['Chat'], base, head);
+ expect(results.map(r => r.component).sort()).toEqual(['core/Chat', 'lab/Chat']);
+ expect(results.find(r => r.component === 'core/Chat').verdict).toBe('pass');
+ expect(results.find(r => r.component === 'lab/Chat').verdict).toBe('fail');
+ });
+
+ it('gives each roster row a package-qualified id', () => {
+ const roster = buildRoster({components: []}, [
+ {component: 'Chat', package: 'core'},
+ {component: 'Chat', package: 'lab'},
+ ]);
+ expect(roster.map(r => r.id)).toEqual(['core/Chat', 'lab/Chat']);
+ });
+});
+
+describe('loadLedger never throws', () => {
+ it('reports an unreadable path instead of throwing, so CI can pass with a warning', async () => {
+ const {ledger, error} = await loadLedger('/nonexistent/component-scores.json');
+ expect(ledger).toBeNull();
+ expect(error).toMatch(/component-scores\.json/);
+ });
+
+ it('rejects JSON that is not a ledger', async () => {
+ const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ledger-')), 'l.json');
+ fs.writeFileSync(file, JSON.stringify({nope: true}));
+ const {ledger, error} = await loadLedger(file);
+ expect(ledger).toBeNull();
+ expect(error).toMatch(/missing a `components` array/);
+ });
+
+ it('reads a real ledger', async () => {
+ const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ledger-')), 'l.json');
+ fs.writeFileSync(file, JSON.stringify({ledgerVersion: 1, components: [entry()]}));
+ const {ledger, error} = await loadLedger(file);
+ expect(error).toBeNull();
+ expect(ledger.components).toHaveLength(1);
+ });
+});
+
+describe('the ledger fetch is bounded', () => {
+ /**
+ * The failure that matters is not an error — a 404 already resolves to
+ * `{ledger: null}` — but a STALL: a connection that is accepted and then
+ * goes quiet. A bare fetch() inherits undici's defaults, whose headers
+ * timeout is minutes, which would hang a sandbox build rather than fall
+ * through to the snapshot-less path.
+ */
+ it('gives up on a server that accepts the connection and never answers', async () => {
+ const sockets = new Set();
+ const server = http.createServer(() => {
+ // Deliberately never respond.
+ });
+ server.on('connection', s => {
+ sockets.add(s);
+ s.on('close', () => sockets.delete(s));
+ });
+ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+ const url = `http://127.0.0.1:${server.address().port}/component-scores.json`;
+
+ try {
+ const started = Date.now();
+ const {ledger, error} = await loadLedger(url, {timeoutMs: 250});
+ const elapsed = Date.now() - started;
+
+ expect(ledger).toBeNull();
+ expect(error).toContain('no response within 250ms');
+ // The point of the test: it came back, and quickly.
+ expect(elapsed).toBeLessThan(3000);
+ } finally {
+ for (const s of sockets) s.destroy();
+ await new Promise(resolve => server.close(resolve));
+ }
+ });
+
+ it('defaults to a bounded timeout rather than undici\'s minutes', () => {
+ expect(LEDGER_FETCH_TIMEOUT_MS).toBeGreaterThan(0);
+ expect(LEDGER_FETCH_TIMEOUT_MS).toBeLessThanOrEqual(30_000);
+ });
+});
+
+describe('the canonical component predicate', () => {
+ const coreSrc = path.join(REPO_ROOT, 'packages/core/src');
+
+ it('accepts a real component directory', () => {
+ expect(isComponentDirectory(coreSrc, 'Button')).toBe(true);
+ expect(isComponentDirectory(coreSrc, 'Badge')).toBe(true);
+ });
+
+ it('rejects the infrastructure directories', () => {
+ for (const dir of ['hooks', 'theme', 'utils', 'i18n', '__tests__']) {
+ expect(isComponentDirectory(coreSrc, dir), dir).toBe(false);
+ }
+ });
+
+ it('rejects a styles-only directory (NavItem)', () => {
+ expect(isComponentDirectory(coreSrc, 'NavItem')).toBe(false);
+ });
+
+ it('rejects context-only directories that render nothing', () => {
+ expect(isComponentDirectory(coreSrc, 'SizeContext')).toBe(false);
+ expect(isComponentDirectory(coreSrc, 'InteractiveRoleContext')).toBe(false);
+ });
+
+ it('rejects a directory that does not exist', () => {
+ expect(isComponentDirectory(coreSrc, 'NotAThing')).toBe(false);
+ });
+
+ it('lists both packages, sorted, with no infrastructure', () => {
+ const all = listComponents(REPO_ROOT);
+ const names = all.map(c => c.component);
+ expect(names).toContain('Button');
+ expect(names).toContain('Stepper');
+ expect(names).not.toContain('hooks');
+ expect(names).not.toContain('NavItem');
+ expect([...names].sort((a, b) => a.localeCompare(b))).toEqual(names);
+ expect(new Set(all.map(c => c.package))).toEqual(new Set(['core', 'lab']));
+ });
+});
+
+describe('grades', () => {
+ it('bands by score', () => {
+ expect(gradeFor(95)).toBe('A');
+ expect(gradeFor(80)).toBe('B');
+ expect(gradeFor(70)).toBe('C');
+ expect(gradeFor(60)).toBe('D');
+ expect(gradeFor(59.9)).toBe('F');
+ expect(gradeFor(null)).toBeNull();
+ });
+
+ it('caps at C when any BLOCK is open, whatever the arithmetic says', () => {
+ expect(gradeFor(95, 1)).toBe('C');
+ expect(gradeFor(85, 3)).toBe('C');
+ expect(gradeFor(65, 1)).toBe('D');
+ expect(gradeFor(40, 9)).toBe('F');
+ });
+});
+
+describe('the section vocabulary matches the rubric', () => {
+ it('weights sum to 100', () => {
+ expect(Object.values(SECTION_WEIGHTS).reduce((a, b) => a + b, 0)).toBe(100);
+ });
+
+ it('carries all eleven rubric sections', () => {
+ expect(SECTION_IDS).toEqual([
+ 'a11y',
+ 'theming',
+ 'api',
+ 'behavior',
+ 'design_objective',
+ 'design_rendered',
+ 'testing',
+ 'code_health',
+ 'docs',
+ 'i18n_rtl',
+ 'responsive',
+ ]);
+ });
+
+ it('reads the weakest SCORED section, ignoring unmeasured ones', () => {
+ const e = entry({
+ sections: {
+ a11y: {score: 1, weight: 16, state: 'unpublished'},
+ design_objective: {score: 4, weight: 6, state: 'scored'},
+ design_rendered: {score: 2, weight: 4, state: 'scored'},
+ testing: {score: 0, weight: 8, state: 'not_measured'},
+ },
+ });
+ expect(weakestSection(e)).toEqual({id: 'design_rendered', score: 2});
+ });
+});
+
+describe('roster, queue and stats', () => {
+ const roster = [
+ {component: 'Alpha', package: 'core', live: true, entry: null},
+ {
+ component: 'Beta',
+ package: 'core',
+ live: true,
+ entry: entry({component: 'Beta', score: 80, grade: 'B', lastAudited: '2026-07-01'}),
+ },
+ {
+ component: 'Gamma',
+ package: 'lab',
+ live: true,
+ entry: entry({
+ component: 'Gamma',
+ score: 50,
+ grade: 'F',
+ lastAudited: '2026-06-01',
+ blocks: withBlocks('A1', 'A2'),
+ }),
+ },
+ {component: 'Zeta', package: 'lab', live: true, entry: null},
+ ];
+
+ it('queues never-audited components first, alphabetically', () => {
+ const q = buildQueue(roster);
+ expect(q.slice(0, 2).map(e => e.component)).toEqual(['Alpha', 'Zeta']);
+ expect(q[0].why).toBe('never audited');
+ });
+
+ it('then queues audited components oldest-first', () => {
+ const q = buildQueue(roster);
+ expect(q.slice(2).map(e => e.component)).toEqual(['Gamma', 'Beta']);
+ });
+
+ it('honours --limit', () => {
+ expect(buildQueue(roster, 3)).toHaveLength(3);
+ });
+
+ it('joins the live roster with the ledger and flags orphan rows', () => {
+ const ledger = {
+ components: [entry({component: 'Beta'}), entry({component: 'Deleted'})],
+ };
+ const joined = buildRoster(ledger, [
+ {component: 'Alpha', package: 'core'},
+ {component: 'Beta', package: 'core'},
+ ]);
+ expect(joined.map(r => r.component)).toEqual(['Alpha', 'Beta', 'Deleted']);
+ expect(joined.find(r => r.component === 'Alpha').entry).toBeNull();
+ expect(joined.find(r => r.component === 'Deleted').live).toBe(false);
+ });
+
+ it('summarises coverage, grades and open BLOCKs', () => {
+ const s = buildStats(roster);
+ expect(s.total).toBe(4);
+ expect(s.audited).toBe(2);
+ expect(s.unaudited).toBe(2);
+ expect(s.percentAudited).toBe(50);
+ expect(s.grades).toMatchObject({B: 1, F: 1});
+ expect(s.openBlocks).toBe(2);
+ expect(s.componentsWithBlocks).toBe(1);
+ expect(s.oldestAudit).toBe('2026-06-01');
+ expect(s.byPackage.core).toEqual({total: 2, audited: 1});
+ });
+});
+
+describe('recording a scorecard', () => {
+ const card = {
+ score: 74.2,
+ lastAudited: '2026-08-10',
+ rubricVersion: '1.2',
+ mode: 'O',
+ commit: 'dccdabea0b',
+ blocks: {count: 1, open: [{id: 'A18', summary: 'baseline entries silence axe'}]},
+ };
+
+ it('derives the grade, applying the open-BLOCK cap', () => {
+ const e = applyScorecard(null, card, {component: 'Badge', pkg: 'core'});
+ expect(e.grade).toBe('C');
+ expect(e.status).toBe('audited');
+ expect(e.package).toBe('core');
+ });
+
+ it('normalises a BLOCK with no issue to `issue: null` rather than dropping it', () => {
+ const e = applyScorecard(null, card, {component: 'Badge', pkg: 'core'});
+ expect(e.blocks.open[0].issue).toBeNull();
+ });
+
+ it('rejects a grade that contradicts the score', () => {
+ expect(() =>
+ applyScorecard(null, {...card, grade: 'A'}, {component: 'Badge', pkg: 'core'}),
+ ).toThrow(/contradicts score/);
+ });
+
+ it('rejects an unknown field rather than storing it silently', () => {
+ expect(() =>
+ applyScorecard(null, {...card, sore: 74}, {component: 'Badge', pkg: 'core'}),
+ ).toThrow(/unknown scorecard field\(s\): sore/);
+ });
+
+ it('rejects an unknown section id and an unknown section state', () => {
+ expect(() =>
+ applyScorecard(null, {...card, sections: {a11yy: {score: 3}}}, {component: 'B', pkg: 'core'}),
+ ).toThrow(/unknown section id/);
+ expect(() =>
+ applyScorecard(
+ null,
+ {...card, sections: {a11y: {score: 3, state: 'vibes'}}},
+ {component: 'B', pkg: 'core'},
+ ),
+ ).toThrow(/unknown section state/);
+ });
+
+ it('fills each section weight from the rubric', () => {
+ const e = applyScorecard(
+ null,
+ {...card, sections: {a11y: {score: 3, state: 'scored'}}},
+ {component: 'B', pkg: 'core'},
+ );
+ expect(e.sections.a11y.weight).toBe(16);
+ });
+
+ it('rejects more listed BLOCKs than the count claims', () => {
+ expect(() =>
+ applyScorecard(
+ null,
+ {...card, blocks: {count: 1, open: [{id: 'A1', summary: 'x'}, {id: 'A2', summary: 'y'}]}},
+ {component: 'B', pkg: 'core'},
+ ),
+ ).toThrow(/BLOCKs listed but blocks.count is 1/);
+ });
+
+ it('refuses to store an unaudited row — an unaudited component simply has none', () => {
+ expect(() =>
+ applyScorecard(null, {...card, status: 'unaudited'}, {component: 'B', pkg: 'core'}),
+ ).toThrow(/audited components only/);
+ });
+
+ it('requires the rubric version, the date and the mode', () => {
+ for (const field of ['rubricVersion', 'lastAudited', 'mode']) {
+ const partial = {...card};
+ delete partial[field];
+ expect(() =>
+ applyScorecard(null, partial, {component: 'B', pkg: 'core'}),
+ field,
+ ).toThrow(new RegExp(field));
+ }
+ });
+});
+
+describe('issue plumbing', () => {
+ it('links a filed BLOCK and says so when one is not filed', () => {
+ expect(blockLink({id: 'A8', summary: 'x', issue: 3885})).toContain(
+ 'https://github.com/facebook/astryx/issues/3885',
+ );
+ expect(blockLink({id: 'A8', summary: 'x', issue: null})).toContain('no issue filed');
+ });
+
+ it('writes an issue body that stands on its own', () => {
+ const body = issueBody(
+ 'Button',
+ entry({mode: 'O', rubricVersion: '1.2', commit: 'dccdabea0b', score: 62.6, grade: 'D'}),
+ {
+ id: 'T6',
+ section: '§2 Theming & token integrity',
+ summary: 'elevation is absent from themeProps',
+ evidence: 'Button.tsx',
+ fix: 'add elevation to the themeProps call on the painting element',
+ },
+ );
+ expect(body).toContain('`T6`');
+ expect(body).toContain('§2 Theming & token integrity');
+ expect(body).toContain('rubric **v1.2**');
+ expect(body).toContain('Component-Audit-Rubric');
+ // The row is readable on the sandbox page, never on a generated wiki table.
+ expect(body).toContain(SCORES_PAGE_URL);
+ expect(body).not.toContain('wiki/Component-Scores');
+ expect(body).toContain('Button.tsx');
+ expect(body).toContain('Closing protocol');
+ expect(body).toContain("If the recorded score doesn't move");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// The write path: --record, --dry-run and --push
+//
+// These drive the real CLI against a real git remote in a temp dir. The push
+// path is the whole point of the tool — an audit that isn't recorded didn't
+// happen — so it is tested end to end rather than mocked, including the case
+// two agents race to record at the same moment.
+// ---------------------------------------------------------------------------
+
+const SCRIPT = path.join(REPO_ROOT, 'scripts', 'score-ledger.mjs');
+
+const git = (cwd, ...argv) =>
+ execFileSync('git', argv, {cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']}).trim();
+
+/** Run the CLI and capture everything, exit code included. */
+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 (e) {
+ return {code: e.status ?? 1, out: `${e.stdout || ''}${e.stderr || ''}`};
+ }
+}
+
+const ledgerWith = (...components) => ({
+ ledgerVersion: 1,
+ rubricVersion: '1.2',
+ updated: '2026-08-01',
+ components,
+});
+
+/** A scorecard the validator accepts. */
+const scorecard = (over = {}) => ({
+ status: 'audited',
+ score: 81,
+ sections: {a11y: {score: 4, state: 'scored'}},
+ blocks: {count: 0, open: []},
+ distinct_defects: 2,
+ lastAudited: '2026-08-11',
+ rubricVersion: '1.2',
+ mode: 'O',
+ commit: 'abc1234567',
+ ...over,
+});
+
+/**
+ * A bare repo standing in for the wiki, plus a working clone of it. The clone
+ * is shallow and pushes over file://, exactly as `ensureWikiClone` produces.
+ */
+function makeWiki(seedLedger) {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'score-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, 'component-scores.json'),
+ `${JSON.stringify(seedLedger, null, 2)}\n`,
+ );
+ git(seed, 'add', '-A');
+ git(seed, 'commit', '-m', 'seed');
+ git(seed, 'push', 'origin', 'master');
+
+ git(root, 'clone', '--depth', '1', `file://${bare}`, clone);
+ identify(clone);
+ return {root, bare, clone, ledger: path.join(clone, 'component-scores.json')};
+}
+
+function identify(dir) {
+ git(dir, 'config', 'user.name', 'Ledger Test');
+ git(dir, 'config', 'user.email', '[email protected]');
+}
+
+const readLedger = file => JSON.parse(fs.readFileSync(file, 'utf8'));
+
+/** What the remote actually holds, which is the only thing that counts. */
+const remoteLedger = bare =>
+ JSON.parse(git(bare, 'show', 'master:component-scores.json'));
+
+describe('the commit message', () => {
+ it('names the component, the grade, the score and the rubric version', () => {
+ expect(commitMessage(entry({score: 62.6, grade: 'D'})).subject).toBe(
+ 'scores: Button D (62.6), rubric 1.2',
+ );
+ });
+
+ it('qualifies an ambiguous name with its package — Chat is two components', () => {
+ const {subject} = commitMessage(
+ entry({component: 'Chat', package: 'lab', score: 70, grade: 'C'}),
+ {ambiguous: true},
+ );
+ expect(subject).toBe('scores: lab/Chat C (70.0), rubric 1.2');
+ });
+
+ it('puts the regression reason in the body, with the numbers it moved from', () => {
+ const {subject, body} = commitMessage(entry({score: 55, grade: 'F'}), {
+ regression: {reason: 'rescored under a stricter reading of A8', from: {score: 70, blocks: 1}},
+ });
+ expect(subject).toBe('scores: Button F (55.0), rubric 1.2');
+ expect(body).toContain('Regression allowed: rescored under a stricter reading of A8');
+ expect(body).toContain('Score 70.0 → 55.0');
+ });
+});
+
+describe('wiki URLs', () => {
+ it('reads the repo out of a wiki remote, https or ssh', () => {
+ expect(repoFromWikiRemote('https://github.com/facebook/astryx.wiki.git')).toBe(
+ 'facebook/astryx',
+ );
+ expect(repoFromWikiRemote('[email protected]:facebook/astryx.wiki.git')).toBe('facebook/astryx');
+ });
+
+ it('builds a commit URL GitHub actually serves', () => {
+ expect(wikiCommitUrl('deadbeef')).toBe(
+ 'https://github.com/facebook/astryx/wiki/_compare/deadbeef',
+ );
+ });
+});
+
+describe('--record', () => {
+ it('reads the scorecard from stdin with --from -, so an agent needs no temp file', () => {
+ const wiki = makeWiki(ledgerWith());
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger], {
+ input: JSON.stringify(scorecard()),
+ });
+ expect(r.code).toBe(0);
+ const row = readLedger(wiki.ledger).components.find(c => c.component === 'Button');
+ expect(row).toMatchObject({package: 'core', grade: 'B', score: 81});
+ });
+
+ it('refuses a regression, and writes nothing at all', () => {
+ const seeded = ledgerWith(entry({score: 90, grade: 'A'}));
+ const wiki = makeWiki(seeded);
+ const before = fs.readFileSync(wiki.ledger, 'utf8');
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger], {
+ input: JSON.stringify(scorecard({score: 70})),
+ });
+ expect(r.code).toBe(1);
+ expect(r.out).toContain('refusing');
+ expect(fs.readFileSync(wiki.ledger, 'utf8')).toBe(before);
+ });
+
+ it('records the reason on the row when a regression is allowed', () => {
+ const wiki = makeWiki(ledgerWith(entry({score: 90, grade: 'A'})));
+ const r = cli([
+ '--record', 'Button',
+ '--from', '-',
+ '--ledger', wiki.ledger,
+ '--allow-regression', 'rescored under v1.2 §5 split',
+ ], {input: JSON.stringify(scorecard({score: 70}))});
+ expect(r.code).toBe(0);
+ const row = readLedger(wiki.ledger).components.find(c => c.component === 'Button');
+ expect(row.regression.reason).toBe('rescored under v1.2 §5 split');
+ expect(row.regression.from).toEqual({score: 90, blocks: 0});
+ });
+
+ /**
+ * `rubricVersion` is the one field the writer controls, and `compareEntry`
+ * calls a version change `incomparable` rather than `fail`. Without this the
+ * guard is bypassed by editing that string: a real 74.2 was overwritten with
+ * a 30 and pushed, in exactly this way, while testing.
+ */
+ it('still demands a reason when the rubric version changed and the numbers fell', () => {
+ const wiki = makeWiki(ledgerWith(entry({score: 74.2, grade: 'C', rubricVersion: '1.1'})));
+ const before = fs.readFileSync(wiki.ledger, 'utf8');
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger], {
+ input: JSON.stringify(scorecard({score: 30, rubricVersion: '1.2'})),
+ });
+ expect(r.code).toBe(1);
+ expect(r.out).toContain('refusing');
+ expect(r.out).toContain('the numbers went down');
+ expect(fs.readFileSync(wiki.ledger, 'utf8')).toBe(before);
+ });
+
+ it('lets a rubric-version RE-SCORE through when the reason is given', () => {
+ const wiki = makeWiki(ledgerWith(entry({score: 74.2, grade: 'C', rubricVersion: '1.1'})));
+ const r = cli([
+ '--record', 'Button', '--from', '-', '--ledger', wiki.ledger,
+ '--allow-regression', 're-audited under v1.2, which splits §5',
+ ], {input: JSON.stringify(scorecard({score: 30, rubricVersion: '1.2'}))});
+ expect(r.code).toBe(0);
+ const row = readLedger(wiki.ledger).components.find(c => c.component === 'Button');
+ expect(row.regression.from).toEqual({score: 74.2, blocks: 0});
+ });
+
+ it('does not demand a reason when a version change IMPROVES the numbers', () => {
+ const wiki = makeWiki(ledgerWith(entry({score: 60, grade: 'D', rubricVersion: '1.1'})));
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger], {
+ input: JSON.stringify(scorecard({score: 81, rubricVersion: '1.2'})),
+ });
+ expect(r.code).toBe(0);
+ const row = readLedger(wiki.ledger).components.find(c => c.component === 'Button');
+ expect(row.regression).toBeUndefined();
+ });
+
+ it('rejects a bare --allow-regression — the reason is the point', () => {
+ const wiki = makeWiki(ledgerWith(entry({score: 90, grade: 'A'})));
+ const r = cli([
+ '--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--allow-regression',
+ ], {input: JSON.stringify(scorecard({score: 70}))});
+ expect(r.code).toBe(1);
+ expect(r.out).toContain('needs a reason');
+ });
+
+ it('--dry-run prints the diff and the commit message and changes nothing', () => {
+ const wiki = makeWiki(ledgerWith());
+ const before = fs.readFileSync(wiki.ledger, 'utf8');
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--dry-run'], {
+ input: JSON.stringify(scorecard()),
+ });
+ expect(r.code).toBe(0);
+ expect(r.out).toContain('--- a/component-scores.json');
+ expect(r.out).toContain('+ "component": "Button"');
+ expect(r.out).toContain('scores: Button B (81.0), rubric 1.2');
+ expect(r.out).toContain('nothing written');
+ expect(fs.readFileSync(wiki.ledger, 'utf8')).toBe(before);
+ });
+
+ it('without --push or --ledger it says how to write, rather than guessing', () => {
+ const r = cli(['--record', 'Button', '--from', '-'], {input: JSON.stringify(scorecard())});
+ expect(r.code).toBe(1);
+ expect(r.out).toContain('--push');
+ });
+});
+
+describe('--record --push', () => {
+ it('commits and pushes in one command, and prints the commit URL', () => {
+ const wiki = makeWiki(ledgerWith());
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--push'], {
+ input: JSON.stringify(scorecard()),
+ });
+ expect(r.code).toBe(0);
+ expect(r.out).toContain('/wiki/_compare/');
+ expect(remoteLedger(wiki.bare).components.map(c => c.component)).toEqual(['Button']);
+ expect(git(wiki.clone, 'log', '-1', '--format=%s')).toBe(
+ 'scores: Button B (81.0), rubric 1.2',
+ );
+ });
+
+ it('pushes nothing when the apply is not clean', () => {
+ const wiki = makeWiki(ledgerWith(entry({score: 90, grade: 'A'})));
+ const head = git(wiki.bare, 'rev-parse', 'master');
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--push'], {
+ input: JSON.stringify(scorecard({score: 70})),
+ });
+ expect(r.code).toBe(1);
+ expect(git(wiki.bare, 'rev-parse', 'master')).toBe(head);
+ });
+
+ it('carries the regression reason into the commit message', () => {
+ const wiki = makeWiki(ledgerWith(entry({score: 90, grade: 'A'})));
+ const r = cli([
+ '--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--push',
+ '--allow-regression', 'A8 was scored too kindly in the calibration pass',
+ ], {input: JSON.stringify(scorecard({score: 70}))});
+ expect(r.code).toBe(0);
+ const message = git(wiki.clone, 'log', '-1', '--format=%B');
+ expect(message).toContain('scores: Button C (70.0), rubric 1.2');
+ expect(message).toContain('A8 was scored too kindly in the calibration pass');
+ });
+
+ it('refuses to commit with no git identity', () => {
+ const wiki = makeWiki(ledgerWith());
+ git(wiki.clone, 'config', '--unset', 'user.name');
+ git(wiki.clone, 'config', '--unset', 'user.email');
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--push'], {
+ input: JSON.stringify(scorecard()),
+ env: {GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null'},
+ });
+ expect(r.code).toBe(1);
+ expect(r.out).toContain('no git identity');
+ });
+
+ it('refuses to sweep unrelated wiki edits into the commit', () => {
+ const wiki = makeWiki(ledgerWith());
+ fs.writeFileSync(path.join(wiki.clone, 'Home.md'), 'half-finished edit\n');
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--push'], {
+ input: JSON.stringify(scorecard()),
+ });
+ expect(r.code).toBe(1);
+ expect(r.out).toContain('unrelated changes');
+ });
+
+ /**
+ * The concurrency case, for real. An `update` hook on the remote lands a
+ * competing record and rejects the first push; the tool must re-apply onto
+ * what the other agent wrote instead of overwriting it. Both rows survive.
+ */
+ it('re-applies onto the winner and keeps both records when two agents race', () => {
+ const wiki = makeWiki(ledgerWith());
+ const competing = ledgerWith(
+ entry({component: 'Badge', score: 74.2, grade: 'C', lastAudited: '2026-08-09'}),
+ );
+ 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',
+ 'git read-tree master',
+ `blob=$(git hash-object -w -- ${JSON.stringify(competingFile).slice(1, -1)})`,
+ 'git update-index --add --cacheinfo 100644,$blob,component-scores.json',
+ 'tree=$(git write-tree)',
+ 'commit=$(git commit-tree $tree -p master -m "scores: Badge C (74.2), rubric 1.2")',
+ 'git update-ref refs/heads/master $commit',
+ 'echo "rejected: non-fast-forward (simulated race)" >&2',
+ 'exit 1',
+ ].join('\n'),
+ );
+ fs.chmodSync(hook, 0o755);
+
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger, '--push'], {
+ input: JSON.stringify(scorecard()),
+ });
+ expect(r.code).toBe(0);
+ expect(r.out).toContain('retrying once');
+ expect(remoteLedger(wiki.bare).components.map(c => c.component).sort()).toEqual([
+ 'Badge',
+ 'Button',
+ ]);
+ });
+});
+
+describe('the generated table is gone', () => {
+ it('--report is not a subcommand any more', () => {
+ const r = cli(['--report']);
+ expect(r.code).toBe(1);
+ expect(r.out).toContain('Usage:');
+ expect(r.out).not.toContain('--report');
+ });
+
+ it('recording writes the JSON and nothing beside it', () => {
+ const wiki = makeWiki(ledgerWith());
+ const r = cli(['--record', 'Button', '--from', '-', '--ledger', wiki.ledger], {
+ input: JSON.stringify(scorecard()),
+ });
+ expect(r.code).toBe(0);
+ expect(fs.readdirSync(wiki.clone).filter(f => f !== '.git')).toEqual([
+ 'component-scores.json',
+ ]);
+ });
+});