@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.
- package/README.md +53 -18
- package/dist/emit-dart.js +7 -18
- package/dist/emit-kotlin.d.ts +1 -1
- package/dist/emit-kotlin.js +9 -20
- package/dist/emit-queries-rust.js +18 -14
- package/dist/emit-queries.js +19 -23
- package/dist/emit-swift.d.ts +1 -1
- package/dist/emit-swift.js +9 -20
- package/dist/emit.d.ts +2 -2
- package/dist/emit.js +9 -20
- package/dist/fmt.js +11 -2
- package/dist/generate.js +31 -26
- package/dist/init.js +4 -5
- package/dist/ir.d.ts +3 -2
- package/dist/ir.js +1 -2
- package/dist/lsp.js +6 -1
- package/dist/manifest.d.ts +1 -2
- package/dist/manifest.js +13 -12
- package/dist/query.d.ts +40 -0
- package/dist/query.js +159 -0
- package/dist/syql-ast.d.ts +2 -0
- package/dist/syql-ast.js +7 -1
- package/dist/syql-browser.js +7 -6
- package/dist/syql-diagnostics.d.ts +1 -0
- package/dist/syql-diagnostics.js +1 -0
- package/dist/syql-lowering.js +1 -0
- package/dist/syql-parser.d.ts +4 -1
- package/dist/syql-parser.js +42 -5
- package/package.json +3 -3
- package/src/emit-dart.ts +11 -22
- package/src/emit-kotlin.ts +13 -26
- package/src/emit-queries-rust.ts +22 -19
- package/src/emit-queries.ts +23 -38
- package/src/emit-swift.ts +15 -24
- package/src/emit.ts +15 -22
- package/src/fmt.ts +10 -2
- package/src/generate.ts +44 -36
- package/src/init.ts +4 -5
- package/src/ir.ts +4 -4
- package/src/lsp.ts +11 -4
- package/src/manifest.ts +22 -18
- package/src/query.ts +251 -0
- package/src/syql-ast.ts +9 -0
- package/src/syql-browser.ts +8 -7
- package/src/syql-diagnostics.ts +2 -0
- package/src/syql-lowering.ts +1 -0
- 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",
|
|
18
|
-
* "scopes": { "project_id":
|
|
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
|
-
* -
|
|
28
|
-
*
|
|
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
|
|
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
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
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,
|
|
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
|
|
package/src/syql-browser.ts
CHANGED
|
@@ -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
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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. */
|
package/src/syql-diagnostics.ts
CHANGED
|
@@ -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:
|
package/src/syql-lowering.ts
CHANGED
package/src/syql-parser.ts
CHANGED
|
@@ -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
|
-
|
|
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 (
|
|
312
|
-
const declaration = this.#parseQuery(
|
|
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
|
-
|
|
324
|
-
|
|
325
|
-
|
|
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
|
-
#
|
|
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
|
};
|