Skip to content

Commit 8b3a99f

Browse files
committed
tooling(cutover): check:adr-anchors excuses released objectui changelog lines, one number per file (objectstack#25803)
Bill item 19: objectui's CHANGELOG.md entries cite its decision 0075 with the bare prefix. A changelog is release-owned history no code PR may edit, so the audit gains RELEASE_OWNED_CITATIONS: rows keyed by file and number, accepted only for a CHANGELOG.md, stale in both directions (number gains a record, file stops citing it). The same number anywhere else still reds. Five synthetic cases pin it. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CUXv64KLMfYv3ia2sWi6te
1 parent 02c4c02 commit 8b3a99f

1 file changed

Lines changed: 140 additions & 7 deletions

File tree

‎scripts/check-adr-anchors.mjs‎

Lines changed: 140 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -234,7 +234,7 @@
234234

235235
import { execFileSync } from 'node:child_process';
236236
import { readFileSync, readdirSync, existsSync } from 'node:fs';
237-
import { join } from 'node:path';
237+
import { join, posix } from 'node:path';
238238

239239
import { ANCHORS_DIR, assembleAnchors, loadAnchors, shardNameFor } from './adr-anchors.mjs';
240240

@@ -407,6 +407,43 @@ const UNRESOLVED_ADR_CITATIONS = [
407407
// exists so nobody re-derives the discrepancy from the removed entry's text.
408408
];
409409

410+
/**
411+
* ⛔ SHRINK-ONLY. Dangling citations that sit in a RELEASE-OWNED file — a
412+
* `CHANGELOG.md`, which AGENTS.md's documentation guardrails forbid any code PR
413+
* to edit: it is compiled from changesets at release time and ships in the npm
414+
* tarball as the record of what was released. A citation there is history; the
415+
* remedy the dangling-citation message offers (cite the right number, spell the
416+
* sibling registry) is an edit to that history, which no PR may make.
417+
*
418+
* Keyed by FILE AND NUMBER, never by number alone: unlike
419+
* {@link UNRESOLVED_ADR_CITATIONS} an entry here excuses one number in one file,
420+
* so the same id written anywhere else — a new source comment, a test, another
421+
* changelog — still reds exactly as before. Every entry must name a file whose
422+
* basename is `CHANGELOG.md` (the audit refuses any other path, so this cannot
423+
* become a general mute list), and the audit fails an entry in BOTH directions
424+
* the way it fails the list above: the number gained a record, or the file no
425+
* longer cites it.
426+
*
427+
* The rows arrived with the objectui import at the cutover (#25752, bill item
428+
* 19): objectui's own `CHANGELOG.md` entries cite its decision 0075 with the bare
429+
* prefix, which objectui's registry used for itself and which names no record
430+
* here. The source and test citations of the same decision were respelled with
431+
* the `ObjectUI` qualifier in objectui before the import; only the released
432+
* changelog lines stay as written.
433+
*/
434+
const RELEASE_OWNED_CITATIONS = [
435+
{
436+
file: 'ui/apps/console/CHANGELOG.md',
437+
number: '0075',
438+
why: 'objectui release notes for the root landing redirect (objectui decision 0075), released before the cutover',
439+
},
440+
{
441+
file: 'ui/packages/app-shell/CHANGELOG.md',
442+
number: '0075',
443+
why: 'objectui release notes for the home path declaration (objectui decision 0075), released before the cutover',
444+
},
445+
];
446+
410447
/**
411448
* ⛔ SHRINK-ONLY. The number collisions that already existed when this audit
412449
* was written (#5992). Every entry is a navigation tax being paid daily, kept
@@ -635,21 +672,54 @@ function citationsIn(file, text) {
635672
* @param {{ file: string, number: string, qualifier: string }[]} citations
636673
* @param {Set<string>} records numbers that name a real record
637674
* @param {{ number: string, why: string }[]} allowlist
675+
* @param {{ file: string, number: string, why: string }[]} [releaseOwned]
676+
* {@link RELEASE_OWNED_CITATIONS}: one number excused in one changelog file
638677
* @returns {string[]} errors
639678
*/
640-
function auditCitedNumbers(citations, records, allowlist) {
679+
function auditCitedNumbers(citations, records, allowlist, releaseOwned = []) {
641680
const errors = [];
642681
const allowed = new Map(allowlist.map((e) => [e.number, e]));
682+
const owned = new Set(releaseOwned.map((e) => `${e.file}\0${e.number}`));
683+
/** `file\0number` pairs a release-owned entry actually excused on this run. */
684+
const ownedHits = new Set();
643685
/** number → sorted files citing it, for numbers that resolve to nothing. */
644686
const danglingFiles = new Map();
645687

646688
for (const { file, number, qualifier } of citations) {
647689
if (CROSS_REPO_QUALIFIERS.has(qualifier)) continue; // another repo's registry
648690
if (records.has(number)) continue;
691+
if (owned.has(`${file}\0${number}`)) {
692+
ownedHits.add(`${file}\0${number}`);
693+
continue;
694+
}
649695
if (!danglingFiles.has(number)) danglingFiles.set(number, new Set());
650696
danglingFiles.get(number).add(file);
651697
}
652698

699+
for (const { file, number, why } of releaseOwned) {
700+
if (posix.basename(file) !== 'CHANGELOG.md') {
701+
errors.push(
702+
`${SELF_PATH}: the RELEASE_OWNED_CITATIONS entry for ADR-${number} names ${file}, which is not a ` +
703+
'`CHANGELOG.md` — the list excuses released history only.\n' +
704+
' Delete the entry and fix the citation where it is written: cite the record that exists, ' +
705+
'or spell the sibling registry (`ObjectUI ADR-NNNN`).',
706+
);
707+
} else if (records.has(number)) {
708+
errors.push(
709+
`${SELF_PATH}: the RELEASE_OWNED_CITATIONS entry for ADR-${number} in ${file} is stale — ${ADR_DIR}/ ` +
710+
`now HAS a record for that number (the entry said: ${why}).\n` +
711+
' Delete the entry, and check the released lines still mean what the new record says.',
712+
);
713+
} else if (!ownedHits.has(`${file}\0${number}`)) {
714+
errors.push(
715+
`${SELF_PATH}: the RELEASE_OWNED_CITATIONS entry for ADR-${number} in ${file} is stale — that file ` +
716+
`no longer cites ADR-${number} (the entry said: ${why}).\n` +
717+
' Delete the entry. The list is shrink-only: an excuse outliving its citation re-licences the ' +
718+
'number for whatever that file says next.',
719+
);
720+
}
721+
}
722+
653723
const nextFree = String(Math.max(0, ...[...records].map(Number)) + 1).padStart(4, '0');
654724

655725
for (const number of [...danglingFiles.keys()].sort()) {
@@ -1030,7 +1100,7 @@ let checked = 0;
10301100
// #6634 — every `ADR-NNNN` written anywhere in the tracked tree resolves to a
10311101
// record, not just the ~30 ids registered in adr-anchors/.
10321102
const citations = collectCitations();
1033-
errors.push(...auditCitedNumbers(citations, records, UNRESOLVED_ADR_CITATIONS));
1103+
errors.push(...auditCitedNumbers(citations, records, UNRESOLVED_ADR_CITATIONS, RELEASE_OWNED_CITATIONS));
10341104

10351105
// #9592 — and one layer down: the `Dk` half of every `ADR-NNNN Dk` citation on
10361106
// the ANCHORED surface must name a decision the cited record actually makes.
@@ -1492,6 +1562,62 @@ function selfTest() {
14921562
`a grandfather clause outliving its citations must fail, got:\n${joined(e)}`,
14931563
);
14941564
}
1565+
1566+
// RELEASE_OWNED_CITATIONS — one number excused in one changelog, and
1567+
// nowhere else.
1568+
const LOG = 'pkg/CHANGELOG.md';
1569+
const ownedRow = [{ file: LOG, number: '0202', why: 'synthetic' }];
1570+
1571+
{
1572+
const e = cited(rows(`shipped ${id('0202')}`, LOG), RECORDS, [], ownedRow);
1573+
assert('release-owned-changelog-citation-is-green', e.length === 0, `expected no errors, got:\n${joined(e)}`);
1574+
}
1575+
1576+
{
1577+
// The excuse is per FILE: the same number in source still reds.
1578+
const e = cited(
1579+
[...rows(`shipped ${id('0202')}`, LOG), ...rows(`see ${id('0202')}`, 'pkg/src/a.ts')],
1580+
RECORDS,
1581+
[],
1582+
ownedRow,
1583+
);
1584+
assert(
1585+
'release-owned-row-does-not-excuse-another-file',
1586+
e.length === 1 && joined(e).includes('pkg/src/a.ts') && !joined(e).includes(LOG),
1587+
`only the listed changelog may cite the number, got:\n${joined(e)}`,
1588+
);
1589+
}
1590+
1591+
{
1592+
const e = cited(rows(`see ${id('0202')}`, 'pkg/src/a.ts'), RECORDS, [], [
1593+
{ file: 'pkg/src/a.ts', number: '0202', why: 'synthetic' },
1594+
]);
1595+
assert(
1596+
'release-owned-row-naming-a-non-changelog-is-refused',
1597+
e.some((m) => m.includes('not a `CHANGELOG.md`')),
1598+
`a row may excuse released history only, got:\n${joined(e)}`,
1599+
);
1600+
}
1601+
1602+
{
1603+
const e = cited(rows(`shipped ${id('0107')}`, LOG), RECORDS, [], [
1604+
{ file: LOG, number: '0107', why: 'synthetic' },
1605+
]);
1606+
assert(
1607+
'release-owned-row-whose-number-gained-a-record-is-red',
1608+
e.length === 1 && /stale/.test(joined(e)) && joined(e).includes('now HAS a record'),
1609+
`a changelog excuse for a number that came back must fail, got:\n${joined(e)}`,
1610+
);
1611+
}
1612+
1613+
{
1614+
const e = cited(rows(`shipped ${id('0090')}`, LOG), RECORDS, [], ownedRow);
1615+
assert(
1616+
'release-owned-row-its-file-no-longer-cites-is-red',
1617+
e.length === 1 && /stale/.test(joined(e)) && joined(e).includes('no longer cites'),
1618+
`an excuse outliving its citation must fail, got:\n${joined(e)}`,
1619+
);
1620+
}
14951621
}
14961622

14971623
// ── Cited decision LETTERS resolve (#9592) ───────────────────────────────
@@ -1788,17 +1914,24 @@ function selfTest() {
17881914
`${new Set(liveCitations.map((c) => c.file)).size} file(s) — the collector is not reading the tree`,
17891915
);
17901916

1791-
const citeGreen = auditCitedNumbers(liveCitations, liveRecords, UNRESOLVED_ADR_CITATIONS);
1917+
const citeGreen = auditCitedNumbers(
1918+
liveCitations,
1919+
liveRecords,
1920+
UNRESOLVED_ADR_CITATIONS,
1921+
RELEASE_OWNED_CITATIONS,
1922+
);
17921923
assert(
17931924
'live-citations-are-green-today',
17941925
citeGreen.length === 0,
17951926
`every cited ADR number must resolve as shipped, got:\n${joined(citeGreen)}`,
17961927
);
17971928

1798-
// Ablation, predicted RED: drop the citation allowlist and each entry's
1929+
// Ablation, predicted RED: drop both citation lists and each entry's
17991930
// number must surface. Green here means the entries are dead weight.
1800-
const citeRed = auditCitedNumbers(liveCitations, liveRecords, []);
1801-
const citeNumbers = UNRESOLVED_ADR_CITATIONS.map((c) => c.number);
1931+
const citeRed = auditCitedNumbers(liveCitations, liveRecords, [], []);
1932+
const citeNumbers = [
1933+
...new Set([...UNRESOLVED_ADR_CITATIONS, ...RELEASE_OWNED_CITATIONS].map((c) => c.number)),
1934+
].sort();
18021935
assert(
18031936
'citation-ablation-without-allowlist-is-red',
18041937
citeRed.length === citeNumbers.length,

0 commit comments

Comments
 (0)