Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.7 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Raw-SQL ratchet (D6 of docs/designs/RUST_ENGINE.md; docs/ci-guards.md#engine-raw-sql-ratchet).
 *
 * Raw SQL outside the engines moves behind typed engine methods, one
 * subsystem at a time, and never grows back. This guard counts, per file
 * under src/ (TypeScript compiler API), the raw-SQL call sites outside the
 * engines:
 *
 *   execute_raw    calls named executeRaw, executeRawDirect or executeRawJsonb
 *                  (on the engine, a transaction, a `Pick<BrainEngine,
 *                  'executeRaw'>` helper or an executor; any receiver)
 *   sql_template   tagged templates whose literal text has SQL structure
 *                  (postgres.js `sql\`...\``, sqlQueryForEngine tags)
 *   driver_call    `.unsafe(...)`, and `.query(...)` / `.exec(...)` whose
 *                  argument literal text has SQL structure (driver handles)
 *
 * SQL structure is the same test as the engine-sql ratchet (`isSqlText`), so
 * comments and prose never count. A SQL string held in a variable and passed
 * to `.query(v)` is not seen; executeRaw calls are counted whatever their
 * argument.
 *
 * Outside the engines means every .ts file under src/ except
 * src/core/engine.ts, src/core/pglite-engine.ts, src/core/postgres-engine.ts,
 * src/core/pglite-engine/**, src/core/postgres-engine/** and
 * src/core/engine-sql/** (where SQL belongs; the engine-sql ratchet guards
 * the engines themselves).
 *
 * Baseline: scripts/engine-raw-sql-baseline.tsv, rows path<TAB>metric<TAB>count[<TAB>note].
 * Counts fall; a raise edits the row in the same PR with a note saying why
 * (scripts/lib/count-ratchet.ts): a rise or a new file
 * fails, a lower count fails until its row is lowered (`--prune` lowers stale
 * rows and never raises one). `--print` prints the current counts.
 *
 * Seam: GBRAIN_GUARD_ROOT (fixture tree root; baseline read from
 * <root>/scripts/engine-raw-sql-baseline.tsv).
 */
import { readFileSync } from 'node:fs';
import { join, relative } from 'node:path';
import ts from 'typescript';
import { isSqlText } from './check-engine-sql-ratchet.ts';
import { runCountRatchet, tsFiles } from './lib/count-ratchet.ts';

const ROOT = process.env.GBRAIN_GUARD_ROOT ?? join(import.meta.dir, '..');
export const METRICS = ['execute_raw', 'sql_template', 'driver_call'] as const;
export type Metric = (typeof METRICS)[number];

const EXECUTE_RAW = new Set(['executeRaw', 'executeRawDirect', 'executeRawJsonb']);
const SQL_ARG_DRIVER = new Set(['query', 'exec']);
const ENGINE_FILES = new Set(['src/core/engine.ts', 'src/core/pglite-engine.ts', 'src/core/postgres-engine.ts']);
const ENGINE_DIRS = ['src/core/pglite-engine/', 'src/core/postgres-engine/', 'src/core/engine-sql/'];

export function isEngineFile(rel: string): boolean {
  return ENGINE_FILES.has(rel) || ENGINE_DIRS.some((d) => rel.startsWith(d));
}

function literalText(node: ts.Node): string | null {
  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
  if (ts.isTemplateExpression(node)) {
    let text = node.head.text;
    for (const span of node.templateSpans) text += (text.endsWith('$') ? '0' : ' _sub_ ') + span.literal.text;
    return text;
  }
  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
    const parts: string[] = [];
    const flatten = (n: ts.Expression): void => {
      if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.PlusToken) {
        flatten(n.left);
        flatten(n.right);
      } else parts.push(literalText(n) ?? ' _sub_ ');
    };
    flatten(node);
    return parts.join('');
  }
  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node)) return literalText(node.expression);
  return null;
}

function calleeName(expr: ts.Expression): string | null {
  if (ts.isIdentifier(expr)) return expr.text;
  if (ts.isPropertyAccessExpression(expr)) return expr.name.text;
  if (ts.isElementAccessExpression(expr)) {
    const key = expr.argumentExpression;
    return ts.isStringLiteral(key) || ts.isNoSubstitutionTemplateLiteral(key) ? key.text : null;
  }
  if (ts.isNonNullExpression(expr) || ts.isParenthesizedExpression(expr)) return calleeName(expr.expression);
  return null;
}

/** `db.unsafe(...)` or `db['unsafe'](...)`: a member call, never a bare function named the same. */
function isMemberCall(expr: ts.Expression): boolean {
  if (ts.isNonNullExpression(expr) || ts.isParenthesizedExpression(expr)) return isMemberCall(expr.expression);
  return ts.isPropertyAccessExpression(expr) || ts.isElementAccessExpression(expr);
}

export function countFile(text: string, fileName = 'file.ts'): Record<Metric, number> {
  const sf = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
  const counts: Record<Metric, number> = { execute_raw: 0, sql_template: 0, driver_call: 0 };
  const visit = (node: ts.Node): void => {
    if (ts.isCallExpression(node)) {
      const name = calleeName(node.expression);
      if (name !== null && EXECUTE_RAW.has(name)) counts.execute_raw++;
      else if (name === 'unsafe' && isMemberCall(node.expression)) counts.driver_call++;
      else if (name !== null && SQL_ARG_DRIVER.has(name) && isMemberCall(node.expression)
        && node.arguments.some((a) => { const t = literalText(a); return t !== null && isSqlText(t); })) counts.driver_call++;
    } else if (ts.isTaggedTemplateExpression(node)) {
      const name = calleeName(node.tag);
      const text = literalText(node.template);
      if (name !== null && EXECUTE_RAW.has(name)) counts.execute_raw++;
      else if (text !== null && isSqlText(text)) counts.sql_template++;
    }
    ts.forEachChild(node, visit);
  };
  visit(sf);
  return counts;
}

export function scanTree(root: string): Map<string, number> {
  const out = new Map<string, number>();
  for (const abs of tsFiles(join(root, 'src'))) {
    const rel = relative(root, abs).replace(/\\/g, '/');
    if (isEngineFile(rel)) continue;
    const counts = countFile(readFileSync(abs, 'utf8'), abs);
    for (const m of METRICS) if (counts[m] > 0) out.set(rel + '\t' + m, counts[m]);
  }
  return out;
}

if (import.meta.main) {
  runCountRatchet({
    name: 'check-engine-raw-sql-ratchet',
    script: 'scripts/check-engine-raw-sql-ratchet.ts',
    baselineRel: 'scripts/engine-raw-sql-baseline.tsv',
    anchor: 'docs/ci-guards.md#engine-raw-sql-ratchet',
    metrics: METRICS,
    why: 'raw SQL outside the engines falls, and a raise needs a written reason; it moves behind typed engine methods (D6, docs/designs/RUST_ENGINE.md "Track 2 rules").',
    riseFix: 'call a typed engine method instead (add one: SQL in src/core/engine-sql/<domain>.ts, both engines delegate; CONTRIBUTING.md "Storage method"); a moved file carries its row with it in the same PR',
    scan: scanTree,
  }, ROOT, process.argv);
}