@syncular/typegen 0.58.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/README.md +96 -43
  2. package/dist/cli.js +8 -3
  3. package/dist/emit-dart.d.ts +4 -3
  4. package/dist/emit-dart.js +40 -100
  5. package/dist/emit-kotlin.d.ts +4 -4
  6. package/dist/emit-kotlin.js +41 -99
  7. package/dist/emit-queries-dart.d.ts +1 -1
  8. package/dist/emit-queries-dart.js +17 -26
  9. package/dist/emit-queries-kotlin.d.ts +1 -1
  10. package/dist/emit-queries-kotlin.js +15 -24
  11. package/dist/emit-queries-rust.d.ts +1 -1
  12. package/dist/emit-queries-rust.js +18 -19
  13. package/dist/emit-queries-swift.d.ts +1 -1
  14. package/dist/emit-queries-swift.js +22 -26
  15. package/dist/emit-queries.d.ts +1 -1
  16. package/dist/emit-queries.js +18 -27
  17. package/dist/emit-swift.d.ts +4 -4
  18. package/dist/emit-swift.js +43 -102
  19. package/dist/emit.d.ts +3 -3
  20. package/dist/emit.js +37 -113
  21. package/dist/errors.d.ts +6 -2
  22. package/dist/errors.js +10 -2
  23. package/dist/fmt.js +11 -2
  24. package/dist/generate.d.ts +4 -3
  25. package/dist/generate.js +61 -73
  26. package/dist/init.js +5 -6
  27. package/dist/ir.d.ts +14 -2
  28. package/dist/ir.js +67 -49
  29. package/dist/lower.d.ts +0 -7
  30. package/dist/lower.js +0 -62
  31. package/dist/lsp.js +6 -1
  32. package/dist/manifest.d.ts +1 -2
  33. package/dist/manifest.js +13 -12
  34. package/dist/migration-lock.d.ts +32 -23
  35. package/dist/migration-lock.js +115 -92
  36. package/dist/naming.d.ts +25 -0
  37. package/dist/naming.js +92 -0
  38. package/dist/query.d.ts +94 -14
  39. package/dist/query.js +642 -461
  40. package/dist/sql.js +18 -3
  41. package/dist/syql-ast.d.ts +2 -0
  42. package/dist/syql-ast.js +7 -1
  43. package/dist/syql-browser.js +7 -6
  44. package/dist/syql-diagnostics.d.ts +1 -0
  45. package/dist/syql-diagnostics.js +1 -0
  46. package/dist/syql-lowering.js +11 -1
  47. package/dist/syql-parser.d.ts +4 -1
  48. package/dist/syql-parser.js +42 -5
  49. package/dist/syql-validator.js +13 -220
  50. package/package.json +3 -3
  51. package/src/cli.ts +9 -3
  52. package/src/emit-dart.ts +44 -116
  53. package/src/emit-kotlin.ts +41 -118
  54. package/src/emit-queries-dart.ts +23 -32
  55. package/src/emit-queries-kotlin.ts +20 -30
  56. package/src/emit-queries-rust.ts +29 -31
  57. package/src/emit-queries-swift.ts +26 -32
  58. package/src/emit-queries.ts +26 -47
  59. package/src/emit-swift.ts +49 -120
  60. package/src/emit.ts +45 -135
  61. package/src/errors.ts +13 -2
  62. package/src/fmt.ts +10 -2
  63. package/src/generate.ts +113 -107
  64. package/src/init.ts +8 -6
  65. package/src/ir.ts +91 -54
  66. package/src/lower.ts +0 -53
  67. package/src/lsp.ts +11 -4
  68. package/src/manifest.ts +22 -18
  69. package/src/migration-lock.ts +192 -137
  70. package/src/naming.ts +154 -0
  71. package/src/query.ts +864 -502
  72. package/src/sql.ts +30 -3
  73. package/src/syql-ast.ts +9 -0
  74. package/src/syql-browser.ts +8 -7
  75. package/src/syql-diagnostics.ts +2 -0
  76. package/src/syql-lowering.ts +16 -1
  77. package/src/syql-parser.ts +73 -8
  78. package/src/syql-validator.ts +21 -279
package/src/manifest.ts CHANGED
@@ -14,8 +14,8 @@
14
14
  * "dart": "./lib/syncular.generated.dart" },
15
15
  * "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
16
16
  * "tables": [{ "name": "tasks", "scopes": ["project:{project_id}"] }],
17
- * "subscriptions": [{ "name": "projectTasks", "table": "tasks",
18
- * "scopes": { "project_id": ["{projectId}"] } }],
17
+ * "subscriptions": [{ "name": "projectTasks",
18
+ * "scopes": { "project_id": "{projectId}" } }],
19
19
  * "extensions": {}
20
20
  * }
21
21
  * ```
@@ -24,8 +24,10 @@
24
24
  * - `schemaVersions` is the §1.5 version history: strictly increasing
25
25
  * versions, each naming the last migration it includes (`through`); the
26
26
  * final entry must cover the final migration.
27
- * - Subscription scope values are literals or whole-value `{param}`
28
- * placeholders (partial templates are unsupported).
27
+ * - A subscription is a unit template (SPEC §4.1): one literal or
28
+ * whole-value `{param}` placeholder per scope variable (partial templates
29
+ * are unsupported), no table. The unit covers every table declaring all of
30
+ * its variables; a template that covers no table is an error.
29
31
  * - `output.ir` / `output.module` are the always-emitted TS defaults;
30
32
  * `output.queryIr` opts into the deterministic analyzed-query document.
31
33
  * `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native schema
@@ -68,8 +70,7 @@ export interface ManifestTable {
68
70
 
69
71
  export interface ManifestSubscription {
70
72
  readonly name: string;
71
- readonly table: string;
72
- readonly scopes: Readonly<Record<string, readonly string[]>>;
73
+ readonly scopes: Readonly<Record<string, string>>;
73
74
  }
74
75
 
75
76
  export interface ManifestSchemaVersion {
@@ -332,30 +333,33 @@ function parseSubscription(
332
333
  ): ManifestSubscription {
333
334
  const context = `subscriptions[${index}]`;
334
335
  const obj = asObject(value, context);
335
- rejectUnknownKeys(obj, ['name', 'table', 'scopes'], context);
336
336
  const name = asString(obj.name, `${context}.name`);
337
337
  if (!IDENTIFIER_RE.test(name)) {
338
338
  fail(
339
339
  `subscription ${JSON.stringify(name)}: name must be a valid identifier`,
340
340
  );
341
341
  }
342
- const table = asString(obj.table, `subscription ${name}: table`);
343
342
  const scopesObj = asObject(obj.scopes, `subscription ${name}: scopes`);
344
- const scopes: Record<string, readonly string[]> = {};
345
- for (const [variable, values] of Object.entries(scopesObj)) {
346
- if (!Array.isArray(values) || values.length === 0) {
347
- fail(
348
- `subscription ${name}: scopes.${variable} must be a non-empty array`,
349
- );
350
- }
351
- scopes[variable] = values.map((v, i) =>
352
- asString(v, `subscription ${name}: scopes.${variable}[${i}]`),
343
+ if ('table' in obj || Object.values(scopesObj).some(Array.isArray)) {
344
+ throw new TypegenError(
345
+ SOURCE,
346
+ 'a subscription is a unit template { "name", "scopes": { "<variable>": "<value or {param}>" } } with one value per scope variable and no table (SPEC §4.1); several values are several templates',
347
+ 'typegen.subscription_legacy_shape',
348
+ { subscription: name },
349
+ );
350
+ }
351
+ rejectUnknownKeys(obj, ['name', 'scopes'], context);
352
+ const scopes: Record<string, string> = {};
353
+ for (const [variable, scope] of Object.entries(scopesObj)) {
354
+ scopes[variable] = asString(
355
+ scope,
356
+ `subscription ${name}: scopes.${variable}`,
353
357
  );
354
358
  }
355
359
  if (Object.keys(scopes).length === 0) {
356
360
  fail(`subscription ${name}: scopes must not be empty`);
357
361
  }
358
- return { name, table, scopes };
362
+ return { name, scopes };
359
363
  }
360
364
 
361
365
  function parseSchemaVersion(
@@ -2,23 +2,24 @@
2
2
  * Immutable application-migration history.
3
3
  *
4
4
  * `syncular.migrations.lock.json` is a version-controlled baseline of every
5
- * migration that has been accepted so far. Existing entries are immutable;
6
- * generation may only append newly named migrations. Format 2 stores one
7
- * canonical head-schema snapshot for actionable diagnostics instead of a
8
- * cumulative schema copy after every migration. Format 1 remains readable and
9
- * writable until an explicit `migrations upgrade-lock` command replaces it.
5
+ * migration that has been accepted so far, with the schema version each one
6
+ * belongs to. Existing entries are immutable; generation may only append newly
7
+ * named migrations, in a schema version above the highest locked one (§7.4).
8
+ * Format 3 stores one canonical head-schema snapshot for actionable
9
+ * diagnostics. Formats 1 and 2 predate per-migration versions: only the
10
+ * explicit `migrations upgrade-lock` command reads them.
10
11
  */
11
12
  import { createHash } from 'node:crypto';
12
13
  import { existsSync, readFileSync } from 'node:fs';
13
14
  import { resolve } from 'node:path';
14
15
  import { TypegenError } from './errors';
15
16
  import type { MigrationInput } from './generate';
16
- import type { IrColumn, IrColumnType } from './ir';
17
+ import type { IrColumn, IrColumnType, IrSchemaVersion } from './ir';
18
+ import { MANIFEST_FILENAME, type ManifestSchemaVersion } from './manifest';
17
19
  import { applyMigrationSql, type ParsedTable } from './sql';
18
20
 
19
21
  export const MIGRATION_LOCK_FILENAME = 'syncular.migrations.lock.json';
20
- export const MIGRATION_LOCK_FORMAT_VERSION = 2;
21
- export const LEGACY_MIGRATION_LOCK_FORMAT_VERSION = 1;
22
+ export const MIGRATION_LOCK_FORMAT_VERSION = 3;
22
23
 
23
24
  export interface MigrationLockColumn {
24
25
  readonly name: string;
@@ -36,18 +37,11 @@ export interface MigrationLockTable {
36
37
  export interface MigrationLockEntry {
37
38
  readonly name: string;
38
39
  readonly sha256: string;
40
+ /** The schema version this migration belongs to (§1.5, §7.4). */
41
+ readonly schemaVersion: number;
39
42
  }
40
43
 
41
- export interface LegacyMigrationLockEntry extends MigrationLockEntry {
42
- readonly tables: readonly MigrationLockTable[];
43
- }
44
-
45
- export interface LegacyMigrationLock {
46
- readonly formatVersion: typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION;
47
- readonly migrations: readonly LegacyMigrationLockEntry[];
48
- }
49
-
50
- export interface MigrationLockV2 {
44
+ export interface MigrationLock {
51
45
  readonly formatVersion: typeof MIGRATION_LOCK_FORMAT_VERSION;
52
46
  readonly migrations: readonly MigrationLockEntry[];
53
47
  readonly head: {
@@ -55,10 +49,17 @@ export interface MigrationLockV2 {
55
49
  };
56
50
  }
57
51
 
58
- export type MigrationLock = LegacyMigrationLock | MigrationLockV2;
52
+ /** A format-1 or format-2 lock: names and checksums without schema versions,
53
+ * read only to upgrade it to the current format. */
54
+ export interface LegacyMigrationLock {
55
+ readonly formatVersion: 1 | 2;
56
+ readonly migrations: readonly Omit<MigrationLockEntry, 'schemaVersion'>[];
57
+ }
59
58
 
60
- interface CurrentMigrationHistory {
61
- readonly migrations: readonly LegacyMigrationLockEntry[];
59
+ interface HistoryEntry {
60
+ readonly name: string;
61
+ readonly sha256: string;
62
+ readonly tables: readonly MigrationLockTable[];
62
63
  }
63
64
 
64
65
  function normalizedSql(sql: string): string {
@@ -94,21 +95,51 @@ function snapshotTables(
94
95
  }
95
96
 
96
97
  /** The names of every migration a committed lock has made immutable. */
97
- export function lockedMigrationNames(lock: MigrationLock): ReadonlySet<string> {
98
+ export function lockedMigrationNames(
99
+ lock: MigrationLock | LegacyMigrationLock,
100
+ ): ReadonlySet<string> {
98
101
  return new Set(lock.migrations.map((migration) => migration.name));
99
102
  }
100
103
 
104
+ /** Resolve the manifest's `schemaVersions` (each naming the last migration
105
+ * it includes) into the migrations every version adds (§1.5). */
106
+ export function buildSchemaVersions(
107
+ declared: readonly ManifestSchemaVersion[],
108
+ migrations: readonly MigrationInput[],
109
+ ): IrSchemaVersion[] {
110
+ const names = migrations.map((m) => m.name);
111
+ let cursor = 0;
112
+ const out = declared.map((entry) => {
113
+ const index = names.indexOf(entry.through, cursor);
114
+ if (index === -1) {
115
+ throw new TypegenError(
116
+ MANIFEST_FILENAME,
117
+ `schemaVersions: version ${entry.version} names migration ${JSON.stringify(entry.through)}, which does not exist after ${JSON.stringify(names[cursor - 1] ?? '(start)')} (migrations: ${names.join(', ')})`,
118
+ );
119
+ }
120
+ const covered = names.slice(cursor, index + 1);
121
+ cursor = index + 1;
122
+ return { version: entry.version, migrations: covered };
123
+ });
124
+ if (cursor !== names.length) {
125
+ throw new TypegenError(
126
+ MANIFEST_FILENAME,
127
+ `schemaVersions: migrations ${names.slice(cursor).join(', ')} are not covered by any schema version — the last entry's "through" must be the last migration`,
128
+ );
129
+ }
130
+ return out;
131
+ }
132
+
101
133
  /** Replay a complete migration sequence with ephemeral diagnostic snapshots.
102
134
  * Migrations named in `lockedNames` replay as deployed history; rules that
103
135
  * only appended migrations must satisfy are skipped for them. */
104
136
  function buildMigrationHistory(
105
137
  migrations: readonly MigrationInput[],
106
138
  lockedNames?: ReadonlySet<string>,
107
- ): CurrentMigrationHistory {
139
+ ): HistoryEntry[] {
108
140
  const tables = new Map<string, ParsedTable>();
109
141
  const droppedTables = new Set<string>();
110
- const entries: LegacyMigrationLockEntry[] = [];
111
- for (const migration of migrations) {
142
+ return migrations.map((migration) => {
112
143
  applyMigrationSql(
113
144
  tables,
114
145
  migration.sql,
@@ -116,52 +147,42 @@ function buildMigrationHistory(
116
147
  droppedTables,
117
148
  { lockedHistory: lockedNames?.has(migration.name) === true },
118
149
  );
119
- entries.push({
150
+ return {
120
151
  name: migration.name,
121
152
  sha256: checksum(migration.sql),
122
153
  tables: snapshotTables(tables),
123
- });
124
- }
125
- return { migrations: entries };
154
+ };
155
+ });
126
156
  }
127
157
 
128
158
  function lockFromHistory(
129
- history: CurrentMigrationHistory,
130
- formatVersion:
131
- | typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION
132
- | typeof MIGRATION_LOCK_FORMAT_VERSION,
159
+ history: readonly HistoryEntry[],
160
+ schemaVersions: readonly IrSchemaVersion[],
133
161
  ): MigrationLock {
134
- if (history.migrations.length === 0) {
135
- failLock('cannot lock an empty migration history');
136
- }
137
- if (formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
138
- return {
139
- formatVersion: LEGACY_MIGRATION_LOCK_FORMAT_VERSION,
140
- migrations: history.migrations,
141
- };
142
- }
143
- const head = history.migrations.at(-1) as LegacyMigrationLockEntry;
162
+ const head = history.at(-1);
163
+ if (head === undefined) failLock('cannot lock an empty migration history');
144
164
  return {
145
165
  formatVersion: MIGRATION_LOCK_FORMAT_VERSION,
146
- migrations: history.migrations.map(({ name, sha256 }) => ({
147
- name,
148
- sha256,
149
- })),
166
+ migrations: history.map(({ name, sha256 }) => {
167
+ const version = schemaVersions.find((v) => v.migrations.includes(name));
168
+ if (version === undefined) {
169
+ throw new Error(`unreachable: migration ${name} has no schema version`);
170
+ }
171
+ return { name, sha256, schemaVersion: version.version };
172
+ }),
150
173
  head: { tables: head.tables },
151
174
  };
152
175
  }
153
176
 
154
- /** Build a deterministic lock document for a complete migration sequence. */
177
+ /** Build a deterministic lock document for a complete migration sequence;
178
+ * `declared` is the manifest's `schemaVersions`. */
155
179
  export function buildMigrationLock(
156
180
  migrations: readonly MigrationInput[],
157
- formatVersion:
158
- | typeof LEGACY_MIGRATION_LOCK_FORMAT_VERSION
159
- | typeof MIGRATION_LOCK_FORMAT_VERSION = MIGRATION_LOCK_FORMAT_VERSION,
160
- lockedNames?: ReadonlySet<string>,
181
+ declared: readonly ManifestSchemaVersion[],
161
182
  ): MigrationLock {
162
183
  return lockFromHistory(
163
- buildMigrationHistory(migrations, lockedNames),
164
- formatVersion,
184
+ buildMigrationHistory(migrations),
185
+ buildSchemaVersions(declared, migrations),
165
186
  );
166
187
  }
167
188
 
@@ -233,37 +254,23 @@ function parseTable(value: unknown, context: string): MigrationLockTable {
233
254
  };
234
255
  }
235
256
 
236
- function parseEntry(value: unknown, index: number): MigrationLockEntry {
257
+ function parseEntry(
258
+ value: unknown,
259
+ index: number,
260
+ ): Omit<MigrationLockEntry, 'schemaVersion'> & { schemaVersion?: unknown } {
237
261
  const context = `migrations[${index}]`;
238
262
  if (!isRecord(value)) failLock(`${context} must be an object`);
239
- const { name, sha256 } = value;
263
+ const { name, sha256, schemaVersion } = value;
240
264
  if (typeof name !== 'string' || name.length === 0) {
241
265
  failLock(`${context}.name must be a non-empty string`);
242
266
  }
243
267
  if (typeof sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(sha256)) {
244
268
  failLock(`${context}.sha256 must be a lowercase SHA-256 digest`);
245
269
  }
246
- return { name, sha256 };
270
+ return { name, sha256, schemaVersion };
247
271
  }
248
272
 
249
- function parseLegacyEntry(
250
- value: unknown,
251
- index: number,
252
- ): LegacyMigrationLockEntry {
253
- const context = `migrations[${index}]`;
254
- const entry = parseEntry(value, index);
255
- if (!isRecord(value)) failLock(`${context} must be an object`);
256
- const { tables } = value;
257
- if (!Array.isArray(tables)) failLock(`${context}.tables must be an array`);
258
- return {
259
- ...entry,
260
- tables: tables.map((table, tableIndex) =>
261
- parseTable(table, `${context}.tables[${tableIndex}]`),
262
- ),
263
- };
264
- }
265
-
266
- function parseHead(value: unknown): MigrationLockV2['head'] {
273
+ function parseHead(value: unknown): MigrationLock['head'] {
267
274
  if (!isRecord(value)) failLock('head must be an object');
268
275
  if (!Array.isArray(value.tables)) failLock('head.tables must be an array');
269
276
  return {
@@ -273,20 +280,10 @@ function parseHead(value: unknown): MigrationLockV2['head'] {
273
280
  };
274
281
  }
275
282
 
276
- function assertUniqueMigrationNames(
277
- migrations: readonly MigrationLockEntry[],
278
- ): void {
279
- const names = new Set<string>();
280
- for (const migration of migrations) {
281
- if (names.has(migration.name)) {
282
- failLock(`migration ${JSON.stringify(migration.name)} appears twice`);
283
- }
284
- names.add(migration.name);
285
- }
286
- }
287
-
288
283
  /** Parse and structurally validate a committed lock document. */
289
- export function parseMigrationLock(source: string): MigrationLock {
284
+ export function parseMigrationLock(
285
+ source: string,
286
+ ): MigrationLock | LegacyMigrationLock {
290
287
  let raw: unknown;
291
288
  try {
292
289
  raw = JSON.parse(source);
@@ -294,27 +291,47 @@ export function parseMigrationLock(source: string): MigrationLock {
294
291
  failLock('invalid JSON');
295
292
  }
296
293
  if (!isRecord(raw)) failLock('root must be an object');
294
+ const { formatVersion } = raw;
297
295
  if (
298
- raw.formatVersion !== LEGACY_MIGRATION_LOCK_FORMAT_VERSION &&
299
- raw.formatVersion !== MIGRATION_LOCK_FORMAT_VERSION
296
+ formatVersion !== 1 &&
297
+ formatVersion !== 2 &&
298
+ formatVersion !== MIGRATION_LOCK_FORMAT_VERSION
300
299
  ) {
301
300
  failLock(
302
- `formatVersion must be ${LEGACY_MIGRATION_LOCK_FORMAT_VERSION} or ${MIGRATION_LOCK_FORMAT_VERSION}, got ${JSON.stringify(raw.formatVersion)}`,
301
+ `formatVersion must be 1, 2, or ${MIGRATION_LOCK_FORMAT_VERSION}, got ${JSON.stringify(formatVersion)}`,
303
302
  );
304
303
  }
305
304
  if (!Array.isArray(raw.migrations) || raw.migrations.length === 0) {
306
305
  failLock('migrations must be a non-empty array');
307
306
  }
308
- if (raw.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION) {
309
- const migrations = raw.migrations.map(parseLegacyEntry);
310
- assertUniqueMigrationNames(migrations);
307
+ const entries = raw.migrations.map(parseEntry);
308
+ const names = new Set<string>();
309
+ for (const { name } of entries) {
310
+ if (names.has(name)) {
311
+ failLock(`migration ${JSON.stringify(name)} appears twice`);
312
+ }
313
+ names.add(name);
314
+ }
315
+ if (formatVersion !== MIGRATION_LOCK_FORMAT_VERSION) {
311
316
  return {
312
- formatVersion: LEGACY_MIGRATION_LOCK_FORMAT_VERSION,
313
- migrations,
317
+ formatVersion,
318
+ migrations: entries.map(({ name, sha256 }) => ({ name, sha256 })),
314
319
  };
315
320
  }
316
- const migrations = raw.migrations.map(parseEntry);
317
- assertUniqueMigrationNames(migrations);
321
+ let previous = 1;
322
+ const migrations = entries.map(({ name, sha256, schemaVersion }, index) => {
323
+ if (
324
+ typeof schemaVersion !== 'number' ||
325
+ !Number.isInteger(schemaVersion) ||
326
+ schemaVersion < previous
327
+ ) {
328
+ failLock(
329
+ `migrations[${index}].schemaVersion must be an integer, at least 1 and at least the previous entry's`,
330
+ );
331
+ }
332
+ previous = schemaVersion;
333
+ return { name, sha256, schemaVersion };
334
+ });
318
335
  return {
319
336
  formatVersion: MIGRATION_LOCK_FORMAT_VERSION,
320
337
  migrations,
@@ -323,7 +340,9 @@ export function parseMigrationLock(source: string): MigrationLock {
323
340
  }
324
341
 
325
342
  /** Read the version-controlled baseline without exposing its absolute path. */
326
- export function readMigrationLock(manifestDir: string): MigrationLock {
343
+ export function readMigrationLock(
344
+ manifestDir: string,
345
+ ): MigrationLock | LegacyMigrationLock {
327
346
  const path = resolve(manifestDir, MIGRATION_LOCK_FILENAME);
328
347
  if (!existsSync(path)) {
329
348
  failLock(
@@ -378,13 +397,13 @@ function describeColumnDifference(
378
397
  }
379
398
 
380
399
  function firstSchemaDifference(
381
- locked: LegacyMigrationLockEntry,
382
- current: LegacyMigrationLockEntry,
400
+ locked: readonly MigrationLockTable[],
401
+ current: readonly MigrationLockTable[],
383
402
  ): string {
384
- const length = Math.max(locked.tables.length, current.tables.length);
403
+ const length = Math.max(locked.length, current.length);
385
404
  for (let index = 0; index < length; index++) {
386
- const before = locked.tables[index];
387
- const after = current.tables[index];
405
+ const before = locked[index];
406
+ const after = current[index];
388
407
  if (before === undefined && after !== undefined) {
389
408
  return `table ${JSON.stringify(after.name)} was added`;
390
409
  }
@@ -416,12 +435,11 @@ const REPAIR_HINT =
416
435
  * New migrations may be appended; existing names and bytes may never change.
417
436
  */
418
437
  function validateMigrationHistory(
419
- locked: MigrationLock,
420
- current: CurrentMigrationHistory,
438
+ locked: MigrationLock | LegacyMigrationLock,
439
+ current: readonly HistoryEntry[],
421
440
  ): void {
422
- for (let index = 0; index < locked.migrations.length; index++) {
423
- const before = locked.migrations[index] as MigrationLockEntry;
424
- const after = current.migrations[index];
441
+ locked.migrations.forEach((before, index) => {
442
+ const after = current[index];
425
443
  if (after === undefined) {
426
444
  failLock(
427
445
  `history drift at migration ${JSON.stringify(before.name)}: the locked migration is missing; ${REPAIR_HINT}`,
@@ -433,51 +451,88 @@ function validateMigrationHistory(
433
451
  );
434
452
  }
435
453
  if (before.sha256 !== after.sha256) {
436
- const diagnosticBefore: LegacyMigrationLockEntry =
437
- locked.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION
438
- ? (locked.migrations[index] as LegacyMigrationLockEntry)
439
- : {
440
- ...before,
441
- tables: locked.head.tables,
442
- };
443
- // Format 2 keeps one schema snapshot after the complete locked prefix.
444
- // Compare it with the current schema at that same boundary, excluding
445
- // valid newly appended migrations from the diagnostic.
446
- const diagnosticAfter =
447
- locked.formatVersion === LEGACY_MIGRATION_LOCK_FORMAT_VERSION
448
- ? after
449
- : (current.migrations[locked.migrations.length - 1] ?? after);
454
+ // The head snapshot is the schema after the complete locked prefix:
455
+ // compare it with the current schema at that same boundary, excluding
456
+ // valid newly appended migrations. A legacy lock is read without one.
457
+ const difference =
458
+ locked.formatVersion === MIGRATION_LOCK_FORMAT_VERSION
459
+ ? `; first schema difference: ${firstSchemaDifference(locked.head.tables, (current[locked.migrations.length - 1] ?? after).tables)}`
460
+ : '';
450
461
  failLock(
451
- `history drift in migration ${JSON.stringify(before.name)}: checksum changed; first schema difference: ${firstSchemaDifference(diagnosticBefore, diagnosticAfter)}; ${REPAIR_HINT}`,
462
+ `history drift in migration ${JSON.stringify(before.name)}: checksum changed${difference}; ${REPAIR_HINT}`,
452
463
  );
453
464
  }
454
- }
465
+ });
455
466
  }
456
467
 
457
468
  /**
458
- * Validate a committed lock against migration inputs and build its exact next
459
- * document. Ordinary generation preserves the committed format; upgrading a
460
- * version-1 lock is always an explicit command.
469
+ * Validate a committed lock against the migration inputs and their schema
470
+ * versions, and build its exact next document. A locked migration keeps its
471
+ * schema version; an appended migration belongs to a version above the
472
+ * highest locked one, because a deployed version never changes (§7.4).
461
473
  */
462
474
  export function updateMigrationLock(
463
- locked: MigrationLock,
475
+ locked: MigrationLock | LegacyMigrationLock,
464
476
  migrations: readonly MigrationInput[],
477
+ declared: readonly ManifestSchemaVersion[],
465
478
  ): MigrationLock {
479
+ if (locked.formatVersion !== MIGRATION_LOCK_FORMAT_VERSION) {
480
+ throw new TypegenError(
481
+ MIGRATION_LOCK_FILENAME,
482
+ 'the lock predates per-migration schema versions; run `syncular migrations upgrade-lock` once and commit the lock',
483
+ 'typegen.migration_lock_outdated',
484
+ { formatVersion: locked.formatVersion },
485
+ );
486
+ }
466
487
  const current = buildMigrationHistory(
467
488
  migrations,
468
489
  lockedMigrationNames(locked),
469
490
  );
470
491
  validateMigrationHistory(locked, current);
471
- return lockFromHistory(current, locked.formatVersion);
492
+ const next = lockFromHistory(
493
+ current,
494
+ buildSchemaVersions(declared, migrations),
495
+ );
496
+ const highestLockedVersion = locked.migrations.at(-1)?.schemaVersion ?? 0;
497
+ next.migrations.forEach(({ name, schemaVersion }, index) => {
498
+ const lockedVersion = locked.migrations[index]?.schemaVersion;
499
+ if (lockedVersion !== undefined && lockedVersion !== schemaVersion) {
500
+ throw new TypegenError(
501
+ MIGRATION_LOCK_FILENAME,
502
+ 'a locked migration moved to another schema version; a locked version keeps its migration set (§7.4)',
503
+ 'typegen.migration_version_changed',
504
+ { migration: name, lockedVersion, schemaVersion },
505
+ );
506
+ }
507
+ if (lockedVersion === undefined && schemaVersion <= highestLockedVersion) {
508
+ throw new TypegenError(
509
+ MIGRATION_LOCK_FILENAME,
510
+ 'an appended migration joins a locked schema version; declare a schema version above the highest locked one (§7.4)',
511
+ 'typegen.schema_version_locked',
512
+ { migration: name, schemaVersion, highestLockedVersion },
513
+ );
514
+ }
515
+ });
516
+ return next;
472
517
  }
473
518
 
474
- /** Validate without changing the committed lock format. */
475
- export function validateMigrationLock(
476
- locked: MigrationLock,
519
+ /**
520
+ * Convert a format-1 or format-2 lock to the current format: validate its
521
+ * locked prefix and record the schema version the manifest's `declared`
522
+ * versions assign each locked migration. Appended migrations stay unlocked for generation.
523
+ */
524
+ export function upgradeMigrationLock(
525
+ locked: LegacyMigrationLock,
477
526
  migrations: readonly MigrationInput[],
478
- ): void {
479
- validateMigrationHistory(
480
- locked,
481
- buildMigrationHistory(migrations, lockedMigrationNames(locked)),
527
+ declared: readonly ManifestSchemaVersion[],
528
+ ): MigrationLock {
529
+ const current = buildMigrationHistory(
530
+ migrations,
531
+ lockedMigrationNames(locked),
532
+ );
533
+ validateMigrationHistory(locked, current);
534
+ return lockFromHistory(
535
+ current.slice(0, locked.migrations.length),
536
+ buildSchemaVersions(declared, migrations),
482
537
  );
483
538
  }