Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
18.1 KB
Raw Blame
/**
 * scripts/build-behavior-changes.ts against throwaway trees: behavior-changes.d/<id>.md fragments dated by the
 * <!-- behavior-change: <id> --> marker's CHANGELOG section, pending markers (changelog.d, [Unreleased]) counted only
 * while VERSION is newer than the top release heading, the fragment problems, releasedIn('<id>') function rows, the
 * --check exit codes, and the byte-identity between a release in progress and the same release folded, which
 * gstack's release check relies on.
 */
import { afterAll, describe, expect, test } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { build, main, NOTICE_FILE, OUT } from '../../scripts/build-behavior-changes.ts';

const roots: string[] = [];
afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });

function tree(files: Record<string, string>): string {
  const root = mkdtempSync(join(tmpdir(), 'gbrain-behavior-changes-'));
  roots.push(root);
  for (const [path, text] of Object.entries(files)) {
    mkdirSync(dirname(join(root, path)), { recursive: true });
    writeFileSync(join(root, path), text);
  }
  return root;
}

const marker = (id: string) => `<!-- behavior-change: ${id} -->`;
const section = (version: string, ...lines: string[]) => `## [${version}] - 2026-11-01\n\n${lines.join('\n')}\n`;
const changelog = (...sections: string[]) => `# Changelog\n\n${sections.join('\n')}`;
const notice = (...rows: string[]) => ['export const BEHAVIOR_CHANGES = [', ...rows.map((r) => `  ${r}`), '];', ''].join('\n');

function run(root: string, argv: string[]): { code: number; out: string } {
  const lines: string[] = [];
  const code = main(argv, { cwd: root, log: (l) => lines.push(l) });
  return { code, out: lines.join('\n') };
}

const rowsOf = (text: string) => [...text.matchAll(/^ {2}\{ since: '([^']+)', id: '([^']+)', (?:kind: '([a-z-]+)', )?text: (".*") \},$/gm)].map((m) => ({ since: m[1], id: m[2], ...(m[3] ? { kind: m[3] } : {}), text: JSON.parse(m[4]!) }));
const releasesOf = (text: string) => Object.fromEntries([...text.matchAll(/^ {2}([a-z0-9_]+): '([^']+)',$/gm)].map((m) => [m[1], m[2]]));

describe('build()', () => {
  test('a pending fragment (marker in changelog.d, VERSION at the top heading) generates nothing', () => {
    const root = tree({
      VERSION: '0.1.0.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')),
      'changelog.d/feature-x.md': `**Faster sync.**\n\n${marker('faster_sync_abc')}\n`,
      'behavior-changes.d/faster_sync_abc.md': 'Sync is faster now.\n',
    });
    const { text, problems } = build(root);
    expect(problems).toEqual([]);
    expect(rowsOf(text)).toEqual([]);
    expect(releasesOf(text)).toEqual({});
  });

  test('an [Unreleased] marker is pending too until a release is being stamped', () => {
    const files = {
      'CHANGELOG.md': changelog(`## [Unreleased]\n\n${marker('faster_sync_abc')}\n`, section('0.1.0.0', 'First.')),
      'behavior-changes.d/faster_sync_abc.md': 'Sync is faster now.\n',
    };
    expect(rowsOf(build(tree({ VERSION: '0.1.0.0\n', ...files })).text)).toEqual([]);
    expect(rowsOf(build(tree({ VERSION: '0.1.1.0\n', ...files })).text)).toEqual([{ since: '0.1.1.0', id: 'faster_sync_abc', text: 'Sync is faster now.' }]);
  });

  test('front matter (kind, exception, deprecation) is read and left out of the notice text; bad values are problems', () => {
    const root = tree({
      VERSION: '0.1.0.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', 'First.', marker('kinded_row_abc'), marker('bad_kind_abc'))),
      'behavior-changes.d/kinded_row_abc.md': '---\nkind: breaking\nexception: security\n---\nA kinded\nchange.\n',
      'behavior-changes.d/bad_kind_abc.md': '---\nkind: sideways\nexception: data-loss\nowner: someone\n---\nText.\n',
    });
    const { text, problems } = build(root);
    expect(rowsOf(text).find((r) => r.id === 'kinded_row_abc')).toEqual({ since: '0.1.0.0', id: 'kinded_row_abc', kind: 'breaking', text: 'A kinded change.' });
    expect(problems).toEqual([
      'behavior-changes.d/bad_kind_abc.md: front matter line "owner: someone" is not one of kind, exception, deprecation',
      'behavior-changes.d/bad_kind_abc.md: kind: sideways is not one of breaking, action, default, fix, add',
      'behavior-changes.d/bad_kind_abc.md: exception: applies only to kind: breaking',
    ]);
  });

  test('a marker under a released CHANGELOG heading dates the row with that version, text joined to one line', () => {
    const root = tree({
      VERSION: '0.1.1.0\n',
      'CHANGELOG.md': changelog(section('0.1.1.0', 'Second.', marker('newer_row_abc')), section('0.1.0.0', 'First.', marker('older_row_abc'))),
      'behavior-changes.d/older_row_abc.md': 'Older\n  change.\n',
      'behavior-changes.d/newer_row_abc.md': 'Newer change.\n',
    });
    const { text, problems } = build(root);
    expect(problems).toEqual([]);
    expect(rowsOf(text)).toEqual([
      { since: '0.1.0.0', id: 'older_row_abc', text: 'Older change.' },
      { since: '0.1.1.0', id: 'newer_row_abc', text: 'Newer change.' },
    ]);
    expect(releasesOf(text)).toEqual({ older_row_abc: '0.1.0.0', newer_row_abc: '0.1.1.0' });
  });

  test('stamping (VERSION newer than the top heading) dates pending changelog.d markers with VERSION', () => {
    const root = tree({
      VERSION: '0.1.1.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', 'First.', marker('older_row_abc'))),
      'changelog.d/feature-x.md': `**Faster sync.**\n\n${marker('faster_sync_abc')}\n`,
      'changelog.d/README.md': `Docs mention ${marker('readme_only_abc')} and are not a fragment.\n`,
      'behavior-changes.d/older_row_abc.md': 'Older change.\n',
      'behavior-changes.d/faster_sync_abc.md': 'Sync is faster now.\n',
    });
    const { text, problems } = build(root);
    expect(problems).toEqual([]);
    expect(rowsOf(text)).toEqual([
      { since: '0.1.0.0', id: 'older_row_abc', text: 'Older change.' },
      { since: '0.1.1.0', id: 'faster_sync_abc', text: 'Sync is faster now.' },
    ]);
  });

  test('problems: fragment without marker, marker without fragment, id repeating a table row, over-long text, bad filename', () => {
    const root = tree({
      VERSION: '0.1.0.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', marker('no_fragment_abc'), marker('old_table_row'), marker('too_long_abc'))),
      [NOTICE_FILE]: notice("{ since: '0.0.9.0', id: 'old_table_row', text: 'Released long ago.' },"),
      'behavior-changes.d/no_marker_abc.md': 'Nobody names me.\n',
      'behavior-changes.d/old_table_row.md': 'Same id as a table row.\n',
      'behavior-changes.d/too_long_abc.md': 'x'.repeat(2001),
      'behavior-changes.d/Bad-Name.md': 'Bad name.\n',
      'behavior-changes.d/notes.txt': 'Not markdown.\n',
    });
    const { problems } = build(root);
    expect(problems.sort()).toEqual([
      'behavior-changes.d/Bad-Name.md: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)',
      'behavior-changes.d/no_marker_abc.md has no <!-- behavior-change: no_marker_abc --> marker in a changelog.d fragment or the CHANGELOG, so no release would disclose it',
      'behavior-changes.d/notes.txt: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)',
      `behavior-changes.d/old_table_row.md repeats the id of a row in ${NOTICE_FILE}`,
      'behavior-changes.d/too_long_abc.md is 2001 characters; the notice renders at most 2000',
      `the marker <!-- behavior-change: no_fragment_abc --> names no behavior-changes.d/no_fragment_abc.md and no function row dated releasedIn('no_fragment_abc')`,
    ]);
  });

  test('text at exactly 2000 characters is accepted', () => {
    const root = tree({
      VERSION: '0.1.0.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', marker('cap_row_abc'))),
      'behavior-changes.d/cap_row_abc.md': 'y'.repeat(2000) + '\n',
    });
    expect(build(root).problems).toEqual([]);
  });

  test("releasedIn('<id>') function rows need a marker and take their release from BEHAVIOR_CHANGE_RELEASES", () => {
    const fnRow = "{ since: releasedIn('fn_row_abc'), id: 'fn_row_abc', text: (chain) => `chain ${chain}` },";
    const unmarked = build(tree({ VERSION: '0.1.0.0\n', 'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')), [NOTICE_FILE]: notice(fnRow) }));
    expect(unmarked.problems).toEqual([`the releasedIn('fn_row_abc') row in ${NOTICE_FILE} has no <!-- behavior-change: fn_row_abc --> marker, so no release would date it`]);

    const pending = build(tree({ VERSION: '0.1.0.0\n', 'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')), 'changelog.d/fn.md': `${marker('fn_row_abc')}\n`, [NOTICE_FILE]: notice(fnRow) }));
    expect(pending.problems).toEqual([]);
    expect(releasesOf(pending.text)).toEqual({});

    const released = build(tree({ VERSION: '0.1.1.0\n', 'CHANGELOG.md': changelog(section('0.1.1.0', marker('fn_row_abc')), section('0.1.0.0', 'First.')), [NOTICE_FILE]: notice(fnRow) }));
    expect(released.problems).toEqual([]);
    expect(rowsOf(released.text)).toEqual([]);
    expect(releasesOf(released.text)).toEqual({ fn_row_abc: '0.1.1.0' });
  });

  test('release in progress and release folded generate byte-identical text', () => {
    const fnRow = "{ since: releasedIn('fn_row_abc'), id: 'fn_row_abc', text: () => 'computed' },";
    const shared = {
      [NOTICE_FILE]: notice("{ since: '0.0.9.0', id: 'table_row_abc', text: 'Old.' },", fnRow),
      'behavior-changes.d/older_row_abc.md': 'Older change.\n',
      'behavior-changes.d/alpha_row_abc.md': 'Alpha change.\n',
      'behavior-changes.d/beta_row_abc.md': 'Beta\nchange.\n',
      'changelog.d/README.md': 'One file per PR.\n',
    };
    const released = section('0.1.0.0', 'First.', marker('older_row_abc'));
    const alpha = `**Alpha.**\n\n${marker('alpha_row_abc')}\n${marker('fn_row_abc')}`;
    const beta = `**Beta.**\n\n${marker('beta_row_abc')}`;
    const fragments = { 'changelog.d/a-alpha.md': `${alpha}\n`, 'changelog.d/b-beta.md': `${beta}\n` };
    const inProgress = build(tree({ ...shared, ...fragments, VERSION: '0.1.1.0\n', 'CHANGELOG.md': changelog(released) }));
    const folded = build(tree({ ...shared, VERSION: '0.1.1.0\n', 'CHANGELOG.md': changelog(section('0.1.1.0', alpha, '', beta), released) }));
    expect(inProgress.problems).toEqual([]);
    expect(folded.problems).toEqual([]);
    expect(folded.text).toBe(inProgress.text);
    expect(rowsOf(folded.text).map((r) => `${r.id}@${r.since}`)).toEqual(['[email protected]', '[email protected]', '[email protected]']);
    expect(releasesOf(folded.text)).toEqual({ older_row_abc: '0.1.0.0', alpha_row_abc: '0.1.1.0', fn_row_abc: '0.1.1.0', beta_row_abc: '0.1.1.0' });

    const notStamping = build(tree({ ...shared, ...fragments, VERSION: '0.1.0.0\n', 'CHANGELOG.md': changelog(released) }));
    expect(notStamping.problems).toEqual([]);
    expect(rowsOf(notStamping.text).map((r) => r.id)).toEqual(['older_row_abc']);
  });

  test('the same id marked in two releases is a problem', () => {
    const root = tree({
      VERSION: '0.1.1.0\n',
      'CHANGELOG.md': changelog(section('0.1.1.0', marker('twice_row_abc')), section('0.1.0.0', marker('twice_row_abc'))),
      'behavior-changes.d/twice_row_abc.md': 'Twice.\n',
    });
    expect(build(root).problems).toEqual(['twice_row_abc is marked in two releases (0.1.0.0 and 0.1.1.0)']);
  });

  test('a marker repeated among unreleased changes, or marked again after its release, is refused on the PR tree', () => {
    const twoFragments = build(tree({
      VERSION: '0.1.0.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')),
      'behavior-changes.d/dup_row_abc.md': 'Dup.\n',
      'changelog.d/a.md': `${marker('dup_row_abc')}\n`,
      'changelog.d/b.md': `${marker('dup_row_abc')}\n`,
    }));
    expect(twoFragments.problems).toEqual(['dup_row_abc is marked twice among the unreleased changes (changelog.d and ## [Unreleased]); the release would mark it twice']);
    const remarked = build(tree({
      VERSION: '0.1.0.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', marker('old_row_abc'))),
      'behavior-changes.d/old_row_abc.md': 'Old.\n',
      'changelog.d/a.md': `${marker('old_row_abc')}\n`,
    }));
    expect(remarked.problems).toEqual(['old_row_abc is marked again after release 0.1.0.0; a released id is never marked again']);
  });

  test('a changelog.d fragment whose front matter bumps anything but patch is refused, naming the file and the fix', () => {
    const base = { VERSION: '0.1.0.0\n', 'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')) };
    for (const bump of ['minor', 'major', "'micro'"]) {
      const { problems } = build(tree({ ...base, 'changelog.d/feature-x.md': `---\nbump: ${bump}\nimportant: security\n---\n**Faster sync.**\n` }));
      expect(problems).toEqual([`changelog.d/feature-x.md says bump: ${bump.replace(/'/g, '')}; gbrain releases are PATCH only and the release takes the highest bump in the batch, so delete the bump: line (or write bump: patch)`]);
    }
    for (const line of ['bump: minor # feature', '"bump": major']) {
      expect(build(tree({ ...base, 'changelog.d/feature-x.md': `---\n${line}\n---\n**Faster sync.**\n` })).problems.join('\n')).toContain('changelog.d/feature-x.md says bump: ');
    }
    expect(build(tree({ ...base, 'changelog.d/feature-x.md': '---\nbump: patch\n---\n**Faster sync.**\n' })).problems).toEqual([]);
    expect(build(tree({ ...base, 'changelog.d/feature-x.md': '**Faster sync.**\n\nbump: minor appears in prose here.\n' })).problems).toEqual([]);
  });

  test('a changelog.d fragment whose important: class is not security, regression or data-loss is refused, naming the three and the doc', () => {
    const base = { VERSION: '0.1.0.0\n', 'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')) };
    for (const [line, value] of [['important: blocker', 'blocker'], ["important: 'urgent'", 'urgent'], ['"important": Security', 'Security'], ['important:', ''], ['important: blocker # unblocks a crew', 'blocker']]) {
      const { problems } = build(tree({ ...base, 'changelog.d/fix-x.md': `---\n${line}\n---\n**Search works again.**\n` }));
      expect(problems).toEqual([`changelog.d/fix-x.md says important: ${value}; stable takes the fast path only for security, regression (in a release that is on stable) or data-loss, so write one of those or delete the important: line (docs/RELEASING.md#daily-stable-check)`]);
    }
    for (const value of ['security', 'regression', 'data-loss', "'data-loss'", 'regression # on stable']) {
      expect(build(tree({ ...base, 'changelog.d/fix-x.md': `---\nimportant: ${value}\n---\n**Search works again.**\n` })).problems).toEqual([]);
    }
    expect(build(tree({ ...base, 'changelog.d/fix-x.md': '**Search works again.**\n\nimportant: blocker appears in prose here.\n' })).problems).toEqual([]);
  });

  test('an id starting with a digit is refused, so the generated map never holds an unquoted numeric key', () => {
    const root = tree({
      VERSION: '0.1.0.0\n',
      'CHANGELOG.md': changelog(section('0.1.0.0', 'First.')),
      'behavior-changes.d/8123_sync.md': 'Sync.\n',
      'changelog.d/a.md': `${marker('8123_sync')}\n`,
    });
    expect(build(root).problems).toEqual([
      'the marker <!-- behavior-change: 8123_sync --> is not an id: lowercase letters, digits and _, starting with a letter (3-96 characters)',
      'behavior-changes.d/8123_sync.md: a fragment is named <id>.md, the id lowercase letters, digits and _, starting with a letter (3-96 characters)',
      "the marker <!-- behavior-change: 8123_sync --> names no behavior-changes.d/8123_sync.md and no function row dated releasedIn('8123_sync')",
    ]);
  });

  test('with [Unreleased] markers on the base, the release in progress orders ids as the fold writes them', () => {
    const shared = {
      'behavior-changes.d/frag_row_abc.md': 'From a fragment.\n',
      'behavior-changes.d/open_row_abc.md': 'From [Unreleased].\n',
    };
    const released = section('0.1.0.0', 'First.');
    const frag = `**Fragment.**\n\n${marker('frag_row_abc')}`;
    const open = `**Open.**\n\n${marker('open_row_abc')}`;
    const inProgress = build(tree({ ...shared, 'changelog.d/a.md': `${frag}\n`, VERSION: '0.1.1.0\n', 'CHANGELOG.md': changelog(`## [Unreleased]\n\n${open}\n`, released) }));
    const folded = build(tree({ ...shared, VERSION: '0.1.1.0\n', 'CHANGELOG.md': changelog(section('0.1.1.0', frag, '', open), released) }));
    expect(inProgress.problems).toEqual([]);
    expect(folded.problems).toEqual([]);
    expect(folded.text).toBe(inProgress.text);
  });
});

describe('main()', () => {
  const files = () => ({
    VERSION: '0.1.0.0\n',
    'CHANGELOG.md': changelog(section('0.1.0.0', marker('older_row_abc'))),
    'behavior-changes.d/older_row_abc.md': 'Older change.\n',
    'src/core/.keep': '',
  });

  test('--check: stale exits 1 without writing, fresh exits 0; a write makes it fresh', () => {
    const root = tree(files());
    const missing = run(root, ['--check']);
    expect(missing.code).toBe(1);
    expect(missing.out).toContain(`FAIL: ${OUT} is stale.`);
    expect(existsSync(join(root, OUT))).toBe(false);

    const write = run(root, []);
    expect(write.code).toBe(0);
    expect(write.out).toContain(`wrote ${OUT}`);
    expect(readFileSync(join(root, OUT), 'utf8')).toBe(build(root).text);
    expect(run(root, []).out).toContain('unchanged');

    const fresh = run(root, ['--check']);
    expect(fresh.code).toBe(0);
    expect(fresh.out).toContain('is fresh');

    writeFileSync(join(root, OUT), readFileSync(join(root, OUT), 'utf8').replace("since: '0.1.0.0'", "since: '0.0.1.0'"));
    expect(run(root, ['--check']).code).toBe(1);
  });

  test('a fragment problem exits 1 with FAIL/Why/Fix and writes nothing', () => {
    const root = tree({ ...files(), 'behavior-changes.d/orphan_row_abc.md': 'No marker.\n' });
    const r = run(root, []);
    expect(r.code).toBe(1);
    expect(r.out).toContain('FAIL: 1 behavior-change fragment problem(s):');
    expect(r.out).toContain('Why:');
    expect(r.out).toContain('Fix:');
    expect(existsSync(join(root, OUT))).toBe(false);
  });

  test('an unknown argument is a usage error', () => {
    expect(run(tree(files()), ['--nope']).code).toBe(2);
  });
});