diff --git a/.github/workflows/plain-title.yml b/.github/workflows/plain-title.yml index 8736d39c0..6487a52fe 100644 --- a/.github/workflows/plain-title.yml +++ b/.github/workflows/plain-title.yml @@ -3,7 +3,8 @@ name: Plain title # Checks that a PR's title reads in everyday words (R76, docs/ship-policy.md#plain-titles). # The title is refused in the front: tracker codes, project-only words and a # type(scope): prefix. One trailing group of references like (ABC-123) or (#4122) -# is fine. The branch name, the PR opening and the commit subjects only warn. +# is fine. The body is refused when it breaks the plain shape (docs/writing-prs.md); +# the branch name and the commit subjects only warn. # PRs created before the policy's since date are exempt. # # WHY pull_request_target: it runs the base repository's copy of this workflow, @@ -77,7 +78,26 @@ jobs: bun --no-env-file --config=/dev/null bin/gstack-plain-title check \ --title-file "$RUNNER_TEMP/pr-title.txt" --created-at "$PR_CREATED_AT" --mode refuse - - name: Check the branch name, opening and commit subjects (warnings only) + # The body: its opening, at most three lines before the first fold, and no + # listed word above the Agent notes fold (docs/writing-prs.md). A PR created + # before the policy's body_since date, or from a generated branch the policy + # exempts (release notes repeat CHANGELOG text), only gets warnings. Only a + # branch in this repository counts as exempt: a fork names its own branches. + - name: Check the body + if: ${{ !cancelled() }} + env: + PR_BRANCH: ${{ github.event.pull_request.head.ref }} + PR_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} + PR_CREATED_AT: ${{ github.event.pull_request.created_at }} + run: | + set -euo pipefail + exempt_branch="" + if [ "$PR_HEAD_REPO" = "$GITHUB_REPOSITORY" ]; then exempt_branch="$PR_BRANCH"; fi + bun --no-env-file --config=/dev/null bin/gstack-plain-title check \ + --body-file "$RUNNER_TEMP/pr-body.txt" --head-branch "$exempt_branch" \ + --created-at "$PR_CREATED_AT" --mode refuse + + - name: Check the branch name and commit subjects (warnings only) if: ${{ !cancelled() }} env: PR_BRANCH: ${{ github.event.pull_request.head.ref }} @@ -85,5 +105,5 @@ jobs: run: | set -euo pipefail bun --no-env-file --config=/dev/null bin/gstack-plain-title check \ - --branch "$PR_BRANCH" --body-file "$RUNNER_TEMP/pr-body.txt" \ + --branch "$PR_BRANCH" \ --commits-file "$RUNNER_TEMP/pr-commits.txt" --created-at "$PR_CREATED_AT" --mode warn diff --git a/.gstack/plain-titles.json b/.gstack/plain-titles.json index 05a4746b1..71d979949 100644 --- a/.gstack/plain-titles.json +++ b/.gstack/plain-titles.json @@ -23,7 +23,12 @@ "no-stop", "GStack Minder", "Capy Workflow Improver", - "Captain" + "Captain", + "Captains", + "crew", + "crews", + "lander", + "landers" ], "allow": [ { @@ -32,9 +37,11 @@ } ], "since": "2026-11-08", + "body_since": "2026-11-18", "exempt_branch_prefixes": [ "release/", "wave/", - "gstack-land-repair/" + "gstack-land-repair/", + "dependabot/" ] } diff --git a/README.md b/README.md index 11ebe35ed..9935ca7cd 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/qa-only` | **QA Reporter** | Explore and report with replayable evidence. Suggest regression cases without changing product code or tests. | | `/pair-agent` | **Multi-Agent Coordinator** | Share gstack's own browser with any AI agent. One command, one paste, connected. Works with OpenClaw, Hermes, Codex, Cursor, or anything that can curl. Each agent gets its own tab. Auto-launches headed mode so you watch everything. Auto-starts ngrok tunnel for remote agents. Scoped tokens, tab isolation, rate limiting, activity attribution. (Runs on the bundled browser — the fallback engine; agents driving Aside just open their own tabs.) | | `/cso` | **Chief Security Officer** | Security audit with an application model, supported findings, independent challenge, and explicit coverage. Static assessment remains available without catalog profiles. With matching qualified profiles, comprehensive mode adds contained runtime/scanner execution and reviewable repair candidates for Node/Bun, Python, and Rails. Qualified runtime and scanner images are published for linux/amd64 and linux/arm64. Without Docker, audits run static assessment only. Runtime-tested bundles authenticate separate external assertions. Project-test completion remains `self_reported` because target code controls the test process; `tested` is reserved for a future target-independent completion witness. | -| `/ship` | **Release Engineer** | Sync main, run tests, explore changed behavior, audit coverage, gate integrity and docs, then verify, push and open a PR. | +| `/ship` | **Release Engineer** | Sync main, run tests, explore changed behavior, audit coverage, gate integrity and docs, then verify, push and open a PR whose body opens with three plain lines ([how gstack writes PRs and commits](docs/writing-prs.md)). | | `/land-and-deploy` | **Release Engineer** | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." | | `/modernize` | **Stale-PR Maintainer** | Bring an aging PR onto its current base and say whether it should still exist: MODERNIZE (rebase, `git range-diff` proof, push with a lease pinned to the observed head), REWORK (the problem stands, the diff does not) or CLOSE (recommended, never done without permission). Reads the base's moved range for conflicts in meaning, not only in text. | | `/canary` | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures. | diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh index e65205dc0..2b5bb7d32 100644 --- a/bin/gstack-doctor-components.sh +++ b/bin/gstack-doctor-components.sh @@ -440,6 +440,7 @@ gstack_result_anchor() { PLAIN_TITLE_REFUSED) printf '%s' 'plain-title-refused' ;; PLAIN_BRANCH_REFUSED) printf '%s' 'plain-branch-refused' ;; PLAIN_OPENING_REFUSED) printf '%s' 'plain-opening-refused' ;; + PLAIN_BODY_REFUSED) printf '%s' 'plain-body-refused' ;; PLAIN_CHANGELOG_REFUSED) printf '%s' 'plain-changelog-refused' ;; PLAIN_COMMIT_REFUSED) printf '%s' 'plain-commit-refused' ;; PLAIN_POLICY_INVALID) printf '%s' 'plain-policy-invalid' ;; diff --git a/bin/gstack-plain-title b/bin/gstack-plain-title index bdbe0dbfe..655c4d4a5 100755 --- a/bin/gstack-plain-title +++ b/bin/gstack-plain-title @@ -10,15 +10,20 @@ import { spawnSync } from 'node:child_process'; import * as fs from 'node:fs'; import * as path from 'node:path'; +import { bodyFindingLine, checkBodyShape, foldSections, type BodyFinding } from '../lib/pr-body-shape'; import { PLAIN_TITLE_POLICY_PATH, checkBranch, checkChangelogEntry, checkCommitSubject, checkOpening, checkTitle, loadPlainTitlePolicy, type PlainFinding, type PlainTitlePolicy } from '../lib/plain-title'; import { resultLine } from '../lib/result-codes'; const HELP = `gstack-plain-title — check that titles, branch names, PR openings and changelog entries read in plain words (docs/ship-policy.md#plain-titles) - check [--title | --title-file ] [--branch ] [--body-file ] [--changelog ] + check [--title | --title-file ] [--branch ] [--body-file [--head-branch ]] [--changelog ] [--commits-file ] [--created-at ] [--mode refuse|warn] [--json] check each input against ${PLAIN_TITLE_POLICY_PATH}; --commits-file holds one commit - subject per line and only ever warns; a PR created before the policy's since date is exempt + subject per line and only ever warns; a PR created before the policy's since date is exempt; + --body-file also checks the body's shape once folded (docs/writing-prs.md: at most 3 lines + and 600 characters before the first fold, listed words below the Agent notes fold), printed as + PLAIN_BODY: lines, which only warn for a PR created before the policy's body_since date or + whose --head-branch starts with one of its exempt_branch_prefixes (a generated release PR) validate check ${PLAIN_TITLE_POLICY_PATH} against its schema init [--force] write an example ${PLAIN_TITLE_POLICY_PATH} @@ -34,7 +39,7 @@ const EXAMPLE = { exempt_branch_prefixes: ['release/'], }; -const VALUE_FLAGS = ['--title', '--title-file', '--branch', '--body-file', '--changelog', '--commits-file', '--created-at', '--mode']; +const VALUE_FLAGS = ['--head-branch', '--title', '--title-file', '--branch', '--body-file', '--changelog', '--commits-file', '--created-at', '--mode']; function usage(message: string): number { process.stderr.write(`gstack-plain-title: ${message}\n${HELP}\n`); @@ -80,7 +85,7 @@ function check(args: string[]): number { const policy = loadPolicy(repoRoot(), 'gstack-plain-title check'); if (policy === 'invalid') return 3; - const done = (status: string, findings: Array = []) => { + const done = (status: string, findings: Array<(PlainFinding | BodyFinding) & { severity: string }> = []) => { const refused = findings.filter(f => f.severity === 'refused').length; process.stdout.write(json ? JSON.stringify({ status, refused, warned: findings.length - refused, findings }) + '\n' : `PLAIN_TITLE: ${status}\n`); return refused ? 1 : 0; @@ -90,16 +95,22 @@ function check(args: string[]): number { const title = opts['--title'] ?? read['--title-file']?.replace(/\r?\n+$/, ''); const severity = mode === 'warn' ? 'warned' : 'refused'; - const findings = [ + const older = (createdAt !== undefined && Date.parse(createdAt) < Date.parse(policy.body_since)) || policy.exempt_branch_prefixes.some(p => (opts['--head-branch'] ?? '').startsWith(p)); + const findings: Array<(PlainFinding | BodyFinding) & { severity: string }> = [ ...(title !== undefined ? checkTitle(title, policy) : []), ...(opts['--branch'] !== undefined ? checkBranch(opts['--branch'], policy) : []), - ...(read['--body-file'] !== undefined ? checkOpening(read['--body-file'], policy) : []), ...(read['--changelog'] !== undefined ? checkChangelogEntry(read['--changelog'], policy) : []), ].map(f => ({ ...f, severity })); + if (read['--body-file'] !== undefined) findings.push(...checkOpening(read['--body-file'], policy).map(f => ({ ...f, severity: older ? 'warned' : severity }))); for (const line of (read['--commits-file'] ?? '').split(/\r?\n/)) { if (line.trim()) findings.push(...checkCommitSubject(line, policy).map(f => ({ ...f, severity: 'warned' }))); } if (!json) for (const f of findings) process.stdout.write(`PLAIN_TITLE: ${f.code} ${f.kind} "${clean(f.match)}" — ${f.hint}${f.severity === 'warned' ? ' (warning only)' : ''}\n`); + if (read['--body-file'] !== undefined) { + const shape = checkBodyShape(foldSections(read['--body-file']), policy.terms); + if (!json) for (const f of shape) process.stdout.write(bodyFindingLine(f, older || severity === 'warned') + '\n'); + findings.push(...shape.map(f => ({ ...f, severity: older ? 'warned' : severity }))); + } const refused = findings.filter(f => f.severity === 'refused').length; const warned = findings.length - refused; return done(refused ? `refused=${refused}${warned ? ` warned=${warned}` : ''}` : warned ? `warned=${warned}` : 'ok', findings); diff --git a/bin/gstack-ship-policy b/bin/gstack-ship-policy index 41d56846f..aa39e97dd 100755 --- a/bin/gstack-ship-policy +++ b/bin/gstack-ship-policy @@ -122,21 +122,25 @@ function main(argv: string[]): number { const result: Record = { history: policy, branch: branch || null, plan }; let verdict: string; let code = EXIT.ok; - if (policy !== 'merge-only') verdict = `HISTORY: squash-ok (no check; policy history=${policy}; plan=${plan})`; - else if (plan !== 'merge') { + if (policy === 'squash-ok') verdict = `HISTORY: squash-ok (no check; policy history=${policy}; plan=${plan})`; + else if (policy === 'no-rewrite' && plan === 'rebase') { + verdict = 'HISTORY: refused (plan=rebase rewrites the branch; policy history=no-rewrite keeps every pushed commit reachable until land squashes the PR into one commit) — fix: merge origin/ into the branch instead (HISTORY_POLICY_VIOLATION)'; + code = EXIT.refused; + } + else if (policy === 'merge-only' && plan !== 'merge') { verdict = `HISTORY: refused (plan=${plan} rewrites history; policy history=merge-only keeps every reviewed commit reachable so gate evidence and preregistration ancestry stay bound to the shas that were gated) — fix: integrate with a merge commit, or set history: squash-ok in .gstack/ship-policy.json on the base branch (HISTORY_POLICY_VIOLATION)`; code = EXIT.refused; } - else if (!branch) { verdict = 'HISTORY: merge-only (detached HEAD; no pushed branch to compare)'; } + else if (!branch) { verdict = `HISTORY: ${policy} (detached HEAD; no pushed branch to compare)`; } else { const remote = spawnSync('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`], { cwd: root, encoding: 'utf8', timeout: 15_000 }); - if (remote.status !== 0) verdict = `HISTORY: merge-only (origin/${branch} not pushed yet; nothing to rewrite)`; + if (remote.status !== 0) verdict = `HISTORY: ${policy} (origin/${branch} not pushed yet; nothing to rewrite)`; else { const anc = spawnSync('git', ['merge-base', '--is-ancestor', remote.stdout.trim(), 'HEAD'], { cwd: root, timeout: 15_000 }); result.remote = remote.stdout.trim(); - if (anc.status === 0) verdict = `HISTORY: ok (merge-only; origin/${branch} is an ancestor of HEAD)`; + if (anc.status === 0) verdict = `HISTORY: ok (${policy}; origin/${branch} is an ancestor of HEAD)`; else { - verdict = `HISTORY: rewritten (origin/${branch} ${remote.stdout.trim().slice(0, 12)} is not an ancestor of HEAD) — fix: ${'merge origin/ instead of rebasing or squashing; never force-push under history: merge-only'} (HISTORY_POLICY_VIOLATION)`; + verdict = `HISTORY: rewritten (origin/${branch} ${remote.stdout.trim().slice(0, 12)} is not an ancestor of HEAD) — fix: ${`merge origin/ instead of rebasing or squashing; never force-push under history: ${policy}`} (HISTORY_POLICY_VIOLATION)`; code = EXIT.fail; } } diff --git a/bin/gstack-ship-queue b/bin/gstack-ship-queue index 3da9e6ce9..b8bcd6180 100755 --- a/bin/gstack-ship-queue +++ b/bin/gstack-ship-queue @@ -32,6 +32,7 @@ * (loaded only on the train paths). */ import { spawnSync } from 'node:child_process'; +import * as fs from 'node:fs'; import * as path from 'node:path'; import { ghSpawnSync } from '../lib/gh-poll'; import { EXIT, exitTableHelp, formatResult } from '../lib/headless-artifacts'; @@ -66,7 +67,7 @@ const HELP = `gstack-ship-queue — the shared merge queue's protocol steps (doc verify --pr --screen (train policy) the PR head's screen verdict read from its run (SCREEN_VERDICT) verify --post-merge [--timeout ] wait for every check run at a merged commit to settle: POST_MERGE: green|red|pending and one CHECK: line per workflow; resumable, default timeout 2700 s - land --pr --pin [--accept-gate-disposition ]... [--repair] [--dry-run] [--allow-repo-commands] [--break-lock] + land --pr --pin [--accept-gate-disposition ]... [--repair] [--dry-run] [--allow-repo-commands] [--break-lock] [--body-file ] merge: direct: merge the PR at its own green head (receipt and READY at the pin, no stamp files, checks green, mergeable clean), verify the tree, write a land note; a stale base runs land.merged_checks, repo commands, only with --allow-repo-commands (never --dry-run); @@ -74,9 +75,12 @@ const HELP = `gstack-ship-queue — the shared merge queue's protocol steps (doc --repair: while frozen, land the one repair PR the freeze admits (recorded under the lock); an owner gate disposition the approval store applies at the pin merges only when the lander passes --accept-gate-disposition (docs/ship-policy.md#gate-dispositions) - land --pr [--dry-run] [--no-wait] [--timeout ] [--break-lock [--break-train-lock]] [--allow-repo-commands] + land --pr [--dry-run] [--no-wait] [--timeout ] [--break-lock [--break-train-lock]] [--allow-repo-commands] [--body-file ] the merge step: lock, merge the base, stamp (fragments folded), push the stamp commit, wait for its checks, squash with --match-head-commit, confirm the base tree; resumable + Both forms merge as one commit titled " (#n)" whose body is the PR body's opening + lines (at most 3) plus the branch's trailers; --body-file replaces the opening lines; METHOD, + SUBJECT and BODY lines show it first (docs/writing-prs.md#the-commit-on-main) land --pr --repair after QUEUE_LAND_DRIFT: open the PR that gives the merge outside land its own release; /ship and land it, which releases the lock land --census what land would do with every open PR (read-only) @@ -90,6 +94,12 @@ const HELP = `gstack-ship-queue — the shared merge queue's protocol steps (doc refs/notes/gstack-land lock), ready under changelog_fragments (its READY receipt note) and merge trains. ${exitTableHelp()}`; +/** land --body-file: the plain lines that replace the PR body's opening in the merge commit; land scans them like the rest of the message. */ +function landBody(file: string | undefined): { text?: string } | { error: string } { + if (file === undefined) return {}; + try { return { text: fs.readFileSync(path.resolve(file), 'utf8') }; } catch (e) { return { error: `cannot read --body-file ${file}: ${(e as NodeJS.ErrnoException).code ?? String(e)}` }; } +} + function flag(args: string[], name: string): string | undefined { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; @@ -173,10 +183,19 @@ function gateAhead(ctx: QueueContext, args: string[]): number { }); } +/** Which land form this checkout's base policy takes, so a lander never guesses between the two. */ +function landFormLine(repoRoot: string): string { + const loaded = loadBasePolicy({ repoRoot, base: resolveBaseBranch(repoRoot), gh: () => ({ ok: false, out: '', err: 'no gh in --help' }) }); + if ('message' in loaded) return ''; + return loaded.policy.merge === 'direct' + ? `\nThis repository (merge: direct): land each READY PR with gstack-ship-queue land --pr --pin .\n` + : `\nThis repository (merge: ${loaded.policy.merge}): land with gstack-ship-queue land --pr ${loaded.policy.train ? ', or train land for a built train' : ''}; --pin is the merge: direct form.\n`; +} + async function main(argv: string[]): Promise { const [cmd, ...args] = argv; - if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { process.stdout.write(HELP + '\n'); return cmd ? EXIT.ok : EXIT.usage; } const probe = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 15_000 }); + if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { process.stdout.write(HELP + '\n' + (probe.status === 0 ? landFormLine(probe.stdout.trim()) : '')); return cmd ? EXIT.ok : EXIT.usage; } if (probe.status !== 0) return usage('not inside a git repository'); const repoRoot = probe.stdout.trim(); const gh = (a: string[]) => { const r = ghSpawnSync(a, { cwd: repoRoot, encoding: 'utf8', timeout: 60_000 }); return { ok: r.status === 0, out: r.stdout ?? '', err: r.stderr ?? (r.error ? String(r.error.message) : '') }; }; @@ -196,15 +215,17 @@ async function main(argv: string[]): Promise { const l = await import('../lib/ship-queue-land'); if (args.includes('--census')) return finish('land', l.census(ctx)); if (!pr || !/^\d+$/.test(pr)) return usage('land needs --pr (or --census)'); + const body = landBody(flag(args, '--body-file')); + if ('error' in body) return usage(body.error); if (args.includes('--pin')) { const pin = flag(args, '--pin') ?? ''; if (!/^[0-9a-f]{40,64}$/.test(pin)) return usage('--pin needs the full head sha the READY names'); const accept = acceptedIds(args); if (accept.bad !== undefined) return usage(`--accept-gate-disposition needs an approval id (a-<12 hex>), not ${JSON.stringify(accept.bad)}`); - return finish('land', (await import('../lib/ship-queue-land-direct')).landDirect(ctx, { pr, pin, acceptGateDispositions: accept.ids, dryRun: args.includes('--dry-run'), allowRepoCommands: args.includes('--allow-repo-commands'), breakLock: args.includes('--break-lock'), repair: args.includes('--repair') })); + return finish('land', (await import('../lib/ship-queue-land-direct')).landDirect(ctx, { pr, pin, body: body.text, acceptGateDispositions: accept.ids, dryRun: args.includes('--dry-run'), allowRepoCommands: args.includes('--allow-repo-commands'), breakLock: args.includes('--break-lock'), repair: args.includes('--repair') })); } const timeout = flag(args, '--timeout'); - return finish('land', l.land(ctx, { pr, repair: args.includes('--repair'), dryRun: args.includes('--dry-run'), noWait: args.includes('--no-wait'), breakLock: args.includes('--break-lock'), breakTrainLock: args.includes('--break-train-lock'), allowRepoCommands: args.includes('--allow-repo-commands'), waitTimeoutMin: timeout && /^\d+$/.test(timeout) ? Number(timeout) : undefined })); + return finish('land', l.land(ctx, { pr, body: body.text, repair: args.includes('--repair'), dryRun: args.includes('--dry-run'), noWait: args.includes('--no-wait'), breakLock: args.includes('--break-lock'), breakTrainLock: args.includes('--break-train-lock'), allowRepoCommands: args.includes('--allow-repo-commands'), waitTimeoutMin: timeout && /^\d+$/.test(timeout) ? Number(timeout) : undefined })); } if (!pr || !/^\d+$/.test(pr)) return usage(`${cmd} needs --pr `); const gateExit = flag(args, '--gate-exit'); diff --git a/changelog.d/plain-pr-bodies.md b/changelog.d/plain-pr-bodies.md new file mode 100644 index 000000000..a73331f9f --- /dev/null +++ b/changelog.d/plain-pr-bodies.md @@ -0,0 +1,4 @@ +--- +bump: minor +--- +- **Pull requests from /ship now open with at most three plain lines, and every merge lands as one commit titled with the PR title.** /ship writes `## ` sections and `gstack-post` folds each into a collapsed section when it posts, so a reader sees what changed, why, and what they have to do, with the rest one click away and the Agent notes section last. `gstack-post fold --body-file F` shows the folded body without posting it. In a repository with `.gstack/plain-titles.json`, `gstack-post` and the Plain title check refuse a body that shows more than three lines (or 600 characters) before its first fold, or uses a listed in-house word above the Agent notes section (`PLAIN_BODY_REFUSED`); gstack now ships a default word list (outside voice, pregate, receipt, carry, stamp, train, lane, soak and more), which a policy extends or replaces with `replace_default_terms`, and `body_since` keeps PRs opened before that date to warnings. Every `gstack-ship-queue land` form now passes the subject ` (#n)` and a body of the PR's opening lines plus the branch's `Co-authored-by:` and other trailers, so GitHub no longer writes its commit list; `--dry-run` prints it and `--body-file` replaces the opening. Release PRs list one plain line per change with its PR. Two new policy settings: `history: no-rewrite` (squash landings, never a rebased or force-pushed branch) and `land.merge_commit_paths` (keep a merge commit for PRs that change those paths, such as eval results). See docs/writing-prs.md. diff --git a/crew/lib/ship-queue-train-land.ts b/crew/lib/ship-queue-train-land.ts index 94d2a99ed..f5dc11afa 100644 --- a/crew/lib/ship-queue-train-land.ts +++ b/crew/lib/ship-queue-train-land.ts @@ -35,6 +35,7 @@ import { verifyPostMerge } from './ship-queue-post-merge'; import { bindTrainReceipt } from './ship-queue-train-gate'; import { checkRun, prInfo, type PrInfo } from './ship-queue-train-github'; import { landPlan } from '../../lib/plan-record'; +import { landMessage, mergeArgs, messageLines } from '../../lib/squash-message'; import { TERMINAL_STATES, activeFreeze, attemptsOf, freezeLockCleared, loadReady, nowIso, trainFile, type LandingRecord, type TrainRecord } from './ship-queue-train-record'; import { fetchBase, fetchTrainBranch, findTrain, frozenLines, nextFor, outFailed, outPending, outRefused, save, trainEnv, type TrainEnv, type TrainOut } from './ship-queue-train'; import { confirmMerged, stopped } from './ship-queue-train-verify'; @@ -133,7 +134,7 @@ function chooseMode(ctx: QueueContext, s: Slot, mainSha: string, conditional: bo return { mode: 'update', why: `the pin's own checks are not green (${ci.line}${missing.length ? `; missing ${missing.join(', ')}` : ''}); they ran against an older base` }; } -/** Merge with the policy's method at an exact head, the PR title as the commit subject (a rebase has none), then confirm main's tree is the slot's prefix. */ +/** Merge with the policy's method at an exact head and lib/squash-message.ts's subject and body (a rebase has none; a land.merge_commit_paths match turns a squash into a merge), then confirm main's tree is the slot's prefix. */ async function mergeAt(ctx: QueueContext, s: Slot, head: string, base: string): Promise<TrainOut> { const pr = s.t.slots[s.i]!.pr; const method = s.env.train.land?.merge_method ?? 'squash'; @@ -143,13 +144,23 @@ async function mergeAt(ctx: QueueContext, s: Slot, head: string, base: string): const target = prInfo(ctx, pr); if ('error' in target) return outPending({ code: 'QUEUE_PROOF_MISSING', message: target.error }, s.lines, s.rerun, s.run); if (target.baseRefName && target.baseRefName !== ctx.base) return retargeted(s, target.baseRefName, ctx.base); + let args = ['pr', 'merge', pr, '--rebase', '--match-head-commit', head]; + if (method !== 'rebase') { + const viewed = ctx.gh(['pr', 'view', pr, '--json', 'title,body']); + if (!viewed.ok) return outPending({ code: 'QUEUE_PROOF_MISSING', message: `cannot read #${pr}'s title and body: ${(viewed.err ?? viewed.out).trim().slice(0, 200)}` }, s.lines, s.rerun, s.run); + let view: { title?: unknown; body?: unknown } = {}; + try { view = viewed.ok ? JSON.parse(viewed.out) : {}; } catch {} + const root = ctx.repoRoot; + const msg = landMessage(root, { pr, title: String(view.title ?? ''), prBody: String(view.body ?? ''), mergeBase: git(root, ['merge-base', base, head]).out, pin: head, tip: base, policy: s.env.policy.policy }); + if ('error' in msg) return outFailed({ code: 'QUEUE_NOT_READY', message: msg.error }, s.lines, s.rerun, s.run); + const m = method === 'merge' ? { ...msg, method: 'merge' as const, why: 'train.land.merge_method: merge' } : msg; + s.lines.push(...messageLines(m)); + args = mergeArgs(pr, head, m); + } const moved = lockPhase(s, 'merging'); if (moved) return outFailed(moved, s.lines, s.rerun, s.run); s.lock.effect = true; - const viewed = method === 'rebase' ? null : ctx.gh(['pr', 'view', pr, '--json', 'title']); - let title = ''; - try { title = viewed?.ok ? String(JSON.parse(viewed.out).title ?? '').trim() : ''; } catch {} - const m = ctx.gh(['pr', 'merge', pr, `--${method}`, '--match-head-commit', head, ...(title ? ['--subject', `${title} (#${pr})`] : [])]); + const m = ctx.gh(args); if (!m.ok) return outFailed({ code: 'QUEUE_NOT_READY', message: `gh pr merge refused: ${(m.err ?? m.out).trim().slice(0, 200)}` }, s.lines, s.rerun, s.run); main = mainNow(ctx, s.env); if ('error' in main) return outPending({ code: 'QUEUE_PROOF_MISSING', message: `merged; ${main.error}` }, s.lines, s.rerun, s.run); diff --git a/crew/test/ship-queue-train-generic.test.ts b/crew/test/ship-queue-train-generic.test.ts index bab6e2180..596b78483 100644 --- a/crew/test/ship-queue-train-generic.test.ts +++ b/crew/test/ship-queue-train-generic.test.ts @@ -248,7 +248,7 @@ describe('generic trains end to end (fixture repos)', () => { expect(origin('rev-parse', 'main^{tree}')).toBe(t.gated[2].tree); expect(trainJson(fx, nonce)).toMatchObject({ state: 'merged', landing: { 1: { mode: 'direct', update: null }, 2: { mode: 'direct' } } }); const merges = fx.read().log.filter(l => l.cmd === 'pr merge').map(l => (l.args as string[]).join(' ')); - expect(merges[0]).toMatch(/^pr merge 1 --squash --match-head-commit [0-9a-f]{40} --subject Change from #1 \(#1\)$/); + expect(merges[0]).toMatch(/^pr merge 1 --squash --match-head-commit [0-9a-f]{40} --subject Change from #1 \(#1\) --body $/); }, 300_000); test('strict protection forces update; a rebase method refuses it; a fork head is refused', () => { diff --git a/crew/test/ship-queue-train-land.test.ts b/crew/test/ship-queue-train-land.test.ts index fcb73231d..46f737a34 100644 --- a/crew/test/ship-queue-train-land.test.ts +++ b/crew/test/ship-queue-train-land.test.ts @@ -62,7 +62,7 @@ describe('stamped trains: build and land', () => { expect(trainJson(fx, nonce)).toMatchObject({ state: 'merged' }); expect(fx.read().prs['2']).toMatchObject({ state: 'MERGED' }); expect((fx.read() as any).labels).toEqual({ 1: 'evals-no-debounce', 2: 'evals-no-debounce' }); - expect((fx.read() as any).mergeArgs['1']).toEqual(['--squash', '--match-head-commit', stamp, '--subject', 'Change from #1 (#1)']); + expect((fx.read() as any).mergeArgs['1']).toEqual(['--squash', '--match-head-commit', stamp, '--subject', 'Change from #1 (#1)', '--body', '']); void h2; }, 300_000); diff --git a/docs/ship-policy.md b/docs/ship-policy.md index 84e4a6834..c2692252d 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -60,7 +60,7 @@ branch that changes the policy. | `stamp_paths` | globs | `[]` | Where exact `(was X)`, `since: X` and `vX` mentions of the branch's tentative version (quoted or bare: `since: 'X'` counts) are rewritten on a restamp. | | `changelog` | path or `null` | `CHANGELOG.md` | Re-headed on a restamp: the PR's `## [Unreleased]` (or old-version) section moves to the top as `## [<version>] - <date>`. | | `mirror` | relative path or `null` | `null` | A paired checkout to restamp identically (tier 2: validated and confined today, not yet run). | -| `history` | `merge-only` \| `squash-ok` | `squash-ok` | `merge-only` makes `/ship` refuse a squash or rebase plan; `gstack-ship-policy check-history` reports a rewritten branch (`HISTORY_POLICY_VIOLATION`). | +| `history` | `merge-only` \| `squash-ok` \| `no-rewrite` | `squash-ok` | `merge-only` makes `/ship` refuse a squash or rebase plan and land keep a merge commit; `gstack-ship-policy check-history` reports a rewritten branch (`HISTORY_POLICY_VIOLATION`). `no-rewrite` refuses a rebase or force-push the same way but lands each PR as one squashed commit ([writing-prs.md](writing-prs.md#the-commit-on-main)); it needs `min_gstack_version` at its own release (`HISTORY_NO_REWRITE_KEY_VERSION`). | | `preregistration_shas` | commit ids | `[]` | Each must be an ancestor of HEAD before push: `gstack-evidence ancestor --from-policy`; the ship receipt records the result. | | `stamp_sensitive_gates` | evidence labels | `[]` | Gates that read VERSION or generated bytes (gstack's own `tests` lane does, through the agents-digest freshness test). The tree receipt never marks them reusable. | | `pr_count` | `{ default_pr_count, split_requires_owner }` | `{1, true}` | The PR-count row in plan reviews. | @@ -80,7 +80,7 @@ branch that changes the policy. | `docs` | `{ caps: [{ path, max_bytes }] }` or `null` | `null` | Documentation files with a byte cap. `/ship` Step 14.5 runs `gstack-ship-receipt docs-caps --base <base>` (the caps come from `origin/<base>`'s policy, never the branch's copy; `--policy <file>` is for a repository bootstrapping its policy) before the verification gate and prints one `DOCS_CAP: <path> <bytes>/<max> ok\|over` line per cap; any `over` (an absent file counts) exits 1 and blocks the ship until the file is trimmed or the cap raised on the base branch (`DOCS_AUDIT_BLOCKED`). At most 64 caps, each path contained. See [the ship receipt](#ship-receipt). Needs `min_gstack_version`. | | `train` | `{ gate_workflow, free_workflow, full_gate_check, record_artifact, max_size, fill_hours, screen_selection, trial_reservation_usd, land? }`, `{ gates, land, max_size, fill_hours }` or `null` | `null` | Turns on [merge trains](#run-a-merge-train), read from the base revision only. Every field is required and an unknown field is `POLICY_INVALID`: `max_size` 1 to 6, `fill_hours` above 0 and at most 24, `screen_selection` `gstack-paid` \| `none`, `trial_reservation_usd` above 0 and at most 100. A block with `gates` ([any repository](#train-gates)) takes `max_size` 1 to 5 and needs `min_gstack_version` at least `TRAIN_GATES_KEY_VERSION`. `null` keeps the per-PR queue exactly as it is. Needs `min_gstack_version`. | | `merge` | `train` \| `direct` | `train` | `direct` lands each READY PR at its own green head with [`land --pr <n> --pin <sha>`](#land-direct): no train and no stamp commit, and `train build` refuses. A PR then leaves VERSION, the `package.json` version and the CHANGELOG at its merge base, and the release sets them. Needs `changelog_fragments`, and the stamping `land --pr <n>` refuses under it. `train` keeps merge trains. Read from the base revision only. Needs `min_gstack_version`. | -| `land` | `{ merged_checks, docs_only_skip? }` or `null` | `null` | Under `merge: direct`, the shell commands (1 to 16, one line of at most 512 characters each, 15 minutes each) [`land --pin`](#land-direct) runs on the pin merged onto the base tip when the base moved past the pin's merge base; it lands only when every one exits 0. They are repo commands, so land runs them only with `--allow-repo-commands`, never under `--dry-run`. `null` lands a stale base untested with a `STALE_BASE: warn` line. `docs_only_skip` lists `merged_checks` commands to skip for a docs-only pin ([pregate.md](pregate.md#docs-only)) and needs `min_gstack_version` at its own release (`LAND_DOCS_ONLY_SKIP_KEY_VERSION`), because older releases refuse it. Any other key under `land` is a warning, ignored. Read from the base revision only. Needs `min_gstack_version`. | +| `land` | `{ merged_checks?, docs_only_skip?, merge_commit_paths? }` or `null` | `null` | Under `merge: direct`, the shell commands (1 to 16, one line of at most 512 characters each, 15 minutes each) [`land --pin`](#land-direct) runs on the pin merged onto the base tip when the base moved past the pin's merge base; it lands only when every one exits 0. They are repo commands, so land runs them only with `--allow-repo-commands`, never under `--dry-run`. `null` lands a stale base untested with a `STALE_BASE: warn` line. `docs_only_skip` lists `merged_checks` commands to skip for a docs-only pin ([pregate.md](pregate.md#docs-only)) and needs `min_gstack_version` at its own release (`LAND_DOCS_ONLY_SKIP_KEY_VERSION`), because older releases refuse it. `merge_commit_paths` (1 to 64 git glob pathspecs, no `..`) makes every land form keep a merge commit, with the plain subject and body, for a PR that changes a matching path, such as an eval results PR whose run records point to its own commits; with it, `merged_checks` may be left out, and it needs `min_gstack_version` at its own release (`LAND_MERGE_COMMIT_PATHS_KEY_VERSION`). Any other key under `land` is a warning, ignored. Read from the base revision only. Needs `min_gstack_version`. | | `docs_only` | `{ allow, deny?, tests? }` or `null` | `null` | Human-docs paths beyond `README.md`, `docs/**.md` and `changelog.d/*.md` for the [docs-only class](pregate.md#repo-docs-paths) (`{ "allow": ["wiki/board/**.md"] }`). `allow` (1 to 16) takes narrow Markdown globs: each ends in `.md`, starts with a literal directory or file name, and passes through no hidden, code, test or agent directory; `**`, `*`, `*.md` and patterns naming agent files are `POLICY_INVALID` with an example of a narrow one. `deny` (up to 64 globs) removes paths, built-in ones included. `tests` (up to 16 test files) are the repository's checks for those directories: the docs lane runs them, and a non-prose file that reads an allowed directory refuses the class unless it is tied to one; a listed test missing from the branch refuses it too. The built-in deny list always wins. Any other key under `docs_only` is a warning, and the classifier then ignores `allow`. Read from the base revision only; a pull request that edits this file is never docs-only. Needs `min_gstack_version`. | | `release_gate` | `{ cadence_hours, gate_workflow, branch, stable_ref, check_name, on_red, bisect_spend_cap_usd }` or `null` | `null` | One full paid gate on main every `cadence_hours` (8 to 168) instead of the per-push main backstop, feeding the stable release; see [release_gate](#release-gate). Every field is required: `on_red` is `hold-release`, `bisect_spend_cap_usd` 0 to 500 (0 skips the bisect). `null` keeps the per-push backstop. Needs `min_gstack_version`. | | `bookkeeping` | glob list | `[]` | <a id="bookkeeping"></a>Root-anchored globs of bookkeeping tables a verify or ratchet step rewrites (size baselines, serial lists, limits), each ending in `.tsv`, `.csv` or `.txt` and never under `.gstack/` or `.github/` (`["scripts/*-baseline.tsv"]`). A matching file changed at most 20 lines after review binds, first touched or not, takes finish's [one scoped reader](review-policy.md#bounded-post-review-edits) instead of Steps 5–11.5; the reader still reads every changed row. Read from the base revision only. Needs `min_gstack_version`. | @@ -2655,7 +2655,10 @@ unless: - the /ship receipt in the PR body and a READY note are both bound to the pin. After merging, it checks that main's tree is exactly the pin merged onto the -commit before it (`QUEUE_LAND_UNVERIFIED` otherwise). A script that reads +commit before it (`QUEUE_LAND_UNVERIFIED` otherwise). The merge is one commit +titled `<PR title> (#n)` with the PR body's opening lines and the branch's +trailers as its body ([the commit on main](writing-prs.md#the-commit-on-main)); +`--dry-run` prints it. A script that reads these before calling land adds nothing; read land's output instead. Every check, with its refusal code, is in [the table below](#land-direct-contract). @@ -2984,10 +2987,12 @@ example "Stop gstack from hitting GitHub's rate limit while it waits on PRs". A title may end with one group of references, such as `(GST-1713)`, `(GST-1808, GST-1809)` or `(#4122)`; that group is never checked. A branch may end with one tracker code (`capy/github-rate-limit-gst-1713`). A PR body -opens with one or two plain sentences (what changed and which goal of the -project it serves) and keeps tracker codes, the ship record and other -machine-read lines in the Agent notes section at the end, below the -`<!-- gstack:agent-notes -->` marker. The checker skips that section. +shows at most three plain lines before its first collapsed section (what +changed, why, and what the reader has to do), folds everything else, and keeps +tracker codes, the ship record and other machine-read lines in the Agent notes +section at the end, below the `<!-- gstack:agent-notes -->` marker. The checker +skips that section. [writing-prs.md](writing-prs.md) has the whole shape, the +default word list and the commit every merge makes. What the checker refuses in the front: @@ -2998,7 +3003,10 @@ What the checker refuses in the front: usually an internal module name. A bare `fix:` or `docs:` is allowed, and so is a leading version such as `v1.98.0.0 release`; - in the PR opening, a first block that is a heading, code block, list, table, - HTML or image, or a paragraph longer than two sentences; + HTML or image; +- in the PR body once folded (`PLAIN_BODY_REFUSED`), more than three lines or 600 + characters before the first fold, text outside a fold below it, a listed word + above the Agent notes section, or a /ship record outside that section; - in a changelog entry, a tracker code anywhere, and a listed word in the bold lead. Code spans, code blocks, links and quoted words are skipped. @@ -3016,7 +3024,9 @@ another project. The keys: | `terms` | The project's own words that mean nothing to an outside reader. | | `allow` | `{ "text", "reason" }` entries. A refused match inside an allowed phrase passes. Every entry says why. | | `since` | A date (`YYYY-MM-DD`, midnight UTC). PRs created before it are exempt, so nothing already open breaks. | -| `exempt_branch_prefixes` | Branch prefixes that gstack's own tools generate; those branches are not checked. | +| `exempt_branch_prefixes` | Branch prefixes that gstack's own tools generate; those branches are not checked, and their bodies only warn. | +| `replace_default_terms` | `true` uses `terms` alone; by default gstack's own list (outside voice, pregate, receipt, ledger, fix-check, carry, stamp, restamp, train, lane, soak and their plurals) is added to it. | +| `body_since` | A date: the body shape refuses only for PRs created on or after it (default: `since`), so open PRs are not broken by the new rule. | gstack's own file lists its tracker prefixes (GST, GSTA, GBRA, GEVA, FOUN, HARN, ALPH) and R-numbers (`R76`), the crew and Captain names, and the words last diff --git a/docs/skills.md b/docs/skills.md index 29d280878..468f6cfcd 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -752,14 +752,14 @@ A lot of branches die when the interesting work is done and only the boring rele ### The PR body -`/ship` writes the PR body from the diff, the receipt and the review, and a reader who was not in the session decides the merge from it. The front is for people and the end is for machines: the body opens with one or two plain sentences saying what changed for someone using the project and which README goal it serves, and it ends with one collapsed **Agent notes** section (`<!-- gstack:agent-notes -->` then `<details><summary>Agent notes</summary>`) that holds the ship receipt, the approval and Plan lines, issue codes and the review-loop lines gstack's tools read. The title follows the same shape: plain words first, an issue code only at the end (`Stop gstack from hitting GitHub's rate limit while it waits on PRs (GST-1713)`), checked by `gstack-plain-title` (see [Plain titles](ship-policy.md#plain-titles)). On Capy (`CAPY_PR: on`) the opening is followed by three sections, in this order, before the standard Summary, Test plan and Documentation sections: +`/ship` writes the PR body from the diff, the receipt and the review, and a reader who was not in the session decides the merge from it. The front is for people and the end is for machines: the body opens with at most three plain lines (600 characters) saying what changed for someone using the project, why (the README goal it serves) and what the reader has to do, every other section sits under a `## ` heading that `gstack-post` folds into a collapsed section ([writing-prs.md](writing-prs.md)), and it ends with one collapsed **Agent notes** section (`<!-- gstack:agent-notes -->` then `<details><summary>Agent notes</summary>`) that holds the ship receipt, the approval and Plan lines, issue codes and the review-loop lines gstack's tools read. The title follows the same shape: plain words first, an issue code only at the end (`Stop gstack from hitting GitHub's rate limit while it waits on PRs (GST-1713)`), checked by `gstack-plain-title` (see [Plain titles](ship-policy.md#plain-titles)). On Capy (`CAPY_PR: on`) the opening is followed by three sections, in this order, before the standard sections (Documentation, Tests and the rest); `## What changed` holds the pictures, then the template's themes: 1. **`## What changed`**: one to three captioned before/after images from `gstack-pr-shots` or a UI screenshot, highest-signal first, with a collapsed text version under each. 2. **`## Why`**: two or three sentences. The first states the problem in the person's words (the issue, the message, the failing run), then the cause and the user-visible effect. 3. **`## Blast radius`**: what else the change touches and the one fact that makes that safe, with the evidence-ladder rung that fact reached (a test that exercises the shared path, a grep over every caller, a measured run). A change to a shared helper, a generated file, a selection list or a policy default always has one; a leaf fix says so in one line. `## Approvals`, the output of `gstack-approvals render` verbatim, goes inside Agent notes. On a private repository that is the table; on a public repository, or one whose visibility gh cannot read, it is only `Approved: yes|no (record <id>)`, because GitHub keeps every earlier version of a PR description. The table shows each local path in Asked, Covers and Still pending as `…/<file name>`, so the home directory, user name and Drive folder in those paths stay out of the body; Exact words stays verbatim, and `gstack-approvals list` keeps the full path. For a private repository that may go public, `render --redacted` prints the public form, byte for byte; `--redacted` with `--full` is refused. -Before the body is composed, `gstack-prose-lint` reads the Why, Summary and Blast radius drafts (`--sections 'Why,Summary,Blast radius' --gate`) and the CHANGELOG entry (`--base origin/<base> --gate`), and a `PROSE_LINT_FOUND` line names the sentence to rewrite; the rest of the body is advisory. The Captain's merge-ask template (`captain/templates/merge-ask.md`) carries the same sections, so a READY report and its PR say the same thing. +Before the body is composed, `gstack-prose-lint` reads the Why, What changed and Blast radius drafts (`--sections 'Why,What changed,Blast radius' --gate`) and the CHANGELOG entry (`--base origin/<base> --gate`), and a `PROSE_LINT_FOUND` line names the sentence to rewrite; the rest of the body is advisory. The Captain's merge-ask template (`captain/templates/merge-ask.md`) carries the same sections, so a READY report and its PR say the same thing. ### Versions: where `/ship` looks, and when it ships without one diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 8372be81f..1357386a7 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -7513,8 +7513,7 @@ every flag and code. `bin/gstack-prose-lint` reads the prose /ship is about to publish, a CHANGELOG entry (Step 13) and the sections the author writes in the PR body (Step 19: -`## Why`, `## Summary` and `## Blast radius`, through `--sections`; the -`## What changed` captions and image text stay a report), and the quality-gate +`## Why`, `## What changed` and `## Blast radius`, through `--sections`), and the quality-gate workflow runs it over `CHANGELOG.md`'s `[Unreleased]` block. It decides only what a regular expression can: autopilot vocabulary, "not just X, but Y", metaphor nouns, a colon used as a conjunction, a bold label that restates its @@ -7893,7 +7892,12 @@ These codes come from `bin/gstack-plain-title`, which /ship, gstack-post and the <a id="plain-opening-refused"></a> ### `PLAIN_TITLE: PLAIN_OPENING_REFUSED <kind> "<match>" — …` -**Meaning.** The readable part of the PR body (everything above the `<!-- gstack:agent-notes -->` marker) does not start with a plain paragraph: it starts with a heading, code block, list, table, HTML or image, runs past two sentences, or names a tracker code or listed word. /ship refuses it; CI only warns. **Fix.** Start the body with one or two sentences saying what changed and which goal of the project it serves. Move codes and records into the Agent notes section at the end. +**Meaning.** The readable part of the PR body (everything above the `<!-- gstack:agent-notes -->` marker) does not start with a plain paragraph: it starts with a heading, code block, list, table, HTML or image, or names a tracker code or listed word. /ship refuses it, and so does CI in a repository with a policy for PRs created on or after its `body_since` date. **Fix.** Start the body with up to three plain lines: what changed for a user, why, and anything the reader has to do. Move codes and records into the Agent notes section at the end. + +<a id="plain-body-refused"></a> +### `PLAIN_BODY: PLAIN_BODY_REFUSED <kind> "<match>" — …` + +**Meaning.** The PR body, folded the way gstack-post posts it, breaks the plain shape (docs/writing-prs.md). `visible-lines`: more than three lines or 600 characters show before the first fold. `unfolded`: text sits outside a fold between the first fold and the Agent notes section. `term`: a listed word appears above the Agent notes section (code spans, code blocks, links and quotes are skipped). `receipt-placement`: the /ship receipt sits outside the Agent notes section, or text follows that section. gstack-post exits 4 and posts nothing, and the Plain title CI check fails, in a repository with `.gstack/plain-titles.json` and for a PR created on or after its `body_since` date; everywhere else, and for comments, these are warnings. **Fix.** Rewrite the body file the way the line says: up to three plain lines first, every other section under a `## ` heading (gstack-post folds it; `gstack-post fold --body-file F` shows the result without posting), and records in the Agent notes section. Then post it again; an edited body reruns the CI check. <a id="plain-changelog-refused"></a> ### `PLAIN_TITLE: PLAIN_CHANGELOG_REFUSED <kind> "<match>" — …` diff --git a/docs/writing-prs.md b/docs/writing-prs.md new file mode 100644 index 000000000..5c7c697ed --- /dev/null +++ b/docs/writing-prs.md @@ -0,0 +1,122 @@ +# Writing pull requests and the commits they land as + +People outside a project read its pull requests, its commit log and its release +notes to decide whether the project is worth using. So everything gstack writes +there, and everything you write there with gstack, follows the same few rules. +`/ship` writes it this way for you, and the checks below catch what slips through. + +## The title + +The title says what changed for someone using the project, in everyday words: +"Stop gstack from hitting GitHub's rate limit while it waits on PRs". One group +of issue references may close it, such as `(GST-1713)` or `(#4122)`. No +`fix(module):` prefix, no tracker code in the front, no in-house words. + +## The body + +A reader sees at most **three lines** (and 600 characters) before anything +collapsed: + +1. what changed for a user; +2. why it matters: the project goal it serves or the problem it fixes; +3. anything the reader has to do, or "Nothing to do". + +Everything else goes under a `## ` heading. `gstack-post` turns each heading +into a collapsed section (a `<details>` fold) when it posts, so you never write +HTML by hand. Say each thing once. Link long logs and review output instead of +pasting them. + +The last section is **Agent notes**, which `/ship` adds. It holds the lines +gstack's tools read: issue links, approvals, review counts and the `/ship` +record. Nothing comes after it except a bot's badge. + +Here is how a body looks on GitHub before anyone clicks: + +``` +/ship's reviewers now end their reply with one count line, and gstack checks it against the findings it read. + +Why: the findings reader misread free-form review prose, so a real problem could be lost. + +Nothing to do: replies without the line are read exactly as before. + +▸ What changed +▸ Tests +▸ Agent notes +``` + +To see a body folded without posting it, run +`gstack-post fold --body-file body.md`. Use its output whenever you post a body +some other way, such as a web editor or another tool. + +## Words to keep out of the front + +Some words mean something only inside the team that uses gstack. Keep them out +of the title, the commit subject and everything above the Agent notes section, +and say what the thing does instead: + +| Instead of | Write | +|------------|-------| +| outside voice | second-model review | +| pregate | the checks that run before a PR opens | +| receipt, ledger | the record of what was checked | +| fix-check | the re-check of a fix | +| carry | reuse a result from an earlier commit | +| stamp, restamp | set the version | +| train, lane, soak | merge several PRs together; the job that runs one part of the work; the wait before a release goes out to everyone | + +gstack ships that list as the default. A project adds its own words in +`.gstack/plain-titles.json` (`terms`), and gstack's own file adds its team names. +Code spans, code blocks, links and quotes are never checked, and the Agent +notes section may use any word. + +<a id="the-commit-on-main"></a> +## The commit on main + +Every gstack merge (`gstack-ship-queue land`, in each of its forms) lands a PR +as **one commit**: + +- the subject is the PR title with GitHub's number, `<title> (#1234)`; +- the body is the PR body's opening lines (at most three, links reduced to their + text), then every trailer the branch's commits carry (`Co-authored-by:`, + `Removed-test:` and any other `Key: value` line), each once, plus a + `Co-authored-by:` for every other commit author. + +So `git log --oneline` reads as a list of changes, with no "Merge pull request" +lines and none of the branch's housekeeping commits. A release PR's commit body +is its release notes instead, one plain line per change with the PR that made it. +Commits from a stacked PR that already landed are left out. + +`gstack-ship-queue land --dry-run` prints the `METHOD:`, `SUBJECT:` and `BODY:` +lines before anything merges, and `--body-file <file>` replaces the opening lines +when the PR body's opening does not suit a commit. Land checks the whole message +for secrets first: a key or token refuses the land, and anything that only looks +private drops the opening and keeps the trailers. + +These settings keep a merge commit instead of a squash, with the same subject and +body ([ship-policy.md](ship-policy.md)): + +- `history: merge-only`, for a repository whose branch rules allow only merge + commits; +- `land.merge_commit_paths`, for PRs that change matching paths, such as an + eval results PR whose run records point to commits on its own branch; +- a merge train whose `train.land.merge_method` is `merge`. + +`history: no-rewrite` is the setting for a repository that wants squash +landings but never a rebased or force-pushed branch: +`gstack-ship-policy check-history --plan rebase` refuses there. + +## Comments and release notes + +GitHub comments and release notes follow the same rules: plain words, the short +version first, details linked. `gstack-post` warns about listed words in a +comment but never refuses one. A published release carries real notes, one +plain line per change, never just a link to the CHANGELOG. + +## When a check refuses + +In a repository with `.gstack/plain-titles.json`, `gstack-post` refuses a body +that breaks these rules (exit 4, `PLAIN_BODY:` lines, nothing posted), and so +does the **Plain title** CI check for PRs opened on or after the policy's +`body_since` date. Each line says what to change; see +[troubleshooting](troubleshooting.md#plain-body-refused). Without the file, +the same findings are warnings only. diff --git a/lib/gstack-post.ts b/lib/gstack-post.ts index 30fb4524f..425979041 100644 --- a/lib/gstack-post.ts +++ b/lib/gstack-post.ts @@ -13,7 +13,10 @@ * its first `## ` section replaces the text between the receipt and the * first heading while the opening text above the receipt is kept; * the Agent notes section (lib/agent-notes.ts) is one section that always - * stays last; `--replace` overwrites instead. + * stays last; `--replace` overwrites instead. Folds in the current body merge by + * their summary, and every body is folded before it is sent (lib/pr-body-shape.ts: + * three visible lines, every `## ` section collapsed), then checked; `fold` + * prints the folded body and posts nothing. * `pr-title` and `pr-create` first check the title against the repository's * plain-title policy (lib/plain-title.ts); a refused title posts nothing. * The scan runs on the merged bytes, which are the bytes sent. @@ -22,7 +25,8 @@ * 2 MEDIUM findings need confirmation, printed as `RULE:` lines plus a * `TOKEN:` that binds the bytes, destination, operation and findings; * 3 `gh`/`glab` failed; 4 the title breaks the plain-title policy, printed as - * `PLAIN_TITLE:` lines; 64 usage or invalid input. Nothing is posted on any + * `PLAIN_TITLE:` lines, or the body breaks the shape, printed as `PLAIN_BODY:` + * lines (title and body are checked in one pass); 64 usage or invalid input. Nothing is posted on any * non-zero exit. bin/gstack-post is the CLI; tests drive `runPost` with a fake * runner so the logic is covered on every platform. */ @@ -30,14 +34,15 @@ import { createHash } from "crypto"; import { scan, type Finding, type RepoVisibility } from "./redact-engine"; import { CI_RUN_WORD_BEFORE } from "./redact-patterns"; import { agentNotesLines, splitAgentNotes } from "./agent-notes"; -import { checkTitle, loadPlainTitlePolicy, PLAIN_TITLE_POLICY_PATH } from "./plain-title"; +import { checkTitle, loadPlainTitlePolicy, PLAIN_TITLE_POLICY_PATH, type PlainTitlePolicy } from "./plain-title"; +import { bodyFindingLine, checkBodyShape, foldSections, unfoldSections } from "./pr-body-shape"; import { RECEIPT_FENCE, RUNS_FENCE, extractReceipt, placeReceipt, renderReceiptBlock, validateReceipt } from "./ship-receipt"; import type { ShipReceipt } from "./headless-artifacts"; import { canonicalRemote } from "./remote-identity"; import { parseChangelog } from "./changelog-check"; import { versionWidth } from "./version-source"; -export const OPS = ["pr-comment", "issue-comment", "reply", "pr-title", "pr-body", "pr-create", "issue-create"] as const; +export const OPS = ["pr-comment", "issue-comment", "reply", "pr-title", "pr-body", "pr-create", "issue-create", "fold"] as const; export type Op = (typeof OPS)[number]; export type HostKind = "github" | "gitlab"; @@ -61,6 +66,7 @@ export const USAGE = `usage: gstack-post <op> [<target>] [options] gstack-post pr-body <pr> --body-file F [--replace] gstack-post pr-create --base <branch> [--head <branch>] [--draft] --title-file F --body-file F gstack-post issue-create --title-file F --body-file F + gstack-post fold --body-file F (prints the folded body; posts nothing) <pr>/<issue> is a number or a URL of this repository on the same host. Options: --host github|gitlab (default: detected from the origin remote) @@ -79,8 +85,11 @@ export const USAGE = `usage: gstack-post <op> [<target>] [options] Exit: 0 posted · 1 HIGH finding refused · 2 MEDIUM findings need confirmation (RULE:/TOKEN: lines on stdout) · 3 gh/glab failed · - 4 the title is not plain words (PLAIN_TITLE: lines on stdout; rewrite the - title file and rerun) or the plain-title policy is invalid; nothing posted · 64 usage + 4 the title is not plain words (PLAIN_TITLE: lines; rewrite the title file) + or the body breaks the shape (PLAIN_BODY: lines; rewrite the body file), or + the plain-title policy is invalid; nothing posted · 64 usage + Every PR body is folded before it is sent: the lines above the first ## stay + visible (at most 3, docs/writing-prs.md), each ## section becomes a fold. `; interface Request { @@ -156,10 +165,10 @@ function parseArgs(argv: string[]): Request { if (!req.attribute || /[\r\n\u0000-\u001f]/.test(req.attribute)) throw new UsageError("--attribute needs one line of text, like \"<model> on behalf of <login>\""); if (req.attribute.length > 200) throw new UsageError("--attribute must be 200 characters or fewer"); } - const creates = req.op === "pr-create" || req.op === "issue-create"; + const creates = req.op === "pr-create" || req.op === "issue-create" || req.op === "fold"; if (positional.length > (creates ? 0 : 1)) throw new UsageError(`unexpected argument "${positional[creates ? 0 : 1]}"`); if (!creates && !req.target) throw new UsageError(`${req.op} needs a target (a number or a URL)`); - const needsTitle = req.op === "pr-title" || creates; + const needsTitle = req.op === "pr-title" || (creates && req.op !== "fold"); const needsBody = req.op !== "pr-title"; if (needsTitle !== !!req.titleFile) throw new UsageError(needsTitle ? `${req.op} needs --title-file` : `${req.op} takes no --title-file`); if (needsBody !== !!req.bodyFile) throw new UsageError(needsBody ? `${req.op} needs --body-file` : `${req.op} takes no --body-file (use --title-file)`); @@ -663,15 +672,21 @@ function send(env: PostEnv, kind: HostKind, req: Request, n: string | undefined, * title passes or the repository has no policy. A finding prints one `PLAIN_TITLE:` line each, in gstack-plain-title's * format, then `PLAIN_TITLE: refused=<n>`; an invalid policy refuses too, so nothing is posted until it is fixed. */ -function plainTitle(env: PostEnv, title: string): boolean { +function plainPolicy(env: PostEnv, comment = false): PlainTitlePolicy | null | "invalid" { const top = env.run("git", ["rev-parse", "--show-toplevel"]); const root = top.status === 0 ? top.stdout.trim() : ""; - if (!root) return true; - let findings; - try { findings = checkTitle(title, loadPlainTitlePolicy(root)); } catch (e) { - env.err(`gstack-post: ${e instanceof Error ? e.message : String(e)} (PLAIN_POLICY_INVALID); nothing was posted. Fix the policy (gstack-plain-title validate), then rerun.\n`); - return false; + if (!root) return null; + try { return loadPlainTitlePolicy(root); } catch (e) { + const why = `gstack-post: ${e instanceof Error ? e.message : String(e)} (PLAIN_POLICY_INVALID)`; + if (comment) { env.err(`${why}; the comment is posted unchecked. Fix the policy (gstack-plain-title validate).\n`); return null; } + env.err(`${why}; nothing was posted. Fix the policy (gstack-plain-title validate), then rerun.\n`); + return "invalid"; } +} + +function plainTitle(env: PostEnv, title: string, policy: PlainTitlePolicy | null | "invalid"): boolean { + if (policy === "invalid") return false; + const findings = checkTitle(title, policy); if (!findings.length) return true; const clean = (s: string) => s.replace(/[\u0000-\u001f\u007f"]/g, " ").slice(0, 80); for (const f of findings) env.out(`PLAIN_TITLE: ${f.code} ${f.kind} "${clean(f.match)}" — ${f.hint}\n`); @@ -680,6 +695,23 @@ function plainTitle(env: PostEnv, title: string): boolean { return false; } +/** + * The body shape check (lib/pr-body-shape.ts) on the folded bytes: one `PLAIN_BODY:` line per finding, then + * `PLAIN_BODY: refused=<n>` or `warned=<n>`. Findings refuse only with a policy file and for a PR created on or after + * its body_since (an existing PR's date is read only when a finding needs it); anything else, comments included, warns. + */ +function plainBody(env: PostEnv, body: string, policy: PlainTitlePolicy | null | "invalid", createdAt: () => string | undefined, comment = false): boolean { + if (policy === "invalid") return false; + const findings = comment ? (policy ? checkBodyShape(`<details>\n\n${body}\n\n</details>`, policy.terms).filter(f => f.kind === "term") : []) : checkBodyShape(body, policy?.terms ?? []); + if (!findings.length) return true; + const when = comment || !policy ? undefined : createdAt(); + const refuse = !!policy && !comment && (when === undefined || Date.parse(when) >= Date.parse(policy.body_since ?? policy.since)); + for (const f of findings) env.out(bodyFindingLine(f, !refuse) + "\n"); + env.out(`PLAIN_BODY: ${refuse ? "refused" : "warned"}=${findings.length}\n`); + if (refuse) env.err("gstack-post: the body does not have the plain shape; nothing was posted. Rewrite the body file the way each PLAIN_BODY: line says (docs/writing-prs.md), then rerun.\n"); + return !refuse; +} + export function runPost(argv: string[], env: PostEnv, configBin = "gstack-config"): number { if (argv.length === 0 || ["help", "--help", "-h"].includes(argv[0]!)) { (argv.length === 0 ? env.err : env.out)(USAGE); @@ -687,11 +719,17 @@ export function runPost(argv: string[], env: PostEnv, configBin = "gstack-config } try { const req = parseArgs(argv); + if (req.op === "fold") { + const folded = foldSections(readText(env, req.bodyFile!, "body")); + env.out(folded.endsWith("\n") ? folded : folded + "\n"); + return plainBody({ ...env, out: env.err }, folded, plainPolicy(env), () => undefined) ? EXIT.posted : EXIT.plainTitle; + } const remote = resolveRemote(env, req.host); if (req.op === "reply" && remote.kind !== "github") throw new UsageError("reply is supported on GitHub only"); const n = req.target === undefined ? undefined : targetNumber(req.target, req.op, remote); const title = req.titleFile ? readText(env, req.titleFile, "title") : undefined; - if (title !== undefined && (req.op === "pr-title" || req.op === "pr-create") && !plainTitle(env, title)) return EXIT.plainTitle; + const policy = req.op === "issue-create" ? null : plainPolicy(env, COMMENT_OPS.has(req.op)); + const titleOk = title === undefined || !(req.op === "pr-title" || req.op === "pr-create") || plainTitle(env, title, policy); let body = req.bodyFile ? readText(env, req.bodyFile, "body") : undefined; if (req.op === "pr-body" && !req.replace) { const current = currentBody(env, remote.kind, n!); @@ -699,11 +737,15 @@ export function runPost(argv: string[], env: PostEnv, configBin = "gstack-config env.err(`gstack-post: cannot read PR ${n}'s current body to merge into (${current.error}); nothing was posted. Rerun with --replace to overwrite the whole body.\n`); return EXIT.cliFailed; } - const m = mergeBodySections(current.body, body!); + const m = mergeBodySections(unfoldSections(current.body), unfoldSections(body!)); body = m.body; const list = (names: string[]) => (names.length ? names.join(", ") : "none"); env.err(`gstack-post: pr-body merged by section: replaced ${list(m.replaced)}; kept ${list(m.kept)}; added ${list(m.added)}${m.dropped.length ? `; dropped ${m.dropped.join(", ")}` : ""}\n`); } + if (body !== undefined && (req.op === "pr-body" || req.op === "pr-create")) body = foldSections(body); + const createdAt = () => { const r = env.run("gh", ["pr", "view", n!, "--json", "createdAt", "--jq", ".createdAt"]); return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : undefined; }; + const bodyOk = body === undefined || req.op === "issue-create" || plainBody(env, body, policy, req.op === "pr-create" ? () => undefined : createdAt, COMMENT_OPS.has(req.op)); + if (!titleOk || !bodyOk) return EXIT.plainTitle; if (body !== undefined && req.attribute) body = attributionCallout(req.attribute) + body; const parts: Array<[Part, string]> = []; if (title !== undefined) parts.push(["title", title]); diff --git a/lib/land-merged-checks.ts b/lib/land-merged-checks.ts index 3d0421612..fdd731a95 100644 --- a/lib/land-merged-checks.ts +++ b/lib/land-merged-checks.ts @@ -32,7 +32,9 @@ function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv): { ok: boolea export interface LandPolicy { /** Shell commands run in the pin merged onto the base tip, in order; each must exit 0. */ - merged_checks: string[]; + merged_checks?: string[]; + /** Git glob pathspecs: a PR that changes one lands as a merge commit, not a squash, so commits a receipt points to stay on the base (lib/squash-message.ts). */ + merge_commit_paths?: string[]; } const MAX_CHECKS = 16, MAX_COMMAND = 512, CHECK_TIMEOUT_MS = 900_000; @@ -40,16 +42,19 @@ const KEPT_ENV = ['PATH', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR']; /** No hook or fsmonitor from the repository's config or the merged tree runs in the git calls around the checks. */ const NO_HOOKS = ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false']; -export const LAND_EXPLANATION = '{ merged_checks, docs_only_skip? } or null, read from the base revision only: under merge: direct, when the base moved past a pin\'s merge base, `land --pin` builds the pin merged onto the base tip in a throwaway worktree (the checkout\'s node_modules linked in) and runs each merged_checks command there (at most 16, 512 characters each, 15 minutes each); it lands only when every one exits 0, and refuses on a conflict (QUEUE_LAND_NOT_CLEAN) or a failure (QUEUE_LAND_MERGED_CHECKS). They are repo commands: land runs them only with --allow-repo-commands (else REPO_COMMANDS_NOT_ALLOWED), never under --dry-run, with PATH and locale as the only environment and a throwaway HOME. null lands a stale base unchecked with a STALE_BASE: warn line. docs_only_skip names merged_checks commands land skips for a pin lib/docs-only.ts calls human docs only (docs/pregate.md#docs-only) and needs min_gstack_version at its own introducing release. An unknown key under land is a warning, ignored.'; +export const LAND_EXPLANATION = '{ merged_checks, docs_only_skip? } or null, read from the base revision only: under merge: direct, when the base moved past a pin\'s merge base, `land --pin` builds the pin merged onto the base tip in a throwaway worktree (the checkout\'s node_modules linked in) and runs each merged_checks command there (at most 16, 512 characters each, 15 minutes each); it lands only when every one exits 0, and refuses on a conflict (QUEUE_LAND_NOT_CLEAN) or a failure (QUEUE_LAND_MERGED_CHECKS). They are repo commands: land runs them only with --allow-repo-commands (else REPO_COMMANDS_NOT_ALLOWED), never under --dry-run, with PATH and locale as the only environment and a throwaway HOME. null lands a stale base unchecked with a STALE_BASE: warn line. docs_only_skip names merged_checks commands land skips for a pin lib/docs-only.ts calls human docs only (docs/pregate.md#docs-only) and needs min_gstack_version at its own introducing release. merge_commit_paths lists git glob pathspecs (at most 64, 256 characters each, no `..`): a PR that changes one lands as a merge commit instead of a squash, so an eval results PR keeps the commits its run receipts point to (docs/writing-prs.md#the-commit-on-main); it needs min_gstack_version at its own introducing release, and with it merged_checks may be left out. An unknown key under land is a warning, ignored.'; /** The keys this gstack reads under land; any other is a warning (lib/ship-policy.ts policyWarnings), never an error. */ -export const LAND_KEYS: readonly string[] = ['merged_checks', 'docs_only_skip']; +export const LAND_KEYS: readonly string[] = ['merged_checks', 'docs_only_skip', 'merge_commit_paths']; export function landPolicyErrors(raw: unknown): PolicyError[] { const l = raw as Record<string, unknown> | null; if (!l || typeof l !== 'object' || Array.isArray(l)) return [{ code: 'POLICY_INVALID', path: 'land', message: 'must be { merged_checks } or null' }]; const out: PolicyError[] = []; + const paths = l.merge_commit_paths; + if (paths !== undefined && (!Array.isArray(paths) || !paths.length || paths.length > 64 || paths.some(p => typeof p !== 'string' || !p.trim() || p.length > 256 || /[\0\r\n]/.test(p) || p.startsWith('/') || p.split(/[\\/]+/).includes('..')))) out.push({ code: 'POLICY_INVALID', path: 'land.merge_commit_paths', message: 'must list 1 to 64 relative git glob pathspecs of at most 256 characters, with no `..`' }); const c = l.merged_checks; + if (c === undefined && paths !== undefined && l.docs_only_skip === undefined) return out; if (!Array.isArray(c) || !c.length || c.length > MAX_CHECKS) return [...out, { code: 'POLICY_INVALID', path: 'land.merged_checks', message: `must list 1 to ${MAX_CHECKS} commands` }]; const skip = l.docs_only_skip; if (skip !== undefined && (!Array.isArray(skip) || skip.some(s => !c.includes(s)) || skip.length >= c.length)) out.push({ code: 'POLICY_INVALID', path: 'land.docs_only_skip', message: 'must list merged_checks commands, leaving at least one to run' }); diff --git a/lib/plain-title.ts b/lib/plain-title.ts index f659d7f16..ff43edacf 100644 --- a/lib/plain-title.ts +++ b/lib/plain-title.ts @@ -6,7 +6,9 @@ * tracker-code regexes, `terms` are the project's own coined words, `allow` * entries (each with a reason) suppress a match they contain, `since` exempts * PRs created before that date, and `exempt_branch_prefixes` names generated - * branches. Front for humans, end for machines: one trailing group of + * branches. DEFAULT_TERMS (the words gstack's own tools print) join `terms` + * unless `replace_default_terms` is true; `body_since` exempts older PRs from + * the body shape check (lib/pr-body-shape.ts) only. Front for humans, end for machines: one trailing group of * references such as `(GST-1713)` or `(#4122)` is never checked. A repository * without the file gets no findings. Callers: bin/gstack-plain-title, * gstack-post and the "Plain title" CI check. @@ -17,11 +19,14 @@ import { splitAgentNotes } from './agent-notes'; import { maskProse } from './prose-lint'; import { redactFindingSpans } from './redact-engine'; -export interface PlainTitlePolicy { codes: string[]; terms: string[]; allow: { text: string; reason: string }[]; since: string; exempt_branch_prefixes: string[] } +export interface PlainTitlePolicy { codes: string[]; terms: string[]; allow: { text: string; reason: string }[]; since: string; exempt_branch_prefixes: string[]; body_since?: string } export interface PlainFinding { code: 'PLAIN_TITLE_REFUSED' | 'PLAIN_BRANCH_REFUSED' | 'PLAIN_OPENING_REFUSED' | 'PLAIN_CHANGELOG_REFUSED' | 'PLAIN_COMMIT_REFUSED'; kind: 'code' | 'term' | 'scope-prefix' | 'opening-shape'; match: string; hint: string } export const PLAIN_TITLE_POLICY_PATH = '.gstack/plain-titles.json'; -const KEYS = ['$schema', 'codes', 'terms', 'allow', 'since', 'exempt_branch_prefixes']; +const KEYS = ['$schema', 'codes', 'terms', 'allow', 'since', 'exempt_branch_prefixes', 'replace_default_terms', 'body_since']; +/** Words gstack's own tools print into PR text, which mean nothing to an outside reader; a policy's `terms` add to them. */ +export const DEFAULT_TERMS: readonly string[] = ['outside voice', 'pregate', 'receipt', 'receipts', 'ledger', 'ledgers', 'fix-check', 'carry', 'stamp', 'restamp', 'train', 'trains', 'lane', 'lanes', 'soak']; +const isDate = (v: unknown) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}/.test(v) && !Number.isNaN(Date.parse(v)); const HINTS = { code: 'move the tracker code to one trailing group like (ABC-123)', PLAIN_BRANCH_REFUSED: 'keep at most one tracker code, at the very end of the branch name', @@ -29,7 +34,7 @@ const HINTS = { PLAIN_CHANGELOG_REFUSED: 'leave tracker codes out of changelog entries', term: 'say what it does for someone using the project, in everyday words', 'scope-prefix': 'drop the type(scope): prefix and start with what changed', - 'opening-shape': 'open with one or two plain sentences: what changed and which goal of the project it serves', + 'opening-shape': 'open with plain lines: what changed for a user, why, and anything the reader has to do', } as const; type Code = PlainFinding['code']; @@ -63,10 +68,13 @@ export function loadPlainTitlePolicy(repoRoot: string): PlainTitlePolicy | null if (typeof entry.text !== 'string' || !entry.text.trim()) throw bad(`allow[${i}].text`, 'must be a non-empty string'); if (typeof entry.reason !== 'string' || !entry.reason.trim()) throw bad(`allow[${i}].reason`, 'must say why the entry is allowed'); }); - if (typeof obj.since !== 'string' || !/^\d{4}-\d{2}-\d{2}/.test(obj.since) || Number.isNaN(Date.parse(obj.since))) throw bad('since', 'must be a date like 2026-11-08'); + if (!isDate(obj.since)) throw bad('since', 'must be a date like 2026-11-08'); + if (obj.body_since !== undefined && !isDate(obj.body_since)) throw bad('body_since', 'must be a date like 2026-11-20'); + if (obj.replace_default_terms !== undefined && typeof obj.replace_default_terms !== 'boolean') throw bad('replace_default_terms', 'must be true or false'); + const terms = obj.replace_default_terms ? obj.terms : [...new Set([...obj.terms, ...DEFAULT_TERMS])]; const prefixes = obj.exempt_branch_prefixes ?? []; if (!Array.isArray(prefixes) || !prefixes.every(p => typeof p === 'string' && p.length > 0)) throw bad('exempt_branch_prefixes', 'must be a list of non-empty strings'); - return { codes: obj.codes, terms: obj.terms, allow: allow as PlainTitlePolicy['allow'], since: obj.since, exempt_branch_prefixes: prefixes as string[] }; + return { codes: obj.codes, terms, allow: allow as PlainTitlePolicy['allow'], since: obj.since as string, exempt_branch_prefixes: prefixes as string[], body_since: (obj.body_since as string | undefined) ?? (obj.since as string) }; } /** A whole-word, case-insensitive regex for a term; a space in the term matches any run of spaces. */ @@ -159,7 +167,7 @@ function openingShape(line: string): string | null { return null; } -/** The readable part (above the Agent notes marker) opens with a prose paragraph of at most two sentences and no refused code or term. */ +/** The readable part (above the Agent notes marker) opens with a prose paragraph with no refused code or term; how long the opening may run is lib/pr-body-shape.ts's check. */ export function checkOpening(body: string, policy: PlainTitlePolicy | null): PlainFinding[] { if (!policy) return []; const code: Code = 'PLAIN_OPENING_REFUSED'; @@ -173,12 +181,7 @@ export function checkOpening(body: string, policy: PlainTitlePolicy | null): Pla const paragraph = lines.slice(start, end < 0 ? undefined : end).join(' ') .replace(/\]\([^)\s]*\)/g, m => ']' + ' '.repeat(m.length - 1)) .replace(/https?:\/\/\S+/g, 'URL'); - const sentences = paragraph.replace(/`[^`]*`/g, 'x').replace(/\b(?:e\.g|i\.e|etc|vs)\./gi, 'x') - .split(/[.!?]+["')\]]*(?:\s+|$)/).filter(s => s.trim()).length; - return [ - ...(sentences > 2 ? [shapeFinding(`${sentences} sentences`)] : []), - ...toFindings(code, scan(paragraph.replace(/`/g, ' '), policy)), - ]; + return toFindings(code, scan(paragraph.replace(/`[^`]*`/g, ' '), policy)); } /** No tracker code anywhere in the entry; refused terms only in its bold lead. Fenced and inline code, URLs and quoted words are skipped. */ diff --git a/lib/pr-body-shape.ts b/lib/pr-body-shape.ts new file mode 100644 index 000000000..839808519 --- /dev/null +++ b/lib/pr-body-shape.ts @@ -0,0 +1,143 @@ +/** + * pr-body-shape — the shape every PR body takes (R76 as amended 2026-11-15, docs/writing-prs.md): at most three + * visible lines before anything folded (what changed for a user, why, and anything the reader has to do), every + * other section folded into a `<details>` block, and the Agent notes section (lib/agent-notes.ts), which holds the + * /ship receipt, last. /ship and people write `## ` sections; gstack-post folds them on publish (foldSections), so + * nobody writes HTML by hand. checkBodyShape is the check gstack-post, gstack-plain-title and the Plain title CI check + * share; a finding refuses only in a repository with `.gstack/plain-titles.json`, and warns everywhere else. + */ +import { AGENT_NOTES_MARKER } from './agent-notes'; +import { maskProse } from './prose-lint'; + +export const VISIBLE_LINES = 3; +export const VISIBLE_CHARS = 600; +export interface BodyFinding { code: 'PLAIN_BODY_REFUSED'; kind: 'visible-lines' | 'unfolded' | 'term' | 'receipt-placement'; match: string; hint: string } + +const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/; +const closesFence = (fence: string, line: string) => new RegExp(`^ {0,3}${fence[0] === '`' ? '`' : '~'}{${fence.length},}\\s*$`).test(line); +const FOLD_OPEN = /^<details>\s*<summary>([^<]*)<\/summary>\s*$/i; +const escape = (s: string) => s.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>'); +const unescape = (s: string) => s.replace(/</g, '<').replace(/>/g, '>').replace(/&/g, '&'); +const tagDelta = (line: string) => { const prose = line.replace(/`[^`]*`/g, ''); return (prose.match(/<details\b/gi)?.length ?? 0) - (prose.match(/<\/details>/gi)?.length ?? 0); }; + +/** One line of a body with what the shape rules need to know about it. */ +interface Line { text: string; depth: number; fenced: boolean; notes: boolean; opensFence?: boolean } + +/** Every line of the body, marking those inside a code fence, inside a `<details>` block (depth before the line) and from the Agent notes marker on. */ +function classify(body: string): Line[] { + const out: Line[] = []; + let fence: string | null = null, depth = 0, notes = false; + for (const text of body.replace(/\r\n?/g, '\n').split('\n')) { + if (!notes && fence === null && depth === 0 && text.trim() === AGENT_NOTES_MARKER) notes = true; + const line: Line = { text, depth, fenced: fence !== null, notes }; + out.push(line); + if (fence !== null) { if (closesFence(fence, text)) fence = null; continue; } + const open = FENCE_OPEN.exec(text); + if (open) { fence = open[1]!; line.fenced = true; line.opensFence = true; continue; } + depth = Math.max(0, depth + tagDelta(text)); + } + return out; +} + +/** HTML comments render as nothing, so they never count as text; the Agent notes marker, itself a comment, is kept. */ +const stripComments = (body: string) => body.replace(/<!--[\s\S]*?-->/g, m => (m === AGENT_NOTES_MARKER ? m : m.replace(/[^\n]/g, ''))); +const blankRun = (lines: string[]) => { while (lines.length && !lines[0]!.trim()) lines.shift(); while (lines.length && !lines.at(-1)!.trim()) lines.pop(); return lines; }; + +/** + * Every top-level `## ` section above the Agent notes marker becomes a fold titled by its heading; the opening above + * the first heading, existing folds, fenced code, the Agent notes section and anything after it are kept byte for + * byte. Folding a folded body changes nothing. + */ +export function foldSections(body: string): string { + const lines = classify(body); + const out: string[] = []; + let section: { title: string; body: string[] } | null = null; + const flush = () => { + if (!section) return; + out.push(`<details><summary>${escape(section.title)}</summary>`, '', ...blankRun(section.body), '', '</details>', ''); + section = null; + }; + for (const l of lines) { + const heading = !l.notes && !l.fenced && l.depth === 0 ? /^ {0,3}## (.+)$/.exec(l.text) : null; + if (heading) { flush(); section = { title: heading[1]!.trim(), body: [] }; continue; } + if (l.notes && section) flush(); + if (section) section.body.push(l.text); + else out.push(l.text); + } + flush(); + return out.join('\n').replace(/\n{3,}(?=<details>)/g, '\n\n').replace(/\n+$/, body.endsWith('\n') ? '\n' : ''); +} + +/** The inverse of foldSections for top-level folds above the Agent notes marker, so a body merges by section title (lib/gstack-post.ts). */ +export function unfoldSections(body: string): string { + const lines = classify(body); + const out: string[] = []; + for (let i = 0; i < lines.length; i++) { + const l = lines[i]!; + const open = !l.notes && !l.fenced && l.depth === 0 ? FOLD_OPEN.exec(l.text.trim()) : null; + const end = open ? lines.findIndex((m, j) => j > i && !m.fenced && m.depth === 1 && m.text.trim() === '</details>') : -1; + if (!open || end < 0) { out.push(l.text); continue; } + out.push(`## ${unescape(open[1]!.trim())}`, '', ...blankRun(lines.slice(i + 1, end).map(m => m.text)), ''); + i = end; + while (i + 1 < lines.length && !lines[i + 1]!.text.trim() && lines[i + 2] && !lines[i + 2]!.notes) i++; + } + return out.join('\n'); +} + +/** The visible opening: the lines above the first fold and the Agent notes marker, HTML comments removed, blank lines dropped; `prose` also drops code blocks, which a commit message never carries. */ +export function visibleOpening(body: string, prose = false): string[] { + const lines = classify(stripComments(body)); + const first = lines.findIndex(l => l.notes || (!l.fenced && l.depth === 0 && /^<details\b/i.test(l.text.trim()))); + return lines.slice(0, first < 0 ? undefined : first).filter(l => !(prose && l.fenced)).map(l => l.text).filter(t => t.trim()); +} + +/** A whole-word, case-insensitive matcher for a listed word; a space in it matches any run of spaces. */ +const wordRe = (term: string) => { + const t = term.trim(); + const edge = (c: string) => (/[A-Za-z0-9_]/.test(c) ? '\\b' : ''); + return new RegExp(`${edge(t[0]!)}${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+')}${edge(t.slice(-1))}`, 'gi'); +}; + +/** + * The shape findings for a body as it will be posted (fold it first): more than VISIBLE_LINES lines or VISIBLE_CHARS + * characters before the first fold, text outside a fold between the first fold and the Agent notes marker, a listed + * word anywhere above the marker (code, quotes and URLs skipped), and a receipt outside the Agent notes section or text + * after it other than a Capy badge. + */ +export function checkBodyShape(body: string, terms: readonly string[] = []): BodyFinding[] { + const out: BodyFinding[] = []; + const add = (kind: BodyFinding['kind'], match: string, hint: string) => out.push({ code: 'PLAIN_BODY_REFUSED', kind, match, hint }); + const opening = visibleOpening(body); + const chars = [...opening.join('\n')].length; + if (opening.length > VISIBLE_LINES || chars > VISIBLE_CHARS) { + add('visible-lines', `${opening.length} lines, ${chars} characters before the first fold`, `keep at most ${VISIBLE_LINES} lines and ${VISIBLE_CHARS} characters above the first fold (what changed for a user, why, what the reader has to do); move the rest into a ## section, which gstack-post folds`); + } + const lines = classify(stripComments(body)); + const firstFold = lines.findIndex(l => !l.notes && !l.fenced && l.depth === 0 && /^<details\b/i.test(l.text.trim())); + const loose = firstFold < 0 ? [] : lines.slice(firstFold).filter(l => !l.notes && l.depth === 0 && l.text.trim() && !/^<\/?details\b/i.test(l.text.trim())); + if (loose.length) add('unfolded', loose[0]!.text.trim().slice(0, 80), 'everything below the opening sits in a fold: put it under a ## heading, which gstack-post folds'); + const notesAt = lines.findIndex(l => l.notes); + if (lines.some((l, i) => (notesAt < 0 || i < notesAt) && l.opensFence && /^ {0,3}`{3,}gstack-ship-receipt\s*$/.test(l.text))) add('receipt-placement', 'gstack-ship-receipt', 'the /ship receipt belongs in the closing Agent notes section; let gstack-ship-receipt write place it'); + if (notesAt >= 0) { + const close = lines.findIndex((l, i) => i > notesAt && !l.fenced && l.text.trim() === '</details>' && l.depth === 1); + const after = close < 0 ? '' : lines.slice(close + 1).map(l => l.text).join('\n').replace(/<a href="https:\/\/capy\.ai\/[\s\S]*?<\/a>/g, '').trim(); + if (after) add('receipt-placement', after.split('\n')[0]!.slice(0, 80), 'the Agent notes section ends the body; move this text above it'); + } + if (terms.length) { + const readable = lines.slice(0, notesAt < 0 ? undefined : notesAt).map(l => l.fenced ? '' : l.text).join('\n'); + const masked = maskProse(readable.replace(/<summary>([^<]*)<\/summary>/gi, ' $1 ')).masked.replace(/<[^>]+>/g, ' ').replace(/[^\s()[\]<>"'`]*\/[^\s()[\]<>"'`]*|[\w.-]+\.[A-Za-z][A-Za-z0-9]{0,5}\b/g, m => ' '.repeat(m.length)); + const seen = new Set<string>(); + for (const term of terms) for (const m of masked.matchAll(wordRe(term))) { + if (seen.has(m[0].toLowerCase())) continue; + seen.add(m[0].toLowerCase()); + add('term', m[0], 'say what it does for someone using the project, in everyday words (the Agent notes section may keep it)'); + } + } + return out; +} + +/** One `PLAIN_BODY:` line per finding, in gstack-plain-title's format. */ +export function bodyFindingLine(f: BodyFinding, warnOnly: boolean): string { + const clean = f.match.replace(/[\u0000-\u001f\u007f"]/g, ' ').slice(0, 80); + return `PLAIN_BODY: ${f.code} ${f.kind} "${clean}" — ${f.hint}${warnOnly ? ' (warning only)' : ''}`; +} diff --git a/lib/release-stamp.ts b/lib/release-stamp.ts index e86c447c2..7bff79055 100644 --- a/lib/release-stamp.ts +++ b/lib/release-stamp.ts @@ -13,6 +13,8 @@ import * as path from 'node:path'; import { parseChangelog } from './changelog-check'; import { effectiveBump, readFragments } from './changelog-fragments'; import { restamp, versionAtRef, type RestampResult } from './restamp'; +import { withAgentNotes } from './agent-notes'; +import { foldSections } from './pr-body-shape'; import { matchesAny, type ShipPolicy } from './ship-policy'; import { buildReceipt } from './tree-receipt'; import { regeneratedAtBase } from '../crew/lib/version-gate-train'; @@ -20,6 +22,23 @@ import { bumpVersion, cmpVersion, fmtVersion, parseVersion, versionWidth } from export const RELEASE_BRANCH = /^release\/(\d+(?:\.\d+){2,3})$/; +/** + * The release notes (R76): one plain line per change the release folds, from each changelog fragment's entries (a + * fragment may hold several `- ` entries): the bold lead sentence, or else the first sentence, with the pull request + * whose squash commit added the fragment (`(#n)` at the end of its subject) when git finds one. + */ +export function releaseNoteLines(root: string, ref: string, fragments: readonly string[]): string[] { + return fragments.flatMap(file => { + const pr = /\(#(\d+)\)\s*$/.exec(git(root, ['log', '-1', '--diff-filter=A', '--format=%s', ref, '--', file]).out)?.[1]; + const text = git(root, ['show', `${ref}:${file}`]).out.replace(/^---\n[\s\S]*?\n---\n/, '').trim(); + return text.split(/\n(?=- )/).map(entry => { + const first = entry.replace(/^- +/, '').replace(/\s+/g, ' ').trim(); + const lead = (/^\*\*(.+?)\*\*/.exec(first)?.[1] ?? first.split(/(?<=[.!?])\s/)[0] ?? '').replace(/\*\*/g, '').trim(); + return lead ? `- ${lead}${pr ? ` (#${pr})` : ''}` : ''; + }).filter(Boolean); + }); +} + export type ReleaseVerdict = { ok: true; version: string; fragments: string[] } | { ok: false; reason: string }; function git(cwd: string, args: string[]): { ok: boolean; out: string; err: string } { @@ -132,16 +151,22 @@ export function openRelease(o: OpenOptions): OpenResult { if (!r.ok) return fail('RELEASE_STAMP_INVALID', `git ${step[0]} failed in the release worktree: ${r.err.split('\n')[0]}`); } const head = git(dir, ['rev-parse', 'HEAD']).out; + const notes = releaseNoteLines(dir, baseSha, git(dir, ['diff', '--name-only', '--diff-filter=D', baseSha, head]).out.split('\n').filter(f => f.endsWith('.md'))); const push = git(dir, ['push', '-q', '--force', 'origin', `HEAD:refs/heads/${branch}`]); if (!push.ok) return fail('RELEASE_STAMP_INVALID', `git push origin ${branch} failed: ${push.err.split('\n')[0]}`); lines.push(`PUSHED: ${branch} ${head}`); - const body = [ + const body = withAgentNotes([ + `v${version} ships ${notes.length} user-visible change${notes.length === 1 ? '' : 's'}, listed one per line under Release notes with the pull request that made each.`, + '', 'It changes only the version, the CHANGELOG and the files generated from them, so it needs no review: merge it once its checks are green.', + '', '## Release notes', '', ...(notes.length ? notes : ['- No user-visible changes.']), '', + ].join('\n'), [ `Release stamp for v${version}, made by \`gstack-release-stamp open\` (\`gstack-restamp --release\`) on origin/${o.base} ${baseSha.slice(0, 12)}: VERSION, the package.json version, the CHANGELOG and the release outputs.`, '', `Folds: ${folded}`, '', `Land it with \`gstack-ship-queue land --pr <this PR> --pin ${head}\` once its checks are green. land checks that this head is exactly the release stamp of its merge base (RELEASE_STAMP_INVALID otherwise), so a release PR needs no /ship receipt.`, - ].join('\n'); + ].join('\n')); + const posted = foldSections(body); const open = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'url,isCrossRepository', '--jq', '[.[] | select(.isCrossRepository | not)][0].url // ""'], dir); - const pr = open.ok && open.out.trim() ? open : gh(['pr', 'create', '--base', o.base, '--head', branch, '--title', `v${version} release`, '--body', body], dir); + const pr = open.ok && open.out.trim() ? open : gh(['pr', 'create', '--base', o.base, '--head', branch, '--title', `v${version} release`, '--body', posted], dir); if (!pr.ok) return fail('RELEASE_STAMP_INVALID', `gh pr create failed (${pr.err.trim().split('\n')[0]}); ${branch} is pushed, so open its PR by hand`); const url = pr.out.trim().split('\n').pop() ?? ''; const n = /\/pull\/(\d+)/.exec(url)?.[1]; diff --git a/lib/result-codes-plain.ts b/lib/result-codes-plain.ts index e2c4497c2..931f5baf8 100644 --- a/lib/result-codes-plain.ts +++ b/lib/result-codes-plain.ts @@ -20,8 +20,13 @@ export const PLAIN_RESULT_CODES = { }, PLAIN_OPENING_REFUSED: { anchor: 'plain-opening-refused', - summary: 'the PR body does not open with one or two plain sentences', - fix: 'start the body with one or two sentences saying what changed and which goal of the project it serves; move codes and records to the Agent notes section at the end', + summary: 'the PR body does not open with a plain paragraph of at most three lines', + fix: 'start the body with up to three plain lines: what changed for a user, why, and anything the reader has to do; move codes and records to the Agent notes section at the end', + }, + PLAIN_BODY_REFUSED: { + anchor: 'plain-body-refused', + summary: 'the PR body, once folded, shows more than three lines or 600 characters before its first fold, leaves text outside a fold, uses a listed word above the Agent notes section, or does not end with that section', + fix: 'keep the opening to three plain lines, put everything else under ## headings (gstack-post folds them), say listed words in everyday words, and let gstack place the receipt in the Agent notes section at the end', }, PLAIN_CHANGELOG_REFUSED: { anchor: 'plain-changelog-refused', diff --git a/lib/ship-policy-keys.ts b/lib/ship-policy-keys.ts index c10bd9282..ec89c1c7e 100644 --- a/lib/ship-policy-keys.ts +++ b/lib/ship-policy-keys.ts @@ -54,6 +54,9 @@ export const PLAN_RECORD_KEY_VERSION = '1.98.0.0'; export const DOCS_ONLY_KEY_VERSION = '1.99.0.0'; /** `land.docs_only_skip` is a field of the older land key, so compatErrors and minimumReader check it by value, as for bump: never. */ export const LAND_DOCS_ONLY_SKIP_KEY_VERSION = '1.99.0.0'; +/** `history: no-rewrite` and `land.merge_commit_paths` are a value and a field of older keys, checked by value like bump: never. */ +export const HISTORY_NO_REWRITE_KEY_VERSION = '1.100.0.0'; +export const LAND_MERGE_COMMIT_PATHS_KEY_VERSION = '1.100.0.0'; export const POLICY_KEY_INTRODUCED: Record<PolicyKey, string> = { bump: '1.91.73.0', queue_mode: '1.91.73.0', release_tool: '1.91.73.0', release_outputs: '1.91.73.0', stamp_paths: '1.91.73.0', changelog: '1.91.73.0', mirror: '1.91.73.0', history: '1.91.73.0', preregistration_shas: '1.91.73.0', stamp_sensitive_gates: '1.91.73.0', diff --git a/lib/ship-policy.ts b/lib/ship-policy.ts index c2e6d98fa..b5731248e 100644 --- a/lib/ship-policy.ts +++ b/lib/ship-policy.ts @@ -23,7 +23,7 @@ import { RESULT_CODES, type ResultCodeName } from './result-codes'; import { reviewErrors, type ReviewPolicy } from './ship-policy-review'; import { READERS_EXPLANATION, readersErrors, type ReadersPolicy } from './ship-policy-readers'; import { cmpVersion, parseVersion } from './version-source'; -import { POLICY_COMPAT_FLOOR, BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION, POLICY_KEY_INTRODUCED, LAND_DOCS_ONLY_SKIP_KEY_VERSION } from './ship-policy-keys'; +import { POLICY_COMPAT_FLOOR, BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION, POLICY_KEY_INTRODUCED, LAND_DOCS_ONLY_SKIP_KEY_VERSION, HISTORY_NO_REWRITE_KEY_VERSION, LAND_MERGE_COMMIT_PATHS_KEY_VERSION } from './ship-policy-keys'; import { placeholderErrors, templateErrors } from './ship-policy-stamps'; import { bookkeepingGlobError, globError } from './ship-policy-bookkeeping'; import { MECHANICAL_EXPLANATION, mechanicalErrors, type MechanicalConstant } from './ship-policy-mechanical'; @@ -34,7 +34,7 @@ export const SHIP_POLICY_SCHEMA = 'https://github.com/garrytan/gstack/docs/ship- export type BumpPolicy = 'patch' | 'ask' | 'never'; export type QueueMode = 'claim-at-open' | 'stamp-at-merge'; -export type HistoryPolicy = 'merge-only' | 'squash-ok'; +export type HistoryPolicy = 'merge-only' | 'squash-ok' | 'no-rewrite'; /** `frozen`: /ship fixes the diff in pass 1, defers unchanged code to the PR body and reviews only the range after; `all`: every finding is fixed now. */ export type ReviewScope = 'frozen' | 'diff-plus-blocking' | 'all'; @@ -56,7 +56,7 @@ export interface ShipPolicy { changelog_fragments: { dir: string; required_checks?: string[] } | null; /** Path of a paired repo to restamp identically (tier 2). */ mirror: string | null; - /** `merge-only` refuses a squash or rebase plan in /ship. */ + /** `merge-only` refuses a squash or rebase plan in /ship; `no-rewrite` refuses a rebase or force-push and lands by squash. */ history: HistoryPolicy; /** Each must be an ancestor of HEAD before push (`gstack-evidence ancestor`). */ preregistration_shas: string[]; @@ -212,7 +212,7 @@ export const POLICY_EXPLANATIONS: Record<PolicyKey, string> = { changelog: 'CHANGELOG path re-headed on a restamp (the PR’s `[Unreleased]` or old-version section moves to the top under the new version). null to skip.', changelog_fragments: '{ dir, required_checks? } or null: a PR adds one unversioned `<dir>/<slug>.md` fragment (optional `bump: minor|major` front matter) instead of an `[Unreleased]` section and leaves VERSION, the manifest version and released CHANGELOG sections at its merge base; the restamp folds every fragment under the allocated version and deletes the files (docs/ship-policy.md#changelog-fragments). `required_checks` lists the check runs or status contexts `train land` requires present and green on a stamp commit. null keeps `[Unreleased]`.', mirror: 'Relative path of a paired repo to restamp identically; writes are confined to it. null to skip.', - history: 'merge-only | squash-ok. merge-only makes /ship refuse a squash or rebase plan.', + history: 'merge-only | squash-ok | no-rewrite. merge-only makes /ship refuse a squash or rebase plan and land with a merge commit; no-rewrite refuses a rebase or force-push of the branch but lands by squash, titled with the PR title (docs/writing-prs.md#the-commit-on-main), and needs min_gstack_version.', preregistration_shas: 'Commits that must be ancestors of HEAD before push (preregistered evals); checked by `gstack-evidence ancestor`.', stamp_sensitive_gates: 'Evidence labels (gstack-evidence --label) that read VERSION or generated bytes; the tree receipt never marks them reusable.', review_scope: 'frozen | diff-plus-blocking | all. frozen (default): /ship Step 9 fixes findings in the diff on pass 1, files blocking findings in code the PR did not change as issues, and later passes read only the range since the previous pass and fix only blocking findings; diff-plus-blocking: the same, but a blocking finding in code the PR did not change is fixed in this PR instead of filed; all: every finding is fixed now (the pre-1.91.249 loop).', @@ -260,18 +260,19 @@ export function installedGstackVersion(): string { */ export function runningGstackVersion(): string { const own = installedGstackVersion(); - const known = [...Object.values(POLICY_KEY_INTRODUCED), BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION].reduce((a, b) => (newer(b, a) ? b : a)); + const known = [...Object.values(POLICY_KEY_INTRODUCED), BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION, HISTORY_NO_REWRITE_KEY_VERSION, LAND_MERGE_COMMIT_PATHS_KEY_VERSION].reduce((a, b) => (newer(b, a) ? b : a)); return parseVersion(own) && !newer(known, own) ? own : known; } /** The newest introducing version among the keys a parsed policy sets: the gstack a crew needs to read it. */ export function minimumReader(raw: Record<string, unknown>): string { return Object.keys(raw).filter((k): k is PolicyKey => POLICY_KEYS.includes(k as PolicyKey)) - .map(k => (k === 'bump' && raw.bump === 'never' ? BUMP_NEVER_KEY_VERSION : k === 'land' && landSkips(raw.land) ? LAND_DOCS_ONLY_SKIP_KEY_VERSION : k === 'train' && genericTrainKeys(raw.train) ? TRAIN_GATES_KEY_VERSION : POLICY_KEY_INTRODUCED[k])).reduce((a, b) => (newer(b, a) ? b : a), POLICY_KEY_INTRODUCED.bump); + .map(k => (k === 'bump' && raw.bump === 'never' ? BUMP_NEVER_KEY_VERSION : k === 'history' && raw.history === 'no-rewrite' ? HISTORY_NO_REWRITE_KEY_VERSION : k === 'land' && landPaths(raw.land) ? LAND_MERGE_COMMIT_PATHS_KEY_VERSION : k === 'land' && landSkips(raw.land) ? LAND_DOCS_ONLY_SKIP_KEY_VERSION : k === 'train' && genericTrainKeys(raw.train) ? TRAIN_GATES_KEY_VERSION : POLICY_KEY_INTRODUCED[k])).reduce((a, b) => (newer(b, a) ? b : a), POLICY_KEY_INTRODUCED.bump); } export interface PolicyError { code: ResultCodeName; path: string; message: string } const landSkips = (land: unknown): boolean => !!land && typeof land === 'object' && 'docs_only_skip' in land; +const landPaths = (land: unknown): boolean => !!land && typeof land === 'object' && 'merge_commit_paths' in land; /** Unknown keys under land and docs_only: ignored with a warning so a newer gstack can add one (docs/ship-policy.md#schema-v1). */ export function policyWarnings(raw: Record<string, unknown>): PolicyWarning[] { @@ -469,7 +470,7 @@ export function validatePolicy(raw: unknown, opts: { gstackVersion?: string } = if (stamps.length) errors.push({ code: 'POLICY_INVALID', path: 'bump', message: `never keeps VERSION on every PR, but ${stamps.join(' and ')} stamps a version at every merge; drop one` }); } oneOf('queue_mode', ['claim-at-open', 'stamp-at-merge']); - oneOf('history', ['merge-only', 'squash-ok']); + oneOf('history', ['merge-only', 'squash-ok', 'no-rewrite']); oneOf('review_scope', ['frozen', 'diff-plus-blocking', 'all']); oneOf('merge', ['direct', 'train']); if ('review_exclude_paths' in obj) excludeErrors(obj.review_exclude_paths, errors); @@ -560,6 +561,9 @@ function compatErrors(obj: Record<string, unknown>, running: string, errors: Pol if (landSkips(obj.land) && !(typeof min === 'string' && !newer(LAND_DOCS_ONLY_SKIP_KEY_VERSION, min))) { errors.push({ code: 'POLICY_INVALID', path: 'land.docs_only_skip', message: `introduced in gstack ${LAND_DOCS_ONLY_SKIP_KEY_VERSION}; set min_gstack_version to ${LAND_DOCS_ONLY_SKIP_KEY_VERSION} or later so an older gstack refuses this policy by name` }); } + for (const [on, path, since] of [[obj.history === 'no-rewrite', 'history', HISTORY_NO_REWRITE_KEY_VERSION], [landPaths(obj.land), 'land.merge_commit_paths', LAND_MERGE_COMMIT_PATHS_KEY_VERSION]] as const) { + if (on && !(typeof min === 'string' && !newer(since, min))) errors.push({ code: 'POLICY_INVALID', path, message: `${path === 'history' ? 'no-rewrite was introduced' : 'introduced'} in gstack ${since}; set min_gstack_version to ${since} or later so an older gstack refuses this policy by name` }); + } if (obj.bump === 'never' && !(typeof min === 'string' && !newer(BUMP_NEVER_KEY_VERSION, min))) { errors.push({ code: 'POLICY_INVALID', path: 'bump', message: `never was introduced in gstack ${BUMP_NEVER_KEY_VERSION}; set min_gstack_version to ${BUMP_NEVER_KEY_VERSION} or later so an older gstack refuses this policy by name` }); } @@ -741,6 +745,7 @@ export function renderEffective(load: LoadedPolicy, opts: { base?: string } = {} export function shipConsequences(policy: ShipPolicy, base: string): string[] { const out: string[] = []; if (policy.history === 'merge-only') out.push('history merge-only: never rebase, squash or force-push this branch; `gstack-ship-policy check-history --plan <merge|squash|rebase>` refuses a rewrite plan (HISTORY_POLICY_VIOLATION)'); + if (policy.history === 'no-rewrite') out.push('history no-rewrite: never rebase or force-push this branch (merge the base in instead); land squashes it into one commit titled with the PR title; `gstack-ship-policy check-history --plan <merge|squash|rebase>` refuses a rebase plan (HISTORY_POLICY_VIOLATION)'); if (policy.queue_mode === 'stamp-at-merge') { out.push(`queue_mode stamp-at-merge: Step 12 items 1-4 are replaced by \`gstack-restamp --next --base ${base} --pr <pr-number> --expect-base <base-sha>\` when this PR is next in the queue (\`--after <predecessor-pr>\` gates ahead in a throwaway worktree when it is not); follow its next: line; claims are ignored`); out.push(`shared merge queue: when a coordinator runs the queue, \`gstack-ship-queue ready --pr <n>\`, \`gate-ahead --after <pr> --pr <n>\` and \`stamp --pr <n> --version <X> --expect-gated <sha> --expect-base <sha>\` replace the calls above; stamp only when your slot is called, send the READY block and the QUEUE_STAMP: line; the coordinator runs \`gstack-ship-queue verify\` (docs/ship-policy.md#run-a-shared-merge-queue)${policy.gate_command ? `; gate command: \`${policy.gate_command}\`` : ''}`); diff --git a/lib/ship-queue-land-direct.ts b/lib/ship-queue-land-direct.ts index 98a0e4ee0..d86ab7a52 100644 --- a/lib/ship-queue-land-direct.ts +++ b/lib/ship-queue-land-direct.ts @@ -8,8 +8,10 @@ * moved past the pin's merge base, the checks at the pin never saw the tree that would land (GST-1316), so land builds * the pin merged onto the base tip and runs the base policy's land.merged_checks there (lib/land-merged-checks.ts; * repo commands, so only under --allow-repo-commands and never under --dry-run), refusing on a conflict or a failure; - * with no list it prints a STALE_BASE: warn line and lands. Then gh pr merge --squash --match-head-commit <pin> with the - * PR title as the commit subject (`--subject "<title> (#<n>)"`, so the checked title is main's history title), a check + * with no list it prints a STALE_BASE: warn line and lands. Then gh pr merge --match-head-commit <pin> with the message + * lib/squash-message.ts builds (subject `<title> (#<n>)`, so the checked title is main's history title, and a body of + * the PR body's opening lines plus the branch's trailers; `--squash`, or `--merge` under history: merge-only or a + * land.merge_commit_paths match), a check * that the merge commit's tree is the pin merged onto that commit's parent (its merged checks rerun when that parent is * neither the base land checked nor in the pin), a land note on refs/notes/gstack-trains, and the lock's release. A * rerun after GitHub merged goes straight to the tree check. @@ -28,9 +30,10 @@ import * as os from 'node:os'; import { activeFreeze, loadReady, persist, rebuildFromNotes, repoIdentity, type FreezeRecord } from '../crew/lib/ship-queue-train-record'; import { bindShippedReceipt } from './ship-receipt-depth'; import { gateAcceptance } from './gate-dispositions'; +import { landMessage, mergeArgs, messageLines, sectionText } from './squash-message'; interface DirectPr { state: string; baseRefName?: string; headRefName: string; headRefOid: string; isCrossRepository: boolean; body: string; title?: string; mergeable?: string; mergeStateStatus?: string; mergeCommit?: { oid: string } | null } -export interface DirectOptions { pr: string; pin: string; dryRun?: boolean; allowRepoCommands?: boolean; breakLock?: boolean; repair?: boolean; now?: () => Date; acceptGateDispositions?: readonly string[] } +export interface DirectOptions { pr: string; pin: string; body?: string; dryRun?: boolean; allowRepoCommands?: boolean; breakLock?: boolean; repair?: boolean; now?: () => Date; acceptGateDispositions?: readonly string[] } /** * The pin's /ship receipt bound to it, and every owner gate disposition the approval store applies at the pin accepted by the @@ -238,7 +241,6 @@ export function landDirect(ctx: QueueContext, o: DirectOptions): StepOutput { if ('failure' in got) return fail(lines, got.failure); held = got.held; } - const subject = info.title?.trim() ? ['--subject', `${info.title.trim()} (#${o.pr})`] : []; const locked = (): StepOutput => { if (held && !git(root, ['fetch', '-q', 'origin', ctx.base]).ok) return fail(lines, { code: 'QUEUE_NOT_READY', message: `cannot re-fetch origin/${ctx.base} under the land lock`, fix: 'fix the fetch, then rerun land' }); const tip = git(root, ['rev-parse', `origin/${ctx.base}`]).out; @@ -260,7 +262,10 @@ export function landDirect(ctx: QueueContext, o: DirectOptions): StepOutput { lines.push(`MERGED_CHECKS: pass tree=${mc.tree} base=${tip} pin=${o.pin.slice(0, 12)} checks: ${checks.join('; ')}`); } } - if (o.dryRun) return { ok: true, run, lines: [...lines, `DRY-RUN: nothing merged (would run gh pr merge ${o.pr} ${policy.history === 'merge-only' ? '--merge' : '--squash'} --match-head-commit ${o.pin}${subject.length ? ` --subject ${JSON.stringify(subject[1])}` : ''})`] }; + const msg = landMessage(root, { pr: o.pr, title: info.title ?? '', prBody: info.body ?? '', mergeBase, pin: o.pin, tip, policy, override: o.body ?? (release ? sectionText(info.body ?? '', 'Release notes') || undefined : undefined) }); + if ('error' in msg) return fail(lines, { code: 'QUEUE_NOT_READY', message: msg.error, fix: 'rewrite the PR title or the opening lines of its body, or pass land --body-file <file> with the plain lines to use; then rerun land' }); + lines.push(...messageLines(msg)); + if (o.dryRun) return { ok: true, run, lines: [...lines, `DRY-RUN: nothing merged (would run gh pr merge ${o.pr} --${msg.method} --match-head-commit ${o.pin} with the SUBJECT and BODY above)`] }; if (o.repair) { if (!rebuildFromNotes(root, remote).fetched) return fail(lines, { code: 'QUEUE_NOT_READY', message: `cannot fetch refs/notes/gstack-trains under the land lock, so the freeze's repair slot cannot be read; nothing merged`, fix: 'fix the fetch, then rerun land' }); const frozen = activeFreeze(keys); @@ -275,10 +280,9 @@ export function landDirect(ctx: QueueContext, o: DirectOptions): StepOutput { lines.push(`REPAIR: #${o.pr}@${o.pin.slice(0, 12)} admitted under the land lock; the freeze stays active until the main backstop is green on a main that contains this merge`); } - const method = policy.history === 'merge-only' ? '--merge' : '--squash'; const lost = held!.set('merging'); if (lost) return fail(lines, lost); - const m = ctx.gh(['pr', 'merge', o.pr, method, '--match-head-commit', o.pin, ...subject]); + const m = ctx.gh(mergeArgs(o.pr, o.pin, msg)); let merge: string | undefined; for (let i = 0; i < (m.ok ? 3 : 1) && !isSha(merge); i++) { if (i) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, pollDelayMs(MIN_POLL_MS)); diff --git a/lib/ship-queue-land.ts b/lib/ship-queue-land.ts index d8232fc6c..aa8f2d6f2 100644 --- a/lib/ship-queue-land.ts +++ b/lib/ship-queue-land.ts @@ -23,6 +23,8 @@ import { matchesAny, type ShipPolicy } from './ship-policy'; import { ciAtHead, loadBasePolicy, type QueueContext, type StepOutput } from './ship-queue'; import { QUEUE_DIR_REL, git, writeJsonAtomic, type QueueFailure } from '../crew/lib/ship-queue-gate'; import { landPlan } from './plan-record'; +import { landMessage, mergeArgs, messageLines } from './squash-message'; +import { withAgentNotes } from './agent-notes'; import { bindShippedReceipt } from './ship-receipt-depth'; import { TERMINAL_STATES, freezeLockCleared, loadReady, loadTrain, rebuildFromNotes, repoIdentity } from '../crew/lib/ship-queue-train-record'; @@ -51,9 +53,10 @@ export interface LandJournal { drift_main?: string; repair_pr?: string; phase: 'locked' | 'stamped' | 'pushed' | 'merged' | 'landed' | 'drift'; } -export interface LandOptions { pr: string; repair?: boolean; dryRun?: boolean; noWait?: boolean; breakLock?: boolean; breakTrainLock?: boolean; allowRepoCommands?: boolean; waitTimeoutMin?: number; now?: () => Date; holder?: string } +export interface LandOptions { pr: string; body?: string; repair?: boolean; dryRun?: boolean; noWait?: boolean; breakLock?: boolean; breakTrainLock?: boolean; allowRepoCommands?: boolean; waitTimeoutMin?: number; now?: () => Date; holder?: string } const fail = (lines: string[], failure: QueueFailure, run: string): StepOutput => ({ ok: false, lines, failure, run }); +const MESSAGE_FIX = 'rewrite the PR title or the opening lines of its body, or pass land --body-file <file> with the plain lines to use; then rerun land'; export const landJournalRel = (pr: string) => `${QUEUE_DIR_REL}/land/${pr}.json`; function readJson<T>(file: string): T | null { try { return JSON.parse(fs.readFileSync(file, 'utf8')) as T; } catch { return null; } } @@ -303,7 +306,7 @@ function repair(ctx: QueueContext, policy: ShipPolicy, j: LandJournal | null, fi pushed = remote[0]!; lines.push(`branch: ${branch} already on origin at ${pushed.slice(0, 12)} (an earlier --repair pushed it); opening or finding its PR`); } - const pr = ctx.gh(['pr', 'create', '--base', ctx.base, '--head', branch, '--title', `Add a changelog entry for changes merged by hand next to #${j.pr}`, '--body', `QUEUE_LAND_DRIFT repair (docs/troubleshooting.md#queue-land-drift). Outside commits: ${outside.join(', ') || 'unknown'}.`]); + const pr = ctx.gh(['pr', 'create', '--base', ctx.base, '--head', branch, '--title', `Add a changelog entry for changes merged by hand next to #${j.pr}`, '--body', withAgentNotes(`Adds a CHANGELOG entry for ${outside.length || 'the'} change${outside.length === 1 ? '' : 's'} merged into ${ctx.base} by hand next to #${j.pr}, so the next release lists ${outside.length === 1 ? 'it' : 'them'}.\n\nMerge it like any other pull request; nothing else to do.\n`, `QUEUE_LAND_DRIFT repair (docs/troubleshooting.md#queue-land-drift). Outside commits: ${outside.join(', ') || 'unknown'}.`)]); const n = /\/pull\/(\d+)/.exec(`${pr.out}\n${pr.err ?? ''}`)?.[1]; if (!n) return fail(lines, { code: 'QUEUE_NOT_READY', message: `gh pr create failed: ${(pr.err ?? pr.out).trim().slice(0, 160)}` }, run); j.repair_pr = n; writeJsonAtomic(file, j); @@ -355,6 +358,10 @@ export function land(ctx: QueueContext, o: LandOptions): StepOutput { if (plan.line) lines.push(plan.line); if (plan.failure) return fail(lines, plan.failure, run); } + const message = (reviewed: string) => { + const tip = git(root, ['rev-parse', `origin/${ctx.base}`]).out; + return landMessage(root, { pr: o.pr, title: info.title ?? '', prBody: info.body ?? '', mergeBase: git(root, ['merge-base', tip, reviewed]).out, pin: reviewed, tip, policy, override: o.body }); + }; if (!j) { const ci = ciAtHead(ctx, pin); lines.push(`CI: ${ci.line}`, ...ci.superseded); @@ -364,7 +371,9 @@ export function land(ctx: QueueContext, o: LandOptions): StepOutput { git(root, ['fetch', '-q', 'origin', ctx.base]); const s = buildStamp(ctx, policy, { pin, baseSha: git(root, ['rev-parse', `origin/${ctx.base}`]).out, pr: o.pr, title: info.title, allowRepoCommands: !!o.allowRepoCommands, now: now() }); if ('code' in s) return fail(lines, s, run); - return { ok: true, run, lines: [...lines, ...s.lines, `STAMP_VERSION: ${s.version}`, `STAMP_TREE: ${s.tree}`, 'DRY-RUN: nothing locked, pushed or merged'] }; + const msg = message(pin); + if ('error' in msg) return fail(lines, { code: 'QUEUE_NOT_READY', message: msg.error, fix: MESSAGE_FIX }, run); + return { ok: true, run, lines: [...lines, ...s.lines, `STAMP_VERSION: ${s.version}`, `STAMP_TREE: ${s.tree}`, ...messageLines(msg), 'DRY-RUN: nothing locked, pushed or merged'] }; } let driftOf: string | undefined; @@ -443,9 +452,12 @@ export function land(ctx: QueueContext, o: LandOptions): StepOutput { const ci = ciAtHead(ctx, j.stamp_commit!); lines.push(`CI: ${ci.line}`); if (!ci.green) return { ok: !ci.line.startsWith('red'), run, lines: [...lines, `NEXT: gstack-pr-wait ${o.pr} --until green && gstack-ship-queue land --pr ${o.pr}`], failure: ci.line.startsWith('red') ? { code: 'QUEUE_NOT_READY', message: `a check failed on the stamp commit ${j.stamp_commit!.slice(0, 12)}` } : undefined }; + const msg = message(j.reviewed_pin); + if ('error' in msg) return fail(lines, { code: 'QUEUE_NOT_READY', message: msg.error, fix: MESSAGE_FIX }, run); + lines.push(...messageLines(msg)); const fm = setLock('merging'); if (fm) return fail(lines, fm, run); - const m = ctx.gh(['pr', 'merge', o.pr, policy.history === 'merge-only' ? '--merge' : '--squash', '--match-head-commit', j.stamp_commit!]); + const m = ctx.gh(mergeArgs(o.pr, j.stamp_commit!, msg)); if (!m.ok) return fail(lines, { code: 'QUEUE_NOT_READY', message: `gh pr merge refused: ${(m.err ?? m.out).trim().slice(0, 200)}` }, run); j.phase = 'merged'; save(); } diff --git a/lib/squash-message.ts b/lib/squash-message.ts new file mode 100644 index 000000000..c577a680e --- /dev/null +++ b/lib/squash-message.ts @@ -0,0 +1,90 @@ +/** + * squash-message — the commit a PR lands as (R76 as amended 2026-11-15, docs/writing-prs.md#the-commit-on-main). The + * subject is the PR title with GitHub's ` (#n)` suffix; the body is the PR body's visible opening (at most three lines + * and 600 characters, the part above the first fold) followed by every distinct `Key: value` trailer the branch's + * commits carry (Co-authored-by, Removed-test and the rest) plus a Co-authored-by for every commit author other than + * the first, so main's one-line log reads as a list of changes and credit survives the squash. A MEDIUM redaction + * finding drops the opening and keeps the trailers; a HIGH one refuses the land. Commits of a stacked parent that already landed are left out (landedStackParent), and the + * whole message passes the shared redaction scan before gh sees it. Every gstack merge (land --pin, the stamping + * land --pr, train land) builds its message here and picks its method with landMethod. + */ +import { spawnSync } from 'node:child_process'; +import type { ShipPolicy } from './ship-policy'; +import { AGENT_NOTES_MARKER } from './agent-notes'; +import { foldSections, unfoldSections, visibleOpening, VISIBLE_CHARS, VISIBLE_LINES } from './pr-body-shape'; +import { scan, type RepoVisibility } from './redact-engine'; +import { landedStackParent } from './ship-receipt'; + +export interface LandMessage { subject: string; body: string; method: 'merge' | 'squash'; why: string; skippedParent: string | null } + +const git = (root: string, args: string[]) => spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 120_000, maxBuffer: 64 * 1024 * 1024 }); + +/** Text wrapped at 72 columns between words, the width git log and GitHub's commit view expect. */ +const wrap = (text: string) => text.split(' ').reduce<string[]>((lines, w) => { const last = lines.at(-1); if (last !== undefined && [...last].length + 1 + [...w].length <= 72) lines[lines.length - 1] = `${last} ${w}`; else lines.push(w); return lines; }, []).join('\n'); + +/** The body's visible opening, at most VISIBLE_LINES lines and VISIBLE_CHARS characters, cut between lines (a first line that alone is too long is cut short), links reduced to their text and each line wrapped at 72. */ +export function openingLines(body: string): string { + const out: string[] = []; + for (const line of visibleOpening(foldSections(body), true).slice(0, VISIBLE_LINES).map(l => l.replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim()).filter(Boolean)) { + if ([...[...out, line].join('\n\n')].length <= VISIBLE_CHARS) { out.push(line); continue; } + if (!out.length) out.push([...line].slice(0, VISIBLE_CHARS - 1).join('') + '…'); + break; + } + return out.map(wrap).join('\n\n'); +} + +/** Every distinct trailer git's own parser finds on the non-merge commits in from..to, oldest first (the first spelling wins); null when git cannot read the range. */ +export function branchTrailers(root: string, from: string, to: string): string[] | null { + const r = git(root, ['log', '--reverse', '--no-merges', '--format=%(trailers:only,unfold)', `${from}..${to}`]); + if (r.status !== 0) return null; + const authors = git(root, ['log', '--reverse', '--no-merges', '--format=%an <%ae>', `${from}..${to}`]); + if (authors.status !== 0) return null; + const others = authors.stdout.split('\n').filter(Boolean).filter((a, _, all) => a !== all[0]).map(a => `Co-authored-by: ${a}`); + const seen = new Map<string, string>(); + for (const line of [...r.stdout.split('\n').map(l => l.trim()), ...others]) if (/^[A-Za-z][A-Za-z0-9-]*: \S/.test(line) && !seen.has(line.toLowerCase())) seen.set(line.toLowerCase(), line); + return [...seen.values()]; +} + +/** merge under history: merge-only or when the PR changes a land.merge_commit_paths pathspec (a commit a receipt points to must stay on the base); squash otherwise. */ +export function landMethod(root: string, policy: Pick<ShipPolicy, 'history' | 'land'>, mergeBase: string, pin: string): { method: 'merge' | 'squash'; why: string } { + if (policy.history === 'merge-only') return { method: 'merge', why: 'history: merge-only' }; + const paths = policy.land?.merge_commit_paths ?? []; + if (!paths.length) return { method: 'squash', why: `history: ${policy.history}` }; + const r = git(root, ['diff', '--name-only', mergeBase, pin, '--', ...paths.map(p => `:(glob)${p}`)]); + if (r.status !== 0) return { method: 'merge', why: 'git could not read the changed paths, so land.merge_commit_paths may match' }; + const hit = r.stdout.split('\n').find(Boolean); + return hit ? { method: 'merge', why: `land.merge_commit_paths matches ${hit}` } : { method: 'squash', why: 'no land.merge_commit_paths match' }; +} + +/** + * The subject and body `gh pr merge` gets. `override` (land --body-file) replaces the opening, never the trailers. + * Refuses (error) when git cannot read the branch's commits or the message holds a HIGH redaction finding. + */ +export function landMessage(root: string, o: { pr: string; title: string; prBody: string; mergeBase: string; pin: string; tip: string; policy: Pick<ShipPolicy, 'history' | 'land'>; override?: string; visibility?: RepoVisibility }): LandMessage | { error: string } { + const parent = landedStackParent(root, { rangeBase: o.mergeBase, reviewed: o.pin, currentBase: o.tip }, ['.']); + const trailers = branchTrailers(root, parent ?? o.mergeBase, o.pin); + if (!o.title.trim()) return { error: `#${o.pr} has no title to use as the commit subject` }; + if (!trailers) return { error: `git cannot read #${o.pr}'s commits ${(parent ?? o.mergeBase).slice(0, 12)}..${o.pin.slice(0, 12)}` }; + const subject = `${o.title.trim()} (#${o.pr})`; + const opening = o.override?.trim() ?? openingLines(o.prBody); + const findings = (text: string) => scan(text, { repoVisibility: o.visibility ?? 'unknown' }).findings; + const high = findings([subject, opening, ...trailers].join('\n\n')).filter(f => f.severity === 'HIGH'); + if (high.length) return { error: `the merge commit message holds ${high.map(f => f.id).join(', ')}; nothing merged` }; + const kept = opening && findings(opening).some(f => f.severity === 'MEDIUM') ? '' : opening; + return { subject, body: [kept, trailers.join('\n')].filter(Boolean).join('\n\n'), ...landMethod(root, o.policy, o.mergeBase, o.pin), skippedParent: parent }; +} + +/** The text of a body's `## <title>` section, or of its fold with that summary; '' when it has none. A release PR's squash body is its Release notes section. */ +export function sectionText(body: string, title: string): string { + const lines = unfoldSections(body).split('\n'); + const start = lines.findIndex(l => l.trim() === `## ${title}`); + if (start < 0) return ''; + const end = lines.findIndex((l, i) => i > start && (/^## /.test(l) || l.trim() === AGENT_NOTES_MARKER)); + return lines.slice(start + 1, end < 0 ? undefined : end).join('\n').trim(); +} + +/** What land prints before it merges: the method (and why), the subject, each body line, and a skipped stacked parent. */ +export const messageLines = (m: LandMessage): string[] => [`METHOD: ${m.method} (${m.why})`, `SUBJECT: ${m.subject}`, ...m.body.split('\n').map(l => `BODY: ${l}`), ...(m.skippedParent ? [`STACK_PARENT: ${m.skippedParent.slice(0, 12)} already landed; its commits' trailers are left out`] : [])]; + +/** The gh pr merge argv for a message: the method, the exact head, and for a merge or squash the subject and body. */ +export const mergeArgs = (pr: string, head: string, m: LandMessage): string[] => ['pr', 'merge', pr, `--${m.method}`, '--match-head-commit', head, '--subject', m.subject, '--body', m.body]; diff --git a/ship/sections/capy-pr.md b/ship/sections/capy-pr.md index e9cd5581a..42923fb17 100644 --- a/ship/sections/capy-pr.md +++ b/ship/sections/capy-pr.md @@ -6,9 +6,13 @@ Read only when Step 19 printed `CAPY_PR: on`. Under Capy a person decides the me the READY report, through a Captain, so the body shows what changed in pictures, why, and who approved what. Guide: `captain.md` beside the Capy `gstack` skill's SKILL.md. -**Order.** The plain opening sentences come first, then `## What changed`, `## Why` and `## Blast radius`, -then the standard sections below. `## Approvals` goes inside the closing Agent notes section, where -`gstack-ship-receipt write` also puts the receipt. Keep `## Summary` to commit themes; do not repeat the captions. +**Order.** The plain opening lines come first (at most three), then `## What changed`, `## Why` and `## Blast radius`, +then the standard sections. `## What changed` holds the pictures below, then the template's themes, without +repeating the captions. gstack-post folds each into a collapsed section. `## Approvals` goes inside the closing +Agent notes section, where `gstack-ship-receipt write` also puts the receipt. A body posted any other way, +Capy's PR tool included, is folded first: pass the output of +`~/.claude/skills/gstack/bin/gstack-post fold --body-file "$PR_BODY_FILE"` (it posts nothing, and exit 4 +with `PLAIN_BODY:` lines means rewrite the body file first). 1. **Pick the evidence:** one to three before/after pairs, highest-signal first. The first is the key image. diff --git a/ship/sections/capy-pr.md.tmpl b/ship/sections/capy-pr.md.tmpl index 41a36d84f..35f3928fc 100644 --- a/ship/sections/capy-pr.md.tmpl +++ b/ship/sections/capy-pr.md.tmpl @@ -4,9 +4,13 @@ Read only when Step 19 printed `CAPY_PR: on`. Under Capy a person decides the me the READY report, through a Captain, so the body shows what changed in pictures, why, and who approved what. Guide: `captain.md` beside the Capy `gstack` skill's SKILL.md. -**Order.** The plain opening sentences come first, then `## What changed`, `## Why` and `## Blast radius`, -then the standard sections below. `## Approvals` goes inside the closing Agent notes section, where -`gstack-ship-receipt write` also puts the receipt. Keep `## Summary` to commit themes; do not repeat the captions. +**Order.** The plain opening lines come first (at most three), then `## What changed`, `## Why` and `## Blast radius`, +then the standard sections. `## What changed` holds the pictures below, then the template's themes, without +repeating the captions. gstack-post folds each into a collapsed section. `## Approvals` goes inside the closing +Agent notes section, where `gstack-ship-receipt write` also puts the receipt. A body posted any other way, +Capy's PR tool included, is folded first: pass the output of +`~/.claude/skills/gstack/bin/gstack-post fold --body-file "$PR_BODY_FILE"` (it posts nothing, and exit 4 +with `PLAIN_BODY:` lines means rewrite the body file first). 1. **Pick the evidence:** one to three before/after pairs, highest-signal first. The first is the key image. diff --git a/ship/sections/pr-body.md b/ship/sections/pr-body.md index 18d7e926c..87bf1c6af 100644 --- a/ship/sections/pr-body.md +++ b/ship/sections/pr-body.md @@ -80,15 +80,19 @@ Run `[ "${GSTACK_CAPY:-}" = 1 ] && echo 'CAPY_PR: on' || echo 'CAPY_PR: off'`. O lead; `## Approvals` goes into the Agent notes. On `CAPY_PR: off`, skip it. The PR/MR body should contain these sections (never reuse a prior run's body). The front is for people, -the end is for machines: the body opens with one or two plain sentences (what changed for someone using -the project, and which goal from the project's README it serves; with no stated goals, the user-visible -benefit), with no heading above them. Tracker codes, receipts, approval and Plan lines, review-loop and -gate lines and every other machine-read line go only in the closing Agent notes section, never above it. +the end is for machines (docs/writing-prs.md): the body opens with at most three plain lines and 600 +characters, with no heading above them: what changed for someone using the project, why (the README goal it +serves, or the user-visible benefit), and anything the reader has to do. Everything else goes under a `## ` +heading, which gstack-post folds into a collapsed section on publish, each thing said once, with long logs +and review output linked rather than pasted. Tracker codes, receipts, approval and Plan lines, review-loop +and gate lines and every other machine-read line go only in the closing Agent notes section, never above it, +and so do in-house words such as the ones docs/writing-prs.md lists. ``` -<One or two plain sentences: what changed for a user, and the README goal it serves.> +<Up to three plain lines, 600 characters in all: what changed for a user; why (the README goal it +serves); and what the reader has to do, or "Nothing to do".> -## Summary +## What changed <Open with the problem in the user's words (what they hit, saw or asked), then the fix and what they get now; themes from `git log origin/<base>..HEAD --oneline` after that, minus VERSION/CHANGELOG bookkeeping. Never an inventory or a commit list. BAD: "Adds @@ -102,6 +106,7 @@ files, hosts) and the one fact that makes that safe, with the rung of the eviden ladder the fact reached (file:line read, walked failure path, script ran, repro).> ## Test Coverage +<Only when Step 7 ran or found gaps; otherwise omit (the Tests section says what ran).> <coverage diagram from Step 7, or "All new code paths have test coverage."> <If Step 7 ran: "Tests: {before} → {after} (+{delta} new)"> <If Step 7 ran: "Coverage: {X}% value-weighted ({Y}% including {W} weakly covered paths)"> @@ -114,10 +119,10 @@ details for cards whose file type has no known comment syntax.> ZERO-RUN lane never reaches this body unresolved.> ## Pre-Landing Review -<findings from Step 9 code review, or "No issues found."; then Step 9.4's `REVIEW_LOOP:` line.> -<Each `Ruled note: …` line `gstack-approvals rulings` prints, verbatim: a finding the owner ruled a disclosed note, +<findings from Step 9 code review in plain words, or "No issues found."; link long review output instead of pasting it.> +<In the Agent notes section, never here: Step 9.4's `REVIEW_LOOP:` line, each `Ruled note: …` line `gstack-approvals rulings` prints, verbatim: a finding the owner ruled a disclosed note, with its ruler and reason; each `Gate disposition: …` line `gstack-approvals dispositions` prints, verbatim; finish's `MECHANICAL: x` as `Mechanical retake: x` and its `UID_SIDECAR: x (beside y)` as `Godot UID sidecar: x (beside y)`. `gstack-ship-receipt write --body` refuses a body missing one.> -<Gate edits: Step 9's latest `Gate edits:` line verbatim — `none detected (...)`, +<Gate edits: in the Agent notes section, Step 9's latest `Gate edits:` line verbatim — `none detected (...)`, `N listed, M read, K findings — J kept, R restored, O open`, `partial (...)` or `UNAVAILABLE — ...`; never `none detected` for partial or UNAVAILABLE. Under it, each kept finding's `gate`, path and `reason`, and each open finding's `gate` and path. @@ -185,15 +190,13 @@ word for word as Step 14.5 saved it in `.gstack/tmp/docs-audit.json`: the receipt write below refuses (`DOCS_AUDIT_BLOCKED`) when the body lacks it.> <Always include the status and reviewed scope: updated, current, or blocked with the actual user's named risk exception. Never omit this section or reuse another invocation's audit.> -## Test plan -- [x] <Each executed test lane's command>: <observed passing summary> - -🤖 Generated with [Claude Code](https://claude.com/claude-code) +## Tests +- [x] <Each executed test command>: <observed passing summary> <!-- gstack:agent-notes --> <details><summary>Agent notes</summary> -<Machine-read lines, last: `Refs <issue codes>`, the `## Approvals` output (Capy) with its Plan line, +<Machine-read lines, last: "🤖 Generated with Claude Code", `Refs <issue codes>`, the `## Approvals` output (Capy) with its Plan line, and the Pre-Landing Review section's `REVIEW_LOOP:`, `Gate edits:`, `Ruled note:`, `Gate disposition:`, `Review-loop exception:` and exception lines. `gstack-ship-receipt write` adds the receipt here; never type it.> @@ -209,8 +212,9 @@ tool-attributed fences (` ```codex-review ` / ` ```review-bot `) so the scanner WARN-degrades the example credentials those tools quote instead of blocking the PR (a live-format credential inside the fence still blocks). -Write the body from above into two private files: the first through the -`## Documentation` heading line, the second from `## Test plan` on, ending with the Agent notes section. +Write the body from above into two private files, with plain `## ` headings (gstack-post folds them; +never write `<details>` by hand): the first through the `## Documentation` heading line, the second +from `## Tests` on, ending with the Agent notes section. ```bash _GT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp" @@ -232,8 +236,8 @@ PR_BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/gstack-pr-body.XXXXXX") || { echo "ERROR: BODY_TOP_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<body-top-file-name>" BODY_REST_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<body-rest-file-name>" [ -s "$BODY_TOP_FILE" ] && [ -s "$BODY_REST_FILE" ] || { echo "Not composed: $BODY_TOP_FILE or $BODY_REST_FILE is empty, so the body was never written. Write both, then rerun." >&2; exit 1; } -~/.claude/skills/gstack/bin/gstack-prose-lint "$BODY_TOP_FILE" --sections 'Why,Summary,Blast radius' --gate >&2 || { echo "Not composed: fix what gstack-prose-lint printed above (a PROSE: line is a sentence to rewrite in the draft; a usage line means the draft lost a heading), then rerun." >&2; exit 1; } -~/.claude/skills/gstack/bin/gstack-plain-title check --body-file "$BODY_TOP_FILE" >&2 || { echo "Not composed: rewrite the opening the PLAIN_TITLE: lines above name (one or two plain sentences, no heading or code above them), then rerun." >&2; exit 1; } +~/.claude/skills/gstack/bin/gstack-prose-lint "$BODY_TOP_FILE" --sections 'Why,What changed,Blast radius' --gate >&2 || { echo "Not composed: fix what gstack-prose-lint printed above (a PROSE: line is a sentence to rewrite in the draft; a usage line means the draft lost a heading), then rerun." >&2; exit 1; } +~/.claude/skills/gstack/bin/gstack-plain-title check --body-file "$BODY_TOP_FILE" >&2 || { echo "Not composed: rewrite what the PLAIN_TITLE: and PLAIN_BODY: lines above name (at most three plain lines before the first ## heading, no listed word above the Agent notes section), then rerun." >&2; exit 1; } { awk 1 "$BODY_TOP_FILE" && cat -- "$DOCS_SECTION_FILE" && echo && awk 1 "$BODY_REST_FILE"; } > "$PR_BODY_FILE" || exit 1 rm -f "$BODY_TOP_FILE" "$BODY_REST_FILE" echo "PR_BODY_FILE: $PR_BODY_FILE" @@ -325,8 +329,9 @@ With open gate findings the same command carries `--draft` before `--title-file` Branch on the exit code of either block: - **0** posted. Remove `$PR_BODY_FILE` and the title file. -- **4** `PLAIN_TITLE_REFUSED`: nothing was posted, body included. Rewrite the title file's front the way - each `PLAIN_TITLE:` line says (Step 18 item 5) and rerun the same block. +- **4** nothing was posted, title and body checked in one pass. For each `PLAIN_TITLE:` line, rewrite the + title file's front the way it says (Step 18 item 5); for each `PLAIN_BODY:` line, rewrite `$PR_BODY_FILE` + the way it says (docs/troubleshooting.md#plain-body-refused). Then rerun the same block. - **1** HIGH finding: BLOCKED — do not publish. Rotate and redact at the source, then compose fresh files. - **2** MEDIUM findings, printed as `RULE:` lines with a `TOKEN:`. AskUserQuestion per diff --git a/ship/sections/pr-body.md.tmpl b/ship/sections/pr-body.md.tmpl index af7ed820e..c0bfb63ad 100644 --- a/ship/sections/pr-body.md.tmpl +++ b/ship/sections/pr-body.md.tmpl @@ -71,15 +71,19 @@ Run `[ "${GSTACK_CAPY:-}" = 1 ] && echo 'CAPY_PR: on' || echo 'CAPY_PR: off'`. O lead; `## Approvals` goes into the Agent notes. On `CAPY_PR: off`, skip it. The PR/MR body should contain these sections (never reuse a prior run's body). The front is for people, -the end is for machines: the body opens with one or two plain sentences (what changed for someone using -the project, and which goal from the project's README it serves; with no stated goals, the user-visible -benefit), with no heading above them. Tracker codes, receipts, approval and Plan lines, review-loop and -gate lines and every other machine-read line go only in the closing Agent notes section, never above it. +the end is for machines (docs/writing-prs.md): the body opens with at most three plain lines and 600 +characters, with no heading above them: what changed for someone using the project, why (the README goal it +serves, or the user-visible benefit), and anything the reader has to do. Everything else goes under a `## ` +heading, which gstack-post folds into a collapsed section on publish, each thing said once, with long logs +and review output linked rather than pasted. Tracker codes, receipts, approval and Plan lines, review-loop +and gate lines and every other machine-read line go only in the closing Agent notes section, never above it, +and so do in-house words such as the ones docs/writing-prs.md lists. ``` -<One or two plain sentences: what changed for a user, and the README goal it serves.> +<Up to three plain lines, 600 characters in all: what changed for a user; why (the README goal it +serves); and what the reader has to do, or "Nothing to do".> -## Summary +## What changed <Open with the problem in the user's words (what they hit, saw or asked), then the fix and what they get now; themes from `git log origin/<base>..HEAD --oneline` after that, minus VERSION/CHANGELOG bookkeeping. Never an inventory or a commit list. BAD: "Adds @@ -93,6 +97,7 @@ files, hosts) and the one fact that makes that safe, with the rung of the eviden ladder the fact reached (file:line read, walked failure path, script ran, repro).> ## Test Coverage +<Only when Step 7 ran or found gaps; otherwise omit (the Tests section says what ran).> <coverage diagram from Step 7, or "All new code paths have test coverage."> <If Step 7 ran: "Tests: {before} → {after} (+{delta} new)"> <If Step 7 ran: "Coverage: {X}% value-weighted ({Y}% including {W} weakly covered paths)"> @@ -105,10 +110,10 @@ details for cards whose file type has no known comment syntax.> ZERO-RUN lane never reaches this body unresolved.> ## Pre-Landing Review -<findings from Step 9 code review, or "No issues found."; then Step 9.4's `REVIEW_LOOP:` line.> -<Each `Ruled note: …` line `gstack-approvals rulings` prints, verbatim: a finding the owner ruled a disclosed note, +<findings from Step 9 code review in plain words, or "No issues found."; link long review output instead of pasting it.> +<In the Agent notes section, never here: Step 9.4's `REVIEW_LOOP:` line, each `Ruled note: …` line `gstack-approvals rulings` prints, verbatim: a finding the owner ruled a disclosed note, with its ruler and reason; each `Gate disposition: …` line `gstack-approvals dispositions` prints, verbatim; finish's `MECHANICAL: x` as `Mechanical retake: x` and its `UID_SIDECAR: x (beside y)` as `Godot UID sidecar: x (beside y)`. `gstack-ship-receipt write --body` refuses a body missing one.> -<Gate edits: Step 9's latest `Gate edits:` line verbatim — `none detected (...)`, +<Gate edits: in the Agent notes section, Step 9's latest `Gate edits:` line verbatim — `none detected (...)`, `N listed, M read, K findings — J kept, R restored, O open`, `partial (...)` or `UNAVAILABLE — ...`; never `none detected` for partial or UNAVAILABLE. Under it, each kept finding's `gate`, path and `reason`, and each open finding's `gate` and path. @@ -176,15 +181,13 @@ word for word as Step 14.5 saved it in `.gstack/tmp/docs-audit.json`: the receipt write below refuses (`DOCS_AUDIT_BLOCKED`) when the body lacks it.> <Always include the status and reviewed scope: updated, current, or blocked with the actual user's named risk exception. Never omit this section or reuse another invocation's audit.> -## Test plan -- [x] <Each executed test lane's command>: <observed passing summary> - -🤖 Generated with [Claude Code](https://claude.com/claude-code) +## Tests +- [x] <Each executed test command>: <observed passing summary> <!-- gstack:agent-notes --> <details><summary>Agent notes</summary> -<Machine-read lines, last: `Refs <issue codes>`, the `## Approvals` output (Capy) with its Plan line, +<Machine-read lines, last: "🤖 Generated with Claude Code", `Refs <issue codes>`, the `## Approvals` output (Capy) with its Plan line, and the Pre-Landing Review section's `REVIEW_LOOP:`, `Gate edits:`, `Ruled note:`, `Gate disposition:`, `Review-loop exception:` and exception lines. `gstack-ship-receipt write` adds the receipt here; never type it.> @@ -200,8 +203,9 @@ tool-attributed fences (` ```codex-review ` / ` ```review-bot `) so the scanner WARN-degrades the example credentials those tools quote instead of blocking the PR (a live-format credential inside the fence still blocks). -Write the body from above into two private files: the first through the -`## Documentation` heading line, the second from `## Test plan` on, ending with the Agent notes section. +Write the body from above into two private files, with plain `## ` headings (gstack-post folds them; +never write `<details>` by hand): the first through the `## Documentation` heading line, the second +from `## Tests` on, ending with the Agent notes section. {{FREE_TEXT_FILE:BODY_TOP_FILE=pr-body-top:BODY_REST_FILE=pr-body-rest}} @@ -215,8 +219,8 @@ PR_BODY_FILE=$(mktemp "${TMPDIR:-/tmp}/gstack-pr-body.XXXXXX") || { echo "ERROR: BODY_TOP_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<body-top-file-name>" BODY_REST_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<body-rest-file-name>" [ -s "$BODY_TOP_FILE" ] && [ -s "$BODY_REST_FILE" ] || { echo "Not composed: $BODY_TOP_FILE or $BODY_REST_FILE is empty, so the body was never written. Write both, then rerun." >&2; exit 1; } -~/.claude/skills/gstack/bin/gstack-prose-lint "$BODY_TOP_FILE" --sections 'Why,Summary,Blast radius' --gate >&2 || { echo "Not composed: fix what gstack-prose-lint printed above (a PROSE: line is a sentence to rewrite in the draft; a usage line means the draft lost a heading), then rerun." >&2; exit 1; } -~/.claude/skills/gstack/bin/gstack-plain-title check --body-file "$BODY_TOP_FILE" >&2 || { echo "Not composed: rewrite the opening the PLAIN_TITLE: lines above name (one or two plain sentences, no heading or code above them), then rerun." >&2; exit 1; } +~/.claude/skills/gstack/bin/gstack-prose-lint "$BODY_TOP_FILE" --sections 'Why,What changed,Blast radius' --gate >&2 || { echo "Not composed: fix what gstack-prose-lint printed above (a PROSE: line is a sentence to rewrite in the draft; a usage line means the draft lost a heading), then rerun." >&2; exit 1; } +~/.claude/skills/gstack/bin/gstack-plain-title check --body-file "$BODY_TOP_FILE" >&2 || { echo "Not composed: rewrite what the PLAIN_TITLE: and PLAIN_BODY: lines above name (at most three plain lines before the first ## heading, no listed word above the Agent notes section), then rerun." >&2; exit 1; } { awk 1 "$BODY_TOP_FILE" && cat -- "$DOCS_SECTION_FILE" && echo && awk 1 "$BODY_REST_FILE"; } > "$PR_BODY_FILE" || exit 1 rm -f "$BODY_TOP_FILE" "$BODY_REST_FILE" echo "PR_BODY_FILE: $PR_BODY_FILE" @@ -308,8 +312,9 @@ With open gate findings the same command carries `--draft` before `--title-file` Branch on the exit code of either block: - **0** posted. Remove `$PR_BODY_FILE` and the title file. -- **4** `PLAIN_TITLE_REFUSED`: nothing was posted, body included. Rewrite the title file's front the way - each `PLAIN_TITLE:` line says (Step 18 item 5) and rerun the same block. +- **4** nothing was posted, title and body checked in one pass. For each `PLAIN_TITLE:` line, rewrite the + title file's front the way it says (Step 18 item 5); for each `PLAIN_BODY:` line, rewrite `$PR_BODY_FILE` + the way it says (docs/troubleshooting.md#plain-body-refused). Then rerun the same block. - **1** HIGH finding: BLOCKED — do not publish. Rotate and redact at the source, then compose fresh files. - **2** MEDIUM findings, printed as `RULE:` lines with a `TOKEN:`. AskUserQuestion per diff --git a/test/docsync-report-interface.test.ts b/test/docsync-report-interface.test.ts index 821094e80..99ebd8058 100644 --- a/test/docsync-report-interface.test.ts +++ b/test/docsync-report-interface.test.ts @@ -73,7 +73,7 @@ mock.module(path.join(root, 'test/helpers/session-runner.ts'), () => ({ } else { const prBody = fs.readFileSync(path.join(fixture.skills, 'ship/sections/pr-body.md'), 'utf8'); const start = prBody.indexOf('## Documentation'); - const end = prBody.indexOf('## Test plan', start); + const end = prBody.indexOf('## Tests', start); expect(start).toBeGreaterThan(0); expect(end).toBeGreaterThan(start); expect(phase).toContain(prBody.slice(start, end)); diff --git a/test/gate-integrity-templates.test.ts b/test/gate-integrity-templates.test.ts index 3a9dd3018..f0d8b4c55 100644 --- a/test/gate-integrity-templates.test.ts +++ b/test/gate-integrity-templates.test.ts @@ -94,7 +94,7 @@ test('/ship Step 16 stage 5 reports each gate finding with disposition, reason a test('/ship PR body carries the Gate edits line and per-lane counts, and an open finding keeps a new PR a draft', () => { const body = read('ship/sections/pr-body.md.tmpl'); - const skeleton = between(body, '## Summary', '#### Compose the body'); + const skeleton = between(body, '## What changed', '#### Compose the body'); const coverage = between(skeleton, '## Test Coverage', '## Pre-Landing Review'); expectTokens(coverage, ['Tests ran: <lane> N', 'Tests ran: <lane> count unavailable', '`tests_ran`'], 'PR body Test Coverage'); const review = between(skeleton, '## Pre-Landing Review', '## Exploratory QA'); diff --git a/test/gstack-post.test.ts b/test/gstack-post.test.ts index 56f0440c1..9ab7dd553 100644 --- a/test/gstack-post.test.ts +++ b/test/gstack-post.test.ts @@ -13,6 +13,7 @@ import * as path from "node:path"; import { EXIT, attributionCallout, mergeBodySections, runPost, type PostEnv } from "../lib/gstack-post"; import { extractReceipt, orderReceipt, placeReceipt, receiptRuns } from "../lib/ship-receipt"; import type { ShipReceipt } from "../lib/headless-artifacts"; +import { foldSections, unfoldSections } from "../lib/pr-body-shape"; interface Call { cmd: string; args: string[]; input?: string } @@ -348,7 +349,7 @@ describe("gstack-post owns the redaction scan", () => { ); for (const [name, text, needle] of holds) { const { code, phones, f } = post(text); - expect([name, phones, code]).toEqual([name, [`RULE: pii.phone.e164 LINE: ${lineOf(text, needle)} PART: body`], EXIT.confirm]); + expect([name, phones, code]).toEqual([name, [`RULE: pii.phone.e164 LINE: ${lineOf(foldSections(text), needle)} PART: body`], EXIT.confirm]); expect(f.posts()).toEqual([]); } }); @@ -494,23 +495,33 @@ describe("gstack-post pr-body merges the PR body by section", () => { test("a first-section-only body keeps the other sections and the receipt; a same-titled section is replaced in place; new sections are appended", () => { const f = withBody(CURRENT, { "/b": "## What Changed\n\n- the new summary\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], f)).toBe(EXIT.posted); - expect(sent(f).input).toBe(RECEIPT("aaaa") + "\n## What Changed\n\n- the new summary\n\n## Why\n\nBecause.\n\n## Approvals\n\n- owner: do it\n"); + expect(sent(f).input).toBe(foldSections(RECEIPT("aaaa") + "\n## What Changed\n\n- the new summary\n\n## Why\n\nBecause.\n\n## Approvals\n\n- owner: do it\n")); expect(f.stderr()).toBe("gstack-post: pr-body merged by section: replaced What changed; kept ship receipt, Why, Approvals; added none\n"); expect(f.calls.find(c => c.cmd === "gh" && c.args[1] === "view")!.args).toEqual(["pr", "view", "5", "--json", "body", "--jq", ".body"]); const receipt = withBody(CURRENT, { "/b": RECEIPT("bbbb") }); expect(run(["pr-body", "5", "--body-file", "/b"], receipt)).toBe(EXIT.posted); - expect(sent(receipt).input).toBe(CURRENT.replace(RECEIPT("aaaa"), RECEIPT("bbbb"))); + expect(sent(receipt).input).toBe(foldSections(CURRENT.replace(RECEIPT("aaaa"), RECEIPT("bbbb")))); expect(receipt.stderr()).toBe("gstack-post: pr-body merged by section: replaced ship receipt; kept What changed, Why, Approvals; added none\n"); const added = withBody(CURRENT, { "/b": "## Why\n\nStill because.\n\n## Tests\n\n- one\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], added)).toBe(EXIT.posted); - expect(sent(added).input).toBe(RECEIPT("aaaa") + "\n## What changed\n\n- the old summary\n\n## Why\n\nStill because.\n\n## Approvals\n\n- owner: do it\n\n## Tests\n\n- one\n"); + expect(sent(added).input).toBe(foldSections(RECEIPT("aaaa") + "\n## What changed\n\n- the old summary\n\n## Why\n\nStill because.\n\n## Approvals\n\n- owner: do it\n\n## Tests\n\n- one\n")); expect(added.stderr()).toBe("gstack-post: pr-body merged by section: replaced Why; kept ship receipt, What changed, Approvals; added Tests\n"); const fenced = withBody("## Notes\n\n```md\n## not a heading\n```\n\n## Why\n\nold\n", { "/b": "## Why\n\nnew\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], fenced)).toBe(EXIT.posted); - expect(sent(fenced).input).toBe("## Notes\n\n```md\n## not a heading\n```\n\n## Why\n\nnew\n"); + expect(sent(fenced).input).toBe(foldSections("## Notes\n\n```md\n## not a heading\n```\n\n## Why\n\nnew\n")); + }); + + // Value: protects=re-posting an already-folded body (the live body, or gstack-post fold output) replaces each section once instead of keeping the + // old sections beside it; fails_when=the incoming folds are read as leading text and every section ends up twice; why_new=GST-2737 review (granted fix-check) + test("a folded incoming body replaces the folded sections it names; nothing is duplicated", () => { + const current = foldSections("Opening.\n\n## Tests\n\nOld\n\n## Why\n\nBecause.\n"); + const f = withBody(current, { "/b": foldSections("Opening.\n\n## Tests\n\nNew\n") }); + expect(run(["pr-body", "5", "--body-file", "/b"], f)).toBe(EXIT.posted); + expect(sent(f).input).toBe(foldSections("Opening.\n\n## Tests\n\nNew\n\n## Why\n\nBecause.\n")); + expect(f.stderr()).toContain("replaced leading text, Tests; kept Why"); }); // Value: protects=a fence closes only on a run of its own character at least as long as the opener with nothing after it, so a ``` line inside a @@ -522,31 +533,31 @@ describe("gstack-post pr-body merges the PR body by section", () => { const long = "## Notes\n\n````md\n```\n## Tests\nfake\n```\n````\n\n## Tests\n\nold\n"; const four = withBody(long, { "/b": "## Tests\n\nnew\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], four)).toBe(EXIT.posted); - expect(sent(four).input).toBe("## Notes\n\n````md\n```\n## Tests\nfake\n```\n````\n\n## Tests\n\nnew\n"); + expect(sent(four).input).toBe(foldSections("## Notes\n\n````md\n```\n## Tests\nfake\n```\n````\n\n## Tests\n\nnew\n")); expect(four.stderr()).toBe("gstack-post: pr-body merged by section: replaced Tests; kept Notes; added none\n"); const info = withBody("## Notes\n\n```sh\n```js\n## Tests\n~~~\n```\n\n## Tests\n\nold\n", { "/b": "## Tests\n\nnew\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], info)).toBe(EXIT.posted); - expect(sent(info).input).toBe("## Notes\n\n```sh\n```js\n## Tests\n~~~\n```\n\n## Tests\n\nnew\n"); + expect(sent(info).input).toBe(foldSections("## Notes\n\n```sh\n```js\n## Tests\n~~~\n```\n\n## Tests\n\nnew\n")); const unclosed = "```gstack-ship-receipt\nSHIP_RECEIPT: pr=5 head=aaaa\n\n## Summary\n\nold\n\n## Approvals\n\n- owner: do it\n"; const open = withBody(unclosed, { "/b": RECEIPT("bbbb") + "\n## Summary\n\nnew\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], open)).toBe(EXIT.posted); - expect(sent(open).input).toBe(RECEIPT("bbbb") + "\n" + unclosed + "\n## Summary\n\nnew\n"); + expect(sent(open).input).toBe(foldSections(RECEIPT("bbbb") + "\n" + unclosed + "\n## Summary\n\nnew\n")); expect(open.stderr()).toBe("gstack-post: pr-body merged by section: replaced none; kept unclosed receipt fence; added ship receipt, Summary\n"); const prose = withBody(unclosed, { "/b": "Updated introduction\n\n## Summary\n\nnew\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], prose)).toBe(EXIT.posted); - expect(sent(prose).input).toBe("Updated introduction\n\n" + unclosed + "\n## Summary\n\nnew\n"); + expect(sent(prose).input).toBe(foldSections("Updated introduction\n\n" + unclosed + "\n## Summary\n\nnew\n")); const inside = withBody("Intro\n\n## Notes\n\n" + unclosed, { "/b": "New intro\n\n## Notes\n\nnew notes\n\n## Approvals\n\n- owner: still\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], inside)).toBe(EXIT.posted); - expect(sent(inside).input).toBe("New intro\n\n## Notes\n\nnew notes\n\n" + unclosed + "\n## Approvals\n\n- owner: still\n"); + expect(sent(inside).input).toBe(foldSections("New intro\n\n## Notes\n\nnew notes\n\n" + unclosed + "\n## Approvals\n\n- owner: still\n")); expect(inside.stderr()).toBe("gstack-post: pr-body merged by section: replaced leading text, Notes; kept unclosed receipt fence; added Approvals\n"); const after = withBody(RECEIPT("aaaa") + "\n## Why\n\nold\n\n" + unclosed, { "/b": RECEIPT("bbbb") + "\n## Why\n\nnew\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], after)).toBe(EXIT.posted); - expect(sent(after).input).toBe(RECEIPT("bbbb") + "\n## Why\n\nnew\n\n" + unclosed); + expect(sent(after).input).toBe(foldSections(RECEIPT("bbbb") + "\n## Why\n\nnew\n\n" + unclosed)); expect(after.stderr()).toBe("gstack-post: pr-body merged by section: replaced ship receipt, Why; kept unclosed receipt fence; added none\n"); }); @@ -560,18 +571,18 @@ describe("gstack-post pr-body merges the PR body by section", () => { const intro = "Draft intro from gh pr create, long enough to need truncation in the summary line\nsecond line\n\n"; const stale = withBody(intro + CURRENT, { "/b": RECEIPT("bbbb") + "\n## What changed\n\n- new\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], stale)).toBe(EXIT.posted); - expect(sent(stale).input).toBe(intro + RECEIPT("bbbb") + "\n## What changed\n\n- new\n\n## Why\n\nBecause.\n\n## Approvals\n\n- owner: do it\n"); + expect(sent(stale).input).toBe(foldSections(intro + RECEIPT("bbbb") + "\n## What changed\n\n- new\n\n## Why\n\nBecause.\n\n## Approvals\n\n- owner: do it\n")); expect(stale.stderr()).toBe("gstack-post: pr-body merged by section: replaced ship receipt, What changed; kept leading text, Why, Approvals; added none\n"); const between = withBody(RECEIPT("aaaa") + "Old note under the receipt\n\n## What changed\n\n- old\n", { "/b": RECEIPT("bbbb") + "## What changed\n\n- new\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], between)).toBe(EXIT.posted); - expect(sent(between).input).toBe(RECEIPT("bbbb") + "\n## What changed\n\n- new\n"); + expect(sent(between).input).toBe(foldSections(RECEIPT("bbbb") + "\n## What changed\n\n- new\n")); expect(between.stderr()).toBe("gstack-post: pr-body merged by section: replaced ship receipt, What changed; kept none; added none; dropped trailing text (\"Old note under the receipt\")\n"); const own = withBody("Stale intro\n\n" + RECEIPT("aaaa") + "Stale note\n\n## Why\n\nold\n", { "/b": "Fresh intro\n\n" + RECEIPT("bbbb") + "Fresh note\n\n## Why\n\nnew\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], own)).toBe(EXIT.posted); - expect(sent(own).input).toBe("Fresh intro\n\n" + RECEIPT("bbbb") + "\nFresh note\n\n## Why\n\nnew\n"); - expect(mergeBodySections(sent(own).input!, "Fresh intro\n\n" + RECEIPT("bbbb") + "Fresh note\n\n## Why\n\nnew\n").body).toBe(sent(own).input!); + expect(sent(own).input).toBe(foldSections("Fresh intro\n\n" + RECEIPT("bbbb") + "\nFresh note\n\n## Why\n\nnew\n")); + expect(foldSections(mergeBodySections(unfoldSections(sent(own).input!), "Fresh intro\n\n" + RECEIPT("bbbb") + "Fresh note\n\n## Why\n\nnew\n").body)).toBe(sent(own).input!); expect(own.stderr()).toBe("gstack-post: pr-body merged by section: replaced leading text, ship receipt, trailing text, Why; kept none; added none\n"); }); @@ -585,17 +596,17 @@ describe("gstack-post pr-body merges the PR body by section", () => { const PREAMBLE = BADGE + "\nThis PR stops the login retry from looping.\n\n"; const first = withBody(PREAMBLE + "## What changed\n\n- the old summary\n\n## Why\n\nBecause.\n", { "/b": RECEIPT("bbbb") + "\n## What changed\n\n- new\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], first)).toBe(EXIT.posted); - expect(sent(first).input).toBe(PREAMBLE + RECEIPT("bbbb") + "\n## What changed\n\n- new\n\n## Why\n\nBecause.\n"); + expect(sent(first).input).toBe(foldSections(PREAMBLE + RECEIPT("bbbb") + "\n## What changed\n\n- new\n\n## Why\n\nBecause.\n")); expect(first.stderr()).toBe("gstack-post: pr-body merged by section: replaced What changed; kept leading text, Why; added ship receipt\n"); const again = withBody(sent(first).input!, { "/b": RECEIPT("cccc") + "\n## What changed\n\n- newer\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], again)).toBe(EXIT.posted); - expect(sent(again).input).toBe(PREAMBLE + RECEIPT("cccc") + "\n## What changed\n\n- newer\n\n## Why\n\nBecause.\n"); + expect(sent(again).input).toBe(foldSections(PREAMBLE + RECEIPT("cccc") + "\n## What changed\n\n- newer\n\n## Why\n\nBecause.\n")); expect(again.stderr()).toBe("gstack-post: pr-body merged by section: replaced ship receipt, What changed; kept leading text, Why; added none\n"); const trailing = withBody(CURRENT + "\n" + BADGE, { "/b": RECEIPT("bbbb") + "\n## Approvals\n\n- owner: ship it\n\n## Tests\n\n- one\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], trailing)).toBe(EXIT.posted); - expect(sent(trailing).input).toBe(RECEIPT("bbbb") + "\n## What changed\n\n- the old summary\n\n## Why\n\nBecause.\n\n## Approvals\n\n- owner: ship it\n\n## Tests\n\n- one\n\n" + BADGE); + expect(sent(trailing).input).toBe(foldSections(RECEIPT("bbbb") + "\n## What changed\n\n- the old summary\n\n## Why\n\nBecause.\n\n## Approvals\n\n- owner: ship it\n\n## Tests\n\n- one\n\n" + BADGE)); expect(trailing.stderr()).toBe("gstack-post: pr-body merged by section: replaced ship receipt, Approvals; kept What changed, Why, capy-badge block; added Tests\n"); }); @@ -655,7 +666,7 @@ describe("gstack-post pr-body merges the PR body by section", () => { test("a partial post keeps the current intro and the note under the receipt", () => { const partial = withBody("Human intro\n\n" + RECEIPT("aaaa") + "Review-loop exception: accepted by owner\n\n## What changed\n\n- old\n", { "/b": "## Screenshots\n\n![shot](u)\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], partial)).toBe(EXIT.posted); - expect(sent(partial).input).toBe("Human intro\n\n" + RECEIPT("aaaa") + "Review-loop exception: accepted by owner\n\n## What changed\n\n- old\n\n## Screenshots\n\n![shot](u)\n"); + expect(sent(partial).input).toBe(foldSections("Human intro\n\n" + RECEIPT("aaaa") + "Review-loop exception: accepted by owner\n\n## What changed\n\n- old\n\n## Screenshots\n\n![shot](u)\n")); expect(partial.stderr()).toBe("gstack-post: pr-body merged by section: replaced none; kept leading text, ship receipt, trailing text, What changed; added Screenshots\n"); for (const file of ["Screenshots below.\n\n## Screenshots\n\n![shot](u)\n", "## Screenshots\n\n![shot](u)\n\n" + RECEIPT("bbbb")]) { @@ -678,12 +689,12 @@ describe("gstack-post pr-body merges the PR body by section", () => { const lead = "Human intro\n\n" + CURRENT; const receiptOnly = withBody(lead, { "/b": RECEIPT("bbbb") }); expect(run(["pr-body", "5", "--body-file", "/b"], receiptOnly)).toBe(EXIT.posted); - expect(sent(receiptOnly).input).toBe(lead.replace(RECEIPT("aaaa"), RECEIPT("bbbb"))); + expect(sent(receiptOnly).input).toBe(foldSections(lead.replace(RECEIPT("aaaa"), RECEIPT("bbbb")))); expect(receiptOnly.stderr()).toBe("gstack-post: pr-body merged by section: replaced ship receipt; kept leading text, What changed, Why, Approvals; added none\n"); const textOnly = withBody(RECEIPT("aaaa") + "Old note\n\n## Why\n\nx\n", { "/b": "New intro\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], textOnly)).toBe(EXIT.posted); - expect(sent(textOnly).input).toBe("New intro\n\n" + RECEIPT("aaaa") + "Old note\n\n## Why\n\nx\n"); + expect(sent(textOnly).input).toBe(foldSections("New intro\n\n" + RECEIPT("aaaa") + "Old note\n\n## Why\n\nx\n")); expect(textOnly.stderr()).toBe("gstack-post: pr-body merged by section: replaced none; kept ship receipt, trailing text, Why; added leading text\n"); const composed = "Intro\n\n" + RECEIPT("bbbb") + "\n## Summary\n\nnew\n\n## Test plan\n\n- [x] bun test\n"; @@ -707,22 +718,22 @@ describe("gstack-post pr-body merges the PR body by section", () => { test("--replace overwrites; a body without H2 headings is kept above a new receipt by any file; the merged bytes are what is scanned; a failed read refuses", () => { const replaced = withBody(CURRENT, { "/b": "## What changed\n\nonly this\n" }); expect(run(["pr-body", "5", "--replace", "--body-file", "/b"], replaced)).toBe(EXIT.posted); - expect(sent(replaced).input).toBe("## What changed\n\nonly this\n"); + expect(sent(replaced).input).toBe(foldSections("## What changed\n\nonly this\n")); expect(replaced.stderr()).toBe(""); expect(replaced.calls.some(c => c.cmd === "gh" && c.args[1] === "view")).toBe(false); const plain = withBody("Just a paragraph.\nAnother line.", { "/b": RECEIPT("bbbb") + "\n## Tests\n\n- one\n" }); expect(run(["pr-body", "5", "--body-file", "/b"], plain)).toBe(EXIT.posted); - expect(sent(plain).input).toBe("Just a paragraph.\nAnother line.\n\n" + RECEIPT("bbbb") + "\n## Tests\n\n- one\n"); + expect(sent(plain).input).toBe(foldSections("Just a paragraph.\nAnother line.\n\n" + RECEIPT("bbbb") + "\n## Tests\n\n- one\n")); expect(plain.stderr()).toBe("gstack-post: pr-body merged by section: replaced none; kept leading text; added ship receipt, Tests\n"); const plainText = withBody("Just a paragraph.\nAnother line.", { "/b": RECEIPT("bbbb") }); expect(run(["pr-body", "5", "--body-file", "/b"], plainText)).toBe(EXIT.posted); - expect(sent(plainText).input).toBe("Just a paragraph.\nAnother line.\n\n" + RECEIPT("bbbb")); + expect(sent(plainText).input).toBe(foldSections("Just a paragraph.\nAnother line.\n\n" + RECEIPT("bbbb"))); expect(plainText.stderr()).toBe("gstack-post: pr-body merged by section: replaced none; kept leading text; added ship receipt\n"); const empty = withBody("", { "/b": "new body" }); expect(run(["pr-body", "6", "--body-file", "/b"], empty)).toBe(EXIT.posted); - expect(sent(empty).input).toBe("new body"); + expect(sent(empty).input).toBe(foldSections("new body")); const secret = fakeEnv({ files: { "/b": "## What changed\n\nclean\n" }, respond: c => (c.cmd === "gh" && c.args[1] === "view" ? { status: 0, stdout: "## Keys\n\n" + AWS + "\n" } : undefined) }); expect(run(["pr-body", "5", "--body-file", "/b"], secret)).toBe(EXIT.refused); @@ -747,15 +758,15 @@ describe("gstack-post pr-body merges the PR body by section", () => { const merged = fakeEnv({ remote, files: { "/b": "## Why\n\nnew\n" }, respond: view(JSON.stringify({ iid: 8, description: "## What changed\n\n- old\n\n## Why\n\nold\n" }) + "\n") }); expect(run(["pr-body", "8", "--body-file", "/b"], merged)).toBe(EXIT.posted); expect(merged.calls.find(c => c.cmd === "glab" && c.args[1] === "view")!.args).toEqual(["mr", "view", "8", "--output", "json"]); - expect(merged.posts()).toEqual([{ cmd: "glab", args: ["mr", "update", "8", "--description=## What changed\n\n- old\n\n## Why\n\nnew\n"], input: undefined }]); + expect(merged.posts()).toEqual([{ cmd: "glab", args: ["mr", "update", "8", "--description=" + foldSections("## What changed\n\n- old\n\n## Why\n\nnew\n")], input: undefined }]); expect(merged.stderr()).toBe("gstack-post: pr-body merged by section: replaced Why; kept What changed; added none\n"); const empty = fakeEnv({ remote, files: { "/b": "## Why\n\nnew\n" }, respond: view("") }); expect(run(["pr-body", "8", "--body-file", "/b"], empty)).toBe(EXIT.posted); - expect(empty.posts()[0]!.args).toEqual(["mr", "update", "8", "--description=## Why\n\nnew\n"]); + expect(empty.posts()[0]!.args).toEqual(["mr", "update", "8", "--description=" + foldSections("## Why\n\nnew\n")]); const nullDescription = fakeEnv({ remote, files: { "/b": "## Why\n\nnew\n" }, respond: view('{"iid":8,"description":null}\n') }); expect(run(["pr-body", "8", "--body-file", "/b"], nullDescription)).toBe(EXIT.posted); - expect(nullDescription.posts()[0]!.args).toEqual(["mr", "update", "8", "--description=## Why\n\nnew\n"]); + expect(nullDescription.posts()[0]!.args).toEqual(["mr", "update", "8", "--description=" + foldSections("## Why\n\nnew\n")]); const garbled = fakeEnv({ remote, files: { "/b": "## Why\n\nnew\n" }, respond: view("<html>502</html>\n") }); expect(run(["pr-body", "8", "--body-file", "/b"], garbled)).toBe(EXIT.cliFailed); @@ -809,7 +820,7 @@ describe("gstack-post pr-body merges the PR body by section", () => { const replaced = withBody(current, { "/b": fresh }); expect(run(["pr-body", "5", "--body-file", "/b", "--replace"], replaced)).toBe(EXIT.posted); - expect(sent(replaced).input).toBe(fresh); + expect(sent(replaced).input).toBe(foldSections(fresh)); }); // Value: protects=a current body holding two ship-receipt blocks (an old receipt pasted below) refuses like a doubled title, so the stale @@ -984,6 +995,18 @@ describe("gstack-post refuses a title that is not in plain words (exit 4)", () = } finally { fs.rmSync(none, { recursive: true, force: true }); fs.rmSync(broken, { recursive: true, force: true }); } }); + // Value: protects=a comment is never held back by a broken policy file, which it never needed before the body check; + // fails_when=an invalid policy stops pr-comment, issue-comment and reply; why_new=comments now read the policy for warnings (GST-2737 review) + test("an invalid policy file warns and still posts a comment", () => { + const broken = repoWith("{ not json"); + try { + const c = fakeEnv({ root: broken, files: { "/b": "The pregate passed.\n" } }); + expect(run(["pr-comment", "7", "--body-file", "/b"], c)).toBe(EXIT.posted); + expect(c.posts()).toHaveLength(1); + expect(c.stderr()).toContain("(PLAIN_POLICY_INVALID); the comment is posted unchecked"); + } finally { fs.rmSync(broken, { recursive: true, force: true }); } + }); + test("the help names exit 4", () => { const f = fakeEnv(); expect(run(["--help"], f)).toBe(EXIT.posted); @@ -991,3 +1014,76 @@ describe("gstack-post refuses a title that is not in plain words (exit 4)", () = }); }); + +describe("gstack-post refuses a PR body that breaks the plain shape (exit 4)", () => { + const repoWith = (policy: string | null) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "gstack-post-body-")); + if (policy !== null) { fs.mkdirSync(path.join(root, ".gstack")); fs.writeFileSync(path.join(root, ".gstack", "plain-titles.json"), policy); } + return root; + }; + const POLICY = JSON.stringify({ codes: ["\\bGST-\\d+\\b"], terms: ["pregate"], allow: [], since: "2026-11-08", body_since: "2026-11-17", exempt_branch_prefixes: [], replace_default_terms: true }); + const TITLE = "Stop gstack from hitting GitHub's rate limit (GST-1713)"; + const LONG = "One.\n\nTwo.\n\nThree.\n\nFour, and the pregate said so.\n\n## Tests\n\n- one\n"; + const created = (at: string) => (c: Call) => (c.cmd === "gh" && c.args[1] === "view" && c.args.includes("createdAt") ? { status: 0, stdout: at + "\n" } : undefined); + + // Value: protects=a body with more than three visible lines or a listed word above the Agent notes fold posts nothing under a policy, + // with title and body findings printed in one pass; fails_when=the body is checked after posting, unfolded, or not at all; + // why_new=R76 as amended 2026-11-15; seam=a real policy file under the fake root; no_claim=real gh + test("a body with four visible lines and a listed word posts nothing; title and body findings print in one pass", () => { + const root = repoWith(POLICY); + try { + const f = fakeEnv({ root, files: { "/t": "Make the pregate quieter", "/b": LONG } }); + expect(run(["pr-create", "--base", "main", "--title-file", "/t", "--body-file", "/b"], f)).toBe(EXIT.plainTitle); + expect(f.calls.filter(c => c.cmd === "gh" || c.cmd === "glab")).toEqual([]); + expect(f.stdout()).toContain("PLAIN_TITLE: refused=1\n"); + expect(f.stdout()).toContain('PLAIN_BODY: PLAIN_BODY_REFUSED visible-lines "4 lines'); + expect(f.stdout()).toContain('PLAIN_BODY: PLAIN_BODY_REFUSED term "pregate"'); + expect(f.stdout()).toContain("PLAIN_BODY: refused=2\n"); + expect(f.stderr()).toContain("the body does not have the plain shape; nothing was posted"); + const edit = fakeEnv({ root, files: { "/b": LONG }, respond: created("2026-11-18T00:00:00Z") }); + expect(run(["pr-body", "7", "--body-file", "/b", "--replace"], edit)).toBe(EXIT.plainTitle); + expect(edit.posts()).toEqual([]); + } finally { fs.rmSync(root, { recursive: true, force: true }); } + }); + + // Value: protects=PRs opened before body_since, repositories without a policy and comments only warn, and still post; + // fails_when=old PRs or other repositories start refusing; why_new=A1 (refusals need a policy) and J1 (comments warn); + // seam=a real policy file and a fake createdAt; no_claim=real gh + test("an older PR, a repository without the policy and a comment get warnings and still post", () => { + const root = repoWith(POLICY); + const none = repoWith(null); + try { + const old = fakeEnv({ root, files: { "/b": LONG }, respond: created("2026-11-10T00:00:00Z") }); + expect(run(["pr-body", "7", "--body-file", "/b", "--replace"], old)).toBe(EXIT.posted); + expect(old.stdout()).toContain("(warning only)"); + expect(old.stdout()).toContain("PLAIN_BODY: warned=2\n"); + const free = fakeEnv({ root: none, files: { "/t": TITLE, "/b": LONG } }); + expect(run(["pr-create", "--base", "main", "--title-file", "/t", "--body-file", "/b"], free)).toBe(EXIT.posted); + expect(free.stdout()).toContain("PLAIN_BODY: warned=1\n"); + const comment = fakeEnv({ root, files: { "/b": "One.\nTwo.\nThree.\nFour: the pregate passed.\n" } }); + expect(run(["pr-comment", "7", "--body-file", "/b"], comment)).toBe(EXIT.posted); + expect(comment.stdout()).toContain('PLAIN_BODY: PLAIN_BODY_REFUSED term "pregate"'); + expect(comment.stdout()).not.toContain("visible-lines"); + } finally { fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(none, { recursive: true, force: true }); } + }); + + // Value: protects=bodies go out folded, a ## section replaces the same-titled fold already on the PR, and fold posts nothing; + // fails_when=a body is posted with open sections or the merge duplicates a folded section; why_new=E1; seam=the fake gh pr view body; no_claim=real gh + test("a body is posted folded, a ## Tests section replaces the Tests fold, and fold prints without posting", () => { + const root = repoWith(POLICY); + try { + const current = "What changed for a user.\n\n<details><summary>Tests</summary>\n\n- old\n\n</details>\n"; + const f = fakeEnv({ root, files: { "/b": "## Tests\n\n- new\n" }, respond: c => (c.cmd === "gh" && c.args[1] === "view" && c.args.includes("body") ? { status: 0, stdout: current } : undefined) }); + expect(run(["pr-body", "7", "--body-file", "/b"], f)).toBe(EXIT.posted); + expect(f.posts().find(c => c.args[1] === "edit")!.input).toBe("What changed for a user.\n\n<details><summary>Tests</summary>\n\n- new\n\n</details>\n"); + const fold = fakeEnv({ root, files: { "/b": "Opening.\n\n## Tests\n\n- one\n" } }); + expect(run(["fold", "--body-file", "/b"], fold)).toBe(EXIT.posted); + expect(fold.stdout()).toBe("Opening.\n\n<details><summary>Tests</summary>\n\n- one\n\n</details>\n"); + expect(fold.calls.filter(c => c.cmd === "gh" || c.cmd === "glab")).toEqual([]); + const bad = fakeEnv({ root, files: { "/b": LONG } }); + expect(run(["fold", "--body-file", "/b"], bad)).toBe(EXIT.plainTitle); + expect(bad.stderr()).toContain("PLAIN_BODY: refused=2"); + } finally { fs.rmSync(root, { recursive: true, force: true }); } + }); +}); + diff --git a/test/gstack-ship-policy.test.ts b/test/gstack-ship-policy.test.ts index d66d2c25e..b30c56174 100644 --- a/test/gstack-ship-policy.test.ts +++ b/test/gstack-ship-policy.test.ts @@ -9,7 +9,7 @@ import * as path from 'node:path'; import { spawnSync } from 'node:child_process'; import { EXIT } from '../lib/headless-artifacts'; import { BUMP_NEVER_KEY_VERSION, CHANGELOG_FRAGMENTS_KEY_VERSION, DEFAULT_POLICY, POLICY_KEYS, POLICY_KEY_INTRODUCED, REVIEW_SCOPE_KEY_VERSION, STAMP_PLACEHOLDERS_KEY_VERSION, globToRegExp, matchesAny, minimumReader, shipConsequences, validatePolicy } from '../lib/ship-policy'; -import { PLAN_RECORD_KEY_VERSION } from '../lib/ship-policy-keys'; +import { HISTORY_NO_REWRITE_KEY_VERSION, LAND_MERGE_COMMIT_PATHS_KEY_VERSION, PLAN_RECORD_KEY_VERSION } from '../lib/ship-policy-keys'; import { fillDue } from '../crew/lib/ship-queue-train'; import { cmpVersion, parseVersion } from '../lib/version-source'; import { BASE_POLICY, cleanup, makeFixtureRepo, runBin, type FixtureRepo } from './helpers/restamp-fixture'; @@ -346,4 +346,31 @@ describe('gstack-ship-policy (bin)', () => { expect(runBin(lax, 'gstack-ship-policy', ['check-history', '--base', 'main']).out).toBe('HISTORY: squash-ok (no check; policy history=squash-ok; plan=merge)\n'); expect(runBin(lax, 'gstack-ship-policy', ['check-history', '--base', 'main', '--plan', 'rebase']).status).toBe(EXIT.ok); }); + + // Value: protects=history: no-rewrite refuses a rebase plan or a rewritten branch but allows a squash landing, and an + // older gstack refuses the value and land.merge_commit_paths by name; fails_when=no-rewrite acts like squash-ok or + // merge-only, or a policy without min_gstack_version validates; why_new=I1 and G1 (GST-2737) + test('history: no-rewrite refuses a rebase plan and a rewritten branch, allows squash; it and land.merge_commit_paths need min_gstack_version', () => { + const repo = fixture({ policy: { ...BASE_POLICY, history: 'no-rewrite', min_gstack_version: HISTORY_NO_REWRITE_KEY_VERSION } }); + repo.git('checkout', '-q', '-b', 'pr'); + fs.writeFileSync(path.join(repo.work, 'a.txt'), 'a\n'); + repo.git('add', '-A'); repo.git('commit', '-q', '-m', 'a'); + repo.git('push', '-q', '-u', 'origin', 'pr'); + expect(runBin(repo, 'gstack-ship-policy', ['check-history', '--base', 'main', '--plan', 'squash']).out).toMatch(/^HISTORY: ok \(no-rewrite; origin\/pr is an ancestor of HEAD\)$/m); + const rebase = runBin(repo, 'gstack-ship-policy', ['check-history', '--base', 'main', '--plan', 'rebase']); + expect(rebase.status).toBe(EXIT.refused); + expect(rebase.out).toMatch(/^HISTORY: refused \(plan=rebase rewrites the branch; .*\(HISTORY_POLICY_VIOLATION\)$/m); + repo.git('commit', '-q', '--amend', '-m', 'a, amended'); + expect(runBin(repo, 'gstack-ship-policy', ['check-history', '--base', 'main']).status).toBe(EXIT.fail); + const codes = (p: Record<string, unknown>) => validatePolicy(p, { gstackVersion: HISTORY_NO_REWRITE_KEY_VERSION }).map(e => `${e.code}:${e.path}`); + expect(codes({ history: 'no-rewrite' })).toEqual(['POLICY_INVALID:history']); + expect(codes({ history: 'no-rewrite', min_gstack_version: HISTORY_NO_REWRITE_KEY_VERSION })).toEqual([]); + expect(codes({ land: { merge_commit_paths: ['evals/**'] }, min_gstack_version: '1.99.0.0' })).toEqual(['POLICY_INVALID:land.merge_commit_paths']); + expect(codes({ land: { merge_commit_paths: ['evals/**'] }, min_gstack_version: LAND_MERGE_COMMIT_PATHS_KEY_VERSION })).toEqual([]); + expect(codes({ land: { merge_commit_paths: ['../out'] }, min_gstack_version: LAND_MERGE_COMMIT_PATHS_KEY_VERSION })).toEqual(['POLICY_INVALID:land.merge_commit_paths']); + expect(validatePolicy({ history: 'no-rewrite', min_gstack_version: HISTORY_NO_REWRITE_KEY_VERSION }, { gstackVersion: '1.99.5.0' }).map(e => e.code)).toContain('POLICY_GSTACK_TOO_OLD'); + expect(minimumReader({ history: 'no-rewrite' })).toBe(HISTORY_NO_REWRITE_KEY_VERSION); + expect(minimumReader({ land: { merge_commit_paths: ['evals/**'] } })).toBe(LAND_MERGE_COMMIT_PATHS_KEY_VERSION); + expect(shipConsequences({ ...DEFAULT_POLICY, history: 'no-rewrite' }, 'main').join('\n')).toContain('never rebase or force-push this branch'); + }); }); diff --git a/test/helpers/docsync-observer.ts b/test/helpers/docsync-observer.ts index 00ac6a56a..c86a19751 100644 --- a/test/helpers/docsync-observer.ts +++ b/test/helpers/docsync-observer.ts @@ -179,7 +179,7 @@ export function docsPreambleCommands(fixture: ReturnType<typeof fixtureDocs>): s export function docsShipPhase(skeleton: string, prBody: string, scenario: DocsScenario, storePointer: string): string { if (scenario === 'store') return storePointer; - return `${sliceBetween(skeleton, '## Step 14.5: Documentation audit (every ship)', '## Step 15: Commit')}\n\n${sliceBetween(prBody, '## Documentation', '## Test plan')}`; + return `${sliceBetween(skeleton, '## Step 14.5: Documentation audit (every ship)', '## Step 15: Commit')}\n\n${sliceBetween(prBody, '## Documentation', '## Tests')}`; } type DocsSessionOptionsInput = { diff --git a/test/plain-title.test.ts b/test/plain-title.test.ts index ae709cbd9..b1e7ea973 100644 --- a/test/plain-title.test.ts +++ b/test/plain-title.test.ts @@ -10,7 +10,7 @@ import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; import { bunIsolationArgs } from '../lib/bun-isolation'; -import { PLAIN_TITLE_POLICY_PATH, checkBranch, checkChangelogEntry, checkCommitSubject, checkOpening, checkTitle, loadPlainTitlePolicy, splitTitle, type PlainFinding } from '../lib/plain-title'; +import { DEFAULT_TERMS, PLAIN_TITLE_POLICY_PATH, checkBranch, checkChangelogEntry, checkCommitSubject, checkOpening, checkTitle, loadPlainTitlePolicy, splitTitle, type PlainFinding } from '../lib/plain-title'; const ROOT = path.resolve(import.meta.dir, '..'); const BIN = path.join(ROOT, 'bin/gstack-plain-title'); @@ -26,7 +26,7 @@ const MAIN_SUBJECTS: Array<[string, string[]]> = [ ['fix(ship): record-ci reuses its own CI row at the same tree, run and selection (GST-1795)', ['scope-prefix:fix(ship):']], ['v1.98.0.0 release: fold the changelog fragments', []], ['ship tooling: post-review voices dispatch, same-tree pregate clears, fix-check p<N> ledgers (GST-1775)', ['term:voices', 'term:pregate', 'term:fix-check', 'term:ledgers']], - ["feat: crew PRs carry their brief's Plan line; ship-queue ready and land check it (GST-1751)", []], + ["feat: crew PRs carry their brief's Plan line; ship-queue ready and land check it (GST-1751)", ['term:crew', 'term:carry']], ['Require the daemon secret and loopback Host/Origin on the design and iOS QA daemons', []], ["browse: keep tunnel-paired agents on web URLs and away from the daemon's disk", []], ['feat(diff-scope): template UI in .ts/.js counts as frontend; receipt records the static design pass (GST-1718)', ['scope-prefix:feat(diff-scope):', 'term:receipt']], @@ -34,7 +34,7 @@ const MAIN_SUBJECTS: Array<[string, string[]]> = [ ['fix(ship-receipt): name the non-ancestor targeted-read commit in RECEIPT_INVALID (GST-1700)', ['scope-prefix:fix(ship-receipt):', 'term:receipt']], ['fix: release stamps and a docs-audit edit after the last fix-check are no gate-class edit (GST-1702)', ['term:fix-check']], ["fix(ship): a cleared remote gate for HEAD's exact tree satisfies a lane whose inventory refuses that tree (GST-1688)", ['scope-prefix:fix(ship):', 'term:lane']], - ['fix: the receipt and the review plan agree on stamp and docs carry for review_targeted (GST-1689)', ['term:receipt']], + ['fix: the receipt and the review plan agree on stamp and docs carry for review_targeted (GST-1689)', ['term:receipt', 'term:carry', 'term:stamp']], ['Capy session: defer the upgrade while a /ship or review run is open; upgrade-path fixes (GST-1677, GST-1658)', []], ['Playwright 1.65.0: bundled Chromium 158 drops the distrusted eMudhra root (#3338)', []], ['changelog.d: a second GST-1631 fragment names what the audit redaction does not cover yet (GST-1635)', ['code:GST-1631']], @@ -143,7 +143,8 @@ describe('checkBranch', () => { expect(src('lib/release-stamp.ts')).toContain('`release/${version}`'); expect(src('crew/lib/ship-queue-wave.ts')).toContain("startsWith('wave/')"); expect(src('lib/ship-queue-land.ts')).toContain('`gstack-land-repair/${j.pr}`'); - expect(policy.exempt_branch_prefixes).toEqual(['release/', 'wave/', 'gstack-land-repair/']); + expect(fs.existsSync(path.join(ROOT, '.github/dependabot.yml'))).toBe(true); + expect(policy.exempt_branch_prefixes).toEqual(['release/', 'wave/', 'gstack-land-repair/', 'dependabot/']); }); }); @@ -163,15 +164,15 @@ describe('checkOpening', () => { expect(brief(checkOpening(NOTES, policy))).toEqual(['opening-shape:no opening paragraph']); }); - test('more than two sentences, or a code or term in the opening, is refused', () => { - expect(brief(checkOpening('One thing. Two things. Three things.', policy))).toEqual(['opening-shape:3 sentences']); + test('three lines of sentences pass (the body shape check owns length); a code or term in the opening is refused', () => { + expect(checkOpening('One thing. Two things. Three things.', policy)).toEqual([]); expect(checkOpening('This changes the setup, e.g. the default. It is plain.', policy)).toEqual([]); expect(brief(checkOpening('The pregate clears faster (GST-1713).', policy))).toEqual(['code:GST-1713', 'term:pregate']); }); test('a marker quoted inline in the opening does not end it; only the section marker on its own line does', () => { const opening = 'Readers find the `<!-- gstack:agent-notes -->` section at the end. It holds the checks. It stays collapsed.\n\n'; - expect(brief(checkOpening(opening + NOTES, policy))).toEqual(['opening-shape:3 sentences']); + expect(checkOpening(opening + NOTES, policy)).toEqual([]); }); }); @@ -206,7 +207,10 @@ describe('policy', () => { expect(() => loadPlainTitlePolicy(withPolicy(JSON.stringify({ ...base, allow: [{ text: 'R2' }] })))).toThrow(/allow\[0\]\.reason/); expect(() => loadPlainTitlePolicy(withPolicy(JSON.stringify({ ...base, since: 'soon' })))).toThrow(/since/); expect(() => loadPlainTitlePolicy(withPolicy(JSON.stringify({ ...base, extra: 1 })))).toThrow(/extra is not a known key/); - expect(loadPlainTitlePolicy(withPolicy(JSON.stringify(base)))).toEqual(base); + expect(() => loadPlainTitlePolicy(withPolicy(JSON.stringify({ ...base, body_since: 'later' })))).toThrow(/body_since/); + expect(() => loadPlainTitlePolicy(withPolicy(JSON.stringify({ ...base, replace_default_terms: 'yes' })))).toThrow(/replace_default_terms/); + expect(loadPlainTitlePolicy(withPolicy(JSON.stringify(base)))).toEqual({ ...base, terms: ['a', ...DEFAULT_TERMS], body_since: base.since }); + expect(loadPlainTitlePolicy(withPolicy(JSON.stringify({ ...base, replace_default_terms: true, body_since: '2026-11-20' })))).toEqual({ ...base, body_since: '2026-11-20' }); }); test("gstack's policy loads and every allow entry says why", () => { @@ -254,6 +258,33 @@ describe('bin/gstack-plain-title', () => { expect([both.status, both.last]).toEqual([1, 'PLAIN_TITLE: refused=1 warned=1']); }); + // Value: protects=--body-file checks the folded shape (three visible lines, no listed word above Agent notes) and refuses + // only for a PR created on or after body_since on a branch the policy does not exempt; fails_when=an unfolded /ship draft + // is refused for its ## sections, or older and generated PRs start failing CI; why_new=R76 as amended 2026-11-15 (GST-2737) + test('a body file is checked once folded; an older PR or an exempt branch only warns', () => { + const draft = file('draft.md', 'What changed.\n\nWhy it helps.\n\nNothing to do.\n\n## What changed\n\n- one\n\n## Tests\n\n- two\n'); + expect(run(dirs.policy, ['check', '--body-file', draft])).toMatchObject({ status: 0, last: 'PLAIN_TITLE: ok' }); + const long = file('long.md', 'One.\n\nTwo.\n\nThree.\n\nFour.\n\n## Tests\n\n- the pregate passed\n'); + const r = run(dirs.policy, ['check', '--body-file', long, '--created-at', '2026-11-20T00:00:00Z']); + expect([r.status, r.last]).toEqual([1, 'PLAIN_TITLE: refused=2']); + expect(r.stdout).toContain('PLAIN_BODY: PLAIN_BODY_REFUSED visible-lines "4 lines'); + expect(r.stdout).toContain('PLAIN_BODY: PLAIN_BODY_REFUSED term "pregate"'); + expect(run(dirs.policy, ['check', '--body-file', long, '--created-at', '2026-11-10T00:00:00Z'])).toMatchObject({ status: 0, last: 'PLAIN_TITLE: warned=2' }); + expect(run(dirs.policy, ['check', '--body-file', long, '--head-branch', 'release/1.2.3.0'])).toMatchObject({ status: 0, last: 'PLAIN_TITLE: warned=2' }); + }); + + // Value: protects=the opening's own findings follow the same body_since and exempt-branch downgrade as the shape findings; + // fails_when=an older PR, a release/ PR or a Dependabot PR fails the required check for a listed word in its opening; + // why_new=the opening moved from the warn step to the refusing body step (GST-2737 review) + test('an older PR or an exempt branch only warns about its opening too', () => { + const body = file('lane.md', 'This lane makes the merge faster for users.\n'); + expect(run(dirs.policy, ['check', '--body-file', body, '--created-at', '2026-11-20T00:00:00Z'])).toMatchObject({ status: 1, last: 'PLAIN_TITLE: refused=2' }); + expect(run(dirs.policy, ['check', '--body-file', body, '--created-at', '2026-11-10T00:00:00Z'])).toMatchObject({ status: 0, last: 'PLAIN_TITLE: warned=2' }); + expect(run(dirs.policy, ['check', '--body-file', body, '--head-branch', 'release/1.2.3.4', '--created-at', '2026-11-20T00:00:00Z'])).toMatchObject({ status: 0, last: 'PLAIN_TITLE: warned=2' }); + expect(run(dirs.policy, ['check', '--body-file', body, '--head-branch', 'dependabot/bun/production-dependencies-ea1c777f8f', '--created-at', '2026-11-20T00:00:00Z'])).toMatchObject({ status: 0, last: 'PLAIN_TITLE: warned=2' }); + expect(run(dirs.policy, ['check', '--body-file', body, '--head-branch', '', '--created-at', '2026-11-20T00:00:00Z'])).toMatchObject({ status: 1, last: 'PLAIN_TITLE: refused=2' }); + }); + test('a changelog entry is checked', () => { const r = run(dirs.policy, ['check', '--changelog', file('frag.md', '**Plain lead (GST-1774).**\n')]); expect([r.status, r.last]).toEqual([1, 'PLAIN_TITLE: refused=1']); diff --git a/test/policy-floor-stable.test.ts b/test/policy-floor-stable.test.ts index b90af5d29..fab317844 100644 --- a/test/policy-floor-stable.test.ts +++ b/test/policy-floor-stable.test.ts @@ -10,7 +10,7 @@ import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; import { EXIT } from '../lib/headless-artifacts'; -import { BUMP_NEVER_KEY_VERSION, POLICY_KEY_INTRODUCED, runningGstackVersion, TRAIN_GATES_KEY_VERSION, validatePolicy } from '../lib/ship-policy'; +import { BUMP_NEVER_KEY_VERSION, HISTORY_NO_REWRITE_KEY_VERSION, LAND_MERGE_COMMIT_PATHS_KEY_VERSION, POLICY_KEY_INTRODUCED, runningGstackVersion, TRAIN_GATES_KEY_VERSION, validatePolicy } from '../lib/ship-policy'; import { cmpVersion, parseVersion } from '../lib/version-source'; import { useDoctorCleanup, REPO, makeFixture, doctor, write as writeFile } from './helpers/doctor-fixture'; import { cleanup as cleanupPregate, commit, makeFixtureRepo as makePregateRepo, runBin as runPregateBin, type FixtureRepo as PregateRepo } from './helpers/pregate-fixture'; @@ -189,7 +189,7 @@ describe('gstack-doctor --check floor row', () => { const f = makeFixture(); fs.copyFileSync(path.join(REPO, 'lib/ship-policy-keys.ts'), path.join(f.root, 'lib/ship-policy-keys.ts')); const newer = (a: string, b: string) => cmpVersion(parseVersion(a)!, parseVersion(b)!) > 0; - const known = [...Object.values(POLICY_KEY_INTRODUCED), BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION].reduce((a, b) => (newer(b, a) ? b : a)); + const known = [...Object.values(POLICY_KEY_INTRODUCED), BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION, HISTORY_NO_REWRITE_KEY_VERSION, LAND_MERGE_COMMIT_PATHS_KEY_VERSION].reduce((a, b) => (newer(b, a) ? b : a)); const dir = project(f, known); const at = floorRow(f, dir); expect(validatePolicy({ min_gstack_version: known })).toEqual([]); diff --git a/test/pr-body-shape.test.ts b/test/pr-body-shape.test.ts new file mode 100644 index 000000000..e4dcd07d2 --- /dev/null +++ b/test/pr-body-shape.test.ts @@ -0,0 +1,92 @@ +/** + * lib/pr-body-shape.ts (R76 as amended 2026-11-15): a PR body shows at most three lines before anything folded, + * every other section sits in a fold, listed words stay below the Agent notes fold, and the /ship receipt ends the + * body inside Agent notes. The #4353 case is the shape of the real body that PR was opened with: a long opening and + * open sections, with its receipt in the Agent notes section. + */ +import { describe, expect, test } from 'bun:test'; +import { withAgentNotes } from '../lib/agent-notes'; +import { checkBodyShape, foldSections, unfoldSections, visibleOpening, VISIBLE_CHARS, VISIBLE_LINES } from '../lib/pr-body-shape'; +import { renderReceiptBlock } from '../lib/ship-receipt'; +import type { ShipReceipt } from '../lib/headless-artifacts'; + +const RECEIPT = renderReceiptBlock({ schema_version: 1, pr: 4353, head: '0d6e4079e3aa', base: 'main' } satisfies ShipReceipt); +const kinds = (body: string, terms: string[] = []) => checkBodyShape(body, terms).map(f => `${f.kind}:${f.match}`); +const OPENING = "/ship's reviewers end their reply with one count line, and gstack checks it against the findings it read.\n\nWhy: a blocker a reviewer reports must never vanish.\n\nNothing to do: replies without the line read as before.\n"; + +describe('the visible opening', () => { + test('three lines fit; a fourth line, or 700 characters on three lines, is refused', () => { + expect(kinds(OPENING)).toEqual([]); + expect(kinds(OPENING + '\nOne more line.\n')).toEqual([`visible-lines:4 lines, ${[...visibleOpening(OPENING + '\nOne more line.\n').join('\n')].length} characters before the first fold`]); + const long = ['a'.repeat(240), 'b'.repeat(240), 'c'.repeat(220)].join('\n\n'); + expect(visibleOpening(long)).toHaveLength(VISIBLE_LINES); + expect(kinds(long)[0]).toStartWith('visible-lines:3 lines, 702 characters'); + expect(VISIBLE_CHARS).toBe(600); + }); + + test('HTML comments and folds never count as visible; text left between folds is refused', () => { + expect(kinds('<!-- a note for tools -->\n' + OPENING + '\n<details><summary>Tests</summary>\n\n- one\n- two\n\n</details>\n')).toEqual([]); + expect(kinds(OPENING + '\n<details><summary>Tests</summary>\n\n- one\n\n</details>\n\nLoose paragraph.\n')).toEqual(['unfolded:Loose paragraph.']); + }); + + test('nested folds stay inside their parent and a fenced <details> is code, not a fold', () => { + const nested = OPENING + '\n<details><summary>Tests</summary>\n\n<details><summary>Logs</summary>\n\nlog\n\n</details>\n\nAfter the inner fold.\n\n</details>\n'; + expect(kinds(nested)).toEqual([]); + expect(foldSections(nested)).toBe(nested); + const fenced = OPENING + '\n## Example\n\n```html\n<details>\n## not a heading\n```\n'; + expect(foldSections(fenced)).toBe(OPENING + '\n<details><summary>Example</summary>\n\n```html\n<details>\n## not a heading\n```\n\n</details>\n'); + expect(kinds(foldSections(fenced))).toEqual([]); + }); +}); + +describe('listed words', () => { + const body = withAgentNotes(OPENING.replace('Why:', 'Why: the outside voice and the pregate said so;') + '\n## Tests\n\n- `lane` stays in code\n', 'Lane notes are fine here.\n\n' + RECEIPT); + test('a listed word above the Agent notes fold is found once per spelling; code and the notes section are skipped', () => { + expect(kinds(foldSections(body), ['outside voice', 'pregate', 'lane'])).toEqual(['term:outside voice', 'term:pregate']); + expect(kinds(foldSections(body))).toEqual([]); + }); + + // Value: protects=a listed word inside a file path or file name is not prose, so a Tests line naming test/ship-receipt-depth.test.ts passes while the + // same word in a sentence is still refused; fails_when=bare paths in the Tests section refuse routine /ship bodies; why_new=GST-2737 review (granted fix-check) + test('a listed word inside a file path or file name is skipped; the same word in a sentence is still found', () => { + const tests = withAgentNotes(OPENING + '\n## Tests\n\n- [x] bun test test/ship-receipt-depth.test.ts: 12 pass\n- [x] bun test release-stamp.test.ts docs/lane.md: pass\n', RECEIPT); + expect(kinds(foldSections(tests), ['receipt', 'stamp', 'lane'])).toEqual([]); + const prose = withAgentNotes(OPENING + '\n## Tests\n\n- the receipt was written after test/ship-receipt-depth.test.ts passed\n', RECEIPT); + expect(kinds(foldSections(prose), ['receipt'])).toEqual(['term:receipt']); + }); +}); + +describe('the Agent notes section ends the body', () => { + test('a receipt outside the notes, or text after them, is refused; a Capy badge after them is fine', () => { + expect(kinds(withAgentNotes(OPENING, RECEIPT))).toEqual([]); + expect(kinds(OPENING + '\n' + RECEIPT)).toContain('receipt-placement:gstack-ship-receipt'); + expect(kinds(withAgentNotes(OPENING, RECEIPT) + '\nA trailing note.\n')).toEqual(['receipt-placement:A trailing note.']); + expect(kinds(withAgentNotes(OPENING, RECEIPT) + '\n<a href="https://capy.ai/x"><img src="b"></a>\n')).toEqual([]); + }); +}); + +describe('folding', () => { + const original = OPENING.split('\n\n')[0] + '\n\n## Why\n\nThe parser read prose and guessed.\n\n## What changed\n\n- The ask.\n- The check.\n\n## Tests\n\n- 52 pass\n\n'; + const body = withAgentNotes(original, 'Plan: plans/gst-2737.md\n\n' + RECEIPT); + test("a #4353-shaped body folds every section, keeps the opening and the receipt byte for byte, and passes", () => { + const folded = foldSections(body); + expect(folded.startsWith(OPENING.split('\n\n')[0] + '\n\n<details><summary>Why</summary>\n\nThe parser read prose and guessed.\n\n</details>\n\n<details><summary>What changed</summary>\n\n- The ask.\n- The check.\n\n</details>\n\n<details><summary>Tests</summary>\n\n- 52 pass\n\n</details>\n')).toBe(true); + expect(folded.slice(folded.indexOf('<!-- gstack:agent-notes -->'))).toBe(body.slice(body.indexOf('<!-- gstack:agent-notes -->'))); + expect(folded).toContain(RECEIPT); + expect(kinds(folded)).toEqual([]); + expect(kinds(body)[0]).toStartWith('visible-lines:8 lines'); + }); + + test('folding is idempotent and unfolding then folding gives the same bytes', () => { + const folded = foldSections(body); + expect(foldSections(folded)).toBe(folded); + expect(foldSections(unfoldSections(folded))).toBe(folded); + expect(unfoldSections(folded)).toContain('## What changed\n\n- The ask.'); + }); + + test('a heading with markup is escaped in the summary and restored on unfold', () => { + const folded = foldSections('Opening.\n\n## Notes <b>&</b>\n\nx\n'); + expect(folded).toBe('Opening.\n\n<details><summary>Notes <b>&</b></summary>\n\nx\n\n</details>\n'); + expect(unfoldSections(folded)).toContain('## Notes <b>&</b>'); + }); +}); diff --git a/test/prose-lint.test.ts b/test/prose-lint.test.ts index 04a8f19a7..84b1e9db3 100644 --- a/test/prose-lint.test.ts +++ b/test/prose-lint.test.ts @@ -307,8 +307,8 @@ describe('wiring', () => { expect(changelog).toContain('gstack-prose-lint CHANGELOG.md --base origin/<base> --gate'); const prBody = read('ship/sections/pr-body.md.tmpl'); const compose = prBody.slice(prBody.indexOf(': "${DOCS_SECTION_FILE:?'), prBody.indexOf('echo "PR_BODY_FILE: $PR_BODY_FILE"')); - expect(compose).toContain(`gstack-prose-lint "$BODY_TOP_FILE" --sections 'Why,Summary,Blast radius' --gate`); - expect(compose).not.toContain('What changed,'); + expect(compose).toContain(`gstack-prose-lint "$BODY_TOP_FILE" --sections 'Why,What changed,Blast radius' --gate`); + expect(compose).not.toContain('Summary,'); expect(compose).not.toContain('"$BODY_REST_FILE" --gate'); expect(compose.indexOf('gstack-prose-lint')).toBeGreaterThan(compose.indexOf('is empty, so the body was never written')); expect(compose.indexOf('gstack-prose-lint')).toBeLessThan(compose.indexOf('{ awk 1 "$BODY_TOP_FILE"')); @@ -317,7 +317,7 @@ describe('wiring', () => { test('the PR body leads with the problem and carries a Blast radius item, on both the standard and the Capy path', () => { const prBody = read('ship/sections/pr-body.md.tmpl'); - const summary = prBody.slice(prBody.indexOf('## Summary'), prBody.indexOf('## Test Coverage')); + const summary = prBody.slice(prBody.indexOf('## What changed'), prBody.indexOf('## Test Coverage')); expect(summary).toContain("Open with the problem in the user's words"); expect(summary).toContain('Never an inventory or a commit list.'); expect(summary).toMatch(/BAD: ".+" GOOD: "/s); diff --git a/test/release-stamp.test.ts b/test/release-stamp.test.ts index 2e47150da..6dd05da04 100644 --- a/test/release-stamp.test.ts +++ b/test/release-stamp.test.ts @@ -7,6 +7,9 @@ import { afterEach, describe, expect, test } from 'bun:test'; import * as fs from 'node:fs'; import * as path from 'node:path'; import { classifyRelease, openRelease } from '../lib/release-stamp'; +import { checkBodyShape, visibleOpening } from '../lib/pr-body-shape'; +import { DEFAULT_TERMS } from '../lib/plain-title'; +import { sectionText } from '../lib/squash-message'; import { loadPolicyFromBase, MERGE_KEY_VERSION } from '../lib/ship-policy'; import { classifyTrainHead } from '../crew/lib/version-gate-train'; import { BASE_POLICY, cleanup, makeFixtureRepo, readFile, runBin, type FixtureRepo } from './helpers/restamp-fixture'; @@ -133,6 +136,10 @@ describe('gstack-release-stamp open', () => { expect(repo.git('--git-dir', repo.origin, 'rev-parse', 'refs/heads/main')).toBe(repo.git('rev-parse', 'origin/main')); expect(calls.map(a => a[1])).toEqual(['list', 'create']); expect(calls[1]!.slice(0, 7)).toEqual(['pr', 'create', '--base', 'main', '--head', 'release/1.3.0.0', '--title']); + const body = calls[1]![calls[1]!.indexOf('--body') + 1]!; + expect(checkBodyShape(body, DEFAULT_TERMS)).toEqual([]); + expect(visibleOpening(body)[0]).toBe('v1.3.0.0 ships 2 user-visible changes, listed one per line under Release notes with the pull request that made each.'); + expect(sectionText(body, 'Release notes')).toBe('- a change\n- b feature'); expect(r.lines.join('\n')).toContain('NEXT: gstack-ship-queue land --pr 42 --pin ' + r.head); expect(classifyRelease({ repoRoot: repo.work, policy: policyOf(repo), mergeBase: repo.git('rev-parse', 'origin/main'), head: r.head! }).ok).toBe(true); expect(repo.git('branch', '--show-current')).toBe('elsewhere'); diff --git a/test/ship-publication-gates.test.ts b/test/ship-publication-gates.test.ts index 08db7e73f..72e4606a8 100644 --- a/test/ship-publication-gates.test.ts +++ b/test/ship-publication-gates.test.ts @@ -2,13 +2,14 @@ import { expect, test } from 'bun:test'; import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join, resolve } from 'node:path'; +import { foldSections } from '../lib/pr-body-shape'; import { killGroup } from '../lib/pregate/supervise'; import { expectMentions } from './helpers/prompt-structure'; const template = readFileSync(new URL('../ship/sections/pr-body.md.tmpl', import.meta.url), 'utf8'); /** The agent writes the body drafts with its file-write tool; the block reads them by printed name. */ -function writeDrafts(root: string, top = '## Summary\n\n## Documentation', rest = '## Test plan\n- [x] bun test: pass'): (block: string) => string { +function writeDrafts(root: string, top = '## What changed\n\n## Documentation', rest = '## Tests\n- [x] bun test: pass'): (block: string) => string { mkdirSync(join(root, '.gstack/tmp'), { recursive: true }); writeFileSync(join(root, '.gstack/tmp/pr-body-top.abc123'), top); writeFileSync(join(root, '.gstack/tmp/pr-body-rest.abc123'), rest); @@ -124,17 +125,17 @@ for (const failure of ['none', 'body', 'title'] as const) { try { const secret = 'AKIA' + '1234567890ABCDEF'; const c = await composed(root, { - top: failure === 'body' ? `## Summary\nkey ${secret}\n\n## Documentation` : undefined, + top: failure === 'body' ? `## What changed\nkey ${secret}\n\n## Documentation` : undefined, title: failure === 'title' ? `v1.2.3.4 fix: ${secret}` : undefined, }); const result = await c.publish(createBlock); if (failure === 'none') { expect(result.exitCode, result.stderr.toString()).toBe(0); expect(result.stdout.toString()).toContain('https://github.com/o/r/pull/9'); - expect(c.calls()).toEqual([{ args: ['pr', 'create', '--base=main', '--title=v1.2.3.4 fix: publication checks', '--body-file=-'], stdin: readFileSync(c.bodyFile, 'utf8') }]); + expect(c.calls()).toEqual([{ args: ['pr', 'create', '--base=main', '--title=v1.2.3.4 fix: publication checks', '--body-file=-'], stdin: foldSections(readFileSync(c.bodyFile, 'utf8')) }]); } else { expect(result.exitCode).toBe(1); - expect(result.stdout.toString()).toContain(`HIGH RULE: aws.access_key LINE: ${failure === 'body' ? 2 : 1} PART: ${failure}`); + expect(result.stdout.toString()).toContain(`HIGH RULE: aws.access_key LINE: ${failure === 'body' ? 3 : 1} PART: ${failure}`); expect(c.calls()).toEqual([]); } } finally { @@ -184,10 +185,10 @@ test.skipIf(process.platform === 'win32')('a block whose background child holds test.skipIf(process.platform === 'win32')('MEDIUM findings publish nothing until the block reruns with the printed token', async () => { const root = mkdtempSync(join(tmpdir(), 'ship-post-medium-')); try { - const c = await composed(root, { top: '## Summary\nThanks jane.roe@acme-corp.io\n\n## Documentation' }); + const c = await composed(root, { top: '## What changed\nThanks jane.roe@acme-corp.io\n\n## Documentation' }); const first = await c.publish(editBlock); expect(first.exitCode).toBe(2); - expect(first.stdout.toString()).toContain('RULE: pii.email LINE: 2 PART: body'); + expect(first.stdout.toString()).toContain('RULE: pii.email LINE: 3 PART: body'); expect(c.calls()).toEqual([]); const token = /^TOKEN: (\S+)$/m.exec(first.stdout.toString())![1]!; const flagged = 'pr-body <pr-number> --body-file "${PR_BODY_FILE:?restore the composed body path}"'; @@ -199,7 +200,7 @@ test.skipIf(process.platform === 'win32')('MEDIUM findings publish nothing until ['pr', 'edit', '9', '--body-file=-'], ['pr', 'edit', '9', '--title=v1.2.3.4 fix: publication checks'], ]); - expect(calls[0]!.stdin).toBe(readFileSync(c.bodyFile, 'utf8')); + expect(calls[0]!.stdin).toBe(foldSections(readFileSync(c.bodyFile, 'utf8'))); } finally { rmSync(root, { recursive: true, force: true }); } @@ -218,7 +219,7 @@ test('publication composes the saved documentation section unchanged and refuses }); const composed = run(join(root, 'section.md')); expect(composed.exitCode).toBe(0); - expect(composed.stdout.toString()).toBe(`## Summary\n\n## Documentation\n${section}\n## Test plan\n- [x] bun test: pass\n`); + expect(composed.stdout.toString()).toBe(`## What changed\n\n## Documentation\n${section}\n## Tests\n- [x] bun test: pass\n`); expect(existsSync(join(root, '.gstack/tmp/pr-body-top.abc123'))).toBe(false); expect(existsSync(join(root, '.gstack/tmp/pr-body-rest.abc123'))).toBe(false); const missing = run(join(root, 'absent.md')); diff --git a/test/ship-queue-land-direct.test.ts b/test/ship-queue-land-direct.test.ts index 4b83b19ea..d1dd4b2c2 100644 --- a/test/ship-queue-land-direct.test.ts +++ b/test/ship-queue-land-direct.test.ts @@ -12,6 +12,7 @@ import * as os from 'node:os'; import * as path from 'node:path'; import { EXIT } from '../lib/headless-artifacts'; import { LAND_KEY_VERSION, MERGE_KEY_VERSION, RELEASE_GATE_KEY_VERSION, validatePolicy } from '../lib/ship-policy'; +import { LAND_MERGE_COMMIT_PATHS_KEY_VERSION } from '../lib/ship-policy-keys'; import { BASE_POLICY, cleanup, makeFixtureRepo, runBin, type FixtureRepo } from './helpers/restamp-fixture'; import { shippedBody } from './helpers/ship-queue-train-fixture'; import { persist, repoIdentity } from '../crew/lib/ship-queue-train-record'; @@ -109,6 +110,8 @@ function openPr(fx: Fx, pr: string, opts: { edit?: (work: string) => void; shipp repo.git('checkout', '-q', '--detach', 'origin/main'); return head; } +/** The gh pr merge arguments land sends for a fixture PR: the title subject, and a body of the opening lines plus trailers (none here: the fixture body is only a receipt). */ +const merged = (pr: string, pin: string, method = '--squash', body = '') => [pr, method, '--match-head-commit', pin, '--subject', `PR ${pr} (#${pr})`, '--body', body]; const land = (fx: Fx, pr: string, pin: string, extra: string[] = []) => runBin(fx.repo, 'gstack-ship-queue', ['land', '--pr', pr, '--pin', pin, '--base', 'main', ...extra], fx.env); const remote = (fx: Fx, ref: string) => { fx.repo.git('fetch', '-q', 'origin', '+refs/heads/*:refs/remotes/origin/*'); return fx.repo.git('rev-parse', 'origin/' + ref); }; const show = (fx: Fx, rev: string) => fx.repo.git('show', rev); @@ -147,7 +150,7 @@ describe('land --pin: direct merge at the PR\'s own green head', () => { const r = land(fx, '7', pin); expect(r.err).toBe(''); expect(r.status).toBe(EXIT.ok); - expect(fx.read().mergeArgs).toEqual(['7', '--squash', '--match-head-commit', pin, '--subject', 'PR 7 (#7)']); + expect(fx.read().mergeArgs).toEqual(merged('7', pin)); const main = remote(fx, 'main'); expect(fx.repo.git('rev-parse', main + '^1')).toBe(base); expect(r.out).toContain('MERGED: #7 as ' + main); @@ -159,6 +162,33 @@ describe('land --pin: direct merge at the PR\'s own green head', () => { expect(notes[0]).toMatchObject({ kind: 'land', pr: '7', pin, merge_sha: main, base_sha: base }); }, 90_000); + // Value: protects=land sends the plain message (title subject, opening lines plus trailers), prints it under --dry-run, + // takes --body-file, and keeps a merge commit for a land.merge_commit_paths match; fails_when=land drops --body (GitHub then + // writes its commit list), ignores the override, or squashes an eval results PR; why_new=R76 as amended 2026-11-15 (GST-2737) + test('the merge commit is the title plus the opening lines; --dry-run prints it, --body-file replaces the opening, a merge_commit_paths match merges', () => { + const fx = setup({ ...POLICY, land: { merge_commit_paths: ['evals/**'] }, min_gstack_version: LAND_MERGE_COMMIT_PATHS_KEY_VERSION }); + const pin = openPr(fx, '31'); + fx.write(d => { d.prs['31'].body = 'Land now writes a plain commit.\n\nWhy: main\'s log should read as a list of changes.\n\n' + d.prs['31'].body; }); + const dry = land(fx, '31', pin, ['--dry-run']); + expect(dry.status).toBe(EXIT.ok); + expect(dry.out).toContain('METHOD: squash (no land.merge_commit_paths match)\nSUBJECT: PR 31 (#31)\nBODY: Land now writes a plain commit.\nBODY: \nBODY: Why: main\'s log should read as a list of changes.\n'); + expect(fx.read().mergeArgs).toBeUndefined(); + const file = path.join(fx.repo.root, 'commit-body.txt'); + fs.writeFileSync(file, 'The line I picked.\n'); + expect(land(fx, '31', pin, ['--body-file', file]).status).toBe(EXIT.ok); + expect(fx.read().mergeArgs).toEqual(merged('31', pin, '--squash', 'The line I picked.')); + const evals = openPr(fx, '32', { edit: w => { fs.mkdirSync(path.join(w, 'evals'), { recursive: true }); fs.writeFileSync(path.join(w, 'evals', 'run.json'), '{}\n'); } }); + const r = land(fx, '32', evals); + expect(r.out).toContain('METHOD: merge (land.merge_commit_paths matches evals/run.json)'); + expect(fx.read().mergeArgs).toEqual(merged('32', evals, '--merge')); + }, 120_000); + + test('--help names the land form this repository takes', () => { + const fx = setup(); + expect(runBin(fx.repo, 'gstack-ship-queue', ['--help'], fx.env).out).toContain('This repository (merge: direct): land each READY PR with gstack-ship-queue land --pr <n> --pin'); + }); + + test('GST-1316: the base moved after the pin\'s CI, so land runs land.merged_checks on the pin merged onto main: a failure refuses with QUEUE_LAND_MERGED_CHECKS and merges nothing, a pass lands and names the merged tree, and a rerun checks again', () => { const fx = setup(CHECKED); const red = openPr(fx, '8', { edit: w => fs.writeFileSync(path.join(w, 'budget.md'), 'pr line\n') }); @@ -761,7 +791,7 @@ describe('land --pin: fail closed and merge methods', () => { fx.write(d => { d.prs['25'].baseRefName = 'main'; }); const r = land(fx, '25', pin); expect(r.err).toBe(''); - expect(fx.read().mergeArgs).toEqual(['25', '--merge', '--match-head-commit', pin, '--subject', 'PR 25 (#25)']); + expect(fx.read().mergeArgs).toEqual(merged('25', pin, '--merge')); }, 90_000); test('land reads the policy after fetching the base: a required check main added since the last fetch is enforced', () => { @@ -1064,7 +1094,7 @@ describe('land --pin --repair: the one way through a backstop freeze under merge expect(r.err).toBe(''); expect(r.status).toBe(EXIT.ok); expect(r.out).toMatch(/^FREEZE: warn only: train backstop froze main \(backstop red on main [0-9a-f]{12}: .*\); the base policy declares release_gate/m); - expect(fx.read().mergeArgs).toEqual(['7', '--squash', '--match-head-commit', pin, '--subject', 'PR 7 (#7)']); + expect(fx.read().mergeArgs).toEqual(merged('7', pin)); expect(freezeOf(fx)).toMatchObject({ train: 'backstop', repair: null, cleared_at: null }); }, 90_000); @@ -1099,7 +1129,7 @@ describe('land --pin --repair: the one way through a backstop freeze under merge expect(r.err).toBe(''); expect(r.status).toBe(EXIT.ok); expect(r.out).toContain(`REPAIR: #7@${pin7.slice(0, 12)} admitted under the land lock`); - expect(fx.read().mergeArgs).toEqual(['7', '--squash', '--match-head-commit', pin7, '--subject', 'PR 7 (#7)']); + expect(fx.read().mergeArgs).toEqual(merged('7', pin7)); expect(fx.read().lockAtMerge).toMatchObject({ pr: '7', journal: 'land-pin:' + pin7 }); expect(freezeOf(fx)).toMatchObject({ train: 'backstop', repair: { pr: '7', head: pin7, train: null }, cleared_at: null, cleared_by: null }); expect(landNotes(fx)).toEqual([expect.objectContaining({ pr: '7', pin: pin7, merge_sha: remote(fx, 'main') })]); @@ -1107,7 +1137,7 @@ describe('land --pin --repair: the one way through a backstop freeze under merge expect(second.err).toContain('(QUEUE_TRAIN_FROZEN)'); expect(second.err).toContain(`repair #7@${pin7.slice(0, 12)}`); expect(land(fx, '8', pin8).err).toContain('(QUEUE_TRAIN_FROZEN)'); - expect(fx.read().mergeArgs).toEqual(['7', '--squash', '--match-head-commit', pin7, '--subject', 'PR 7 (#7)']); + expect(fx.read().mergeArgs).toEqual(merged('7', pin7)); }, 120_000); test('a recorded repair that never merged at its pin gives way to the next --repair; a repair train holding the freeze does not', () => { diff --git a/test/ship-queue-land.test.ts b/test/ship-queue-land.test.ts index 13f816660..1643148eb 100644 --- a/test/ship-queue-land.test.ts +++ b/test/ship-queue-land.test.ts @@ -626,7 +626,8 @@ describe('land: one pass, base, lock and history', () => { const r = land(fx, ['--pr', '13']); expect(r.err).toBe(''); expect(r.out).toContain('LANDED: '); - expect(JSON.parse(fs.readFileSync(fx.data, 'utf8')).mergeArgs).toContain('--merge'); + expect(JSON.parse(fs.readFileSync(fx.data, 'utf8')).mergeArgs).toEqual(['--merge', '--match-head-commit', expect.any(String), '--subject', 'PR 13 title (#13)', '--body', '']); + expect(r.out).toContain('SUBJECT: PR 13 title (#13)'); }, 90_000); // Value: protects=a merge-only land interrupted after GitHub merged resumes to LANDED, though a true merge puts the pin inside diff --git a/test/ship-receipt-depth.test.ts b/test/ship-receipt-depth.test.ts index 749167fb6..05056a280 100644 --- a/test/ship-receipt-depth.test.ts +++ b/test/ship-receipt-depth.test.ts @@ -15,7 +15,7 @@ import { extractReceipt, renderReceiptBlock } from '../lib/ship-receipt'; import { bindShippedReceipt, receiptDepthAtHead, receiptDepthVerdict, reviewLoopExceptionLine } from '../lib/ship-receipt-depth'; import { bunIsolationArgs } from '../lib/bun-isolation'; import { runScriptSync } from '../lib/script-invocation'; -import { BUMP_NEVER_KEY_VERSION, POLICY_KEY_INTRODUCED, TRAIN_GATES_KEY_VERSION } from '../lib/ship-policy'; +import { BUMP_NEVER_KEY_VERSION, HISTORY_NO_REWRITE_KEY_VERSION, LAND_MERGE_COMMIT_PATHS_KEY_VERSION, POLICY_KEY_INTRODUCED, TRAIN_GATES_KEY_VERSION } from '../lib/ship-policy'; import { cmpVersion, parseVersion } from '../lib/version-source'; import { cleanup, commit, makeFixtureRepo, ROOT, runBin, type FixtureRepo } from './helpers/pregate-fixture'; @@ -88,7 +88,7 @@ describe('write records the review depth at the checked-out head', () => { { cwd: repo.work, encoding: 'utf8', timeout: 180_000, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, ...repo.env } }); expect(write.status, write.stderr).toBe(EXIT.ok); expect(receiptIn(body).gstack_version).toBe('1.0.0.0'); - const newestKey = [...Object.values(POLICY_KEY_INTRODUCED), BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION].reduce((a, b) => (cmpVersion(parseVersion(b)!, parseVersion(a)!) > 0 ? b : a)); + const newestKey = [...Object.values(POLICY_KEY_INTRODUCED), BUMP_NEVER_KEY_VERSION, TRAIN_GATES_KEY_VERSION, HISTORY_NO_REWRITE_KEY_VERSION, LAND_MERGE_COMMIT_PATHS_KEY_VERSION].reduce((a, b) => (cmpVersion(parseVersion(b)!, parseVersion(a)!) > 0 ? b : a)); const reader = spawnSync(process.execPath, [...bunIsolationArgs(), '-e', `console.log((await import(${JSON.stringify(path.join(installed, 'lib', 'ship-policy.ts'))})).runningGstackVersion())`], { cwd: repo.work, encoding: 'utf8', timeout: 60_000 }); expect(reader.stdout.trim(), reader.stderr).toBe(newestKey); diff --git a/test/ship-workflow-clarity.test.ts b/test/ship-workflow-clarity.test.ts index b8847b6e6..f637c61b0 100644 --- a/test/ship-workflow-clarity.test.ts +++ b/test/ship-workflow-clarity.test.ts @@ -223,7 +223,7 @@ test('Step 14.5 runs the doc caps before the verification gate and records the a expectTokens(docs, ['`DOCS_CAP: none declared`', '"status":"updated|current"', '"status":"blocked"', '"exception":{"accepted_by"', '`DOCS_AUDIT_BLOCKED`', 'An unattended run has no owner to accept: it stops here.'], 'ship documentation section'); const compose = between(prTemplate, 'Handoff record first', '**Existing open PR/MR**'); expectTokens(compose, ['--docs @.gstack/tmp/docs-audit.json', '`DOCS_AUDIT_BLOCKED`'], 'ship pr-body receipt write'); - expectTokens(compact(between(prTemplate, '## Documentation', '## Test plan')), ['`Documentation exception: accepted by <accepted_by> <date> via <via>: <reason>`'], 'ship pr-body Documentation'); + expectTokens(compact(between(prTemplate, '## Documentation', '## Tests')), ['`Documentation exception: accepted by <accepted_by> <date> via <via>: <reason>`'], 'ship pr-body Documentation'); }); test('Step 9.4 applies the cap before any edit, names its scratch files under .gstack/tmp/, logs Step 11 late defers, and hands reviewers the range from pass 2 (PR 1 review notes)', () => { diff --git a/test/size-ledger/ship/gst-2737-plain-pr-bodies.json b/test/size-ledger/ship/gst-2737-plain-pr-bodies.json new file mode 100644 index 000000000..4f029c612 --- /dev/null +++ b/test/size-ledger/ship/gst-2737-plain-pr-bodies.json @@ -0,0 +1,4 @@ +{ + "bytes": 1153, + "why": "GST-2737: /ship writes a folded PR body with a three-line opening (pr-body template and gstack-post fold)" +} diff --git a/test/squash-message.test.ts b/test/squash-message.test.ts new file mode 100644 index 000000000..9a8b58781 --- /dev/null +++ b/test/squash-message.test.ts @@ -0,0 +1,115 @@ +/** + * lib/squash-message.ts: every gstack merge lands as one commit titled "<PR title> (#n)" whose body is the PR body's + * opening lines plus the branch's trailers (docs/writing-prs.md#the-commit-on-main). Real git repositories in a temp + * directory; no network. + */ +import { afterEach, describe, expect, test } from 'bun:test'; +import { spawnSync } from 'node:child_process'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { branchTrailers, landMessage, landMethod, mergeArgs, openingLines, sectionText } from '../lib/squash-message'; + +const dirs: string[] = []; +afterEach(() => { while (dirs.length) fs.rmSync(dirs.pop()!, { recursive: true, force: true }); }); + +/** A repository with one base commit on main; `commit` adds a file as the named author with the given message. */ +function repo() { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-squash-msg-')); + dirs.push(root); + const git = (args: string[], who = 'Ada <ada@example.com>') => { + const [name, email] = [who.replace(/ <.*/, ''), /<(.*)>/.exec(who)![1]!]; + const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 30_000, env: { ...process.env, GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email } }); + if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr}`); + return r.stdout.trim(); + }; + git(['init', '-q', '-b', 'main']); + const commit = (file: string, message: string, who?: string) => { fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true }); fs.writeFileSync(path.join(root, file), file + '\n'); git(['add', '-A'], who); git(['commit', '-q', '-m', message], who); return git(['rev-parse', 'HEAD']); }; + const base = commit('README.md', 'base'); + return { root, git, commit, base }; +} + +const OPENING = 'X is faster now: [the cache](https://example.com/c) keeps parsed files.\n\nWhy: big repositories waited a minute.\n\nNothing to do.\n'; +const BODY = OPENING + '\n## Tests\n\n- 12 pass\n'; +const SQUASH = { history: 'squash-ok' as const, land: null }; + +describe('the commit message', () => { + // Value: protects=main's log reads as plain changes with credit kept; fails_when=the subject loses the number, the body pastes the + // whole PR, a fold leaks in, links keep their URLs, or a trailer is lost or doubled; why_new=R76 as amended 2026-11-15 + test('subject is the title with (#n); body is the opening lines, then each trailer once and every other author', () => { + const r = repo(); + r.git(['checkout', '-q', '-b', 'pr']); + r.commit('src/a.ts', 'speed up the parser\n\nRemoved-test: test/old.test.ts\nCo-authored-by: Carol <carol@example.com>'); + const pin = r.commit('src/b.ts', 'tidy\n\nCo-authored-by: Carol <carol@example.com>', 'Bob <bob@example.com>'); + const m = landMessage(r.root, { pr: '5', title: 'Make X faster', prBody: BODY, mergeBase: r.base, pin, tip: r.base, policy: SQUASH }); + if ('error' in m) throw new Error(m.error); + expect(m.subject).toBe('Make X faster (#5)'); + expect(m.body).toBe('X is faster now: the cache keeps parsed files.\n\nWhy: big repositories waited a minute.\n\nNothing to do.\n\nRemoved-test: test/old.test.ts\nCo-authored-by: Carol <carol@example.com>\nCo-authored-by: Bob <bob@example.com>'); + expect([m.method, m.skippedParent]).toEqual(['squash', null]); + expect(mergeArgs('5', pin, m)).toEqual(['pr', 'merge', '5', '--squash', '--match-head-commit', pin, '--subject', 'Make X faster (#5)', '--body', m.body]); + }); + + test('an empty or receipt-only opening gives the trailers alone; a long line wraps at 72; at most three lines are kept', () => { + const r = repo(); + r.git(['checkout', '-q', '-b', 'pr']); + const pin = r.commit('src/a.ts', 'a\n\nCo-authored-by: Carol <carol@example.com>'); + const receiptOnly = '\`\`\`gstack-ship-receipt\n{ "schema_version": 1 }\n\`\`\`\n\n## What changed\n\nx\n'; + for (const prBody of ['', receiptOnly]) { + const m = landMessage(r.root, { pr: '5', title: 'T', prBody, mergeBase: r.base, pin, tip: r.base, policy: SQUASH }); + expect('error' in m ? m.error : m.body).toBe('Co-authored-by: Carol <carol@example.com>'); + } + const long = 'word '.repeat(30).trim(); + expect(openingLines(long).split('\n').every(l => l.length <= 72)).toBe(true); + expect(openingLines('one\n\ntwo\n\nthree\n\nfour\n')).toBe('one\n\ntwo\n\nthree'); + }); + + // Value: protects=a secret never reaches main's history through a commit message; fails_when=the scan is skipped or + // runs on other bytes than the ones sent; why_new=gate answer "the squash message goes through the redaction scan" + test('a key in the title, opening or --body-file refuses; a phone-shaped number drops the opening and keeps the trailers', () => { + const r = repo(); + r.git(['checkout', '-q', '-b', 'pr']); + const pin = r.commit('src/a.ts', 'a\n\nCo-authored-by: Carol <carol@example.com>'); + const key = 'AKIA' + '1234567890ABCDEF'; + const at = (o: { title?: string; prBody?: string; override?: string }) => landMessage(r.root, { pr: '5', title: o.title ?? 'T', prBody: o.prBody ?? BODY, override: o.override, mergeBase: r.base, pin, tip: r.base, policy: SQUASH }); + for (const o of [{ title: 'T ' + key }, { prBody: 'Uses ' + key + '.\n' }, { override: 'Uses ' + key }]) expect(at(o)).toMatchObject({ error: expect.stringContaining('nothing merged') }); + expect(at({ prBody: 'Call +14155552671 for help.\n' })).toMatchObject({ body: 'Co-authored-by: Carol <carol@example.com>' }); + expect(at({ override: 'The plain line I chose.' })).toMatchObject({ body: 'The plain line I chose.\n\nCo-authored-by: Carol <carol@example.com>' }); + expect(at({ title: ' ' })).toMatchObject({ error: expect.stringContaining('no title') }); + }); + + // Value: protects=a stacked PR's commit does not repeat the credit lines of its parent, which already landed; + // fails_when=landedStackParent is not consulted; why_new=gate answer Addition B + test('commits of a stacked parent that already landed are left out', () => { + const r = repo(); + r.git(['checkout', '-q', '-b', 'stack']); + const parent = r.commit('src/parent.ts', 'parent\n\nCo-authored-by: Dan <dan@example.com>'); + const pin = r.commit('src/child.ts', 'child\n\nCo-authored-by: Erin <erin@example.com>'); + r.git(['checkout', '-q', 'main']); + r.git(['checkout', '-q', parent, '--', 'src/parent.ts']); + r.git(['commit', '-q', '-m', 'Parent PR (#4)']); + const tip = r.git(['rev-parse', 'HEAD']); + const m = landMessage(r.root, { pr: '6', title: 'Child', prBody: '', mergeBase: r.base, pin, tip, policy: SQUASH }); + expect(m).toMatchObject({ skippedParent: parent, body: 'Co-authored-by: Erin <erin@example.com>' }); + expect(branchTrailers(r.root, r.base, pin)).toEqual(['Co-authored-by: Dan <dan@example.com>', 'Co-authored-by: Erin <erin@example.com>']); + }); +}); + +describe('the merge method', () => { + // Value: protects=repositories that must keep merge commits keep them, with the same subject and body; + // fails_when=merge-only or a merge_commit_paths match squashes; why_new=G1 and I1 + test('merge-only and a land.merge_commit_paths match merge; no-rewrite and a miss squash', () => { + const r = repo(); + r.git(['checkout', '-q', '-b', 'pr']); + const pin = r.commit('evals/results/run-1.json', 'results'); + expect(landMethod(r.root, { history: 'merge-only', land: null }, r.base, pin)).toEqual({ method: 'merge', why: 'history: merge-only' }); + expect(landMethod(r.root, { history: 'no-rewrite', land: null }, r.base, pin)).toEqual({ method: 'squash', why: 'history: no-rewrite' }); + expect(landMethod(r.root, { history: 'squash-ok', land: { merge_commit_paths: ['evals/**'] } }, r.base, pin)).toEqual({ method: 'merge', why: 'land.merge_commit_paths matches evals/results/run-1.json' }); + expect(landMethod(r.root, { history: 'squash-ok', land: { merge_commit_paths: ['docs/**'] } }, r.base, pin)).toEqual({ method: 'squash', why: 'no land.merge_commit_paths match' }); + }); + + test("a release PR's commit body is its Release notes section", () => { + const body = 'v1.2.0.0 ships 2 changes.\n\n<details><summary>Release notes</summary>\n\n- One thing (#1)\n- Another (#2)\n\n</details>\n\n<!-- gstack:agent-notes -->\n<details><summary>Agent notes</summary>\n\nx\n\n</details>\n'; + expect(sectionText(body, 'Release notes')).toBe('- One thing (#1)\n- Another (#2)'); + expect(sectionText(body, 'Missing')).toBe(''); + }); +});