sqllens 1.1.0 → 1.2.0

package/README.md

@@ -15,9 +15,7 @@ Athena, Fabric, and MariaDB (see [Dialects](#dialects)).
 
 The front end is error-tolerant and token-first, so the library drives editor
 features (completion, hover, diagnostics, go-to-definition) over incomplete,
-mid-edit text. See [Editor / language tooling](#editor--language-tooling). An LSP
-(Language Server Protocol) server built on it lives in the repo, but it is
-experimental and not part of the published package.
+mid-edit text. See [Editor / language tooling](#editor--language-tooling).
 
 ```bash
 npm install sqllens
@@ -208,7 +206,7 @@ import { parse, qualify, lineage, deriveSymbols, toScopes, Schema } from "sqllen
 const { ast, errors, cst } = parse("SELECT a, b FROM t", "snowflake");
 // ast = dialect-neutral IR (frozen); cst = the raw antlr tree (escape hatch)
 
-const scopes = toScopes(ast, { dialect: "snowflake" }); // idempotent lift
+const scopes = toScopes(ast); // idempotent lift
 qualify(scopes, schema);   // reuses scopes — never re-parses or re-resolves
 lineage(scopes, schema);   // safe on the same scopes, in any order
 deriveSymbols(scopes);     // independent results
@@ -381,76 +379,6 @@ doc.tokenAt(7);                   // token under an offset
 const next = doc.withText("SELECT amount, id FROM sales", 2); // immutable edit → new doc
 ```
 
-## Language server (experimental)
-
-An LSP (Language Server Protocol) server built on the library lives in `src/lsp/`.
-It is experimental and **not part of the published npm package**: the package ships
-the library only, and the server is source you run from the repo. It holds one
-`SqlDocument` per open file (rebuilt on edit) and reaches the library only through
-the public API, and adds no analysis of its own beyond protocol translation.
-
-A SQL server needs only a subset of LSP's ~30 request types: some don't apply to
-SQL (type hierarchy, document color, monikers), and a few are deferred (formatting,
-project-wide navigation). Where the server stands today, feature by feature:
-
-### Language features
-
-| Feature | Status |
-| --- | --- |
-| Completion (+ resolve) | ✅ |
-| Hover | ✅ |
-| Hover — nullability | ✅ (` — not null` / ` — nullable` suffix when provable) |
-| Signature help | ✅ |
-| Go to definition | ✅ |
-| Find references | ✅ |
-| Document highlight | ✅ |
-| Document symbols | ✅ |
-| Folding range | ✅ |
-| Selection range | ✅ |
-| Semantic tokens (full / range / delta) | ✅ all three |
-| Inlay hints | ✅ (no resolve) |
-| Code lens | ✅ (no resolve) |
-| Go to declaration | ◻️ not yet |
-| Go to type definition | ◻️ not yet |
-| Go to implementation | ◻️ not yet — name → its defining query (view / model); needs the project model |
-| Call hierarchy | ◻️ not yet — the CTE / view / model dependency graph |
-| Document link | ◻️ not yet |
-| Linked editing range | ◻️ not yet — live alias / name sync-edit |
-| Code action (quick fixes) | ◻️ next phase |
-| Rename (+ prepare) | ◻️ next phase |
-| Formatting / range / on-type | ◻️ deferred (external formatter) |
-| Inline values | ◻️ debugger surface |
-| Type hierarchy | — n/a — SQL has no type-inheritance relation |
-| Document color | — n/a — no color literals |
-| Moniker | — n/a — LSIF / cross-repo indexing concern |
-
-### Diagnostics & document sync
-
-| Feature | Status |
-| --- | --- |
-| Diagnostics — push (`publishDiagnostics`) | ✅ |
-| Diagnostics — call signature (arity / argument type) | ✅ (curated tables; never-wrong, per-dialect coercion) |
-| Diagnostics — pull (document) | ✅ |
-| Diagnostics — pull (workspace) | ◻️ not yet |
-| Text sync — open / change / close | ✅ (full-document) |
-| Incremental sync | ◻️ full-document only (fine at SQL file sizes) |
-| Save notifications (`didSave` / `willSave`) | ◻️ not yet |
-| Notebook document sync | ◻️ not yet |
-
-### Workspace features
-
-| Feature | Status |
-| --- | --- |
-| Workspace symbols | ◻️ needs a project / multi-file model |
-| Execute command | ◻️ not yet |
-| Configuration / watched-files | ◻️ not yet (protocol config; file-based `.sqllens.json` config exists) |
-| File operations (create / rename / delete) | ◻️ not yet |
-
-Legend: ✅ implemented · ◻️ not yet / deferred · — not applicable to SQL. The
-deferred items are tracked work: rename and
-code actions are the next LSP phase, workspace symbols need the project model,
-and formatting is expected to wrap an existing external formatter.
-
 ## How sqllens compares
 
 The SQL-parser field splits into parse-only libraries and semantic tools bound

package/THIRD-PARTY-NOTICES.md

@@ -120,14 +120,59 @@ Forked from [antlr/grammars-v4](https://github.com/antlr/grammars-v4)
 Positive Technologies; (c) 2017 Ivan Khudyashev. Licensed under the MIT License
 (full text retained in the file headers).
 
+## Doc-derived function-signature tables (distributed in this repository)
+
+The generated per-dialect function-signature tables (produced by
+`tools/harvest-signatures.mjs`, committed under `src/`) carry factual API-surface
+data (function names, parameter names, arity, optionality) extracted from each
+dialect's reference documentation. Sources and their licenses:
+
+### T-SQL signatures, from MicrosoftDocs/sql-docs (CC BY 4.0)
+
+Derived from the Transact-SQL reference markdown in
+[MicrosoftDocs/sql-docs](https://github.com/MicrosoftDocs/sql-docs), (c) Microsoft
+Corporation, licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+Changes were made: the documented syntax notation was mechanically parsed and
+transformed into TypeScript signature tables; no documentation prose is reproduced.
+
+### DuckDB signatures, from duckdb/duckdb-web (MIT)
+
+Derived from the function reference markdown in
+[duckdb/duckdb-web](https://github.com/duckdb/duckdb-web), Copyright 2018-2025
+Stichting DuckDB Foundation, MIT License.
+
+### PostgreSQL signatures, from the PostgreSQL documentation (PostgreSQL License)
+
+Derived from `doc/src/sgml/func.sgml` of
+[postgres/postgres](https://github.com/postgres/postgres) (REL_18_STABLE),
+Copyright (c) 1996-2025, PostgreSQL Global Development Group, PostgreSQL License.
+
+### Trino signatures, from trinodb/trino docs (Apache License 2.0)
+
+Derived from the sphinx function reference in
+[trinodb/trino](https://github.com/trinodb/trino) `docs/src/main/sphinx/functions`
+(release 482), Apache License 2.0. trinodb/trino ships no `NOTICE` file, so there
+is no 4(d) attribution to reproduce.
+
+### BigQuery / GoogleSQL signatures, from google/googlesql docs (Apache License 2.0)
+
+Derived from the function reference markdown in
+[google/googlesql](https://github.com/google/googlesql) `docs/`, (c) Google LLC,
+Apache License 2.0.
+
+### Databricks and Snowflake signatures, from the vendors' public SQL references
+
+Derived from the Syntax sections of the public SQL language references at
+[docs.databricks.com](https://docs.databricks.com) ((c) Databricks, Inc.) and
+[docs.snowflake.com](https://docs.snowflake.com) ((c) Snowflake Inc.). These sites
+publish no redistribution license; the tables reproduce only the factual call
+shape of each function (name, parameter names, arity, optionality), the same facts
+any SQL tool documents about a dialect's API surface, and no documentation prose.
+Credited here as sources with thanks.
+
 ## Runtime and build dependencies (not redistributed in source)
 
 - **antlr4ng** — the TypeScript ANTLR runtime (BSD-3-Clause). Runtime dependency.
 - **antlr-ng** — the pure-TypeScript ANTLR generator used by `npm run gen` to
   produce `src/generated/` (a build product, gitignored). Dev dependency.
-- **vscode-languageserver** / **vscode-languageserver-protocol** /
-  **vscode-languageserver-textdocument** / **vscode-languageserver-types** — the
-  LSP layer's runtime dependencies (MIT).
-- **minimatch** — glob matching used by the LSP layer (ISC).
-
 Consult each package's own license for the authoritative terms.

package/dist/api.d.ts

@@ -117,10 +117,12 @@ export { SqlDocument, type DocumentAnalysis, type StatementCell, type DocumentVa
 export { LineIndex } from "./document/line-index.js";
 export type { StatementCellSpan } from "./document/split.js";
 export { complete, completeAt, type Completion } from "./completion/complete.js";
-export { signatureAt, type SignatureInfo } from "./signature/signature.js";
-export { FUNCTION_SIGNATURES, HARVESTED_SIGNATURES, lookupSignature, hasSignature, type FnSignature, type ParamSig, } from "./signature/signatures.js";
+export { jinjaSlotAt, type JinjaSlot } from "./completion/jinja-slot.js";
+export { signatureAt, type SignatureHelpInfo, type SignatureLabel } from "./signature/signature.js";
+export { SIGNATURES, lookupSignature, hasSignature, type FnSignature, type ParamSig } from "./signature/signatures.js";
 export { referencesAt, type Occurrence, type Occurrences } from "./references/references.js";
 export { dialectSymbols, type DialectSymbols } from "./dialect-symbols.js";
 export { CallbackSchema, type SchemaProvider, type TableResolver } from "./qualify/schema-provider.js";
 export { DERIVED_DIALECTS, resolveDialect } from "./derived-dialects.js";
-export { foldIdentifier, displayName, type IdentKind } from "./ident/fold.js";
+export { foldIdentifier, displayName } from "./dialect-behavior/public-fold.js";
+export type { IdentKind } from "./ident/fold.js";

package/dist/api.js

@@ -205,11 +205,18 @@ export { LineIndex } from "./document/line-index.js";
 // Scope-aware completion over a SqlDocument — the broken-input editor feature (keywords + schema
 // tables/columns + function names at the caret). Total: never throws.
 export { complete, completeAt } from "./completion/complete.js";
+// The NEUTRAL half of jinja completion: which call + arg slot the caret sits in inside a jinja tag
+// (`{{ ref('cu│` → { callee: "ref", argIndex: 0, prefix: "cu" }). Carries no dbt vocabulary; a
+// consumer maps callee + argIndex to a role and supplies candidates. Reuses the parsed tags.
+export { jinjaSlotAt } from "./completion/jinja-slot.js";
 // Signature help over a SqlDocument — the broken-input editor feature that shows parameter hints
-// while typing inside a call's parens. Lookup order: curated (hand-verified) → harvested (doc-derived
-// long tail, from tools/harvest-signatures.mjs) → name-only fallback. A pure token scan; never throws.
+// while typing inside a call's parens. SIGNATURES is the merged per-dialect table (curated overrides
+// folded over the harvested doc-derived long tail at generation time, tools/harvest-signatures.mjs);
+// a name maps to an overload SET (readonly FnSignature[]), not a single shape: it is common for a
+// builtin to be overloaded on argument type or arity. An unknown name degrades to a one-entry
+// name-only fallback. A pure token scan; never throws.
 export { signatureAt } from "./signature/signature.js";
-export { FUNCTION_SIGNATURES, HARVESTED_SIGNATURES, lookupSignature, hasSignature, } from "./signature/signatures.js";
+export { SIGNATURES, lookupSignature, hasSignature } from "./signature/signatures.js";
 // References / occurrence engine — find the declaration + every occurrence of the symbol under a
 // cursor offset. The core primitive behind LSP references / documentHighlight / codeLens / rename.
 // Total: never throws; returns null off-symbol.
@@ -228,4 +235,4 @@ export { DERIVED_DIALECTS, resolveDialect } from "./derived-dialects.js";
 // The dialect-true identifier fold — the identity key for name comparison (unquote + case-fold per
 // the dialect's documented rules) and its display twin (unquote only). Exported so an embedding
 // consumer comparing names against IR/scope output folds the same way the pipeline does.
-export { foldIdentifier, displayName } from "./ident/fold.js";
+export { foldIdentifier, displayName } from "./dialect-behavior/public-fold.js";

package/dist/bigquery/behavior.d.ts

@@ -0,0 +1,2 @@
+import type { DialectBehavior } from "../dialect-behavior/behavior.js";
+export declare const bigqueryBehavior: DialectBehavior;

package/dist/bigquery/behavior.js

@@ -0,0 +1,20 @@
+import { acceptsFor } from "../dialect-behavior/coerce-rules.js";
+import { likePatternToRegExp } from "../scope/like-pattern.js";
+import { SIGNATURES } from "../signature/signatures.js";
+import { displayName, fold, foldTableName, matchesSourceKey } from "./fold.js";
+import { bigqueryLiteral, bigqueryParseType, bigquerySpecial, BIGQUERY_FUNCTION_RETURNS } from "./infer.js";
+export const bigqueryBehavior = {
+    fold,
+    displayName,
+    foldTableName,
+    matchesSourceKey,
+    likeMatch: (pattern, value) => likePatternToRegExp(pattern).test(value),
+    literal: bigqueryLiteral,
+    parseType: bigqueryParseType,
+    functions: BIGQUERY_FUNCTION_RETURNS,
+    division: "float",
+    special: bigquerySpecial,
+    signatures: SIGNATURES.bigquery,
+    // BigQuery implicit coercion: no STRING->NUMBER coercion, no BOOL<->NUMBER coercion (STR_TO_NUM=false, BOOL_NUM=false).
+    accepts: (argType, paramText) => acceptsFor(bigqueryParseType, false, false, argType, paramText),
+};

package/dist/bigquery/dot-path.d.ts

@@ -1,5 +1,4 @@
 import { type Lexer, ListTokenSource } from "antlr4ng";
-import { GoogleSQLLexer } from "../generated/bigquery/GoogleSQLLexer.js";
 import type { SyntaxDiagnostic } from "../parse-diagnostics.js";
 /**
  * Lex `sql` and return a token source with the DOT_IDENTIFIER rewrite applied, plus positioned
@@ -11,4 +10,3 @@ export declare function dotPathTokenSource(sql: string, lexer: Lexer): {
     source: ListTokenSource;
     escapeDiagnostics: SyntaxDiagnostic[];
 };
-export { GoogleSQLLexer };

package/dist/bigquery/dot-path.js

@@ -365,4 +365,3 @@ export function dotPathTokenSource(sql, lexer) {
     const tokens = lexer.getAllTokens(); // full lex (drives lexer error listeners); EOF excluded
     return { source: new ListTokenSource(rewriteDotPaths(tokens)), escapeDiagnostics: badLiteralEscapes(tokens) };
 }
-export { GoogleSQLLexer };

package/dist/bigquery/fold.d.ts

@@ -0,0 +1,8 @@
+import { type FoldRule, type IdentKind } from "../ident/fold.js";
+export declare const BIGQUERY_FOLD_RULE: FoldRule;
+/** Fold an identifier to its BigQuery identity key. */
+export declare function fold(raw: string, kind?: IdentKind): string;
+/** Presentation twin: strip delimiters, no case change. */
+export declare function displayName(raw: string): string;
+export declare function foldTableName(parts: string[]): string[];
+export declare function matchesSourceKey(key: string, rawPart: string): boolean;

package/dist/bigquery/fold.js

@@ -0,0 +1,39 @@
+// BigQuery identifier folding. The FoldRule plus its bound engine, colocated here because BOTH the
+// upstream lower() and the downstream DialectBehavior need it (the fold rule is the one dialect concern
+// used at two stages).
+//
+// cloud.google.com/bigquery/docs/reference/standard-sql/lexical — verified live (via search,
+// the JS-rendered page would not return body text to WebFetch): "table names are case-sensitive,
+// but column names are not" — so table identifiers preserve case and everything else (column,
+// field, alias, CTE) folds to lower, REGARDLESS of backtick-quoting either way (backticks are
+// required for reserved words/specials, not a case-quoting mechanism — same "not case-quoting"
+// shape as Databricks, but the preserved/folded split is per identifier KIND here, not
+// per-quoting). Escape mechanism corrected from the originally assumed doubling: "Quoted
+// identifiers have the same escape sequences as string literals" (backslash-escaped, e.g.
+// `` `a\`b` `` → `` a`b ``) — NOT doubling like every other backtick/quote dialect here. This
+// module unescapes the identifier-relevant case (`` \` ``) plus the general `\X`→`X` pattern; it
+// does not implement BigQuery's full string-literal escape grammar (\n, \xHH, \uXXXX, octal, …),
+// out of scope for an identifier fold — those escapes are exotic in identifier text.
+import { displayWith, foldWith } from "../ident/fold.js";
+const BACKTICK = ["`", "`"];
+export const BIGQUERY_FOLD_RULE = {
+    delimiters: [BACKTICK],
+    unquoted: "lower",
+    quoted: "lower",
+    tableCase: "preserve",
+    escapeStyle: "backslash",
+};
+/** Fold an identifier to its BigQuery identity key. */
+export function fold(raw, kind = "other") {
+    return foldWith(BIGQUERY_FOLD_RULE, raw, kind);
+}
+/** Presentation twin: strip delimiters, no case change. */
+export function displayName(raw) {
+    return displayWith(BIGQUERY_FOLD_RULE, raw);
+}
+export function foldTableName(parts) {
+    return parts.map((p) => fold(p, "table"));
+}
+export function matchesSourceKey(key, rawPart) {
+    return key === fold(rawPart) || key === fold(rawPart, "table");
+}

package/dist/bigquery/index.d.ts

@@ -0,0 +1,7 @@
+import { lower } from "./lower.js";
+import { parseBigQuery } from "./parse.js";
+export declare const bigquery: {
+    parse: typeof parseBigQuery;
+    lower: typeof lower;
+    behavior: import("../dialect-behavior/behavior.js").DialectBehavior;
+};

package/dist/bigquery/index.js

@@ -0,0 +1,10 @@
+// The complete bigquery dialect module: parse + lower (front end) and behavior (semantic knowledge).
+// The registry wires this; to understand everything sqllens does for bigquery, read this folder.
+import { bigqueryBehavior } from "./behavior.js";
+import { lower } from "./lower.js";
+import { parseBigQuery } from "./parse.js";
+export const bigquery = {
+    parse: parseBigQuery,
+    lower,
+    behavior: bigqueryBehavior,
+};

package/dist/{infer/bigquery.d.ts → bigquery/infer.d.ts}

@@ -1,6 +1,6 @@
 import type { Expr } from "../ir/ir.js";
-import type { FnRule } from "./functions.js";
-import { type Type } from "./types.js";
+import type { FnRule } from "../infer/functions.js";
+import { type Type } from "../infer/types.js";
 export declare const BQ_ALIASES: Record<string, string>;
 export declare function bigqueryParseType(text: string): Type;
 export declare function bigqueryLiteral(text: string): Type;

package/dist/{infer/bigquery.js → bigquery/infer.js}

@@ -1,5 +1,6 @@
-import { commonType } from "./coerce.js";
-import { parseType, scalar, UNKNOWN } from "./types.js";
+import { commonType } from "../infer/coerce.js";
+import { parseType, scalar, UNKNOWN } from "../infer/types.js";
+import { fold } from "./fold.js";
 // BigQuery / GoogleSQL inference knowledge — function return types, literal forms, and scalar-type
 // aliases — from the GoogleSQL function reference
 // (cloud.google.com/bigquery/docs/reference/standard-sql/functions-and-operators). Same contract as
@@ -24,7 +25,7 @@ export const BQ_ALIASES = {
     geography: "geography",
 };
 export function bigqueryParseType(text) {
-    return parseType(text, BQ_ALIASES, "bigquery");
+    return parseType(text, BQ_ALIASES, fold);
 }
 export function bigqueryLiteral(text) {
     const t = text.trim();

package/dist/bigquery/lower.js

@@ -1549,37 +1549,60 @@ function lowerFunctionCall(node) {
         name = (keyword ? keyword.getText() : (leftmostToken(node) ?? "")).toLowerCase();
     }
     const suffix = directChildrenOfRule(node, P.RULE_function_call_expression_with_clauses_suffix)[0];
-    const args = suffix ? collectCallArgs(suffix) : [];
+    const { args, argNames } = suffix ? collectCallArgs(suffix) : { args: [], argNames: [] };
     const over = suffix ? firstOfRule(suffix, P.RULE_over_clause) : undefined;
     const window = over ? lowerOver(over) : undefined;
     const distinct = hasDirectToken(node, P.DISTINCT_SYMBOL);
-    return { kind: "function", name, qualifier, args, aggregate: AGGREGATES.has(name), distinct, window, cst: node };
+    return {
+        kind: "function",
+        name,
+        qualifier,
+        args,
+        // Named-argument invocation `fn(name => value)`: the per-arg names make the call
+        // conservation-visible and let the arity checker's named-arg bypass fire (a named call's
+        // positional count says nothing about the documented positional signature).
+        ...(argNames.some((n) => n !== undefined) ? { argNames } : {}),
+        aggregate: AGGREGATES.has(name),
+        distinct,
+        window,
+        cst: node,
+    };
 }
-/** function_call_argument children of the suffix (skipping nested calls' own args). */
+/** function_call_argument children of the suffix (skipping nested calls' own args), with the
+ *  `name => value` parameter name per arg slot (undefined for positional args). */
 function collectCallArgs(suffix) {
-    const out = [];
+    const args = [];
+    const argNames = [];
     for (const arg of shallowNodesOfRule(suffix, P.RULE_function_call_argument)) {
         // function_call_argument: expression alias? | named_argument | lambda_argument | sequence_arg
         const named = directChildrenOfRule(arg, P.RULE_named_argument)[0];
         if (named) {
+            const argName = directChildrenOfRule(named, P.RULE_identifier)[0]?.getText();
             const e = directChildrenOfRule(named, P.RULE_expression)[0];
-            if (e)
-                out.push(lowerExpr(e));
+            if (e) {
+                args.push(lowerExpr(e));
+                argNames.push(argName);
+            }
             const lam = directChildrenOfRule(named, P.RULE_lambda_argument)[0];
-            if (lam)
-                out.push(lowerLambda(lam));
+            if (lam) {
+                args.push(lowerLambda(lam));
+                argNames.push(argName);
+            }
             continue;
         }
         const lambda = directChildrenOfRule(arg, P.RULE_lambda_argument)[0];
         if (lambda) {
-            out.push(lowerLambda(lambda));
+            args.push(lowerLambda(lambda));
+            argNames.push(undefined);
             continue;
         }
         const e = directChildrenOfRule(arg, P.RULE_expression)[0];
-        if (e)
-            out.push(lowerExpr(e));
+        if (e) {
+            args.push(lowerExpr(e));
+            argNames.push(undefined);
+        }
     }
-    return out;
+    return { args, argNames };
 }
 /** lambda_argument: lambda_argument_list -> expression. */
 function lowerLambda(node) {

package/dist/bigquery/signatures.generated.d.ts

@@ -0,0 +1,6 @@
+import type { FnSignature } from "../signature/signatures.js";
+/** The merged function-signature table for bigquery: curated overrides folded over the harvested
+ *  doc-derived long tail (overrides win by key, replacing the whole overload set), keyed by
+ *  lowercased name. Each name maps to an ORDERED overload set - a name with one documented shape
+ *  is a one-element array. `origin` says which layer produced the set. */
+export declare const BIGQUERY_SIGNATURES: Record<string, FnSignature[]>;