Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* check:behavior-since (scripts/check-behavior-since.ts): a BEHAVIOR_CHANGES
* row with since: 'TBD' passes on an unstamped development branch and is
* refused on a stamped tree (VERSION has a CHANGELOG release header and differs
* from the base ref's), on master, and under --stamped (release:restamp's drift
* check and the Release workflow). release:restamp rewrites the rows first.
* Fixtures are throwaway git repos; origin/master is a local ref.
*/
import { afterAll, describe, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { main, NOTICE_FILE, tbdLines } from '../../scripts/check-behavior-since.ts';
import { build, OUT } from '../../scripts/build-behavior-changes.ts';
import { DEFAULT_CHECKS } from '../../scripts/release-restamp.ts';
import { BEHAVIOR_NOTICE_FILE, restampSinceLines, stampTbdSince } from '../../scripts/lib/restamp.ts';
const roots: string[] = [];
afterAll(() => { for (const root of roots) rmSync(root, { recursive: true, force: true }); });
function git(cwd: string, ...args: string[]): string {
return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
}
function put(root: string, files: Record<string, string>): void {
for (const [path, text] of Object.entries(files)) {
mkdirSync(dirname(join(root, path)), { recursive: true });
writeFileSync(join(root, path), text);
}
}
function notice(...sinces: string[]): string {
return ['export const BEHAVIOR_CHANGES = [', ...sinces.map((since, i) => ' { since: \'' + since + '\', text: \'Row ' + i + '.\' },'), '];', ''].join('\n');
}
function changelog(...versions: string[]): string {
return '# Changelog\n\n' + versions.map((v) => '## [' + v + '] - 2026-10-20\n\nEntry.\n').join('\n');
}
function commit(root: string, message: string): void {
git(root, 'add', '-A');
git(root, 'commit', '-q', '-m', message);
}
/** A repo whose origin/master is at 0.60.322.0 with only released rows, checked out on a feature branch. */
function repo(): string {
const root = mkdtempSync(join(tmpdir(), 'gbrain-behavior-since-'));
roots.push(root);
git(root, 'init', '-q', '-b', 'master');
git(root, 'config', 'user.email', '[email protected]');
git(root, 'config', 'user.name', 't');
put(root, { VERSION: '0.60.322.0\n', 'CHANGELOG.md': changelog('0.60.322.0'), [NOTICE_FILE]: notice('0.60.321.0', '0.60.322.0'), '.gstack/ship-policy.json': '{ "bump": "patch" }\n' });
commit(root, 'master');
git(root, 'update-ref', 'refs/remotes/origin/master', 'HEAD');
git(root, 'checkout', '-q', '-b', 'feature');
return root;
}
function run(root: string, argv: string[] = [], env: Record<string, string> = {}): { code: number; out: string } {
const lines: string[] = [];
const code = main(argv, { cwd: root, env, log: (line) => lines.push(line) });
return { code, out: lines.join('\n') };
}
describe('check:behavior-since', () => {
test('an unstamped branch (VERSION equals origin/master) may carry TBD rows', () => {
const root = repo();
put(root, { [NOTICE_FILE]: notice('0.60.321.0', '0.60.322.0', 'TBD') });
commit(root, 'feature');
const r = run(root);
expect(r.code).toBe(0);
expect(r.out).toContain('unstamped branch');
});
test('a stamped tree with one TBD row is refused with a fix line', () => {
const root = repo();
put(root, { VERSION: '0.60.323.0\n', 'CHANGELOG.md': changelog('0.60.323.0', '0.60.322.0'), [NOTICE_FILE]: notice('0.60.321.0', '0.60.322.0', '0.60.323.0', 'TBD') });
commit(root, 'stamp by hand, one row missed');
const r = run(root);
expect(r.code).toBe(1);
expect(r.out).toContain('FAIL: 1 BEHAVIOR_CHANGES row(s)');
expect(r.out).toContain('line 5');
expect(r.out).toContain('a stamped tree');
expect(r.out).toContain("Fix: run bun run release:restamp");
expect(r.out).toContain("since: '0.60.323.0'");
});
test('a stamped tree whose rows carry the release passes', () => {
const root = repo();
put(root, { VERSION: '0.60.323.0\n', 'CHANGELOG.md': changelog('0.60.323.0', '0.60.322.0'), [NOTICE_FILE]: notice('0.60.322.0', '0.60.323.0', '0.60.323.0') });
commit(root, 'stamp');
expect(run(root).code).toBe(0);
});
test('--stamped refuses any TBD row, even on an unstamped branch, and passes without one', () => {
const root = repo();
expect(run(root, ['--stamped']).code).toBe(0);
put(root, { [NOTICE_FILE]: notice('0.60.322.0', 'TBD') });
commit(root, 'feature');
const r = run(root, ['--stamped']);
expect(r.code).toBe(1);
expect(r.out).toContain('a tree being stamped or released');
});
test('--stamped refuses when the registry is missing (a sparse checkout without it)', () => {
const root = repo();
rmSync(join(root, NOTICE_FILE));
expect(run(root, ['--stamped']).code).toBe(1);
});
test('--stamped fails closed when .gstack/ship-policy.json is missing or cannot be parsed', () => {
const root = repo();
rmSync(join(root, '.gstack/ship-policy.json'));
const missing = run(root, ['--stamped']);
expect(missing.code).toBe(1);
expect(missing.out).toContain('FAIL: .gstack/ship-policy.json is missing');
put(root, { '.gstack/ship-policy.json': '{ "merge": "direct",\n' });
const broken = run(root, ['--stamped']);
expect(broken.code).toBe(1);
expect(broken.out).toContain('FAIL: .gstack/ship-policy.json cannot be parsed');
expect(run(root).code).toBe(0);
});
test('master refuses a TBD row: by GITHUB_REF, by HEAD at the base, and when the base itself ships one', () => {
const root = repo();
put(root, { [NOTICE_FILE]: notice('0.60.322.0', 'TBD') });
commit(root, 'feature');
expect(run(root, [], { GITHUB_REF: 'refs/heads/master' }).code).toBe(1);
git(root, 'update-ref', 'refs/remotes/origin/master', 'HEAD');
const atBase = run(root);
expect(atBase.code).toBe(1);
expect(atBase.out).toContain('the base ref origin/master itself');
put(root, { 'README.md': 'later\n' });
commit(root, 'a branch off a master that ships TBD');
const r = run(root);
expect(r.code).toBe(1);
expect(r.out).toContain('already ships a TBD row');
});
test('without the base ref: refused under CI, skipped locally', () => {
const root = repo();
put(root, { [NOTICE_FILE]: notice('0.60.322.0', 'TBD') });
commit(root, 'feature');
git(root, 'update-ref', '-d', 'refs/remotes/origin/master');
expect(run(root, [], { CI: 'true' }).code).toBe(1);
const local = run(root);
expect(local.code).toBe(0);
expect(local.out).toContain('GBRAIN_CHECK_SKIPPED');
});
test('unknown arguments are a usage error', () => {
expect(run(repo(), ['--nope']).code).toBe(2);
});
});
describe('release:restamp and the TBD rows', () => {
test('stampTbdSince gives every TBD row the new version and leaves released rows alone', () => {
const text = notice('0.60.322.0', 'TBD', 'TBD');
const stamped = stampTbdSince(text, '0.60.323.0');
expect(tbdLines(stamped)).toEqual([]);
expect(stamped).toBe(notice('0.60.322.0', '0.60.323.0', '0.60.323.0'));
expect(stampTbdSince(stamped, '0.60.324.0')).toBe(stamped);
expect(BEHAVIOR_NOTICE_FILE).toBe(NOTICE_FILE);
});
test('restampSinceLines moves only branch-added rows from the old version to the new one', () => {
const text = notice('0.60.323.0', '0.60.323.0', '0.60.323.0');
expect(restampSinceLines(text, new Set([3, 4]), '0.60.323.0', '0.60.324.0')).toBe(notice('0.60.323.0', '0.60.324.0', '0.60.324.0'));
expect(restampSinceLines(text, new Set([3]), '0.60.324.0', '0.60.324.0')).toBe(text);
});
test("restamp's drift checks run the guard with --stamped", () => {
expect(DEFAULT_CHECKS.map((c) => c.argv.join(' '))).toContain('bun scripts/check-behavior-since.ts --stamped');
});
});
describe('check:behavior-since under merge: direct', () => {
const POLICY = { '.gstack/ship-policy.json': JSON.stringify({ merge: 'direct' }) + '\n' };
const marker = '<!-- behavior-change: faster_sync_abc -->';
const fragment = { 'behavior-changes.d/faster_sync_abc.md': 'Sync is faster now.\n' };
/** origin/master already switched to merge: direct; the feature branch starts from it. */
function directRepo(): string {
const root = repo();
git(root, 'checkout', '-q', 'master');
put(root, POLICY);
commit(root, 'merge: direct');
git(root, 'update-ref', 'refs/remotes/origin/master', 'HEAD');
git(root, 'checkout', '-q', '-B', 'feature');
return root;
}
test('a literal TBD row is refused even on an unstamped branch (VERSION equals origin/master)', () => {
const root = directRepo();
put(root, { [NOTICE_FILE]: notice('0.60.321.0', '0.60.322.0', 'TBD') });
commit(root, 'feature');
const r = run(root);
expect(r.code).toBe(1);
expect(r.out).toContain("FAIL: 1 BEHAVIOR_CHANGES row(s) in " + NOTICE_FILE + " say since: 'TBD' (line 4)");
expect(r.out).toContain('under merge: direct');
expect(r.out).toContain('behavior-changes.d/<id>.md');
expect(run(root, ['--stamped']).code).toBe(1);
});
test('a branch with a pending fragment and no TBD row passes without --stamped', () => {
const root = directRepo();
put(root, { ...fragment, 'changelog.d/feature.md': '**Faster sync.**\n\n' + marker + '\n' });
commit(root, 'feature');
expect(run(root).code).toBe(0);
});
test('--stamped refuses a release commit that still holds an unfolded changelog.d fragment', () => {
const root = directRepo();
put(root, { ...fragment, VERSION: '0.60.323.0\n', 'changelog.d/feature.md': '**Faster sync.**\n\n' + marker + '\n', 'changelog.d/README.md': 'docs\n' });
put(root, { [OUT]: build(root).text });
commit(root, 'release, fragments not folded');
const r = run(root, ['--stamped']);
expect(r.code).toBe(1);
expect(r.out).toContain('still holds 1 unfolded changelog.d fragment(s): feature.md');
expect(r.out).toContain('VERSION 0.60.323.0');
});
test('--stamped refuses a folded release whose generated table is stale, and passes once it is fresh', () => {
const root = directRepo();
put(root, { ...fragment, VERSION: '0.60.323.0\n', 'CHANGELOG.md': changelog('0.60.322.0').replace('# Changelog\n\n', '# Changelog\n\n## [0.60.323.0] - 2026-11-09\n\n**Faster sync.**\n\n' + marker + '\n\n'), 'changelog.d/README.md': 'docs\n' });
commit(root, 'release, table not regenerated');
const stale = run(root, ['--stamped']);
expect(stale.code).toBe(1);
expect(stale.out).toContain('has a stale ' + OUT);
const { text, problems } = build(root);
expect(problems).toEqual([]);
expect(text).toContain("{ since: '0.60.323.0', id: 'faster_sync_abc'");
put(root, { [OUT]: text });
commit(root, 'release, table regenerated');
const ok = run(root, ['--stamped']);
expect(ok.code).toBe(0);
expect(ok.out).toContain("no since: 'TBD' row");
});
test('--stamped names the first fragment problem when the table cannot be built', () => {
const root = directRepo();
put(root, { ...fragment, VERSION: '0.60.323.0\n' });
put(root, { [OUT]: build(root).text });
commit(root, 'release with an orphan fragment');
const r = run(root, ['--stamped']);
expect(r.code).toBe(1);
expect(r.out).toContain('has a stale ' + OUT + ' (behavior-changes.d/faster_sync_abc.md has no');
});
});