@syncular/typegen 0.15.47 → 0.16.1

package/src/query.ts

@@ -62,6 +62,7 @@
  * for the query shapes this tier supports.
  */
 import { TypegenError } from './errors';
+import { isSyqlTrivia, lexSyqlSqlSource, type SyqlToken } from './syql-lexer';
 import type { IrColumn, IrColumnType, IrDocument, IrTable } from './ir';
 import { lowerProjection, mainVerbAfterWith } from './lower';
 import { buildNamingMap, type NamingMode, type NamingTarget } from './naming';
@@ -245,6 +246,7 @@ export interface QuerySyqlStatement {
   readonly sql: string;
   readonly positionalSql: string;
   readonly binds: readonly QuerySyqlPlanBind[];
+  readonly relations: readonly QueryRelation[];
 }
 
 /** The target-neutral physical plan every emitter must implement exactly. */
@@ -267,6 +269,14 @@ export interface QuerySyqlMetadata {
   readonly identity?: readonly string[];
 }
 
+/** Physical relation boundaries in the exact positional SQL statement. */
+export interface QueryRelation {
+  readonly table: string;
+  readonly start: number;
+  readonly end: number;
+  readonly alias?: string;
+}
+
 export interface AnalyzedQuery {
   /** camelCase function name (path-derived, or a `-- name:` override). */
   readonly name: string;
@@ -281,6 +291,7 @@ export interface AnalyzedQuery {
   readonly sql: string;
   /** The lowered SQL with `:name` rewritten to positional `?`. */
   readonly positionalSql: string;
+  readonly relations: readonly QueryRelation[];
   /** Params in first-occurrence (positional) order. */
   readonly params: readonly QueryParam[];
   /** Result columns in SELECT order. */
@@ -692,6 +703,9 @@ export function toPositionalSql(sql: string): string {
 
 export interface TableRef {
   readonly table: string;
+  readonly start: number;
+  readonly end: number;
+  readonly explicitAlias?: string;
   /** Alias (or the table name when un-aliased). */
   readonly alias: string;
   /** True when an enclosing flat join chain can null-extend this relation. */
@@ -709,6 +723,7 @@ const RESERVED_ALIAS = new Set([
   'inner',
   'left',
   'right',
+  'full',
   'outer',
   'natural',
   'join',
@@ -716,197 +731,215 @@ const RESERVED_ALIAS = new Set([
   'using',
   'limit',
   'having',
+  'union',
+  'intersect',
+  'except',
+  'offset',
+  'window',
+  'indexed',
+  'not',
 ]);
-const RESERVED_ALIAS_PATTERN = [...RESERVED_ALIAS].join('|');
-const TABLE_REF_RE = new RegExp(
-  `\\b(FROM|(?:NATURAL\\s+)?(?:(LEFT|RIGHT|FULL)(?:\\s+OUTER)?|INNER|CROSS)?\\s*JOIN)\\s+((?:\\(\\s*)*)(${IDENT})(?:\\s+(?:AS\\s+)?((?!(?:${RESERVED_ALIAS_PATTERN})\\b)${IDENT}))?`,
-  'gi',
-);
-
-function parenthesisDepthAt(sql: string, index: number): number {
-  let depth = 0;
-  for (let cursor = 0; cursor < index; cursor += 1) {
-    if (sql[cursor] === '(') depth += 1;
-    else if (sql[cursor] === ')') depth = Math.max(0, depth - 1);
-  }
-  return depth;
+function sqlIdentifier(token: SyqlToken | undefined): string | undefined {
+  if (token?.kind === 'identifier') return token.text;
+  if (token?.kind !== 'quoted-identifier') return undefined;
+  const quote = token.text[0];
+  const value = token.text.slice(1, -1);
+  return quote === '[' ? value : value.split(`${quote}${quote}`).join(quote);
 }
 
-function matchingParenthesis(sql: string, open: number): number {
-  let depth = 0;
-  for (let cursor = open; cursor < sql.length; cursor += 1) {
-    if (sql[cursor] === '(') depth += 1;
-    else if (sql[cursor] === ')') {
-      depth -= 1;
-      if (depth === 0) return cursor;
-    }
-  }
-  return sql.length;
-}
-
-function hasCommaJoinedSchemaTable(sql: string, ir: IrDocument): boolean {
-  const cleaned = stripCommentsAndStrings(sql);
-  const known = new Set(
+export function scanTableRefs(sql: string, ir: IrDocument): TableRef[] {
+  const tokens = lexSyqlSqlSource('query SQL', sql).filter(
+    (token) => !isSyqlTrivia(token) && token.kind !== 'eof',
+  );
+  const known = new Map(
     ir.tables.flatMap((table) => [
-      table.name.toLowerCase(),
-      ...table.ftsIndexes.map((index) => index.name.toLowerCase()),
+      [table.name.toLowerCase(), table.name] as const,
+      ...table.ftsIndexes.map(
+        (index) => [index.name.toLowerCase(), index.name] as const,
+      ),
     ]),
   );
+  const closes = new Map<number, number>();
+  const parents: number[] = [];
+  const depths: number[] = [];
+  const stack: number[] = [];
+  tokens.forEach((token, index) => {
+    if (token.text === ')') {
+      const open = stack.pop();
+      if (open !== undefined) closes.set(open, index);
+    }
+    parents[index] = stack.at(-1) ?? -1;
+    depths[index] = stack.length;
+    if (token.text === '(') stack.push(index);
+  });
   const activeFromDepths = new Set<number>();
   const clauseEnders = new Set([
-    'WHERE',
-    'GROUP',
-    'HAVING',
-    'ORDER',
-    'LIMIT',
-    'WINDOW',
-    'UNION',
-    'EXCEPT',
-    'INTERSECT',
-    'RETURNING',
+    'where',
+    'group',
+    'having',
+    'order',
+    'limit',
+    'window',
+    'union',
+    'except',
+    'intersect',
+    'returning',
   ]);
-  let depth = 0;
-  let cursor = 0;
-  /** The previous significant token: an uppercased word or a single
-   * punctuation character. Distinguishes a table-source group — a `(` after
-   * FROM, JOIN, `,` or another `(` — from a function call or parenthesized
-   * expression, whose `(` follows an identifier or an operator. */
-  let previous: string | undefined;
-  const nextIdentifier = (start: number): string | undefined => {
-    let index = start;
-    while (
-      index < cleaned.length &&
-      (/\s/.test(cleaned[index] as string) || cleaned[index] === '(')
-    ) {
-      index += 1;
-    }
-    const match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(cleaned.slice(index));
-    return match?.[0];
-  };
-
-  while (cursor < cleaned.length) {
-    const char = cleaned[cursor] as string;
-    if (/\s/.test(char)) {
-      cursor += 1;
-      continue;
+  for (const [index, token] of tokens.entries()) {
+    const depth = depths[index] ?? 0;
+    const word =
+      token.kind === 'identifier' ? token.text.toLowerCase() : undefined;
+    if (word === 'in' && sqlIdentifier(tokens[index + 1]) !== undefined) {
+      throw new TypegenError(
+        'query SQL',
+        'table-name IN expressions are unsupported; use an explicit SELECT subquery',
+      );
     }
-    if (char === '(') {
-      const opensTableSource =
-        previous === 'FROM' ||
-        previous === 'JOIN' ||
-        previous === ',' ||
-        previous === '(';
-      const next = nextIdentifier(cursor + 1);
+    if (word === 'from') activeFromDepths.add(depth);
+    else if (word !== undefined && clauseEnders.has(word))
+      activeFromDepths.delete(depth);
+    else if (token.text === ')') activeFromDepths.delete(depth + 1);
+    else if (token.text === '(' && activeFromDepths.has(depth)) {
+      const previous = tokens[index - 1]?.text.toLowerCase();
+      const next = tokens[index + 1];
       if (
-        opensTableSource &&
-        activeFromDepths.has(depth) &&
-        next !== undefined &&
-        known.has(next.toLowerCase())
+        previous !== undefined &&
+        ['from', 'join', ',', '('].includes(previous) &&
+        !(
+          next?.kind === 'identifier' &&
+          ['select', 'with', 'values'].includes(next.text.toLowerCase())
+        )
       ) {
         activeFromDepths.add(depth + 1);
       }
-      depth += 1;
-      previous = '(';
-      cursor += 1;
-      continue;
+    } else if (token.text === ',' && activeFromDepths.has(depth)) {
+      throw new TypegenError(
+        'query SQL',
+        'comma-separated table sources are unsupported because reactive proof requires every relation; use an explicit JOIN ... ON clause',
+      );
     }
-    if (char === ')') {
-      activeFromDepths.delete(depth);
-      depth = Math.max(0, depth - 1);
-      previous = ')';
-      cursor += 1;
+  }
+  const ctes: { name: string; start: number; end: number }[] = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token?.kind !== 'identifier' || token.text.toLowerCase() !== 'with')
       continue;
-    }
-    if (char === ',' && activeFromDepths.has(depth)) {
-      const next = nextIdentifier(cursor + 1);
-      if (next !== undefined && known.has(next.toLowerCase())) return true;
-      previous = ',';
+    const scopeEnd = closes.get(parents[index] ?? -1) ?? tokens.length;
+    let cursor = index + 1;
+    if (tokens[cursor]?.text.toLowerCase() === 'recursive') cursor += 1;
+    for (;;) {
+      const name = sqlIdentifier(tokens[cursor]);
+      if (name === undefined) break;
+      cursor += 1;
+      if (tokens[cursor]?.text === '(')
+        cursor = (closes.get(cursor) ?? scopeEnd) + 1;
+      if (tokens[cursor]?.text.toLowerCase() !== 'as') break;
+      cursor += 1;
+      if (tokens[cursor]?.text.toLowerCase() === 'not') cursor += 1;
+      if (tokens[cursor]?.text.toLowerCase() === 'materialized') cursor += 1;
+      if (tokens[cursor]?.text !== '(') break;
+      ctes.push({ name: name.toLowerCase(), start: index, end: scopeEnd });
+      cursor = (closes.get(cursor) ?? scopeEnd) + 1;
+      if (tokens[cursor]?.text !== ',') break;
       cursor += 1;
-      continue;
-    }
-    if (/[A-Za-z_]/.test(char)) {
-      let end = cursor + 1;
-      while (
-        end < cleaned.length &&
-        /[A-Za-z0-9_]/.test(cleaned[end] as string)
-      ) {
-        end += 1;
-      }
-      const word = cleaned.slice(cursor, end).toUpperCase();
-      if (word === 'FROM') activeFromDepths.add(depth);
-      else if (clauseEnders.has(word)) activeFromDepths.delete(depth);
-      previous = word;
-      cursor = end;
-      continue;
     }
-    previous = char;
-    cursor += 1;
   }
-  return false;
-}
-
-export function scanTableRefs(sql: string, ir: IrDocument): TableRef[] {
-  const cleaned = stripCommentsAndStrings(sql);
-  const known = new Map(
-    ir.tables.flatMap((table) => [
-      [table.name.toLowerCase(), table.name] as const,
-      ...table.ftsIndexes.map(
-        (index) => [index.name.toLowerCase(), index.name] as const,
-      ),
-    ]),
-  );
-  const nullableGroups = [
-    ...cleaned.matchAll(/\b(?:LEFT|FULL)(?:\s+OUTER)?\s+JOIN\s*(\()/gi),
-  ].map((match) => {
-    const open = (match.index ?? 0) + match[0].lastIndexOf('(');
-    return { open, close: matchingParenthesis(cleaned, open) };
-  });
   const refs: TableRef[] = [];
   const relationStartByDepth = new Map<number, number>();
-  for (const m of cleaned.matchAll(TABLE_REF_RE)) {
-    const operator = (m[1] as string).toUpperCase();
-    const outerKind = m[2]?.toUpperCase();
-    const rawTable = m[4] as string;
-    const operatorDepth = parenthesisDepthAt(cleaned, m.index ?? 0);
-    const relativeTableIndex = m[0]
-      .toLowerCase()
-      .indexOf(rawTable.toLowerCase(), (m[1] as string).length);
-    const tableIndex =
-      (m.index ?? 0) + Math.max((m[1] as string).length, relativeTableIndex);
-    const tableDepth = parenthesisDepthAt(cleaned, tableIndex);
-    if (operator === 'FROM') {
+  const nullableGroups: { start: number; end: number }[] = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token?.kind !== 'identifier') continue;
+    const operator = token.text.toLowerCase();
+    if (operator !== 'from' && operator !== 'join') continue;
+    let outerKind: string | undefined;
+    if (operator === 'join') {
+      let previous = index - 1;
+      if (tokens[previous]?.text.toLowerCase() === 'outer') previous -= 1;
+      if (tokens[previous]?.kind === 'identifier')
+        outerKind = tokens[previous]?.text.toLowerCase();
+    }
+    const operatorDepth = depths[index] ?? 0;
+    let cursor = index + 1;
+    if (operator === 'from')
       relationStartByDepth.set(operatorDepth, refs.length);
-      relationStartByDepth.set(tableDepth, refs.length);
-    } else if (
-      tableDepth > operatorDepth &&
-      !relationStartByDepth.has(tableDepth)
+    if (outerKind === 'right' || outerKind === 'full') {
+      for (
+        let prior = relationStartByDepth.get(operatorDepth) ?? refs.length;
+        prior < refs.length;
+        prior += 1
+      ) {
+        const ref = refs[prior];
+        if (ref !== undefined) refs[prior] = { ...ref, nullable: true };
+      }
+    }
+    if (
+      (outerKind === 'left' || outerKind === 'full') &&
+      tokens[cursor]?.text === '('
     ) {
-      relationStartByDepth.set(tableDepth, refs.length);
+      nullableGroups.push({
+        start: cursor,
+        end: closes.get(cursor) ?? tokens.length,
+      });
     }
-    if (outerKind === 'RIGHT' || outerKind === 'FULL') {
-      const relationStart =
-        relationStartByDepth.get(operatorDepth) ?? refs.length;
-      for (let index = relationStart; index < refs.length; index += 1) {
-        const prior = refs[index];
-        if (prior !== undefined && !prior.nullable) {
-          refs[index] = { ...prior, nullable: true };
-        }
-      }
+    while (tokens[cursor]?.text === '(') cursor += 1;
+    const tableToken = tokens[cursor];
+    if (
+      tableToken?.kind === 'identifier' &&
+      ['select', 'with', 'values'].includes(tableToken.text.toLowerCase())
+    )
+      continue;
+    const rawTable = sqlIdentifier(tableToken);
+    if (rawTable === undefined || tableToken === undefined) {
+      throw new TypegenError('query SQL', 'cannot resolve table relation');
     }
-    const table = known.get(rawTable.toLowerCase());
-    if (table === undefined) continue; // e.g. a derived SELECT/CTE name
-    let alias = m[5];
-    if (alias !== undefined && RESERVED_ALIAS.has(alias.toLowerCase())) {
-      alias = undefined;
+    if (tokens[cursor + 1]?.text === '.') {
+      throw new TypegenError(
+        'query SQL',
+        'schema-qualified relations are unsupported; use application table names',
+      );
     }
+    if (
+      ctes.some(
+        (cte) =>
+          cte.name === rawTable.toLowerCase() &&
+          cursor > cte.start &&
+          cursor < cte.end,
+      )
+    )
+      continue;
+    const table = known.get(rawTable.toLowerCase());
+    if (table === undefined)
+      throw new TypegenError(
+        'query SQL',
+        `unresolved table relation ${JSON.stringify(rawTable)}`,
+      );
+    const tableDepth = depths[cursor] ?? operatorDepth;
+    if (operator === 'from' || !relationStartByDepth.has(tableDepth))
+      relationStartByDepth.set(tableDepth, refs.length);
+    let aliasToken = tokens[cursor + 1];
+    if (
+      aliasToken?.kind === 'identifier' &&
+      aliasToken.text.toLowerCase() === 'as'
+    )
+      aliasToken = tokens[cursor + 2];
+    const explicitAlias =
+      aliasToken?.kind === 'quoted-identifier' ||
+      (aliasToken?.kind === 'identifier' &&
+        !RESERVED_ALIAS.has(aliasToken.text.toLowerCase()))
+        ? sqlIdentifier(aliasToken)
+        : undefined;
     refs.push({
       table,
-      alias: alias ?? table,
+      start: tableToken.span.start.offset,
+      end: tableToken.span.end.offset,
+      alias: explicitAlias ?? table,
+      ...(explicitAlias === undefined ? {} : { explicitAlias }),
       nullable:
-        outerKind === 'LEFT' ||
-        outerKind === 'FULL' ||
+        outerKind === 'left' ||
+        outerKind === 'full' ||
         nullableGroups.some(
-          (group) => tableIndex > group.open && tableIndex < group.close,
+          (group) => cursor > group.start && cursor < group.end,
         ),
     });
   }
@@ -1486,13 +1519,6 @@ export function analyzeStatement(
   if (sourceSql.length === 0) {
     throw new TypegenError(file, 'query file is empty');
   }
-  if (hasCommaJoinedSchemaTable(sourceSql, ir)) {
-    throw new TypegenError(
-      file,
-      'comma-separated table sources are unsupported because reactive proof requires every relation; use an explicit JOIN ... ON clause',
-    );
-  }
-
   // SELECT-only (the read tier). A `WITH` is allowed when its main statement
   // is a SELECT (SQLite also allows WITH … INSERT/UPDATE/DELETE — writes).
   const firstKeyword = /^\s*([A-Za-z]+)/.exec(
@@ -1695,6 +1721,12 @@ export function analyzeStatement(
     sourceSql,
     sql,
     positionalSql: toPositionalSql(sql),
+    relations: scanTableRefs(toPositionalSql(sql), ir).map((ref) => ({
+      table: ref.table,
+      start: ref.start,
+      end: ref.end,
+      ...(ref.explicitAlias === undefined ? {} : { alias: ref.explicitAlias }),
+    })),
     params,
     columns,
     tables,

package/src/syql-diagnostics.ts

@@ -0,0 +1,160 @@
+import type { SyqlLexErrorCode } from './syql-lexer';
+import type { SyqlLoweringErrorCode } from './syql-lowering';
+import type { SyqlModuleErrorCode } from './syql-modules';
+import type { SyqlParseErrorCode } from './syql-parser';
+import type { SyqlSemanticErrorCode } from './syql-semantics';
+import type { SyqlTemplateParseErrorCode } from './syql-template-parser';
+import type { SyqlValidationErrorCode } from './syql-validator';
+
+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 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.',
+} as const satisfies Readonly<Record<SyqlDiagnosticCode, string>>;
+
+/** Generate a deterministic JSON-ready code-to-remedy catalog. */
+export function generateSyqlDiagnosticCatalog(): Readonly<
+  Array<{ readonly code: SyqlDiagnosticCode; readonly remedy: string }>
+> {
+  return (Object.keys(SYQL_DIAGNOSTIC_REMEDIES) as SyqlDiagnosticCode[])
+    .sort()
+    .map((code) => ({ code, remedy: SYQL_DIAGNOSTIC_REMEDIES[code] }));
+}
+
+/** Resolve a diagnostic remedy without requiring a narrowed code type. */
+export function syqlDiagnosticRemedy(code: string): string | undefined {
+  const remedies: Readonly<Record<string, string>> = SYQL_DIAGNOSTIC_REMEDIES;
+  return remedies[code];
+}

package/src/syql-lowering.ts

@@ -470,6 +470,7 @@ function lowerStatement(
       ...(activationMask === undefined ? {} : { activationMask }),
       sql: namedSql,
       positionalSql: analyzed.positionalSql,
+      relations: analyzed.relations,
       binds: bindNames.map((name) =>
         planBind(
           name,

package/src/syql-validator.ts

@@ -450,7 +450,18 @@ class Validator {
       location,
     );
     this.#validateDeterminism(activeSql, logical.declaration.statement.span);
-    const refs = scanTableRefs(activeSql, this.#ir);
+    let refs: TableRef[];
+    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,