Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.5 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Engine-kind branch ratchet (D6 of docs/designs/RUST_ENGINE.md, "Engine
 * selection"; docs/ci-guards.md#engine-kind-branches).
 *
 * A third engine must never fall silently into a two-way `pglite` / `postgres`
 * branch. New code asks a capability question or uses an exhaustive switch
 * over every engine kind instead. This guard counts, per file under src/
 * (TypeScript compiler API), outside the engines:
 *
 *   kind_compare   `x === 'pglite'`, `x !== 'postgres'` (and `==` / `!=`, either
 *                  side) where x ends in the name kind, engineKind,
 *                  engine_kind or engine (`engine.kind`, `cfg.engine`)
 *   kind_case      `case 'pglite':` / `case 'postgres':` in a switch over such x,
 *                  unless the switch is exhaustive (its default clause opens
 *                  with a `never` check on the switched value; see isExhaustive)
 *
 * Outside the engines is the same set as the raw-SQL ratchet
 * (scripts/check-engine-raw-sql-ratchet.ts `isEngineFile`).
 *
 * Baseline: scripts/engine-kind-branches-baseline.tsv, rows
 * path<TAB>metric<TAB>count[<TAB>note]. Counts fall (scripts/lib/count-ratchet.ts);
 * a raise edits the row in the same PR with a note saying why;
 * `--prune` lowers stale rows, `--print` prints the current counts.
 *
 * Seam: GBRAIN_GUARD_ROOT (fixture tree root; baseline read from
 * <root>/scripts/engine-kind-branches-baseline.tsv).
 */
import { readFileSync } from 'node:fs';
import { join, relative } from 'node:path';
import ts from 'typescript';
import { isEngineFile } from './check-engine-raw-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 = ['kind_compare', 'kind_case'] as const;
export type Metric = (typeof METRICS)[number];

const KINDS = new Set(['pglite', 'postgres']);
const KIND_NAMES = new Set(['kind', 'engineKind', 'engine_kind', 'engine']);
const EQUALITY = new Set([
  ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken,
  ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsToken,
]);

function isKindLiteral(node: ts.Expression): boolean {
  return (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && KINDS.has(node.text);
}

function isKindExpr(node: ts.Expression): boolean {
  if (ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node) || ts.isAsExpression(node)) return isKindExpr(node.expression);
  if (ts.isIdentifier(node)) return KIND_NAMES.has(node.text);
  if (ts.isPropertyAccessExpression(node)) return KIND_NAMES.has(node.name.text);
  if (ts.isElementAccessExpression(node)) {
    const key = node.argumentExpression;
    return (ts.isStringLiteral(key) || ts.isNoSubstitutionTemplateLiteral(key)) && KIND_NAMES.has(key.text);
  }
  return false;
}

/**
 * An exhaustive switch is the recommended form, so it never counts: the first
 * statement of its `default` clause (or of a block that is the clause's first
 * statement) hands the switched value itself to a compile-time `never` check
 * (`const unreachable: never = kind;`, `kind satisfies never;`,
 * `assertNever(kind);`, `return assertNever(kind);` or `throw assertNever(kind);`),
 * so a third engine fails typecheck instead of falling into a branch.
 * Nothing counts that the first statement does not prove: a check after other
 * statements (an earlier `if (kind) return` narrows the value to `never`), a
 * check inside a nested function, a cast (`kind as never`), a check on some
 * other value, or a switch whose clauses declare a name that shadows the
 * switched value's root identifier.
 */
function isExhaustive(node: ts.SwitchStatement): boolean {
  const def = node.caseBlock.clauses.find(ts.isDefaultClause);
  if (!def) return false;
  const subjectExpr = unwrap(node.expression);
  const root = rootName(subjectExpr);
  if (root === undefined) return false;
  const subject = subjectExpr.getText();
  const isSubject = (e: ts.Expression | undefined): boolean => e !== undefined && unwrap(e).getText() === subject;
  const isAssertNever = (e: ts.Expression | undefined): boolean => {
    if (e === undefined) return false;
    const c = unwrap(e);
    return ts.isCallExpression(c) && ts.isIdentifier(c.expression) && c.expression.text === 'assertNever'
      && c.arguments.length === 1 && isSubject(c.arguments[0]);
  };
  let first: ts.Statement | undefined = def.statements[0];
  const scopes: ts.NodeArray<ts.Statement>[] = node.caseBlock.clauses.map(c => c.statements);
  if (first && ts.isBlock(first)) {
    scopes.push(first.statements);
    first = first.statements[0];
  }
  for (const statements of scopes) {
    for (const st of statements) if (declaredNames(st).includes(root)) return false;
  }
  if (!first) return false;
  if (ts.isVariableStatement(first)) {
    const decls = first.declarationList.declarations;
    return decls.length === 1 && decls[0].type?.kind === ts.SyntaxKind.NeverKeyword && isSubject(decls[0].initializer);
  }
  if (ts.isExpressionStatement(first)) {
    const e = unwrap(first.expression);
    if (ts.isSatisfiesExpression(e)) return e.type.kind === ts.SyntaxKind.NeverKeyword && isSubject(e.expression);
    return isAssertNever(e);
  }
  if (ts.isReturnStatement(first) || ts.isThrowStatement(first)) return isAssertNever(first.expression);
  return false;
}

/** The leftmost identifier of `kind`, `engine.kind` or `cfg['engine']`; undefined for anything else. */
function rootName(e: ts.Expression): string | undefined {
  const x = unwrap(ts.isAsExpression(e) ? e.expression : e);
  if (ts.isIdentifier(x)) return x.text;
  if (x.kind === ts.SyntaxKind.ThisKeyword) return 'this';
  if (ts.isPropertyAccessExpression(x) || ts.isElementAccessExpression(x)) return rootName(x.expression);
  return undefined;
}

/** Names a statement declares in the scope it sits in (variables, functions, classes). */
function declaredNames(st: ts.Statement): string[] {
  const out: string[] = [];
  const bind = (n: ts.BindingName): void => {
    if (ts.isIdentifier(n)) out.push(n.text);
    else for (const el of n.elements) if (!ts.isOmittedExpression(el)) bind(el.name);
  };
  if (ts.isVariableStatement(st)) st.declarationList.declarations.forEach(d => bind(d.name));
  else if ((ts.isFunctionDeclaration(st) || ts.isClassDeclaration(st)) && st.name) out.push(st.name.text);
  return out;
}

function unwrap(e: ts.Expression): ts.Expression {
  return ts.isParenthesizedExpression(e) || ts.isNonNullExpression(e) ? unwrap(e.expression) : e;
}

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> = { kind_compare: 0, kind_case: 0 };
  const visit = (node: ts.Node): void => {
    if (ts.isBinaryExpression(node) && EQUALITY.has(node.operatorToken.kind)) {
      if ((isKindLiteral(node.right) && isKindExpr(node.left)) || (isKindLiteral(node.left) && isKindExpr(node.right))) counts.kind_compare++;
    } else if (ts.isSwitchStatement(node) && isKindExpr(node.expression) && !isExhaustive(node)) {
      for (const clause of node.caseBlock.clauses) {
        if (ts.isCaseClause(clause) && isKindLiteral(clause.expression)) counts.kind_case++;
      }
    }
    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-kind-branches',
    script: 'scripts/check-engine-kind-branches.ts',
    baselineRel: 'scripts/engine-kind-branches-baseline.tsv',
    anchor: 'docs/ci-guards.md#engine-kind-branches',
    metrics: METRICS,
    why: 'a third engine must never fall into a two-way pglite/postgres branch; these branches fall, and a raise needs a written reason (D6, docs/designs/RUST_ENGINE.md "Engine selection").',
    riseFix: 'ask a capability question (engine.capabilities) or switch over every engine kind with a default clause whose first statement is a never check on the switched value (`const unreachable: never = kind;`; that switch never counts) instead of comparing with \'pglite\' / \'postgres\'; a moved file carries its row with it in the same PR',
    scan: scanTree,
  }, ROOT, process.argv);
}