Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.7 KB
Raw Blame
#!/usr/bin/env node
/**
 * CI guard for the unscoped-check/scoped-write source-isolation bug class.
 *
 * The trap: `engine.getPage(slug)` with NO opts matches the slug in ANY
 * source (first row wins), while the paired write (`putPage` /
 * `importFromContent` / `tx.putPage`) defaults to the 'default' source. A
 * page that exists only in source B makes the existence check "succeed",
 * and the write then targets a DIFFERENT row — duplicates, clobbers, or
 * crashes (this class broke dream cycles for weeks; the writer/slug-registry
 * variant forced spurious slug disambiguation).
 *
 * Heuristic (deliberately file-scoped, same posture as
 * check-source-scope-onboard.sh): flag any non-test source file that contains
 * BOTH
 *   (a) a getPage/tx.getPage call whose balanced argument span has no second
 *       argument at all, OR a conditional second argument whose false branch
 *       is undefined/null/{} — shorthand (`x ? { sourceId } : undefined`) and
 *       expanded (`x ? { sourceId: x } : undefined`) forms alike (any-source
 *       when unset — the read half of the bug),
 *   AND
 *   (b) any write-path call: putPage( / importFromContent( / importFromFile(.
 *
 * The fix pattern (operations.ts): `getPage(slug, { sourceId: x ?? 'default' })`
 * — mirror the write's schema default on the read.
 *
 * Opt-out: a `gbrain-allow-unscoped-getpage: <reason>` comment ANYWHERE in the
 * getPage call span or on the line above it (for genuinely read-only,
 * first-match-semantics callers).
 *
 * Exit 0 = clean, 1 = violations. Runs under node or bun.
 */
import { readdirSync, readFileSync, statSync } from 'node:fs';
import { join } from 'node:path';

// Default scan roots; overridable via argv so the guard's self-test can point
// it at fixtures (`node check-getpage-scoped-write.mjs /tmp/fixtures`).
const ROOTS = process.argv.slice(2).length > 0 ? process.argv.slice(2) : ['src'];

const GETPAGE_RE = /\.\s*getPage\s*(?:<[^>;]*>)?\s*\(/g;
const WRITE_RE = /\b(putPage|importFromContent|importFromFile)\s*(?:<[^>;]*>)?\s*\(/;
const OPT_OUT = 'gbrain-allow-unscoped-getpage';

/** Walk from the '(' at openIdx and return [start,end) of the balanced span,
 *  respecting strings, template literals, and comments. */
function findSpan(src, openIdx) {
  let depth = 0;
  let mode = 'code'; // code | line | block | sq | dq | tpl
  for (let i = openIdx; i < src.length; i++) {
    const c = src[i];
    const n = src[i + 1];
    if (mode === 'line') { if (c === '\n') mode = 'code'; continue; }
    if (mode === 'block') { if (c === '*' && n === '/') { mode = 'code'; i++; } continue; }
    if (mode === 'sq') { if (c === '\\') { i++; continue; } if (c === "'") mode = 'code'; continue; }
    if (mode === 'dq') { if (c === '\\') { i++; continue; } if (c === '"') mode = 'code'; continue; }
    if (mode === 'tpl') { if (c === '\\') { i++; continue; } if (c === '`') mode = 'code'; continue; }
    if (c === '/' && n === '/') { mode = 'line'; i++; continue; }
    if (c === '/' && n === '*') { mode = 'block'; i++; continue; }
    if (c === "'") { mode = 'sq'; continue; }
    if (c === '"') { mode = 'dq'; continue; }
    if (c === '`') { mode = 'tpl'; continue; }
    if (c === '(') depth++;
    else if (c === ')') { depth--; if (depth === 0) return [openIdx + 1, i]; }
  }
  return [openIdx + 1, src.length];
}

/** Blank out comments so commented examples don't trip the probes. */
function stripComments(s) {
  return s.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
}

/** Split a balanced span into top-level arguments (commas at depth 0 only). */
function topLevelArgs(span) {
  const args = [];
  let depth = 0;
  let mode = 'code';
  let cur = '';
  for (let i = 0; i < span.length; i++) {
    const c = span[i];
    const n = span[i + 1];
    if (mode === 'line') { if (c === '\n') mode = 'code'; cur += c; continue; }
    if (mode === 'block') { if (c === '*' && n === '/') { mode = 'code'; cur += '*/'; i++; continue; } cur += c; continue; }
    if (mode === 'sq') { if (c === '\\') { cur += c + (n ?? ''); i++; continue; } if (c === "'") mode = 'code'; cur += c; continue; }
    if (mode === 'dq') { if (c === '\\') { cur += c + (n ?? ''); i++; continue; } if (c === '"') mode = 'code'; cur += c; continue; }
    if (mode === 'tpl') { if (c === '\\') { cur += c + (n ?? ''); i++; continue; } if (c === '`') mode = 'code'; cur += c; continue; }
    if (c === '/' && n === '/') { mode = 'line'; cur += c; continue; }
    if (c === '/' && n === '*') { mode = 'block'; cur += c; continue; }
    if (c === "'") { mode = 'sq'; cur += c; continue; }
    if (c === '"') { mode = 'dq'; cur += c; continue; }
    if (c === '`') { mode = 'tpl'; cur += c; continue; }
    if (c === '(' || c === '[' || c === '{') depth++;
    else if (c === ')' || c === ']' || c === '}') depth--;
    else if (c === ',' && depth === 0) { args.push(cur); cur = ''; continue; }
    cur += c;
  }
  if (cur.trim().length > 0) args.push(cur);
  return args;
}

/** True when the getPage second argument is the any-source-when-unset shape. */
function isUnscopedRead(span) {
  const args = topLevelArgs(span);
  if (args.length < 2) return true; // no opts at all → unscoped
  const opts = stripComments(args[1]).trim();
  // Ternary opts whose false branch is undefined/null/{} — any-source when
  // unset. Covers BOTH the shorthand (`x ? { sourceId } : undefined`) and the
  // expanded form (`x ? { sourceId: x } : undefined`): the object-literal
  // colon in the expanded form defeated a naive [^:]* regex, so this checks
  // "mentions sourceId + ends in a bare-empty false branch" instead.
  if (opts.includes('sourceId') && /\?[\s\S]*:\s*(undefined|null|\{\s*\})\s*$/.test(opts)) return true;
  if (/^(undefined|null|\{\s*\})$/.test(opts)) return true;
  return false;
}

const violations = [];

function scanFile(file) {
  const src = readFileSync(file, 'utf8');
  if (!WRITE_RE.test(stripComments(src))) return; // no write path in this file → read-only semantics allowed
  GETPAGE_RE.lastIndex = 0;
  let m;
  while ((m = GETPAGE_RE.exec(src))) {
    const openIdx = m.index + m[0].length - 1;
    const [s, e] = findSpan(src, openIdx);
    const span = src.slice(s, e);
    // Opt-out marker inside the span, on the lines just before the call, or
    // in a trailing comment on the closing-paren line.
    const before = src.slice(Math.max(0, m.index - 300), m.index);
    const afterEnd = src.indexOf('\n', e);
    const tail = src.slice(e, afterEnd === -1 ? src.length : afterEnd);
    if (
      span.includes(OPT_OUT) ||
      before.split('\n').slice(-3).join('\n').includes(OPT_OUT) ||
      tail.includes(OPT_OUT)
    ) continue;
    if (!isUnscopedRead(span)) continue;
    const line = src.slice(0, m.index).split('\n').length;
    violations.push(
      `${file}:${line}  unscoped getPage(...) in a file that also writes (putPage/importFromContent) — ` +
      `scope the read to the write's source: getPage(slug, { sourceId: x ?? 'default' })`,
    );
  }
}

function walk(dir) {
  let ents;
  try { ents = readdirSync(dir); } catch { return; }
  for (const ent of ents) {
    if (ent === 'node_modules') continue;
    const p = join(dir, ent);
    const st = statSync(p);
    if (st.isDirectory()) walk(p);
    else if (p.endsWith('.ts') && !p.endsWith('.test.ts')) scanFile(p);
  }
}

for (const root of ROOTS) walk(root);

if (violations.length) {
  console.error('Unscoped-getPage-with-write violations (source-isolation bug class):\n');
  for (const v of violations) console.error('  ' + v);
  console.error(
    `\n${violations.length} violation(s). Fix: pass { sourceId: x ?? 'default' } on the read ` +
    `(mirrors putPage's schema default), or mark genuinely read-only first-match calls with ` +
    `a '${OPT_OUT}: <reason>' comment.`,
  );
  process.exit(1);
}
console.log('check-getpage-scoped-write: clean (no unscoped getPage in write-path files)');