@syncular/typegen 0.2.0 → 0.3.0

package/dist/lsp.js

@@ -0,0 +1,376 @@
+/**
+ * `syncular lsp` — a minimal `.syql` language server (DESIGN-queries.md
+ * §10, staged Q5). Zero dependencies: hand-rolled JSON-RPC over stdio with
+ * Content-Length framing, and the SAME parser/checker the generator runs —
+ * diagnostics are generate-time truth, not a re-implementation.
+ *
+ * Capabilities:
+ * - diagnostics (on open/change): parse errors, lowering errors (B1,
+ *   knob conflicts), and — when a `syncular.json` is found above the file —
+ *   the full SQLite-checked analysis (types, unknown columns, naming
+ *   collisions).
+ * - hover: a query name shows its lowered, checked SQL (what actually
+ *   runs); an `@fragment` ref shows the fragment body.
+ * - definition: an `@fragment` ref jumps to its declaration (same file —
+ *   fragments are file-scoped).
+ *
+ * The server core is a pure(ish) class (`SyqlLanguageServer.handle`)
+ * so tests drive it without stdio; `runLspStdio` is the thin transport.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { TypegenError } from './errors.js';
+import { buildIr, loadMigrations, makeQueryDb } from './generate.js';
+import { MANIFEST_FILENAME, parseManifest } from './manifest.js';
+import { analyzeSyqlFile, parseSyqlFile } from './syql.js';
+// ---------------------------------------------------------------------------
+// Text/position helpers
+// ---------------------------------------------------------------------------
+function offsetToPosition(text, offset) {
+    const clamped = Math.max(0, Math.min(offset, text.length));
+    let line = 0;
+    let lineStart = 0;
+    for (let i = 0; i < clamped; i++) {
+        if (text[i] === '\n') {
+            line += 1;
+            lineStart = i + 1;
+        }
+    }
+    return { line, character: clamped - lineStart };
+}
+function positionToOffset(text, position) {
+    let line = 0;
+    let i = 0;
+    while (i < text.length && line < position.line) {
+        if (text[i] === '\n')
+            line += 1;
+        i += 1;
+    }
+    return Math.min(text.length, i + position.character);
+}
+/** The `@word` / `word` under the cursor, with its range. */
+function wordAt(text, offset) {
+    const isWord = (ch) => ch !== undefined && /[A-Za-z0-9_@]/.test(ch);
+    if (!isWord(text[offset]) && !isWord(text[offset - 1]))
+        return null;
+    let start = isWord(text[offset]) ? offset : offset - 1;
+    while (start > 0 && isWord(text[start - 1]))
+        start -= 1;
+    let end = start;
+    while (end < text.length && isWord(text[end]))
+        end += 1;
+    return { word: text.slice(start, end), start, end };
+}
+function uriToPath(uri) {
+    return uri.startsWith('file://') ? decodeURIComponent(uri.slice(7)) : uri;
+}
+function findManifestDir(fromPath) {
+    let dir = dirname(fromPath);
+    for (let i = 0; i < 20; i++) {
+        if (existsSync(resolve(dir, MANIFEST_FILENAME)))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// The server
+// ---------------------------------------------------------------------------
+export class SyqlLanguageServer {
+    #documents = new Map();
+    #contexts = new Map();
+    /** Handle one incoming message; returns the outgoing messages. */
+    handle(message) {
+        const { method, id } = message;
+        if (method === 'initialize') {
+            return [
+                {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        capabilities: {
+                            textDocumentSync: 1, // full
+                            hoverProvider: true,
+                            definitionProvider: true,
+                        },
+                        serverInfo: { name: 'syncular-syql-lsp', version: '0.0.1' },
+                    },
+                },
+            ];
+        }
+        if (method === 'textDocument/didOpen') {
+            const params = message.params;
+            this.#documents.set(params.textDocument.uri, params.textDocument.text);
+            return [this.#publishDiagnostics(params.textDocument.uri)];
+        }
+        if (method === 'textDocument/didChange') {
+            const params = message.params;
+            const last = params.contentChanges[params.contentChanges.length - 1];
+            if (last !== undefined) {
+                this.#documents.set(params.textDocument.uri, last.text);
+            }
+            return [this.#publishDiagnostics(params.textDocument.uri)];
+        }
+        if (method === 'textDocument/didClose') {
+            const params = message.params;
+            this.#documents.delete(params.textDocument.uri);
+            return [];
+        }
+        if (method === 'textDocument/hover') {
+            return [{ jsonrpc: '2.0', id, result: this.#hover(message.params) }];
+        }
+        if (method === 'textDocument/definition') {
+            return [{ jsonrpc: '2.0', id, result: this.#definition(message.params) }];
+        }
+        if (method === 'shutdown') {
+            return [{ jsonrpc: '2.0', id, result: null }];
+        }
+        if (id !== undefined && method !== undefined) {
+            return [
+                {
+                    jsonrpc: '2.0',
+                    id,
+                    error: { code: -32601, message: `unhandled method ${method}` },
+                },
+            ];
+        }
+        return [];
+    }
+    /** Reset cached manifest contexts (e.g. after schema edits). */
+    invalidateProjects() {
+        this.#contexts = new Map();
+    }
+    #context(uri) {
+        const path = uriToPath(uri);
+        const manifestDir = findManifestDir(path);
+        if (manifestDir === null)
+            return null;
+        const cached = this.#contexts.get(manifestDir);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const manifest = parseManifest(JSON.parse(readFileSync(resolve(manifestDir, MANIFEST_FILENAME), 'utf8')));
+            const migrations = loadMigrations(resolve(manifestDir, manifest.migrations));
+            const ir = buildIr(manifest, migrations);
+            const { db } = makeQueryDb(ir);
+            const targets = ['ts'];
+            const context = {
+                ir,
+                db,
+                manifestDir,
+                naming: {
+                    naming: manifest.naming,
+                    targets,
+                    backend: manifest.queryBackend,
+                },
+            };
+            this.#contexts.set(manifestDir, context);
+            return context;
+        }
+        catch {
+            this.#contexts.set(manifestDir, null);
+            return null;
+        }
+    }
+    #publishDiagnostics(uri) {
+        const text = this.#documents.get(uri) ?? '';
+        const diagnostics = this.#diagnose(uri, text);
+        return {
+            jsonrpc: '2.0',
+            method: 'textDocument/publishDiagnostics',
+            params: { uri, diagnostics },
+        };
+    }
+    #diagnose(uri, text) {
+        const path = uriToPath(uri);
+        const context = this.#context(uri);
+        try {
+            if (context !== null) {
+                // The full generate-time analysis: parse + lower + SQLite check.
+                const rel = relative(context.manifestDir, path).split('\\').join('/');
+                analyzeSyqlFile(rel, text, context.ir, context.db, context.naming);
+            }
+            else {
+                // No manifest reachable: parser + lowering only.
+                const parsed = parseSyqlFile(path, text);
+                void parsed;
+            }
+            return [];
+        }
+        catch (error) {
+            return [this.#errorToDiagnostic(error, text)];
+        }
+    }
+    #errorToDiagnostic(error, text) {
+        const message = error instanceof Error ? error.message : String(error);
+        let range = {
+            start: { line: 0, character: 0 },
+            end: { line: 0, character: 1 },
+        };
+        if (error instanceof TypegenError) {
+            // Cursor errors carry `file:line`; lowering errors carry
+            // `file (query name)` — anchor those at the declaration.
+            const lineMatch = /:(\d+): /.exec(message);
+            const queryMatch = /\(query ([A-Za-z][A-Za-z0-9]*)\)/.exec(message);
+            if (lineMatch !== null) {
+                const line = Number.parseInt(lineMatch[1], 10) - 1;
+                range = {
+                    start: { line, character: 0 },
+                    end: { line, character: 200 },
+                };
+            }
+            else if (queryMatch !== null) {
+                try {
+                    const parsed = parseSyqlFile('doc', text);
+                    const decl = parsed.queries.find((q) => q.name === queryMatch[1]);
+                    if (decl !== undefined) {
+                        const start = offsetToPosition(text, decl.offset);
+                        range = {
+                            start,
+                            end: { line: start.line, character: start.character + 200 },
+                        };
+                    }
+                }
+                catch {
+                    // fall through to line 0
+                }
+            }
+        }
+        return { range, severity: 1, source: 'syncular', message };
+    }
+    #hover(params) {
+        const p = params;
+        const text = this.#documents.get(p.textDocument.uri);
+        if (text === undefined)
+            return null;
+        const offset = positionToOffset(text, p.position);
+        const found = wordAt(text, offset);
+        if (found === null)
+            return null;
+        let parsed;
+        try {
+            parsed = parseSyqlFile('doc', text);
+        }
+        catch {
+            return null;
+        }
+        // `@fragment` ref → the fragment's body.
+        if (found.word.startsWith('@')) {
+            const fragment = parsed.fragments.find((f) => f.name === found.word.slice(1));
+            if (fragment === undefined)
+                return null;
+            return {
+                contents: {
+                    kind: 'markdown',
+                    value: `\`\`\`sql\n${fragment.body}\n\`\`\``,
+                },
+            };
+        }
+        // A query name → the lowered, checked SQL (needs the project schema).
+        const query = parsed.queries.find((q) => q.name === found.word);
+        if (query !== undefined) {
+            const context = this.#context(p.textDocument.uri);
+            if (context === null)
+                return null;
+            try {
+                const analyzed = analyzeSyqlFile('doc.syql', text, context.ir, context.db, context.naming).find((q) => q.name === found.word);
+                if (analyzed === undefined)
+                    return null;
+                const lines = [
+                    '```sql',
+                    analyzed.sql,
+                    '```',
+                    '',
+                    `tables: ${analyzed.tables.join(', ')}`,
+                    ...(analyzed.variants !== undefined
+                        ? [`variants: ${analyzed.variants.length} enumerated statements`]
+                        : []),
+                ];
+                return { contents: { kind: 'markdown', value: lines.join('\n') } };
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    #definition(params) {
+        const p = params;
+        const text = this.#documents.get(p.textDocument.uri);
+        if (text === undefined)
+            return null;
+        const offset = positionToOffset(text, p.position);
+        const found = wordAt(text, offset);
+        if (found === null || !found.word.startsWith('@'))
+            return null;
+        let parsed;
+        try {
+            parsed = parseSyqlFile('doc', text);
+        }
+        catch {
+            return null;
+        }
+        const fragment = parsed.fragments.find((f) => f.name === found.word.slice(1));
+        if (fragment === undefined)
+            return null;
+        const start = offsetToPosition(text, fragment.offset);
+        return {
+            uri: p.textDocument.uri,
+            range: {
+                start,
+                end: {
+                    line: start.line,
+                    character: start.character + 'fragment '.length + fragment.name.length,
+                },
+            },
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// stdio transport (Content-Length framing)
+// ---------------------------------------------------------------------------
+/** Run the language server over stdio until `exit`. */
+export async function runLspStdio() {
+    const server = new SyqlLanguageServer();
+    let buffer = Buffer.alloc(0);
+    const write = (message) => {
+        const body = Buffer.from(JSON.stringify(message), 'utf8');
+        process.stdout.write(Buffer.concat([
+            Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'),
+            body,
+        ]));
+    };
+    for await (const chunk of process.stdin) {
+        buffer = Buffer.concat([buffer, chunk]);
+        for (;;) {
+            const headerEnd = buffer.indexOf('\r\n\r\n');
+            if (headerEnd === -1)
+                break;
+            const header = buffer.subarray(0, headerEnd).toString('ascii');
+            const lengthMatch = /Content-Length: (\d+)/i.exec(header);
+            if (lengthMatch === null) {
+                buffer = buffer.subarray(headerEnd + 4);
+                continue;
+            }
+            const length = Number.parseInt(lengthMatch[1], 10);
+            if (buffer.length < headerEnd + 4 + length)
+                break;
+            const body = buffer.subarray(headerEnd + 4, headerEnd + 4 + length);
+            buffer = buffer.subarray(headerEnd + 4 + length);
+            let message;
+            try {
+                message = JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                continue;
+            }
+            if (message.method === 'exit')
+                return;
+            for (const outgoing of server.handle(message))
+                write(outgoing);
+        }
+    }
+}

package/dist/manifest.d.ts

@@ -1,3 +1,6 @@
+import type { NamingMode } from './naming.js';
+/** §7/§8 `.syql` conditional-lowering backend selection. */
+export type ManifestQueryBackend = 'neutralize' | 'variants' | 'auto';
 export declare const MANIFEST_FILENAME = "syncular.json";
 /** Same shorthand the server schema accepts (§3.1). */
 export type ManifestScopeSpec = string | {
@@ -67,6 +70,14 @@ export interface Manifest {
     /** Directory of `.sql` named-query files (default `./queries`). Only read
      * when at least one output requests a named-queries file. */
     readonly queries: string;
+    /** §5 casing: "camel" (default) maps snake_case SQL names to camelCase in
+     * 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. */
+    readonly queryBackend: ManifestQueryBackend;
     readonly output: ManifestOutput;
     readonly schemaVersions: readonly ManifestSchemaVersion[];
     readonly tables: readonly ManifestTable[];

package/dist/manifest.js

@@ -209,6 +209,8 @@ export function parseManifest(raw) {
         'manifestVersion',
         'migrations',
         'queries',
+        'naming',
+        'queryBackend',
         'output',
         'schemaVersions',
         'tables',
@@ -222,6 +224,22 @@ export function parseManifest(raw) {
         ? './migrations'
         : asString(obj.migrations, 'migrations');
     const queries = obj.queries === undefined ? './queries' : asString(obj.queries, 'queries');
+    let naming = 'camel';
+    if (obj.naming !== undefined) {
+        if (obj.naming !== 'camel' && obj.naming !== 'preserve') {
+            fail(`naming must be "camel" or "preserve", got ${JSON.stringify(obj.naming)}`);
+        }
+        naming = obj.naming;
+    }
+    let queryBackend = 'neutralize';
+    if (obj.queryBackend !== undefined) {
+        if (obj.queryBackend !== 'neutralize' &&
+            obj.queryBackend !== 'variants' &&
+            obj.queryBackend !== 'auto') {
+            fail(`queryBackend must be "neutralize", "variants" or "auto", got ${JSON.stringify(obj.queryBackend)}`);
+        }
+        queryBackend = obj.queryBackend;
+    }
     let ir = './syncular.ir.json';
     let module = './syncular.generated.ts';
     let queriesOut;
@@ -294,6 +312,8 @@ export function parseManifest(raw) {
         manifestVersion: 1,
         migrations,
         queries,
+        naming,
+        queryBackend,
         output: outputSpec,
         schemaVersions,
         tables,

package/dist/naming.d.ts

@@ -0,0 +1,22 @@
+/** Manifest `"naming"`: camelCase emission (default) or SQL-truth names. */
+export type NamingMode = 'camel' | 'preserve';
+/** The pinned §12 snake→camel conversion. Non-identifier names (computed
+ * result columns like `count(*)`) are returned unchanged. */
+export declare function snakeToCamel(name: string): string;
+/** The emitter targets whose keyword sets we police. `ts` is included for
+ * completeness (its emitters can quote any property, so its list is the
+ * small set that breaks generated FUNCTION/const identifiers). */
+export type NamingTarget = 'ts' | 'swift' | 'kotlin' | 'dart';
+/** One naming-map entry: the SQL-truth name and its language-facing name. */
+export interface NameMapping {
+    readonly sqlName: string;
+    readonly langName: string;
+}
+/**
+ * Map a set of SQL names to language names under `mode`, enforcing the §12
+ * hard errors within the scope (one table's columns / one query's projection
+ * / one query's params). `context` and `scope` name the error location
+ * (e.g. `queries/list.sql`, `table todos`); `targets` are the emitters this
+ * run generates — keyword hazards are only real on targets that exist.
+ */
+export declare function buildNamingMap(sqlNames: readonly string[], mode: NamingMode, context: string, scope: string, targets: readonly NamingTarget[]): NameMapping[];