@syncular/typegen 0.59.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 (47) hide show
  1. package/README.md +53 -18
  2. package/dist/emit-dart.js +7 -18
  3. package/dist/emit-kotlin.d.ts +1 -1
  4. package/dist/emit-kotlin.js +9 -20
  5. package/dist/emit-queries-rust.js +18 -14
  6. package/dist/emit-queries.js +19 -23
  7. package/dist/emit-swift.d.ts +1 -1
  8. package/dist/emit-swift.js +9 -20
  9. package/dist/emit.d.ts +2 -2
  10. package/dist/emit.js +9 -20
  11. package/dist/fmt.js +11 -2
  12. package/dist/generate.js +31 -26
  13. package/dist/init.js +4 -5
  14. package/dist/ir.d.ts +3 -2
  15. package/dist/ir.js +1 -2
  16. package/dist/lsp.js +6 -1
  17. package/dist/manifest.d.ts +1 -2
  18. package/dist/manifest.js +13 -12
  19. package/dist/query.d.ts +40 -0
  20. package/dist/query.js +159 -0
  21. package/dist/syql-ast.d.ts +2 -0
  22. package/dist/syql-ast.js +7 -1
  23. package/dist/syql-browser.js +7 -6
  24. package/dist/syql-diagnostics.d.ts +1 -0
  25. package/dist/syql-diagnostics.js +1 -0
  26. package/dist/syql-lowering.js +1 -0
  27. package/dist/syql-parser.d.ts +4 -1
  28. package/dist/syql-parser.js +42 -5
  29. package/package.json +3 -3
  30. package/src/emit-dart.ts +11 -22
  31. package/src/emit-kotlin.ts +13 -26
  32. package/src/emit-queries-rust.ts +22 -19
  33. package/src/emit-queries.ts +23 -38
  34. package/src/emit-swift.ts +15 -24
  35. package/src/emit.ts +15 -22
  36. package/src/fmt.ts +10 -2
  37. package/src/generate.ts +44 -36
  38. package/src/init.ts +4 -5
  39. package/src/ir.ts +4 -4
  40. package/src/lsp.ts +11 -4
  41. package/src/manifest.ts +22 -18
  42. package/src/query.ts +251 -0
  43. package/src/syql-ast.ts +9 -0
  44. package/src/syql-browser.ts +8 -7
  45. package/src/syql-diagnostics.ts +2 -0
  46. package/src/syql-lowering.ts +1 -0
  47. package/src/syql-parser.ts +73 -8
package/src/manifest.ts CHANGED
@@ -14,8 +14,8 @@
14
14
  * "dart": "./lib/syncular.generated.dart" },
15
15
  * "schemaVersions": [{ "version": 1, "through": "0001_initial" }],
16
16
  * "tables": [{ "name": "tasks", "scopes": ["project:{project_id}"] }],
17
- * "subscriptions": [{ "name": "projectTasks", "table": "tasks",
18
- * "scopes": { "project_id": ["{projectId}"] } }],
17
+ * "subscriptions": [{ "name": "projectTasks",
18
+ * "scopes": { "project_id": "{projectId}" } }],
19
19
  * "extensions": {}
20
20
  * }
21
21
  * ```
@@ -24,8 +24,10 @@
24
24
  * - `schemaVersions` is the §1.5 version history: strictly increasing
25
25
  * versions, each naming the last migration it includes (`through`); the
26
26
  * final entry must cover the final migration.
27
- * - Subscription scope values are literals or whole-value `{param}`
28
- * placeholders (partial templates are unsupported).
27
+ * - A subscription is a unit template (SPEC §4.1): one literal or
28
+ * whole-value `{param}` placeholder per scope variable (partial templates
29
+ * are unsupported), no table. The unit covers every table declaring all of
30
+ * its variables; a template that covers no table is an error.
29
31
  * - `output.ir` / `output.module` are the always-emitted TS defaults;
30
32
  * `output.queryIr` opts into the deterministic analyzed-query document.
31
33
  * `output.swift` / `output.kotlin` / `output.dart` are OPT-IN native schema
@@ -68,8 +70,7 @@ export interface ManifestTable {
68
70
 
69
71
  export interface ManifestSubscription {
70
72
  readonly name: string;
71
- readonly table: string;
72
- readonly scopes: Readonly<Record<string, readonly string[]>>;
73
+ readonly scopes: Readonly<Record<string, string>>;
73
74
  }
74
75
 
75
76
  export interface ManifestSchemaVersion {
@@ -332,30 +333,33 @@ function parseSubscription(
332
333
  ): ManifestSubscription {
333
334
  const context = `subscriptions[${index}]`;
334
335
  const obj = asObject(value, context);
335
- rejectUnknownKeys(obj, ['name', 'table', 'scopes'], context);
336
336
  const name = asString(obj.name, `${context}.name`);
337
337
  if (!IDENTIFIER_RE.test(name)) {
338
338
  fail(
339
339
  `subscription ${JSON.stringify(name)}: name must be a valid identifier`,
340
340
  );
341
341
  }
342
- const table = asString(obj.table, `subscription ${name}: table`);
343
342
  const scopesObj = asObject(obj.scopes, `subscription ${name}: scopes`);
344
- const scopes: Record<string, readonly string[]> = {};
345
- for (const [variable, values] of Object.entries(scopesObj)) {
346
- if (!Array.isArray(values) || values.length === 0) {
347
- fail(
348
- `subscription ${name}: scopes.${variable} must be a non-empty array`,
349
- );
350
- }
351
- scopes[variable] = values.map((v, i) =>
352
- asString(v, `subscription ${name}: scopes.${variable}[${i}]`),
343
+ if ('table' in obj || Object.values(scopesObj).some(Array.isArray)) {
344
+ throw new TypegenError(
345
+ SOURCE,
346
+ 'a subscription is a unit template { "name", "scopes": { "<variable>": "<value or {param}>" } } with one value per scope variable and no table (SPEC §4.1); several values are several templates',
347
+ 'typegen.subscription_legacy_shape',
348
+ { subscription: name },
349
+ );
350
+ }
351
+ rejectUnknownKeys(obj, ['name', 'scopes'], context);
352
+ const scopes: Record<string, string> = {};
353
+ for (const [variable, scope] of Object.entries(scopesObj)) {
354
+ scopes[variable] = asString(
355
+ scope,
356
+ `subscription ${name}: scopes.${variable}`,
353
357
  );
354
358
  }
355
359
  if (Object.keys(scopes).length === 0) {
356
360
  fail(`subscription ${name}: scopes must not be empty`);
357
361
  }
358
- return { name, table, scopes };
362
+ return { name, scopes };
359
363
  }
360
364
 
361
365
  function parseSchemaVersion(
package/src/query.ts CHANGED
@@ -144,6 +144,38 @@ export interface QueryCoverageBinding {
144
144
  }[];
145
145
  }
146
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
+
147
179
  export interface QueryReactiveMetadata {
148
180
  readonly dependencies: readonly {
149
181
  readonly table: string;
@@ -282,6 +314,23 @@ export interface QueryRelation {
282
314
  readonly alias?: string;
283
315
  }
284
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
+
285
334
  export interface AnalyzedQuery {
286
335
  /** camelCase function name (path-derived, or a `-- name:` override). */
287
336
  readonly name: string;
@@ -307,6 +356,8 @@ export interface AnalyzedQuery {
307
356
  /** Revision-1 frontend/public-input and physical execution contract. When
308
357
  * present, emitters use this instead of treating `params` as the API. */
309
358
  readonly syql?: QuerySyqlMetadata;
359
+ /** Plan findings the author acknowledged on the statement. */
360
+ readonly acknowledgements: readonly QueryAcknowledgement[];
310
361
  }
311
362
 
312
363
  /** The public SYQL input an emitter binds by name. */
@@ -536,6 +587,47 @@ function parseCommentParams(file: string, raw: string): CommentParam[] {
536
587
  return out;
537
588
  }
538
589
 
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
+ );
621
+ }
622
+ out.push({
623
+ finding,
624
+ ...(table === undefined ? {} : { table }),
625
+ reason: match[2] as string,
626
+ });
627
+ }
628
+ return out;
629
+ }
630
+
539
631
  /** Blank comments and string/blob literals with spaces (newlines kept), so
540
632
  * offset-preserving text scans never read inside them. */
541
633
  export function stripCommentsAndStrings(sql: string): string {
@@ -1589,6 +1681,13 @@ export interface QueryDb {
1589
1681
  declaredTypes: readonly (string | null)[];
1590
1682
  paramsCount: number;
1591
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 }[];
1592
1691
  }
1593
1692
 
1594
1693
  /** Synthesize the schema DDL from the IR (the reverse of the migration
@@ -1860,6 +1959,7 @@ export function analyzeStatement(
1860
1959
  ): AnalyzedQuery {
1861
1960
  const file = location;
1862
1961
  const commentParams = parseCommentParams(file, statementText);
1962
+ const acknowledgements = parseCommentAcknowledgements(file, statementText);
1863
1963
  const sourceSql = statementText.trim();
1864
1964
  if (sourceSql.length === 0) {
1865
1965
  throw new TypegenError(file, 'query file is empty');
@@ -2232,6 +2332,7 @@ export function analyzeStatement(
2232
2332
  columns,
2233
2333
  tables,
2234
2334
  reactive,
2335
+ acknowledgements,
2235
2336
  };
2236
2337
  }
2237
2338
 
@@ -2295,3 +2396,153 @@ export function analyzeQuery(
2295
2396
  const results = analyzeQueryFile(file, raw, ir, db, naming);
2296
2397
  return results[0] as AnalyzedQuery;
2297
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
+ }
package/src/syql-ast.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  /** Stable, span-free semantic AST used by revision-1 conformance fixtures. */
2
+ import type { QueryAcknowledgement } from './query';
2
3
  import { isSyqlTrivia, type SyqlToken } from './syql-lexer';
3
4
  import type {
4
5
  SyqlDeclaration,
@@ -99,6 +100,7 @@ export type SyqlSemanticDeclaration =
99
100
  readonly defaultSize: number;
100
101
  readonly maxSize: number;
101
102
  };
103
+ readonly acknowledgements?: readonly QueryAcknowledgement[];
102
104
  };
103
105
 
104
106
  export interface SyqlSemanticFile {
@@ -261,6 +263,13 @@ function semanticDeclaration(
261
263
  maxSize: declaration.limit.maxSize,
262
264
  },
263
265
  }),
266
+ ...(declaration.acknowledgements.length === 0
267
+ ? {}
268
+ : {
269
+ acknowledgements: declaration.acknowledgements.map((ack) => ({
270
+ ...ack,
271
+ })),
272
+ }),
264
273
  };
265
274
  }
266
275
 
@@ -9,6 +9,7 @@
9
9
  import { formatSyql } from './fmt';
10
10
  import type { IrDocument } from './ir';
11
11
  import {
12
+ checkQueryPlan,
12
13
  type QueryBackend,
13
14
  type QueryDb,
14
15
  type QueryNamingOptions,
@@ -65,13 +66,13 @@ export function compileSyqlSource(
65
66
  const file = options.file ?? SYQL_BROWSER_DEFAULT_FILE;
66
67
  const semantic = analyzeSyqlSemantics(singleFileGraph(file, source));
67
68
  const validated = validateSyqlProgram(semantic, ir, db, options.naming);
68
- return {
69
- queries: validated.queries.map((query) =>
70
- lowerSyqlQuery(query, ir, db, options.naming, {
71
- ...(options.backend === undefined ? {} : { backend: options.backend }),
72
- }),
73
- ),
74
- };
69
+ const queries = validated.queries.map((query) =>
70
+ lowerSyqlQuery(query, ir, db, options.naming, {
71
+ ...(options.backend === undefined ? {} : { backend: options.backend }),
72
+ }),
73
+ );
74
+ for (const query of queries) checkQueryPlan(query.analysis, ir, db);
75
+ return { queries };
75
76
  }
76
77
 
77
78
  /** Format one virtual source file with the canonical SYQL formatter. */
@@ -58,6 +58,8 @@ export const SYQL_DIAGNOSTIC_REMEDIES = {
58
58
  'Rewrite the parameter using a supported value, optional, range, group, sort, or limit form.',
59
59
  SYQL2012_INVALID_QUERY_BODY:
60
60
  'Rewrite the query body using the clause order and forms defined by the SYQL grammar.',
61
+ SYQL2013_INVALID_ACKNOWLEDGEMENT:
62
+ "Write the acknowledgement as allow <finding> <table> '<reason>' directly above a query, once per finding.",
61
63
  SYQL3001_EXPECTED_EMBEDDED_TOKEN:
62
64
  'Insert the required token in the embedded SQL construct.',
63
65
  SYQL3002_INVALID_BIND:
@@ -668,6 +668,7 @@ export function lowerSyqlQuery(
668
668
  file: logical.module.file,
669
669
  reactive: validated.reactive,
670
670
  syql: metadata,
671
+ acknowledgements: logical.declaration.acknowledgements,
671
672
  };
672
673
  return {
673
674
  validated,
@@ -6,6 +6,7 @@ import {
6
6
  type SyqlSourceSpan,
7
7
  type SyqlToken,
8
8
  } from './syql-lexer';
9
+ import { QUERY_PLAN_FINDINGS, type QueryAcknowledgement } from './query';
9
10
  import {
10
11
  parseSyqlEmbeddedTemplate,
11
12
  type SyqlEmbeddedTemplate,
@@ -151,6 +152,8 @@ export interface SyqlQueryDeclaration {
151
152
  readonly statement: SyqlTemplate;
152
153
  readonly sort?: SyqlSortSection;
153
154
  readonly limit?: SyqlLimitDeclaration;
155
+ /** Query plan findings acknowledged before the declaration (§14.5). */
156
+ readonly acknowledgements: readonly QueryAcknowledgement[];
154
157
  readonly span: SyqlSourceSpan;
155
158
  readonly nameSpan: SyqlSourceSpan;
156
159
  }
@@ -181,7 +184,8 @@ export type SyqlParseErrorCode =
181
184
  | 'SYQL2009_INVALID_INTEGER'
182
185
  | 'SYQL2010_INVALID_PAGE_RANGE'
183
186
  | 'SYQL2011_INVALID_PARAMETER'
184
- | 'SYQL2012_INVALID_QUERY_BODY';
187
+ | 'SYQL2012_INVALID_QUERY_BODY'
188
+ | 'SYQL2013_INVALID_ACKNOWLEDGEMENT';
185
189
 
186
190
  const CAMEL_IDENT_RE = /^[a-z][A-Za-z0-9]*$/;
187
191
  const INTEGER_LITERAL_RE = /^(?:0|[1-9][0-9]*)$/;
@@ -298,7 +302,9 @@ class Parser {
298
302
  }
299
303
 
300
304
  sawDeclaration = true;
301
- if (keyword.text === 'predicate') {
305
+ const acknowledgements = this.#parseAcknowledgements();
306
+ const next = this.#peek();
307
+ if (acknowledgements.length === 0 && next.text === 'predicate') {
302
308
  const declaration = this.#parsePredicate();
303
309
  this.#claimName(
304
310
  fileNames,
@@ -308,8 +314,11 @@ class Parser {
308
314
  );
309
315
  declarations.push(declaration);
310
316
  predicates.push(declaration);
311
- } else if (keyword.text === 'query' || keyword.text === 'sync') {
312
- const declaration = this.#parseQuery(keyword.text === 'sync');
317
+ } else if (next.text === 'query' || next.text === 'sync') {
318
+ const declaration = this.#parseQuery(
319
+ next.text === 'sync',
320
+ acknowledgements,
321
+ );
313
322
  this.#claimName(
314
323
  fileNames,
315
324
  declaration.name,
@@ -320,9 +329,13 @@ class Parser {
320
329
  queries.push(declaration);
321
330
  } else {
322
331
  this.#fail(
323
- 'SYQL2008_INVALID_MEMBER',
324
- keyword,
325
- `expected import, predicate, query, or sync query; found ${JSON.stringify(keyword.text)}`,
332
+ acknowledgements.length > 0
333
+ ? 'SYQL2013_INVALID_ACKNOWLEDGEMENT'
334
+ : 'SYQL2008_INVALID_MEMBER',
335
+ next,
336
+ acknowledgements.length > 0
337
+ ? `a query plan acknowledgement precedes a query declaration; found ${JSON.stringify(next.text || 'end of file')}`
338
+ : `expected import, predicate, query, or sync query; found ${JSON.stringify(next.text)}`,
326
339
  );
327
340
  }
328
341
  }
@@ -469,7 +482,58 @@ class Parser {
469
482
  };
470
483
  }
471
484
 
472
- #parseQuery(sync: boolean): SyqlQueryDeclaration {
485
+ #parseAcknowledgements(): QueryAcknowledgement[] {
486
+ const out: QueryAcknowledgement[] = [];
487
+ while (this.#peek().text === 'allow') {
488
+ const start = this.#take();
489
+ const kind = this.#take();
490
+ const finding = QUERY_PLAN_FINDINGS.find((name) => name === kind.text);
491
+ if (finding === undefined) {
492
+ this.#fail(
493
+ 'SYQL2013_INVALID_ACKNOWLEDGEMENT',
494
+ kind,
495
+ `expected a query plan finding (${QUERY_PLAN_FINDINGS.join(', ')}), found ${JSON.stringify(kind.text || 'end of file')}`,
496
+ );
497
+ }
498
+ const table = finding === 'many_tables' ? undefined : this.#take();
499
+ if (table !== undefined && table.kind !== 'identifier') {
500
+ this.#fail(
501
+ 'SYQL2013_INVALID_ACKNOWLEDGEMENT',
502
+ table,
503
+ `expected the table the finding names, found ${JSON.stringify(table.text || 'end of file')}`,
504
+ );
505
+ }
506
+ const reason = this.#take();
507
+ const text = reason.text.slice(1, -1).split("''").join("'");
508
+ if (reason.kind !== 'string' || text.trim() === '') {
509
+ this.#fail(
510
+ 'SYQL2013_INVALID_ACKNOWLEDGEMENT',
511
+ reason,
512
+ 'a query plan acknowledgement ends with a non-blank reason string',
513
+ );
514
+ }
515
+ if (
516
+ out.some((ack) => ack.finding === finding && ack.table === table?.text)
517
+ ) {
518
+ this.#fail(
519
+ 'SYQL2013_INVALID_ACKNOWLEDGEMENT',
520
+ start,
521
+ 'the query already acknowledges this finding',
522
+ );
523
+ }
524
+ out.push({
525
+ finding,
526
+ ...(table === undefined ? {} : { table: table.text }),
527
+ reason: text,
528
+ });
529
+ }
530
+ return out;
531
+ }
532
+
533
+ #parseQuery(
534
+ sync: boolean,
535
+ acknowledgements: readonly QueryAcknowledgement[],
536
+ ): SyqlQueryDeclaration {
473
537
  const start = sync ? this.#expectText('sync') : this.#peek();
474
538
  this.#expectText('query');
475
539
  const name = this.#parseCamelName('query name');
@@ -551,6 +615,7 @@ class Parser {
551
615
  statement: body.statement,
552
616
  ...(body.sort === undefined ? {} : { sort: body.sort }),
553
617
  ...(body.limit === undefined ? {} : { limit: body.limit }),
618
+ acknowledgements,
554
619
  span: spanBetween(start, body.close),
555
620
  nameSpan: name.span,
556
621
  };