@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/dist/query.js CHANGED
@@ -63,8 +63,8 @@
63
63
  */
64
64
  import { TypegenError } from './errors.js';
65
65
  import { isSyqlTrivia, lexSyqlSqlSource } from './syql-lexer.js';
66
- import { findProjection, lowerProjection, mainVerbAfterWith } from './lower.js';
67
- import { buildNamingMap } from './naming.js';
66
+ import { findProjection, lowerProjection } from './lower.js';
67
+ import { buildNamingMap, validateQueryIdentifier, } from './naming.js';
68
68
  /** The SQL decltype keyword → §2.4 type map (mirrors sql.ts TYPE_MAP so a
69
69
  * plain column ref's decltype resolves to the exact IR type). */
70
70
  const DECLTYPE_MAP = {
@@ -90,7 +90,46 @@ const DECLTYPE_MAP = {
90
90
  const SYNC_VERSION_COLUMN = '_sync_version';
91
91
  /** Stable private identity shared by every declared local FTS5 projection. */
92
92
  const FTS_SOURCE_ID_COLUMN = '_syncular_source_id';
93
+ /** The window bases (SPEC §4.8) a query's coverage needs, for generated
94
+ * descriptors. A base names no table, so tables proven by the same base share
95
+ * one entry; a fixed scope bound to several params yields one base per value
96
+ * combination, since a base holds one value per fixed variable. Ordered by
97
+ * code point of the JSON so emitted metadata is byte-identical across
98
+ * locales. */
99
+ export function windowBases(coverage) {
100
+ const bases = coverage.flatMap((entry) => {
101
+ let combinations = [[]];
102
+ for (const scope of entry.fixedScopes) {
103
+ combinations = combinations.flatMap((combination) => scope.params.map((param) => [
104
+ ...combination,
105
+ { variable: scope.variable, param },
106
+ ]));
107
+ }
108
+ return combinations.map((fixedScopes) => ({
109
+ variable: entry.variable,
110
+ units: entry.units,
111
+ fixedScopes,
112
+ }));
113
+ });
114
+ return [...new Map(bases.map((base) => [JSON.stringify(base), base]))]
115
+ .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
116
+ .map(([, base]) => base);
117
+ }
93
118
  const DEFAULT_NAMING = { naming: 'camel', targets: ['ts'] };
119
+ /** The findings of the query plan check (`docs/SYQL.md` §14.5). */
120
+ export const QUERY_PLAN_FINDINGS = [
121
+ 'scan',
122
+ 'automatic_index',
123
+ 'unbounded',
124
+ 'many_tables',
125
+ ];
126
+ /** The public SYQL input an emitter binds by name. */
127
+ export function syqlInput(query, name) {
128
+ const input = query.syql?.inputs.find((candidate) => candidate.name === name);
129
+ if (input === undefined)
130
+ throw new Error(`unknown SYQL input ${name}`);
131
+ return input;
132
+ }
94
133
  // -- path → name --------------------------------------------------------------
95
134
  /** A single kebab-case path segment (folder) or filename stem. */
96
135
  const KEBAB_SEGMENT_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -145,114 +184,80 @@ export function validateOverrideName(name, location) {
145
184
  }
146
185
  return name;
147
186
  }
148
- /** Split file content into statements on top-level `;` (string/comment-aware).
149
- * Blank/comment-only tails are dropped; each statement keeps its own leading
150
- * comment block (everything between the previous `;` and this SQL). */
151
- export function splitStatements(content) {
152
- const parts = [];
153
- let i = 0;
154
- let start = 0;
155
- while (i < content.length) {
156
- const ch = content[i];
157
- const next = content[i + 1];
158
- if (ch === '-' && next === '-') {
159
- const end = content.indexOf('\n', i);
160
- i = end === -1 ? content.length : end;
161
- }
162
- else if (ch === '/' && next === '*') {
163
- const end = content.indexOf('*/', i + 2);
164
- i = end === -1 ? content.length : end + 2;
187
+ // -- SQL tokens -----------------------------------------------------------------
188
+ //
189
+ // Every scan below reads the lossless SYQL lexer (`syql-lexer.ts`), so string
190
+ // literals, quoted identifiers, and comments are atomic tokens: their text is
191
+ // never split, rescanned, or rewritten. SQLite remains the authority on
192
+ // correctness.
193
+ /** Significant SQL tokens (no trivia) with each token's parenthesis depth,
194
+ * its innermost enclosing `(` (or -1), and every `(` index's matching `)`. */
195
+ function sqlStructure(sql, file = 'query SQL') {
196
+ const tokens = lexSyqlSqlSource(file, sql).filter((token) => !isSyqlTrivia(token) && token.kind !== 'eof');
197
+ const depths = [];
198
+ const parents = [];
199
+ const closes = new Map();
200
+ const stack = [];
201
+ tokens.forEach((token, index) => {
202
+ if (token.text === ')') {
203
+ const open = stack.pop();
204
+ if (open !== undefined)
205
+ closes.set(open, index);
165
206
  }
166
- else if (ch === "'") {
167
- let j = i + 1;
168
- for (;;) {
169
- if (j >= content.length)
170
- break;
171
- if (content[j] === "'") {
172
- if (content[j + 1] === "'")
173
- j += 2;
174
- else {
175
- j += 1;
176
- break;
177
- }
178
- }
179
- else
180
- j += 1;
207
+ parents[index] = stack.at(-1) ?? -1;
208
+ depths[index] = stack.length;
209
+ if (token.text === '(')
210
+ stack.push(index);
211
+ });
212
+ return { tokens, depths, parents, closes };
213
+ }
214
+ function lowerWord(token) {
215
+ return token?.kind === 'identifier' ? token.text.toLowerCase() : undefined;
216
+ }
217
+ /** Split file content into statements on top-level `;` tokens. A statement
218
+ * keeps its leading comment block; comment-only parts are dropped. The
219
+ * SELECT-only subset has no BEGIN/END blocks, so every `;` token ends one
220
+ * statement and a trailing `;` is optional. */
221
+ export function splitStatements(content, file = 'query SQL') {
222
+ const out = [];
223
+ let lead;
224
+ let hasSql = false;
225
+ for (const token of lexSyqlSqlSource(file, content)) {
226
+ if (token.kind === 'eof' || token.text === ';') {
227
+ if (lead !== undefined && hasSql) {
228
+ out.push({
229
+ text: content.slice(lead.span.start.offset, token.span.start.offset),
230
+ startLine: lead.span.start.line,
231
+ });
181
232
  }
182
- i = j;
183
- }
184
- else if (ch === ';') {
185
- parts.push({ text: content.slice(start, i), startOffset: start });
186
- i += 1;
187
- start = i;
233
+ lead = undefined;
234
+ hasSql = false;
188
235
  }
189
- else {
190
- i += 1;
236
+ else if (token.kind !== 'whitespace') {
237
+ lead ??= token;
238
+ hasSql ||= !isSyqlTrivia(token);
191
239
  }
192
240
  }
193
- if (start < content.length) {
194
- parts.push({ text: content.slice(start), startOffset: start });
195
- }
196
- const out = [];
197
- for (const part of parts) {
198
- // Drop parts whose SQL body (comments/whitespace stripped) is empty — a
199
- // trailing `;` or a comment-only tail is not a statement.
200
- if (stripCommentsAndStrings(part.text).trim().length === 0)
201
- continue;
202
- // Report the line of the statement's first NON-blank character (skip the
203
- // blank/whitespace run after the previous `;`), so the location points at
204
- // real content, not the terminator's trailing newline.
205
- const lead = part.text.length - part.text.replace(/^\s+/, '').length;
206
- const before = content.slice(0, part.startOffset + lead);
207
- const startLine = before.split('\n').length;
208
- out.push({ text: part.text.replace(/^\s+/, ''), startLine });
209
- }
210
241
  return out;
211
242
  }
212
- /** The leading comment block of a statement: the run of blank + line/block
213
- * comment lines before the first SQL token. `-- name:` / `-- param` markers are
214
- * scoped HERE (to the statement they directly precede), not file-wide. Returns
215
- * the `--` comment lines (block comments carry no markers we parse). */
216
- function leadingCommentBlock(statementText) {
217
- const lines = [];
218
- let i = 0;
219
- while (i < statementText.length) {
220
- // Skip leading whitespace on the line.
221
- while (i < statementText.length &&
222
- /[ \t\r]/.test(statementText[i])) {
223
- i += 1;
224
- }
225
- const ch = statementText[i];
226
- const next = statementText[i + 1];
227
- if (ch === '\n') {
228
- i += 1;
229
- continue;
230
- }
231
- if (ch === '-' && next === '-') {
232
- const end = statementText.indexOf('\n', i);
233
- const line = statementText.slice(i, end === -1 ? undefined : end);
234
- lines.push(line);
235
- i = end === -1 ? statementText.length : end + 1;
236
- continue;
237
- }
238
- if (ch === '/' && next === '*') {
239
- const end = statementText.indexOf('*/', i + 2);
240
- // Block comments carry no markers we parse; skip and keep scanning for
241
- // more leading comments (but they don't contribute -- name:/-- param).
242
- i = end === -1 ? statementText.length : end + 2;
243
- continue;
244
- }
245
- break; // first SQL token — the comment block ends here
243
+ /** The `--` comments before a statement's first SQL token. `-- name:` and
244
+ * `-- param` markers are scoped to the statement they precede. */
245
+ function leadingComments(statementText) {
246
+ const comments = [];
247
+ for (const token of lexSyqlSqlSource('query SQL', statementText)) {
248
+ if (!isSyqlTrivia(token))
249
+ break;
250
+ if (token.kind === 'line-comment')
251
+ comments.push(token.text);
246
252
  }
247
- return lines;
253
+ return comments;
248
254
  }
249
- const NAME_MARKER_RE = /^\s*--\s*name:\s*(\S+)\s*$/;
255
+ const NAME_MARKER_RE = /^--\s*name:\s*(\S+)\s*$/;
250
256
  /** The `-- name:` override in a statement's leading comment block, or null. */
251
257
  export function parseStatementName(statementText, location) {
252
- const lines = leadingCommentBlock(statementText);
253
258
  let found = null;
254
- for (const line of lines) {
255
- const m = NAME_MARKER_RE.exec(line);
259
+ for (const comment of leadingComments(statementText)) {
260
+ const m = NAME_MARKER_RE.exec(comment);
256
261
  if (m === null)
257
262
  continue;
258
263
  if (found !== null) {
@@ -262,7 +267,7 @@ export function parseStatementName(statementText, location) {
262
267
  }
263
268
  return found;
264
269
  }
265
- const PARAM_COMMENT_RE = /^\s*--\s*param\s+:([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z_]+)\s*$/;
270
+ const PARAM_COMMENT_RE = /^--\s*param\s+:([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z_]+)\s*$/;
266
271
  const PARAM_TYPES = new Set([
267
272
  'string',
268
273
  'integer',
@@ -273,16 +278,11 @@ const PARAM_TYPES = new Set([
273
278
  'blob_ref',
274
279
  'crdt',
275
280
  ]);
276
- /** Parse `-- param :name <type>` header lines. They must precede the SQL. */
281
+ /** Parse the `-- param :name <type>` markers of the leading comment block. */
277
282
  function parseCommentParams(file, raw) {
278
283
  const out = [];
279
- for (const line of raw.split('\n')) {
280
- const trimmed = line.trim();
281
- if (trimmed.length === 0)
282
- continue;
283
- if (!trimmed.startsWith('--'))
284
- break; // first non-comment line ends the header
285
- const match = PARAM_COMMENT_RE.exec(line);
284
+ for (const comment of leadingComments(raw)) {
285
+ const match = PARAM_COMMENT_RE.exec(comment);
286
286
  if (match === null)
287
287
  continue; // an ordinary comment, ignore
288
288
  const name = match[1];
@@ -294,67 +294,57 @@ function parseCommentParams(file, raw) {
294
294
  }
295
295
  return out;
296
296
  }
297
- /** Strip `--` and block comments so identifier scans don't hit commented SQL,
298
- * and string literals so `':x'` inside a string isn't read as a param. */
299
- export function stripCommentsAndStrings(sql) {
300
- let out = '';
301
- let i = 0;
302
- while (i < sql.length) {
303
- const ch = sql[i];
304
- const next = sql[i + 1];
305
- if (ch === '-' && next === '-') {
306
- const end = sql.indexOf('\n', i);
307
- const stop = end === -1 ? sql.length : end;
308
- out += ' '.repeat(stop - i);
309
- i = stop;
310
- }
311
- else if (ch === '/' && next === '*') {
312
- const end = sql.indexOf('*/', i + 2);
313
- const stop = end === -1 ? sql.length : end + 2;
314
- out += sql.slice(i, stop).replace(/[^\n]/g, ' ');
315
- i = stop;
316
- }
317
- else if (ch === "'") {
318
- let stop = i + 1;
319
- while (stop < sql.length) {
320
- if (sql[stop] === "'" && sql[stop + 1] === "'") {
321
- stop += 2;
322
- continue;
323
- }
324
- if (sql[stop] === "'") {
325
- stop += 1;
326
- break;
327
- }
328
- stop += 1;
329
- }
330
- out += sql.slice(i, stop).replace(/[^\n]/g, ' ');
331
- i = stop;
332
- }
333
- else {
334
- out += ch;
335
- i += 1;
336
- }
297
+ const ACKNOWLEDGEMENT_RE = new RegExp(`^--\\s*allow\\s+(${QUERY_PLAN_FINDINGS.join('|')})\\b`);
298
+ /** Parse the `-- allow <finding> [table]: <reason>` acknowledgements of the
299
+ * leading comment block (`docs/SYQL.md` §14.5). */
300
+ function parseCommentAcknowledgements(file, raw) {
301
+ const out = [];
302
+ for (const comment of leadingComments(raw)) {
303
+ const kind = ACKNOWLEDGEMENT_RE.exec(comment)?.[1];
304
+ const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind);
305
+ if (finding === undefined)
306
+ continue;
307
+ const match = /^--\s*allow\s+\w+(?:\s+([A-Za-z_][A-Za-z0-9_]*))?\s*:\s*(\S.*?)\s*$/.exec(comment);
308
+ const table = match?.[1];
309
+ if (match === null ||
310
+ (finding === 'many_tables') !== (table === undefined) ||
311
+ out.some((other) => other.finding === finding && other.table === table)) {
312
+ throw new TypegenError(file, 'invalid query plan acknowledgement; write `-- allow <finding> <table>: <reason>` once per finding', 'typegen.query_acknowledgement_invalid', { file, comment });
313
+ }
314
+ out.push({
315
+ finding,
316
+ ...(table === undefined ? {} : { table }),
317
+ reason: match[2],
318
+ });
337
319
  }
338
320
  return out;
339
321
  }
340
- /** Distinct `:name` placeholders in first-occurrence order (dedup by name,
341
- * matching SQLite's paramsCount which counts distinct names). */
322
+ /** Blank comments and string/blob literals with spaces (newlines kept), so
323
+ * offset-preserving text scans never read inside them. */
324
+ export function stripCommentsAndStrings(sql) {
325
+ return lexSyqlSqlSource('query SQL', sql)
326
+ .map((token) => token.kind === 'line-comment' ||
327
+ token.kind === 'block-comment' ||
328
+ token.kind === 'string' ||
329
+ token.kind === 'blob'
330
+ ? token.text.replace(/[^\n]/g, ' ')
331
+ : token.text)
332
+ .join('');
333
+ }
334
+ /** Distinct `:name` binds in first-occurrence order (SQLite's paramsCount
335
+ * counts distinct names). */
342
336
  function scanParamNames(sql) {
343
- const cleaned = stripCommentsAndStrings(sql);
344
- // `:name` but not `::` (Postgres cast) — our subset never has `::`.
345
- const re = /:([A-Za-z_][A-Za-z0-9_]*)/g;
346
- const seen = [];
347
- for (const m of cleaned.matchAll(re)) {
348
- const name = m[1];
349
- if (!seen.includes(name))
350
- seen.push(name);
337
+ const names = [];
338
+ for (const token of lexSyqlSqlSource('query SQL', sql)) {
339
+ const name = token.text.slice(1);
340
+ if (token.kind === 'bind' && !names.includes(name))
341
+ names.push(name);
351
342
  }
352
- return seen;
343
+ return names;
353
344
  }
354
- /** Rewrite `:name` → positional placeholders AND strip comments + collapse
355
- * whitespace, producing a clean single-line SQL string suitable for
356
- * embedding in a generated string literal. String literals are preserved
357
- * verbatim (their inner whitespace is not collapsed).
345
+ /** The emitted single-line statement: `:name` binds become positional, every
346
+ * whitespace/comment run between tokens becomes one space, and every other
347
+ * token (string literals, quoted identifiers) keeps its exact text.
358
348
  *
359
349
  * When every param occurs exactly once, plain `?` is emitted. When ANY
360
350
  * param repeats (the §7 neutralization guards mention a param in the guard
@@ -362,83 +352,27 @@ function scanParamNames(sql) {
362
352
  * form — one bound value per DISTINCT param, reuse resolved by SQLite —
363
353
  * so the generated bind array stays one-entry-per-param. */
364
354
  export function toPositionalSql(sql) {
365
- const tokens = [];
366
- let i = 0;
367
- while (i < sql.length) {
368
- const ch = sql[i];
369
- const next = sql[i + 1];
370
- if (ch === '-' && next === '-') {
371
- const end = sql.indexOf('\n', i);
372
- i = end === -1 ? sql.length : end + 1;
373
- tokens.push(' ');
374
- }
375
- else if (ch === '/' && next === '*') {
376
- const end = sql.indexOf('*/', i + 2);
377
- i = end === -1 ? sql.length : end + 2;
378
- tokens.push(' ');
379
- }
380
- else if (ch === "'") {
381
- // Preserve string literals verbatim (including any '' escapes).
382
- let j = i + 1;
383
- let lit = "'";
384
- for (;;) {
385
- if (j >= sql.length)
386
- break;
387
- if (sql[j] === "'") {
388
- if (sql[j + 1] === "'") {
389
- lit += "''";
390
- j += 2;
391
- }
392
- else {
393
- lit += "'";
394
- j += 1;
395
- break;
396
- }
397
- }
398
- else {
399
- lit += sql[j];
400
- j += 1;
401
- }
402
- }
403
- tokens.push(lit);
404
- i = j;
405
- }
406
- else if (ch === ':' && next !== undefined && /[A-Za-z_]/.test(next)) {
407
- let end = i + 1;
408
- while (end < sql.length && /[A-Za-z0-9_]/.test(sql[end])) {
409
- end += 1;
410
- }
411
- tokens.push({ param: sql.slice(i + 1, end) });
412
- i = end;
413
- }
414
- else if (/\s/.test(ch)) {
415
- tokens.push(' ');
416
- i += 1;
417
- }
418
- else {
419
- tokens.push(ch);
420
- i += 1;
421
- }
422
- }
423
- const order = [];
424
- let repeats = false;
355
+ const tokens = lexSyqlSqlSource('query SQL', sql);
356
+ const order = scanParamNames(sql);
357
+ const repeats = tokens.filter((token) => token.kind === 'bind').length > order.length;
358
+ let out = '';
359
+ let space = false;
425
360
  for (const token of tokens) {
426
- if (typeof token === 'string')
361
+ if (isSyqlTrivia(token) || token.kind === 'eof') {
362
+ space = out.length > 0;
427
363
  continue;
428
- if (order.includes(token.param))
429
- repeats = true;
430
- else
431
- order.push(token.param);
364
+ }
365
+ if (space)
366
+ out += ' ';
367
+ space = false;
368
+ out +=
369
+ token.kind !== 'bind'
370
+ ? token.text
371
+ : repeats
372
+ ? `?${order.indexOf(token.text.slice(1)) + 1}`
373
+ : '?';
432
374
  }
433
- const rendered = tokens
434
- .map((token) => {
435
- if (typeof token === 'string')
436
- return token;
437
- return repeats ? `?${order.indexOf(token.param) + 1}` : '?';
438
- })
439
- .join('');
440
- // Collapse runs of the whitespace placeholders; trim.
441
- return rendered.replace(/\s+/g, ' ').trim();
375
+ return out;
442
376
  }
443
377
  const IDENT = '[A-Za-z_][A-Za-z0-9_]*';
444
378
  // `FROM tbl [AS] a`, `JOIN tbl [AS] a`. We only need the referenced base
@@ -467,7 +401,8 @@ const RESERVED_ALIAS = new Set([
467
401
  'indexed',
468
402
  'not',
469
403
  ]);
470
- function sqlIdentifier(token) {
404
+ /** The name a plain or quoted identifier token spells. */
405
+ export function sqlIdentifier(token) {
471
406
  if (token?.kind === 'identifier')
472
407
  return token.text;
473
408
  if (token?.kind !== 'quoted-identifier')
@@ -482,7 +417,7 @@ export function scanTableRefs(sql, ir, lowered = false) {
482
417
  /** `lowered` scans emitted SQL, whose FTS mapping reads
483
418
  * ({@link lowerFtsSourceIds}) are internal and not relations of the query. */
484
419
  export function scanRelations(sql, ir, lowered = false) {
485
- const tokens = lexSyqlSqlSource('query SQL', sql).filter((token) => !isSyqlTrivia(token) && token.kind !== 'eof');
420
+ const { tokens, depths, parents, closes } = sqlStructure(sql);
486
421
  const known = new Map(ir.tables.flatMap((table) => [
487
422
  [table.name.toLowerCase(), table.name],
488
423
  ...table.ftsIndexes.map((index) => [index.name.toLowerCase(), index.name]),
@@ -490,21 +425,6 @@ export function scanRelations(sql, ir, lowered = false) {
490
425
  const mappings = new Set(lowered
491
426
  ? ir.tables.flatMap((table) => table.ftsIndexes.map((index) => ftsMappingTable(index.name).toLowerCase()))
492
427
  : []);
493
- const closes = new Map();
494
- const parents = [];
495
- const depths = [];
496
- const stack = [];
497
- tokens.forEach((token, index) => {
498
- if (token.text === ')') {
499
- const open = stack.pop();
500
- if (open !== undefined)
501
- closes.set(open, index);
502
- }
503
- parents[index] = stack.at(-1) ?? -1;
504
- depths[index] = stack.length;
505
- if (token.text === '(')
506
- stack.push(index);
507
- });
508
428
  const activeFromDepths = new Set();
509
429
  const clauseEnders = new Set([
510
430
  'where',
@@ -719,6 +639,212 @@ export function scanRelations(sql, ir, lowered = false) {
719
639
  },
720
640
  };
721
641
  }
642
+ const CLAUSE_WORDS = new Set([
643
+ 'where',
644
+ 'group',
645
+ 'having',
646
+ 'order',
647
+ 'limit',
648
+ 'window',
649
+ 'join',
650
+ 'inner',
651
+ 'left',
652
+ 'right',
653
+ 'full',
654
+ 'cross',
655
+ 'natural',
656
+ ]);
657
+ /**
658
+ * The scope-proof rule shared by `.sql` and `.syql` queries (SYQL §13). A
659
+ * comparison proves a scope only when it is a whole top-level conjunct of
660
+ * the WHERE clause of the SELECT scope that reads the instance: the outer
661
+ * statement or a top-level CTE body. Parentheses around a whole conjunct are
662
+ * transparent. Nothing else is a proof: a WHERE clause with a top-level OR, a
663
+ * compound SELECT scope, a nested subquery, and any other conjunct shape (NOT,
664
+ * a comparison of the comparison, a function, CASE, COLLATE, IS after the
665
+ * bind, a literal in an IN list). Column equalities also come from the
666
+ * conjuncts of an ON clause without OR, NOT, or a subquery.
667
+ */
668
+ export function scopeProofs(sql, ir) {
669
+ const { tokens, depths, closes } = sqlStructure(sql);
670
+ const relations = scanRelations(sql, ir);
671
+ const binds = [];
672
+ const equalities = [];
673
+ const tableOf = (ref) => ir.tables.find((table) => table.name === ref.table);
674
+ const scopeColumn = (scope, qualifier, column) => {
675
+ const name = column.toLowerCase();
676
+ const candidates = relations.tables.filter((ref) => relations.scopeAt(ref.start) === scope &&
677
+ (qualifier === undefined
678
+ ? tableOf(ref)?.columns.some((c) => c.name.toLowerCase() === name)
679
+ : ref.alias.toLowerCase() === qualifier.toLowerCase()));
680
+ const ref = candidates.length === 1 ? candidates[0] : undefined;
681
+ const declared = ref === undefined
682
+ ? undefined
683
+ : tableOf(ref)?.scopes.find((s) => s.column.toLowerCase() === name);
684
+ return ref === undefined || declared === undefined
685
+ ? undefined
686
+ : { scope, alias: ref.alias.toLowerCase(), column: name };
687
+ };
688
+ const columnAt = (index) => {
689
+ const first = sqlIdentifier(tokens[index]);
690
+ if (first === undefined)
691
+ return undefined;
692
+ if (tokens[index + 1]?.text !== '.')
693
+ return { qualifier: undefined, column: first, next: index + 1 };
694
+ const column = sqlIdentifier(tokens[index + 2]);
695
+ return column === undefined
696
+ ? undefined
697
+ : { qualifier: first, column, next: index + 3 };
698
+ };
699
+ const equal = (index) => tokens[index]?.text === '=' || tokens[index]?.text === '==';
700
+ const bindAt = (index) => tokens[index]?.kind === 'bind'
701
+ ? tokens[index].text.slice(1)
702
+ : undefined;
703
+ const conjuncts = (from, to) => {
704
+ const parts = [];
705
+ let start = from;
706
+ let cases = 0;
707
+ let between = false;
708
+ for (let index = from; index < to; index += 1) {
709
+ if (depths[index] !== depths[from])
710
+ continue;
711
+ const word = lowerWord(tokens[index]);
712
+ if (word === 'case')
713
+ cases += 1;
714
+ else if (word === 'end')
715
+ cases -= 1;
716
+ else if (cases > 0)
717
+ continue;
718
+ else if (word === 'or')
719
+ return [];
720
+ else if (word === 'between')
721
+ between = true;
722
+ else if (word === 'and' && between)
723
+ between = false;
724
+ else if (word === 'and') {
725
+ parts.push([start, index]);
726
+ start = index + 1;
727
+ }
728
+ }
729
+ parts.push([start, to]);
730
+ return parts.flatMap(([start, end]) => tokens[start]?.text === '(' &&
731
+ closes.get(start) === end - 1 &&
732
+ !['select', 'with', 'values'].includes(lowerWord(tokens[start + 1]) ?? '')
733
+ ? conjuncts(start + 1, end - 1)
734
+ : [[start, end]]);
735
+ };
736
+ const classify = (scope, start, end, join) => {
737
+ const reversed = bindAt(start);
738
+ const left = columnAt(reversed === undefined ? start : start + 2);
739
+ if (left === undefined)
740
+ return;
741
+ if (reversed !== undefined) {
742
+ const subject = scopeColumn(scope, left.qualifier, left.column);
743
+ if (join === undefined &&
744
+ equal(start + 1) &&
745
+ left.next === end &&
746
+ subject)
747
+ binds.push({ ...subject, operator: 'equal', params: [reversed] });
748
+ return;
749
+ }
750
+ const operator = left.next;
751
+ const bind = bindAt(operator + 1);
752
+ const list = tokens.slice(operator + 2, end - 1);
753
+ const right = columnAt(operator + 1);
754
+ if (join === undefined &&
755
+ bind !== undefined &&
756
+ operator + 2 === end &&
757
+ (equal(operator) || lowerWord(tokens[operator]) === 'is')) {
758
+ const subject = scopeColumn(scope, left.qualifier, left.column);
759
+ if (subject)
760
+ binds.push({ ...subject, operator: 'equal', params: [bind] });
761
+ }
762
+ else if (join === undefined &&
763
+ lowerWord(tokens[operator]) === 'in' &&
764
+ closes.get(operator + 1) === end - 1 &&
765
+ list.length % 2 === 1 &&
766
+ list.every((token, index) => index % 2 === 0 ? token.kind === 'bind' : token.text === ',')) {
767
+ const subject = scopeColumn(scope, left.qualifier, left.column);
768
+ const params = list.flatMap((token) => token.kind === 'bind' ? [token.text.slice(1)] : []);
769
+ if (subject)
770
+ binds.push({ ...subject, operator: 'in', params });
771
+ }
772
+ else if (equal(operator) &&
773
+ right?.next === end &&
774
+ left.qualifier !== undefined &&
775
+ right.qualifier !== undefined) {
776
+ const l = scopeColumn(scope, left.qualifier, left.column);
777
+ const r = scopeColumn(scope, right.qualifier, right.column);
778
+ if (l === undefined || r === undefined)
779
+ return;
780
+ if (join?.kind !== 'left' && join?.kind !== 'right') {
781
+ equalities.push({ target: l, source: r, symmetric: true });
782
+ return;
783
+ }
784
+ // An outer join's ON constrains matched rows of its null-extended side
785
+ // only; an equality with both operands on one side proves nothing.
786
+ if (join.introduced.has(l.alias) === join.introduced.has(r.alias))
787
+ return;
788
+ const [introduced, prior] = join.introduced.has(l.alias)
789
+ ? [l, r]
790
+ : [r, l];
791
+ equalities.push(join.kind === 'left'
792
+ ? { target: introduced, source: prior, symmetric: false }
793
+ : { target: prior, source: introduced, symmetric: false });
794
+ }
795
+ };
796
+ const ranges = [
797
+ { scope: 'main', from: 0, to: tokens.length },
798
+ ...relations.cteScopes.map((cte) => ({
799
+ scope: `cte:${cte.name}`,
800
+ from: tokens.findIndex((token) => token.span.start.offset >= cte.start),
801
+ to: tokens.findIndex((token) => token.span.start.offset >= cte.end),
802
+ })),
803
+ ];
804
+ for (const range of ranges) {
805
+ const own = [];
806
+ for (let index = range.from; index < range.to; index += 1) {
807
+ if (depths[index] === depths[range.from])
808
+ own.push(index);
809
+ }
810
+ const words = own.map((index) => lowerWord(tokens[index]) ?? '');
811
+ if (words.some((w) => w === 'union' || w === 'intersect' || w === 'except'))
812
+ continue;
813
+ own.forEach((at, position) => {
814
+ const word = words[position];
815
+ if (word !== 'where' && word !== 'on')
816
+ return;
817
+ let next = position + 1;
818
+ while (next < words.length && !CLAUSE_WORDS.has(words[next]))
819
+ next += 1;
820
+ const to = own[next] ?? range.to;
821
+ if (word === 'where') {
822
+ for (const [start, end] of conjuncts(at + 1, to))
823
+ classify(range.scope, start, end);
824
+ return;
825
+ }
826
+ if (tokens
827
+ .slice(at + 1, to)
828
+ .some((token) => ['or', 'not', 'select', 'with'].includes(lowerWord(token) ?? '')))
829
+ return;
830
+ const join = words.lastIndexOf('join', position);
831
+ if (join < 0)
832
+ return;
833
+ const kind = words[join - 1] === 'outer' ? words[join - 2] : words[join - 1];
834
+ if (kind === 'full')
835
+ return;
836
+ // The relations between JOIN and ON, a parenthesized group included.
837
+ const introduced = new Set(relations.tables
838
+ .filter((ref) => ref.start >
839
+ tokens[own[join]].span.start.offset &&
840
+ ref.start < tokens[at].span.start.offset)
841
+ .map((ref) => ref.alias.toLowerCase()));
842
+ for (const [start, end] of conjuncts(at + 1, to))
843
+ classify(range.scope, start, end, { kind, introduced });
844
+ });
845
+ }
846
+ return { binds, equalities };
847
+ }
722
848
  /** Split the outermost SELECT list of `sql` into items. Returns null when the
723
849
  * statement has no outer `SELECT … FROM` or projects `*` / `t.*`. */
724
850
  export function splitSelectList(sql) {
@@ -835,79 +961,9 @@ function applicationColumnType(column) {
835
961
  ? column.declaredType
836
962
  : column.type;
837
963
  }
838
- function inferParamType(paramName, sql, refs, ir) {
839
- const cleaned = stripCommentsAndStrings(sql);
840
- const byName = new Map(ir.tables.map((t) => [t.name, t]));
841
- const lookup = (qualifier, column) => {
842
- if (qualifier !== undefined) {
843
- const ref = refs.find((r) => r.alias === qualifier);
844
- const table = ref && byName.get(ref.table);
845
- const resolved = table?.columns.find((c) => c.name === column);
846
- return resolved === undefined ? null : applicationColumnType(resolved);
847
- }
848
- for (const ref of refs) {
849
- const table = byName.get(ref.table);
850
- const col = table?.columns.find((c) => c.name === column);
851
- if (col !== undefined)
852
- return applicationColumnType(col);
853
- }
854
- return null;
855
- };
856
- // `col = :name`, `col >= :name`, `col <> :name`, `col LIKE :name`, etc.
857
- const cmp = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s*(?:=|==|!=|<>|<=|>=|<|>|\\bLIKE\\b|\\bIS\\b)\\s*:${paramName}\\b`, 'i');
858
- const cmpM = cmp.exec(cleaned);
859
- if (cmpM !== null) {
860
- const t = lookup(cmpM[1], cmpM[2]);
861
- if (t !== null)
862
- return t;
863
- }
864
- // reversed: `:name = col`
865
- const rev = new RegExp(`:${paramName}\\b\\s*(?:=|==|!=|<>|<=|>=|<|>)\\s*(?:(${IDENT})\\.)?(${IDENT})`, 'i');
866
- const revM = rev.exec(cleaned);
867
- if (revM !== null) {
868
- const t = lookup(revM[1], revM[2]);
869
- if (t !== null)
870
- return t;
871
- }
872
- // `col IN (…, :name, …)` — find the nearest `col IN (` before the param.
873
- const inRe = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+IN\\s*\\(([^)]*:${paramName}\\b[^)]*)\\)`, 'i');
874
- const inM = inRe.exec(cleaned);
875
- if (inM !== null) {
876
- const t = lookup(inM[1], inM[2]);
877
- if (t !== null)
878
- return t;
879
- }
880
- // `col BETWEEN :name AND …` / `col BETWEEN … AND :name` — both endpoints
881
- // take the column's type (the §4 from+to group shape).
882
- const btwLeft = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+:${paramName}\\b`, 'i');
883
- const btwLeftM = btwLeft.exec(cleaned);
884
- if (btwLeftM !== null) {
885
- const t = lookup(btwLeftM[1], btwLeftM[2]);
886
- if (t !== null)
887
- return t;
888
- }
889
- const btwRight = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+\\S+\\s+AND\\s+:${paramName}\\b`, 'i');
890
- const btwRightM = btwRight.exec(cleaned);
891
- if (btwRightM !== null) {
892
- const t = lookup(btwRightM[1], btwRightM[2]);
893
- if (t !== null)
894
- return t;
895
- }
896
- // `… LIKE <expr mentioning :name>` — a LIKE operand is TEXT, even inside
897
- // a concatenation (`title like '%' || :q || '%'`, the search-fragment
898
- // shape).
899
- const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'i');
900
- if (like.test(cleaned))
901
- return 'string';
902
- const match = new RegExp(`\\bMATCH\\b\\s*:${paramName}\\b`, 'i');
903
- if (match.test(cleaned))
904
- return 'string';
905
- return null;
906
- }
907
964
  /**
908
- * Return every revision-1 column/LIKE type constraint for one bind. Unlike
909
- * `inferParamType` (the legacy first-match helper), SYQL uses the complete set
910
- * so conflicting checked uses cannot be silently accepted.
965
+ * Every column/LIKE/MATCH type constraint on one bind, in pattern order. A
966
+ * `.sql` query takes the first; SYQL rejects conflicting evidence.
911
967
  */
912
968
  export function inferParamTypeEvidence(paramName, sql, refs, ir) {
913
969
  const cleaned = stripCommentsAndStrings(sql);
@@ -923,14 +979,16 @@ export function inferParamTypeEvidence(paramName, sql, refs, ir) {
923
979
  evidence.push(type);
924
980
  return;
925
981
  }
926
- const matches = refs.flatMap((ref) => {
927
- const table = byName.get(ref.table);
928
- const item = table?.columns.find((candidate) => candidate.name === column);
929
- const type = item === undefined ? undefined : applicationColumnType(item);
930
- return type === undefined ? [] : [type];
931
- });
932
- if (matches.length === 1)
933
- evidence.push(matches[0]);
982
+ // An unqualified name read by several relations is evidence only when
983
+ // every candidate column has the same type.
984
+ const matches = new Set(refs.flatMap((ref) => {
985
+ const item = byName
986
+ .get(ref.table)
987
+ ?.columns.find((candidate) => candidate.name === column);
988
+ return item === undefined ? [] : [applicationColumnType(item)];
989
+ }));
990
+ if (matches.size === 1)
991
+ evidence.push(...matches);
934
992
  };
935
993
  const comparison = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s*(?:=|==|!=|<>|<=|>=|<|>|\\bLIKE\\b|\\bIS\\b)\\s*:${paramName}\\b`, 'gi');
936
994
  for (const match of cleaned.matchAll(comparison)) {
@@ -961,51 +1019,41 @@ export function inferParamTypeEvidence(paramName, sql, refs, ir) {
961
1019
  return evidence;
962
1020
  }
963
1021
  // -- fallback column typing (computed expressions) ----------------------------
964
- const AGG_RE = /\b(count|sum|total|avg|min|max)\s*\(/i;
965
- /** decltype-null column: the documented honest fallback. Aggregates and
966
- * arithmetic → nullable number; everything else → nullable string. */
967
- function fallbackColumnType(expr) {
968
- if (AGG_RE.test(expr) || /[+\-*/]/.test(expr))
969
- return 'float';
970
- return 'string';
971
- }
972
- function inferReactiveMetadata(sql, refs, ir, params, columns) {
973
- const conservative = /\b(?:UNION|EXCEPT|INTERSECT)\b/i.test(stripCommentsAndStrings(sql));
974
- const requiredAt = (index) => {
975
- const cleaned = stripCommentsAndStrings(sql);
976
- const where = /\bWHERE\b/i.exec(cleaned);
977
- if (where === null || index < where.index + where[0].length)
1022
+ export const AGGREGATE_FUNCTIONS = new Set([
1023
+ 'avg',
1024
+ 'count',
1025
+ 'group_concat',
1026
+ 'max',
1027
+ 'min',
1028
+ 'sum',
1029
+ 'total',
1030
+ ]);
1031
+ /** True when `expr` calls an aggregate outside a subquery. `min`/`max` with
1032
+ * several arguments are scalar functions, and an OVER clause makes a window
1033
+ * function, which aggregates no rows. */
1034
+ function callsAggregate(expr) {
1035
+ const { tokens, depths, parents, closes } = sqlStructure(expr);
1036
+ return tokens.some((token, index) => {
1037
+ const name = lowerWord(token) ?? '';
1038
+ const close = closes.get(index + 1);
1039
+ if (!AGGREGATE_FUNCTIONS.has(name) || close === undefined)
978
1040
  return false;
979
- const matchStack = [];
980
- for (let cursor = where.index + where[0].length; cursor < index; cursor += 1) {
981
- if (cleaned[cursor] === '(')
982
- matchStack.push(cursor);
983
- else if (cleaned[cursor] === ')')
984
- matchStack.pop();
985
- }
986
- const stack = [];
987
- for (let cursor = where.index + where[0].length; cursor < cleaned.length; cursor += 1) {
988
- const char = cleaned[cursor];
989
- if (char === '(')
990
- stack.push(cursor);
991
- else if (char === ')')
992
- stack.pop();
993
- const atBoundary = cursor === 0 || !/[A-Za-z0-9_:]/.test(cleaned[cursor - 1] ?? '');
994
- if (cursor > index &&
995
- atBoundary &&
996
- /^(?:GROUP\s+BY|ORDER\s+BY|LIMIT|HAVING)\b/i.test(cleaned.slice(cursor))) {
997
- break;
998
- }
999
- if (atBoundary &&
1000
- /^OR\b/i.test(cleaned.slice(cursor)) &&
1001
- stack.length <= matchStack.length &&
1002
- stack.every((open, stackIndex) => matchStack[stackIndex] === open)) {
1041
+ for (let open = parents[index] ?? -1; open >= 0; open = parents[open] ?? -1)
1042
+ if (lowerWord(tokens[open + 1]) === 'select')
1003
1043
  return false;
1004
- }
1005
- }
1006
- return true;
1007
- };
1008
- const byParam = new Map(params.map((param) => [param.name, param]));
1044
+ let after = close + 1;
1045
+ if (lowerWord(tokens[after]) === 'filter')
1046
+ after = (closes.get(after + 1) ?? after) + 1;
1047
+ const scalar = (name === 'min' || name === 'max') &&
1048
+ tokens
1049
+ .slice(index + 2, close)
1050
+ .some((arg, at) => arg.text === ',' && depths[index + 2 + at] === depths[index + 2]);
1051
+ return !scalar && lowerWord(tokens[after]) !== 'over';
1052
+ });
1053
+ }
1054
+ function inferReactiveMetadata(sql, relations, ir, columns) {
1055
+ const refs = relations.tables;
1056
+ const proofs = scopeProofs(sql, ir).binds;
1009
1057
  const dependencies = [];
1010
1058
  const coverage = [];
1011
1059
  const ftsOwner = new Map(ir.tables.flatMap((table) => table.ftsIndexes.map((index) => [index.name, table.name])));
@@ -1014,43 +1062,23 @@ function inferReactiveMetadata(sql, refs, ir, params, columns) {
1014
1062
  ].sort()) {
1015
1063
  const table = ir.tables.find((candidate) => candidate.name === tableName);
1016
1064
  const tableRefs = refs.filter((ref) => ref.table === tableName);
1065
+ const ref = tableRefs.length === 1 ? tableRefs[0] : undefined;
1017
1066
  const scopes = [];
1018
- if (table !== undefined && tableRefs.length === 1 && !conservative) {
1019
- const qualifier = tableRefs[0]?.alias;
1067
+ if (table !== undefined && ref !== undefined) {
1020
1068
  for (const scope of table.scopes) {
1021
- const column = scope.column.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
1022
- const qualified = qualifier === undefined
1023
- ? `(?<![A-Za-z0-9_.:])(?:${IDENT}\\.)?${column}\\b`
1024
- : `(?<![A-Za-z0-9_.:])(?:${qualifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.)?${column}\\b`;
1025
- const found = [];
1026
- const equality = new RegExp(`${qualified}\\s*(?:=|==|\\bIS\\b)\\s*:(${IDENT})\\b|:(${IDENT})\\b\\s*(?:=|==)\\s*${qualified}`, 'gi');
1027
- for (const match of sql.matchAll(equality)) {
1028
- if (!requiredAt(match.index))
1029
- continue;
1030
- const name = match[1] ?? match[2];
1031
- const param = name === undefined ? undefined : byParam.get(name);
1032
- if (param !== undefined) {
1033
- found.push(param.name);
1034
- }
1035
- }
1036
- const inList = new RegExp(`${qualified}\\s+IN\\s*\\(([^)]*)\\)`, 'gi');
1037
- for (const match of sql.matchAll(inList)) {
1038
- if (!requiredAt(match.index))
1039
- continue;
1040
- for (const paramMatch of (match[1] ?? '').matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
1041
- const param = byParam.get(paramMatch[1]);
1042
- if (param !== undefined) {
1043
- found.push(param.name);
1044
- }
1045
- }
1046
- }
1047
- const unique = [...new Set(found)];
1048
- if (unique.length > 0) {
1069
+ const params = [
1070
+ ...new Set(proofs
1071
+ .filter((proof) => proof.scope === relations.scopeAt(ref.start) &&
1072
+ proof.alias === ref.alias.toLowerCase() &&
1073
+ proof.column === scope.column.toLowerCase())
1074
+ .flatMap((proof) => proof.params)),
1075
+ ];
1076
+ if (params.length > 0) {
1049
1077
  scopes.push({
1050
1078
  table: tableName,
1051
1079
  variable: scope.variable,
1052
1080
  pattern: scope.pattern,
1053
- params: unique,
1081
+ params,
1054
1082
  });
1055
1083
  }
1056
1084
  }
@@ -1180,24 +1208,8 @@ export function lowerFtsSourceIds(sql, ir) {
1180
1208
  const relations = scanRelations(sql, ir);
1181
1209
  if (!relations.tables.some((ref) => ftsNames.has(ref.table)))
1182
1210
  return sql;
1183
- const tokens = lexSyqlSqlSource('query SQL', sql).filter((token) => !isSyqlTrivia(token) && token.kind !== 'eof');
1184
- const depths = [];
1185
- const closes = new Map();
1186
- const stack = [];
1187
- tokens.forEach((token, index) => {
1188
- if (token.text === ')') {
1189
- const open = stack.pop();
1190
- if (open !== undefined)
1191
- closes.set(open, index);
1192
- }
1193
- depths[index] = stack.length;
1194
- if (token.text === '(')
1195
- stack.push(index);
1196
- });
1197
- const lower = (index) => {
1198
- const token = tokens[index];
1199
- return token?.kind === 'identifier' ? token.text.toLowerCase() : undefined;
1200
- };
1211
+ const { tokens, depths, closes } = sqlStructure(sql);
1212
+ const lower = (index) => lowerWord(tokens[index]);
1201
1213
  // Every SELECT scope as an offset range; the outer statement spans all.
1202
1214
  const scopes = [
1203
1215
  { start: -1, end: sql.length + 1 },
@@ -1332,22 +1344,26 @@ export function lowerFtsSourceIds(sql, ir) {
1332
1344
  export function analyzeStatement(name, location, statementText, ir, db, naming = DEFAULT_NAMING) {
1333
1345
  const file = location;
1334
1346
  const commentParams = parseCommentParams(file, statementText);
1347
+ const acknowledgements = parseCommentAcknowledgements(file, statementText);
1335
1348
  const sourceSql = statementText.trim();
1336
1349
  if (sourceSql.length === 0) {
1337
1350
  throw new TypegenError(file, 'query file is empty');
1338
1351
  }
1339
1352
  // SELECT-only (the read tier). A `WITH` is allowed when its main statement
1340
1353
  // is a SELECT (SQLite also allows WITH … INSERT/UPDATE/DELETE — writes).
1341
- const firstKeyword = /^\s*([A-Za-z]+)/.exec(stripCommentsAndStrings(statementText).trimStart())?.[1];
1342
- const upperKeyword = firstKeyword?.toUpperCase();
1343
- if (upperKeyword === 'WITH') {
1344
- const main = mainVerbAfterWith(stripCommentsAndStrings(statementText));
1345
- if (main !== 'SELECT') {
1346
- throw new TypegenError(file, `named queries are SELECT-only (the read tier); this WITH statement's main verb is ${JSON.stringify(main ?? '')}. Writes go through mutate() (SPEC §7.1).`);
1354
+ // CTE bodies sit inside parentheses and a bare keyword cannot name a CTE,
1355
+ // so the first depth-0 verb after `WITH` is the main verb.
1356
+ const statement = sqlStructure(statementText, file);
1357
+ const firstKeyword = lowerWord(statement.tokens[0]);
1358
+ if (firstKeyword === 'with') {
1359
+ const main = statement.tokens.find((token, index) => statement.depths[index] === 0 &&
1360
+ ['select', 'values', 'insert', 'update', 'delete', 'replace'].includes(lowerWord(token) ?? ''));
1361
+ if (lowerWord(main) !== 'select') {
1362
+ throw new TypegenError(file, `named queries are SELECT-only (the read tier); this WITH statement's main verb is ${JSON.stringify(main?.text.toUpperCase() ?? '')}. Writes go through mutate() (SPEC §7.1).`);
1347
1363
  }
1348
1364
  }
1349
- else if (upperKeyword !== 'SELECT') {
1350
- throw new TypegenError(file, `named queries are SELECT-only (the read tier); found ${JSON.stringify(firstKeyword ?? '')}. Writes go through mutate() (SPEC §7.1).`);
1365
+ else if (firstKeyword !== 'select') {
1366
+ throw new TypegenError(file, `named queries are SELECT-only (the read tier); found ${JSON.stringify(statement.tokens[0]?.text ?? '')}. Writes go through mutate() (SPEC §7.1).`);
1351
1367
  }
1352
1368
  // Let SQLite validate + describe the AUTHORED query first. Any bad
1353
1369
  // reference throws here with SQLite's own message.
@@ -1412,6 +1428,38 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
1412
1428
  : { ...source, nullableByJoin: source.nullableByJoin || cteRef.nullable };
1413
1429
  };
1414
1430
  const items = splitSelectList(sql);
1431
+ // A bare column of a SELECT that aggregates without GROUP BY reads NULL
1432
+ // when no row matches, and a compound SELECT returns the rows of every
1433
+ // branch, so a column is nullable when any branch can yield NULL there.
1434
+ const outer = sqlStructure(sql);
1435
+ const cuts = outer.tokens.flatMap((token, index) => outer.depths[index] === 0 &&
1436
+ ['union', 'intersect', 'except'].includes(lowerWord(token) ?? '')
1437
+ ? [token.span]
1438
+ : []);
1439
+ const branches = [0, ...cuts.map((span) => span.end.offset)].map((start, index) => {
1440
+ const end = cuts[index]?.start.offset ?? sql.length;
1441
+ const branchItems = splitSelectList(sql.slice(start, end));
1442
+ const grouped = outer.tokens.some((token, at) => outer.depths[at] === 0 &&
1443
+ token.span.start.offset >= start &&
1444
+ token.span.start.offset < end &&
1445
+ lowerWord(token) === 'group');
1446
+ const aggregated = !grouped &&
1447
+ (branchItems?.some((item) => callsAggregate(item.expr)) ?? false);
1448
+ return { start, end, items: branchItems, aggregated };
1449
+ });
1450
+ const branchNullable = (index) => branches.some((branch, position) => {
1451
+ if (branch.aggregated)
1452
+ return true;
1453
+ if (position === 0)
1454
+ return false;
1455
+ const item = branch.items?.[index];
1456
+ const source = item === undefined
1457
+ ? null
1458
+ : resolveSource(item, scoped.tables.filter((ref) => scoped.scopeAt(ref.start) === 'main' &&
1459
+ ref.start >= branch.start &&
1460
+ ref.start < branch.end), ir);
1461
+ return source === null || source.column.nullable || source.nullableByJoin;
1462
+ });
1415
1463
  const columns = described.columnNames.map((colName, index) => {
1416
1464
  const decl = described.declaredTypes[index];
1417
1465
  const item = items?.[index];
@@ -1427,7 +1475,7 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
1427
1475
  name: sqlName,
1428
1476
  langName,
1429
1477
  type: 'integer',
1430
- nullable: syncVersionNullable,
1478
+ nullable: syncVersionNullable || branchNullable(index),
1431
1479
  fidelity: 'exact',
1432
1480
  };
1433
1481
  }
@@ -1435,24 +1483,44 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
1435
1483
  // Exact: app-facing queries read the decrypted local mirror. Encrypted
1436
1484
  // columns therefore expose their pre-wire declaredType, while the schema
1437
1485
  // IR and mutation codec continue to carry the bytes wire type.
1438
- const sourceType = source.column.encrypted === true &&
1439
- source.column.declaredType !== undefined
1440
- ? source.column.declaredType
1441
- : source.column.type;
1442
1486
  return {
1443
1487
  name: sqlName,
1444
1488
  langName,
1445
- type: sourceType,
1446
- nullable: source.column.nullable || source.nullableByJoin,
1489
+ type: applicationColumnType(source.column),
1490
+ nullable: source.column.nullable ||
1491
+ source.nullableByJoin ||
1492
+ branchNullable(index),
1447
1493
  fidelity: 'exact',
1448
1494
  origin: { table: source.table, column: source.column.name },
1449
1495
  };
1450
1496
  }
1451
- // Fallback: decltype affinity if present, else the expr-shape fallback.
1452
- const mapped = decl !== null && decl !== undefined
1453
- ? DECLTYPE_MAP[decl.toUpperCase()]
1497
+ // Computed column (SYQL §14.1): the type is the decltype SQLite reports,
1498
+ // else the target of a whole-expression CAST, else integer for a
1499
+ // whole-expression count(); anything else is refused.
1500
+ const { tokens, depths, closes } = sqlStructure(item?.expr ?? '');
1501
+ const whole = tokens[1]?.text === '(' && closes.get(1) === tokens.length - 1
1502
+ ? lowerWord(tokens[0])
1454
1503
  : undefined;
1455
- const type = mapped ?? (item !== undefined ? fallbackColumnType(item.expr) : 'string');
1504
+ const asAt = tokens.findLastIndex((token, at) => depths[at] === 1 && lowerWord(token) === 'as');
1505
+ const castType = tokens
1506
+ .flatMap((token, at) => at > asAt && depths[at] === 1 && token.kind === 'identifier'
1507
+ ? [token.text.toUpperCase()]
1508
+ : [])
1509
+ .join(' ');
1510
+ const type = (decl !== null && decl !== undefined
1511
+ ? DECLTYPE_MAP[decl.toUpperCase()]
1512
+ : undefined) ??
1513
+ // SQLite gives the other mapped names NUMERIC or BLOB affinity, which
1514
+ // can change the value's storage class.
1515
+ (whole === 'cast' &&
1516
+ asAt > 0 &&
1517
+ /^(INTEGER|INT|BIGINT|SMALLINT|TEXT|REAL|FLOAT|DOUBLE|BLOB|BOOLEAN|BOOL)$/.test(castType)
1518
+ ? DECLTYPE_MAP[castType]
1519
+ : undefined) ??
1520
+ (whole === 'count' ? 'integer' : undefined);
1521
+ if (type === undefined) {
1522
+ throw new TypegenError(file, 'computed result column has no declared type; wrap the expression in CAST(... AS <type>)', 'typegen.computed_column_type', { query: name, column: sqlName });
1523
+ }
1456
1524
  return {
1457
1525
  name: sqlName,
1458
1526
  langName,
@@ -1479,8 +1547,8 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
1479
1547
  if (commented !== undefined) {
1480
1548
  return { name: paramName, langName, type: commented, source: 'comment' };
1481
1549
  }
1482
- const inferred = inferParamType(paramName, sql, refs, ir);
1483
- if (inferred !== null) {
1550
+ const inferred = inferParamTypeEvidence(paramName, sql, refs, ir)[0];
1551
+ if (inferred !== undefined) {
1484
1552
  return { name: paramName, langName, type: inferred, source: 'inferred' };
1485
1553
  }
1486
1554
  throw new TypegenError(file, `cannot infer a type for param :${paramName} (it is not compared to a plain column). Add a header comment: \`-- param :${paramName} <type>\` (one of ${[...PARAM_TYPES].join(', ')}).`);
@@ -1491,34 +1559,47 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
1491
1559
  throw new TypegenError(file, `-- param :${cp.name} names a parameter the query does not use`);
1492
1560
  }
1493
1561
  }
1494
- const reactive = inferReactiveMetadata(sql, refs, ir, params, columns);
1562
+ validateQueryIdentifier(name, naming.targets, file, 'query name');
1563
+ for (const column of columns) {
1564
+ validateQueryIdentifier(column.langName, naming.targets, file, 'result column');
1565
+ }
1566
+ for (const param of params) {
1567
+ if (!internalParams.has(param.name))
1568
+ validateQueryIdentifier(param.langName, naming.targets, file, 'param');
1569
+ }
1570
+ const reactive = inferReactiveMetadata(sql, scoped, ir, columns);
1571
+ // The emitted statement is what SQLite checks: the positional form, with
1572
+ // FTS source-id lowering applied, must prepare to the same result columns
1573
+ // and take exactly one value per distinct param.
1495
1574
  const physical = lowerFtsSourceIds(sql, ir);
1496
- if (physical !== sql) {
1497
- const lowered = analyze(physical);
1498
- if (lowered.paramsCount !== described.paramsCount ||
1499
- lowered.columnNames.length !== described.columnNames.length ||
1500
- lowered.columnNames.some((n, i) => n !== described.columnNames[i])) {
1501
- throw new TypegenError(file, `internal: FTS source-id lowering changed the result columns [${described.columnNames.join(', ')}] to [${lowered.columnNames.join(', ')}]`);
1502
- }
1575
+ const positionalSql = toPositionalSql(physical);
1576
+ const emitted = analyze(positionalSql);
1577
+ if (emitted.paramsCount !== params.length ||
1578
+ emitted.columnNames.join('\0') !== described.columnNames.join('\0')) {
1579
+ throw new TypegenError(file, 'internal: the emitted positional SQL does not prepare to the analyzed columns and params', 'typegen.emitted_sql_mismatch', {
1580
+ columns: described.columnNames,
1581
+ emittedColumns: emitted.columnNames,
1582
+ params: params.length,
1583
+ emittedParams: emitted.paramsCount,
1584
+ });
1503
1585
  }
1504
1586
  return {
1505
1587
  name,
1506
1588
  file,
1507
1589
  sourceSql,
1508
1590
  sql: physical,
1509
- positionalSql: toPositionalSql(physical),
1510
- relations: scanTableRefs(toPositionalSql(physical), ir, true).map((ref) => ({
1591
+ positionalSql,
1592
+ relations: scanTableRefs(positionalSql, ir, true).map((ref) => ({
1511
1593
  table: ref.table,
1512
1594
  start: ref.start,
1513
1595
  end: ref.end,
1514
- ...(ref.explicitAlias === undefined
1515
- ? {}
1516
- : { alias: ref.explicitAlias }),
1596
+ ...(ref.explicitAlias === undefined ? {} : { alias: ref.explicitAlias }),
1517
1597
  })),
1518
1598
  params,
1519
1599
  columns,
1520
1600
  tables,
1521
1601
  reactive,
1602
+ acknowledgements,
1522
1603
  };
1523
1604
  }
1524
1605
  /**
@@ -1533,7 +1614,7 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
1533
1614
  * missing one errors, naming the file + the statement's position/first line.
1534
1615
  */
1535
1616
  export function analyzeQueryFile(relPath, content, ir, db, naming = DEFAULT_NAMING) {
1536
- const statements = splitStatements(content);
1617
+ const statements = splitStatements(content, relPath);
1537
1618
  if (statements.length === 0) {
1538
1619
  throw new TypegenError(relPath, 'query file is empty');
1539
1620
  }
@@ -1554,10 +1635,110 @@ export function analyzeQueryFile(relPath, content, ir, db, naming = DEFAULT_NAMI
1554
1635
  * (or a `-- name:` override) and analyze. Rejects a `;`-separated file loudly
1555
1636
  * — use {@link analyzeQueryFile} for the multi-statement contract. */
1556
1637
  export function analyzeQuery(file, raw, ir, db, naming = DEFAULT_NAMING) {
1557
- const statements = splitStatements(raw);
1638
+ const statements = splitStatements(raw, file);
1558
1639
  if (statements.length > 1) {
1559
1640
  throw new TypegenError(file, 'a query file holds exactly one SELECT statement here (found a `;` separating statements) — use analyzeQueryFile for multi-statement files');
1560
1641
  }
1561
1642
  const results = analyzeQueryFile(file, raw, ir, db, naming);
1562
1643
  return results[0];
1563
1644
  }
1645
+ /**
1646
+ * The query plan check (`docs/SYQL.md` §14.5): plan every physical statement
1647
+ * against the schema database and fail on the first finding the query does
1648
+ * not acknowledge, then on the first acknowledgement that matches no finding.
1649
+ */
1650
+ export function checkQueryPlan(query, ir, db) {
1651
+ const findings = [];
1652
+ const tables = new Map(ir.tables.map((table) => [table.name, table]));
1653
+ const statements = query.syql?.plan.statements ?? [query];
1654
+ statements.forEach(({ positionalSql: sql, relations }, statement) => {
1655
+ const rows = db.plan(sql);
1656
+ const plan = rows.map((row) => row.detail);
1657
+ const scans = (details) => details.filter((detail) => detail.startsWith('SCAN ') && !detail.includes(' VIRTUAL TABLE')).length;
1658
+ // A plan names a relation by its alias, or by its table when unaliased.
1659
+ const tableOf = (name) => relations.find((relation) => (relation.alias ?? relation.table) === name)
1660
+ ?.table ?? name;
1661
+ const context = { query: query.name, file: query.file, statement, sql };
1662
+ for (const detail of plan) {
1663
+ const automatic = /^SEARCH (\S+) USING AUTOMATIC (?:PARTIAL )?(?:COVERING )?INDEX \((.*)\)/.exec(detail);
1664
+ if (automatic === null)
1665
+ continue;
1666
+ const table = tableOf(automatic[1]);
1667
+ findings.push({
1668
+ finding: 'automatic_index',
1669
+ table,
1670
+ details: {
1671
+ ...context,
1672
+ table,
1673
+ columns: [...automatic[2].matchAll(/(\w+)[=<>]/g)].map((key) => key[1]),
1674
+ plan,
1675
+ },
1676
+ });
1677
+ }
1678
+ const scanCount = scans(plan);
1679
+ if (scanCount > 0) {
1680
+ for (const table of [
1681
+ ...new Set(relations.map((relation) => relation.table)),
1682
+ ]) {
1683
+ const columns = (tables.get(table)?.columns ?? [])
1684
+ .map((column) => column.name)
1685
+ .filter((column) => scans(db
1686
+ .plan(sql, `CREATE INDEX "__syncular_plan_probe" ON "${table}" ("${column}")`)
1687
+ .map((row) => row.detail)) < scanCount);
1688
+ if (columns.length > 0) {
1689
+ findings.push({
1690
+ finding: 'scan',
1691
+ table,
1692
+ details: { ...context, table, columns, plan },
1693
+ });
1694
+ }
1695
+ }
1696
+ }
1697
+ const { tokens, depths } = sqlStructure(sql);
1698
+ const bounded = tokens.some((token, index) => depths[index] === 0 &&
1699
+ ['where', 'limit'].includes(lowerWord(token) ?? ''));
1700
+ const topScan = rows.find((row) => row.parent === 0 &&
1701
+ scans([row.detail]) === 1 &&
1702
+ tables.has(tableOf(row.detail.split(' ')[1])));
1703
+ if (!bounded && topScan !== undefined) {
1704
+ const table = tableOf(topScan.detail.split(' ')[1]);
1705
+ findings.push({
1706
+ finding: 'unbounded',
1707
+ table,
1708
+ details: { ...context, table, plan },
1709
+ });
1710
+ }
1711
+ });
1712
+ const dependencies = [
1713
+ ...new Set(query.reactive.dependencies.map(({ table }) => table)),
1714
+ ].sort();
1715
+ if (dependencies.length > 4) {
1716
+ findings.push({
1717
+ finding: 'many_tables',
1718
+ details: { query: query.name, file: query.file, tables: dependencies },
1719
+ });
1720
+ }
1721
+ const messages = {
1722
+ scan: 'the query plan scans a table that an index on one of the listed columns would let SQLite search; declare the index or acknowledge the finding',
1723
+ automatic_index: 'the query plan builds an automatic index on every run; declare an index on the listed columns or acknowledge the finding',
1724
+ unbounded: 'the query reads every row of a table, with no WHERE and no LIMIT; bound the query or acknowledge the finding',
1725
+ many_tables: 'the query reads more than four tables, and a change to any of them re-runs it; split the query or acknowledge the finding',
1726
+ };
1727
+ const acknowledged = (acknowledgement, found) => acknowledgement.finding === found.finding &&
1728
+ acknowledgement.table === found.table;
1729
+ for (const found of findings) {
1730
+ if (!query.acknowledgements.some((ack) => acknowledged(ack, found))) {
1731
+ throw new TypegenError(query.file, messages[found.finding], `typegen.query_${found.finding}`, found.details);
1732
+ }
1733
+ }
1734
+ for (const ack of query.acknowledgements) {
1735
+ if (!findings.some((found) => acknowledged(ack, found))) {
1736
+ throw new TypegenError(query.file, 'the query plan acknowledgement matches no finding of its query; remove it', 'typegen.query_acknowledgement_unused', {
1737
+ query: query.name,
1738
+ file: query.file,
1739
+ finding: ack.finding,
1740
+ table: ack.table ?? null,
1741
+ });
1742
+ }
1743
+ }
1744
+ }