@syncular/typegen 0.1.3 → 0.2.1

package/src/cli.ts

@@ -1,104 +1,183 @@
 #!/usr/bin/env bun
+/**
+ * The `syncular` CLI. Subcommands:
+ *
+ *   generate [--manifest-dir <dir>] [--check] [--watch]
+ *     Reads `syncular.json` + `migrations/` under the manifest dir and writes
+ *     the neutral IR JSON and generated TS module (paths from the manifest's
+ *     `output`). `--check` regenerates in memory and fails (exit 1) unless the
+ *     files on disk match byte-exactly. `--watch` regenerates on change.
+ *
+ *   init [--manifest-dir <dir>]
+ *     Drops a starter `syncular.json` + `migrations/0001_initial` into an
+ *     existing project (the "add syncular to my app" path).
+ *
+ * The generate CONTRACT (inputs, outputs, byte-exact `--check`) is unchanged;
+ * this file only adds `init`, `--watch`, and friendlier errors.
+ */
+import { watch } from 'node:fs';
+import { resolve } from 'node:path';
+import { checkOutputs, generate, writeOutputs } from './generate';
+import { InitError, initProject } from './init';
+import { MANIFEST_FILENAME } from './manifest';
 
-import { readFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import {
-  loadSyncularClientContract,
-  toSyncularCodegenJson,
-  writeSyncularCodegenJsonFromModule,
-} from './app-contract';
+const DOCS_HINT =
+  'See the schema guide: https://github.com/bkniffler/syncular (guide-schema), ' +
+  'or run `syncular init` to scaffold a starter manifest + migration.';
 
-interface CodegenConfigCommand {
-  app: string;
-  out: string;
-  exportName?: string;
+const USAGE = `usage: syncular <command> [options]
+
+commands:
+  generate   build the IR + typed module from syncular.json + migrations/
+  init       scaffold a starter syncular.json + migrations/0001_initial
+
+generate options:
+  --manifest-dir <dir>   directory holding syncular.json (default: .)
+  --check                fail unless generated files are byte-exactly fresh
+  --watch                regenerate on file change (Ctrl-C to stop)
+
+init options:
+  --manifest-dir <dir>   directory to scaffold into (default: .)`;
+
+function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}
+
+interface GenerateArgs {
+  manifestDir: string;
   check: boolean;
+  watch: boolean;
 }
 
-async function main(argv: string[]): Promise<void> {
-  const command = argv[0];
-  if (command !== 'codegen-config') {
-    printUsageAndExit(command ? `Unknown command ${command}` : undefined);
-  }
-  const options = parseCodegenConfigArgs(argv.slice(1));
-  if (options.check) {
-    const contract = await loadSyncularClientContract({
-      modulePath: options.app,
-      exportName: options.exportName,
-    });
-    const expected = toSyncularCodegenJson(contract);
-    const actual = await readFile(options.out, 'utf8').catch((error) => {
-      throw new Error(
-        `Cannot read ${options.out}; run without --check to generate it first: ${error.message}`
-      );
-    });
-    if (actual !== expected) {
-      throw new Error(
-        `${options.out} does not match ${options.app}; run syncular generate --app ${options.app}`
-      );
+function parseGenerateArgs(argv: readonly string[]): GenerateArgs {
+  const args: GenerateArgs = { manifestDir: '.', check: false, watch: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--check') {
+      args.check = true;
+    } else if (arg === '--watch') {
+      args.watch = true;
+    } else if (arg === '--manifest-dir') {
+      const value = argv[i + 1];
+      if (value === undefined) fail('--manifest-dir requires a value');
+      args.manifestDir = value;
+      i += 1;
+    } else {
+      fail(`unknown argument ${JSON.stringify(arg)}\n${USAGE}`);
     }
-    return;
   }
-  await writeSyncularCodegenJsonFromModule({
-    modulePath: options.app,
-    exportName: options.exportName,
-    outputPath: options.out,
-  });
+  if (args.check && args.watch) {
+    fail('--check and --watch cannot be combined');
+  }
+  return args;
 }
 
-function parseCodegenConfigArgs(args: string[]): CodegenConfigCommand {
-  let app: string | undefined;
-  let out: string | undefined;
-  let exportName: string | undefined;
-  let check = false;
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-    if (arg === '--app') {
-      app = requireValue(args, (index += 1), '--app');
-    } else if (arg === '--out') {
-      out = requireValue(args, (index += 1), '--out');
-    } else if (arg === '--export') {
-      exportName = requireValue(args, (index += 1), '--export');
-    } else if (arg === '--check') {
-      check = true;
-    } else if (arg === '--help' || arg === '-h') {
-      printUsageAndExit();
+function parseManifestDir(argv: readonly string[]): string {
+  let manifestDir = '.';
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--manifest-dir') {
+      const value = argv[i + 1];
+      if (value === undefined) fail('--manifest-dir requires a value');
+      manifestDir = value;
+      i += 1;
     } else {
-      printUsageAndExit(`Unknown option ${arg}`);
+      fail(`unknown argument ${JSON.stringify(arg)}\n${USAGE}`);
     }
   }
-  if (!app) printUsageAndExit('Missing --app');
-  return {
-    app,
-    out: out ?? defaultCodegenConfigPath(app),
-    exportName,
-    check,
-  };
+  return manifestDir;
 }
 
-function defaultCodegenConfigPath(app: string): string {
-  const appPath = app.startsWith('file:') ? fileURLToPath(app) : app;
-  return join(dirname(appPath), 'generated', 'syncular.codegen.json');
+/** Add a docs pointer to the fail-loud missing-input errors. */
+function friendlyGenerateError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (
+    message.includes('manifest not found') ||
+    message.includes('migrations directory does not exist') ||
+    message.includes('no migrations found')
+  ) {
+    return `${message}\n${DOCS_HINT}`;
+  }
+  return message;
 }
 
-function requireValue(args: string[], index: number, option: string): string {
-  const value = args[index];
-  if (!value || value.startsWith('--')) {
-    printUsageAndExit(`${option} requires a value`);
+function runGenerateOnce(args: GenerateArgs): void {
+  let result: ReturnType<typeof generate>;
+  try {
+    result = generate(args.manifestDir);
+  } catch (error) {
+    fail(friendlyGenerateError(error));
+  }
+  if (args.check) {
+    const drift = checkOutputs(result);
+    if (drift.length > 0) {
+      fail(`generated output is out of date:\n${drift.join('\n')}`);
+    }
+    console.log('generated output is up to date');
+    return;
+  }
+  writeOutputs(result);
+  for (const output of result.outputs) {
+    console.log(`wrote ${output.path}`);
   }
-  return value;
 }
 
-function printUsageAndExit(message?: string): never {
-  if (message) console.error(message);
-  console.error(
-    [
-      'Usage:',
-      '  syncular-typegen codegen-config --app ./syncular.app.ts [--out ./generated/syncular.codegen.json] [--export app] [--check]',
-    ].join('\n')
-  );
-  process.exit(message ? 1 : 0);
+/** `--watch`: regenerate on any change under the manifest dir. Uses Bun's
+ * `fs.watch` recursively; debounced so a burst of writes triggers one run. */
+function runGenerateWatch(args: GenerateArgs): void {
+  const dir = resolve(args.manifestDir);
+  const safeRun = (): void => {
+    try {
+      const result = generate(args.manifestDir);
+      // Skip the write when the outputs are already fresh — otherwise writing
+      // them (they live under the watched dir) would re-trigger the watcher in
+      // a loop.
+      if (checkOutputs(result).length === 0) return;
+      writeOutputs(result);
+      console.log(`regenerated ${result.modulePath}`);
+    } catch (error) {
+      // In watch mode a bad intermediate state is expected — report, don't die.
+      console.error(friendlyGenerateError(error));
+    }
+  };
+  safeRun();
+  console.log(`watching ${dir} for changes (Ctrl-C to stop)…`);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  watch(dir, { recursive: true }, () => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(safeRun, 50);
+  });
 }
 
-await main(process.argv.slice(2));
+export function runCli(argv: readonly string[]): void {
+  const command = argv[0];
+  if (command === 'generate') {
+    const args = parseGenerateArgs(argv.slice(1));
+    if (args.watch) {
+      runGenerateWatch(args);
+      return;
+    }
+    runGenerateOnce(args);
+    return;
+  }
+  if (command === 'init') {
+    const dir = parseManifestDir(argv.slice(1));
+    try {
+      const result = initProject(dir);
+      for (const path of result.written) console.log(`wrote ${path}`);
+      console.log(
+        '\nNext: `syncular generate` to build the typed schema, then wire ' +
+          `${MANIFEST_FILENAME}'s "output.module" into your server + client.`,
+      );
+    } catch (error) {
+      fail(error instanceof InitError ? error.message : String(error));
+    }
+    return;
+  }
+  fail(USAGE);
+}
+
+if (import.meta.main) {
+  runCli(process.argv.slice(2));
+}

package/src/emit-dart.ts

@@ -0,0 +1,245 @@
+/**
+ * Dart emitter: neutral IR → one standalone `.dart` file exporting
+ *
+ * - `const syncularSchema` — the ServerSchema-compatible `Map<String,
+ *   Object?>` built from the IR (fed straight into `SyncularClient.create(
+ *   schema: …)`),
+ * - one class per table with typed fields (per the six §2.4 column types +
+ *   blob_ref/crdt) and a `fromRow(Map<String, Object?>)` factory,
+ * - a `syncular<Name>Subscription` helper per subscription with a typed
+ *   `scopes(...)` builder.
+ *
+ * The row shape is `Map<String, Object?>` — the exact type the Dart wrapper's
+ * `query`/`readRows` return. The header carries the IR hash so `--check`
+ * verifies freshness byte-exactly.
+ */
+import type { IrColumnType, IrDocument, IrSubscription, IrTable } from './ir';
+
+/** §2.4 column type → honest Dart type. `json`/`blob_ref` are the raw
+ * canonical JSON string; `bytes`/`crdt` are opaque `List<int>`. */
+const DART_TYPE: Readonly<Record<IrColumnType, string>> = {
+  string: 'String',
+  integer: 'int',
+  float: 'double',
+  boolean: 'bool',
+  json: 'String',
+  bytes: 'List<int>',
+  blob_ref: 'String',
+  crdt: 'List<int>',
+};
+
+/** §5.11: app-side Dart type — declaredType for an encrypted column. */
+function appDartType(column: IrTable['columns'][number]): string {
+  const type =
+    column.encrypted === true && column.declaredType !== undefined
+      ? column.declaredType
+      : column.type;
+  return DART_TYPE[type];
+}
+
+function pascalCase(name: string): string {
+  return name
+    .split(/[_-]+/)
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+function camelCase(name: string): string {
+  const pascal = pascalCase(name);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+function quote(value: string): string {
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\$/g, '\\$')}'`;
+}
+
+function emitSchemaValue(ir: IrDocument, indent: string): string[] {
+  const lines: string[] = [];
+  const i = indent;
+  lines.push(`${i}<String, Object?>{`);
+  lines.push(`${i}  'version': ${ir.schemaVersion},`);
+  lines.push(`${i}  'tables': [`);
+  for (const table of ir.tables) {
+    lines.push(`${i}    {`);
+    lines.push(`${i}      'name': ${quote(table.name)},`);
+    lines.push(`${i}      'primaryKey': ${quote(table.primaryKey)},`);
+    lines.push(`${i}      'columns': [`);
+    for (const column of table.columns) {
+      const parts = [
+        `'name': ${quote(column.name)}`,
+        `'type': ${quote(column.type)}`,
+        `'nullable': ${column.nullable}`,
+      ];
+      if (column.crdtType !== undefined) {
+        parts.push(`'crdtType': ${quote(column.crdtType)}`);
+      }
+      if (column.encrypted === true) {
+        parts.push("'encrypted': true");
+        parts.push(
+          `'declaredType': ${quote(column.declaredType ?? column.type)}`,
+        );
+      }
+      lines.push(`${i}        {${parts.join(', ')}},`);
+    }
+    lines.push(`${i}      ],`);
+    lines.push(`${i}      'scopes': [`);
+    for (const scope of table.scopes) {
+      lines.push(
+        `${i}        {'pattern': ${quote(scope.pattern)}, 'column': ${quote(scope.column)}},`,
+      );
+    }
+    lines.push(`${i}      ],`);
+    lines.push(`${i}    },`);
+  }
+  lines.push(`${i}  ],`);
+  lines.push(`${i}}`);
+  return lines;
+}
+
+/** The accessor lifting a §2.4 value out of a `Map<String, Object?>` row. */
+function rowAccessor(column: { type: IrColumnType; name: string }): string {
+  const key = `row[${quote(column.name)}]`;
+  switch (column.type) {
+    case 'string':
+    case 'json':
+    case 'blob_ref':
+      return `${key} as String?`;
+    case 'integer':
+      return `(${key} as num?)?.toInt()`;
+    case 'float':
+      return `(${key} as num?)?.toDouble()`;
+    case 'boolean':
+      return `_rowBool(${key})`;
+    case 'bytes':
+    case 'crdt':
+      return `_rowBytes(${key})`;
+  }
+}
+
+function emitClass(table: IrTable): string[] {
+  const type = pascalCase(table.name);
+  const lines: string[] = [];
+  lines.push(`/// One ${table.name} row (§2.4 column order).`);
+  lines.push(`class ${type} {`);
+  for (const column of table.columns) {
+    const dart = appDartType(column);
+    const opt = column.nullable ? '?' : '';
+    lines.push(`  final ${dart}${opt} ${camelCase(column.name)};`);
+  }
+  lines.push('');
+  const ctorParams = table.columns
+    .map((c) => `${c.nullable ? '' : 'required '}this.${camelCase(c.name)}`)
+    .join(', ');
+  lines.push(`  const ${type}({${ctorParams}});`);
+  lines.push('');
+  lines.push(
+    `  /// Build from a \`query\`/\`readRows\` row. Returns null when a`,
+  );
+  lines.push(`  /// non-nullable column is missing or mistyped.`);
+  lines.push(`  static ${type}? fromRow(Map<String, Object?> row) {`);
+  for (const column of table.columns) {
+    if (!column.nullable) {
+      const name = camelCase(column.name);
+      lines.push(`    final ${name} = ${rowAccessor(column)};`);
+      lines.push(`    if (${name} == null) return null;`);
+    }
+  }
+  const args = table.columns
+    .map((c) => {
+      const name = camelCase(c.name);
+      return c.nullable ? `${name}: ${rowAccessor(c)}` : `${name}: ${name}`;
+    })
+    .join(', ');
+  lines.push(`    return ${type}(${args});`);
+  lines.push('  }');
+  lines.push('}');
+  return lines;
+}
+
+function emitSubscription(sub: IrSubscription): string[] {
+  const params: string[] = [];
+  for (const scope of sub.scopes) {
+    for (const value of scope.values) {
+      if (value.kind === 'parameter' && !params.includes(value.name)) {
+        params.push(value.name);
+      }
+    }
+  }
+  const lines: string[] = [];
+  lines.push(
+    `/// Requested-scope template for the ${quote(sub.name)} subscription.`,
+  );
+  lines.push(`class Syncular${pascalCase(sub.name)}Subscription {`);
+  lines.push(`  static const String name = ${quote(sub.name)};`);
+  lines.push(`  static const String table = ${quote(sub.table)};`);
+  const args = params.map((p) => `required String ${camelCase(p)}`).join(', ');
+  const argsClause = args.length > 0 ? `{${args}}` : '';
+  lines.push(`  static Map<String, List<String>> scopes(${argsClause}) => {`);
+  for (const scope of sub.scopes) {
+    const values = scope.values
+      .map((value) =>
+        value.kind === 'literal' ? quote(value.value) : camelCase(value.name),
+      )
+      .join(', ');
+    lines.push(`        ${quote(scope.variable)}: [${values}],`);
+  }
+  lines.push('      };');
+  lines.push('}');
+  return lines;
+}
+
+export function emitDartModule(ir: IrDocument, hash: string): string {
+  const parts: string[] = [];
+  parts.push(
+    [
+      '// Generated by @syncular/typegen — DO NOT EDIT.',
+      `// irVersion: ${ir.irVersion}`,
+      `// irHash: ${hash}`,
+      '// ignore_for_file: type=lint',
+    ].join('\n'),
+  );
+
+  // The schema constant.
+  const schemaLines: string[] = [];
+  schemaLines.push('/// ServerSchema-compatible schema (SPEC §2.4, §3.1) —');
+  schemaLines.push('/// pass to `SyncularClient.create(schema: …)`.');
+  const schemaValue = emitSchemaValue(ir, '');
+  schemaValue[0] = `const Map<String, Object?> syncularSchema = ${schemaValue[0]}`;
+  schemaValue[schemaValue.length - 1] =
+    `${schemaValue[schemaValue.length - 1]};`;
+  for (const line of schemaValue) schemaLines.push(line);
+  parts.push(schemaLines.join('\n'));
+
+  // Shared row-decode helpers.
+  parts.push(
+    [
+      '/// Lift a SQLite boolean: a real bool, or 0/1 as a number.',
+      'bool? _rowBool(Object? value) {',
+      '  if (value is bool) return value;',
+      '  if (value is num) return value != 0;',
+      '  return null;',
+      '}',
+      '',
+      "/// Decode the core's {'\\$bytes': '<hex>'} marshaling (bytes as hex).",
+      'List<int>? _rowBytes(Object? value) {',
+      '  if (value is! Map) return null;',
+      "  final hex = value[r'$bytes'];",
+      '  if (hex is! String || hex.length % 2 != 0) return null;',
+      '  return [',
+      '    for (var i = 0; i < hex.length; i += 2)',
+      '      int.parse(hex.substring(i, i + 2), radix: 16),',
+      '  ];',
+      '}',
+    ].join('\n'),
+  );
+
+  for (const table of ir.tables) {
+    parts.push(emitClass(table).join('\n'));
+  }
+  for (const sub of ir.subscriptions) {
+    parts.push(emitSubscription(sub).join('\n'));
+  }
+
+  return `${parts.join('\n\n')}\n`;
+}