@syncular/typegen 0.2.0 → 0.3.0

package/src/fmt.ts

@@ -0,0 +1,351 @@
+/**
+ * `syncular fmt` — the canonical `.syql` formatter (DESIGN-queries.md §10,
+ * §12). One style, no options:
+ *
+ * - SQL keywords lowercase; identifier casing preserved (SQL-truth).
+ * - one space after commas; collapsed whitespace elsewhere.
+ * - one clause per line in the body; WHERE conjuncts one per line,
+ *   `and`-prefixed and indented under the `where`.
+ * - declarations separated by one blank line; knobs on their own lines.
+ * - comments are preserved: a declaration's leading comment block stays
+ *   above it; comments inside bodies stay on their own lines.
+ *
+ * The formatter is built on the same parser as the generator (`.syql` that
+ * does not parse does not format), and formatting is semantics-preserving
+ * by construction — `fmt` output re-parses to the same declarations.
+ */
+import { TypegenError } from './errors';
+import { parseSyqlFile, type SyqlQueryDecl } from './syql';
+
+/** SQL keywords the canon lowercases (a pragmatic core set — identifiers
+ * that collide with these would need quoting anyway). */
+const SQL_KEYWORDS = new Set(
+  (
+    'select from where group by having order limit offset window and or not ' +
+    'in is null like glob between exists case when then else end as on using ' +
+    'join left right full outer inner cross natural union all except ' +
+    'intersect distinct values with recursive asc desc collate cast'
+  ).split(' '),
+);
+
+interface Token {
+  readonly kind: 'word' | 'string' | 'comment' | 'punct' | 'param' | 'fragment';
+  readonly text: string;
+}
+
+/** Tokenize a body: strings/comments verbatim, words, `:params`,
+ * `@fragment` refs, single punctuation chars. */
+function tokenize(body: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < body.length) {
+    const ch = body[i] as string;
+    if (/\s/.test(ch)) {
+      i += 1;
+      continue;
+    }
+    if (body.startsWith('--', i)) {
+      const nl = body.indexOf('\n', i);
+      const end = nl === -1 ? body.length : nl;
+      tokens.push({ kind: 'comment', text: body.slice(i, end).trimEnd() });
+      i = end;
+      continue;
+    }
+    if (body.startsWith('/*', i)) {
+      const close = body.indexOf('*/', i + 2);
+      const end = close === -1 ? body.length : close + 2;
+      tokens.push({ kind: 'comment', text: body.slice(i, end) });
+      i = end;
+      continue;
+    }
+    if (ch === "'") {
+      let j = i + 1;
+      for (;;) {
+        if (j >= body.length) break;
+        if (body[j] === "'") {
+          if (body[j + 1] === "'") j += 2;
+          else {
+            j += 1;
+            break;
+          }
+        } else j += 1;
+      }
+      tokens.push({ kind: 'string', text: body.slice(i, j) });
+      i = j;
+      continue;
+    }
+    if (ch === ':' && /[A-Za-z_]/.test(body[i + 1] ?? '')) {
+      let j = i + 1;
+      while (j < body.length && /[A-Za-z0-9_]/.test(body[j] as string)) j += 1;
+      tokens.push({ kind: 'param', text: body.slice(i, j) });
+      i = j;
+      continue;
+    }
+    if (ch === '@' && /[A-Za-z_]/.test(body[i + 1] ?? '')) {
+      let j = i + 1;
+      while (j < body.length && /[A-Za-z0-9_]/.test(body[j] as string)) j += 1;
+      tokens.push({ kind: 'fragment', text: body.slice(i, j) });
+      i = j;
+      continue;
+    }
+    if (/[A-Za-z_]/.test(ch)) {
+      let j = i + 1;
+      while (j < body.length && /[A-Za-z0-9_]/.test(body[j] as string)) j += 1;
+      tokens.push({ kind: 'word', text: body.slice(i, j) });
+      i = j;
+      continue;
+    }
+    // Multi-char operators stay one token (`||`, `>=`, `<=`, `<>`, `!=`, `==`).
+    const two = body.slice(i, i + 2);
+    if (['||', '>=', '<=', '<>', '!=', '=='].includes(two)) {
+      tokens.push({ kind: 'punct', text: two });
+      i += 2;
+      continue;
+    }
+    tokens.push({ kind: 'punct', text: ch });
+    i += 1;
+  }
+  return tokens;
+}
+
+/** Render tokens back to one line with canonical spacing + keyword case. */
+function render(tokens: readonly Token[]): string {
+  let out = '';
+  let prev: Token | undefined;
+  for (const token of tokens) {
+    let text = token.text;
+    if (token.kind === 'word' && SQL_KEYWORDS.has(text.toLowerCase())) {
+      text = text.toLowerCase();
+    }
+    const glueLeft =
+      token.kind === 'punct' &&
+      (text === ',' || text === ')' || text === ';' || text === '.');
+    const glueRight =
+      prev !== undefined &&
+      ((prev.kind === 'punct' && (prev.text === '(' || prev.text === '.')) ||
+        prev.kind === 'fragment');
+    if (out.length > 0 && !glueLeft && !glueRight) out += ' ';
+    out += text;
+    prev = token;
+  }
+  return out;
+}
+
+/** Clause keywords that start a new line at paren depth 0. */
+const CLAUSE_STARTERS = new Set([
+  'select',
+  'from',
+  'where',
+  'group',
+  'having',
+  'order',
+  'limit',
+  'window',
+  'union',
+  'except',
+  'intersect',
+]);
+
+/** Format a body: one clause per line; WHERE conjuncts one per line. */
+function formatBody(body: string): string[] {
+  const tokens = tokenize(body);
+  const lines: string[] = [];
+  let current: Token[] = [];
+  let depth = 0;
+  let braceDepth = 0;
+  let inWhere = false;
+  let pendingBetween = 0;
+  const flush = (): void => {
+    if (current.length > 0) lines.push(render(current));
+    current = [];
+  };
+  for (const token of tokens) {
+    if (token.kind === 'comment') {
+      flush();
+      lines.push(token.text);
+      continue;
+    }
+    if (token.kind === 'punct') {
+      if (token.text === '(') depth += 1;
+      else if (token.text === ')') depth -= 1;
+      else if (token.text === '{') braceDepth += 1;
+      else if (token.text === '}') braceDepth -= 1;
+    }
+    if (token.kind === 'word' && depth === 0 && braceDepth === 0) {
+      const word = token.text.toLowerCase();
+      if (CLAUSE_STARTERS.has(word)) {
+        flush();
+        inWhere = word === 'where';
+        pendingBetween = 0;
+      } else if (inWhere) {
+        if (word === 'between') pendingBetween += 1;
+        else if (word === 'and') {
+          if (pendingBetween > 0) pendingBetween -= 1;
+          else flush();
+        }
+      }
+    }
+    current.push(token);
+  }
+  flush();
+  // Indent: clauses flush-left; WHERE continuation (`and …`) indented 2.
+  return lines.map((line) =>
+    /^(and|or)\b/.test(line) || line.startsWith('--') ? `  ${line}` : line,
+  );
+}
+
+function formatSignature(decl: {
+  readonly params: SyqlQueryDecl['params'];
+}): string {
+  const parts: string[] = [];
+  const seenGroups = new Set<string>();
+  for (const param of decl.params) {
+    if (param.group !== undefined) {
+      if (seenGroups.has(param.group)) continue;
+      seenGroups.add(param.group);
+      const members = decl.params.filter((p) => p.group === param.group);
+      parts.push(`${members.map((p) => p.name).join('+')}?`);
+      continue;
+    }
+    if (param.flag) parts.push(`${param.name}?: flag`);
+    else parts.push(`${param.name}${param.optional ? '?' : ''}`);
+  }
+  return parts.join(', ');
+}
+
+/** The leading comment block (verbatim lines) before each declaration. */
+function leadingComments(source: string): Map<number, string[]> {
+  // Map from declaration index (0-based, in order of appearance) to its
+  // preceding comment lines.
+  const out = new Map<number, string[]>();
+  let pending: string[] = [];
+  let declIndex = 0;
+  let i = 0;
+  while (i < source.length) {
+    const ch = source[i] as string;
+    if (/\s/.test(ch)) {
+      i += 1;
+      continue;
+    }
+    if (source.startsWith('--', i)) {
+      const nl = source.indexOf('\n', i);
+      const end = nl === -1 ? source.length : nl;
+      pending.push(source.slice(i, end).trimEnd());
+      i = end;
+      continue;
+    }
+    if (source.startsWith('/*', i)) {
+      const close = source.indexOf('*/', i + 2);
+      const end = close === -1 ? source.length : close + 2;
+      pending.push(source.slice(i, end));
+      i = end;
+      continue;
+    }
+    // A declaration keyword: attach pending comments, then skip through its
+    // brace block.
+    if (pending.length > 0) {
+      out.set(declIndex, pending);
+      pending = [];
+    }
+    declIndex += 1;
+    const brace = source.indexOf('{', i);
+    if (brace === -1) break;
+    let depth = 0;
+    let j = brace;
+    while (j < source.length) {
+      const c = source[j] as string;
+      if (c === "'") {
+        j += 1;
+        while (j < source.length && source[j] !== "'") j += 1;
+      } else if (source.startsWith('--', j)) {
+        const nl = source.indexOf('\n', j);
+        j = nl === -1 ? source.length : nl;
+      } else if (c === '{') depth += 1;
+      else if (c === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          j += 1;
+          break;
+        }
+      }
+      j += 1;
+    }
+    i = j;
+  }
+  return out;
+}
+
+/** Format one `.syql` source file into its canonical form. Throws
+ * {@link TypegenError} when the source does not parse. */
+export function formatSyql(file: string, source: string): string {
+  const parsed = parseSyqlFile(file, source);
+  const comments = leadingComments(source);
+  const decls: { order: number; text: string }[] = [];
+
+  // Re-derive declaration order (fragments/queries interleave in-source);
+  // parseSyqlFile keeps per-kind order, so re-scan the source for kind
+  // keywords to interleave faithfully.
+  const orderRe = /\b(query|fragment)\s+([A-Za-z][A-Za-z0-9]*)/g;
+  const blanked = source
+    .replace(/--[^\n]*/g, (m) => ' '.repeat(m.length))
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length))
+    .replace(/'(?:[^']|'')*'/g, (m) => ' '.repeat(m.length));
+  const sequence: { kind: string; name: string }[] = [];
+  let braceDepth = 0;
+  let lastIndex = 0;
+  for (let i = 0; i < blanked.length; i++) {
+    const c = blanked[i];
+    if (c === '{') braceDepth += 1;
+    else if (c === '}') braceDepth -= 1;
+    else if (braceDepth === 0) {
+      orderRe.lastIndex = i;
+      const m = orderRe.exec(blanked);
+      if (m !== null && m.index === i) {
+        sequence.push({ kind: m[1] as string, name: m[2] as string });
+        i = orderRe.lastIndex - 1;
+        lastIndex = orderRe.lastIndex;
+      }
+    }
+  }
+  void lastIndex;
+
+  sequence.forEach((entry, index) => {
+    const lines: string[] = [];
+    const leading = comments.get(index);
+    if (leading !== undefined) lines.push(...leading);
+    if (entry.kind === 'fragment') {
+      const decl = parsed.fragments.find((f) => f.name === entry.name);
+      if (decl === undefined) return;
+      lines.push(`fragment ${decl.name}(${formatSignature(decl)}) {`);
+      for (const line of formatBody(decl.body)) lines.push(`  ${line}`);
+      lines.push('}');
+    } else {
+      const decl = parsed.queries.find((q) => q.name === entry.name);
+      if (decl === undefined) return;
+      const knobs: string[] = [];
+      if (decl.orderBy !== undefined) {
+        const dir = decl.orderBy.defaultDir === 'desc' ? ' desc' : '';
+        knobs.push(
+          `  orderBy ${decl.orderBy.allowed.join(' | ')} default ${decl.orderBy.defaultColumn}${dir}`,
+        );
+      }
+      if (decl.limit !== undefined) {
+        const parts: string[] = [];
+        if (decl.limit.max !== undefined) parts.push(`max ${decl.limit.max}`);
+        if (decl.limit.default !== undefined) {
+          parts.push(`default ${decl.limit.default}`);
+        }
+        knobs.push(`  limit ${parts.join(' ')}`);
+      }
+      if (decl.variants === true) knobs.push('  variants');
+      lines.push(
+        `query ${decl.name}(${formatSignature(decl)})${knobs.length > 0 ? `\n${knobs.join('\n')}\n{` : ' {'}`,
+      );
+      for (const line of formatBody(decl.body)) lines.push(`  ${line}`);
+      lines.push('}');
+    }
+    decls.push({ order: index, text: lines.join('\n') });
+  });
+
+  return `${decls.map((d) => d.text).join('\n\n')}\n`;
+}

package/src/generate.ts

@@ -40,13 +40,16 @@ import {
   type ManifestScopeSpec,
   parseManifest,
 } from './manifest';
+import { buildNamingMap, type NamingTarget } from './naming';
 import {
   type AnalyzedQuery,
   analyzeQueryFile,
   type QueryDb,
+  type QueryNamingOptions,
   synthesizeDdl,
 } from './query';
 import { applyMigrationSql, type ParsedTable } from './sql';
+import { analyzeSyqlFile } from './syql';
 
 export interface MigrationInput {
   /** Directory name, e.g. `0001_initial`. */
@@ -340,31 +343,36 @@ export function loadMigrations(migrationsDir: string): MigrationInput[] {
   });
 }
 
-/** One `.sql` named-query file: path (relative to the queries root, forward
- * slashes) + raw contents. A file may hold multiple statements. */
+/** One named-query file (`.sql` — the compatibility floor — or `.syql`, the
+ * DSL): path relative to the queries root (forward slashes) + raw contents.
+ * A file may hold multiple statements/declarations. */
 export interface QueryInput {
   /** Path relative to the queries root, forward-slashed (e.g.
-   * `billing/invoices/list.sql`). Drives the path-derived default name. */
+   * `billing/invoices/list.sql`). Drives the path-derived default name for
+   * `.sql`; `.syql` queries carry their own names. */
   readonly file: string;
   readonly sql: string;
 }
 
-/** Recursively collect `*.sql` paths under `dir`, relative to `root`
- * (forward-slashed), sorted for deterministic emission. */
+/** Recursively collect `*.sql` + `*.syql` paths under `dir`, relative to
+ * `root` (forward-slashed), sorted for deterministic emission. */
 function collectSqlFiles(root: string, dir: string): string[] {
   const out: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const abs = join(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(...collectSqlFiles(root, abs));
-    } else if (entry.isFile() && entry.name.endsWith('.sql')) {
+    } else if (
+      entry.isFile() &&
+      (entry.name.endsWith('.sql') || entry.name.endsWith('.syql'))
+    ) {
       out.push(relative(root, abs).split(sep).join('/'));
     }
   }
   return out;
 }
 
-/** Load `queries/**\/*.sql` recursively, ordered by relative path
+/** Load `queries/**\/*.{sql,syql}` recursively, ordered by relative path
  * (deterministic emission). Folders are pure organization. */
 export function loadQueries(queriesDir: string): QueryInput[] {
   if (!existsSync(queriesDir)) return [];
@@ -380,7 +388,10 @@ export function loadQueries(queriesDir: string): QueryInput[] {
  * `analyze` prepares the statement (validating references) and reads its
  * column names + declared types; it executes once against the empty DB so
  * `declaredTypes` (decltype) is populated. */
-function makeQueryDb(ir: IrDocument): { db: QueryDb; close: () => void } {
+export function makeQueryDb(ir: IrDocument): {
+  db: QueryDb;
+  close: () => void;
+} {
   const sqlite = new Database(':memory:');
   sqlite.run(synthesizeDdl(ir));
   const db: QueryDb = {
@@ -408,13 +419,18 @@ function makeQueryDb(ir: IrDocument): { db: QueryDb; close: () => void } {
 export function analyzeQueries(
   ir: IrDocument,
   queries: readonly QueryInput[],
+  naming?: QueryNamingOptions,
 ): AnalyzedQuery[] {
   if (queries.length === 0) return [];
   const { db, close } = makeQueryDb(ir);
   try {
     // Each file may hold multiple statements; flatten in path order (stable).
+    // Frontends dispatch on extension; both produce the same AnalyzedQuery
+    // shape (§1 — nothing downstream knows the frontend).
     const analyzed = queries.flatMap((q) =>
-      analyzeQueryFile(q.file, q.sql, ir, db),
+      q.file.endsWith('.syql')
+        ? analyzeSyqlFile(q.file, q.sql, ir, db, naming)
+        : analyzeQueryFile(q.file, q.sql, ir, db, naming),
     );
     // Names must be unique across the whole manifest — the filesystem no longer
     // guarantees uniqueness once `-- name:` overrides exist. Report BOTH source
@@ -476,9 +492,32 @@ export function generate(manifestDir: string): GenerateResult {
   const manifest = parseManifest(raw);
   const migrations = loadMigrations(resolve(manifestDir, manifest.migrations));
   const ir = buildIr(manifest, migrations);
+
+  // §5/§12 naming: the emitter targets this run generates (keyword hazards
+  // are only real on targets that exist), and the per-table collision check
+  // for the generated row types.
+  const targets: NamingTarget[] = ['ts'];
+  if (manifest.output.swift !== undefined) targets.push('swift');
+  if (manifest.output.kotlin !== undefined) targets.push('kotlin');
+  if (manifest.output.dart !== undefined) targets.push('dart');
+  const naming: QueryNamingOptions = {
+    naming: manifest.naming,
+    targets,
+    backend: manifest.queryBackend,
+  };
+  for (const table of ir.tables) {
+    buildNamingMap(
+      table.columns.map((c) => c.name),
+      manifest.naming,
+      MANIFEST_FILENAME,
+      `table ${table.name}`,
+      targets,
+    );
+  }
+
   const irJson = serializeIr(ir);
   const hash = irHash(irJson);
-  const module = emitModule(ir, hash);
+  const module = emitModule(ir, hash, manifest.naming);
   const irPath = resolve(manifestDir, manifest.output.ir);
   const modulePath = resolve(manifestDir, manifest.output.module);
   const outputs: GeneratedOutput[] = [
@@ -497,7 +536,11 @@ export function generate(manifestDir: string): GenerateResult {
     kotlin?.queriesPath !== undefined ||
     dart?.queriesPath !== undefined;
   const analyzedQueries = wantsQueries
-    ? analyzeQueries(ir, loadQueries(resolve(manifestDir, manifest.queries)))
+    ? analyzeQueries(
+        ir,
+        loadQueries(resolve(manifestDir, manifest.queries)),
+        naming,
+      )
     : [];
   if (wantsQueries && analyzedQueries.length === 0) {
     throw new TypegenError(

package/src/index.ts

@@ -12,8 +12,14 @@ export * from './emit-queries-kotlin';
 export * from './emit-queries-swift';
 export * from './emit-swift';
 export * from './errors';
+export * from './fmt';
 export * from './generate';
 export * from './ir';
+export * from './lower';
+export * from './lsp';
 export * from './manifest';
+export * from './naming';
 export * from './query';
+export * from './query-ir';
 export * from './sql';
+export * from './syql';