Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.5 KB
Raw Blame
#!/usr/bin/env bun
/**
 * check:behavior-since — a BEHAVIOR_CHANGES row with `since: 'TBD'` never ships.
 *
 *   bun run check:behavior-since              verify / CI: refuse TBD rows on a stamped tree or master
 *   bun scripts/check-behavior-since.ts --stamped
 *                                             restamp / release: refuse any TBD row
 *
 * Unstamped development branches write their rows as since: 'TBD' and the
 * merge-slot stamp gives them the release. compareReleases ranks 'TBD' below
 * every release, so a TBD row that ships is never disclosed by the upgrade
 * notice. Any TBD row is refused when:
 *   - --stamped is passed (release:restamp after it rewrites the rows, the
 *     Release workflow before it publishes);
 *   - the run is on master (GITHUB_REF=refs/heads/master, or HEAD is the base
 *     ref's commit), or the base ref itself carries a TBD row;
 *   - CHANGELOG.md has a release header for VERSION and VERSION differs from
 *     the base ref's VERSION (a stamped PR head, stamped by tool or by hand).
 * Otherwise VERSION equals the base's (an unstamped branch) and TBD rows pass.
 *
 * Under .gstack/ship-policy.json `merge: direct` versions are written at release, which never edits this file, so
 * a TBD row is refused on every tree: a plain-text row is a behavior-changes.d/<id>.md fragment and a function row
 * is dated `since: releasedIn('<id>')` (behavior-changes.d/README.md). With --stamped (the Release workflow) the
 * release commit must also hold no unfolded changelog.d fragment and a fresh behavior-change table, and a missing or
 * unparsable .gstack/ship-policy.json is refused rather than read as "not direct".
 *
 * Base ref: $GBRAIN_RELEASE_BASE_REF, default origin/master. When it is
 * unavailable the check fails under CI=true and skips locally.
 * Exit: 0 ok or skipped, 1 refused, 2 usage. Docs: docs/RELEASING.md#release-restamp
 */
import { spawnSync } from 'node:child_process';
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { build, CHANGELOG_FRAGMENT_DIR, OUT } from './build-behavior-changes.ts';

export const NOTICE_FILE = 'src/core/behavior-change-notice.ts';
const POLICY_FILE = '.gstack/ship-policy.json';
const TBD = /since:\s*'TBD'/;
const SEE = 'See:  docs/RELEASING.md#release-restamp';

/** 1-based line numbers of the since: 'TBD' rows in the notice source. */
export function tbdLines(text: string): number[] {
  return text.split('\n').flatMap((line, i) => (TBD.test(line) ? [i + 1] : []));
}

export function main(argv: string[], opts: { cwd?: string; env?: Record<string, string | undefined>; log?: (line: string) => void } = {}): number {
  const root = opts.cwd ?? process.cwd();
  const env = opts.env ?? process.env;
  const log = opts.log ?? ((line: string) => console.log(line));
  const unknown = argv.filter((a) => a !== '--stamped');
  if (unknown.length) {
    log(`usage: bun scripts/check-behavior-since.ts [--stamped]   (unknown: ${unknown.join(' ')})`);
    return 2;
  }
  const git = (...args: string[]) => {
    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
    return { ok: r.status === 0, out: (r.stdout ?? '').trim() };
  };
  const read = (file: string) => (existsSync(join(root, file)) ? readFileSync(join(root, file), 'utf8') : '');

  if (argv.includes('--stamped') && !existsSync(join(root, NOTICE_FILE))) {
    log(`FAIL: ${NOTICE_FILE} is missing, so its rows cannot be checked before stamping or release.`);
    log('Fix:  check the file out (a sparse checkout must include it), then rerun.');
    log(SEE);
    return 1;
  }
  const policy = (() => { try { return { merge: JSON.parse(read(POLICY_FILE)).merge }; } catch (e) { return { error: existsSync(join(root, POLICY_FILE)) ? `cannot be parsed (${e instanceof Error ? e.message : String(e)})` : 'is missing' }; } })();
  if ('error' in policy && argv.includes('--stamped')) {
    log(`FAIL: ${POLICY_FILE} ${policy.error}, so this check cannot tell whether the release commit must have folded its changelog.d fragments and regenerated its behavior-change table.`);
    log('Why:  --stamped guards a stamp or a release; reading no policy as `merge` unset would skip those checks without saying so.');
    log(`Fix:  restore ${POLICY_FILE} from master (git checkout origin/master -- ${POLICY_FILE}; a sparse checkout must include .gstack), then rerun.`);
    log(SEE);
    return 1;
  }
  const direct = !('error' in policy) && policy.merge === 'direct';
  if (direct && argv.includes('--stamped')) {
    const unfolded = existsSync(join(root, CHANGELOG_FRAGMENT_DIR)) ? readdirSync(join(root, CHANGELOG_FRAGMENT_DIR)).filter((f) => f.endsWith('.md') && f !== 'README.md') : [];
    const table = build(root);
    const stale = table.problems.length > 0 || read(OUT) !== table.text;
    if (unfolded.length || stale) {
      log(`FAIL: the release commit (VERSION ${read('VERSION').trim()}) ${unfolded.length ? `still holds ${unfolded.length} unfolded ${CHANGELOG_FRAGMENT_DIR} fragment(s): ${unfolded.join(', ')}` : `has a stale ${OUT}`}${table.problems.length ? ` (${table.problems[0]})` : ''}.`);
      log('Why:  a release folds every changelog fragment into its CHANGELOG section and dates its behavior-change rows; a commit that did not is not a release.');
      log('Fix:  open the release again with gstack-release-stamp open, which stamps a fresh checkout of master; never edit a release/<version> branch by hand.');
      log('See:  docs/RELEASING.md#releases-per-batch');
      return 1;
    }
  }
  const lines = tbdLines(read(NOTICE_FILE));
  if (direct && lines.length) {
    log(`FAIL: ${lines.length} BEHAVIOR_CHANGES row(s) in ${NOTICE_FILE} say since: 'TBD' (line ${lines.join(', ')}).`);
    log('Why:  under merge: direct the release writes versions and never edits this file, so a TBD row would never be dated or disclosed.');
    log("Fix:  move a plain-text row to behavior-changes.d/<id>.md and name <!-- behavior-change: <id> --> in your changelog.d fragment; a function row keeps its line as since: releasedIn('<id>') with the same marker (bun run release:unstamp converts a branch).");
    log('See:  behavior-changes.d/README.md');
    return 1;
  }
  if (lines.length === 0) {
    log(`check-behavior-since: ok (no since: 'TBD' row in ${NOTICE_FILE})`);
    return 0;
  }
  const version = read('VERSION').trim();
  const refuse = (context: string) => {
    log(`FAIL: ${lines.length} BEHAVIOR_CHANGES row(s) in ${NOTICE_FILE} still say since: 'TBD' (line ${lines.join(', ')}) on ${context}.`);
    log("Why:  compareReleases ranks 'TBD' below every release, so a shipped TBD row is never shown by the upgrade notice; the merge-slot stamp must give each row its release.");
    log(`Fix:  run bun run release:restamp (it rewrites every since: 'TBD' to the new VERSION), or replace each since: 'TBD' with since: '${version}' by hand, then rerun bun run check:behavior-since.`);
    log(SEE);
    return 1;
  };

  if (argv.includes('--stamped')) return refuse(`a tree being stamped or released (VERSION ${version})`);
  if (env.GITHUB_REF === 'refs/heads/master') return refuse(`master (VERSION ${version})`);

  const ref = env.GBRAIN_RELEASE_BASE_REF || 'origin/master';
  const baseCommit = git('rev-parse', '--verify', '-q', `${ref}^{commit}`);
  if (!baseCommit.ok) {
    const msg = `check-behavior-since: base ref ${ref} is not available (git fetch origin master)`;
    if (env.CI === 'true') {
      log(`FAIL: ${msg}`);
      log('Why:  without the base ref the check cannot tell an unstamped branch from a stamped one.');
      log('Fix:  fetch it in the workflow (git fetch --no-tags --depth=1 origin +refs/heads/master:refs/remotes/origin/master)');
      log(SEE);
      return 1;
    }
    log(`skip: ${msg}`);
    log(`GBRAIN_CHECK_SKIPPED: base ref ${ref} unavailable`);
    return 0;
  }
  if (git('rev-parse', 'HEAD').out === baseCommit.out) return refuse(`the base ref ${ref} itself (VERSION ${version})`);
  const base = git('show', `${ref}:${NOTICE_FILE}`);
  if (base.ok && tbdLines(base.out).length > 0) return refuse(`a tree whose base ${ref} already ships a TBD row`);
  const baseVersion = git('show', `${ref}:VERSION`).out.trim();
  const header = read('CHANGELOG.md').split('\n').some((line) => line.startsWith(`## [${version}]`));
  if (header && version !== baseVersion) return refuse(`a stamped tree (VERSION ${version} has a CHANGELOG release header; ${ref} is at ${baseVersion})`);

  log(`check-behavior-since: ok (${lines.length} since: 'TBD' row(s) on an unstamped branch: VERSION ${version} equals ${ref}'s; the merge-slot stamp replaces them)`);
  return 0;
}

if (import.meta.main) process.exit(main(process.argv.slice(2)));