Files
gstack/bin/gstack-ship-policy
T
Garry Tanandcapy-ai[bot] c53b15c48d Open pull requests with three plain lines and land each one as a single commit (GST-2737) (#4438)
* WIP plain PR bodies and squash messages

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Fold PR bodies to three plain lines and land every PR as one plainly titled commit

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Expect the plain commit body in the train land tests

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Count the new policy keys in the floor tests and record the ship size change

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Let older, generated and Dependabot PRs pass the body check, and keep comments posting

The opening check now follows the same date and branch exemption as the rest of the body check, Dependabot branches are exempt, the exemption only counts for branches in this repository, a merge that cannot read the PR waits instead of refusing, and a broken policy file no longer stops comments.

Review-Finding: p1/specialist-batched#1 reader=testing
Review-Finding: p1/specialist-batched#2 reader=testing
Review-Finding: p1/red-team#1 reader=red-team
Review-Finding: p1/red-team#2 reader=red-team
Review-Finding: p1/red-team#4 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Stop re-posted PR bodies from duplicating sections, and let file names through the word check

Posting an already-folded body now replaces each section once instead of keeping the old copy beside it, and listed words inside file paths or file names, such as a test file in the Tests section, no longer count as prose.

Review-Finding: v2/outside-voice#3 reader=outside-voice
Review-Finding: v2/adversarial-native#2 reader=adversarial-native
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Describe the folded three-line PR body in the skills guide and the prose lint help

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-17 13:14:33 +00:00

158 lines
9.5 KiB
TypeScript
Executable File

#!/usr/bin/env -S bun --no-env-file --config=/dev/null
/**
* gstack-ship-policy — read, validate and explain `.gstack/ship-policy.json` (plan C1).
*
* gstack-ship-policy init [--explain] [--force] write the example (every key at its default)
* gstack-ship-policy validate [--policy-from head|base] [--base <ref>] [--json]
* gstack-ship-policy show-effective [--policy-from base|head] [--base <ref>] [--json]
* gstack-ship-policy check-history [--base <ref>] [--branch <name>] [--plan merge|squash|rebase] [--json]
*
* `show-effective` reads the committed copy on origin/<base> by default (the
* reviewed policy); `validate` reads the working tree by default (the file
* you are editing). Query commands: no GSTACK_RESULT line; `--json` means
* JSON only on stdout. Logic: lib/ship-policy.ts; codes: lib/result-codes.ts.
*/
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { EXIT, exitTableHelp } from '../lib/headless-artifacts';
import { resultLine } from '../lib/result-codes';
import {
BUMP_NEVER_KEY_VERSION, POLICY_KEYS, POLICY_KEY_INTRODUCED, SHIP_POLICY_PATH, examplePolicyJson, explainPolicy, isUnavailable, loadPolicyFromBase, loadPolicyFromHead,
minimumReader, policyUnavailableLine, renderEffective, resolveBaseBranch, type LoadedPolicy,
} from '../lib/ship-policy';
import { logShipCall } from '../lib/ship-call-log';
import { floorAgainstStable, newestStableRelease } from '../lib/stable-release';
logShipCall('gstack-ship-policy');
const HELP = `gstack-ship-policy — the repo ship policy (docs/ship-policy.md)
init [--explain] [--force] write ${SHIP_POLICY_PATH} with every key at its default
validate [--policy-from head|base] [--base <ref>] schema and containment check (default: the working tree)
show-effective [--policy-from base|head] [--base <ref>]
resolved values with the source of each (default: origin/<base>)
check-history [--base <ref>] [--branch <name>] [--plan merge|squash|rebase]
under history: merge-only, refuse a squash/rebase plan or a rewritten branch
--json: JSON only on stdout. Error lines end in (<CODE>) with a fix: clause.
${exitTableHelp()}`;
function flag(args: string[], name: string): string | undefined {
const i = args.indexOf(name);
return i >= 0 ? args[i + 1] : undefined;
}
function usage(message: string): number {
process.stderr.write(`gstack-ship-policy: ${message}\n${HELP}\n`);
return EXIT.usage;
}
function repoRoot(): string {
const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 15_000 });
return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : process.cwd();
}
function load(root: string, args: string[], defaultFrom: 'base' | 'head'): LoadedPolicy | number {
const from = flag(args, '--policy-from') ?? defaultFrom;
if (from !== 'base' && from !== 'head') return usage('--policy-from needs base or head');
if (from === 'head') return loadPolicyFromHead(root);
const base = resolveBaseBranch(root, flag(args, '--base'));
const loaded = loadPolicyFromBase(root, base);
if (isUnavailable(loaded)) {
process.stderr.write(policyUnavailableLine('gstack-ship-policy', base, loaded.detail) + '\n');
return EXIT.refused;
}
return loaded;
}
function printErrors(loaded: LoadedPolicy): void {
for (const e of loaded.errors) process.stderr.write(resultLine('gstack-ship-policy', e.code, `${e.message} at ${e.path || SHIP_POLICY_PATH}`) + '\n');
for (const w of loaded.warnings) process.stderr.write(`gstack-ship-policy: WARN ${w.path}: ${w.message}\n`);
}
function main(argv: string[]): number {
const [cmd, ...rest] = argv;
const json = rest.includes('--json');
if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { process.stdout.write(HELP + '\n'); return cmd ? EXIT.ok : EXIT.usage; }
const root = repoRoot();
if (cmd === 'init') {
if (rest.includes('--explain')) { process.stdout.write(explainPolicy()); if (rest.length === 1) return EXIT.ok; }
const file = path.join(root, SHIP_POLICY_PATH);
if (fs.existsSync(file) && !rest.includes('--force')) {
process.stderr.write(resultLine('gstack-ship-policy init', 'POLICY_EXISTS', file) + '\n');
return EXIT.refused;
}
fs.mkdirSync(path.dirname(file), { recursive: true });
fs.writeFileSync(file, examplePolicyJson());
process.stdout.write(`POLICY_WRITTEN: ${SHIP_POLICY_PATH} (edit it, then gstack-ship-policy validate; commit it on the base branch before /ship reads it)\n`);
return EXIT.ok;
}
if (cmd === 'validate' || cmd === 'show-effective') {
const loaded = load(root, rest, cmd === 'validate' ? 'head' : 'base');
if (typeof loaded === 'number') return loaded;
const floor: ReturnType<typeof floorAgainstStable> = cmd === 'validate' && loaded.present ? floorAgainstStable(loaded.policy.min_gstack_version, newestStableRelease()) : {};
if (floor.error) loaded.errors.push(floor.error);
const set = POLICY_KEYS.filter(k => loaded.values[k] && loaded.values[k] !== 'default');
const introduced = Object.fromEntries(set.map(k => [k, k === 'bump' && loaded.policy.bump === 'never' ? BUMP_NEVER_KEY_VERSION : k === 'land' ? minimumReader({ land: loaded.policy.land }) : POLICY_KEY_INTRODUCED[k]]));
const minReader = set.length ? minimumReader(Object.fromEntries(set.map(k => [k, loaded.policy[k]]))) : null;
if (json) {
process.stdout.write(JSON.stringify({ valid: loaded.errors.length === 0, present: loaded.present, source: loaded.source, policy: loaded.policy, values: loaded.values, introduced, min_reader: minReader, ...(cmd === 'validate' ? { stable: floor.stable ?? null, warnings: [...(floor.warning ? [floor.warning] : []), ...loaded.warnings.map(w => `${w.path}: ${w.message}`)] } : {}), errors: loaded.errors }) + '\n');
return loaded.errors.length ? EXIT.fail : EXIT.ok;
}
printErrors(loaded);
if (floor.warning) process.stderr.write(`gstack-ship-policy: WARN ${floor.warning}\n`);
if (cmd === 'validate') {
process.stdout.write(loaded.errors.length ? `POLICY_INVALID: ${loaded.errors.length} error(s) in ${loaded.source.label}\n` : `POLICY_VALID: ${loaded.present ? loaded.source.label : `no ${SHIP_POLICY_PATH} (defaults apply)`}\n`);
for (const k of set) process.stdout.write(`KEY: ${k} introduced=${introduced[k]}\n`);
if (minReader) process.stdout.write(`MIN_READER: gstack ${minReader} (every lane that reads this policy needs at least this version)\n`);
return loaded.errors.length ? EXIT.fail : EXIT.ok;
}
process.stdout.write(renderEffective(loaded, { base: flag(rest, '--base') ?? resolveBaseBranch(root) }));
return loaded.errors.length ? EXIT.fail : EXIT.ok;
}
if (cmd === 'check-history') {
const loaded = load(root, rest, 'base');
if (typeof loaded === 'number') return loaded;
const branch = flag(rest, '--branch') ?? (spawnSync('git', ['branch', '--show-current'], { cwd: root, encoding: 'utf8', timeout: 15_000 }).stdout ?? '').trim();
const policy = loaded.policy.history;
const plan = flag(rest, '--plan') ?? 'merge';
if (!['merge', 'squash', 'rebase'].includes(plan)) return usage(`--plan must be merge, squash or rebase (got ${plan})`);
const result: Record<string, unknown> = { history: policy, branch: branch || null, plan };
let verdict: string;
let code = EXIT.ok;
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/<base> 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: ${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: ${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 (${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/<base> instead of rebasing or squashing; never force-push under history: ${policy}`} (HISTORY_POLICY_VIOLATION)`;
code = EXIT.fail;
}
}
}
result.ok = code === EXIT.ok;
result.verdict = verdict;
process.stdout.write(json ? JSON.stringify(result) + '\n' : verdict + '\n');
return code;
}
return usage(`unknown command ${cmd}`);
}
process.exitCode = main(process.argv.slice(2));