@deterministic-code/migraters 0.0.0-stage → 0.0.1

package/src/dialects/sqlserver-dialect.ts

@@ -0,0 +1,87 @@
+import type { Request as MssqlRequest } from 'mssql';
+import type { MigrationClient, MigrationSqlParam } from '../migration-client.ts';
+import { interopDefault } from '../infrastructure/interop-default.ts';
+import { readSqlTemplate } from '../infrastructure/sql-templates.ts';
+import { SqlDialectBase } from '../abstractions/sql-dialect-base.ts';
+
+const [migratesDdl, migrateLogsDdl] = await Promise.all([
+  readSqlTemplate('sqlserver', 'migrates'),
+  readSqlTemplate('sqlserver', 'migrate_logs'),
+]);
+
+const bindMssql = (
+  req: Pick<MssqlRequest, 'input'>,
+  sql: string,
+  params: MigrationSqlParam[],
+): string => {
+  let n = 0;
+  return sql.replace(/\?/g, () => {
+    const name = `p${n}`;
+    req.input(name, params[n]);
+    n++;
+    return `@${name}`;
+  });
+};
+
+export class SqlServerDialect extends SqlDialectBase {
+  readonly name = 'sqlserver' as const;
+  readonly connectionEnvironmentVariables = ['MSSQL_URL', 'DATABASE_URL'] as const;
+  readonly migratesDdl = migratesDdl;
+  readonly migrateLogsDdl = migrateLogsDdl;
+
+  quoteIdent(ident: string): string {
+    return `[${ident}]`;
+  }
+
+  nowExpr(): string {
+    return 'SYSUTCDATETIME()';
+  }
+
+  limitClause(n: number): string {
+    return `OFFSET 0 ROWS FETCH NEXT ${n} ROWS ONLY`;
+  }
+
+  async createClient(connection: string): Promise<MigrationClient> {
+    const mssql = interopDefault(await import('mssql'));
+    const pool = await mssql.connect(connection);
+    return {
+      dialect: 'sqlserver',
+      async exec(sql) {
+        await pool.request().batch(sql);
+      },
+      async query(sql, params = []) {
+        const req = pool.request();
+        const translated = bindMssql(req, sql, params);
+        const r = await req.query(translated);
+        return r.recordset ?? [];
+      },
+      async run(sql, params = []) {
+        const req = pool.request();
+        const translated = bindMssql(req, sql, params);
+        await req.query(translated);
+      },
+      async transaction(fn) {
+        const tx = pool.transaction();
+        await tx.begin();
+        try {
+          const r = await fn();
+          await tx.commit();
+          return r;
+        } catch (e) {
+          try {
+            await tx.rollback();
+          } catch (rollbackErr) {
+            console.warn(
+              'sqlserver rollback failed after transaction error; original error rethrown',
+              rollbackErr,
+            );
+          }
+          throw e;
+        }
+      },
+      async close() {
+        await pool.close();
+      },
+    };
+  }
+}

package/src/generate-help.test.ts

@@ -0,0 +1,33 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { describe, expect, it } from 'vitest';
+import { generateHelpFiles, renderHelpTemplates } from './generate-help.ts';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const CLI_YAML = join(REPO_ROOT, 'cli.yaml');
+const HELP_DIR = join(REPO_ROOT, 'shared', 'templates', 'help');
+
+describe('generate-help', () => {
+  it('shared/templates/help matches cli.yaml', async () => {
+    const generated = renderHelpTemplates(parse(await readFile(CLI_YAML, 'utf8')));
+    for (const [verb, text] of Object.entries(generated)) {
+      const onDisk = await readFile(join(HELP_DIR, `${verb}.txt`), 'utf8');
+      expect(onDisk, verb).toBe(text);
+    }
+  });
+
+  it('writes the verb templates', async () => {
+    const written = await generateHelpFiles();
+    expect(written.map((p) => p.slice(p.lastIndexOf('/') + 1)).sort()).toEqual([
+      'bundle.yaml',
+      'cli.yaml',
+      'create.txt',
+      'down.txt',
+      'init.txt',
+      'setup.txt',
+      'up.txt',
+    ]);
+  });
+});

package/src/generate-help.ts

@@ -0,0 +1,173 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse } from 'yaml';
+
+type HelpArg = {
+  flag: string;
+  placeholder?: string;
+  required: boolean;
+  help: string;
+};
+
+type HelpCommand = {
+  verb: string;
+  summary: string;
+  examples: string;
+  show_connection_env?: boolean;
+  args: HelpArg[];
+};
+
+type HelpSpec = {
+  providers: string[];
+  connection_environment: Record<string, string[]>;
+  commands: HelpCommand[];
+};
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const CLI_YAML = join(REPO_ROOT, 'cli.yaml');
+const HELP_DIR = join(REPO_ROOT, 'shared', 'templates', 'help');
+
+const requireString = (value: unknown, path: string): string => {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`cli.yaml: ${path} must be a non-empty string`);
+  }
+  return value;
+};
+
+const parseHelpSpec = (raw: unknown): HelpSpec => {
+  if (raw === null || typeof raw !== 'object') {
+    throw new Error('cli.yaml: root must be a mapping');
+  }
+  const doc = raw as Record<string, unknown>;
+  if (!Array.isArray(doc.providers) || doc.providers.some((p) => typeof p !== 'string')) {
+    throw new Error('cli.yaml: providers must be a string list');
+  }
+  const envRaw = doc.connection_environment;
+  if (envRaw === null || typeof envRaw !== 'object' || Array.isArray(envRaw)) {
+    throw new Error('cli.yaml: connection_environment must be a mapping');
+  }
+  const connection_environment: Record<string, string[]> = {};
+  for (const [dialect, vars] of Object.entries(envRaw)) {
+    if (!Array.isArray(vars) || vars.some((v) => typeof v !== 'string')) {
+      throw new Error(`cli.yaml: connection_environment.${dialect} must be a string list`);
+    }
+    connection_environment[dialect] = vars;
+  }
+  if (!Array.isArray(doc.commands)) {
+    throw new Error('cli.yaml: commands must be a list');
+  }
+  const commands = doc.commands.map((item, i) => {
+    if (item === null || typeof item !== 'object') {
+      throw new Error(`cli.yaml: commands[${i}] must be a mapping`);
+    }
+    const row = item as Record<string, unknown>;
+    const verb = requireString(row.verb, `commands[${i}].verb`);
+    if (!Array.isArray(row.args)) {
+      throw new Error(`cli.yaml: commands.${verb}.args must be a list`);
+    }
+    return {
+      verb,
+      summary: requireString(row.summary, `commands.${verb}.summary`),
+      examples: requireString(row.examples, `commands.${verb}.examples`),
+      show_connection_env: row.show_connection_env === true,
+      args: row.args.map((arg, j) => {
+        if (arg === null || typeof arg !== 'object') {
+          throw new Error(`cli.yaml: commands.${verb}.args[${j}] must be a mapping`);
+        }
+        const a = arg as Record<string, unknown>;
+        return {
+          flag: requireString(a.flag, `commands.${verb}.args[${j}].flag`),
+          placeholder: typeof a.placeholder === 'string' ? a.placeholder : undefined,
+          required: a.required === true,
+          help: requireString(a.help, `commands.${verb}.args[${j}].help`),
+        };
+      }),
+    };
+  });
+  return {
+    providers: doc.providers as string[],
+    connection_environment,
+    commands,
+  };
+};
+
+const wrapArgHelp = (flag: string, help: string, flagWidth: number): string => {
+  const lines = help.replace(/\s+$/, '').split('\n');
+  const indent = `  ${flag.padEnd(flagWidth)}  `;
+  const cont = ' '.repeat(indent.length);
+  return [indent + lines[0], ...lines.slice(1).map((line) => cont + line.trimStart())].join('\n');
+};
+
+const renderFlags = (args: HelpArg[]): string => {
+  const flagWidth = Math.max(...args.map((a) => a.flag.length));
+  return args.map((a) => wrapArgHelp(a.flag, a.help, flagWidth)).join('\n');
+};
+
+const renderConnectionEnv = (spec: HelpSpec): string => {
+  const nameWidth = Math.max(...spec.providers.map((p) => p.length));
+  const lines = spec.providers.map((name) => {
+    const vars = spec.connection_environment[name];
+    if (!vars) {
+      throw new Error(`cli.yaml: connection_environment missing ${name}`);
+    }
+    return `  ${name.padEnd(nameWidth)}  ${vars.join(', ')}`;
+  });
+  return [
+    'Per-dialect env vars consulted when --connection is omitted:',
+    ...lines,
+  ].join('\n');
+};
+
+const indentBlock = (text: string): string =>
+  text
+    .split('\n')
+    .map((line) => (line.length === 0 ? '' : `  ${line}`))
+    .join('\n');
+
+export const renderHelpTemplate = (spec: HelpSpec, command: HelpCommand): string => {
+  const parts = [
+    '{{usage}}',
+    '',
+    command.summary.replace(/\s+$/, ''),
+    '',
+    renderFlags(command.args),
+    '',
+    'Examples:',
+    indentBlock(command.examples.replace(/\s+$/, '')),
+  ];
+  if (command.show_connection_env) {
+    parts.push('', renderConnectionEnv(spec));
+  }
+  return `${parts.join('\n')}\n`;
+};
+
+export const renderHelpTemplates = (raw: unknown): Record<string, string> => {
+  const spec = parseHelpSpec(raw);
+  return Object.fromEntries(spec.commands.map((c) => [c.verb, renderHelpTemplate(spec, c)]));
+};
+
+export const generateHelpFiles = async (): Promise<string[]> => {
+  const files = renderHelpTemplates(parse(await readFile(CLI_YAML, 'utf8')));
+  const written: string[] = [];
+  const packagedDir = join(dirname(fileURLToPath(import.meta.url)), '..');
+  const packagedCli = join(packagedDir, 'cli.yaml');
+  await writeFile(packagedCli, await readFile(CLI_YAML, 'utf8'));
+  written.push(packagedCli);
+  const packagedBundle = join(packagedDir, 'bundle.yaml');
+  await writeFile(packagedBundle, await readFile(join(REPO_ROOT, 'bundle.yaml'), 'utf8'));
+  written.push(packagedBundle);
+  for (const [verb, text] of Object.entries(files)) {
+    const path = join(HELP_DIR, `${verb}.txt`);
+    await writeFile(path, text);
+    written.push(path);
+  }
+  return written;
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  const written = await generateHelpFiles();
+  for (const path of written) {
+    console.log(path);
+  }
+}

package/src/help.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import {
+  fillHelpTemplate,
+  migrateCommand,
+  verbFromCommand,
+  type MigrateVerb,
+} from './cli-contract.ts';
+import { loadHelp, loadProgramUsage } from './help.ts';
+
+const VERBS: MigrateVerb[] = ['setup', 'up', 'down', 'create'];
+
+describe('unified help loader', () => {
+  it('maps migrate-<verb> onto the shared template file', () => {
+    expect(verbFromCommand('migrate-create')).toBe('create');
+    expect(migrateCommand('create')).toBe('migrate-create');
+    expect(() => verbFromCommand('MigrateRunner')).toThrow(/Unknown migrate command/);
+  });
+
+  it('fills {{command}} and {{usage}} from cli.yaml', () => {
+    const filled = fillHelpTemplate('{{usage}}\n  {{command}} --name x\n', 'migrate-create');
+    expect(filled.startsWith('Usage: migrate-create --provider')).toBe(true);
+    expect(filled).toContain('migrate-create --name x');
+    expect(filled).not.toContain('{{');
+  });
+
+  it('loads program usage with the same migrate-<verb> Usage lines', async () => {
+    const text = await loadProgramUsage();
+    for (const verb of VERBS) {
+      expect(text).toContain(`Usage: ${migrateCommand(verb)} --provider`);
+    }
+    expect(text).toContain('Usage: migrate-init');
+    expect(text).not.toContain('{{command}}');
+    expect(text).not.toContain('MigrateRunner');
+    expect(text).not.toMatch(/^Usage: (create|up|down|setup) /m);
+  });
+
+  it('loads the same filled help the rust and csharp runners produce', async () => {
+    for (const verb of VERBS) {
+      const command = migrateCommand(verb);
+      const text = await loadHelp(command);
+      expect(text.startsWith(`Usage: ${command} --provider`)).toBe(true);
+      expect(text).toContain(`${command} --provider sqlite`);
+      expect(text).not.toContain('{{command}}');
+      expect(text).not.toMatch(/^Usage: (create|up|down|setup) /m);
+      expect(text).not.toMatch(/^\s+(create|up|down|setup) --provider/m);
+    }
+  });
+});

package/src/help.ts

@@ -0,0 +1,12 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fillHelpTemplate, programUsageText, verbFromCommand } from './cli-contract.ts';
+import { templatesRoot } from './infrastructure/templates-root.ts';
+
+export const loadHelp = async (command: string): Promise<string> => {
+  const verb = verbFromCommand(command);
+  const text = await readFile(join(templatesRoot(), 'help', `${verb}.txt`), 'utf8');
+  return fillHelpTemplate(text, command);
+};
+
+export const loadProgramUsage = async (): Promise<string> => programUsageText();

package/src/index.ts

@@ -0,0 +1,23 @@
+export * from './datasource-migrate.ts';
+export type {
+  CreateArg,
+  CreateResponse,
+  DownArg,
+  IMigrater,
+  SetupArg,
+  UpArg,
+} from './abstractions/migrater.ts';
+export { getMigrater, Migrater } from './migrater.ts';
+export {
+  fillHelpTemplate,
+  migrateCommand,
+  verbFromCommand,
+  type MigrateVerb,
+} from './cli-contract.ts';
+export { loadHelp, loadProgramUsage } from './help.ts';
+export {
+  fillTemplate,
+  loadMessage,
+  loadScaffold,
+} from './infrastructure/message-templates.ts';
+export { normalizeDialect, pathExists, type SqlDialect } from './sql.ts';

package/src/infrastructure/connection-resolver.ts

@@ -0,0 +1,18 @@
+import type { ISqlDialect } from '../abstractions/sql-dialect.ts';
+
+export class ConnectionResolver {
+  constructor(private readonly env: NodeJS.ProcessEnv = process.env) {}
+
+  fromEnvironment(dialect: ISqlDialect): string | null {
+    for (const name of dialect.connectionEnvironmentVariables) {
+      const value = this.env[name];
+      if (value) return value;
+    }
+    return null;
+  }
+
+  resolve(dialect: ISqlDialect, fromFlag: string | null): string | null {
+    if (fromFlag) return fromFlag;
+    return this.fromEnvironment(dialect);
+  }
+}

package/src/infrastructure/default-factory.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { defaultDialectFactory } from './default-factory.ts';
+
+describe('defaultDialectFactory', () => {
+  it('registers every dialect name and alias', () => {
+    const names = defaultDialectFactory.all().map((d) => d.name);
+    expect(names).toEqual(['sqlite', 'postgres', 'mysql', 'sqlserver', 'oracle']);
+    expect(defaultDialectFactory.get('sqlite3').name).toBe('sqlite');
+    expect(defaultDialectFactory.get('postgresql').name).toBe('postgres');
+    expect(defaultDialectFactory.get('mariadb').name).toBe('mysql');
+    expect(defaultDialectFactory.get('mssql').name).toBe('sqlserver');
+    expect(defaultDialectFactory.get('mssqlserver').name).toBe('sqlserver');
+    expect(defaultDialectFactory.get('ms-sql-server').name).toBe('sqlserver');
+    expect(defaultDialectFactory.get('ora').name).toBe('oracle');
+    expect(defaultDialectFactory.tryGet('nope')).toBeUndefined();
+    expect(() => defaultDialectFactory.get('nope')).toThrow(/Unknown SQL dialect/);
+  });
+});

package/src/infrastructure/default-factory.ts

@@ -0,0 +1,17 @@
+import { SqlDialectFactory } from '../abstractions/sql-dialect-factory.ts';
+import { MysqlDialect } from '../dialects/mysql-dialect.ts';
+import { OracleDialect } from '../dialects/oracle-dialect.ts';
+import { PostgresDialect } from '../dialects/postgres-dialect.ts';
+import { SqliteDialect } from '../dialects/sqlite-dialect.ts';
+import { SqlServerDialect } from '../dialects/sqlserver-dialect.ts';
+import { ConnectionResolver } from './connection-resolver.ts';
+
+export const defaultDialectFactory = new SqlDialectFactory([
+  new SqliteDialect(),
+  new PostgresDialect(),
+  new MysqlDialect(),
+  new SqlServerDialect(),
+  new OracleDialect(),
+]);
+
+export const connectionResolver = new ConnectionResolver();

package/src/infrastructure/interop-default.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+import { interopDefault } from './interop-default.ts';
+
+describe('interopDefault', () => {
+  it('prefers default when present and falls back to the module namespace', () => {
+    expect(interopDefault({ default: { connect: 1 } })).toEqual({ connect: 1 });
+    expect(interopDefault({ connect: 2 })).toEqual({ connect: 2 });
+  });
+});

package/src/infrastructure/interop-default.ts

@@ -0,0 +1,2 @@
+export const interopDefault = <T>(mod: { default?: T }): T =>
+  (mod.default ?? mod) as T;

package/src/infrastructure/message-templates.ts

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { templatesRoot } from './templates-root.ts';
+
+export const fillTemplate = (text: string, vars: Record<string, string>): string => {
+  let out = text;
+  for (const [key, value] of Object.entries(vars)) {
+    out = out.replaceAll(`{{${key}}}`, value);
+  }
+  return out;
+};
+
+export const loadMessage = async (
+  relativePath: string,
+  vars: Record<string, string> = {},
+): Promise<string> => {
+  const text = await readFile(
+    join(templatesRoot(), 'messages', `${relativePath}.txt`),
+    'utf8',
+  );
+  return fillTemplate(text, vars);
+};
+
+export const loadScaffold = async (
+  name: 'up' | 'down',
+  vars: Record<string, string>,
+): Promise<string> => {
+  const text = await readFile(join(templatesRoot(), 'scaffold', `${name}.sql`), 'utf8');
+  return fillTemplate(text, vars);
+};

package/src/infrastructure/split-on-go.ts

@@ -0,0 +1,19 @@
+const GO_LINE = /^\s*GO\s*$/i;
+
+/** Split migration SQL on whole-line GO batch separators. */
+export function splitOnGo(text: string): string[] {
+  const batches: string[] = [];
+  let buf = '';
+  for (const line of text.replace(/\r\n/g, '\n').split('\n')) {
+    if (GO_LINE.test(line)) {
+      const s = buf.trim();
+      if (s.length > 0) batches.push(s);
+      buf = '';
+      continue;
+    }
+    buf = buf.length > 0 ? `${buf}\n${line}` : line;
+  }
+  const tail = buf.trim();
+  if (tail.length > 0) batches.push(tail);
+  return batches;
+}

package/src/infrastructure/sql-templates.ts

@@ -0,0 +1,10 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { SqlDialect } from '../sql.ts';
+import { templatesRoot } from './templates-root.ts';
+
+export const readSqlTemplate = async (
+  dialect: SqlDialect,
+  name: 'migrates' | 'migrate_logs',
+): Promise<string> =>
+  (await readFile(join(templatesRoot(), 'sql', dialect, `${name}.sql`), 'utf8')).trim();

package/src/infrastructure/templates-root.ts

@@ -0,0 +1,13 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Repo `shared/templates`; after build, `dist/templates` (copied from shared). */
+export const templatesRoot = (): string => {
+  const normalized = HERE.replaceAll('\\', '/');
+  if (normalized.endsWith('/dist/infrastructure')) {
+    return join(HERE, '..', 'templates');
+  }
+  return join(HERE, '..', '..', '..', 'shared', 'templates');
+};

package/src/init-select.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { loadSelectedPackages, resolveInitDialects } from './init-select.ts';
+
+describe('init dialect selection', () => {
+  it('accepts aliases and keeps cli.yaml order', () => {
+    expect(resolveInitDialects(['ora', 'pg'], false)).toEqual(['postgres', 'oracle']);
+  });
+
+  it('restores every provider for --all', () => {
+    expect(resolveInitDialects([], true)).toEqual([
+      'sqlite',
+      'postgres',
+      'mysql',
+      'sqlserver',
+      'oracle',
+    ]);
+  });
+
+  it('reads typescript packages from bundle.yaml', async () => {
+    const selected = await loadSelectedPackages(['sqlite', 'postgres']);
+    expect(selected.packages.map((p) => p.name).sort()).toEqual(['better-sqlite3', 'pg']);
+    expect(selected.allDriverPackages).toEqual(
+      expect.arrayContaining(['better-sqlite3', 'pg', 'mysql2', 'mssql', 'oracledb']),
+    );
+  });
+});

package/src/init-select.ts

@@ -0,0 +1,73 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { cliSpec } from './cli-spec.ts';
+
+export type SelectedDialects = {
+  names: string[];
+  packages: { name: string; version: string }[];
+  allDriverPackages: string[];
+};
+
+const stripKey = (raw: string): string => raw.replace(/[\s_-]/g, '').toLowerCase();
+
+export const normalizeInitProvider = (raw: string): string | undefined => {
+  const key = stripKey(raw);
+  const direct = cliSpec.providers.find((p) => stripKey(p) === key);
+  if (direct) return direct;
+  return cliSpec.provider_aliases[key];
+};
+
+export const resolveInitDialects = (raw: string[], all: boolean): string[] => {
+  if (all) return [...cliSpec.providers];
+  if (raw.length === 0) {
+    throw new Error('pass --dialect <provider> at least once, or --all');
+  }
+  const selected = new Set<string>();
+  for (const value of raw) {
+    const name = normalizeInitProvider(value);
+    if (!name) {
+      throw new Error(`unsupported provider: ${value}`);
+    }
+    selected.add(name);
+  }
+  return cliSpec.providers.filter((name) => selected.has(name));
+};
+
+type BundleDialect = {
+  packages?: { name: string; version: string }[];
+};
+
+type BundleDoc = {
+  languages?: {
+    typescript?: {
+      dialects?: Record<string, BundleDialect>;
+    };
+  };
+};
+
+export const bundleYamlPath = (): string => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, '..', 'bundle.yaml'),
+    join(here, '..', '..', 'bundle.yaml'),
+    join(process.cwd(), 'bundle.yaml'),
+  ];
+  const found = candidates.find((candidate) => existsSync(candidate));
+  if (!found) {
+    throw new Error('bundle.yaml not found');
+  }
+  return found;
+};
+
+export const loadSelectedPackages = async (dialects: string[]): Promise<SelectedDialects> => {
+  const raw = parse(await readFile(bundleYamlPath(), 'utf8')) as BundleDoc;
+  const byName = raw.languages?.typescript?.dialects ?? {};
+  const allDriverPackages = [
+    ...new Set(Object.values(byName).flatMap((d) => (d.packages ?? []).map((p) => p.name))),
+  ];
+  const packages = dialects.flatMap((name) => byName[name]?.packages ?? []);
+  return { names: dialects, packages, allDriverPackages };
+};