@syncular/typegen 0.15.47 → 0.16.1

package/dist/syql-diagnostics.d.ts

@@ -0,0 +1,77 @@
+import type { SyqlLexErrorCode } from './syql-lexer.js';
+import type { SyqlLoweringErrorCode } from './syql-lowering.js';
+import type { SyqlModuleErrorCode } from './syql-modules.js';
+import type { SyqlParseErrorCode } from './syql-parser.js';
+import type { SyqlSemanticErrorCode } from './syql-semantics.js';
+import type { SyqlTemplateParseErrorCode } from './syql-template-parser.js';
+import type { SyqlValidationErrorCode } from './syql-validator.js';
+export type SyqlRuntimeErrorCode = 'SYQL_RUNTIME_MISSING_REQUIRED_INPUT' | 'SYQL_RUNTIME_UNKNOWN_INPUT' | 'SYQL_RUNTIME_INVALID_INPUT' | 'SYQL_RUNTIME_INVALID_GROUP' | 'SYQL_RUNTIME_INVALID_SORT' | 'SYQL_RUNTIME_INVALID_LIMIT';
+export type SyqlDiagnosticCode = SyqlLexErrorCode | SyqlParseErrorCode | SyqlTemplateParseErrorCode | SyqlModuleErrorCode | SyqlSemanticErrorCode | SyqlValidationErrorCode | SyqlLoweringErrorCode | 'SYQL9001_PROJECT_CONTEXT' | SyqlRuntimeErrorCode;
+/** Stable compiler and generated-runtime diagnostic remedies keyed by code. */
+export declare const SYQL_DIAGNOSTIC_REMEDIES: {
+    readonly SYQL1001_UNTERMINATED_STRING: "Close the string literal with a matching single quote.";
+    readonly SYQL1002_UNTERMINATED_IDENTIFIER: "Close the quoted identifier with its matching delimiter.";
+    readonly SYQL1003_UNTERMINATED_COMMENT: "Close the block comment with */.";
+    readonly SYQL1004_UNTERMINATED_IMPORT_PATH: "Close the import path with a matching double quote.";
+    readonly SYQL2001_EXPECTED_TOKEN: "Insert the token named by the diagnostic at the reported source position.";
+    readonly SYQL2002_INVALID_NAME: "Rename the declaration or parameter to a valid lower-camel identifier.";
+    readonly SYQL2003_RESERVED_NAME: "Rename the declaration or parameter so it does not use a reserved SYQL name.";
+    readonly SYQL2004_DUPLICATE_NAME: "Give each declaration, parameter, group member, and profile a unique name in its scope.";
+    readonly SYQL2005_INVALID_IMPORT: "Use a relative .syql import with explicit imported predicate names.";
+    readonly SYQL2006_EMPTY_TEMPLATE: "Add a SQL expression or statement inside the braces.";
+    readonly SYQL2007_FORBIDDEN_SEMICOLON: "Remove the semicolon from the embedded SQL template.";
+    readonly SYQL2008_INVALID_MEMBER: "Use a member supported by the surrounding SYQL declaration.";
+    readonly SYQL2009_INVALID_INTEGER: "Use a decimal integer within the range named by the diagnostic.";
+    readonly SYQL2010_INVALID_PAGE_RANGE: "Choose default and maximum page sizes that satisfy the declared range.";
+    readonly SYQL2011_INVALID_PARAMETER: "Rewrite the parameter using a supported value, optional, range, group, sort, or limit form.";
+    readonly SYQL2012_INVALID_QUERY_BODY: "Rewrite the query body using the clause order and forms defined by the SYQL grammar.";
+    readonly SYQL3001_EXPECTED_EMBEDDED_TOKEN: "Insert the required token in the embedded SQL construct.";
+    readonly SYQL3002_INVALID_BIND: "Bind a declared input with the :name form in a supported SQL position.";
+    readonly SYQL3003_INVALID_PREDICATE_CALL: "Call the predicate with declared bind arguments and matching parentheses.";
+    readonly SYQL3004_INVALID_WHEN: "Use when with declared controls and a nonempty conditional SQL body.";
+    readonly SYQL3005_INVALID_REACTIVE_DIRECTIVE: "Rewrite the reactive directive using a supported revision-1 form.";
+    readonly SYQL3006_FORBIDDEN_TEMPLATE_NODE: "Remove the conditional or predicate construct from this SQL context.";
+    readonly SYQL3007_UNEXPECTED_BRACE: "Remove the unmatched brace or close the surrounding embedded construct.";
+    readonly SYQL3008_FORBIDDEN_PARAMETER_FORM: "Use a value bind in this context instead of a range, group, sort, or limit control.";
+    readonly SYQL4001_IMPORT_OUTSIDE_ROOT: "Move the imported file under the configured query root and use a relative path.";
+    readonly SYQL4002_MODULE_NOT_FOUND: "Create the imported .syql file or correct the relative import path.";
+    readonly SYQL4003_IMPORT_CYCLE: "Remove one import edge so predicate modules form an acyclic graph.";
+    readonly SYQL4004_UNKNOWN_PREDICATE: "Export and import the predicate under the referenced name.";
+    readonly SYQL4005_DUPLICATE_IMPORT_TARGET: "Import each local predicate name once in the module.";
+    readonly SYQL4006_DUPLICATE_QUERY: "Give every query in the project a unique public name.";
+    readonly SYQL5001_UNKNOWN_PREDICATE: "Define the predicate locally or import it under the referenced name.";
+    readonly SYQL5002_PREDICATE_CYCLE: "Remove the recursive predicate call so expansion terminates.";
+    readonly SYQL5003_PREDICATE_ARITY: "Pass exactly the number of bind arguments declared by the predicate.";
+    readonly SYQL5004_CLOSED_PREDICATE: "Declare each external bind as a predicate parameter and pass it at the call site.";
+    readonly SYQL5005_UNUSED_PREDICATE_PARAMETER: "Use the predicate parameter in its body or remove it from the signature.";
+    readonly SYQL5006_UNDECLARED_BIND: "Declare the bind as a query input or predicate parameter.";
+    readonly SYQL5007_UNUSED_INPUT: "Use the query input in SQL or remove it from the public signature.";
+    readonly SYQL5008_INVALID_CONTROL: "Use an optional input, group, sort, or limit name as the control.";
+    readonly SYQL5009_MISSING_DOMINANCE: "Guard every optional bind with a when condition that proves its presence.";
+    readonly SYQL5010_UNUSED_CONTROL: "Use the control in the query body or remove it from the signature.";
+    readonly SYQL5011_TYPE_CONFLICT: "Make every declaration and SQL use of the bind agree on one SYQL type.";
+    readonly SYQL6001_INVALID_PLACEMENT: "Move the SYQL construct to the SQL clause named by the diagnostic.";
+    readonly SYQL6002_INVALID_SQL: "Correct the reported SQLite syntax, table, column, function, or bind error.";
+    readonly SYQL6003_NONDETERMINISTIC_SQL: "Replace nondeterministic SQL with values supplied through query inputs or stored columns.";
+    readonly SYQL6004_TYPE_CONFLICT: "Align the declared input type with the schema column and SQL expression types.";
+    readonly SYQL6005_INVALID_SYNC_QUERY: "Select stable row identity and preserve the scope coverage required for reactive sync.";
+    readonly SYQL6006_INVALID_SORT: "Use declared sort profiles with deterministic ORDER BY terms and a stable tie-breaker.";
+    readonly SYQL6007_INVALID_LIMIT: "Use the declared limit control and keep its default and maximum within the supported range.";
+    readonly SYQL6008_INVALID_IDENTITY: "Declare identity columns that are selected, non-null, and sufficient to identify each result row.";
+    readonly SYQL7001_ENUMERATION_LIMIT: "Use the auto or neutralize backend, reduce control combinations, or raise the explicit compiler limit.";
+    readonly SYQL7002_INTERNAL_LOWERING: "Report the query and diagnostic to the Syncular maintainers.";
+    readonly SYQL9001_PROJECT_CONTEXT: "Open the file under a project with a valid syncular.json, migrations, schema output, and query root.";
+    readonly SYQL_RUNTIME_MISSING_REQUIRED_INPUT: "Pass the required generated-query input.";
+    readonly SYQL_RUNTIME_UNKNOWN_INPUT: "Remove the unknown key from the generated-query input object.";
+    readonly SYQL_RUNTIME_INVALID_INPUT: "Pass a value that matches the generated input type and nullability.";
+    readonly SYQL_RUNTIME_INVALID_GROUP: "Pass either the complete generated group shape or omit the optional group.";
+    readonly SYQL_RUNTIME_INVALID_SORT: "Pass one of the sort profile names exported for the generated query.";
+    readonly SYQL_RUNTIME_INVALID_LIMIT: "Pass an integer within the generated query limit range.";
+};
+/** Generate a deterministic JSON-ready code-to-remedy catalog. */
+export declare function generateSyqlDiagnosticCatalog(): Readonly<Array<{
+    readonly code: SyqlDiagnosticCode;
+    readonly remedy: string;
+}>>;
+/** Resolve a diagnostic remedy without requiring a narrowed code type. */
+export declare function syqlDiagnosticRemedy(code: string): string | undefined;

package/dist/syql-diagnostics.js

@@ -0,0 +1,72 @@
+/** Stable compiler and generated-runtime diagnostic remedies keyed by code. */
+export const SYQL_DIAGNOSTIC_REMEDIES = {
+    SYQL1001_UNTERMINATED_STRING: 'Close the string literal with a matching single quote.',
+    SYQL1002_UNTERMINATED_IDENTIFIER: 'Close the quoted identifier with its matching delimiter.',
+    SYQL1003_UNTERMINATED_COMMENT: 'Close the block comment with */.',
+    SYQL1004_UNTERMINATED_IMPORT_PATH: 'Close the import path with a matching double quote.',
+    SYQL2001_EXPECTED_TOKEN: 'Insert the token named by the diagnostic at the reported source position.',
+    SYQL2002_INVALID_NAME: 'Rename the declaration or parameter to a valid lower-camel identifier.',
+    SYQL2003_RESERVED_NAME: 'Rename the declaration or parameter so it does not use a reserved SYQL name.',
+    SYQL2004_DUPLICATE_NAME: 'Give each declaration, parameter, group member, and profile a unique name in its scope.',
+    SYQL2005_INVALID_IMPORT: 'Use a relative .syql import with explicit imported predicate names.',
+    SYQL2006_EMPTY_TEMPLATE: 'Add a SQL expression or statement inside the braces.',
+    SYQL2007_FORBIDDEN_SEMICOLON: 'Remove the semicolon from the embedded SQL template.',
+    SYQL2008_INVALID_MEMBER: 'Use a member supported by the surrounding SYQL declaration.',
+    SYQL2009_INVALID_INTEGER: 'Use a decimal integer within the range named by the diagnostic.',
+    SYQL2010_INVALID_PAGE_RANGE: 'Choose default and maximum page sizes that satisfy the declared range.',
+    SYQL2011_INVALID_PARAMETER: 'Rewrite the parameter using a supported value, optional, range, group, sort, or limit form.',
+    SYQL2012_INVALID_QUERY_BODY: 'Rewrite the query body using the clause order and forms defined by the SYQL grammar.',
+    SYQL3001_EXPECTED_EMBEDDED_TOKEN: 'Insert the required token in the embedded SQL construct.',
+    SYQL3002_INVALID_BIND: 'Bind a declared input with the :name form in a supported SQL position.',
+    SYQL3003_INVALID_PREDICATE_CALL: 'Call the predicate with declared bind arguments and matching parentheses.',
+    SYQL3004_INVALID_WHEN: 'Use when with declared controls and a nonempty conditional SQL body.',
+    SYQL3005_INVALID_REACTIVE_DIRECTIVE: 'Rewrite the reactive directive using a supported revision-1 form.',
+    SYQL3006_FORBIDDEN_TEMPLATE_NODE: 'Remove the conditional or predicate construct from this SQL context.',
+    SYQL3007_UNEXPECTED_BRACE: 'Remove the unmatched brace or close the surrounding embedded construct.',
+    SYQL3008_FORBIDDEN_PARAMETER_FORM: 'Use a value bind in this context instead of a range, group, sort, or limit control.',
+    SYQL4001_IMPORT_OUTSIDE_ROOT: 'Move the imported file under the configured query root and use a relative path.',
+    SYQL4002_MODULE_NOT_FOUND: 'Create the imported .syql file or correct the relative import path.',
+    SYQL4003_IMPORT_CYCLE: 'Remove one import edge so predicate modules form an acyclic graph.',
+    SYQL4004_UNKNOWN_PREDICATE: 'Export and import the predicate under the referenced name.',
+    SYQL4005_DUPLICATE_IMPORT_TARGET: 'Import each local predicate name once in the module.',
+    SYQL4006_DUPLICATE_QUERY: 'Give every query in the project a unique public name.',
+    SYQL5001_UNKNOWN_PREDICATE: 'Define the predicate locally or import it under the referenced name.',
+    SYQL5002_PREDICATE_CYCLE: 'Remove the recursive predicate call so expansion terminates.',
+    SYQL5003_PREDICATE_ARITY: 'Pass exactly the number of bind arguments declared by the predicate.',
+    SYQL5004_CLOSED_PREDICATE: 'Declare each external bind as a predicate parameter and pass it at the call site.',
+    SYQL5005_UNUSED_PREDICATE_PARAMETER: 'Use the predicate parameter in its body or remove it from the signature.',
+    SYQL5006_UNDECLARED_BIND: 'Declare the bind as a query input or predicate parameter.',
+    SYQL5007_UNUSED_INPUT: 'Use the query input in SQL or remove it from the public signature.',
+    SYQL5008_INVALID_CONTROL: 'Use an optional input, group, sort, or limit name as the control.',
+    SYQL5009_MISSING_DOMINANCE: 'Guard every optional bind with a when condition that proves its presence.',
+    SYQL5010_UNUSED_CONTROL: 'Use the control in the query body or remove it from the signature.',
+    SYQL5011_TYPE_CONFLICT: 'Make every declaration and SQL use of the bind agree on one SYQL type.',
+    SYQL6001_INVALID_PLACEMENT: 'Move the SYQL construct to the SQL clause named by the diagnostic.',
+    SYQL6002_INVALID_SQL: 'Correct the reported SQLite syntax, table, column, function, or bind error.',
+    SYQL6003_NONDETERMINISTIC_SQL: 'Replace nondeterministic SQL with values supplied through query inputs or stored columns.',
+    SYQL6004_TYPE_CONFLICT: 'Align the declared input type with the schema column and SQL expression types.',
+    SYQL6005_INVALID_SYNC_QUERY: 'Select stable row identity and preserve the scope coverage required for reactive sync.',
+    SYQL6006_INVALID_SORT: 'Use declared sort profiles with deterministic ORDER BY terms and a stable tie-breaker.',
+    SYQL6007_INVALID_LIMIT: 'Use the declared limit control and keep its default and maximum within the supported range.',
+    SYQL6008_INVALID_IDENTITY: 'Declare identity columns that are selected, non-null, and sufficient to identify each result row.',
+    SYQL7001_ENUMERATION_LIMIT: 'Use the auto or neutralize backend, reduce control combinations, or raise the explicit compiler limit.',
+    SYQL7002_INTERNAL_LOWERING: 'Report the query and diagnostic to the Syncular maintainers.',
+    SYQL9001_PROJECT_CONTEXT: 'Open the file under a project with a valid syncular.json, migrations, schema output, and query root.',
+    SYQL_RUNTIME_MISSING_REQUIRED_INPUT: 'Pass the required generated-query input.',
+    SYQL_RUNTIME_UNKNOWN_INPUT: 'Remove the unknown key from the generated-query input object.',
+    SYQL_RUNTIME_INVALID_INPUT: 'Pass a value that matches the generated input type and nullability.',
+    SYQL_RUNTIME_INVALID_GROUP: 'Pass either the complete generated group shape or omit the optional group.',
+    SYQL_RUNTIME_INVALID_SORT: 'Pass one of the sort profile names exported for the generated query.',
+    SYQL_RUNTIME_INVALID_LIMIT: 'Pass an integer within the generated query limit range.',
+};
+/** Generate a deterministic JSON-ready code-to-remedy catalog. */
+export function generateSyqlDiagnosticCatalog() {
+    return Object.keys(SYQL_DIAGNOSTIC_REMEDIES)
+        .sort()
+        .map((code) => ({ code, remedy: SYQL_DIAGNOSTIC_REMEDIES[code] }));
+}
+/** Resolve a diagnostic remedy without requiring a narrowed code type. */
+export function syqlDiagnosticRemedy(code) {
+    const remedies = SYQL_DIAGNOSTIC_REMEDIES;
+    return remedies[code];
+}

package/dist/syql-lowering.js

@@ -309,6 +309,7 @@ function lowerStatement(validated, ir, db, naming, sql, sortProfile, activationM
             ...(activationMask === undefined ? {} : { activationMask }),
             sql: namedSql,
             positionalSql: analyzed.positionalSql,
+            relations: analyzed.relations,
             binds: bindNames.map((name) => planBind(name, owners, conditionBinds, query.conditions, validated.limit, query)),
         },
         analysis: { ...analyzed, sourceSql: namedSql, sql: namedSql },

package/dist/syql-validator.js

@@ -303,7 +303,15 @@ class Validator {
         const activeStructure = this.#inspect(activeSql, location);
         this.#validateStatementShape(activeSql, activeStructure, logical.declaration, location);
         this.#validateDeterminism(activeSql, logical.declaration.statement.span);
-        const refs = scanTableRefs(activeSql, this.#ir);
+        let refs;
+        try {
+            refs = scanTableRefs(activeSql, this.#ir);
+        }
+        catch (error) {
+            // Preserve SQLite's source-spanned diagnostics for invalid relations.
+            this.#validateSqlite(activeSql, logical, []);
+            this.#fail('SYQL6002_INVALID_SQL', logical.declaration.statement.span, error instanceof Error ? error.message : String(error));
+        }
         this.#validatePortableProfile(activeSql, logical.declaration.statement.span, refs);
         this.#validateSqlite(activeSql, logical, refs);
         const bindSymbols = this.#bindSymbols(logical.declaration);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.15.47",
+  "version": "0.16.1",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -56,9 +56,9 @@
     "!dist/**/*.test.d.ts"
   ],
   "dependencies": {
-    "@syncular/core": "0.15.47"
+    "@syncular/core": "0.16.1"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.47"
+    "@syncular/server": "0.16.1"
   }
 }

package/src/emit-queries-rust.ts

@@ -892,7 +892,7 @@ function emitSupport(clientCrate: string): string {
     '        ));',
     '    }',
     '    hex.as_bytes()',
-    '        .chunks_exact(2)',
+    '        .chunks(2)',
     '        .map(|pair| {',
     '            let pair = std::str::from_utf8(pair)',
     '                .map_err(|_| decode_error(query, column, "bytes", "non-ASCII $bytes envelope"))?;',

package/src/emit-queries.ts

@@ -314,15 +314,15 @@ function emitSyqlQuery(query: AnalyzedQuery, hash: string): string {
       : `raw?: ${Params}`;
   const validated = hasParams ? `${query.name}Validate(raw)` : undefined;
   const statementType = hasParams
-    ? `{ sql: string; bind: (params: ${Params}) => QueryValue[] }`
-    : '{ sql: string; bind: () => QueryValue[] }';
-  lines.push(`const ${query.name}Statements: ${statementType}[] = [`);
+    ? `QueryRelationPlan & { bind: (params: ${Params}) => QueryValue[] }`
+    : 'QueryRelationPlan & { bind: () => QueryValue[] }';
+  lines.push(`const ${query.name}Statements: (${statementType})[] = [`);
   for (const statement of metadata.plan.statements) {
     const binds = statement.binds
       .map((bind) => syqlBindExpr(query, bind, 'params'))
       .join(', ');
     lines.push(
-      `  { sql: ${quote(statement.positionalSql)}, bind: (${hasParams ? 'params' : ''}) => [${binds}] },`,
+      `  { sql: ${quote(statement.positionalSql)}, relations: ${JSON.stringify(statement.relations)}, bind: (${hasParams ? 'params' : ''}) => [${binds}] },`,
     );
   }
   lines.push('];');
@@ -399,6 +399,7 @@ function emitSyqlQuery(query: AnalyzedQuery, hash: string): string {
     );
   }
   lines.push(`  tables: ${query.name}Tables,`);
+  lines.push(`  relationPlans: ${query.name}Statements,`);
   lines.push(
     `  resultColumns: [${query.columns.map((column) => `{ name: ${quote(column.langName)}, type: ${quote(column.type)}, nullable: ${column.nullable} }`).join(', ')}],`,
   );
@@ -540,6 +541,9 @@ function emitQuery(query: AnalyzedQuery, hash: string): string {
   lines.push(`  sql: ${sqlConst},`);
   lines.push(`  mapRow: ${query.name}MapRow,`);
   lines.push(`  tables: ${query.name}Tables,`);
+  lines.push(
+    `  relationPlans: [{ sql: ${sqlConst}, relations: ${JSON.stringify(query.relations)} }],`,
+  );
   lines.push(
     `  resultColumns: [${query.columns.map((column) => `{ name: ${quote(column.langName)}, type: ${quote(column.type)}, nullable: ${column.nullable} }`).join(', ')}],`,
   );
@@ -683,6 +687,11 @@ export function emitQueriesModule(
       " *  `@syncular/react`'s `useQuery`. `Row` is the projection row",
       ' *  type; `Params` is `undefined` for a param-less query. `sqlFor`',
       ' *  selects a checked revision-1 SYQL physical statement when needed. */',
+      'export interface QueryRelationPlan {',
+      '  readonly sql: string;',
+      '  readonly relations: readonly { readonly table: string; readonly start: number; readonly end: number; readonly alias?: string }[];',
+      '}',
+      '',
       'export interface NamedQuery<Row, Params = undefined> {',
       '  readonly id: string;',
       '  readonly hasParams: boolean;',
@@ -690,6 +699,7 @@ export function emitQueriesModule(
       '  readonly mapRow: (row: Readonly<Record<string, unknown>>) => Row;',
       '  readonly tables: readonly string[];',
       '  readonly resultColumns: readonly QueryResultColumn[];',
+      '  readonly relationPlans: readonly QueryRelationPlan[];',
       '  readonly bind: (params: Params) => readonly QueryValue[];',
       '  readonly sqlFor?: (params: Params) => string;',
       '  readonly dependencies: (params: Params) => readonly QueryDependency[];',

package/src/index.ts

@@ -25,6 +25,7 @@ export * from './query';
 export * from './query-ir';
 export * from './sql';
 export * from './syql-ast';
+export * from './syql-diagnostics';
 export * from './syql-lexer';
 export * from './syql-lowering';
 export * from './syql-modules';

package/src/lsp.ts

@@ -9,6 +9,7 @@ import type { IrDocument } from './ir';
 import { MANIFEST_FILENAME, parseManifest } from './manifest';
 import { lockedMigrationNames, readMigrationLock } from './migration-lock';
 import type { QueryDb, QueryNamingOptions } from './query';
+import { syqlDiagnosticRemedy } from './syql-diagnostics';
 import { SyqlFrontendError, type SyqlSourceSpan } from './syql-lexer';
 import type { SyqlLoweredQuery } from './syql-lowering';
 import { lowerSyqlQuery } from './syql-lowering';
@@ -49,6 +50,7 @@ interface Diagnostic {
   severity: number;
   source: string;
   code?: string;
+  data?: { readonly remedy: string };
   message: string;
 }
 
@@ -384,14 +386,25 @@ export class SyqlLanguageServer {
       error instanceof SyqlFrontendError &&
       resolve(error.sourceFile) === file
     ) {
+      const remedy = syqlDiagnosticRemedy(error.code);
       return {
         range: spanRange(text, error.span),
         severity: 1,
         source: 'syncular',
         code: error.code,
+        ...(remedy === undefined ? {} : { data: { remedy } }),
         message: error.detail,
       };
     }
+    const projectContextError =
+      this.#context(pathToFileURL(file).href).kind === 'error';
+    const code =
+      error instanceof SyqlFrontendError
+        ? error.code
+        : projectContextError
+          ? 'SYQL9001_PROJECT_CONTEXT'
+          : undefined;
+    const remedy = code === undefined ? undefined : syqlDiagnosticRemedy(code);
     return {
       range: {
         start: { line: 0, character: 0 },
@@ -402,11 +415,11 @@ export class SyqlLanguageServer {
       },
       severity: 1,
       source: 'syncular',
-      ...(error instanceof SyqlFrontendError ? { code: error.code } : {}),
-      message:
-        this.#context(pathToFileURL(file).href).kind === 'error'
-          ? `SYQL9001_PROJECT_CONTEXT: ${message}`
-          : message,
+      ...(code === undefined ? {} : { code }),
+      ...(remedy === undefined ? {} : { data: { remedy } }),
+      message: projectContextError
+        ? `SYQL9001_PROJECT_CONTEXT: ${message}`
+        : message,
     };
   }
 

package/src/query-ir.ts

@@ -14,13 +14,14 @@ import type { AnalyzedQuery } from './query';
 /** Serialize analyzed queries as the deterministic QueryIR JSON document. */
 export function serializeQueryIr(queries: readonly AnalyzedQuery[]): string {
   const doc = {
-    queryIrVersion: 3,
+    queryIrVersion: 4,
     queries: queries.map((query) => ({
       name: query.name,
       file: query.file,
       sourceSql: query.sourceSql,
       sql: query.sql,
       positionalSql: query.positionalSql,
+      relations: query.relations,
       params: query.params.map((param) => ({
         name: param.name,
         langName: param.langName,
@@ -101,6 +102,7 @@ export function serializeQueryIr(queries: readonly AnalyzedQuery[]): string {
                     : { activationMask: statement.activationMask }),
                   sql: statement.sql,
                   positionalSql: statement.positionalSql,
+                  relations: statement.relations,
                   binds: statement.binds.map((bind) => ({ ...bind })),
                 })),
               },