@syncular/typegen 0.2.0 → 0.3.0

package/src/query.ts

@@ -48,7 +48,7 @@
  * error listing the fix. bun:sqlite can't name params, so we parse `:name`
  * tokens from the SQL ourselves (first-occurrence order = positional order).
  *
- * ## The tables set (for useSyncQuery `{tables}` — exact invalidation)
+ * ## The tables set (for useRawSql `{tables}` — exact invalidation)
  *
  * bun:sqlite exposes no authorizer and no statement table-list; EXPLAIN
  * opcodes are fragile. The honest mechanism: the FROM/JOIN table set we
@@ -62,6 +62,8 @@
  */
 import { TypegenError } from './errors';
 import type { IrColumnType, IrDocument, IrTable } from './ir';
+import { lowerProjection, mainVerbAfterWith } from './lower';
+import { buildNamingMap, type NamingMode, type NamingTarget } from './naming';
 
 /** The SQL decltype keyword → §2.4 type map (mirrors sql.ts TYPE_MAP so a
  * plain column ref's decltype resolves to the exact IR type). */
@@ -89,14 +91,45 @@ const DECLTYPE_MAP: Readonly<Record<string, IrColumnType>> = {
 export type QueryParamType = IrColumnType;
 
 export interface QueryParam {
+  /** SQL-truth `:name` (as authored). */
   readonly name: string;
+  /** Language-facing name (§5 naming map; equals `name` under "preserve"). */
+  readonly langName: string;
   readonly type: QueryParamType;
   /** How the type was resolved — for the docs/tests, not emitted. */
   readonly source: 'inferred' | 'comment';
+  /** §4 (DESIGN-queries.md): an optional param — its auto-guarded conjunct
+   * applies only when it is provided. Always false for the `.sql` tier. */
+  readonly optional?: boolean;
+  /** §4: the `from+to` pairing — params sharing a group apply together. */
+  readonly group?: string;
+  /** §3: a `: flag` boolean guard param (never in a predicate as written;
+   * the lowering binds it). Implies optional. */
+  readonly flag?: boolean;
+}
+
+/** §6 orderBy knob: a generate-time allowlist (identifiers cannot bind). */
+export interface QueryOrderBy {
+  /** Allowed columns: authored SQL name + the language-facing key the
+   * generated signature accepts. Each is SQLite-checked at generate time. */
+  readonly allowed: readonly { name: string; langName: string }[];
+  /** Default column (authored SQL name). */
+  readonly defaultColumn: string;
+  readonly defaultDir: 'asc' | 'desc';
+}
+
+/** §6 limit knob: a bound value with a codegen clamp + default. */
+export interface QueryLimit {
+  readonly max?: number;
+  readonly default?: number;
 }
 
 export interface QueryColumn {
+  /** SQL-truth result name (pre-lowering, as authored). */
   readonly name: string;
+  /** Language-facing name — the RUNTIME result key after §5 projection
+   * lowering (equals `name` under "preserve"). */
+  readonly langName: string;
   readonly type: IrColumnType;
   readonly nullable: boolean;
   /** `exact` = resolved to an IR column (plain ref); `fallback` = a computed
@@ -104,22 +137,78 @@ export interface QueryColumn {
   readonly fidelity: 'exact' | 'fallback';
 }
 
+/** §7/§8 backend selection: neutralization (default), always-variants, or
+ * the small-N heuristic (`auto`: enumerate at ≤ 2 optional groups). */
+export type QueryBackend = 'neutralize' | 'variants' | 'auto';
+
+/** Naming/backend options threaded from the manifest into query analysis. */
+export interface QueryNamingOptions {
+  readonly naming: NamingMode;
+  /** Emitter targets this run generates — keyword hazards are only real on
+   * targets that exist. */
+  readonly targets: readonly NamingTarget[];
+  /** `.syql` conditional-lowering backend (default `neutralize`); the
+   * per-query `variants` knob always forces enumeration. */
+  readonly backend?: QueryBackend;
+}
+
+const DEFAULT_NAMING: QueryNamingOptions = { naming: 'camel', targets: ['ts'] };
+
 export interface AnalyzedQuery {
   /** camelCase function name (path-derived, or a `-- name:` override). */
   readonly name: string;
   /** Source location for errors, e.g. `billing/list.sql` (or `list.sql#2`
    * for the 2nd statement of a multi-statement file). */
   readonly file: string;
-  /** The SQL as written (named `:params`), trimmed. */
+  /** The SQL as authored (named `:params`), trimmed — pre-lowering. */
+  readonly sourceSql: string;
+  /** The LOWERED SQL (named `:params`): §5 projection aliasing applied, so
+   * runtime result keys are the language-facing names. Equals `sourceSql`
+   * when nothing needed rewriting. */
   readonly sql: string;
-  /** The SQL with `:name` rewritten to positional `?` (wrapper surface). */
+  /** The lowered SQL with `:name` rewritten to positional `?`. */
   readonly positionalSql: string;
   /** Params in first-occurrence (positional) order. */
   readonly params: readonly QueryParam[];
   /** Result columns in SELECT order. */
   readonly columns: readonly QueryColumn[];
-  /** IR tables this query reads (the useSyncQuery `{tables}` set), sorted. */
+  /** IR tables this query reads (the useRawSql `{tables}` set), sorted. */
   readonly tables: readonly string[];
+  /** §6 orderBy knob (`.syql` tier). When present, `sql`/`positionalSql`
+   * carry the DEFAULT order-by tail and `positionalSqlBase` is the static
+   * prefix emitters compose the selected column onto. */
+  readonly orderBy?: QueryOrderBy;
+  /** §6 limit knob (`.syql` tier): the trailing `LIMIT ?` bind's clamp. */
+  readonly limit?: QueryLimit;
+  /** positional SQL WITHOUT the dynamic ORDER BY/LIMIT tail; present only
+   * when `orderBy` is (emitters build `base + ORDER BY <baked> + limit
+   * tail`). */
+  readonly positionalSqlBase?: string;
+  /** The positional limit tail (e.g. ` limit min(coalesce(?, 50), 100)` —
+   * the default+clamp live IN the SQL, so runtimes bind `limit ?? null`).
+   * Present only when BOTH knobs are declared (composers need it verbatim). */
+  readonly positionalLimitTail?: string;
+  /** §7 variant-enumeration backend (opt-in `variants` knob): one checked
+   * statement per combination of provided optional groups. Semantically
+   * identical to the neutralization `sql` by construction; the TS emitter
+   * dispatches on provided-ness for perfect index use. `when` lists the
+   * provided group keys; `params` are the DISTINCT param names this variant
+   * binds, positional order. */
+  readonly variants?: readonly {
+    readonly when: readonly string[];
+    readonly sql: string;
+    readonly positionalSql: string;
+    readonly params: readonly string[];
+  }[];
+  /** The optional-group keys, in dispatch-bit order (bit i of the variant
+   * index = group i provided). Present iff `variants` is. */
+  readonly variantGroups?: readonly {
+    readonly key: string;
+    /** Params whose provision defines the group (all must be non-null; a
+     * flag group is "on" when its single param is TRUE). */
+    readonly params: readonly string[];
+    readonly flag: boolean;
+  }[];
 }
 
 // -- path → name --------------------------------------------------------------
@@ -422,12 +511,21 @@ function scanParamNames(sql: string): string[] {
   return seen;
 }
 
-/** Rewrite `:name` → positional `?` (repeats included) AND strip comments +
- * collapse whitespace, producing a clean single-line SQL string suitable for
+/** Rewrite `:name` → positional placeholders AND strip comments + collapse
+ * whitespace, producing a clean single-line SQL string suitable for
  * embedding in a generated string literal. String literals are preserved
- * verbatim (their inner whitespace is not collapsed). */
-function toPositionalSql(sql: string): string {
-  const tokens: string[] = [];
+ * verbatim (their inner whitespace is not collapsed).
+ *
+ * When every param occurs exactly once, plain `?` is emitted. When ANY
+ * param repeats (the §7 neutralization guards mention a param in the guard
+ * AND the predicate), the WHOLE statement uses SQLite's numbered `?N`
+ * form — one bound value per DISTINCT param, reuse resolved by SQLite —
+ * so the generated bind array stays one-entry-per-param. */
+export function toPositionalSql(sql: string): string {
+  interface ParamToken {
+    readonly param: string;
+  }
+  const tokens: (string | ParamToken)[] = [];
   let i = 0;
   while (i < sql.length) {
     const ch = sql[i] as string;
@@ -467,7 +565,7 @@ function toPositionalSql(sql: string): string {
       while (end < sql.length && /[A-Za-z0-9_]/.test(sql[end] as string)) {
         end += 1;
       }
-      tokens.push('?');
+      tokens.push({ param: sql.slice(i + 1, end) });
       i = end;
     } else if (/\s/.test(ch)) {
       tokens.push(' ');
@@ -477,8 +575,21 @@ function toPositionalSql(sql: string): string {
       i += 1;
     }
   }
+  const order: string[] = [];
+  let repeats = false;
+  for (const token of tokens) {
+    if (typeof token === 'string') continue;
+    if (order.includes(token.param)) repeats = true;
+    else order.push(token.param);
+  }
+  const rendered = tokens
+    .map((token) => {
+      if (typeof token === 'string') return token;
+      return repeats ? `?${order.indexOf(token.param) + 1}` : '?';
+    })
+    .join('');
   // Collapse runs of the whitespace placeholders; trim.
-  return tokens.join('').replace(/\s+/g, ' ').trim();
+  return rendered.replace(/\s+/g, ' ').trim();
 }
 
 // -- FROM/JOIN table resolution ----------------------------------------------
@@ -671,6 +782,31 @@ function inferParamType(
     const t = lookup(inM[1], inM[2] as string);
     if (t !== null) return t;
   }
+  // `col BETWEEN :name AND …` / `col BETWEEN … AND :name` — both endpoints
+  // take the column's type (the §4 from+to group shape).
+  const btwLeft = new RegExp(
+    `(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+:${paramName}\\b`,
+    'i',
+  );
+  const btwLeftM = btwLeft.exec(cleaned);
+  if (btwLeftM !== null) {
+    const t = lookup(btwLeftM[1], btwLeftM[2] as string);
+    if (t !== null) return t;
+  }
+  const btwRight = new RegExp(
+    `(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+\\S+\\s+AND\\s+:${paramName}\\b`,
+    'i',
+  );
+  const btwRightM = btwRight.exec(cleaned);
+  if (btwRightM !== null) {
+    const t = lookup(btwRightM[1], btwRightM[2] as string);
+    if (t !== null) return t;
+  }
+  // `… LIKE <expr mentioning :name>` — a LIKE operand is TEXT, even inside
+  // a concatenation (`title like '%' || :q || '%'`, the search-fragment
+  // shape).
+  const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'i');
+  if (like.test(cleaned)) return 'string';
   return null;
 }
 
@@ -747,36 +883,49 @@ export function analyzeStatement(
   statementText: string,
   ir: IrDocument,
   db: QueryDb,
+  naming: QueryNamingOptions = DEFAULT_NAMING,
 ): AnalyzedQuery {
   const file = location;
   const commentParams = parseCommentParams(file, statementText);
-  const sql = statementText.trim();
-  if (sql.length === 0) {
+  const sourceSql = statementText.trim();
+  if (sourceSql.length === 0) {
     throw new TypegenError(file, 'query file is empty');
   }
 
-  // SELECT-only (the read tier). Reject the first keyword loudly otherwise.
+  // 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(
     stripCommentsAndStrings(statementText).trimStart(),
   )?.[1];
-  if (firstKeyword === undefined || firstKeyword.toUpperCase() !== 'SELECT') {
+  const upperKeyword = firstKeyword?.toUpperCase();
+  if (upperKeyword === 'WITH') {
+    const main = mainVerbAfterWith(stripCommentsAndStrings(statementText));
+    if (main !== 'SELECT') {
+      throw new TypegenError(
+        file,
+        `named queries are SELECT-only (the read tier); this WITH statement's main verb is ${JSON.stringify(main ?? '')}. Writes go through mutate() (SPEC §7.1).`,
+      );
+    }
+  } else if (upperKeyword !== 'SELECT') {
     throw new TypegenError(
       file,
       `named queries are SELECT-only (the read tier); found ${JSON.stringify(firstKeyword ?? '')}. Writes go through mutate() (SPEC §7.1).`,
     );
   }
 
-  // Let SQLite validate + describe the query. Any bad reference throws here
-  // with SQLite's own message (which names the offending table/column).
-  let described: ReturnType<QueryDb['analyze']>;
-  try {
-    described = db.analyze(sql);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new TypegenError(file, `SQL rejected by SQLite: ${message}`);
-  }
+  // Let SQLite validate + describe the AUTHORED query first. Any bad
+  // reference throws here with SQLite's own message.
+  const analyze = (candidate: string): ReturnType<QueryDb['analyze']> => {
+    try {
+      return db.analyze(candidate);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new TypegenError(file, `SQL rejected by SQLite: ${message}`);
+    }
+  };
+  let described = analyze(sourceSql);
 
-  const refs = scanTableRefs(sql, ir);
+  const refs = scanTableRefs(sourceSql, ir);
   const tableSet = new Set(refs.map((r) => r.table));
   const tables = [...tableSet].sort();
   if (tables.length === 0) {
@@ -786,17 +935,57 @@ export function analyzeStatement(
     );
   }
 
-  // Columns: pair bun's column names + decltypes with our source resolution.
+  // §5 lowering: rewrite the projection so runtime result keys are the
+  // language-facing names ("camel"); a no-op pass-through under "preserve".
+  let sql = sourceSql;
+  let sqlNames: readonly string[] = described.columnNames;
+  let langNames: readonly string[] = described.columnNames;
+  if (naming.naming === 'camel') {
+    const lowered = lowerProjection(
+      sourceSql,
+      refs,
+      ir,
+      file,
+      (candidate) => analyze(candidate).columnNames,
+      (names) =>
+        buildNamingMap(names, 'camel', file, 'projection', naming.targets).map(
+          (m) => m.langName,
+        ),
+    );
+    sqlNames = lowered.sqlNames;
+    langNames = lowered.langNames;
+    if (lowered.changed) {
+      sql = lowered.sql;
+      described = analyze(sql);
+      // Defensive: the rewritten projection's runtime keys must BE the
+      // language names — this is the whole point of the lowering.
+      if (
+        described.columnNames.length !== langNames.length ||
+        described.columnNames.some((n, i) => n !== langNames[i])
+      ) {
+        throw new TypegenError(
+          file,
+          `internal: lowered projection keys [${described.columnNames.join(', ')}] do not match the naming map [${langNames.join(', ')}]`,
+        );
+      }
+    }
+  }
+
+  // Columns: pair bun's column names + decltypes with our source resolution
+  // (against the LOWERED sql — aliased plain refs still resolve exactly).
   const items = splitSelectList(sql);
   const columns: QueryColumn[] = described.columnNames.map((colName, index) => {
     const decl = described.declaredTypes[index];
     const item = items?.[index];
     const source = item !== undefined ? resolveSource(item, refs, ir) : null;
+    const sqlName = sqlNames[index] ?? colName;
+    const langName = langNames[index] ?? colName;
     if (source !== null) {
       // Exact: IR column type + IR nullability. (decltype agrees; we prefer
       // the IR type so blob_ref/crdt/json semantic types survive.)
       return {
-        name: colName,
+        name: sqlName,
+        langName,
         type: source.column.type,
         nullable: source.column.nullable,
         fidelity: 'exact',
@@ -809,11 +998,18 @@ export function analyzeStatement(
         : undefined;
     const type =
       mapped ?? (item !== undefined ? fallbackColumnType(item.expr) : 'string');
-    return { name: colName, type, nullable: true, fidelity: 'fallback' };
+    return {
+      name: sqlName,
+      langName,
+      type,
+      nullable: true,
+      fidelity: 'fallback',
+    };
   });
 
   // Params: names from the text (positional order), types from inference or
-  // the `-- param` comment; every param must resolve.
+  // the `-- param` comment; every param must resolve. Param langNames go
+  // through the same §12 map (authored camelCase params are identity).
   const paramNames = scanParamNames(sql);
   if (paramNames.length !== described.paramsCount) {
     // Defensive: our scan and SQLite disagree (shouldn't happen for the subset).
@@ -822,15 +1018,23 @@ export function analyzeStatement(
       `internal: scanned ${paramNames.length} params (${paramNames.join(', ')}) but SQLite reports ${described.paramsCount}`,
     );
   }
+  const paramLangNames = buildNamingMap(
+    paramNames,
+    naming.naming,
+    file,
+    'params',
+    naming.targets,
+  );
   const commentByName = new Map(commentParams.map((p) => [p.name, p.type]));
-  const params: QueryParam[] = paramNames.map((paramName) => {
+  const params: QueryParam[] = paramNames.map((paramName, index) => {
+    const langName = paramLangNames[index]?.langName ?? paramName;
     const commented = commentByName.get(paramName);
     if (commented !== undefined) {
-      return { name: paramName, type: commented, source: 'comment' };
+      return { name: paramName, langName, type: commented, source: 'comment' };
     }
     const inferred = inferParamType(paramName, sql, refs, ir);
     if (inferred !== null) {
-      return { name: paramName, type: inferred, source: 'inferred' };
+      return { name: paramName, langName, type: inferred, source: 'inferred' };
     }
     throw new TypegenError(
       file,
@@ -850,6 +1054,7 @@ export function analyzeStatement(
   return {
     name,
     file,
+    sourceSql,
     sql,
     positionalSql: toPositionalSql(sql),
     params,
@@ -874,6 +1079,7 @@ export function analyzeQueryFile(
   content: string,
   ir: IrDocument,
   db: QueryDb,
+  naming: QueryNamingOptions = DEFAULT_NAMING,
 ): AnalyzedQuery[] {
   const statements = splitStatements(content);
   if (statements.length === 0) {
@@ -893,7 +1099,7 @@ export function analyzeQueryFile(
       );
     }
     const name = override ?? defaultName;
-    return analyzeStatement(name, location, stmt.text, ir, db);
+    return analyzeStatement(name, location, stmt.text, ir, db, naming);
   });
 }
 
@@ -905,6 +1111,7 @@ export function analyzeQuery(
   raw: string,
   ir: IrDocument,
   db: QueryDb,
+  naming: QueryNamingOptions = DEFAULT_NAMING,
 ): AnalyzedQuery {
   const statements = splitStatements(raw);
   if (statements.length > 1) {
@@ -913,6 +1120,6 @@ export function analyzeQuery(
       'a query file holds exactly one SELECT statement here (found a `;` separating statements) — use analyzeQueryFile for multi-statement files',
     );
   }
-  const results = analyzeQueryFile(file, raw, ir, db);
+  const results = analyzeQueryFile(file, raw, ir, db, naming);
   return results[0] as AnalyzedQuery;
 }