@syncular/typegen 0.15.30 → 0.15.32

package/dist/lsp.js

@@ -289,7 +289,7 @@ export class SyqlLanguageServer {
                 severity: 1,
                 source: 'syncular',
                 code: error.code,
-                message,
+                message: error.detail,
             };
         }
         return {

package/dist/syql-browser.d.ts

@@ -0,0 +1,18 @@
+import type { IrDocument } from './ir.js';
+import { type QueryBackend, type QueryDb, type QueryNamingOptions, synthesizeDdl } from './query.js';
+import { type SyqlLoweredQuery } from './syql-lowering.js';
+export declare const SYQL_BROWSER_DEFAULT_FILE = "/playground.syql";
+export type { IrDocument, QueryDb };
+export { synthesizeDdl };
+export interface CompileSyqlSourceOptions {
+    readonly file?: string;
+    readonly naming?: QueryNamingOptions;
+    readonly backend?: QueryBackend;
+}
+export interface CompiledSyqlSource {
+    readonly queries: readonly SyqlLoweredQuery[];
+}
+/** Compile every query declaration in one virtual source file. */
+export declare function compileSyqlSource(source: string, ir: IrDocument, db: QueryDb, options?: CompileSyqlSourceOptions): CompiledSyqlSource;
+/** Format one virtual source file with the canonical SYQL formatter. */
+export declare function formatSyqlSource(source: string, file?: string): string;

package/dist/syql-browser.js

@@ -0,0 +1,46 @@
+/**
+ * Browser-safe composition boundary for one virtual SYQL source file.
+ *
+ * The parser, semantic analyzer, validator, formatter, and lowerer are all
+ * portable. Filesystem traversal and SQLite initialization are deliberately
+ * left to the host: browsers provide an in-memory QueryDb, while Bun/Node can
+ * keep using the normal project generator.
+ */
+import { formatSyql } from './fmt.js';
+import { synthesizeDdl, } from './query.js';
+import { SyqlFrontendError } from './syql-lexer.js';
+import { lowerSyqlQuery } from './syql-lowering.js';
+import { parseSyqlSyntaxFile } from './syql-parser.js';
+import { analyzeSyqlSemantics } from './syql-semantics.js';
+import { validateSyqlProgram } from './syql-validator.js';
+export const SYQL_BROWSER_DEFAULT_FILE = '/playground.syql';
+export { synthesizeDdl };
+function singleFileGraph(file, source) {
+    const module = parseSyqlSyntaxFile(file, source);
+    const unsupportedImport = module.imports[0];
+    if (unsupportedImport !== undefined) {
+        throw new SyqlFrontendError('PLAYGROUND_IMPORTS_UNAVAILABLE', unsupportedImport.span, 'the browser playground supports one virtual file; declare reusable predicates in the same editor');
+    }
+    return {
+        root: '/',
+        entries: [file],
+        modules: [module],
+        moduleByPath: new Map([[file, module]]),
+        edges: [],
+    };
+}
+/** Compile every query declaration in one virtual source file. */
+export function compileSyqlSource(source, ir, db, options = {}) {
+    const file = options.file ?? SYQL_BROWSER_DEFAULT_FILE;
+    const semantic = analyzeSyqlSemantics(singleFileGraph(file, source));
+    const validated = validateSyqlProgram(semantic, ir, db, options.naming);
+    return {
+        queries: validated.queries.map((query) => lowerSyqlQuery(query, ir, db, options.naming, {
+            ...(options.backend === undefined ? {} : { backend: options.backend }),
+        })),
+    };
+}
+/** Format one virtual source file with the canonical SYQL formatter. */
+export function formatSyqlSource(source, file = SYQL_BROWSER_DEFAULT_FILE) {
+    return formatSyql(file, source);
+}

package/dist/syql-lexer.d.ts

@@ -31,6 +31,8 @@ export type SyqlLexErrorCode = 'SYQL1001_UNTERMINATED_STRING' | 'SYQL1002_UNTERM
 /** A source-spanned, stable-code error shared by the lexer and parser. */
 export declare class SyqlFrontendError extends TypegenError {
     readonly code: string;
+    /** Human-readable diagnostic without the location/code prefix in `message`. */
+    readonly detail: string;
     readonly span: SyqlSourceSpan;
     readonly sourceFile: string;
     constructor(code: string, span: SyqlSourceSpan, message: string);

package/dist/syql-lexer.js

@@ -9,12 +9,15 @@ import { TypegenError } from './errors.js';
 /** A source-spanned, stable-code error shared by the lexer and parser. */
 export class SyqlFrontendError extends TypegenError {
     code;
+    /** Human-readable diagnostic without the location/code prefix in `message`. */
+    detail;
     span;
     sourceFile;
     constructor(code, span, message) {
         super(`${span.file}:${span.start.line}:${span.start.column}`, `${code}: ${message}`);
         this.name = 'SyqlFrontendError';
         this.code = code;
+        this.detail = message;
         this.span = span;
         this.sourceFile = span.file;
     }

package/dist/syql-validator.js

@@ -3,6 +3,7 @@ import { isSyqlTrivia, lexSyqlSqlSource, SyqlFrontendError, } from './syql-lexer
 import { syqlRangeEndBind, syqlRangeStartBind } from './syql-semantics.js';
 const IDENT_SOURCE = '[A-Za-z_][A-Za-z0-9_]*';
 const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SQLITE_SUBJECT_RE = '[A-Za-z_][A-Za-z0-9_$]*';
 const NONDETERMINISTIC_FUNCTIONS = new Set([
     'random',
     'randomblob',
@@ -26,6 +27,49 @@ const CURRENT_TIME_KEYWORDS = new Set([
     'current_time',
     'current_timestamp',
 ]);
+function editDistance(left, right) {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+        const current = [leftIndex];
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+            current[rightIndex] = Math.min(current[rightIndex - 1] + 1, previous[rightIndex] + 1, previous[rightIndex - 1] +
+                (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1));
+        }
+        previous.splice(0, previous.length, ...current);
+    }
+    return previous[right.length];
+}
+function nearestName(authored, candidates) {
+    const normalized = authored.toLowerCase();
+    const ranked = [...new Set(candidates)]
+        .filter((candidate) => candidate.toLowerCase() !== normalized)
+        .map((candidate) => ({
+        candidate,
+        distance: editDistance(normalized, candidate.toLowerCase()),
+    }))
+        .sort((left, right) => left.distance - right.distance ||
+        left.candidate.localeCompare(right.candidate));
+    const nearest = ranked[0];
+    if (nearest === undefined)
+        return undefined;
+    const threshold = Math.max(1, Math.floor(normalized.length / 3));
+    return nearest.distance <= threshold ? nearest.candidate : undefined;
+}
+function suggestion(authored, candidates) {
+    const nearest = nearestName(authored, candidates);
+    return nearest === undefined ? '' : `; did you mean \`${nearest}\`?`;
+}
+function identifierText(token) {
+    if (token?.kind === 'identifier')
+        return token.text;
+    if (token?.kind !== 'quoted-identifier')
+        return undefined;
+    if (token.text.startsWith('[') && token.text.endsWith(']')) {
+        return token.text.slice(1, -1).replaceAll(']]', ']');
+    }
+    const quote = token.text[0];
+    return token.text.slice(1, -1).replaceAll(`${quote}${quote}`, quote ?? '');
+}
 const AGGREGATE_FUNCTIONS = new Set([
     'avg',
     'count',
@@ -261,6 +305,7 @@ class Validator {
         this.#validateDeterminism(activeSql, logical.declaration.statement.span);
         const refs = scanTableRefs(activeSql, this.#ir);
         this.#validatePortableProfile(activeSql, logical.declaration.statement.span, refs);
+        this.#validateSqlite(activeSql, logical, refs);
         const bindSymbols = this.#bindSymbols(logical.declaration);
         const bindTypes = this.#resolveBindTypes(logical, activeSql, refs, bindSymbols);
         const sort = this.#validateSort(logical.declaration, activeStructure, location);
@@ -573,6 +618,134 @@ class Validator {
             }
         }
     }
+    #validateSqlite(sql, logical, refs) {
+        try {
+            this.#db.analyze(sql);
+        }
+        catch (error) {
+            const sqliteMessage = error instanceof Error ? error.message : String(error);
+            const diagnostic = this.#describeSqliteError(sqliteMessage, logical, refs);
+            this.#fail('SYQL6002_INVALID_SQL', diagnostic.span, diagnostic.message);
+        }
+    }
+    #describeSqliteError(sqliteMessage, logical, refs) {
+        const fallback = logical.declaration.statement.span;
+        const tableNames = this.#ir.tables.flatMap((table) => [
+            table.name,
+            ...table.ftsIndexes.map((index) => index.name),
+        ]);
+        const noTable = new RegExp(`no such table:\\s*(?:main\\.)?(${SQLITE_SUBJECT_RE})`, 'i').exec(sqliteMessage);
+        if (noTable !== null) {
+            const table = noTable[1];
+            return {
+                span: this.#sqlSubjectSpan(logical, table, 'table') ?? fallback,
+                message: `unknown table \`${table}\`${suggestion(table, tableNames)}`,
+            };
+        }
+        const noColumn = new RegExp(`no such column:\\s*(${SQLITE_SUBJECT_RE})(?:\\.(${SQLITE_SUBJECT_RE}))?`, 'i').exec(sqliteMessage);
+        if (noColumn !== null) {
+            const first = noColumn[1];
+            const second = noColumn[2];
+            if (second !== undefined) {
+                const qualifier = first;
+                const ref = refs.find((candidate) => candidate.alias.toLowerCase() === qualifier.toLowerCase());
+                if (ref === undefined) {
+                    const qualifiers = refs.map((candidate) => candidate.alias);
+                    return {
+                        span: this.#sqlSubjectSpan(logical, `${qualifier}.${second}`, 'qualifier') ?? fallback,
+                        message: `unknown table or alias \`${qualifier}\`${suggestion(qualifier, qualifiers)}`,
+                    };
+                }
+                const columns = this.#columnsForTable(ref.table);
+                return {
+                    span: this.#sqlSubjectSpan(logical, `${qualifier}.${second}`, 'column') ??
+                        fallback,
+                    message: `unknown column \`${second}\` on \`${qualifier}\`${suggestion(second, columns)}`,
+                };
+            }
+            const columns = refs.flatMap((ref) => this.#columnsForTable(ref.table));
+            return {
+                span: this.#sqlSubjectSpan(logical, first, 'column') ?? fallback,
+                message: `unknown column \`${first}\`${suggestion(first, columns)}`,
+            };
+        }
+        const ambiguous = new RegExp(`ambiguous column name:\\s*(?:${SQLITE_SUBJECT_RE}\\.)?(${SQLITE_SUBJECT_RE})`, 'i').exec(sqliteMessage);
+        if (ambiguous !== null) {
+            const column = ambiguous[1];
+            const choices = refs
+                .filter((ref) => this.#columnsForTable(ref.table).some((candidate) => candidate.toLowerCase() === column.toLowerCase()))
+                .map((ref) => `\`${ref.alias}.${column}\``);
+            return {
+                span: this.#sqlSubjectSpan(logical, column, 'column') ?? fallback,
+                message: `column \`${column}\` is ambiguous${choices.length === 0
+                    ? '; add a table or alias qualifier'
+                    : `; use ${choices.join(' or ')}`}`,
+            };
+        }
+        const syntax = /near\s+["']([^"']+)["']:\s*syntax error/i.exec(sqliteMessage);
+        if (syntax !== null) {
+            const token = syntax[1];
+            return {
+                span: this.#sqlSubjectSpan(logical, token, 'token') ?? fallback,
+                message: `SQL syntax error near \`${token}\``,
+            };
+        }
+        if (/incomplete input/i.test(sqliteMessage)) {
+            return {
+                span: {
+                    file: fallback.file,
+                    start: fallback.end,
+                    end: fallback.end,
+                },
+                message: 'incomplete SQL statement',
+            };
+        }
+        return {
+            span: fallback,
+            message: `SQL rejected by SQLite: ${sqliteMessage}`,
+        };
+    }
+    #columnsForTable(tableName) {
+        const table = this.#ir.tables.find((candidate) => candidate.name === tableName);
+        if (table !== undefined)
+            return table.columns.map((column) => column.name);
+        for (const owner of this.#ir.tables) {
+            const fts = owner.ftsIndexes.find((candidate) => candidate.name === tableName);
+            if (fts !== undefined)
+                return ['_syncular_source_id', ...fts.columns];
+        }
+        return [];
+    }
+    #sqlSubjectSpan(logical, subject, focus) {
+        const tokens = significant(logical.declaration.statement.tokens);
+        const [qualifier, column] = subject.split('.', 2);
+        const matches = (token, expected) => identifierText(token)?.toLowerCase() === expected.toLowerCase();
+        if (focus === 'table') {
+            for (let index = 0; index < tokens.length - 1; index += 1) {
+                const keyword = tokenLower(tokens[index]);
+                if ((keyword === 'from' || keyword === 'join') &&
+                    matches(tokens[index + 1], subject)) {
+                    return tokens[index + 1]?.span;
+                }
+            }
+        }
+        if (column !== undefined) {
+            for (let index = 0; index < tokens.length - 2; index += 1) {
+                if (matches(tokens[index], qualifier) &&
+                    tokens[index + 1]?.text === '.' &&
+                    matches(tokens[index + 2], column)) {
+                    return focus === 'qualifier'
+                        ? tokens[index]?.span
+                        : tokens[index + 2]?.span;
+                }
+            }
+        }
+        for (const token of tokens) {
+            if (matches(token, subject))
+                return token.span;
+        }
+        return undefined;
+    }
     #bindSymbols(query) {
         const symbols = new Map();
         for (const parameter of query.parameters) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/typegen",
-  "version": "0.15.30",
+  "version": "0.15.32",
   "description": "Syncular schema-to-TypeScript type generator and the `syncular` CLI",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -36,6 +36,14 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
+    },
+    "./syql-browser": {
+      "bun": "./src/syql-browser.ts",
+      "browser": "./dist/syql-browser.js",
+      "import": {
+        "types": "./dist/syql-browser.d.ts",
+        "default": "./dist/syql-browser.js"
+      }
     }
   },
   "files": [
@@ -48,7 +56,7 @@
     "!dist/**/*.test.d.ts"
   ],
   "devDependencies": {
-    "@syncular/core": "0.15.30",
-    "@syncular/server": "0.15.30"
+    "@syncular/core": "0.15.32",
+    "@syncular/server": "0.15.32"
   }
 }

package/src/lsp.ts

@@ -379,7 +379,7 @@ export class SyqlLanguageServer {
         severity: 1,
         source: 'syncular',
         code: error.code,
-        message,
+        message: error.detail,
       };
     }
     return {

package/src/syql-browser.ts

@@ -0,0 +1,83 @@
+/**
+ * Browser-safe composition boundary for one virtual SYQL source file.
+ *
+ * The parser, semantic analyzer, validator, formatter, and lowerer are all
+ * portable. Filesystem traversal and SQLite initialization are deliberately
+ * left to the host: browsers provide an in-memory QueryDb, while Bun/Node can
+ * keep using the normal project generator.
+ */
+import { formatSyql } from './fmt';
+import type { IrDocument } from './ir';
+import {
+  type QueryBackend,
+  type QueryDb,
+  type QueryNamingOptions,
+  synthesizeDdl,
+} from './query';
+import { SyqlFrontendError } from './syql-lexer';
+import { lowerSyqlQuery, type SyqlLoweredQuery } from './syql-lowering';
+import type { SyqlModuleGraph } from './syql-modules';
+import { parseSyqlSyntaxFile } from './syql-parser';
+import { analyzeSyqlSemantics } from './syql-semantics';
+import { validateSyqlProgram } from './syql-validator';
+
+export const SYQL_BROWSER_DEFAULT_FILE = '/playground.syql';
+
+export type { IrDocument, QueryDb };
+export { synthesizeDdl };
+
+export interface CompileSyqlSourceOptions {
+  readonly file?: string;
+  readonly naming?: QueryNamingOptions;
+  readonly backend?: QueryBackend;
+}
+
+export interface CompiledSyqlSource {
+  readonly queries: readonly SyqlLoweredQuery[];
+}
+
+function singleFileGraph(file: string, source: string): SyqlModuleGraph {
+  const module = parseSyqlSyntaxFile(file, source);
+  const unsupportedImport = module.imports[0];
+  if (unsupportedImport !== undefined) {
+    throw new SyqlFrontendError(
+      'PLAYGROUND_IMPORTS_UNAVAILABLE',
+      unsupportedImport.span,
+      'the browser playground supports one virtual file; declare reusable predicates in the same editor',
+    );
+  }
+  return {
+    root: '/',
+    entries: [file],
+    modules: [module],
+    moduleByPath: new Map([[file, module]]),
+    edges: [],
+  };
+}
+
+/** Compile every query declaration in one virtual source file. */
+export function compileSyqlSource(
+  source: string,
+  ir: IrDocument,
+  db: QueryDb,
+  options: CompileSyqlSourceOptions = {},
+): CompiledSyqlSource {
+  const file = options.file ?? SYQL_BROWSER_DEFAULT_FILE;
+  const semantic = analyzeSyqlSemantics(singleFileGraph(file, source));
+  const validated = validateSyqlProgram(semantic, ir, db, options.naming);
+  return {
+    queries: validated.queries.map((query) =>
+      lowerSyqlQuery(query, ir, db, options.naming, {
+        ...(options.backend === undefined ? {} : { backend: options.backend }),
+      }),
+    ),
+  };
+}
+
+/** Format one virtual source file with the canonical SYQL formatter. */
+export function formatSyqlSource(
+  source: string,
+  file = SYQL_BROWSER_DEFAULT_FILE,
+): string {
+  return formatSyql(file, source);
+}

package/src/syql-lexer.ts

@@ -55,6 +55,8 @@ export type SyqlLexErrorCode =
 /** A source-spanned, stable-code error shared by the lexer and parser. */
 export class SyqlFrontendError extends TypegenError {
   readonly code: string;
+  /** Human-readable diagnostic without the location/code prefix in `message`. */
+  readonly detail: string;
   readonly span: SyqlSourceSpan;
   readonly sourceFile: string;
 
@@ -65,6 +67,7 @@ export class SyqlFrontendError extends TypegenError {
     );
     this.name = 'SyqlFrontendError';
     this.code = code;
+    this.detail = message;
     this.span = span;
     this.sourceFile = span.file;
   }

package/src/syql-validator.ts

@@ -101,8 +101,14 @@ interface BindSymbol {
   readonly authoredType?: SyqlValueType;
 }
 
+interface SqliteDiagnostic {
+  readonly span: SyqlSourceSpan;
+  readonly message: string;
+}
+
 const IDENT_SOURCE = '[A-Za-z_][A-Za-z0-9_]*';
 const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SQLITE_SUBJECT_RE = '[A-Za-z_][A-Za-z0-9_$]*';
 const NONDETERMINISTIC_FUNCTIONS = new Set([
   'random',
   'randomblob',
@@ -126,6 +132,63 @@ const CURRENT_TIME_KEYWORDS = new Set([
   'current_time',
   'current_timestamp',
 ]);
+
+function editDistance(left: string, right: string): number {
+  const previous = Array.from(
+    { length: right.length + 1 },
+    (_, index) => index,
+  );
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      current[rightIndex] = Math.min(
+        (current[rightIndex - 1] as number) + 1,
+        (previous[rightIndex] as number) + 1,
+        (previous[rightIndex - 1] as number) +
+          (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1),
+      );
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[right.length] as number;
+}
+
+function nearestName(
+  authored: string,
+  candidates: readonly string[],
+): string | undefined {
+  const normalized = authored.toLowerCase();
+  const ranked = [...new Set(candidates)]
+    .filter((candidate) => candidate.toLowerCase() !== normalized)
+    .map((candidate) => ({
+      candidate,
+      distance: editDistance(normalized, candidate.toLowerCase()),
+    }))
+    .sort(
+      (left, right) =>
+        left.distance - right.distance ||
+        left.candidate.localeCompare(right.candidate),
+    );
+  const nearest = ranked[0];
+  if (nearest === undefined) return undefined;
+  const threshold = Math.max(1, Math.floor(normalized.length / 3));
+  return nearest.distance <= threshold ? nearest.candidate : undefined;
+}
+
+function suggestion(authored: string, candidates: readonly string[]): string {
+  const nearest = nearestName(authored, candidates);
+  return nearest === undefined ? '' : `; did you mean \`${nearest}\`?`;
+}
+
+function identifierText(token: SyqlToken | undefined): string | undefined {
+  if (token?.kind === 'identifier') return token.text;
+  if (token?.kind !== 'quoted-identifier') return undefined;
+  if (token.text.startsWith('[') && token.text.endsWith(']')) {
+    return token.text.slice(1, -1).replaceAll(']]', ']');
+  }
+  const quote = token.text[0];
+  return token.text.slice(1, -1).replaceAll(`${quote}${quote}`, quote ?? '');
+}
 const AGGREGATE_FUNCTIONS = new Set([
   'avg',
   'count',
@@ -393,6 +456,7 @@ class Validator {
       logical.declaration.statement.span,
       refs,
     );
+    this.#validateSqlite(activeSql, logical, refs);
 
     const bindSymbols = this.#bindSymbols(logical.declaration);
     const bindTypes = this.#resolveBindTypes(
@@ -898,6 +962,190 @@ class Validator {
     }
   }
 
+  #validateSqlite(
+    sql: string,
+    logical: SyqlLogicalQuery,
+    refs: readonly TableRef[],
+  ): void {
+    try {
+      this.#db.analyze(sql);
+    } catch (error) {
+      const sqliteMessage =
+        error instanceof Error ? error.message : String(error);
+      const diagnostic = this.#describeSqliteError(
+        sqliteMessage,
+        logical,
+        refs,
+      );
+      this.#fail('SYQL6002_INVALID_SQL', diagnostic.span, diagnostic.message);
+    }
+  }
+
+  #describeSqliteError(
+    sqliteMessage: string,
+    logical: SyqlLogicalQuery,
+    refs: readonly TableRef[],
+  ): SqliteDiagnostic {
+    const fallback = logical.declaration.statement.span;
+    const tableNames = this.#ir.tables.flatMap((table) => [
+      table.name,
+      ...table.ftsIndexes.map((index) => index.name),
+    ]);
+    const noTable = new RegExp(
+      `no such table:\\s*(?:main\\.)?(${SQLITE_SUBJECT_RE})`,
+      'i',
+    ).exec(sqliteMessage);
+    if (noTable !== null) {
+      const table = noTable[1] as string;
+      return {
+        span: this.#sqlSubjectSpan(logical, table, 'table') ?? fallback,
+        message: `unknown table \`${table}\`${suggestion(table, tableNames)}`,
+      };
+    }
+
+    const noColumn = new RegExp(
+      `no such column:\\s*(${SQLITE_SUBJECT_RE})(?:\\.(${SQLITE_SUBJECT_RE}))?`,
+      'i',
+    ).exec(sqliteMessage);
+    if (noColumn !== null) {
+      const first = noColumn[1] as string;
+      const second = noColumn[2];
+      if (second !== undefined) {
+        const qualifier = first;
+        const ref = refs.find(
+          (candidate) =>
+            candidate.alias.toLowerCase() === qualifier.toLowerCase(),
+        );
+        if (ref === undefined) {
+          const qualifiers = refs.map((candidate) => candidate.alias);
+          return {
+            span:
+              this.#sqlSubjectSpan(
+                logical,
+                `${qualifier}.${second}`,
+                'qualifier',
+              ) ?? fallback,
+            message: `unknown table or alias \`${qualifier}\`${suggestion(qualifier, qualifiers)}`,
+          };
+        }
+        const columns = this.#columnsForTable(ref.table);
+        return {
+          span:
+            this.#sqlSubjectSpan(logical, `${qualifier}.${second}`, 'column') ??
+            fallback,
+          message: `unknown column \`${second}\` on \`${qualifier}\`${suggestion(second, columns)}`,
+        };
+      }
+      const columns = refs.flatMap((ref) => this.#columnsForTable(ref.table));
+      return {
+        span: this.#sqlSubjectSpan(logical, first, 'column') ?? fallback,
+        message: `unknown column \`${first}\`${suggestion(first, columns)}`,
+      };
+    }
+
+    const ambiguous = new RegExp(
+      `ambiguous column name:\\s*(?:${SQLITE_SUBJECT_RE}\\.)?(${SQLITE_SUBJECT_RE})`,
+      'i',
+    ).exec(sqliteMessage);
+    if (ambiguous !== null) {
+      const column = ambiguous[1] as string;
+      const choices = refs
+        .filter((ref) =>
+          this.#columnsForTable(ref.table).some(
+            (candidate) => candidate.toLowerCase() === column.toLowerCase(),
+          ),
+        )
+        .map((ref) => `\`${ref.alias}.${column}\``);
+      return {
+        span: this.#sqlSubjectSpan(logical, column, 'column') ?? fallback,
+        message: `column \`${column}\` is ambiguous${
+          choices.length === 0
+            ? '; add a table or alias qualifier'
+            : `; use ${choices.join(' or ')}`
+        }`,
+      };
+    }
+
+    const syntax = /near\s+["']([^"']+)["']:\s*syntax error/i.exec(
+      sqliteMessage,
+    );
+    if (syntax !== null) {
+      const token = syntax[1] as string;
+      return {
+        span: this.#sqlSubjectSpan(logical, token, 'token') ?? fallback,
+        message: `SQL syntax error near \`${token}\``,
+      };
+    }
+    if (/incomplete input/i.test(sqliteMessage)) {
+      return {
+        span: {
+          file: fallback.file,
+          start: fallback.end,
+          end: fallback.end,
+        },
+        message: 'incomplete SQL statement',
+      };
+    }
+    return {
+      span: fallback,
+      message: `SQL rejected by SQLite: ${sqliteMessage}`,
+    };
+  }
+
+  #columnsForTable(tableName: string): readonly string[] {
+    const table = this.#ir.tables.find(
+      (candidate) => candidate.name === tableName,
+    );
+    if (table !== undefined) return table.columns.map((column) => column.name);
+    for (const owner of this.#ir.tables) {
+      const fts = owner.ftsIndexes.find(
+        (candidate) => candidate.name === tableName,
+      );
+      if (fts !== undefined) return ['_syncular_source_id', ...fts.columns];
+    }
+    return [];
+  }
+
+  #sqlSubjectSpan(
+    logical: SyqlLogicalQuery,
+    subject: string,
+    focus: 'table' | 'qualifier' | 'column' | 'token',
+  ): SyqlSourceSpan | undefined {
+    const tokens = significant(logical.declaration.statement.tokens);
+    const [qualifier, column] = subject.split('.', 2);
+    const matches = (token: SyqlToken | undefined, expected: string): boolean =>
+      identifierText(token)?.toLowerCase() === expected.toLowerCase();
+
+    if (focus === 'table') {
+      for (let index = 0; index < tokens.length - 1; index += 1) {
+        const keyword = tokenLower(tokens[index]);
+        if (
+          (keyword === 'from' || keyword === 'join') &&
+          matches(tokens[index + 1], subject)
+        ) {
+          return tokens[index + 1]?.span;
+        }
+      }
+    }
+    if (column !== undefined) {
+      for (let index = 0; index < tokens.length - 2; index += 1) {
+        if (
+          matches(tokens[index], qualifier as string) &&
+          tokens[index + 1]?.text === '.' &&
+          matches(tokens[index + 2], column)
+        ) {
+          return focus === 'qualifier'
+            ? tokens[index]?.span
+            : tokens[index + 2]?.span;
+        }
+      }
+    }
+    for (const token of tokens) {
+      if (matches(token, subject)) return token.span;
+    }
+    return undefined;
+  }
+
   #bindSymbols(query: SyqlQueryDeclaration): ReadonlyMap<string, BindSymbol> {
     const symbols = new Map<string, BindSymbol>();
     for (const parameter of query.parameters) {