Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.4 KB
Raw Blame
/**
 * BrainEngine parity coverage list stays current.
 *
 * Authoring gate (docs/TESTING.md#authoring-gate):
 *  - Contract: test/engine-parity/coverage.tsv equals the generator output,
 *    so the parity number (covered N/198) in review is real.
 *  - Regression: a new parity case, a new or renamed BrainEngine method, or
 *    a hand edit of the list that leaves the checked-in number stale.
 *  - Why existing coverage misses it: test/engine-surface-coverage.test.ts
 *    asks "is the method called anywhere in test/", not "is it compared
 *    across engine arms".
 *    Also pins that every parity file selects its arms with `testBackends()`
 *    and has a row in test/postgres-unit-arms.txt, so its Postgres arm runs
 *    in CI (the unit lanes unset DATABASE_URL and run only the PGLite arm).
 *    Also self-tests test/engine-parity/arm-capabilities.ts: no arm lacks
 *    raw_sql yet, so the harness's refusal check has no live caller until the
 *    Rust arm lands, and these assertions keep it honest meanwhile.
 *  - Seam: none (pure file generation).
 */
import { describe, expect, test } from 'bun:test';
import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { buildCoverage, COVERAGE_FILE, FAMILIES, parityDeclarations } from './coverage.ts';
import { armCapabilities, isCapabilityRefusal, missingCapability, PARITY_ARMS } from './arm-capabilities.ts';

describe('engine parity coverage list', () => {
  test('coverage.tsv is fresh (regenerate: bun test/engine-parity/coverage.ts --write)', () => {
    const report = buildCoverage();
    expect(readFileSync(COVERAGE_FILE, 'utf8')).toBe(report.text);
  });

  test('every family member is a BrainEngine method and every method has one family', () => {
    const report = buildCoverage();
    const assigned = Object.values(FAMILIES).flat();
    expect([...assigned].sort()).toEqual([...report.methods].sort());
    expect(new Set(assigned).size).toBe(assigned.length);
  });

  test('every parity case declares at least one method, with no duplicates', () => {
    for (const decl of parityDeclarations()) {
      expect({ name: decl.name, empty: decl.methods.length === 0 }).toEqual({ name: decl.name, empty: false });
      expect({ name: decl.name, dupes: decl.methods.length - new Set(decl.methods).size }).toEqual({ name: decl.name, dupes: 0 });
    }
  });
  test('every parity file runs every arm: testBackends() and a Postgres lane row', () => {
    const dir = import.meta.dir;
    const files = readdirSync(dir).filter((f) => f.endsWith('.test.ts') && f !== 'coverage.test.ts').sort();
    expect(files.length).toBeGreaterThan(0);
    const lanes = new Set(readFileSync(join(dir, '..', 'postgres-unit-arms.txt'), 'utf8').split('\n').map((l) => l.trim()));
    for (const file of files) {
      const text = readFileSync(join(dir, file), 'utf8');
      const row = `test/engine-parity/${file}`;
      expect({ file, selectsArms: text.includes('parityArms(testBackends())'), laned: lanes.has(row) })
        .toEqual({ file, selectsArms: true, laned: true });
    }
  });

  test('arm capabilities: SQL arms run raw SQL, only Postgres holds the schema lock, Rust has neither yet', () => {
    expect(PARITY_ARMS.map((arm) => [arm, [...armCapabilities(arm)].sort()])).toEqual([
      ['pglite', ['raw_sql']], ['postgres', ['raw_sql', 'schema_migration_lock']], ['rust', []],
    ]);
    expect([missingCapability('raw_sql'), missingCapability('schema_migration_lock')]).toEqual([
      { kind: 'refuses', label: 'refuses:raw_sql' }, { kind: 'n/a', label: 'n/a:postgres-only' },
    ]);
  });

  test('isCapabilityRefusal accepts only engine_capability_missing naming that capability', () => {
    const refusal = Object.assign(new Error('raw SQL is not available on this engine'), { code: 'engine_capability_missing', reason: 'raw_sql' });
    const viaEnvelope = Object.assign(new Error('x'), { envelope: { code: 'engine_capability_missing', detail: { reason: 'raw_sql' } } });
    expect([
      isCapabilityRefusal(refusal, 'raw_sql'),
      isCapabilityRefusal(viaEnvelope, 'raw_sql'),
      isCapabilityRefusal(refusal, 'schema_migration_lock'),
      isCapabilityRefusal(Object.assign(new Error('x'), { code: 'engine_unavailable', reason: 'raw_sql' }), 'raw_sql'),
      isCapabilityRefusal(new Error('engine_capability_missing raw_sql'), 'raw_sql'),
      isCapabilityRefusal(null, 'raw_sql'),
    ]).toEqual([true, true, false, false, false, false]);
  });
});