|
234 | 234 |
|
235 | 235 | import { execFileSync } from 'node:child_process'; |
236 | 236 | import { readFileSync, readdirSync, existsSync } from 'node:fs'; |
237 | | -import { join } from 'node:path'; |
| 237 | +import { join, posix } from 'node:path'; |
238 | 238 |
|
239 | 239 | import { ANCHORS_DIR, assembleAnchors, loadAnchors, shardNameFor } from './adr-anchors.mjs'; |
240 | 240 |
|
@@ -407,6 +407,43 @@ const UNRESOLVED_ADR_CITATIONS = [ |
407 | 407 | // exists so nobody re-derives the discrepancy from the removed entry's text. |
408 | 408 | ]; |
409 | 409 |
|
| 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 | + |
410 | 447 | /** |
411 | 448 | * ⛔ SHRINK-ONLY. The number collisions that already existed when this audit |
412 | 449 | * was written (#5992). Every entry is a navigation tax being paid daily, kept |
@@ -635,21 +672,54 @@ function citationsIn(file, text) { |
635 | 672 | * @param {{ file: string, number: string, qualifier: string }[]} citations |
636 | 673 | * @param {Set<string>} records numbers that name a real record |
637 | 674 | * @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 |
638 | 677 | * @returns {string[]} errors |
639 | 678 | */ |
640 | | -function auditCitedNumbers(citations, records, allowlist) { |
| 679 | +function auditCitedNumbers(citations, records, allowlist, releaseOwned = []) { |
641 | 680 | const errors = []; |
642 | 681 | 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(); |
643 | 685 | /** number → sorted files citing it, for numbers that resolve to nothing. */ |
644 | 686 | const danglingFiles = new Map(); |
645 | 687 |
|
646 | 688 | for (const { file, number, qualifier } of citations) { |
647 | 689 | if (CROSS_REPO_QUALIFIERS.has(qualifier)) continue; // another repo's registry |
648 | 690 | if (records.has(number)) continue; |
| 691 | + if (owned.has(`${file}\0${number}`)) { |
| 692 | + ownedHits.add(`${file}\0${number}`); |
| 693 | + continue; |
| 694 | + } |
649 | 695 | if (!danglingFiles.has(number)) danglingFiles.set(number, new Set()); |
650 | 696 | danglingFiles.get(number).add(file); |
651 | 697 | } |
652 | 698 |
|
| 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 | + |
653 | 723 | const nextFree = String(Math.max(0, ...[...records].map(Number)) + 1).padStart(4, '0'); |
654 | 724 |
|
655 | 725 | for (const number of [...danglingFiles.keys()].sort()) { |
@@ -1030,7 +1100,7 @@ let checked = 0; |
1030 | 1100 | // #6634 — every `ADR-NNNN` written anywhere in the tracked tree resolves to a |
1031 | 1101 | // record, not just the ~30 ids registered in adr-anchors/. |
1032 | 1102 | const citations = collectCitations(); |
1033 | | -errors.push(...auditCitedNumbers(citations, records, UNRESOLVED_ADR_CITATIONS)); |
| 1103 | +errors.push(...auditCitedNumbers(citations, records, UNRESOLVED_ADR_CITATIONS, RELEASE_OWNED_CITATIONS)); |
1034 | 1104 |
|
1035 | 1105 | // #9592 — and one layer down: the `Dk` half of every `ADR-NNNN Dk` citation on |
1036 | 1106 | // the ANCHORED surface must name a decision the cited record actually makes. |
@@ -1492,6 +1562,62 @@ function selfTest() { |
1492 | 1562 | `a grandfather clause outliving its citations must fail, got:\n${joined(e)}`, |
1493 | 1563 | ); |
1494 | 1564 | } |
| 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 | + } |
1495 | 1621 | } |
1496 | 1622 |
|
1497 | 1623 | // ── Cited decision LETTERS resolve (#9592) ─────────────────────────────── |
@@ -1788,17 +1914,24 @@ function selfTest() { |
1788 | 1914 | `${new Set(liveCitations.map((c) => c.file)).size} file(s) — the collector is not reading the tree`, |
1789 | 1915 | ); |
1790 | 1916 |
|
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 | + ); |
1792 | 1923 | assert( |
1793 | 1924 | 'live-citations-are-green-today', |
1794 | 1925 | citeGreen.length === 0, |
1795 | 1926 | `every cited ADR number must resolve as shipped, got:\n${joined(citeGreen)}`, |
1796 | 1927 | ); |
1797 | 1928 |
|
1798 | | - // Ablation, predicted RED: drop the citation allowlist and each entry's |
| 1929 | + // Ablation, predicted RED: drop both citation lists and each entry's |
1799 | 1930 | // 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(); |
1802 | 1935 | assert( |
1803 | 1936 | 'citation-ablation-without-allowlist-is-red', |
1804 | 1937 | citeRed.length === citeNumbers.length, |
|
0 commit comments