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.tsindex 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.jsonindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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">{categoriesdiff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.tsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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',+ ]);+ });+});