Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env bun
/**
* Function-size ratchet (refactor wave 1, W5; docs/TESTING.md#function-size-ratchet).
*
* check-module-size.sh caps FILE size, so a 3,000-line function inside a file
* under its ceiling was invisible. This guard measures every function-like
* node in src/**\/*.ts (excluding *.generated.ts and .d.ts) with the
* TypeScript compiler API: function declarations, methods, constructors,
* accessors, arrow functions and function expressions, including the
* object-literal and class-property forms. Nested functions are measured on
* their own; an outer function's length includes them.
*
* Rules (every violation is reported, then one exit):
* 1. a function over LIMIT lines with no baseline row -> FAIL (new)
* 2. a baselined function longer than its row -> FAIL (growth)
* 3. a baselined function at or under LIMIT -> FAIL (remove the row)
* 4. a baselined function more than SLACK lines under its row -> FAIL (lower the row)
* 5. a baseline row whose function no longer exists -> FAIL (remove or transfer)
* 6. a row raised above (or added since) the base baseline
* without an issue/TODO id in its justification -> FAIL (raise)
* 7. malformed, duplicate or unsorted rows -> FAIL
*
* Rows are keyed by `path<TAB>name-path`, never line numbers, so unrelated
* edits above a function do not churn the baseline. The name path is built
* from enclosing declarations, property names and call context, e.g.
* `PGLiteEngine.initSchema`, `runServeHttp>app.post('/mcp')`,
* `MIGRATIONS[v131].handler`, `add>result=this.engine.transaction(#0)`
* (`>` enters a function, `.` a member, `=` a call whose result is bound); a repeated key gets a `#2`, `#3` ordinal in
* source order. Every failure prints the computed key so it can be copied.
*
* Baseline identity transfer: a move-only commit changes a function's key.
* `bun scripts/check-function-size.ts --transfer` rewrites a missing row to
* the one unbaselined over-limit function whose whitespace-normalized text is
* identical to the old function at the base ref (default HEAD; `--from <ref>`)
* apart from an added leading `export` and re-relativized module specifiers,
* keeping lines and justification. Anything that is not a verified identical
* move is left for review.
*
* Seams: GBRAIN_GUARD_ROOT (fixture root; baseline read from
* <root>/scripts/function-size-baseline.tsv, base baseline from
* <root>/scripts/function-size-baseline.base.tsv if present),
* GBRAIN_FUNCTION_SIZE_LIMIT, GBRAIN_FUNCTION_SIZE_SLACK,
* GBRAIN_FUNCTION_SIZE_BASE_REF (git ref whose merge-base supplies the base
* baseline; default origin/master).
*/
import { spawnSync } from 'node:child_process';
import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { dirname, join, relative, resolve } from 'node:path';
import ts from 'typescript';
const FIXTURE_ROOT = process.env.GBRAIN_GUARD_ROOT;
const ROOT = FIXTURE_ROOT ?? gitOut(['rev-parse', '--show-toplevel'], process.cwd())?.trim() ?? process.cwd();
const BASELINE_REL = 'scripts/function-size-baseline.tsv';
const BASELINE = join(ROOT, BASELINE_REL);
const LIMIT = positiveInt(process.env.GBRAIN_FUNCTION_SIZE_LIMIT, 300);
const SLACK = positiveInt(process.env.GBRAIN_FUNCTION_SIZE_SLACK, 50);
const ANCHOR = 'docs/TESTING.md#function-size-ratchet';
const ISSUE_ID = /(#\d+|TODOS\.md:\d+|\bTODO[-:]\s*\S+|\b[A-Z][A-Z0-9]+-\d+\b)/;
const HEADER = 'path\tname\tlines\tjustification';
function positiveInt(raw: string | undefined, fallback: number): number {
const n = raw ? Number.parseInt(raw, 10) : NaN;
return Number.isFinite(n) && n > 0 ? n : fallback;
}
function gitOut(args: string[], cwd: string): string | null {
const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
return r.status === 0 ? r.stdout : null;
}
export interface MeasuredFunction {
path: string;
name: string;
line: number;
lines: number;
text: string;
}
function propertyName(name: ts.PropertyName | ts.BindingName, sf: ts.SourceFile): string {
if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name)) return name.text;
if (ts.isStringLiteral(name) || ts.isNumericLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name)) return name.text;
return name.getText(sf).replace(/\s+/g, ' ');
}
function isFunctionLike(node: ts.Node): node is ts.FunctionLikeDeclaration {
return (
ts.isFunctionDeclaration(node) ||
ts.isMethodDeclaration(node) ||
ts.isConstructorDeclaration(node) ||
ts.isGetAccessorDeclaration(node) ||
ts.isSetAccessorDeclaration(node) ||
ts.isArrowFunction(node) ||
ts.isFunctionExpression(node)
);
}
function callLabel(call: ts.CallExpression | ts.NewExpression, sf: ts.SourceFile, child: ts.Node): string {
const callee = call.expression.getText(sf).replace(/\s+/g, '');
const args = call.arguments ?? ts.factory.createNodeArray();
const literal = args.find((a) => ts.isStringLiteral(a) || ts.isNoSubstitutionTemplateLiteral(a)) as
| ts.StringLiteral
| undefined;
if (literal) return `${callee}('${literal.text.slice(0, 60)}')`;
const index = args.findIndex((a) => a === child || (child.pos >= a.pos && child.end <= a.end));
return `${callee}(#${index < 0 ? 0 : index})`;
}
function arrayElementLabel(obj: ts.ObjectLiteralExpression, arr: ts.ArrayLiteralExpression): string {
for (const p of obj.properties) {
if (!ts.isPropertyAssignment(p) || !ts.isIdentifier(p.name)) continue;
if (p.name.text === 'version' && ts.isNumericLiteral(p.initializer)) return `[v${p.initializer.text}]`;
}
for (const p of obj.properties) {
if (!ts.isPropertyAssignment(p) || !ts.isIdentifier(p.name)) continue;
if (p.name.text === 'name' && ts.isStringLiteral(p.initializer)) return `[${p.initializer.text}]`;
}
return `[${arr.elements.indexOf(obj)}]`;
}
/**
* Label contributed by one ancestor (or the function itself), or null when the
* node adds nothing to the name path. `fn` marks labels that open a function
* scope, so the next segment is joined with `>` instead of `.`.
*/
type Segment = { label: string; fn: boolean; bracket?: boolean; call?: boolean };
function labelOf(node: ts.Node, child: ts.Node, sf: ts.SourceFile): Segment | null {
if (ts.isFunctionDeclaration(node)) return { label: node.name?.text ?? '<anonymous>', fn: true };
if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) return { label: node.name?.text ?? '<class>', fn: false };
if (ts.isMethodDeclaration(node)) return { label: propertyName(node.name, sf), fn: true };
if (ts.isConstructorDeclaration(node)) return { label: 'constructor', fn: true };
if (ts.isGetAccessorDeclaration(node)) return { label: `get ${propertyName(node.name, sf)}`, fn: true };
if (ts.isSetAccessorDeclaration(node)) return { label: `set ${propertyName(node.name, sf)}`, fn: true };
if (ts.isVariableDeclaration(node)) return { label: propertyName(node.name, sf), fn: false };
if (ts.isPropertyAssignment(node) || ts.isPropertyDeclaration(node)) return { label: propertyName(node.name, sf), fn: false };
if (ts.isExportAssignment(node)) return { label: 'default', fn: false };
if ((ts.isCallExpression(node) || ts.isNewExpression(node)) && child !== node.expression) {
return { label: callLabel(node, sf, child), fn: false, call: true };
}
if (ts.isCallExpression(node) && child === node.expression) return { label: '<iife>', fn: false };
if (ts.isArrayLiteralExpression(node) && ts.isObjectLiteralExpression(child)) {
return { label: arrayElementLabel(child, node), fn: false, bracket: true };
}
if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
return node.name ? { label: node.name.text, fn: true } : { label: '', fn: true };
}
return null;
}
function namePath(fnNode: ts.Node, sf: ts.SourceFile): string {
const segments: Segment[] = [];
let child: ts.Node = fnNode;
let node: ts.Node | undefined = fnNode;
while (node && !ts.isSourceFile(node)) {
const l = labelOf(node, child, sf);
if (l) segments.unshift(l);
child = node;
node = node.parent;
}
let out = '';
let prev = null as Segment | null;
for (const s of segments) {
if (s.label === '') {
const before: Segment | null = prev;
prev = before ? { ...before, fn: before.fn || s.fn } : s;
continue;
}
if (!out) out = s.label;
else if (s.bracket) out += s.label;
else if (prev?.fn) out += '>' + s.label;
else if (s.call && prev && !prev.call && !prev.bracket) out += '=' + s.label;
else out += '.' + s.label;
prev = s;
}
return out || '<anonymous>';
}
export function measureSource(path: string, text: string): MeasuredFunction[] {
const sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
const found: MeasuredFunction[] = [];
const seen = new Map<string, number>();
const visit = (node: ts.Node): void => {
if (isFunctionLike(node) && node.body) {
const start = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line;
const end = sf.getLineAndCharacterOfPosition(node.getEnd()).line;
let name = namePath(node, sf);
const n = (seen.get(name) ?? 0) + 1;
seen.set(name, n);
if (n > 1) name = `${name}#${n}`;
found.push({ path, name, line: start + 1, lines: end - start + 1, text: node.getText(sf) });
}
ts.forEachChild(node, visit);
};
visit(sf);
return found;
}
function srcFiles(root: string): string[] {
const out: string[] = [];
const walk = (dir: string): void => {
if (!existsSync(dir)) return;
for (const entry of readdirSync(dir).sort()) {
const full = join(dir, entry);
if (statSync(full).isDirectory()) walk(full);
else if (entry.endsWith('.ts') && !entry.endsWith('.generated.ts') && !entry.endsWith('.d.ts')) out.push(full);
}
};
walk(join(root, 'src'));
return out;
}
interface BaselineRow {
path: string;
name: string;
lines: number;
justification: string;
lineNo: number;
}
function parseBaseline(text: string, label: string, problems: string[]): BaselineRow[] {
const rows: BaselineRow[] = [];
const lines = text.split('\n');
let sawHeader = false;
lines.forEach((raw, i) => {
if (!raw.trim() || raw.startsWith('#')) return;
if (raw === HEADER) {
sawHeader = true;
return;
}
const cols = raw.split('\t');
const lines = Number(cols[2]);
if (cols.length !== 4 || !cols[0] || !cols[1] || !Number.isInteger(lines) || !cols[3]?.trim()) {
problems.push(`FAIL: ${label}:${i + 1} malformed row (want path<TAB>name<TAB>lines<TAB>justification)`);
return;
}
rows.push({ path: cols[0], name: cols[1], lines, justification: cols[3], lineNo: i + 1 });
});
if (!sawHeader && rows.length) problems.push(`FAIL: ${label} is missing the header line "${HEADER.replace(/\t/g, '<TAB>')}"`);
return rows;
}
function baseBaselineText(): { text: string | null; source: string } {
if (FIXTURE_ROOT) {
const p = join(ROOT, 'scripts/function-size-baseline.base.tsv');
return existsSync(p) ? { text: readFileSync(p, 'utf8'), source: 'fixture base' } : { text: null, source: 'none' };
}
const ref = process.env.GBRAIN_FUNCTION_SIZE_BASE_REF ?? 'origin/master';
const mergeBase = gitOut(['merge-base', 'HEAD', ref], ROOT)?.trim();
const at = mergeBase ?? (gitOut(['rev-parse', '--verify', 'HEAD'], ROOT) ? 'HEAD' : null);
if (!at) return { text: null, source: 'none (no git history)' };
const text = gitOut(['show', `${at}:${BASELINE_REL}`], ROOT);
const source = mergeBase ? `merge-base with ${ref}` : `HEAD (${ref} unavailable)`;
return { text, source: text === null ? `${source}: no baseline yet (seed)` : source };
}
const repoRelative = (abs: string) => relative(ROOT, abs).replace(/\\/g, '/');
const keyOf = (path: string, name: string) => `${path}\t${name}`;
const normalized = (s: string) => s.replace(/\s+/g, ' ').trim();
/**
* Move-normalized text for --transfer: a move into another module may add a
* leading `export` and must re-relativize module specifiers (`import('../x.ts')`
* becomes `import('../../x.ts')` one directory down). Specifier-shaped string
* literals are resolved against their own file, so they compare equal only
* when both sides name the same module.
*/
function moveNormalized(text: string, path: string): string {
const resolved = text.replace(/(['"])(\.\.?\/[^'"\n]*)\1/g, (_m, q: string, spec: string) =>
`${q}@${repoRelative(resolve(dirname(join(ROOT, path)), spec))}${q}`);
return normalized(resolved).replace(/^export /, '');
}
function formatBaseline(rows: Omit<BaselineRow, 'lineNo'>[], preamble: string): string {
const sorted = [...rows].sort((a, b) => (a.path === b.path ? (a.name < b.name ? -1 : a.name > b.name ? 1 : 0) : a.path < b.path ? -1 : 1));
return preamble + [HEADER, ...sorted.map((r) => `${r.path}\t${r.name}\t${r.lines}\t${r.justification}`)].join('\n') + '\n';
}
function preambleOf(text: string): string {
const out: string[] = [];
for (const line of text.split('\n')) {
if (line.startsWith('#')) out.push(line);
else break;
}
return out.length ? out.join('\n') + '\n' : '';
}
function main(): number {
const t0 = performance.now();
const args = process.argv.slice(2);
const measured = srcFiles(ROOT).flatMap((f) => measureSource(repoRelative(f), readFileSync(f, 'utf8')));
const byKey = new Map(measured.map((m) => [keyOf(m.path, m.name), m]));
const problems: string[] = [];
if (!existsSync(BASELINE)) {
console.error(`FAIL: ${BASELINE_REL} not found under ${ROOT}`);
return 1;
}
const baselineText = readFileSync(BASELINE, 'utf8');
const rows = parseBaseline(baselineText, BASELINE_REL, problems);
if (args[0] === '--seed') {
const seeded = measured
.filter((m) => m.lines > LIMIT)
.map((m) => ({ path: m.path, name: m.name, lines: m.lines, justification: args[1] ?? 'seed' }));
writeFileSync(BASELINE, formatBaseline(seeded, preambleOf(baselineText)));
console.log(`seeded ${seeded.length} row(s) into ${BASELINE_REL}`);
return 0;
}
if (args[0] === '--transfer') {
const fromIdx = args.indexOf('--from');
const ref = fromIdx >= 0 ? args[fromIdx + 1] : 'HEAD';
const baselined = new Set(rows.map((r) => keyOf(r.path, r.name)));
const candidates = measured.filter((m) => m.lines > LIMIT && !baselined.has(keyOf(m.path, m.name)));
let moved = 0;
const next = rows.map((r) => {
if (byKey.has(keyOf(r.path, r.name))) return r;
const old = gitOut(['show', `${ref}:${r.path}`], ROOT);
const oldFn = old ? measureSource(r.path, old).find((m) => m.name === r.name) : undefined;
const matches = oldFn ? candidates.filter((c) => moveNormalized(c.text, c.path) === moveNormalized(oldFn.text, r.path)) : [];
if (matches.length !== 1) {
console.log(`skip: ${r.path}\t${r.name} (${oldFn ? `${matches.length} identical candidates` : `not found at ${ref}`})`);
return r;
}
moved++;
console.log(`transfer: ${r.path}\t${r.name} -> ${matches[0].path}\t${matches[0].name}`);
return { ...r, path: matches[0].path, name: matches[0].name };
});
writeFileSync(BASELINE, formatBaseline(next, preambleOf(baselineText)));
console.log(`transferred ${moved} row(s); review the ${BASELINE_REL} diff`);
return 0;
}
const seenRows = new Set<string>();
let prev = '';
for (const r of rows) {
const key = keyOf(r.path, r.name);
if (seenRows.has(key)) problems.push(`FAIL: ${BASELINE_REL}:${r.lineNo} duplicate row for ${key}`);
seenRows.add(key);
if (prev && key < prev) problems.push(`FAIL: ${BASELINE_REL}:${r.lineNo} rows must be sorted by path then name (regenerate order)`);
prev = key;
}
const baselineByKey = new Map(rows.map((r) => [keyOf(r.path, r.name), r]));
const newLong = measured.filter((m) => m.lines > LIMIT && !baselineByKey.has(keyOf(m.path, m.name)));
for (const m of newLong) {
problems.push(`FAIL: ${m.path}:${m.line} ${m.name} is ${m.lines} lines, over the ${LIMIT}-line limit (no baseline row)\n key: ${m.path}\t${m.name}`);
}
const missing: BaselineRow[] = [];
for (const r of rows) {
const m = byKey.get(keyOf(r.path, r.name));
if (!m) {
missing.push(r);
problems.push(`FAIL: ${BASELINE_REL}:${r.lineNo} ${r.path} ${r.name} no longer exists (remove the row, or --transfer a verified move)`);
} else if (m.lines > r.lines) {
problems.push(`FAIL: ${m.path}:${m.line} ${m.name} grew to ${m.lines} lines, over its ${r.lines}-line baseline\n key: ${m.path}\t${m.name}`);
} else if (m.lines <= LIMIT) {
problems.push(`FAIL: ${m.path}:${m.line} ${m.name} shrank to ${m.lines} lines, under the ${LIMIT}-line limit: remove its baseline row`);
} else if (r.lines - m.lines > SLACK) {
problems.push(`FAIL: ${m.path}:${m.line} ${m.name} shrank to ${m.lines} lines; lower its baseline row from ${r.lines} to ${m.lines}`);
}
}
const moveHints = missing.filter((r) => newLong.some((m) => m.name.split(/[>.]/).pop() === r.name.split(/[>.]/).pop()));
if (moveHints.length) {
problems.push(`FAIL: ${moveHints.length} missing row(s) match a new over-limit function by name; if this is a move-only commit run: bun scripts/check-function-size.ts --transfer`);
}
const base = baseBaselineText();
const raises: string[] = [];
if (base.text !== null) {
const baseRows = new Map(parseBaseline(base.text, 'base baseline', []).map((r) => [keyOf(r.path, r.name), r]));
for (const r of rows) {
const b = baseRows.get(keyOf(r.path, r.name));
if (b && r.lines <= b.lines) continue;
const what = b ? `raised ${b.lines} -> ${r.lines}` : `added at ${r.lines}`;
raises.push(`${r.path}\t${r.name} ${what}: ${r.justification}`);
if (!ISSUE_ID.test(r.justification)) {
problems.push(`FAIL: ${BASELINE_REL}:${r.lineNo} ${r.name} ${what} without an issue/TODO id in its justification`);
}
}
}
const seconds = ((performance.now() - t0) / 1000).toFixed(1);
const overLimit = measured.filter((m) => m.lines > LIMIT).length;
for (const r of raises) console.log(`raise: ${r}`);
if (problems.length) {
for (const p of problems) console.error(p);
console.error(`Why: functions over ${LIMIT} lines may not appear or grow; the baseline only shrinks (W5 ratchet).`);
console.error('Fix: extract cohesive blocks into named helpers or sibling modules (phase / stage / handler-table pattern);');
console.error(` a justified exception edits ${BASELINE_REL} with an issue/TODO id in the justification.`);
console.error(`See: ${ANCHOR}`);
console.error(`function-size: ${problems.length} violation(s); ${overLimit} over-limit function(s), ${rows.length} baseline row(s), base: ${base.source}, ${seconds}s`);
return 1;
}
console.log(`OK: function sizes within ${BASELINE_REL} (${overLimit} over-limit function(s) baselined, ${raises.length} raise(s), base: ${base.source}, ${seconds}s)`);
return 0;
}
if (import.meta.main) process.exit(main());