Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.1 KB
Raw Blame
/**
 * D6 (docs/designs/RUST_ENGINE.md): scripts/check-engine-raw-sql-ratchet.ts
 * counts raw SQL per file under src/ outside the engines and fails when a
 * count rises above its baseline row, when a file has no row, or when a count
 * falls without its row falling too. The engine-kind branch ratchet shares the
 * same runner (scripts/lib/count-ratchet.ts) and is covered here too.
 */
import { afterEach, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { countFile, isEngineFile } from '../../scripts/check-engine-raw-sql-ratchet.ts';
import { countFile as countKinds } from '../../scripts/check-engine-kind-branches.ts';

const REPO = resolve(import.meta.dir, '..', '..');
const RAW = { guard: join(REPO, 'scripts', 'check-engine-raw-sql-ratchet.ts'), baseline: 'scripts/engine-raw-sql-baseline.tsv' };
const KIND = { guard: join(REPO, 'scripts', 'check-engine-kind-branches.ts'), baseline: 'scripts/engine-kind-branches-baseline.tsv' };
const dirs: string[] = [];
afterEach(() => {
  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
});

function tree(baselineRel: string, files: Record<string, string>): string {
  const root = mkdtempSync(join(tmpdir(), 'gbrain-engine-raw-sql-ratchet-'));
  dirs.push(root);
  for (const [rel, body] of Object.entries({ [baselineRel]: '# baseline\n', ...files })) {
    mkdirSync(join(root, rel, '..'), { recursive: true });
    writeFileSync(join(root, rel), body);
  }
  return root;
}

function run(guard: string, root: string, args: string[] = []) {
  const r = spawnSync('bun', [guard, ...args], { encoding: 'utf8', env: { ...process.env, GBRAIN_GUARD_ROOT: root } });
  return { code: r.status, out: `${r.stdout}\n${r.stderr}` };
}

describe('check-engine-raw-sql-ratchet.ts: what counts', () => {
  test('executeRaw, executeRawDirect and executeRawJsonb count on any receiver', () => {
    const c = countFile([
      'declare const engine: any, tx: any, exec: any;',
      'engine.executeRaw("SELECT 1");',
      'tx.executeRawDirect(q);',
      'exec.executeRawJsonb("UPDATE pages SET frontmatter = $1::jsonb", [o]);',
      'const f = engine.executeRaw;',
    ].join('\n'));
    expect(c.execute_raw).toBe(3);
  });

  test('literal bracket-access calls count like the dot spelling', () => {
    const c = countFile([
      'declare const e: any, db: any;',
      'e["executeRaw"]("SELECT 1");',
      'e[`executeRawJsonb`]("UPDATE pages SET frontmatter = $1::jsonb", [o]);',
      'db["unsafe"](text);',
      'db["query"]("SELECT id FROM pages");',
      'e[name]("SELECT 1");',
    ].join('\n'));
    expect(c.execute_raw).toBe(2);
    expect(c.driver_call).toBe(2);
  });

  test('an executeRaw tag counts once, as execute_raw', () => {
    expect(countFile('declare const e: any;\ne.executeRaw`SELECT id FROM pages`;')).toEqual({ execute_raw: 1, sql_template: 0, driver_call: 0 });
  });

  test('SQL tagged templates count; non-SQL templates and comments do not', () => {
    const c = countFile([
      'declare const sql: any, html: any;',
      'sql`SELECT id FROM pages WHERE slug = ${s}`;',
      'html`<p>select a page from the list</p>`;',
      '// sql`SELECT id FROM pages`',
      'const plain = `SELECT id FROM pages`;',
    ].join('\n'));
    expect(c.sql_template).toBe(1);
    expect(c.execute_raw).toBe(0);
  });

  test('driver_call: unsafe always, query and exec only with SQL text', () => {
    const c = countFile([
      'declare const db: any, re: any;',
      'db.unsafe(text);',
      'db.query("SELECT id FROM pages WHERE id = $1", [1]);',
      'db.exec("CREATE TABLE t (a int)");',
      'db.query(text);',
      're.exec("hello world");',
    ].join('\n'));
    expect(c.driver_call).toBe(3);
  });

  // Value: protects=SQL built by concatenation, interpolation, casts or wrapped callees still counts; fails_when=literalText or calleeName stops unwrapping a supported form; why_new=earlier cases use direct literals and plain callees only; seam=none
  test('concatenated, interpolated and wrapped SQL still counts; non-SQL text does not', () => {
    const c = countFile([
      'declare const db: any, e: any, t: string;',
      'db.query("SELECT id " + "FROM pages WHERE slug = " + t);',
      'db.query(`SELECT ${t} FROM pages`);',
      'db.query(("SELECT 1") as string);',
      '(db.query)("SELECT 1");',
      'db!.unsafe(t);',
      '(e!.executeRaw)("SELECT 1");',
      'db.query("hello " + t);',
      'db.exec(`say ${t} twice`);',
    ].join('\n'));
    expect(c).toEqual({ execute_raw: 1, sql_template: 0, driver_call: 5 });
  });

  test('the engines are out of scope; everything else under src/ is in', () => {
    for (const rel of [
      'src/core/engine.ts', 'src/core/pglite-engine.ts', 'src/core/postgres-engine.ts',
      'src/core/pglite-engine/pages.ts', 'src/core/postgres-engine/facts.ts', 'src/core/engine-sql/pages.ts',
    ]) expect(isEngineFile(rel)).toBe(true);
    for (const rel of ['src/core/search/hybrid.ts', 'src/commands/doctor.ts', 'src/core/engine-factory.ts'])
      expect(isEngineFile(rel)).toBe(false);
  });
});

describe('check-engine-raw-sql-ratchet.ts: shrink-only baseline', () => {
  const site = 'declare const e: any;\nexport const a = () => e.executeRaw("SELECT 1");\n';

  test('a matching baseline passes and engine files are never counted', () => {
    const root = tree(RAW.baseline, {
      [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\n',
      'src/core/a.ts': site,
      'src/core/engine-sql/pages.ts': site + site,
      'src/core/pglite-engine.ts': site,
    });
    const r = run(RAW.guard, root);
    expect(r.code).toBe(0);
    expect(r.out).toContain('check-engine-raw-sql-ratchet: ok (1 sites in 1 files: execute_raw 1, sql_template 0, driver_call 0)');
  });

  test('a rise above the row fails with the fix', () => {
    const root = tree(RAW.baseline, {
      [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\n',
      'src/core/a.ts': site + 'export const b = () => e.executeRaw("SELECT 2");\n',
    });
    const r = run(RAW.guard, root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('FAIL: src/core/a.ts execute_raw: baseline 1, actual 2');
    expect(r.out).toContain('typed engine method');
  });

  test('a new file with no row fails', () => {
    const root = tree(RAW.baseline, { 'src/commands/new.ts': site });
    const r = run(RAW.guard, root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('FAIL: src/commands/new.ts execute_raw: baseline 0, actual 1');
  });

  test('a stale row fails, and --prune lowers it without raising anything', () => {
    const root = tree(RAW.baseline, {
      [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t3\nsrc/core/gone.ts\tsql_template\t2\n',
      'src/core/a.ts': site,
    });
    const r = run(RAW.guard, root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('stale row: src/core/a.ts execute_raw: baseline 3, actual 1');
    expect(r.out).toContain('stale row: src/core/gone.ts sql_template: baseline 2, actual 0');
    const p = run(RAW.guard, root, ['--prune']);
    expect(p.out).toContain('pruned 2 row(s)');
    expect(readFileSync(join(root, RAW.baseline), 'utf8')).toBe('# baseline\nsrc/core/a.ts\texecute_raw\t1\n');
    expect(run(RAW.guard, root).code).toBe(0);
  });

  test('--prune never adds a row for a rise', () => {
    const root = tree(RAW.baseline, { 'src/core/a.ts': site });
    run(RAW.guard, root, ['--prune']);
    expect(readFileSync(join(root, RAW.baseline), 'utf8')).toBe('# baseline\n');
    expect(run(RAW.guard, root).code).toBe(1);
  });

  test('a missing baseline fails closed', () => {
    const root = tree(RAW.baseline, { 'src/core/a.ts': site });
    rmSync(join(root, RAW.baseline));
    const r = run(RAW.guard, root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('baseline file missing');
  });

  test('duplicate and malformed rows fail', () => {
    const root = tree(RAW.baseline, {
      [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\nsrc/core/a.ts\texecute_raw\t1\nsrc/core/b.ts\tnot_a_metric\t1\n',
      'src/core/a.ts': site,
    });
    const r = run(RAW.guard, root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('duplicate row for src/core/a.ts execute_raw');
    expect(r.out).toContain('malformed row');
  });

  // Value: protects=a baseline row with a bad count or shape fails instead of loosening the ratchet; fails_when=parseRows accepts zero, negative, fractional or text counts, wrong columns or an empty path; why_new=the malformed case above covers unknown metrics only; seam=none
  test('rows with a bad count, the wrong column count or an empty path are malformed', () => {
    for (const row of ['src/core/a.ts\texecute_raw\t0', 'src/core/a.ts\texecute_raw\t-1', 'src/core/a.ts\texecute_raw\t1.5',
      'src/core/a.ts\texecute_raw\tone', 'src/core/a.ts\texecute_raw', 'src/core/a.ts\texecute_raw\t1\twhy\textra', '\texecute_raw\t1']) {
      const root = tree(RAW.baseline, { [RAW.baseline]: `# baseline\nsrc/core/a.ts\texecute_raw\t1\n${row}\n`, 'src/core/a.ts': site });
      const r = run(RAW.guard, root);
      expect(r.code, row).toBe(1);
      expect(r.out, row).toContain('malformed row');
    }
  });

  test('a raised row with a note passes; --prune keeps the note; an empty note is malformed', () => {
    const raised = tree(RAW.baseline, {
      [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\tfix #1: needs one read until links move\n',
      'src/core/a.ts': site,
    });
    expect(run(RAW.guard, raised).code).toBe(0);
    const stale = tree(RAW.baseline, {
      [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t3\tfix #1: why\n',
      'src/core/a.ts': site,
    });
    run(RAW.guard, stale, ['--prune']);
    expect(readFileSync(join(stale, RAW.baseline), 'utf8')).toBe('# baseline\nsrc/core/a.ts\texecute_raw\t1\tfix #1: why\n');
    const empty = tree(RAW.baseline, {
      [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\t \n',
      'src/core/a.ts': site,
    });
    const r = run(RAW.guard, empty);
    expect(r.code).toBe(1);
    expect(r.out).toContain('the note column is empty');
  });

  test('a rise names both ways out: a typed method, or a raised row with a note', () => {
    const root = tree(RAW.baseline, { 'src/core/a.ts': site });
    const r = run(RAW.guard, root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('call a typed engine method');
    expect(r.out).toContain('with a note column saying why');
  });

  test('--print emits the current rows in the baseline format', () => {
    const root = tree(RAW.baseline, { 'src/core/a.ts': site, 'src/b.ts': 'declare const sql: any;\nsql`DELETE FROM pages`;\n' });
    const r = spawnSync('bun', [RAW.guard, '--print'], { encoding: 'utf8', env: { ...process.env, GBRAIN_GUARD_ROOT: root } });
    expect(r.stdout).toBe('src/b.ts\tsql_template\t1\nsrc/core/a.ts\texecute_raw\t1\n');
  });
});

describe('check-engine-kind-branches.ts', () => {
  test('counts two-way comparisons and switch cases on engine-kind names only', () => {
    const c = countKinds([
      'declare const engine: any, cfg: any, kind: string, opts: any, mode: string;',
      'engine.kind === "pglite";',
      '"postgres" !== cfg.engine;',
      'kind == "pglite";',
      'opts.engineKind != "postgres";',
      'mode === "pglite";',
      'engine.kind === "sqlite";',
      'switch (engine.kind) { case "pglite": break; case "postgres": break; default: break; }',
      'switch (mode) { case "pglite": break; }',
    ].join('\n'));
    expect(c.kind_compare).toBe(4);
    expect(c.kind_case).toBe(2);
  });

  // Value: protects=bracket, backtick and wrapped spellings of an engine-kind branch still count; fails_when=isKindExpr or isKindLiteral stops unwrapping one of these forms; why_new=the case above uses dot access and quoted literals only; seam=none
  test('bracket access, backtick literals and wrapped subjects count too', () => {
    const c = countKinds([
      'declare const e: any, kind: any;',
      'e["kind"] === "pglite";',
      'e[`engineKind`] === "postgres";',
      'kind === `postgres`;',
      '(e.kind as string) === "pglite";',
      'e!.engine !== "postgres";',
      'e["mode"] === "pglite";',
      'switch ((e.kind)) { case `pglite`: break; }',
    ].join('\n'));
    expect(c).toEqual({ kind_compare: 5, kind_case: 1 });
  });

  test('an exhaustive switch whose default asserts never does not count; an incomplete one does', () => {
    const exhaustive = (tail: string) => countKinds([
      "type Kind = 'pglite' | 'postgres'; declare const kind: Kind; declare function assertNever(x: never): never;",
      `switch (kind) { case 'pglite': break; case 'postgres': break; default: ${tail} }`,
    ].join('\n')).kind_case;
    expect(exhaustive('{ const unreachable: never = kind; throw new Error(String(unreachable)); }')).toBe(0);
    expect(exhaustive('assertNever(kind);')).toBe(0);
    expect(exhaustive('kind satisfies never; throw new Error("unreachable");')).toBe(0);
    expect(exhaustive('return assertNever(kind);')).toBe(0);
    expect(exhaustive('throw assertNever(kind);')).toBe(0);
    expect(exhaustive('throw new Error("unknown engine");')).toBe(2);
    // A cast or a never check on another value proves nothing.
    expect(exhaustive('void (kind as never);')).toBe(2);
    expect(exhaustive('{ declare const other: never; const x: never = other; }')).toBe(2);
    expect(exhaustive('assertNever(other as never);')).toBe(2);
    // The check must be the clause's first statement: earlier control flow can
    // narrow the value to never after an unknown kind has already escaped.
    expect(exhaustive('{ if (kind) return 2; const unreachable: never = kind; return unreachable; }')).toBe(2);
    expect(exhaustive('console.log(kind); assertNever(kind);')).toBe(2);
    expect(exhaustive('throw new Error(String(kind satisfies never));')).toBe(2);
    // A never check in a nested function, or on a name that shadows the
    // switched value, says nothing about the outer switch.
    expect(exhaustive('{ const check = (kind: never) => kind satisfies never; return 2; }')).toBe(2);
    expect(exhaustive('{ const check = (kind: never) => { const u: never = kind; }; return 2; }')).toBe(2);
    expect(countKinds([
      "type Kind = 'pglite' | 'postgres'; declare const kind: Kind;",
      "switch (kind) { case 'pglite': const kind2 = 1; break; case 'postgres': { break; } default: { const unreachable: never = kind; const kind = 0 as never; } }",
    ].join('\n')).kind_case).toBe(2);
    expect(countKinds([
      "declare const engine: { kind: 'pglite' | 'postgres' };",
      "switch (engine.kind) { case 'pglite': let engine = { kind: 0 as never }; break; case 'postgres': break; default: const u: never = engine.kind; }",
    ].join('\n')).kind_case).toBe(2);
    expect(countKinds([
      "declare const engine: { kind: 'pglite' | 'postgres' };",
      "switch (engine.kind) { case 'pglite': break; case 'postgres': break; default: const u: never = engine.kind; }",
    ].join('\n')).kind_case).toBe(0);
    // A switch that leaves a kind out keeps counting even with a never check that does not compile.
    expect(countKinds("declare const kind: 'pglite' | 'postgres';\nswitch (kind) { case 'pglite': break; default: break; }").kind_case).toBe(1);
    expect(countKinds("declare const kind: string;\nswitch (kind) { case 'pglite': break; case 'postgres': break; }").kind_case).toBe(2);
  });

  test('a new branch outside the engines fails; inside the engines it is ignored', () => {
    const root = tree(KIND.baseline, {
      'src/core/pglite-engine.ts': 'declare const e: any;\nexport const x = e.kind === "pglite";\n',
      'src/core/b.ts': 'declare const e: any;\nexport const x = e.kind === "postgres";\n',
    });
    const r = run(KIND.guard, root);
    expect(r.code).toBe(1);
    expect(r.out).toContain('FAIL: src/core/b.ts kind_compare: baseline 0, actual 1');
    expect(r.out).toContain('capability');
  });

  test('a matching baseline passes', () => {
    const root = tree(KIND.baseline, {
      [KIND.baseline]: '# baseline\nsrc/core/b.ts\tkind_compare\t1\n',
      'src/core/b.ts': 'declare const e: any;\nexport const x = e.kind === "postgres";\n',
    });
    expect(run(KIND.guard, root).code).toBe(0);
  });
});