@syncular/typegen 0.4.0 → 0.5.0

package/src/query.ts

@@ -135,6 +135,35 @@ export interface QueryColumn {
   /** `exact` = resolved to an IR column (plain ref); `fallback` = a computed
    * expression typed by the documented honest fallback. */
   readonly fidelity: 'exact' | 'fallback';
+  /** Proven physical origin for reactive row identity and diagnostics. */
+  readonly origin?: { readonly table: string; readonly column: string };
+}
+
+export interface QueryScopeBinding {
+  readonly table: string;
+  readonly variable: string;
+  readonly pattern: string;
+  readonly params: readonly string[];
+}
+
+export interface QueryCoverageBinding {
+  readonly table: string;
+  readonly variable: string;
+  readonly units: readonly string[];
+  readonly fixedScopes: readonly {
+    readonly variable: string;
+    readonly params: readonly string[];
+  }[];
+}
+
+export interface QueryReactiveMetadata {
+  readonly dependencies: readonly {
+    readonly table: string;
+    readonly scopes: readonly QueryScopeBinding[];
+  }[];
+  readonly coverage: readonly QueryCoverageBinding[];
+  /** Language-facing projection fields forming a proven unique row key. */
+  readonly rowKey?: readonly string[];
 }
 
 /** §7/§8 backend selection: neutralization (default), always-variants, or
@@ -174,6 +203,7 @@ export interface AnalyzedQuery {
   readonly columns: readonly QueryColumn[];
   /** 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. */
@@ -480,15 +510,29 @@ function stripCommentsAndStrings(sql: string): string {
     const next = sql[i + 1];
     if (ch === '-' && next === '-') {
       const end = sql.indexOf('\n', i);
-      i = end === -1 ? sql.length : end;
+      const stop = end === -1 ? sql.length : end;
+      out += ' '.repeat(stop - i);
+      i = stop;
     } else if (ch === '/' && next === '*') {
       const end = sql.indexOf('*/', i + 2);
-      i = end === -1 ? sql.length : end + 2;
-      out += ' ';
+      const stop = end === -1 ? sql.length : end + 2;
+      out += sql.slice(i, stop).replace(/[^\n]/g, ' ');
+      i = stop;
     } else if (ch === "'") {
-      const end = sql.indexOf("'", i + 1);
-      i = end === -1 ? sql.length : end + 1;
-      out += ' ';
+      let stop = i + 1;
+      while (stop < sql.length) {
+        if (sql[stop] === "'" && sql[stop + 1] === "'") {
+          stop += 2;
+          continue;
+        }
+        if (sql[stop] === "'") {
+          stop += 1;
+          break;
+        }
+        stop += 1;
+      }
+      out += sql.slice(i, stop).replace(/[^\n]/g, ' ');
+      i = stop;
     } else {
       out += ch;
       i += 1;
@@ -691,6 +735,7 @@ function splitSelectList(sql: string): SelectItem[] | null {
 const PLAIN_REF_RE = new RegExp(`^(?:(${IDENT})\\.)?(${IDENT})$`);
 
 interface ResolvedSource {
+  readonly table: string;
   readonly column: IrTable['columns'][number];
 }
 
@@ -710,14 +755,14 @@ function resolveSource(
     if (ref === undefined) return null;
     const table = byName.get(ref.table);
     const col = table?.columns.find((c) => c.name === columnName);
-    return col === undefined ? null : { column: col };
+    return col === undefined ? null : { table: ref.table, column: col };
   }
   // Unqualified: search every FROM/JOIN table (SQLite already resolved
   // ambiguity; a single-table query is the common case).
   for (const ref of refs) {
     const table = byName.get(ref.table);
     const col = table?.columns.find((c) => c.name === columnName);
-    if (col !== undefined) return { column: col };
+    if (col !== undefined) return { table: ref.table, column: col };
   }
   return null;
 }
@@ -821,6 +866,156 @@ function fallbackColumnType(expr: string): IrColumnType {
   return 'string';
 }
 
+function inferReactiveMetadata(
+  sql: string,
+  refs: readonly TableRef[],
+  ir: IrDocument,
+  params: readonly QueryParam[],
+  columns: readonly QueryColumn[],
+): QueryReactiveMetadata {
+  const conservative = /\b(?:UNION|EXCEPT|INTERSECT)\b/i.test(
+    stripCommentsAndStrings(sql),
+  );
+  const requiredAt = (index: number): boolean => {
+    const cleaned = stripCommentsAndStrings(sql);
+    const where = /\bWHERE\b/i.exec(cleaned);
+    if (where === null || index < where.index + where[0].length) return false;
+    const matchStack: number[] = [];
+    for (
+      let cursor = where.index + where[0].length;
+      cursor < index;
+      cursor += 1
+    ) {
+      if (cleaned[cursor] === '(') matchStack.push(cursor);
+      else if (cleaned[cursor] === ')') matchStack.pop();
+    }
+    const stack: number[] = [];
+    for (
+      let cursor = where.index + where[0].length;
+      cursor < cleaned.length;
+      cursor += 1
+    ) {
+      const char = cleaned[cursor];
+      if (char === '(') stack.push(cursor);
+      else if (char === ')') stack.pop();
+      if (
+        cursor > index &&
+        /^(?:GROUP\s+BY|ORDER\s+BY|LIMIT|HAVING)\b/i.test(cleaned.slice(cursor))
+      ) {
+        break;
+      }
+      if (
+        /^OR\b/i.test(cleaned.slice(cursor)) &&
+        stack.every((open, stackIndex) => matchStack[stackIndex] === open)
+      ) {
+        return false;
+      }
+    }
+    return true;
+  };
+  const byParam = new Map(params.map((param) => [param.name, param] as const));
+  const dependencies: Array<{
+    table: string;
+    scopes: QueryScopeBinding[];
+  }> = [];
+  const coverage: QueryCoverageBinding[] = [];
+
+  for (const tableName of [...new Set(refs.map((ref) => ref.table))].sort()) {
+    const table = ir.tables.find((candidate) => candidate.name === tableName);
+    const tableRefs = refs.filter((ref) => ref.table === tableName);
+    const scopes: QueryScopeBinding[] = [];
+    if (table !== undefined && tableRefs.length === 1 && !conservative) {
+      const qualifier = tableRefs[0]?.alias;
+      for (const scope of table.scopes) {
+        const column = scope.column.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const qualified =
+          qualifier === undefined
+            ? `(?:${IDENT}\\.)?${column}`
+            : `(?:${qualifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.)?${column}`;
+        const found: string[] = [];
+        const equality = new RegExp(
+          `${qualified}\\s*(?:=|==|\\bIS\\b)\\s*:(${IDENT})\\b|:(${IDENT})\\b\\s*(?:=|==)\\s*${qualified}`,
+          'gi',
+        );
+        for (const match of sql.matchAll(equality)) {
+          if (!requiredAt(match.index)) continue;
+          const name = match[1] ?? match[2];
+          const param = name === undefined ? undefined : byParam.get(name);
+          if (
+            param !== undefined &&
+            param.optional !== true &&
+            param.flag !== true
+          ) {
+            found.push(param.name);
+          }
+        }
+        const inList = new RegExp(`${qualified}\\s+IN\\s*\\(([^)]*)\\)`, 'gi');
+        for (const match of sql.matchAll(inList)) {
+          if (!requiredAt(match.index)) continue;
+          for (const paramMatch of (match[1] ?? '').matchAll(
+            /:([A-Za-z_][A-Za-z0-9_]*)/g,
+          )) {
+            const param = byParam.get(paramMatch[1] as string);
+            if (
+              param !== undefined &&
+              param.optional !== true &&
+              param.flag !== true
+            ) {
+              found.push(param.name);
+            }
+          }
+        }
+        const unique = [...new Set(found)];
+        if (unique.length > 0) {
+          scopes.push({
+            table: tableName,
+            variable: scope.variable,
+            pattern: scope.pattern,
+            params: unique,
+          });
+        }
+      }
+      if (table.scopes.length > 0 && scopes.length === table.scopes.length) {
+        const variable = scopes[0] as QueryScopeBinding;
+        coverage.push({
+          table: tableName,
+          variable: variable.variable,
+          units: variable.params,
+          fixedScopes: scopes.slice(1).map((scope) => ({
+            variable: scope.variable,
+            params: scope.params,
+          })),
+        });
+      }
+    }
+    dependencies.push({ table: tableName, scopes });
+  }
+
+  let rowKey: readonly string[] | undefined;
+  const simpleSingleTable =
+    refs.length === 1 &&
+    !/\b(?:DISTINCT|GROUP\s+BY|UNION|EXCEPT|INTERSECT)\b/i.test(
+      stripCommentsAndStrings(sql),
+    );
+  if (simpleSingleTable) {
+    const table = ir.tables.find(
+      (candidate) => candidate.name === refs[0]?.table,
+    );
+    const primary = columns.find(
+      (column) =>
+        table !== undefined &&
+        column.origin?.table === table.name &&
+        column.origin?.column === table.primaryKey,
+    );
+    if (primary !== undefined) rowKey = [primary.langName];
+  }
+  return {
+    dependencies,
+    coverage,
+    ...(rowKey !== undefined ? { rowKey } : {}),
+  };
+}
+
 // -- public API ---------------------------------------------------------------
 
 export interface QueryDb {
@@ -989,6 +1184,7 @@ export function analyzeStatement(
         type: source.column.type,
         nullable: source.column.nullable,
         fidelity: 'exact',
+        origin: { table: source.table, column: source.column.name },
       };
     }
     // Fallback: decltype affinity if present, else the expr-shape fallback.
@@ -1051,6 +1247,8 @@ export function analyzeStatement(
     }
   }
 
+  const reactive = inferReactiveMetadata(sql, refs, ir, params, columns);
+
   return {
     name,
     file,
@@ -1060,6 +1258,7 @@ export function analyzeStatement(
     params,
     columns,
     tables,
+    reactive,
   };
 }
 

package/src/syql-ast.ts

@@ -0,0 +1,277 @@
+/** Stable, span-free semantic AST used by revision-1 conformance fixtures. */
+import { isSyqlTrivia, type SyqlToken } from './syql-lexer';
+import type {
+  SyqlDeclaration,
+  SyqlGroupMember,
+  SyqlQueryParameter,
+  SyqlSyntaxFile,
+  SyqlTemplate,
+  SyqlValueType,
+} from './syql-parser';
+import type { SyqlEmbeddedNode } from './syql-template-parser';
+
+export interface SyqlSemanticToken {
+  readonly kind: SyqlToken['kind'];
+  readonly text: string;
+}
+
+export interface SyqlSemanticType {
+  readonly base: SyqlValueType['base'];
+  readonly nullable: boolean;
+}
+
+export type SyqlSemanticTemplateNode =
+  | {
+      readonly kind: 'sql';
+      readonly tokens: readonly SyqlSemanticToken[];
+    }
+  | {
+      readonly kind: 'predicate-call';
+      readonly name: string;
+      readonly arguments: readonly string[];
+    }
+  | {
+      readonly kind: 'when';
+      readonly controls: readonly string[];
+      readonly body: readonly SyqlSemanticTemplateNode[];
+    }
+  | {
+      readonly kind: 'scope' | 'cover';
+      readonly bindings: readonly {
+        readonly qualifier: string;
+        readonly column: string;
+        readonly operator: 'equal' | 'in';
+        readonly values: readonly string[];
+      }[];
+    };
+
+export interface SyqlSemanticTemplate {
+  readonly mode: SyqlTemplate['tree']['mode'];
+  readonly nodes: readonly SyqlSemanticTemplateNode[];
+}
+
+export type SyqlSemanticQueryParameter =
+  | {
+      readonly kind: 'value';
+      readonly name: string;
+      readonly optional: boolean;
+      readonly type?: SyqlSemanticType;
+    }
+  | {
+      readonly kind: 'switch';
+      readonly name: string;
+      readonly optional: true;
+    }
+  | {
+      readonly kind: 'group';
+      readonly name: string;
+      readonly optional: true;
+      readonly members: readonly {
+        readonly name: string;
+        readonly type?: SyqlSemanticType;
+      }[];
+    };
+
+export type SyqlSemanticDeclaration =
+  | {
+      readonly kind: 'predicate';
+      readonly name: string;
+      readonly parameters: readonly {
+        readonly name: string;
+        readonly type?: SyqlSemanticType;
+      }[];
+      readonly body: SyqlSemanticTemplate;
+    }
+  | {
+      readonly kind: 'query';
+      readonly name: string;
+      readonly parameters: readonly SyqlSemanticQueryParameter[];
+      readonly sql: SyqlSemanticTemplate;
+      readonly sort?: {
+        readonly control: string;
+        readonly defaultProfile: string;
+        readonly profiles: readonly {
+          readonly name: string;
+          readonly order: SyqlSemanticTemplate;
+        }[];
+      };
+      readonly page?: {
+        readonly control: string;
+        readonly defaultSize: number;
+        readonly maxSize: number;
+      };
+      readonly identity?: readonly string[];
+    };
+
+export interface SyqlSemanticFile {
+  readonly kind: 'syql-file';
+  readonly revision: 1;
+  readonly imports: readonly {
+    readonly path: string;
+    readonly items: readonly {
+      readonly imported: string;
+      readonly local: string;
+    }[];
+  }[];
+  readonly declarations: readonly SyqlSemanticDeclaration[];
+}
+
+function semanticType(
+  type: SyqlValueType | undefined,
+): SyqlSemanticType | undefined {
+  return type === undefined
+    ? undefined
+    : { base: type.base, nullable: type.nullable };
+}
+
+function semanticMember(member: SyqlGroupMember): {
+  readonly name: string;
+  readonly type?: SyqlSemanticType;
+} {
+  const type = semanticType(member.type);
+  return { name: member.name, ...(type === undefined ? {} : { type }) };
+}
+
+function semanticParameter(
+  parameter: SyqlQueryParameter,
+): SyqlSemanticQueryParameter {
+  if (parameter.kind === 'switch') {
+    return { kind: 'switch', name: parameter.name, optional: true };
+  }
+  if (parameter.kind === 'group') {
+    return {
+      kind: 'group',
+      name: parameter.name,
+      optional: true,
+      members: parameter.members.map(semanticMember),
+    };
+  }
+  const type = semanticType(parameter.type);
+  return {
+    kind: 'value',
+    name: parameter.name,
+    optional: parameter.optional,
+    ...(type === undefined ? {} : { type }),
+  };
+}
+
+function semanticRawTokens(
+  tokens: readonly SyqlToken[],
+): readonly SyqlSemanticToken[] {
+  return tokens
+    .filter((token) => !isSyqlTrivia(token))
+    .map((token) => ({ kind: token.kind, text: token.text }));
+}
+
+function semanticNode(
+  node: SyqlEmbeddedNode,
+): SyqlSemanticTemplateNode | undefined {
+  if (node.kind === 'raw') {
+    const tokens = semanticRawTokens(node.tokens);
+    return tokens.length === 0 ? undefined : { kind: 'sql', tokens };
+  }
+  if (node.kind === 'predicate-call') {
+    return {
+      kind: 'predicate-call',
+      name: node.name,
+      arguments: node.arguments.map((argument) => argument.name),
+    };
+  }
+  if (node.kind === 'when') {
+    return {
+      kind: 'when',
+      controls: node.controls,
+      body: semanticNodes(node.body.nodes),
+    };
+  }
+  return {
+    kind: node.kind,
+    bindings: node.bindings.map((binding) => ({
+      qualifier: binding.column.qualifier,
+      column: binding.column.name,
+      operator: binding.operator,
+      values: binding.values.map((value) => value.name),
+    })),
+  };
+}
+
+function semanticNodes(
+  nodes: readonly SyqlEmbeddedNode[],
+): readonly SyqlSemanticTemplateNode[] {
+  return nodes.flatMap((node) => {
+    const semantic = semanticNode(node);
+    return semantic === undefined ? [] : [semantic];
+  });
+}
+
+function semanticTemplate(template: SyqlTemplate): SyqlSemanticTemplate {
+  return {
+    mode: template.tree.mode,
+    nodes: semanticNodes(template.tree.nodes),
+  };
+}
+
+function semanticDeclaration(
+  declaration: SyqlDeclaration,
+): SyqlSemanticDeclaration {
+  if (declaration.kind === 'predicate') {
+    return {
+      kind: 'predicate',
+      name: declaration.name,
+      parameters: declaration.parameters.map((parameter) => {
+        const type = semanticType(parameter.type);
+        return {
+          name: parameter.name,
+          ...(type === undefined ? {} : { type }),
+        };
+      }),
+      body: semanticTemplate(declaration.body),
+    };
+  }
+  return {
+    kind: 'query',
+    name: declaration.name,
+    parameters: declaration.parameters.map(semanticParameter),
+    sql: semanticTemplate(declaration.sql.body),
+    ...(declaration.sort === undefined
+      ? {}
+      : {
+          sort: {
+            control: declaration.sort.control,
+            defaultProfile: declaration.sort.defaultProfile,
+            profiles: declaration.sort.profiles.map((profile) => ({
+              name: profile.name,
+              order: semanticTemplate(profile.order),
+            })),
+          },
+        }),
+    ...(declaration.page === undefined
+      ? {}
+      : {
+          page: {
+            control: declaration.page.control,
+            defaultSize: declaration.page.defaultSize,
+            maxSize: declaration.page.maxSize,
+          },
+        }),
+    ...(declaration.identity === undefined
+      ? {}
+      : { identity: declaration.identity.fields }),
+  };
+}
+
+/** Return the stable syntax/semantic AST pinned by `spec/syql` fixtures. */
+export function toSyqlSemanticAst(file: SyqlSyntaxFile): SyqlSemanticFile {
+  return {
+    kind: 'syql-file',
+    revision: 1,
+    imports: file.imports.map((declaration) => ({
+      path: declaration.path,
+      items: declaration.items.map((item) => ({
+        imported: item.imported,
+        local: item.local,
+      })),
+    })),
+    declarations: file.declarations.map(semanticDeclaration),
+  };
+}