Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.8 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Test env opt-in guard (docs/TESTING.md#test-isolation-lint-and-helpers).
 *
 * test/helpers/operator-env-preload.ts deletes every GBRAIN_* variable outside
 * its keep-lists before any test file loads. A test that gates execution on a
 * stripped name (`describe.skipIf(!process.env.GBRAIN_X)`, `if (env) return`,
 * a top-level constant used that way) can never see it set, so the gate is a
 * silent no-op: six opt-ins, including `bun run test:compile-smoke`, were dead
 * this way. This guard parses every test file under test/ and evals/ with the
 * TypeScript AST and fails on an execution-gating read of a GBRAIN_* name the
 * scrub strips, unless the same file assigns that name itself. Names that
 * src/ reads are product configuration, not test opt-ins: the scrub removing
 * them is the hermeticity it exists for, so a test asserting their absence is
 * not flagged.
 *
 * The policy (keep-lists, RENAMED map, naming rule) is imported from
 * test/helpers/operator-env-policy.ts, the module the preload applies.
 *
 * Second rule (GBRA-79): a file the unit matrix loads (anything scanned that
 * is not `*.serial.test.ts`, not under test/e2e/ and not a `*-preload.ts`)
 * must not delete or assign `process.env.GBRAIN_PGLITE_SNAPSHOT` at module
 * scope. scripts/test-shard.sh runs a whole unit shard (hundreds of files) in
 * ONE bun process, so a module-scope delete persists for every later file in
 * the shard and each of their in-memory PGLite engines falls back to a cold
 * initSchema() (~3 s): three such files cost ≈ +350 s per poisoned shard and
 * pushed shards past the 22-minute job timeout. Serial and E2E files get a
 * process per file, and a preload is process-wide by design
 * (operator-env-preload.ts honours GBRAIN_NO_SNAPSHOT=1 there). The accepted
 * shape is a beforeAll that saves and deletes the value and an afterAll that
 * restores it (or test/helpers/with-snapshot.ts per test).
 *
 * Seam: GBRAIN_GUARD_ROOT (fixture tree root).
 */
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
import { join, relative } from 'node:path';
import ts from 'typescript';
import { isStripped } from '../test/helpers/operator-env-policy';

const ROOT = process.env.GBRAIN_GUARD_ROOT ?? join(import.meta.dir, '..');
const ANCHOR = 'docs/TESTING.md#test-isolation-lint-and-helpers';
const SCAN_DIRS = ['test', 'evals'];
const SKIP_DIRS = new Set(['node_modules', 'guards']);
const GATE_CALLS = new Set(['skipIf', 'if', 'todoIf', 'runIf']);
const TEST_CALL = /^(describe|test|it)(\.(skip|todo|only|if|skipIf))?$/;
const SNAPSHOT_ENV = 'GBRAIN_PGLITE_SNAPSHOT';
const OWN_PROCESS_FILE = /(\.serial\.test\.ts$|-preload\.ts$|(^|\/)test\/e2e\/)/;

function tsFiles(dir: string): string[] {
  if (!existsSync(dir)) return [];
  const out: string[] = [];
  for (const entry of readdirSync(dir).sort()) {
    const full = join(dir, entry);
    if (statSync(full).isDirectory()) {
      if (!SKIP_DIRS.has(entry)) out.push(...tsFiles(full));
    } else if (/\.(ts|tsx|mts)$/.test(entry) && !entry.endsWith('.d.ts')) {
      out.push(full);
    }
  }
  return out;
}

/** `process.env.NAME` / `process.env['NAME']` → NAME, else null. */
function envName(node: ts.Node): string | null {
  let target: ts.Expression;
  let name: string;
  if (ts.isPropertyAccessExpression(node)) {
    target = node.expression;
    name = node.name.text;
  } else if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) {
    target = node.expression;
    name = node.argumentExpression.text;
  } else {
    return null;
  }
  if (!ts.isPropertyAccessExpression(target) || target.name.text !== 'env') return null;
  if (!ts.isIdentifier(target.expression) || target.expression.text !== 'process') return null;
  return name;
}

const isAssignmentTarget = (node: ts.Node): boolean => {
  const parent = node.parent;
  if (ts.isDeleteExpression(parent)) return true;
  return ts.isBinaryExpression(parent)
    && parent.left === node
    && parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment
    && parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment;
};

/** Whether `node` sits outside every function body: evaluated once, at module load. */
const atModuleScope = (node: ts.Node): boolean => {
  for (let cur = node.parent; cur; cur = cur.parent) {
    if (ts.isFunctionLike(cur)) return false;
  }
  return true;
};

const contains = (outer: ts.Node | undefined, inner: ts.Node): boolean =>
  !!outer && inner.pos >= outer.pos && inner.end <= outer.end;

function calleeText(call: ts.CallExpression, sf: ts.SourceFile): string {
  let callee: ts.Expression = call.expression;
  while (ts.isCallExpression(callee)) callee = callee.expression;
  return callee.getText(sf);
}

/** Whether an if-branch stops or selects test execution (return, throw, a test registration, process.exit). */
function branchGates(stmt: ts.Statement | undefined, sf: ts.SourceFile): boolean {
  if (!stmt) return false;
  let found = false;
  const visit = (node: ts.Node): void => {
    if (found || ts.isFunctionLike(node)) return;
    if (ts.isReturnStatement(node) || ts.isThrowStatement(node)) found = true;
    else if (ts.isCallExpression(node)) {
      const text = calleeText(node, sf);
      if (TEST_CALL.test(text) || text === 'process.exit') found = true;
    }
    if (!found) ts.forEachChild(node, visit);
  };
  visit(stmt);
  return found;
}

const selectsTest = (expr: ts.Expression, sf: ts.SourceFile): boolean =>
  TEST_CALL.test(expr.getText(sf));

/**
 * Whether `node` (an env read, or a reference to a value derived from one)
 * gates execution. Walks up to the enclosing statement; a `const X = <read>`
 * or `return <read>` makes every use of X / the returning function a gate
 * candidate in turn.
 */
function gates(node: ts.Node, sf: ts.SourceFile, seen: Set<string>): boolean {
  for (let child = node, cur = node.parent; cur; child = cur, cur = cur.parent) {
    if (ts.isCallExpression(cur) && cur.arguments.some(a => contains(a, child))) {
      const callee = cur.expression;
      if (ts.isPropertyAccessExpression(callee) && GATE_CALLS.has(callee.name.text)) return true;
      continue;
    }
    if (ts.isIfStatement(cur) && contains(cur.expression, node)) {
      return branchGates(cur.thenStatement, sf) || branchGates(cur.elseStatement, sf);
    }
    if (ts.isConditionalExpression(cur) && contains(cur.condition, node)) {
      return selectsTest(cur.whenTrue, sf) || selectsTest(cur.whenFalse, sf);
    }
    if (ts.isVariableDeclaration(cur) && ts.isIdentifier(cur.name) && contains(cur.initializer, node)) {
      return usesGate(cur.name.text, sf, seen);
    }
    if (ts.isReturnStatement(cur)) {
      const fn = enclosingFunctionName(cur);
      return fn ? usesGate(fn, sf, seen) : false;
    }
    if (ts.isFunctionLike(cur) || ts.isSourceFile(cur)) return false;
  }
  return false;
}

function enclosingFunctionName(node: ts.Node): string | null {
  for (let cur = node.parent; cur; cur = cur.parent) {
    if (ts.isFunctionDeclaration(cur)) return cur.name?.text ?? null;
    if (ts.isArrowFunction(cur) || ts.isFunctionExpression(cur)) {
      const decl = cur.parent;
      return ts.isVariableDeclaration(decl) && ts.isIdentifier(decl.name) ? decl.name.text : null;
    }
    if (ts.isFunctionLike(cur)) return null;
  }
  return null;
}

function usesGate(name: string, sf: ts.SourceFile, seen: Set<string>): boolean {
  if (seen.has(name)) return false;
  seen.add(name);
  let found = false;
  const visit = (node: ts.Node): void => {
    if (found) return;
    if (ts.isIdentifier(node) && node.text === name && !isDeclarationName(node) && gates(node, sf, seen)) found = true;
    else ts.forEachChild(node, visit);
  };
  visit(sf);
  return found;
}

const isDeclarationName = (node: ts.Identifier): boolean => {
  const parent = node.parent;
  return (ts.isVariableDeclaration(parent) || ts.isFunctionDeclaration(parent) || ts.isParameter(parent))
    && parent.name === node;
};

type Kind = 'stripped' | 'snapshot_module_scope';
interface Finding { kind: Kind; file: string; line: number; name: string; verb?: string }

function scanFile(path: string): Finding[] {
  const text = readFileSync(path, 'utf8');
  if (!text.includes('GBRAIN_')) return [];
  const sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true);
  const file = relative(ROOT, path);
  const matrixFile = !OWN_PROCESS_FILE.test(file);
  const assigned = new Set<string>();
  const reads: Array<{ node: ts.Node; name: string }> = [];
  const findings: Finding[] = [];
  const lineOf = (node: ts.Node): number => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
  const visit = (node: ts.Node): void => {
    const name = envName(node);
    if (name && name.startsWith('GBRAIN_')) {
      if (isAssignmentTarget(node)) {
        assigned.add(name);
        if (matrixFile && name === SNAPSHOT_ENV && atModuleScope(node)) {
          const verb = ts.isDeleteExpression(node.parent) ? 'deletes' : 'assigns';
          findings.push({ kind: 'snapshot_module_scope', file, line: lineOf(node), name, verb });
        }
      } else {
        reads.push({ node, name });
      }
    }
    ts.forEachChild(node, visit);
  };
  visit(sf);
  for (const { node, name } of reads) {
    if (!isStripped(name) || assigned.has(name) || PRODUCT.has(name)) continue;
    if (!gates(node, sf, new Set())) continue;
    findings.push({ kind: 'stripped', file, line: lineOf(node), name });
  }
  return findings;
}

function productNames(): Set<string> {
  const names = new Set<string>();
  for (const file of tsFiles(join(ROOT, 'src'))) {
    for (const m of readFileSync(file, 'utf8').matchAll(/\bGBRAIN_[A-Z0-9_]+/g)) names.add(m[0]);
  }
  return names;
}

const PRODUCT = productNames();
const findings = SCAN_DIRS.flatMap(dir => tsFiles(join(ROOT, dir))).flatMap(scanFile);
if (findings.length === 0) {
  console.log('✓ test env opt-ins: no test gates execution on a GBRAIN_* name the operator-env scrub strips; no matrix file changes GBRAIN_PGLITE_SNAPSHOT at module scope');
  process.exit(0);
}
const stripped = findings.filter(f => f.kind === 'stripped');
const leaks = findings.filter(f => f.kind === 'snapshot_module_scope');
if (stripped.length > 0) {
  for (const f of stripped) {
    console.error(`FAIL [test_env_opt_in_stripped]: ${f.file}:${f.line} gates execution on ${f.name}, which the operator-env scrub deletes before tests run, so this gate can never fire.`);
  }
  console.error('Why: test/helpers/operator-env-preload.ts strips every GBRAIN_* name outside its keep-lists (test/helpers/operator-env-policy.ts); an opt-in under such a name is a silent skip.');
  console.error('Fix: rename the opt-in to GBRAIN_TEST_<AREA>_<WHAT> (paid: GBRAIN_TEST_LIVE_<WHAT>) and add the old name to RENAMED in test/helpers/operator-env-policy.ts, or add a KEEP_EXACT row there with its reason. GBRAIN_TEST_KEEP_AMBIENT_ENV=1 disables the scrub for local debugging only.');
}
if (leaks.length > 0) {
  for (const f of leaks) {
    console.error(`FAIL [test_env_snapshot_module_scope]: ${f.file}:${f.line} ${f.verb} process.env.${f.name} at module scope, which leaks into every later test file in the same bun process.`);
  }
  console.error('Why: scripts/test-shard.sh runs a whole unit shard (hundreds of files) in ONE bun process, so a module-scope change to GBRAIN_PGLITE_SNAPSHOT persists for every file after this one and each of their in-memory PGLite engines cold-boots initSchema() (~3 s each, about +350 s per poisoned shard) instead of restoring the snapshot; *.serial.test.ts and test/e2e/ files get their own process and *-preload.ts files are process-wide by design, so those are exempt.');
  console.error('Fix: move the change into hooks: beforeAll saves process.env.GBRAIN_PGLITE_SNAPSHOT and deletes it, afterAll restores the saved value (delete it when the saved value was undefined), or scope it per test with withColdPglite / withSnapshotValue from test/helpers/with-snapshot.ts.');
}
console.error(`Docs: ${ANCHOR}`);
process.exit(1);