diff --git a/lib/ship-release.ts b/lib/ship-release.ts index b6e517d91..9e282a4ba 100644 --- a/lib/ship-release.ts +++ b/lib/ship-release.ts @@ -11,6 +11,8 @@ */ import * as fs from 'node:fs'; import * as path from 'node:path'; +import { normalizeChangelog } from './changelog-check'; +import { versionAtRef } from './restamp'; import { classifyPath } from './review-depth'; import { comparePath, contextPacket, gateEditedPaths, isTestCode, PACKET_SECTION_CAP, readScopedReview, touchedPaths, type PatchSides } from './ship-patch'; import { parseReceiptDocs, type ReceiptDocs } from './ship-receipt-docs'; @@ -217,7 +219,11 @@ function route(cwd: string, base: string, reviewed: string, reviewedBase: string return by; } -/** Step 16 stage 3. Test code, paths only the base moved, and --docs-requested fixes the audit's own result asked for do not stale the audit (GST-391). */ +/** + * Step 16 stage 3. Test code, paths only the base or a stamp moved, a slot restamp after the audit (the CHANGELOG's heading + * move or re-heading, the version file's version, each against the audited bytes; GST-906), and --docs-requested fixes the + * audit's own result asked for do not stale the audit (GST-391). + */ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly string[], requested: string[], resultFile: string | undefined, r: Report): boolean { const cmp = bin(cwd, 'gstack-docs-candidate', ['compare', postFile], 120_000); let stale: string[] | null = null; @@ -253,7 +259,18 @@ function docsFresh(cwd: string, base: string, postFile: string, moved: readonly if (!atAudit || (nowDiff && nowDiff.status !== 0)) { r.stop(`git could not list the paths the branch touched against ${baseRef}; documentation freshness is unknown (stage 3)`); return false; } const branchAtAudit = new Set([...atAudit, ...record.staged, ...record.unstaged, ...record.untracked]); const branchNow = new Set([...(nowDiff ? nul(nowDiff.stdout) : []), ...nul(git(cwd, ['ls-files', '-z', '--others', '--exclude-standard']).stdout)]); - const carried = { tests: stale.filter(isTestCode), base: stale.filter(p => !isTestCode(p) && (moved.includes(p) || (!!auditBase && !!nowBase && !branchAtAudit.has(p) && !branchNow.has(p)))), requested: [] as string[] }; + const changelog = shipPolicy(cwd, base)?.changelog; + const versionFile = versionAtRef(cwd, 'HEAD'); + const restamped = stale.filter(p => { + const isChangelog = p === changelog; + if (!isChangelog && !('rel' in versionFile && p === versionFile.rel)) return false; + const audited = typeof record.hashes?.[p] === 'string' ? git(cwd, ['cat-file', 'blob', record.hashes[p]]) : null; + if (audited?.status !== 0) return false; + let now: string; + try { now = fs.readFileSync(path.join(cwd, p), 'utf8'); } catch { return false; } + return isChangelog ? normalizeChangelog(audited.stdout) === normalizeChangelog(now) : !!parseVersion(audited.stdout.trim()) && !!parseVersion(now.trim()); + }); + const carried = { tests: stale.filter(isTestCode), base: stale.filter(p => !isTestCode(p) && (moved.includes(p) || restamped.includes(p) || (!!auditBase && !!nowBase && !branchAtAudit.has(p) && !branchNow.has(p)))), requested: [] as string[] }; let audit: any = null; try { audit = resultFile ? JSON.parse(fs.readFileSync(resultFile, 'utf8')) : null; } catch { audit = null; } for (const p of requested.filter(q => stale!.includes(q) && !carried.tests.includes(q) && !carried.base.includes(q))) { diff --git a/test/ship-rereview-triggers.test.ts b/test/ship-rereview-triggers.test.ts index f06b65074..dd82cb6fb 100644 --- a/test/ship-rereview-triggers.test.ts +++ b/test/ship-rereview-triggers.test.ts @@ -525,3 +525,32 @@ describe('preflight carry route for an adjacent base edit (GST-442)', () => { }); }); +describe('a CHANGELOG re-heading after the docs audit (GST-906, GBRA-258, gbrain #8372)', () => { + // Value: protects=a slot restamp after the Step 14.5 snapshot that only re-heads the branch's CHANGELOG entry + // ([Unreleased], or its old version after a lost slot, moved to `## [] - `, with the audited VERSION moved + // in the second case) keeps the audit fresh, while an entry edit beside the re-heading, or audited bytes git does not + // hold, stays stale; fails_when=finish stops with DOCS: stale (CHANGELOG.md) or (VERSION) on a pure restamp (recovery + // then needs a third audit or a named risk) or waves an entry edit through; seam=lib/ship-release.ts docsFresh; + // no_claim=the restamp writer + test('a re-heading alone keeps the audit fresh; an entry edit or unheld audited bytes stays stale', () => { + const policy = JSON.stringify({ bump: 'patch', queue_mode: 'stamp-at-merge', changelog: 'CHANGELOG.md', stamp_files: ['VERSION', 'package.json', 'CHANGELOG.md'] }); + const log = (heading: string, entry = '- b ships') => `# Changelog\n\n${heading}\n\n${entry}\n\n## [1.0.0.0] - 2026-10-30\n\n- base entry\n`; + const cases = [ + ['[Unreleased] re-headed', '1.0.0.0', log('## [Unreleased]'), '1.0.1.0', log('## [1.0.1.0] - 2026-11-01'), true, 'fresh'], + ['old version re-headed after a lost slot', '1.0.1.0', log('## [1.0.1.0] - 2026-11-01'), '1.0.2.0', log('## [1.0.2.0] - 2026-11-02'), true, 'fresh'], + ['re-heading plus an entry edit', '1.0.0.0', log('## [Unreleased]'), '1.0.1.0', log('## [1.0.1.0] - 2026-11-01', '- b ships fast'), true, 'stale'], + ['audited bytes never committed or staged', '1.0.0.0', log('## [Unreleased]'), '1.0.1.0', log('## [1.0.1.0] - 2026-11-01'), false, 'stale'], + ] as const; + for (const [name, audited, auditedLog, stamped, stampedLog, committed, verdict] of cases) { + const f = fx({ '.gstack/ship-policy.json': policy, 'CHANGELOG.md': '# Changelog\n\n## [1.0.0.0] - 2026-10-30\n\n- base entry\n' }); + const reviewed = wtree(f); + f.write({ VERSION: `${audited}\n`, 'CHANGELOG.md': auditedLog }); + if (committed) f.commit('Steps 12-13: version and CHANGELOG'); + const post = snapshot(f); + f.write({ VERSION: `${stamped}\n`, 'CHANGELOG.md': stampedLog }); f.commit('slot restamp'); + const r = finish(f, reviewed, post, ['--reviewed-base', mergeBase(f)]); + if (verdict === 'fresh') expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 0, expect.stringContaining('DOCS: fresh against the Step 14.5 post-audit snapshot')]); + else expect([name, r.status, lineOf(r.stdout, 'DOCS')]).toEqual([name, 3, 'DOCS: stale (CHANGELOG.md)']); + } + }); +});