@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/query.ts CHANGED
@@ -64,8 +64,13 @@
64
64
  import { TypegenError } from './errors';
65
65
  import { isSyqlTrivia, lexSyqlSqlSource, type SyqlToken } from './syql-lexer';
66
66
  import type { IrColumn, IrColumnType, IrDocument, IrTable } from './ir';
67
- import { findProjection, lowerProjection, mainVerbAfterWith } from './lower';
68
- import { buildNamingMap, type NamingMode, type NamingTarget } from './naming';
67
+ import { findProjection, lowerProjection } from './lower';
68
+ import {
69
+ buildNamingMap,
70
+ type NamingMode,
71
+ type NamingTarget,
72
+ validateQueryIdentifier,
73
+ } from './naming';
69
74
 
70
75
  /** The SQL decltype keyword → §2.4 type map (mirrors sql.ts TYPE_MAP so a
71
76
  * plain column ref's decltype resolves to the exact IR type). */
@@ -116,7 +121,7 @@ export interface QueryColumn {
116
121
  readonly type: IrColumnType;
117
122
  readonly nullable: boolean;
118
123
  /** `exact` = resolved to an IR column (plain ref); `fallback` = a computed
119
- * expression typed by the documented honest fallback. */
124
+ * expression typed by its `CAST` or `count()` (SYQL §14.1). */
120
125
  readonly fidelity: 'exact' | 'fallback';
121
126
  /** Proven physical origin for reactive row identity and diagnostics. */
122
127
  readonly origin?: { readonly table: string; readonly column: string };
@@ -139,6 +144,38 @@ export interface QueryCoverageBinding {
139
144
  }[];
140
145
  }
141
146
 
147
+ /** The window bases (SPEC §4.8) a query's coverage needs, for generated
148
+ * descriptors. A base names no table, so tables proven by the same base share
149
+ * one entry; a fixed scope bound to several params yields one base per value
150
+ * combination, since a base holds one value per fixed variable. Ordered by
151
+ * code point of the JSON so emitted metadata is byte-identical across
152
+ * locales. */
153
+ export function windowBases(coverage: readonly QueryCoverageBinding[]): {
154
+ readonly variable: string;
155
+ readonly units: readonly string[];
156
+ readonly fixedScopes: readonly { variable: string; param: string }[];
157
+ }[] {
158
+ const bases = coverage.flatMap((entry) => {
159
+ let combinations: { variable: string; param: string }[][] = [[]];
160
+ for (const scope of entry.fixedScopes) {
161
+ combinations = combinations.flatMap((combination) =>
162
+ scope.params.map((param) => [
163
+ ...combination,
164
+ { variable: scope.variable, param },
165
+ ]),
166
+ );
167
+ }
168
+ return combinations.map((fixedScopes) => ({
169
+ variable: entry.variable,
170
+ units: entry.units,
171
+ fixedScopes,
172
+ }));
173
+ });
174
+ return [...new Map(bases.map((base) => [JSON.stringify(base), base]))]
175
+ .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
176
+ .map(([, base]) => base);
177
+ }
178
+
142
179
  export interface QueryReactiveMetadata {
143
180
  readonly dependencies: readonly {
144
181
  readonly table: string;
@@ -277,6 +314,23 @@ export interface QueryRelation {
277
314
  readonly alias?: string;
278
315
  }
279
316
 
317
+ /** The findings of the query plan check (`docs/SYQL.md` §14.5). */
318
+ export const QUERY_PLAN_FINDINGS = [
319
+ 'scan',
320
+ 'automatic_index',
321
+ 'unbounded',
322
+ 'many_tables',
323
+ ] as const;
324
+ export type QueryPlanFinding = (typeof QUERY_PLAN_FINDINGS)[number];
325
+
326
+ /** An author's acknowledgement of one plan finding, with its reason. */
327
+ export interface QueryAcknowledgement {
328
+ readonly finding: QueryPlanFinding;
329
+ /** Absent for `many_tables`. */
330
+ readonly table?: string;
331
+ readonly reason: string;
332
+ }
333
+
280
334
  export interface AnalyzedQuery {
281
335
  /** camelCase function name (path-derived, or a `-- name:` override). */
282
336
  readonly name: string;
@@ -302,6 +356,18 @@ export interface AnalyzedQuery {
302
356
  /** Revision-1 frontend/public-input and physical execution contract. When
303
357
  * present, emitters use this instead of treating `params` as the API. */
304
358
  readonly syql?: QuerySyqlMetadata;
359
+ /** Plan findings the author acknowledged on the statement. */
360
+ readonly acknowledgements: readonly QueryAcknowledgement[];
361
+ }
362
+
363
+ /** The public SYQL input an emitter binds by name. */
364
+ export function syqlInput(
365
+ query: AnalyzedQuery,
366
+ name: string,
367
+ ): QuerySyqlPublicInput {
368
+ const input = query.syql?.inputs.find((candidate) => candidate.name === name);
369
+ if (input === undefined) throw new Error(`unknown SYQL input ${name}`);
370
+ return input;
305
371
  }
306
372
 
307
373
  // -- path → name --------------------------------------------------------------
@@ -381,13 +447,38 @@ export function validateOverrideName(name: string, location: string): string {
381
447
  return name;
382
448
  }
383
449
 
384
- // -- statement splitting ------------------------------------------------------
450
+ // -- SQL tokens -----------------------------------------------------------------
385
451
  //
386
- // A file may hold multiple statements separated by top-level `;`. We split on
387
- // semicolons that are NOT inside a single-quoted string, a `--` line comment,
388
- // or a `/* */` block comment. The SELECT-only subset has no BEGIN/END blocks,
389
- // so top-level semicolons are unambiguous statement terminators. A trailing
390
- // semicolon on the last statement is optional (an empty tail is dropped).
452
+ // Every scan below reads the lossless SYQL lexer (`syql-lexer.ts`), so string
453
+ // literals, quoted identifiers, and comments are atomic tokens: their text is
454
+ // never split, rescanned, or rewritten. SQLite remains the authority on
455
+ // correctness.
456
+
457
+ /** Significant SQL tokens (no trivia) with each token's parenthesis depth,
458
+ * its innermost enclosing `(` (or -1), and every `(` index's matching `)`. */
459
+ function sqlStructure(sql: string, file = 'query SQL') {
460
+ const tokens = lexSyqlSqlSource(file, sql).filter(
461
+ (token) => !isSyqlTrivia(token) && token.kind !== 'eof',
462
+ );
463
+ const depths: number[] = [];
464
+ const parents: number[] = [];
465
+ const closes = new Map<number, number>();
466
+ const stack: number[] = [];
467
+ tokens.forEach((token, index) => {
468
+ if (token.text === ')') {
469
+ const open = stack.pop();
470
+ if (open !== undefined) closes.set(open, index);
471
+ }
472
+ parents[index] = stack.at(-1) ?? -1;
473
+ depths[index] = stack.length;
474
+ if (token.text === '(') stack.push(index);
475
+ });
476
+ return { tokens, depths, parents, closes };
477
+ }
478
+
479
+ function lowerWord(token: SyqlToken | undefined): string | undefined {
480
+ return token?.kind === 'identifier' ? token.text.toLowerCase() : undefined;
481
+ }
391
482
 
392
483
  export interface SplitStatement {
393
484
  /** The raw statement text (leading comment block + SQL), as written. */
@@ -396,113 +487,56 @@ export interface SplitStatement {
396
487
  readonly startLine: number;
397
488
  }
398
489
 
399
- /** Split file content into statements on top-level `;` (string/comment-aware).
400
- * Blank/comment-only tails are dropped; each statement keeps its own leading
401
- * comment block (everything between the previous `;` and this SQL). */
402
- export function splitStatements(content: string): SplitStatement[] {
403
- const parts: { text: string; startOffset: number }[] = [];
404
- let i = 0;
405
- let start = 0;
406
- while (i < content.length) {
407
- const ch = content[i] as string;
408
- const next = content[i + 1];
409
- if (ch === '-' && next === '-') {
410
- const end = content.indexOf('\n', i);
411
- i = end === -1 ? content.length : end;
412
- } else if (ch === '/' && next === '*') {
413
- const end = content.indexOf('*/', i + 2);
414
- i = end === -1 ? content.length : end + 2;
415
- } else if (ch === "'") {
416
- let j = i + 1;
417
- for (;;) {
418
- if (j >= content.length) break;
419
- if (content[j] === "'") {
420
- if (content[j + 1] === "'") j += 2;
421
- else {
422
- j += 1;
423
- break;
424
- }
425
- } else j += 1;
490
+ /** Split file content into statements on top-level `;` tokens. A statement
491
+ * keeps its leading comment block; comment-only parts are dropped. The
492
+ * SELECT-only subset has no BEGIN/END blocks, so every `;` token ends one
493
+ * statement and a trailing `;` is optional. */
494
+ export function splitStatements(
495
+ content: string,
496
+ file = 'query SQL',
497
+ ): SplitStatement[] {
498
+ const out: SplitStatement[] = [];
499
+ let lead: SyqlToken | undefined;
500
+ let hasSql = false;
501
+ for (const token of lexSyqlSqlSource(file, content)) {
502
+ if (token.kind === 'eof' || token.text === ';') {
503
+ if (lead !== undefined && hasSql) {
504
+ out.push({
505
+ text: content.slice(lead.span.start.offset, token.span.start.offset),
506
+ startLine: lead.span.start.line,
507
+ });
426
508
  }
427
- i = j;
428
- } else if (ch === ';') {
429
- parts.push({ text: content.slice(start, i), startOffset: start });
430
- i += 1;
431
- start = i;
432
- } else {
433
- i += 1;
509
+ lead = undefined;
510
+ hasSql = false;
511
+ } else if (token.kind !== 'whitespace') {
512
+ lead ??= token;
513
+ hasSql ||= !isSyqlTrivia(token);
434
514
  }
435
515
  }
436
- if (start < content.length) {
437
- parts.push({ text: content.slice(start), startOffset: start });
438
- }
439
- const out: SplitStatement[] = [];
440
- for (const part of parts) {
441
- // Drop parts whose SQL body (comments/whitespace stripped) is empty — a
442
- // trailing `;` or a comment-only tail is not a statement.
443
- if (stripCommentsAndStrings(part.text).trim().length === 0) continue;
444
- // Report the line of the statement's first NON-blank character (skip the
445
- // blank/whitespace run after the previous `;`), so the location points at
446
- // real content, not the terminator's trailing newline.
447
- const lead = part.text.length - part.text.replace(/^\s+/, '').length;
448
- const before = content.slice(0, part.startOffset + lead);
449
- const startLine = before.split('\n').length;
450
- out.push({ text: part.text.replace(/^\s+/, ''), startLine });
451
- }
452
516
  return out;
453
517
  }
454
518
 
455
- /** The leading comment block of a statement: the run of blank + line/block
456
- * comment lines before the first SQL token. `-- name:` / `-- param` markers are
457
- * scoped HERE (to the statement they directly precede), not file-wide. Returns
458
- * the `--` comment lines (block comments carry no markers we parse). */
459
- function leadingCommentBlock(statementText: string): string[] {
460
- const lines: string[] = [];
461
- let i = 0;
462
- while (i < statementText.length) {
463
- // Skip leading whitespace on the line.
464
- while (
465
- i < statementText.length &&
466
- /[ \t\r]/.test(statementText[i] as string)
467
- ) {
468
- i += 1;
469
- }
470
- const ch = statementText[i];
471
- const next = statementText[i + 1];
472
- if (ch === '\n') {
473
- i += 1;
474
- continue;
475
- }
476
- if (ch === '-' && next === '-') {
477
- const end = statementText.indexOf('\n', i);
478
- const line = statementText.slice(i, end === -1 ? undefined : end);
479
- lines.push(line);
480
- i = end === -1 ? statementText.length : end + 1;
481
- continue;
482
- }
483
- if (ch === '/' && next === '*') {
484
- const end = statementText.indexOf('*/', i + 2);
485
- // Block comments carry no markers we parse; skip and keep scanning for
486
- // more leading comments (but they don't contribute -- name:/-- param).
487
- i = end === -1 ? statementText.length : end + 2;
488
- continue;
489
- }
490
- break; // first SQL token — the comment block ends here
519
+ /** The `--` comments before a statement's first SQL token. `-- name:` and
520
+ * `-- param` markers are scoped to the statement they precede. */
521
+ function leadingComments(statementText: string): string[] {
522
+ const comments: string[] = [];
523
+ for (const token of lexSyqlSqlSource('query SQL', statementText)) {
524
+ if (!isSyqlTrivia(token)) break;
525
+ if (token.kind === 'line-comment') comments.push(token.text);
491
526
  }
492
- return lines;
527
+ return comments;
493
528
  }
494
529
 
495
- const NAME_MARKER_RE = /^\s*--\s*name:\s*(\S+)\s*$/;
530
+ const NAME_MARKER_RE = /^--\s*name:\s*(\S+)\s*$/;
496
531
 
497
532
  /** The `-- name:` override in a statement's leading comment block, or null. */
498
533
  export function parseStatementName(
499
534
  statementText: string,
500
535
  location: string,
501
536
  ): string | null {
502
- const lines = leadingCommentBlock(statementText);
503
537
  let found: string | null = null;
504
- for (const line of lines) {
505
- const m = NAME_MARKER_RE.exec(line);
538
+ for (const comment of leadingComments(statementText)) {
539
+ const m = NAME_MARKER_RE.exec(comment);
506
540
  if (m === null) continue;
507
541
  if (found !== null) {
508
542
  throw new TypegenError(
@@ -515,20 +549,13 @@ export function parseStatementName(
515
549
  return found;
516
550
  }
517
551
 
518
- // -- lightweight SQL scanning -------------------------------------------------
519
- //
520
- // We do NOT re-implement SQLite's parser (that is what prepare() is for). We
521
- // scan the text only for: header `-- param` comments, `:name` placeholders,
522
- // FROM/JOIN table identifiers, and SELECT-column → source resolution. SQLite
523
- // remains the authority on correctness.
524
-
525
552
  interface CommentParam {
526
553
  readonly name: string;
527
554
  readonly type: IrColumnType;
528
555
  }
529
556
 
530
557
  const PARAM_COMMENT_RE =
531
- /^\s*--\s*param\s+:([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z_]+)\s*$/;
558
+ /^--\s*param\s+:([A-Za-z_][A-Za-z0-9_]*)\s+([A-Za-z_]+)\s*$/;
532
559
 
533
560
  const PARAM_TYPES = new Set<string>([
534
561
  'string',
@@ -541,14 +568,11 @@ const PARAM_TYPES = new Set<string>([
541
568
  'crdt',
542
569
  ]);
543
570
 
544
- /** Parse `-- param :name <type>` header lines. They must precede the SQL. */
571
+ /** Parse the `-- param :name <type>` markers of the leading comment block. */
545
572
  function parseCommentParams(file: string, raw: string): CommentParam[] {
546
573
  const out: CommentParam[] = [];
547
- for (const line of raw.split('\n')) {
548
- const trimmed = line.trim();
549
- if (trimmed.length === 0) continue;
550
- if (!trimmed.startsWith('--')) break; // first non-comment line ends the header
551
- const match = PARAM_COMMENT_RE.exec(line);
574
+ for (const comment of leadingComments(raw)) {
575
+ const match = PARAM_COMMENT_RE.exec(comment);
552
576
  if (match === null) continue; // an ordinary comment, ignore
553
577
  const name = match[1] as string;
554
578
  const type = (match[2] as string).toLowerCase();
@@ -563,65 +587,76 @@ function parseCommentParams(file: string, raw: string): CommentParam[] {
563
587
  return out;
564
588
  }
565
589
 
566
- /** Strip `--` and block comments so identifier scans don't hit commented SQL,
567
- * and string literals so `':x'` inside a string isn't read as a param. */
568
- export function stripCommentsAndStrings(sql: string): string {
569
- let out = '';
570
- let i = 0;
571
- while (i < sql.length) {
572
- const ch = sql[i] as string;
573
- const next = sql[i + 1];
574
- if (ch === '-' && next === '-') {
575
- const end = sql.indexOf('\n', i);
576
- const stop = end === -1 ? sql.length : end;
577
- out += ' '.repeat(stop - i);
578
- i = stop;
579
- } else if (ch === '/' && next === '*') {
580
- const end = sql.indexOf('*/', i + 2);
581
- const stop = end === -1 ? sql.length : end + 2;
582
- out += sql.slice(i, stop).replace(/[^\n]/g, ' ');
583
- i = stop;
584
- } else if (ch === "'") {
585
- let stop = i + 1;
586
- while (stop < sql.length) {
587
- if (sql[stop] === "'" && sql[stop + 1] === "'") {
588
- stop += 2;
589
- continue;
590
- }
591
- if (sql[stop] === "'") {
592
- stop += 1;
593
- break;
594
- }
595
- stop += 1;
596
- }
597
- out += sql.slice(i, stop).replace(/[^\n]/g, ' ');
598
- i = stop;
599
- } else {
600
- out += ch;
601
- i += 1;
590
+ const ACKNOWLEDGEMENT_RE = new RegExp(
591
+ `^--\\s*allow\\s+(${QUERY_PLAN_FINDINGS.join('|')})\\b`,
592
+ );
593
+
594
+ /** Parse the `-- allow <finding> [table]: <reason>` acknowledgements of the
595
+ * leading comment block (`docs/SYQL.md` §14.5). */
596
+ function parseCommentAcknowledgements(
597
+ file: string,
598
+ raw: string,
599
+ ): QueryAcknowledgement[] {
600
+ const out: QueryAcknowledgement[] = [];
601
+ for (const comment of leadingComments(raw)) {
602
+ const kind = ACKNOWLEDGEMENT_RE.exec(comment)?.[1];
603
+ const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind);
604
+ if (finding === undefined) continue;
605
+ const match =
606
+ /^--\s*allow\s+\w+(?:\s+([A-Za-z_][A-Za-z0-9_]*))?\s*:\s*(\S.*?)\s*$/.exec(
607
+ comment,
608
+ );
609
+ const table = match?.[1];
610
+ if (
611
+ match === null ||
612
+ (finding === 'many_tables') !== (table === undefined) ||
613
+ out.some((other) => other.finding === finding && other.table === table)
614
+ ) {
615
+ throw new TypegenError(
616
+ file,
617
+ 'invalid query plan acknowledgement; write `-- allow <finding> <table>: <reason>` once per finding',
618
+ 'typegen.query_acknowledgement_invalid',
619
+ { file, comment },
620
+ );
602
621
  }
622
+ out.push({
623
+ finding,
624
+ ...(table === undefined ? {} : { table }),
625
+ reason: match[2] as string,
626
+ });
603
627
  }
604
628
  return out;
605
629
  }
606
630
 
607
- /** Distinct `:name` placeholders in first-occurrence order (dedup by name,
608
- * matching SQLite's paramsCount which counts distinct names). */
631
+ /** Blank comments and string/blob literals with spaces (newlines kept), so
632
+ * offset-preserving text scans never read inside them. */
633
+ export function stripCommentsAndStrings(sql: string): string {
634
+ return lexSyqlSqlSource('query SQL', sql)
635
+ .map((token) =>
636
+ token.kind === 'line-comment' ||
637
+ token.kind === 'block-comment' ||
638
+ token.kind === 'string' ||
639
+ token.kind === 'blob'
640
+ ? token.text.replace(/[^\n]/g, ' ')
641
+ : token.text,
642
+ )
643
+ .join('');
644
+ }
645
+
646
+ /** Distinct `:name` binds in first-occurrence order (SQLite's paramsCount
647
+ * counts distinct names). */
609
648
  function scanParamNames(sql: string): string[] {
610
- const cleaned = stripCommentsAndStrings(sql);
611
- // `:name` but not `::` (Postgres cast) — our subset never has `::`.
612
- const re = /:([A-Za-z_][A-Za-z0-9_]*)/g;
613
- const seen: string[] = [];
614
- for (const m of cleaned.matchAll(re)) {
615
- const name = m[1] as string;
616
- if (!seen.includes(name)) seen.push(name);
649
+ const names: string[] = [];
650
+ for (const token of lexSyqlSqlSource('query SQL', sql)) {
651
+ const name = token.text.slice(1);
652
+ if (token.kind === 'bind' && !names.includes(name)) names.push(name);
617
653
  }
618
- return seen;
654
+ return names;
619
655
  }
620
656
 
621
- /** Rewrite `:name` → positional placeholders AND strip comments + collapse
622
- * whitespace, producing a clean single-line SQL string suitable for
623
- * embedding in a generated string literal. String literals are preserved
624
- * verbatim (their inner whitespace is not collapsed).
657
+ /** The emitted single-line statement: `:name` binds become positional, every
658
+ * whitespace/comment run between tokens becomes one space, and every other
659
+ * token (string literals, quoted identifiers) keeps its exact text.
625
660
  *
626
661
  * When every param occurs exactly once, plain `?` is emitted. When ANY
627
662
  * param repeats (the §7 neutralization guards mention a param in the guard
@@ -629,74 +664,27 @@ function scanParamNames(sql: string): string[] {
629
664
  * form — one bound value per DISTINCT param, reuse resolved by SQLite —
630
665
  * so the generated bind array stays one-entry-per-param. */
631
666
  export function toPositionalSql(sql: string): string {
632
- interface ParamToken {
633
- readonly param: string;
634
- }
635
- const tokens: (string | ParamToken)[] = [];
636
- let i = 0;
637
- while (i < sql.length) {
638
- const ch = sql[i] as string;
639
- const next = sql[i + 1];
640
- if (ch === '-' && next === '-') {
641
- const end = sql.indexOf('\n', i);
642
- i = end === -1 ? sql.length : end + 1;
643
- tokens.push(' ');
644
- } else if (ch === '/' && next === '*') {
645
- const end = sql.indexOf('*/', i + 2);
646
- i = end === -1 ? sql.length : end + 2;
647
- tokens.push(' ');
648
- } else if (ch === "'") {
649
- // Preserve string literals verbatim (including any '' escapes).
650
- let j = i + 1;
651
- let lit = "'";
652
- for (;;) {
653
- if (j >= sql.length) break;
654
- if (sql[j] === "'") {
655
- if (sql[j + 1] === "'") {
656
- lit += "''";
657
- j += 2;
658
- } else {
659
- lit += "'";
660
- j += 1;
661
- break;
662
- }
663
- } else {
664
- lit += sql[j];
665
- j += 1;
666
- }
667
- }
668
- tokens.push(lit);
669
- i = j;
670
- } else if (ch === ':' && next !== undefined && /[A-Za-z_]/.test(next)) {
671
- let end = i + 1;
672
- while (end < sql.length && /[A-Za-z0-9_]/.test(sql[end] as string)) {
673
- end += 1;
674
- }
675
- tokens.push({ param: sql.slice(i + 1, end) });
676
- i = end;
677
- } else if (/\s/.test(ch)) {
678
- tokens.push(' ');
679
- i += 1;
680
- } else {
681
- tokens.push(ch);
682
- i += 1;
683
- }
684
- }
685
- const order: string[] = [];
686
- let repeats = false;
667
+ const tokens = lexSyqlSqlSource('query SQL', sql);
668
+ const order = scanParamNames(sql);
669
+ const repeats =
670
+ tokens.filter((token) => token.kind === 'bind').length > order.length;
671
+ let out = '';
672
+ let space = false;
687
673
  for (const token of tokens) {
688
- if (typeof token === 'string') continue;
689
- if (order.includes(token.param)) repeats = true;
690
- else order.push(token.param);
674
+ if (isSyqlTrivia(token) || token.kind === 'eof') {
675
+ space = out.length > 0;
676
+ continue;
677
+ }
678
+ if (space) out += ' ';
679
+ space = false;
680
+ out +=
681
+ token.kind !== 'bind'
682
+ ? token.text
683
+ : repeats
684
+ ? `?${order.indexOf(token.text.slice(1)) + 1}`
685
+ : '?';
691
686
  }
692
- const rendered = tokens
693
- .map((token) => {
694
- if (typeof token === 'string') return token;
695
- return repeats ? `?${order.indexOf(token.param) + 1}` : '?';
696
- })
697
- .join('');
698
- // Collapse runs of the whitespace placeholders; trim.
699
- return rendered.replace(/\s+/g, ' ').trim();
687
+ return out;
700
688
  }
701
689
 
702
690
  // -- FROM/JOIN table resolution ----------------------------------------------
@@ -739,7 +727,10 @@ const RESERVED_ALIAS = new Set([
739
727
  'indexed',
740
728
  'not',
741
729
  ]);
742
- function sqlIdentifier(token: SyqlToken | undefined): string | undefined {
730
+ /** The name a plain or quoted identifier token spells. */
731
+ export function sqlIdentifier(
732
+ token: SyqlToken | undefined,
733
+ ): string | undefined {
743
734
  if (token?.kind === 'identifier') return token.text;
744
735
  if (token?.kind !== 'quoted-identifier') return undefined;
745
736
  const quote = token.text[0];
@@ -793,9 +784,7 @@ export function scanRelations(
793
784
  ir: IrDocument,
794
785
  lowered = false,
795
786
  ): SqlRelations {
796
- const tokens = lexSyqlSqlSource('query SQL', sql).filter(
797
- (token) => !isSyqlTrivia(token) && token.kind !== 'eof',
798
- );
787
+ const { tokens, depths, parents, closes } = sqlStructure(sql);
799
788
  const known = new Map(
800
789
  ir.tables.flatMap((table) => [
801
790
  [table.name.toLowerCase(), table.name] as const,
@@ -813,19 +802,6 @@ export function scanRelations(
813
802
  )
814
803
  : [],
815
804
  );
816
- const closes = new Map<number, number>();
817
- const parents: number[] = [];
818
- const depths: number[] = [];
819
- const stack: number[] = [];
820
- tokens.forEach((token, index) => {
821
- if (token.text === ')') {
822
- const open = stack.pop();
823
- if (open !== undefined) closes.set(open, index);
824
- }
825
- parents[index] = stack.at(-1) ?? -1;
826
- depths[index] = stack.length;
827
- if (token.text === '(') stack.push(index);
828
- });
829
805
  const activeFromDepths = new Set<number>();
830
806
  const clauseEnders = new Set([
831
807
  'where',
@@ -1062,6 +1038,268 @@ export function scanRelations(
1062
1038
  };
1063
1039
  }
1064
1040
 
1041
+ // -- scope proofs (SYQL §13) ----------------------------------------------------
1042
+
1043
+ /** A declared scope column of one table instance: the instance's SELECT scope
1044
+ * ({@link SqlRelations.scopeAt}), lowercased alias, and lowercased column. */
1045
+ export interface ScopeColumn {
1046
+ readonly scope: string;
1047
+ readonly alias: string;
1048
+ readonly column: string;
1049
+ }
1050
+
1051
+ export interface ScopeProofs {
1052
+ /** `column = :bind`, `:bind = column`, `column IS :bind`, and
1053
+ * `column IN (:a, :b)` conjuncts of a WHERE clause. */
1054
+ readonly binds: readonly (ScopeColumn & {
1055
+ readonly operator: 'equal' | 'in';
1056
+ readonly params: readonly string[];
1057
+ })[];
1058
+ /** Qualified `a.x = b.y` conjuncts. A symmetric equality (a WHERE conjunct
1059
+ * or an inner-join ON conjunct) proves each operand from the other; an
1060
+ * outer-join ON conjunct proves only `target` from `source`. */
1061
+ readonly equalities: readonly {
1062
+ readonly target: ScopeColumn;
1063
+ readonly source: ScopeColumn;
1064
+ readonly symmetric: boolean;
1065
+ }[];
1066
+ }
1067
+
1068
+ const CLAUSE_WORDS = new Set([
1069
+ 'where',
1070
+ 'group',
1071
+ 'having',
1072
+ 'order',
1073
+ 'limit',
1074
+ 'window',
1075
+ 'join',
1076
+ 'inner',
1077
+ 'left',
1078
+ 'right',
1079
+ 'full',
1080
+ 'cross',
1081
+ 'natural',
1082
+ ]);
1083
+
1084
+ /**
1085
+ * The scope-proof rule shared by `.sql` and `.syql` queries (SYQL §13). A
1086
+ * comparison proves a scope only when it is a whole top-level conjunct of
1087
+ * the WHERE clause of the SELECT scope that reads the instance: the outer
1088
+ * statement or a top-level CTE body. Parentheses around a whole conjunct are
1089
+ * transparent. Nothing else is a proof: a WHERE clause with a top-level OR, a
1090
+ * compound SELECT scope, a nested subquery, and any other conjunct shape (NOT,
1091
+ * a comparison of the comparison, a function, CASE, COLLATE, IS after the
1092
+ * bind, a literal in an IN list). Column equalities also come from the
1093
+ * conjuncts of an ON clause without OR, NOT, or a subquery.
1094
+ */
1095
+ export function scopeProofs(sql: string, ir: IrDocument): ScopeProofs {
1096
+ const { tokens, depths, closes } = sqlStructure(sql);
1097
+ const relations = scanRelations(sql, ir);
1098
+ const binds: ScopeProofs['binds'][number][] = [];
1099
+ const equalities: ScopeProofs['equalities'][number][] = [];
1100
+ const tableOf = (ref: TableRef) =>
1101
+ ir.tables.find((table) => table.name === ref.table);
1102
+ const scopeColumn = (
1103
+ scope: string,
1104
+ qualifier: string | undefined,
1105
+ column: string,
1106
+ ): ScopeColumn | undefined => {
1107
+ const name = column.toLowerCase();
1108
+ const candidates = relations.tables.filter(
1109
+ (ref) =>
1110
+ relations.scopeAt(ref.start) === scope &&
1111
+ (qualifier === undefined
1112
+ ? tableOf(ref)?.columns.some((c) => c.name.toLowerCase() === name)
1113
+ : ref.alias.toLowerCase() === qualifier.toLowerCase()),
1114
+ );
1115
+ const ref = candidates.length === 1 ? candidates[0] : undefined;
1116
+ const declared =
1117
+ ref === undefined
1118
+ ? undefined
1119
+ : tableOf(ref)?.scopes.find((s) => s.column.toLowerCase() === name);
1120
+ return ref === undefined || declared === undefined
1121
+ ? undefined
1122
+ : { scope, alias: ref.alias.toLowerCase(), column: name };
1123
+ };
1124
+ const columnAt = (index: number) => {
1125
+ const first = sqlIdentifier(tokens[index]);
1126
+ if (first === undefined) return undefined;
1127
+ if (tokens[index + 1]?.text !== '.')
1128
+ return { qualifier: undefined, column: first, next: index + 1 };
1129
+ const column = sqlIdentifier(tokens[index + 2]);
1130
+ return column === undefined
1131
+ ? undefined
1132
+ : { qualifier: first, column, next: index + 3 };
1133
+ };
1134
+ const equal = (index: number) =>
1135
+ tokens[index]?.text === '=' || tokens[index]?.text === '==';
1136
+ const bindAt = (index: number) =>
1137
+ tokens[index]?.kind === 'bind'
1138
+ ? (tokens[index] as SyqlToken).text.slice(1)
1139
+ : undefined;
1140
+ const conjuncts = (from: number, to: number): [number, number][] => {
1141
+ const parts: [number, number][] = [];
1142
+ let start = from;
1143
+ let cases = 0;
1144
+ let between = false;
1145
+ for (let index = from; index < to; index += 1) {
1146
+ if (depths[index] !== depths[from]) continue;
1147
+ const word = lowerWord(tokens[index]);
1148
+ if (word === 'case') cases += 1;
1149
+ else if (word === 'end') cases -= 1;
1150
+ else if (cases > 0) continue;
1151
+ else if (word === 'or') return [];
1152
+ else if (word === 'between') between = true;
1153
+ else if (word === 'and' && between) between = false;
1154
+ else if (word === 'and') {
1155
+ parts.push([start, index]);
1156
+ start = index + 1;
1157
+ }
1158
+ }
1159
+ parts.push([start, to]);
1160
+ return parts.flatMap(([start, end]) =>
1161
+ tokens[start]?.text === '(' &&
1162
+ closes.get(start) === end - 1 &&
1163
+ !['select', 'with', 'values'].includes(lowerWord(tokens[start + 1]) ?? '')
1164
+ ? conjuncts(start + 1, end - 1)
1165
+ : [[start, end]],
1166
+ );
1167
+ };
1168
+ const classify = (
1169
+ scope: string,
1170
+ start: number,
1171
+ end: number,
1172
+ join?: {
1173
+ readonly kind: string | undefined;
1174
+ readonly introduced: ReadonlySet<string>;
1175
+ },
1176
+ ): void => {
1177
+ const reversed = bindAt(start);
1178
+ const left = columnAt(reversed === undefined ? start : start + 2);
1179
+ if (left === undefined) return;
1180
+ if (reversed !== undefined) {
1181
+ const subject = scopeColumn(scope, left.qualifier, left.column);
1182
+ if (
1183
+ join === undefined &&
1184
+ equal(start + 1) &&
1185
+ left.next === end &&
1186
+ subject
1187
+ )
1188
+ binds.push({ ...subject, operator: 'equal', params: [reversed] });
1189
+ return;
1190
+ }
1191
+ const operator = left.next;
1192
+ const bind = bindAt(operator + 1);
1193
+ const list = tokens.slice(operator + 2, end - 1);
1194
+ const right = columnAt(operator + 1);
1195
+ if (
1196
+ join === undefined &&
1197
+ bind !== undefined &&
1198
+ operator + 2 === end &&
1199
+ (equal(operator) || lowerWord(tokens[operator]) === 'is')
1200
+ ) {
1201
+ const subject = scopeColumn(scope, left.qualifier, left.column);
1202
+ if (subject)
1203
+ binds.push({ ...subject, operator: 'equal', params: [bind] });
1204
+ } else if (
1205
+ join === undefined &&
1206
+ lowerWord(tokens[operator]) === 'in' &&
1207
+ closes.get(operator + 1) === end - 1 &&
1208
+ list.length % 2 === 1 &&
1209
+ list.every((token, index) =>
1210
+ index % 2 === 0 ? token.kind === 'bind' : token.text === ',',
1211
+ )
1212
+ ) {
1213
+ const subject = scopeColumn(scope, left.qualifier, left.column);
1214
+ const params = list.flatMap((token) =>
1215
+ token.kind === 'bind' ? [token.text.slice(1)] : [],
1216
+ );
1217
+ if (subject) binds.push({ ...subject, operator: 'in', params });
1218
+ } else if (
1219
+ equal(operator) &&
1220
+ right?.next === end &&
1221
+ left.qualifier !== undefined &&
1222
+ right.qualifier !== undefined
1223
+ ) {
1224
+ const l = scopeColumn(scope, left.qualifier, left.column);
1225
+ const r = scopeColumn(scope, right.qualifier, right.column);
1226
+ if (l === undefined || r === undefined) return;
1227
+ if (join?.kind !== 'left' && join?.kind !== 'right') {
1228
+ equalities.push({ target: l, source: r, symmetric: true });
1229
+ return;
1230
+ }
1231
+ // An outer join's ON constrains matched rows of its null-extended side
1232
+ // only; an equality with both operands on one side proves nothing.
1233
+ if (join.introduced.has(l.alias) === join.introduced.has(r.alias)) return;
1234
+ const [introduced, prior] = join.introduced.has(l.alias)
1235
+ ? [l, r]
1236
+ : [r, l];
1237
+ equalities.push(
1238
+ join.kind === 'left'
1239
+ ? { target: introduced, source: prior, symmetric: false }
1240
+ : { target: prior, source: introduced, symmetric: false },
1241
+ );
1242
+ }
1243
+ };
1244
+ const ranges = [
1245
+ { scope: 'main', from: 0, to: tokens.length },
1246
+ ...relations.cteScopes.map((cte) => ({
1247
+ scope: `cte:${cte.name}`,
1248
+ from: tokens.findIndex((token) => token.span.start.offset >= cte.start),
1249
+ to: tokens.findIndex((token) => token.span.start.offset >= cte.end),
1250
+ })),
1251
+ ];
1252
+ for (const range of ranges) {
1253
+ const own: number[] = [];
1254
+ for (let index = range.from; index < range.to; index += 1) {
1255
+ if (depths[index] === depths[range.from]) own.push(index);
1256
+ }
1257
+ const words = own.map((index) => lowerWord(tokens[index]) ?? '');
1258
+ if (words.some((w) => w === 'union' || w === 'intersect' || w === 'except'))
1259
+ continue;
1260
+ own.forEach((at, position) => {
1261
+ const word = words[position];
1262
+ if (word !== 'where' && word !== 'on') return;
1263
+ let next = position + 1;
1264
+ while (next < words.length && !CLAUSE_WORDS.has(words[next] as string))
1265
+ next += 1;
1266
+ const to = own[next] ?? range.to;
1267
+ if (word === 'where') {
1268
+ for (const [start, end] of conjuncts(at + 1, to))
1269
+ classify(range.scope, start, end);
1270
+ return;
1271
+ }
1272
+ if (
1273
+ tokens
1274
+ .slice(at + 1, to)
1275
+ .some((token) =>
1276
+ ['or', 'not', 'select', 'with'].includes(lowerWord(token) ?? ''),
1277
+ )
1278
+ )
1279
+ return;
1280
+ const join = words.lastIndexOf('join', position);
1281
+ if (join < 0) return;
1282
+ const kind =
1283
+ words[join - 1] === 'outer' ? words[join - 2] : words[join - 1];
1284
+ if (kind === 'full') return;
1285
+ // The relations between JOIN and ON, a parenthesized group included.
1286
+ const introduced = new Set(
1287
+ relations.tables
1288
+ .filter(
1289
+ (ref) =>
1290
+ ref.start >
1291
+ (tokens[own[join] as number] as SyqlToken).span.start.offset &&
1292
+ ref.start < (tokens[at] as SyqlToken).span.start.offset,
1293
+ )
1294
+ .map((ref) => ref.alias.toLowerCase()),
1295
+ );
1296
+ for (const [start, end] of conjuncts(at + 1, to))
1297
+ classify(range.scope, start, end, { kind, introduced });
1298
+ });
1299
+ }
1300
+ return { binds, equalities };
1301
+ }
1302
+
1065
1303
  // -- SELECT column → source resolution ---------------------------------------
1066
1304
  //
1067
1305
  // For each result column bun gives us (name + decltype), we resolve its origin
@@ -1224,95 +1462,9 @@ function applicationColumnType(column: IrColumn): IrColumnType {
1224
1462
  : column.type;
1225
1463
  }
1226
1464
 
1227
- function inferParamType(
1228
- paramName: string,
1229
- sql: string,
1230
- refs: readonly TableRef[],
1231
- ir: IrDocument,
1232
- ): IrColumnType | null {
1233
- const cleaned = stripCommentsAndStrings(sql);
1234
- const byName = new Map(ir.tables.map((t) => [t.name, t] as const));
1235
- const lookup = (
1236
- qualifier: string | undefined,
1237
- column: string,
1238
- ): IrColumnType | null => {
1239
- if (qualifier !== undefined) {
1240
- const ref = refs.find((r) => r.alias === qualifier);
1241
- const table = ref && byName.get(ref.table);
1242
- const resolved = table?.columns.find((c) => c.name === column);
1243
- return resolved === undefined ? null : applicationColumnType(resolved);
1244
- }
1245
- for (const ref of refs) {
1246
- const table = byName.get(ref.table);
1247
- const col = table?.columns.find((c) => c.name === column);
1248
- if (col !== undefined) return applicationColumnType(col);
1249
- }
1250
- return null;
1251
- };
1252
- // `col = :name`, `col >= :name`, `col <> :name`, `col LIKE :name`, etc.
1253
- const cmp = new RegExp(
1254
- `(?:(${IDENT})\\.)?(${IDENT})\\s*(?:=|==|!=|<>|<=|>=|<|>|\\bLIKE\\b|\\bIS\\b)\\s*:${paramName}\\b`,
1255
- 'i',
1256
- );
1257
- const cmpM = cmp.exec(cleaned);
1258
- if (cmpM !== null) {
1259
- const t = lookup(cmpM[1], cmpM[2] as string);
1260
- if (t !== null) return t;
1261
- }
1262
- // reversed: `:name = col`
1263
- const rev = new RegExp(
1264
- `:${paramName}\\b\\s*(?:=|==|!=|<>|<=|>=|<|>)\\s*(?:(${IDENT})\\.)?(${IDENT})`,
1265
- 'i',
1266
- );
1267
- const revM = rev.exec(cleaned);
1268
- if (revM !== null) {
1269
- const t = lookup(revM[1], revM[2] as string);
1270
- if (t !== null) return t;
1271
- }
1272
- // `col IN (…, :name, …)` — find the nearest `col IN (` before the param.
1273
- const inRe = new RegExp(
1274
- `(?:(${IDENT})\\.)?(${IDENT})\\s+IN\\s*\\(([^)]*:${paramName}\\b[^)]*)\\)`,
1275
- 'i',
1276
- );
1277
- const inM = inRe.exec(cleaned);
1278
- if (inM !== null) {
1279
- const t = lookup(inM[1], inM[2] as string);
1280
- if (t !== null) return t;
1281
- }
1282
- // `col BETWEEN :name AND …` / `col BETWEEN … AND :name` — both endpoints
1283
- // take the column's type (the §4 from+to group shape).
1284
- const btwLeft = new RegExp(
1285
- `(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+:${paramName}\\b`,
1286
- 'i',
1287
- );
1288
- const btwLeftM = btwLeft.exec(cleaned);
1289
- if (btwLeftM !== null) {
1290
- const t = lookup(btwLeftM[1], btwLeftM[2] as string);
1291
- if (t !== null) return t;
1292
- }
1293
- const btwRight = new RegExp(
1294
- `(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+\\S+\\s+AND\\s+:${paramName}\\b`,
1295
- 'i',
1296
- );
1297
- const btwRightM = btwRight.exec(cleaned);
1298
- if (btwRightM !== null) {
1299
- const t = lookup(btwRightM[1], btwRightM[2] as string);
1300
- if (t !== null) return t;
1301
- }
1302
- // `… LIKE <expr mentioning :name>` — a LIKE operand is TEXT, even inside
1303
- // a concatenation (`title like '%' || :q || '%'`, the search-fragment
1304
- // shape).
1305
- const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'i');
1306
- if (like.test(cleaned)) return 'string';
1307
- const match = new RegExp(`\\bMATCH\\b\\s*:${paramName}\\b`, 'i');
1308
- if (match.test(cleaned)) return 'string';
1309
- return null;
1310
- }
1311
-
1312
1465
  /**
1313
- * Return every revision-1 column/LIKE type constraint for one bind. Unlike
1314
- * `inferParamType` (the legacy first-match helper), SYQL uses the complete set
1315
- * so conflicting checked uses cannot be silently accepted.
1466
+ * Every column/LIKE/MATCH type constraint on one bind, in pattern order. A
1467
+ * `.sql` query takes the first; SYQL rejects conflicting evidence.
1316
1468
  */
1317
1469
  export function inferParamTypeEvidence(
1318
1470
  paramName: string,
@@ -1336,15 +1488,17 @@ export function inferParamTypeEvidence(
1336
1488
  if (type !== undefined) evidence.push(type);
1337
1489
  return;
1338
1490
  }
1339
- const matches = refs.flatMap((ref) => {
1340
- const table = byName.get(ref.table);
1341
- const item = table?.columns.find(
1342
- (candidate) => candidate.name === column,
1343
- );
1344
- const type = item === undefined ? undefined : applicationColumnType(item);
1345
- return type === undefined ? [] : [type];
1346
- });
1347
- if (matches.length === 1) evidence.push(matches[0] as IrColumnType);
1491
+ // An unqualified name read by several relations is evidence only when
1492
+ // every candidate column has the same type.
1493
+ const matches = new Set(
1494
+ refs.flatMap((ref) => {
1495
+ const item = byName
1496
+ .get(ref.table)
1497
+ ?.columns.find((candidate) => candidate.name === column);
1498
+ return item === undefined ? [] : [applicationColumnType(item)];
1499
+ }),
1500
+ );
1501
+ if (matches.size === 1) evidence.push(...matches);
1348
1502
  };
1349
1503
 
1350
1504
  const comparison = new RegExp(
@@ -1391,68 +1545,50 @@ export function inferParamTypeEvidence(
1391
1545
 
1392
1546
  // -- fallback column typing (computed expressions) ----------------------------
1393
1547
 
1394
- const AGG_RE = /\b(count|sum|total|avg|min|max)\s*\(/i;
1548
+ export const AGGREGATE_FUNCTIONS = new Set([
1549
+ 'avg',
1550
+ 'count',
1551
+ 'group_concat',
1552
+ 'max',
1553
+ 'min',
1554
+ 'sum',
1555
+ 'total',
1556
+ ]);
1395
1557
 
1396
- /** decltype-null column: the documented honest fallback. Aggregates and
1397
- * arithmetic → nullable number; everything else → nullable string. */
1398
- function fallbackColumnType(expr: string): IrColumnType {
1399
- if (AGG_RE.test(expr) || /[+\-*/]/.test(expr)) return 'float';
1400
- return 'string';
1558
+ /** True when `expr` calls an aggregate outside a subquery. `min`/`max` with
1559
+ * several arguments are scalar functions, and an OVER clause makes a window
1560
+ * function, which aggregates no rows. */
1561
+ function callsAggregate(expr: string): boolean {
1562
+ const { tokens, depths, parents, closes } = sqlStructure(expr);
1563
+ return tokens.some((token, index) => {
1564
+ const name = lowerWord(token) ?? '';
1565
+ const close = closes.get(index + 1);
1566
+ if (!AGGREGATE_FUNCTIONS.has(name) || close === undefined) return false;
1567
+ for (let open = parents[index] ?? -1; open >= 0; open = parents[open] ?? -1)
1568
+ if (lowerWord(tokens[open + 1]) === 'select') return false;
1569
+ let after = close + 1;
1570
+ if (lowerWord(tokens[after]) === 'filter')
1571
+ after = (closes.get(after + 1) ?? after) + 1;
1572
+ const scalar =
1573
+ (name === 'min' || name === 'max') &&
1574
+ tokens
1575
+ .slice(index + 2, close)
1576
+ .some(
1577
+ (arg, at) =>
1578
+ arg.text === ',' && depths[index + 2 + at] === depths[index + 2],
1579
+ );
1580
+ return !scalar && lowerWord(tokens[after]) !== 'over';
1581
+ });
1401
1582
  }
1402
1583
 
1403
1584
  function inferReactiveMetadata(
1404
1585
  sql: string,
1405
- refs: readonly TableRef[],
1586
+ relations: SqlRelations,
1406
1587
  ir: IrDocument,
1407
- params: readonly QueryParam[],
1408
1588
  columns: readonly QueryColumn[],
1409
1589
  ): QueryReactiveMetadata {
1410
- const conservative = /\b(?:UNION|EXCEPT|INTERSECT)\b/i.test(
1411
- stripCommentsAndStrings(sql),
1412
- );
1413
- const requiredAt = (index: number): boolean => {
1414
- const cleaned = stripCommentsAndStrings(sql);
1415
- const where = /\bWHERE\b/i.exec(cleaned);
1416
- if (where === null || index < where.index + where[0].length) return false;
1417
- const matchStack: number[] = [];
1418
- for (
1419
- let cursor = where.index + where[0].length;
1420
- cursor < index;
1421
- cursor += 1
1422
- ) {
1423
- if (cleaned[cursor] === '(') matchStack.push(cursor);
1424
- else if (cleaned[cursor] === ')') matchStack.pop();
1425
- }
1426
- const stack: number[] = [];
1427
- for (
1428
- let cursor = where.index + where[0].length;
1429
- cursor < cleaned.length;
1430
- cursor += 1
1431
- ) {
1432
- const char = cleaned[cursor];
1433
- if (char === '(') stack.push(cursor);
1434
- else if (char === ')') stack.pop();
1435
- const atBoundary =
1436
- cursor === 0 || !/[A-Za-z0-9_:]/.test(cleaned[cursor - 1] ?? '');
1437
- if (
1438
- cursor > index &&
1439
- atBoundary &&
1440
- /^(?:GROUP\s+BY|ORDER\s+BY|LIMIT|HAVING)\b/i.test(cleaned.slice(cursor))
1441
- ) {
1442
- break;
1443
- }
1444
- if (
1445
- atBoundary &&
1446
- /^OR\b/i.test(cleaned.slice(cursor)) &&
1447
- stack.length <= matchStack.length &&
1448
- stack.every((open, stackIndex) => matchStack[stackIndex] === open)
1449
- ) {
1450
- return false;
1451
- }
1452
- }
1453
- return true;
1454
- };
1455
- const byParam = new Map(params.map((param) => [param.name, param] as const));
1590
+ const refs = relations.tables;
1591
+ const proofs = scopeProofs(sql, ir).binds;
1456
1592
  const dependencies: Array<{
1457
1593
  table: string;
1458
1594
  scopes: QueryScopeBinding[];
@@ -1469,47 +1605,28 @@ function inferReactiveMetadata(
1469
1605
  ].sort()) {
1470
1606
  const table = ir.tables.find((candidate) => candidate.name === tableName);
1471
1607
  const tableRefs = refs.filter((ref) => ref.table === tableName);
1608
+ const ref = tableRefs.length === 1 ? tableRefs[0] : undefined;
1472
1609
  const scopes: QueryScopeBinding[] = [];
1473
- if (table !== undefined && tableRefs.length === 1 && !conservative) {
1474
- const qualifier = tableRefs[0]?.alias;
1610
+ if (table !== undefined && ref !== undefined) {
1475
1611
  for (const scope of table.scopes) {
1476
- const column = scope.column.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
1477
- const qualified =
1478
- qualifier === undefined
1479
- ? `(?<![A-Za-z0-9_.:])(?:${IDENT}\\.)?${column}\\b`
1480
- : `(?<![A-Za-z0-9_.:])(?:${qualifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.)?${column}\\b`;
1481
- const found: string[] = [];
1482
- const equality = new RegExp(
1483
- `${qualified}\\s*(?:=|==|\\bIS\\b)\\s*:(${IDENT})\\b|:(${IDENT})\\b\\s*(?:=|==)\\s*${qualified}`,
1484
- 'gi',
1485
- );
1486
- for (const match of sql.matchAll(equality)) {
1487
- if (!requiredAt(match.index)) continue;
1488
- const name = match[1] ?? match[2];
1489
- const param = name === undefined ? undefined : byParam.get(name);
1490
- if (param !== undefined) {
1491
- found.push(param.name);
1492
- }
1493
- }
1494
- const inList = new RegExp(`${qualified}\\s+IN\\s*\\(([^)]*)\\)`, 'gi');
1495
- for (const match of sql.matchAll(inList)) {
1496
- if (!requiredAt(match.index)) continue;
1497
- for (const paramMatch of (match[1] ?? '').matchAll(
1498
- /:([A-Za-z_][A-Za-z0-9_]*)/g,
1499
- )) {
1500
- const param = byParam.get(paramMatch[1] as string);
1501
- if (param !== undefined) {
1502
- found.push(param.name);
1503
- }
1504
- }
1505
- }
1506
- const unique = [...new Set(found)];
1507
- if (unique.length > 0) {
1612
+ const params = [
1613
+ ...new Set(
1614
+ proofs
1615
+ .filter(
1616
+ (proof) =>
1617
+ proof.scope === relations.scopeAt(ref.start) &&
1618
+ proof.alias === ref.alias.toLowerCase() &&
1619
+ proof.column === scope.column.toLowerCase(),
1620
+ )
1621
+ .flatMap((proof) => proof.params),
1622
+ ),
1623
+ ];
1624
+ if (params.length > 0) {
1508
1625
  scopes.push({
1509
1626
  table: tableName,
1510
1627
  variable: scope.variable,
1511
1628
  pattern: scope.pattern,
1512
- params: unique,
1629
+ params,
1513
1630
  });
1514
1631
  }
1515
1632
  }
@@ -1564,6 +1681,13 @@ export interface QueryDb {
1564
1681
  declaredTypes: readonly (string | null)[];
1565
1682
  paramsCount: number;
1566
1683
  };
1684
+ /** The `EXPLAIN QUERY PLAN` rows of `sql`. With `index`, a `CREATE INDEX`
1685
+ * statement, SQLite plans as if that index existed; the database keeps no
1686
+ * trace of it afterwards. */
1687
+ plan(
1688
+ sql: string,
1689
+ index?: string,
1690
+ ): readonly { id: number; parent: number; detail: string }[];
1567
1691
  }
1568
1692
 
1569
1693
  /** Synthesize the schema DDL from the IR (the reverse of the migration
@@ -1669,24 +1793,8 @@ export function lowerFtsSourceIds(sql: string, ir: IrDocument): string {
1669
1793
  );
1670
1794
  const relations = scanRelations(sql, ir);
1671
1795
  if (!relations.tables.some((ref) => ftsNames.has(ref.table))) return sql;
1672
- const tokens = lexSyqlSqlSource('query SQL', sql).filter(
1673
- (token) => !isSyqlTrivia(token) && token.kind !== 'eof',
1674
- );
1675
- const depths: number[] = [];
1676
- const closes = new Map<number, number>();
1677
- const stack: number[] = [];
1678
- tokens.forEach((token, index) => {
1679
- if (token.text === ')') {
1680
- const open = stack.pop();
1681
- if (open !== undefined) closes.set(open, index);
1682
- }
1683
- depths[index] = stack.length;
1684
- if (token.text === '(') stack.push(index);
1685
- });
1686
- const lower = (index: number): string | undefined => {
1687
- const token = tokens[index];
1688
- return token?.kind === 'identifier' ? token.text.toLowerCase() : undefined;
1689
- };
1796
+ const { tokens, depths, closes } = sqlStructure(sql);
1797
+ const lower = (index: number) => lowerWord(tokens[index]);
1690
1798
  // Every SELECT scope as an offset range; the outer statement spans all.
1691
1799
  const scopes = [
1692
1800
  { start: -1, end: sql.length + 1 },
@@ -1851,28 +1959,35 @@ export function analyzeStatement(
1851
1959
  ): AnalyzedQuery {
1852
1960
  const file = location;
1853
1961
  const commentParams = parseCommentParams(file, statementText);
1962
+ const acknowledgements = parseCommentAcknowledgements(file, statementText);
1854
1963
  const sourceSql = statementText.trim();
1855
1964
  if (sourceSql.length === 0) {
1856
1965
  throw new TypegenError(file, 'query file is empty');
1857
1966
  }
1858
1967
  // SELECT-only (the read tier). A `WITH` is allowed when its main statement
1859
1968
  // is a SELECT (SQLite also allows WITH … INSERT/UPDATE/DELETE — writes).
1860
- const firstKeyword = /^\s*([A-Za-z]+)/.exec(
1861
- stripCommentsAndStrings(statementText).trimStart(),
1862
- )?.[1];
1863
- const upperKeyword = firstKeyword?.toUpperCase();
1864
- if (upperKeyword === 'WITH') {
1865
- const main = mainVerbAfterWith(stripCommentsAndStrings(statementText));
1866
- if (main !== 'SELECT') {
1969
+ // CTE bodies sit inside parentheses and a bare keyword cannot name a CTE,
1970
+ // so the first depth-0 verb after `WITH` is the main verb.
1971
+ const statement = sqlStructure(statementText, file);
1972
+ const firstKeyword = lowerWord(statement.tokens[0]);
1973
+ if (firstKeyword === 'with') {
1974
+ const main = statement.tokens.find(
1975
+ (token, index) =>
1976
+ statement.depths[index] === 0 &&
1977
+ ['select', 'values', 'insert', 'update', 'delete', 'replace'].includes(
1978
+ lowerWord(token) ?? '',
1979
+ ),
1980
+ );
1981
+ if (lowerWord(main) !== 'select') {
1867
1982
  throw new TypegenError(
1868
1983
  file,
1869
- `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).`,
1984
+ `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).`,
1870
1985
  );
1871
1986
  }
1872
- } else if (upperKeyword !== 'SELECT') {
1987
+ } else if (firstKeyword !== 'select') {
1873
1988
  throw new TypegenError(
1874
1989
  file,
1875
- `named queries are SELECT-only (the read tier); found ${JSON.stringify(firstKeyword ?? '')}. Writes go through mutate() (SPEC §7.1).`,
1990
+ `named queries are SELECT-only (the read tier); found ${JSON.stringify(statement.tokens[0]?.text ?? '')}. Writes go through mutate() (SPEC §7.1).`,
1876
1991
  );
1877
1992
  }
1878
1993
 
@@ -1979,6 +2094,53 @@ export function analyzeStatement(
1979
2094
  : { ...source, nullableByJoin: source.nullableByJoin || cteRef.nullable };
1980
2095
  };
1981
2096
  const items = splitSelectList(sql);
2097
+ // A bare column of a SELECT that aggregates without GROUP BY reads NULL
2098
+ // when no row matches, and a compound SELECT returns the rows of every
2099
+ // branch, so a column is nullable when any branch can yield NULL there.
2100
+ const outer = sqlStructure(sql);
2101
+ const cuts = outer.tokens.flatMap((token, index) =>
2102
+ outer.depths[index] === 0 &&
2103
+ ['union', 'intersect', 'except'].includes(lowerWord(token) ?? '')
2104
+ ? [token.span]
2105
+ : [],
2106
+ );
2107
+ const branches = [0, ...cuts.map((span) => span.end.offset)].map(
2108
+ (start, index) => {
2109
+ const end = cuts[index]?.start.offset ?? sql.length;
2110
+ const branchItems = splitSelectList(sql.slice(start, end));
2111
+ const grouped = outer.tokens.some(
2112
+ (token, at) =>
2113
+ outer.depths[at] === 0 &&
2114
+ token.span.start.offset >= start &&
2115
+ token.span.start.offset < end &&
2116
+ lowerWord(token) === 'group',
2117
+ );
2118
+ const aggregated =
2119
+ !grouped &&
2120
+ (branchItems?.some((item) => callsAggregate(item.expr)) ?? false);
2121
+ return { start, end, items: branchItems, aggregated };
2122
+ },
2123
+ );
2124
+ const branchNullable = (index: number): boolean =>
2125
+ branches.some((branch, position) => {
2126
+ if (branch.aggregated) return true;
2127
+ if (position === 0) return false;
2128
+ const item = branch.items?.[index];
2129
+ const source =
2130
+ item === undefined
2131
+ ? null
2132
+ : resolveSource(
2133
+ item,
2134
+ scoped.tables.filter(
2135
+ (ref) =>
2136
+ scoped.scopeAt(ref.start) === 'main' &&
2137
+ ref.start >= branch.start &&
2138
+ ref.start < branch.end,
2139
+ ),
2140
+ ir,
2141
+ );
2142
+ return source === null || source.column.nullable || source.nullableByJoin;
2143
+ });
1982
2144
  const columns: QueryColumn[] = described.columnNames.map((colName, index) => {
1983
2145
  const decl = described.declaredTypes[index];
1984
2146
  const item = items?.[index];
@@ -1998,7 +2160,7 @@ export function analyzeStatement(
1998
2160
  name: sqlName,
1999
2161
  langName,
2000
2162
  type: 'integer',
2001
- nullable: syncVersionNullable,
2163
+ nullable: syncVersionNullable || branchNullable(index),
2002
2164
  fidelity: 'exact',
2003
2165
  };
2004
2166
  }
@@ -2006,27 +2168,58 @@ export function analyzeStatement(
2006
2168
  // Exact: app-facing queries read the decrypted local mirror. Encrypted
2007
2169
  // columns therefore expose their pre-wire declaredType, while the schema
2008
2170
  // IR and mutation codec continue to carry the bytes wire type.
2009
- const sourceType =
2010
- source.column.encrypted === true &&
2011
- source.column.declaredType !== undefined
2012
- ? source.column.declaredType
2013
- : source.column.type;
2014
2171
  return {
2015
2172
  name: sqlName,
2016
2173
  langName,
2017
- type: sourceType,
2018
- nullable: source.column.nullable || source.nullableByJoin,
2174
+ type: applicationColumnType(source.column),
2175
+ nullable:
2176
+ source.column.nullable ||
2177
+ source.nullableByJoin ||
2178
+ branchNullable(index),
2019
2179
  fidelity: 'exact',
2020
2180
  origin: { table: source.table, column: source.column.name },
2021
2181
  };
2022
2182
  }
2023
- // Fallback: decltype affinity if present, else the expr-shape fallback.
2024
- const mapped =
2025
- decl !== null && decl !== undefined
2026
- ? DECLTYPE_MAP[decl.toUpperCase()]
2183
+ // Computed column (SYQL §14.1): the type is the decltype SQLite reports,
2184
+ // else the target of a whole-expression CAST, else integer for a
2185
+ // whole-expression count(); anything else is refused.
2186
+ const { tokens, depths, closes } = sqlStructure(item?.expr ?? '');
2187
+ const whole =
2188
+ tokens[1]?.text === '(' && closes.get(1) === tokens.length - 1
2189
+ ? lowerWord(tokens[0])
2027
2190
  : undefined;
2191
+ const asAt = tokens.findLastIndex(
2192
+ (token, at) => depths[at] === 1 && lowerWord(token) === 'as',
2193
+ );
2194
+ const castType = tokens
2195
+ .flatMap((token, at) =>
2196
+ at > asAt && depths[at] === 1 && token.kind === 'identifier'
2197
+ ? [token.text.toUpperCase()]
2198
+ : [],
2199
+ )
2200
+ .join(' ');
2028
2201
  const type =
2029
- mapped ?? (item !== undefined ? fallbackColumnType(item.expr) : 'string');
2202
+ (decl !== null && decl !== undefined
2203
+ ? DECLTYPE_MAP[decl.toUpperCase()]
2204
+ : undefined) ??
2205
+ // SQLite gives the other mapped names NUMERIC or BLOB affinity, which
2206
+ // can change the value's storage class.
2207
+ (whole === 'cast' &&
2208
+ asAt > 0 &&
2209
+ /^(INTEGER|INT|BIGINT|SMALLINT|TEXT|REAL|FLOAT|DOUBLE|BLOB|BOOLEAN|BOOL)$/.test(
2210
+ castType,
2211
+ )
2212
+ ? DECLTYPE_MAP[castType]
2213
+ : undefined) ??
2214
+ (whole === 'count' ? 'integer' : undefined);
2215
+ if (type === undefined) {
2216
+ throw new TypegenError(
2217
+ file,
2218
+ 'computed result column has no declared type; wrap the expression in CAST(... AS <type>)',
2219
+ 'typegen.computed_column_type',
2220
+ { query: name, column: sqlName },
2221
+ );
2222
+ }
2030
2223
  return {
2031
2224
  name: sqlName,
2032
2225
  langName,
@@ -2065,8 +2258,8 @@ export function analyzeStatement(
2065
2258
  if (commented !== undefined) {
2066
2259
  return { name: paramName, langName, type: commented, source: 'comment' };
2067
2260
  }
2068
- const inferred = inferParamType(paramName, sql, refs, ir);
2069
- if (inferred !== null) {
2261
+ const inferred = inferParamTypeEvidence(paramName, sql, refs, ir)[0];
2262
+ if (inferred !== undefined) {
2070
2263
  return { name: paramName, langName, type: inferred, source: 'inferred' };
2071
2264
  }
2072
2265
  throw new TypegenError(
@@ -2084,21 +2277,43 @@ export function analyzeStatement(
2084
2277
  }
2085
2278
  }
2086
2279
 
2087
- const reactive = inferReactiveMetadata(sql, refs, ir, params, columns);
2280
+ validateQueryIdentifier(name, naming.targets, file, 'query name');
2281
+ for (const column of columns) {
2282
+ validateQueryIdentifier(
2283
+ column.langName,
2284
+ naming.targets,
2285
+ file,
2286
+ 'result column',
2287
+ );
2288
+ }
2289
+ for (const param of params) {
2290
+ if (!internalParams.has(param.name))
2291
+ validateQueryIdentifier(param.langName, naming.targets, file, 'param');
2292
+ }
2293
+
2294
+ const reactive = inferReactiveMetadata(sql, scoped, ir, columns);
2088
2295
 
2296
+ // The emitted statement is what SQLite checks: the positional form, with
2297
+ // FTS source-id lowering applied, must prepare to the same result columns
2298
+ // and take exactly one value per distinct param.
2089
2299
  const physical = lowerFtsSourceIds(sql, ir);
2090
- if (physical !== sql) {
2091
- const lowered = analyze(physical);
2092
- if (
2093
- lowered.paramsCount !== described.paramsCount ||
2094
- lowered.columnNames.length !== described.columnNames.length ||
2095
- lowered.columnNames.some((n, i) => n !== described.columnNames[i])
2096
- ) {
2097
- throw new TypegenError(
2098
- file,
2099
- `internal: FTS source-id lowering changed the result columns [${described.columnNames.join(', ')}] to [${lowered.columnNames.join(', ')}]`,
2100
- );
2101
- }
2300
+ const positionalSql = toPositionalSql(physical);
2301
+ const emitted = analyze(positionalSql);
2302
+ if (
2303
+ emitted.paramsCount !== params.length ||
2304
+ emitted.columnNames.join('\0') !== described.columnNames.join('\0')
2305
+ ) {
2306
+ throw new TypegenError(
2307
+ file,
2308
+ 'internal: the emitted positional SQL does not prepare to the analyzed columns and params',
2309
+ 'typegen.emitted_sql_mismatch',
2310
+ {
2311
+ columns: described.columnNames,
2312
+ emittedColumns: emitted.columnNames,
2313
+ params: params.length,
2314
+ emittedParams: emitted.paramsCount,
2315
+ },
2316
+ );
2102
2317
  }
2103
2318
 
2104
2319
  return {
@@ -2106,21 +2321,18 @@ export function analyzeStatement(
2106
2321
  file,
2107
2322
  sourceSql,
2108
2323
  sql: physical,
2109
- positionalSql: toPositionalSql(physical),
2110
- relations: scanTableRefs(toPositionalSql(physical), ir, true).map(
2111
- (ref) => ({
2112
- table: ref.table,
2113
- start: ref.start,
2114
- end: ref.end,
2115
- ...(ref.explicitAlias === undefined
2116
- ? {}
2117
- : { alias: ref.explicitAlias }),
2118
- }),
2119
- ),
2324
+ positionalSql,
2325
+ relations: scanTableRefs(positionalSql, ir, true).map((ref) => ({
2326
+ table: ref.table,
2327
+ start: ref.start,
2328
+ end: ref.end,
2329
+ ...(ref.explicitAlias === undefined ? {} : { alias: ref.explicitAlias }),
2330
+ })),
2120
2331
  params,
2121
2332
  columns,
2122
2333
  tables,
2123
2334
  reactive,
2335
+ acknowledgements,
2124
2336
  };
2125
2337
  }
2126
2338
 
@@ -2142,7 +2354,7 @@ export function analyzeQueryFile(
2142
2354
  db: QueryDb,
2143
2355
  naming: QueryNamingOptions = DEFAULT_NAMING,
2144
2356
  ): AnalyzedQuery[] {
2145
- const statements = splitStatements(content);
2357
+ const statements = splitStatements(content, relPath);
2146
2358
  if (statements.length === 0) {
2147
2359
  throw new TypegenError(relPath, 'query file is empty');
2148
2360
  }
@@ -2174,7 +2386,7 @@ export function analyzeQuery(
2174
2386
  db: QueryDb,
2175
2387
  naming: QueryNamingOptions = DEFAULT_NAMING,
2176
2388
  ): AnalyzedQuery {
2177
- const statements = splitStatements(raw);
2389
+ const statements = splitStatements(raw, file);
2178
2390
  if (statements.length > 1) {
2179
2391
  throw new TypegenError(
2180
2392
  file,
@@ -2184,3 +2396,153 @@ export function analyzeQuery(
2184
2396
  const results = analyzeQueryFile(file, raw, ir, db, naming);
2185
2397
  return results[0] as AnalyzedQuery;
2186
2398
  }
2399
+
2400
+ /**
2401
+ * The query plan check (`docs/SYQL.md` §14.5): plan every physical statement
2402
+ * against the schema database and fail on the first finding the query does
2403
+ * not acknowledge, then on the first acknowledgement that matches no finding.
2404
+ */
2405
+ export function checkQueryPlan(
2406
+ query: AnalyzedQuery,
2407
+ ir: IrDocument,
2408
+ db: QueryDb,
2409
+ ): void {
2410
+ const findings: {
2411
+ readonly finding: QueryPlanFinding;
2412
+ readonly table?: string;
2413
+ readonly details: Readonly<Record<string, unknown>>;
2414
+ }[] = [];
2415
+ const tables = new Map(ir.tables.map((table) => [table.name, table]));
2416
+ const statements = query.syql?.plan.statements ?? [query];
2417
+ statements.forEach(({ positionalSql: sql, relations }, statement) => {
2418
+ const rows = db.plan(sql);
2419
+ const plan = rows.map((row) => row.detail);
2420
+ const scans = (details: readonly string[]): number =>
2421
+ details.filter(
2422
+ (detail) =>
2423
+ detail.startsWith('SCAN ') && !detail.includes(' VIRTUAL TABLE'),
2424
+ ).length;
2425
+ // A plan names a relation by its alias, or by its table when unaliased.
2426
+ const tableOf = (name: string): string =>
2427
+ relations.find((relation) => (relation.alias ?? relation.table) === name)
2428
+ ?.table ?? name;
2429
+ const context = { query: query.name, file: query.file, statement, sql };
2430
+ for (const detail of plan) {
2431
+ const automatic =
2432
+ /^SEARCH (\S+) USING AUTOMATIC (?:PARTIAL )?(?:COVERING )?INDEX \((.*)\)/.exec(
2433
+ detail,
2434
+ );
2435
+ if (automatic === null) continue;
2436
+ const table = tableOf(automatic[1] as string);
2437
+ findings.push({
2438
+ finding: 'automatic_index',
2439
+ table,
2440
+ details: {
2441
+ ...context,
2442
+ table,
2443
+ columns: [...(automatic[2] as string).matchAll(/(\w+)[=<>]/g)].map(
2444
+ (key) => key[1],
2445
+ ),
2446
+ plan,
2447
+ },
2448
+ });
2449
+ }
2450
+ const scanCount = scans(plan);
2451
+ if (scanCount > 0) {
2452
+ for (const table of [
2453
+ ...new Set(relations.map((relation) => relation.table)),
2454
+ ]) {
2455
+ const columns = (tables.get(table)?.columns ?? [])
2456
+ .map((column) => column.name)
2457
+ .filter(
2458
+ (column) =>
2459
+ scans(
2460
+ db
2461
+ .plan(
2462
+ sql,
2463
+ `CREATE INDEX "__syncular_plan_probe" ON "${table}" ("${column}")`,
2464
+ )
2465
+ .map((row) => row.detail),
2466
+ ) < scanCount,
2467
+ );
2468
+ if (columns.length > 0) {
2469
+ findings.push({
2470
+ finding: 'scan',
2471
+ table,
2472
+ details: { ...context, table, columns, plan },
2473
+ });
2474
+ }
2475
+ }
2476
+ }
2477
+ const { tokens, depths } = sqlStructure(sql);
2478
+ const bounded = tokens.some(
2479
+ (token, index) =>
2480
+ depths[index] === 0 &&
2481
+ ['where', 'limit'].includes(lowerWord(token) ?? ''),
2482
+ );
2483
+ const topScan = rows.find(
2484
+ (row) =>
2485
+ row.parent === 0 &&
2486
+ scans([row.detail]) === 1 &&
2487
+ tables.has(tableOf(row.detail.split(' ')[1] as string)),
2488
+ );
2489
+ if (!bounded && topScan !== undefined) {
2490
+ const table = tableOf(topScan.detail.split(' ')[1] as string);
2491
+ findings.push({
2492
+ finding: 'unbounded',
2493
+ table,
2494
+ details: { ...context, table, plan },
2495
+ });
2496
+ }
2497
+ });
2498
+ const dependencies = [
2499
+ ...new Set(query.reactive.dependencies.map(({ table }) => table)),
2500
+ ].sort();
2501
+ if (dependencies.length > 4) {
2502
+ findings.push({
2503
+ finding: 'many_tables',
2504
+ details: { query: query.name, file: query.file, tables: dependencies },
2505
+ });
2506
+ }
2507
+
2508
+ const messages: Record<QueryPlanFinding, string> = {
2509
+ 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',
2510
+ automatic_index:
2511
+ 'the query plan builds an automatic index on every run; declare an index on the listed columns or acknowledge the finding',
2512
+ unbounded:
2513
+ 'the query reads every row of a table, with no WHERE and no LIMIT; bound the query or acknowledge the finding',
2514
+ many_tables:
2515
+ 'the query reads more than four tables, and a change to any of them re-runs it; split the query or acknowledge the finding',
2516
+ };
2517
+ const acknowledged = (
2518
+ acknowledgement: QueryAcknowledgement,
2519
+ found: (typeof findings)[number],
2520
+ ): boolean =>
2521
+ acknowledgement.finding === found.finding &&
2522
+ acknowledgement.table === found.table;
2523
+ for (const found of findings) {
2524
+ if (!query.acknowledgements.some((ack) => acknowledged(ack, found))) {
2525
+ throw new TypegenError(
2526
+ query.file,
2527
+ messages[found.finding],
2528
+ `typegen.query_${found.finding}`,
2529
+ found.details,
2530
+ );
2531
+ }
2532
+ }
2533
+ for (const ack of query.acknowledgements) {
2534
+ if (!findings.some((found) => acknowledged(ack, found))) {
2535
+ throw new TypegenError(
2536
+ query.file,
2537
+ 'the query plan acknowledgement matches no finding of its query; remove it',
2538
+ 'typegen.query_acknowledgement_unused',
2539
+ {
2540
+ query: query.name,
2541
+ file: query.file,
2542
+ finding: ack.finding,
2543
+ table: ack.table ?? null,
2544
+ },
2545
+ );
2546
+ }
2547
+ }
2548
+ }