@syncular/typegen 0.5.0 → 0.6.0

package/dist/manifest.d.ts

@@ -77,9 +77,7 @@ export interface Manifest {
      * generated row types/params (queries lower with `AS` aliases); "preserve"
      * keeps SQL-truth names everywhere. */
     readonly naming: NamingMode;
-    /** §7 `.syql` backend: "neutralize" (default), "variants" (enumerate
-     * whenever eligible), or "auto" (enumerate at ≤ 2 optional groups). The
-     * per-query `variants` knob always forces enumeration. */
+    /** §7 `.syql` backend: "auto" (default), "neutralize", or "variants". */
     readonly queryBackend: ManifestQueryBackend;
     readonly output: ManifestOutput;
     readonly schemaVersions: readonly ManifestSchemaVersion[];

package/dist/manifest.js

@@ -232,7 +232,7 @@ export function parseManifest(raw) {
         }
         naming = obj.naming;
     }
-    let queryBackend = 'neutralize';
+    let queryBackend = 'auto';
     if (obj.queryBackend !== undefined) {
         if (obj.queryBackend !== 'neutralize' &&
             obj.queryBackend !== 'variants' &&

package/dist/query-ir.js

@@ -1,7 +1,7 @@
 /** Serialize analyzed queries as the deterministic QueryIR JSON document. */
 export function serializeQueryIr(queries) {
     const doc = {
-        queryIrVersion: 2,
+        queryIrVersion: 3,
         queries: queries.map((query) => ({
             name: query.name,
             file: query.file,
@@ -12,11 +12,6 @@ export function serializeQueryIr(queries) {
                 name: param.name,
                 langName: param.langName,
                 type: param.type,
-                // §4 metadata — emitted only when set, so `.sql`-tier IR bytes are
-                // unchanged from before the DSL existed.
-                ...(param.optional === true ? { optional: true } : {}),
-                ...(param.group !== undefined ? { group: param.group } : {}),
-                ...(param.flag === true ? { flag: true } : {}),
             })),
             columns: query.columns.map((column) => ({
                 name: column.name,
@@ -49,43 +44,59 @@ export function serializeQueryIr(queries) {
                     ? { rowKey: query.reactive.rowKey }
                     : {}),
             },
-            // §6 knob metadata — emitted only when declared.
-            ...(query.orderBy !== undefined
-                ? {
-                    orderBy: {
-                        allowed: query.orderBy.allowed.map((c) => ({
-                            name: c.name,
-                            langName: c.langName,
-                        })),
-                        defaultColumn: query.orderBy.defaultColumn,
-                        defaultDir: query.orderBy.defaultDir,
+            ...(query.syql === undefined
+                ? {}
+                : {
+                    syql: {
+                        revision: query.syql.revision,
+                        inputs: query.syql.inputs.map((input) => {
+                            if (input.kind === 'value')
+                                return { ...input };
+                            if (input.kind === 'group') {
+                                return {
+                                    kind: input.kind,
+                                    name: input.name,
+                                    langName: input.langName,
+                                    members: input.members.map((member) => ({ ...member })),
+                                };
+                            }
+                            if (input.kind === 'sort') {
+                                return {
+                                    kind: input.kind,
+                                    name: input.name,
+                                    langName: input.langName,
+                                    defaultProfile: input.defaultProfile,
+                                    profiles: input.profiles.map((profile) => ({ ...profile })),
+                                };
+                            }
+                            return { ...input };
+                        }),
+                        plan: {
+                            backend: query.syql.plan.backend,
+                            activationControls: query.syql.plan.activationControls,
+                            conditions: query.syql.plan.conditions.map((condition) => ({
+                                controls: condition.controls,
+                                ...(condition.bind === undefined
+                                    ? {}
+                                    : { bind: condition.bind }),
+                            })),
+                            statements: query.syql.plan.statements.map((statement) => ({
+                                ...(statement.sortProfile === undefined
+                                    ? {}
+                                    : { sortProfile: statement.sortProfile }),
+                                ...(statement.activationMask === undefined
+                                    ? {}
+                                    : { activationMask: statement.activationMask }),
+                                sql: statement.sql,
+                                positionalSql: statement.positionalSql,
+                                binds: statement.binds.map((bind) => ({ ...bind })),
+                            })),
+                        },
+                        ...(query.syql.identity === undefined
+                            ? {}
+                            : { identity: query.syql.identity }),
                     },
-                }
-                : {}),
-            ...(query.limit !== undefined ? { limit: query.limit } : {}),
-            ...(query.positionalSqlBase !== undefined
-                ? { positionalSqlBase: query.positionalSqlBase }
-                : {}),
-            // §7 variant backend — emitted only when the query opts in.
-            ...(query.variantGroups !== undefined
-                ? {
-                    variantGroups: query.variantGroups.map((g) => ({
-                        key: g.key,
-                        params: g.params,
-                        flag: g.flag,
-                    })),
-                }
-                : {}),
-            ...(query.variants !== undefined
-                ? {
-                    variants: query.variants.map((v) => ({
-                        when: v.when,
-                        sql: v.sql,
-                        positionalSql: v.positionalSql,
-                        params: v.params,
-                    })),
-                }
-                : {}),
+                }),
         })),
     };
     return `${JSON.stringify(doc, null, 2)}\n`;

package/dist/query.d.ts

@@ -10,31 +10,6 @@ export interface QueryParam {
     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). */
@@ -77,7 +52,7 @@ export interface QueryReactiveMetadata {
     /** Language-facing projection fields forming a proven unique row key. */
     readonly rowKey?: readonly string[];
 }
-/** §7/§8 backend selection: neutralization (default), always-variants, or
+/** §7/§8 backend selection: neutralization, 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. */
@@ -86,9 +61,103 @@ export interface QueryNamingOptions {
     /** 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. */
+    /** `.syql` conditional-lowering policy (default `auto`). */
     readonly backend?: QueryBackend;
+    /** Compiler-reserved physical binds. They retain their exact names and do
+     * not participate in public target-language keyword/private-name checks. */
+    readonly internalParams?: readonly string[];
+}
+/** Revision-1 SYQL public inputs. These are deliberately separate from SQL
+ * binds: groups and switches are public values without corresponding SQLite
+ * parameters, while compiler-generated parameters are never public. */
+export type QuerySyqlPublicInput = {
+    readonly kind: 'value';
+    readonly name: string;
+    readonly langName: string;
+    readonly type: QueryParamType;
+    readonly nullable: boolean;
+    readonly required: boolean;
+} | {
+    readonly kind: 'group';
+    readonly name: string;
+    readonly langName: string;
+    readonly members: readonly {
+        readonly name: string;
+        readonly langName: string;
+        readonly type: QueryParamType;
+        readonly nullable: boolean;
+    }[];
+} | {
+    readonly kind: 'switch';
+    readonly name: string;
+    readonly langName: string;
+    readonly default: false;
+} | {
+    readonly kind: 'sort';
+    readonly name: string;
+    readonly langName: string;
+    readonly defaultProfile: string;
+    readonly profiles: readonly {
+        readonly name: string;
+        readonly langName: string;
+    }[];
+} | {
+    readonly kind: 'page';
+    readonly name: string;
+    readonly langName: string;
+    readonly defaultSize: number;
+    readonly maxSize: number;
+};
+/** One distinct SQLite bind in a physical revision-1 statement. */
+export type QuerySyqlPlanBind = {
+    readonly kind: 'value';
+    readonly name: string;
+    readonly type: QueryParamType;
+    readonly input: string;
+} | {
+    readonly kind: 'group-member';
+    readonly name: string;
+    readonly type: QueryParamType;
+    readonly input: string;
+    readonly member: string;
+} | {
+    readonly kind: 'condition-active';
+    readonly name: string;
+    readonly type: 'boolean';
+    readonly condition: number;
+    readonly controls: readonly string[];
+} | {
+    readonly kind: 'page';
+    readonly name: string;
+    readonly type: 'integer';
+    readonly input: string;
+};
+/** One SQLite-checked statement selected by sort profile and, for the
+ * enumerated backend, the activation bitmask. */
+export interface QuerySyqlStatement {
+    readonly sortProfile?: string;
+    readonly activationMask?: number;
+    readonly sql: string;
+    readonly positionalSql: string;
+    readonly binds: readonly QuerySyqlPlanBind[];
+}
+/** The target-neutral physical plan every emitter must implement exactly. */
+export interface QuerySyqlExecutionPlan {
+    readonly backend: Exclude<QueryBackend, 'auto'>;
+    /** One bit per optional scalar/group/switch, in declaration order. */
+    readonly activationControls: readonly string[];
+    readonly conditions: readonly {
+        readonly controls: readonly string[];
+        /** Present only for neutralized plans. */
+        readonly bind?: string;
+    }[];
+    readonly statements: readonly QuerySyqlStatement[];
+}
+export interface QuerySyqlMetadata {
+    readonly revision: 1;
+    readonly inputs: readonly QuerySyqlPublicInput[];
+    readonly plan: QuerySyqlExecutionPlan;
+    readonly identity?: readonly string[];
 }
 export interface AnalyzedQuery {
     /** camelCase function name (path-derived, or a `-- name:` override). */
@@ -111,41 +180,9 @@ export interface AnalyzedQuery {
     /** IR tables this query reads (the useRawSql `{tables}` set), sorted. */
     readonly tables: readonly string[];
     readonly reactive: QueryReactiveMetadata;
-    /** §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;
-    }[];
+    /** Revision-1 frontend/public-input and physical execution contract. When
+     * present, emitters use this instead of treating `params` as the API. */
+    readonly syql?: QuerySyqlMetadata;
 }
 /**
  * Path-relative default name. `billing/invoices/list.sql` → `billingInvoicesList`;
@@ -171,6 +208,9 @@ export interface SplitStatement {
 export declare function splitStatements(content: string): SplitStatement[];
 /** The `-- name:` override in a statement's leading comment block, or null. */
 export declare function parseStatementName(statementText: string, location: string): string | null;
+/** Strip `--` and block comments so identifier scans don't hit commented SQL,
+ * and string literals so `':x'` inside a string isn't read as a param. */
+export declare function stripCommentsAndStrings(sql: string): string;
 /** 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
@@ -182,6 +222,18 @@ export declare function parseStatementName(statementText: string, location: stri
  * form — one bound value per DISTINCT param, reuse resolved by SQLite —
  * so the generated bind array stays one-entry-per-param. */
 export declare function toPositionalSql(sql: string): string;
+export interface TableRef {
+    readonly table: string;
+    /** Alias (or the table name when un-aliased). */
+    readonly alias: string;
+}
+export declare function scanTableRefs(sql: string, ir: IrDocument): TableRef[];
+/**
+ * Return every revision-1 column/LIKE type constraint for one bind. Unlike
+ * `inferParamType` (the legacy first-match helper), SYQL uses the complete set
+ * so conflicting checked uses cannot be silently accepted.
+ */
+export declare function inferParamTypeEvidence(paramName: string, sql: string, refs: readonly TableRef[], ir: IrDocument): readonly IrColumnType[];
 export interface QueryDb {
     /** Prepare + return the result columns / declared types / param count.
      * Throws (with SQLite's message) when the SQL is invalid against the DDL. */

package/dist/query.js

@@ -290,7 +290,7 @@ function parseCommentParams(file, raw) {
 }
 /** Strip `--` and block comments so identifier scans don't hit commented SQL,
  * and string literals so `':x'` inside a string isn't read as a param. */
-function stripCommentsAndStrings(sql) {
+export function stripCommentsAndStrings(sql) {
     let out = '';
     let i = 0;
     while (i < sql.length) {
@@ -453,7 +453,7 @@ const RESERVED_ALIAS = new Set([
     'limit',
     'having',
 ]);
-function scanTableRefs(sql, ir) {
+export function scanTableRefs(sql, ir) {
     const cleaned = stripCommentsAndStrings(sql);
     const known = new Map(ir.tables.map((t) => [t.name, t]));
     const refs = [];
@@ -603,6 +603,57 @@ function inferParamType(paramName, sql, refs, ir) {
         return 'string';
     return null;
 }
+/**
+ * Return every revision-1 column/LIKE type constraint for one bind. Unlike
+ * `inferParamType` (the legacy first-match helper), SYQL uses the complete set
+ * so conflicting checked uses cannot be silently accepted.
+ */
+export function inferParamTypeEvidence(paramName, sql, refs, ir) {
+    const cleaned = stripCommentsAndStrings(sql);
+    const byName = new Map(ir.tables.map((table) => [table.name, table]));
+    const evidence = [];
+    const add = (qualifier, column) => {
+        if (qualifier !== undefined) {
+            const ref = refs.find((candidate) => candidate.alias === qualifier);
+            const table = ref === undefined ? undefined : byName.get(ref.table);
+            const type = table?.columns.find((item) => item.name === column)?.type;
+            if (type !== undefined)
+                evidence.push(type);
+            return;
+        }
+        const matches = refs.flatMap((ref) => {
+            const table = byName.get(ref.table);
+            const type = table?.columns.find((item) => item.name === column)?.type;
+            return type === undefined ? [] : [type];
+        });
+        if (matches.length === 1)
+            evidence.push(matches[0]);
+    };
+    const comparison = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s*(?:=|==|!=|<>|<=|>=|<|>|\\bLIKE\\b|\\bIS\\b)\\s*:${paramName}\\b`, 'gi');
+    for (const match of cleaned.matchAll(comparison)) {
+        add(match[1], match[2]);
+    }
+    const reversed = new RegExp(`:${paramName}\\b\\s*(?:=|==|!=|<>|<=|>=|<|>)\\s*(?:(${IDENT})\\.)?(${IDENT})`, 'gi');
+    for (const match of cleaned.matchAll(reversed)) {
+        add(match[1], match[2]);
+    }
+    const inList = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+IN\\s*\\(([^)]*:${paramName}\\b[^)]*)\\)`, 'gi');
+    for (const match of cleaned.matchAll(inList)) {
+        add(match[1], match[2]);
+    }
+    const betweenLeft = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+:${paramName}\\b`, 'gi');
+    for (const match of cleaned.matchAll(betweenLeft)) {
+        add(match[1], match[2]);
+    }
+    const betweenRight = new RegExp(`(?:(${IDENT})\\.)?(${IDENT})\\s+BETWEEN\\s+\\S+\\s+AND\\s+:${paramName}\\b`, 'gi');
+    for (const match of cleaned.matchAll(betweenRight)) {
+        add(match[1], match[2]);
+    }
+    const like = new RegExp(`\\bLIKE\\b[^()]*:${paramName}\\b`, 'gi');
+    if (like.test(cleaned))
+        evidence.push('string');
+    return evidence;
+}
 // -- fallback column typing (computed expressions) ----------------------------
 const AGG_RE = /\b(count|sum|total|avg|min|max)\s*\(/i;
 /** decltype-null column: the documented honest fallback. Aggregates and
@@ -665,9 +716,7 @@ function inferReactiveMetadata(sql, refs, ir, params, columns) {
                         continue;
                     const name = match[1] ?? match[2];
                     const param = name === undefined ? undefined : byParam.get(name);
-                    if (param !== undefined &&
-                        param.optional !== true &&
-                        param.flag !== true) {
+                    if (param !== undefined) {
                         found.push(param.name);
                     }
                 }
@@ -677,9 +726,7 @@ function inferReactiveMetadata(sql, refs, ir, params, columns) {
                         continue;
                     for (const paramMatch of (match[1] ?? '').matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) {
                         const param = byParam.get(paramMatch[1]);
-                        if (param !== undefined &&
-                            param.optional !== true &&
-                            param.flag !== true) {
+                        if (param !== undefined) {
                             found.push(param.name);
                         }
                     }
@@ -867,10 +914,12 @@ export function analyzeStatement(name, location, statementText, ir, db, naming =
         // Defensive: our scan and SQLite disagree (shouldn't happen for the subset).
         throw new TypegenError(file, `internal: scanned ${paramNames.length} params (${paramNames.join(', ')}) but SQLite reports ${described.paramsCount}`);
     }
-    const paramLangNames = buildNamingMap(paramNames, naming.naming, file, 'params', naming.targets);
+    const internalParams = new Set(naming.internalParams ?? []);
+    const publicParamLangNames = buildNamingMap(paramNames.filter((name) => !internalParams.has(name)), naming.naming, file, 'params', naming.targets);
+    const langNameByParam = new Map(publicParamLangNames.map((mapping) => [mapping.sqlName, mapping.langName]));
     const commentByName = new Map(commentParams.map((p) => [p.name, p.type]));
-    const params = paramNames.map((paramName, index) => {
-        const langName = paramLangNames[index]?.langName ?? paramName;
+    const params = paramNames.map((paramName) => {
+        const langName = langNameByParam.get(paramName) ?? paramName;
         const commented = commentByName.get(paramName);
         if (commented !== undefined) {
             return { name: paramName, langName, type: commented, source: 'comment' };

package/dist/syql-lexer.d.ts

@@ -38,3 +38,5 @@ export declare class SyqlFrontendError extends TypegenError {
 export declare function isSyqlTrivia(token: SyqlToken): boolean;
 /** Lex one complete `.syql` source file, including trivia and an EOF token. */
 export declare function lexSyqlSource(file: string, source: string): readonly SyqlToken[];
+/** Lex an isolated SQL/template string without import-path contextual rules. */
+export declare function lexSyqlSqlSource(file: string, source: string): readonly SyqlToken[];

package/dist/syql-lexer.js

@@ -92,9 +92,11 @@ class Lexer {
     #column = 1;
     #braceDepth = 0;
     #expectImportPath = false;
-    constructor(file, source) {
+    #recognizeImportPaths;
+    constructor(file, source, recognizeImportPaths = true) {
         this.#file = file;
         this.#source = source;
+        this.#recognizeImportPaths = recognizeImportPaths;
     }
     lex() {
         while (this.#offset < this.#source.length)
@@ -161,7 +163,8 @@ class Lexer {
             else if (token.text === '}')
                 this.#braceDepth = Math.max(0, this.#braceDepth - 1);
         }
-        if (token.kind === 'identifier' &&
+        if (this.#recognizeImportPaths &&
+            token.kind === 'identifier' &&
             token.text === 'from' &&
             this.#braceDepth === 0) {
             this.#expectImportPath = true;
@@ -365,3 +368,7 @@ class Lexer {
 export function lexSyqlSource(file, source) {
     return new Lexer(file, source).lex();
 }
+/** Lex an isolated SQL/template string without import-path contextual rules. */
+export function lexSyqlSqlSource(file, source) {
+    return new Lexer(file, source, false).lex();
+}

package/dist/syql-lowering.d.ts

@@ -0,0 +1,22 @@
+import type { IrDocument } from './ir.js';
+import { type AnalyzedQuery, type QueryBackend, type QueryDb, type QueryNamingOptions, type QuerySyqlExecutionPlan } from './query.js';
+import type { SyqlValidatedQuery } from './syql-validator.js';
+export type SyqlLoweringErrorCode = 'SYQL7001_ENUMERATION_LIMIT' | 'SYQL7002_INTERNAL_LOWERING';
+export interface SyqlLoweringOptions {
+    readonly backend?: QueryBackend;
+    /** Maximum physical activation variants generated for diagnostics and a
+     * forced variants backend. Sort profiles multiply this count. */
+    readonly maxEnumeratedStatements?: number;
+}
+export interface SyqlLoweredQuery {
+    readonly validated: SyqlValidatedQuery;
+    readonly analysis: AnalyzedQuery;
+    readonly selected: QuerySyqlExecutionPlan;
+    readonly neutralized: QuerySyqlExecutionPlan;
+    /** Omitted only when enumeration exceeds compiler resource policy. */
+    readonly enumerated?: QuerySyqlExecutionPlan;
+}
+/** Lower one validated revision-1 query and prepare every generated physical
+ * statement. The selected plan is embedded into the returned shared QueryIR
+ * query; the second plan is retained for equivalence conformance tests. */
+export declare function lowerSyqlQuery(validated: SyqlValidatedQuery, ir: IrDocument, db: QueryDb, naming?: QueryNamingOptions, options?: SyqlLoweringOptions): SyqlLoweredQuery;