Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.7 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Schema-migration registry generator (refactor wave 1, W3).
 *
 * Reads every `src/core/schema-migrations/v<NNN>-<name>.ts` file and writes the
 * committed static-import registry `src/core/schema-migrations/registry.generated.ts`
 * (static imports only, so `bun build --compile` bundles every migration and the
 * engine-dynamic-import rule holds). Regenerate, never hand-merge:
 *
 *   bun run build:schema-migrations            # rewrite the registry
 *   bun run new:migration <snake_name>         # scaffold v<max+1>-<name>.ts, then rewrite
 *   bun scripts/build-schema-migrations.ts --check   # exit 1 if the committed registry is stale
 *
 * Checks (FAIL/Why/Fix/See, exit 1): filename `v<NNN>-<name-with-dashes>.ts`
 * with NNN zero-padded to at least 3; the file exports exactly one
 * `export const v<NNN>: Migration = { version: <NNN>, name: '<name_with_underscores>', ... }`
 * whose version and name match the filename; no version appears in two files.
 *
 * Array order: the runner sorts by version, but `MIGRATIONS` keeps master's
 * historical array order (pinned by the migrations golden). Versions listed in
 * HISTORICAL_ARRAY_ORDER come first in that order; every other version follows
 * ascending. New migrations therefore append in version order.
 *
 * It also writes `latest.generated.ts`, the highest version as a constant, so a
 * connect-time "anything pending?" check (src/core/migrate-pending.ts) never
 * loads the ~220 migration modules the registry imports.
 *
 * Seams for tests: --dir <path> (migrations dir), --out <path> (registry path),
 * --out-latest <path> (latest-version path).
 */

import { spawnSync } from 'node:child_process';
import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
import { basename, join, relative, resolve } from 'node:path';
import ts from 'typescript';

const REPO = resolve(import.meta.dir, '..');
const DEFAULT_DIR = join(REPO, 'src/core/schema-migrations');
const REGISTRY_NAME = 'registry.generated.ts';
const LATEST_NAME = 'latest.generated.ts';
const SEE = 'See:  docs/TESTING.md#schema-migration-registry';

/**
 * Master's MIGRATIONS array order for the versions that were not appended in
 * version order (release-order reasons: v20-v23 landed before v15/v16, v37/v38
 * before v30, v58/v59 before v55, v77/v78 before v66). Frozen: never edit.
 */
export const HISTORICAL_ARRAY_ORDER: readonly number[] = [
  2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 23, 22, 21, 20, 15, 16, 24, 25, 26, 27, 28, 29, 37, 38, 30, 31, 32,
  33, 34, 35, 36, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 59, 58, 55, 56, 57, 60, 61, 62,
  63, 64, 65, 78, 77, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76,
];

export interface MigrationFile {
  file: string;
  version: number;
  name: string;
  exportName: string;
}

export class RegistryError extends Error {}

const FILE_RE = /^v(\d{3,})-([a-z0-9]+(?:-[a-z0-9]+)*)\.ts$/;
const NON_MIGRATION_FILES = new Set(['types.ts', 'helpers.ts', REGISTRY_NAME, LATEST_NAME]);

export function pad(version: number): string {
  return String(version).padStart(3, '0');
}

function rel(p: string): string {
  return relative(REPO, p) || p;
}

function fail(what: string, why: string, fix: string): never {
  throw new RegistryError(`FAIL: ${what}\nWhy:  ${why}\nFix:  ${fix}\n${SEE}`);
}

function readLiteral(file: string): { exportName: string; version: number; name: string } {
  const text = readFileSync(file, 'utf8');
  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
  const found: { exportName: string; version: number; name: string; line: number }[] = [];
  for (const stmt of sf.statements) {
    if (!ts.isVariableStatement(stmt)) continue;
    if (!stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
    for (const d of stmt.declarationList.declarations) {
      if (!ts.isIdentifier(d.name) || !d.initializer || !ts.isObjectLiteralExpression(d.initializer)) continue;
      if (!d.type || d.type.getText(sf) !== 'Migration') continue;
      let version: number | undefined;
      let name: string | undefined;
      for (const p of d.initializer.properties) {
        if (!ts.isPropertyAssignment(p) || !ts.isIdentifier(p.name)) continue;
        if (p.name.text === 'version' && ts.isNumericLiteral(p.initializer)) version = Number(p.initializer.text);
        if (p.name.text === 'name' && ts.isStringLiteralLike(p.initializer)) name = p.initializer.text;
      }
      const line = sf.getLineAndCharacterOfPosition(d.getStart(sf)).line + 1;
      if (version === undefined || name === undefined) {
        fail(`${rel(file)}:${line} ${d.name.text} has no literal \`version: <number>\` and \`name: '<string>'\``,
          'the registry generator reads the version and name statically; computed values cannot be cross-checked against the filename.',
          `write them as literals, e.g. \`version: 179, name: 'add_widget_index'\`.`);
      }
      found.push({ exportName: d.name.text, version, name, line });
    }
  }
  if (found.length !== 1) {
    fail(`${rel(file)} exports ${found.length} \`Migration\` constants (expected exactly 1)`,
      'each schema migration file holds one migration so the registry, the filename and schema_version agree.',
      'keep one `export const v<NNN>: Migration = { ... };` per file (bun run new:migration <name> writes the template).');
  }
  return found[0]!;
}

/** Scan and cross-check every migration file in `dir`. */
export function scanMigrations(dir: string): MigrationFile[] {
  const out: MigrationFile[] = [];
  for (const entry of readdirSync(dir).sort()) {
    if (!entry.endsWith('.ts') || NON_MIGRATION_FILES.has(entry)) continue;
    const file = join(dir, entry);
    const m = FILE_RE.exec(entry);
    if (!m) {
      fail(`${rel(file)} is not named v<NNN>-<name-with-dashes>.ts`,
        'every non-helper file in src/core/schema-migrations/ is a migration, and its filename carries the version the registry is sorted and checked by.',
        `rename it, e.g. git mv ${rel(file)} ${rel(join(dir, 'v179-add-widget-index.ts'))} (NNN zero-padded to 3), then run: bun run build:schema-migrations`);
    }
    const fileVersion = Number(m[1]);
    const slug = m[2]!;
    if (m[1] !== pad(fileVersion)) {
      fail(`${rel(file)} version ${m[1]} is not zero-padded to exactly ${pad(fileVersion).length} digits`,
        'filenames sort lexically; padding keeps directory order equal to version order.',
        `git mv ${rel(file)} ${rel(join(dir, `v${pad(fileVersion)}-${slug}.ts`))}`);
    }
    const lit = readLiteral(file);
    const expectedName = slug.replace(/-/g, '_');
    if (lit.version !== fileVersion) {
      fail(`${rel(file)} declares \`version: ${lit.version}\` but its filename says ${fileVersion}`,
        'the filename and the version field must agree; the runner applies and records `version`.',
        `set \`version: ${fileVersion}\` inside it, or git mv it to v${pad(lit.version)}-${slug}.ts; then run: bun run build:schema-migrations`);
    }
    if (lit.name !== expectedName) {
      fail(`${rel(file)} declares \`name: '${lit.name}'\` but its filename implies '${expectedName}'`,
        'the name field is the filename slug with - replaced by _; both appear in schema_version history and logs.',
        `set \`name: '${expectedName}'\`, or rename the file to v${pad(fileVersion)}-${lit.name.replace(/_/g, '-')}.ts`);
    }
    if (lit.exportName !== `v${pad(fileVersion)}`) {
      fail(`${rel(file)} exports \`${lit.exportName}\` but the registry expects \`v${pad(fileVersion)}\``,
        'the generated registry imports each migration by its padded version name.',
        `rename the export to \`export const v${pad(fileVersion)}: Migration = { ... }\``);
    }
    out.push({ file, version: fileVersion, name: lit.name, exportName: lit.exportName });
  }
  const byVersion = new Map<number, MigrationFile>();
  for (const m of out) {
    const prior = byVersion.get(m.version);
    if (prior) duplicate(prior, m, out);
    byVersion.set(m.version, m);
  }
  return out;
}

function onOriginMaster(file: string): boolean {
  const r = spawnSync('git', ['cat-file', '-e', `origin/master:${rel(file)}`], { cwd: REPO, stdio: 'ignore' });
  return r.status === 0;
}

function duplicate(first: MigrationFile, second: MigrationFile, all: MigrationFile[]): never {
  const [keep, move] = onOriginMaster(second.file) && !onOriginMaster(first.file) ? [second, first] : [first, second];
  const tag = (m: MigrationFile) => (onOriginMaster(m.file) ? '  (on origin/master)' : '  (this branch)');
  const next = Math.max(...all.map((m) => m.version)) + 1;
  const moved = join(move.file, '..', `v${pad(next)}-${basename(move.file).replace(FILE_RE, '$2')}.ts`);
  throw new RegistryError([
    `FAIL: schema migration version ${keep.version} is defined twice:`,
    `      ${rel(keep.file)}${tag(keep)}`,
    `      ${rel(move.file)}${tag(move)}`,
    'Why:  versions are applied in order and recorded in schema_version; two files cannot share one.',
    `Fix:  git mv ${rel(move.file)} ${rel(moved)}`,
    `      set \`version: ${next}\` and \`export const v${pad(next)}\` inside it, then run: bun run build:schema-migrations`,
    '      (already applied to a disposable dev DB: rebuild it and replay; applied to retained data:',
    '      reconcile schema_version explicitly, never just edit the counter.)',
    SEE,
  ].join('\n'));
}

/** Registry order: HISTORICAL_ARRAY_ORDER first, then every other version ascending. */
export function registryOrder(files: MigrationFile[]): MigrationFile[] {
  const byVersion = new Map(files.map((m) => [m.version, m]));
  const historical = new Set(HISTORICAL_ARRAY_ORDER);
  const ordered: MigrationFile[] = [];
  for (const v of HISTORICAL_ARRAY_ORDER) {
    const m = byVersion.get(v);
    if (m) ordered.push(m);
  }
  ordered.push(...files.filter((m) => !historical.has(m.version)).sort((a, b) => a.version - b.version));
  return ordered;
}

export function renderRegistry(files: MigrationFile[]): string {
  const ordered = registryOrder(files);
  const imports = [...files]
    .sort((a, b) => a.version - b.version)
    .map((m) => `import { ${m.exportName} } from './${basename(m.file)}';`);
  return [
    '// AUTO-GENERATED by scripts/build-schema-migrations.ts from src/core/schema-migrations/v<NNN>-*.ts.',
    '// Do not edit or hand-merge. Regenerate: bun run build:schema-migrations',
    '//',
    '// Schema migrations (database DDL, applied by src/core/migrate.ts runMigrations and',
    '// recorded in schema_version). Not to be confused with the version-upgrade',
    '// orchestrator registry in src/commands/migrations/index.ts.',
    '',
    "import type { Migration } from './types.ts';",
    ...imports,
    '',
    '// Array order is historical (see HISTORICAL_ARRAY_ORDER in the generator); the',
    '// runner sorts by version before applying.',
    'export const MIGRATIONS: Migration[] = [',
    ...ordered.map((m) => `  ${m.exportName},`),
    '];',
    '',
  ].join('\n');
}

export function renderLatest(files: MigrationFile[]): string {
  return [
    '// AUTO-GENERATED by scripts/build-schema-migrations.ts from src/core/schema-migrations/v<NNN>-*.ts.',
    '// Do not edit or hand-merge. Regenerate: bun run build:schema-migrations',
    '//',
    '// The highest schema migration version (migrate.ts LATEST_VERSION), importable without',
    '// loading the migrations themselves.',
    '',
    `export const LATEST_SCHEMA_VERSION = ${files.length > 0 ? Math.max(...files.map((m) => m.version)) : 1};`,
    '',
  ].join('\n');
}

export function scaffold(dir: string, rawName: string): string {
  if (!/^[a-z0-9]+(?:[_-][a-z0-9]+)*$/.test(rawName)) {
    fail(`migration name '${rawName}' is not lower-case snake_case`,
      'the name becomes both the filename slug (dashes) and the `name` field (underscores).',
      'use lower-case letters, digits and _ (e.g. bun run new:migration add_widget_index).');
  }
  const files = scanMigrations(dir);
  const next = files.length === 0 ? 2 : Math.max(...files.map((m) => m.version)) + 1;
  const name = rawName.replace(/-/g, '_');
  const file = join(dir, `v${pad(next)}-${name.replace(/_/g, '-')}.ts`);
  if (existsSync(file)) fail(`${rel(file)} already exists`, 'scaffolding never overwrites a migration.', 'pick another name.');
  writeFileSync(file, [
    "import type { Migration } from './types.ts';",
    '',
    '// Applied by src/core/migrate.ts on the next initSchema(); see docs/ENGINES.md',
    '// ("Canonical schema sources") for when schema.sql or a TS fragment also changes.',
    `export const v${pad(next)}: Migration = {`,
    `  version: ${next},`,
    `  name: '${name}',`,
    '  // Re-running must be safe: CREATE ... IF NOT EXISTS / ADD COLUMN IF NOT EXISTS.',
    '  idempotent: true,',
    '  sql: `',
    '    -- TODO: DDL',
    '  `,',
    '};',
    '',
  ].join('\n'));
  return file;
}

function main(argv: string[]): number {
  let dir = DEFAULT_DIR;
  let out: string | undefined;
  let outLatest: string | undefined;
  let check = false;
  let newName: string | undefined;
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i]!;
    if (a === '--dir') dir = resolve(argv[++i]!);
    else if (a === '--out') out = resolve(argv[++i]!);
    else if (a === '--out-latest') outLatest = resolve(argv[++i]!);
    else if (a === '--check') check = true;
    else if (a === '--new') newName = argv[++i];
    else {
      console.error(`unknown argument ${a}`);
      return 2;
    }
  }
  if (argv.includes('--new') && !newName) {
    console.error('usage: bun run new:migration <snake_name>');
    return 2;
  }
  const target = out ?? join(dir, REGISTRY_NAME);
  const latestTarget = outLatest ?? join(dir, LATEST_NAME);
  try {
    if (newName) console.log(`Created ${rel(scaffold(dir, newName))}`);
    const files = scanMigrations(dir);
    const outputs: Array<[string, string]> = [[target, renderRegistry(files)], [latestTarget, renderLatest(files)]];
    if (check) {
      for (const [file, text] of outputs) {
        const committed = existsSync(file) ? readFileSync(file, 'utf8') : '';
        if (committed !== text) {
          console.error([
            `FAIL: ${rel(file)} is stale (does not match the migration files in ${rel(dir)}).`,
            'Why:  the registry is generated; an added, renamed or removed migration file (or a hand edit/merge of the registry) makes it drift.',
            'Fix:  bun run build:schema-migrations   (then commit the regenerated registry; never hand-merge it)',
            SEE,
          ].join('\n'));
          return 1;
        }
        console.log(`✓ ${rel(file)} is fresh`);
      }
      return 0;
    }
    for (const [file, text] of outputs) {
      writeFileSync(file, text);
      console.log(`Generated ${rel(file)}`);
    }
    return 0;
  } catch (e) {
    if (e instanceof RegistryError) {
      console.error(e.message);
      return 1;
    }
    throw e;
  }
}

if (import.meta.main) process.exit(main(process.argv.slice(2)));