sqllens 1.5.1 → 1.7.0

package/dist/api.d.ts

@@ -116,14 +116,18 @@ export type { Token, TokenRole } from "./token/token.js";
 export { SqlDocument, type DocumentAnalysis, type StatementCell, type DocumentVariant, type UnionCte, } from "./document/document.js";
 export { LineIndex } from "./document/line-index.js";
 export type { StatementCellSpan } from "./document/split.js";
-export { complete, completeAt, type Completion } from "./completion/complete.js";
+export { complete, completeAt, type Completion, type CompletionResult, type ReplaceRange, type CompleteOptions, type CandidateIdentity, type CandidateDecoration, type DecorateCandidate, } from "./completion/complete.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 { renderSignature, type RenderSignatureOptions } from "./signature/render.js";
 export { FN_DOCS, lookupFnDoc, type FnDoc } from "./signature/docs.js";
 export { referencesAt, type Occurrence, type Occurrences } from "./references/references.js";
-export { dialectSymbols, type DialectSymbols } from "./dialect-symbols.js";
+export { frameAt, type Frame } from "./scope/frame.js";
+export { clausesOf, type ClauseInfo, type ClauseKind } from "./scope/clauses.js";
+export { setOpArmsOf, type SetOpArm, type SetOpArms } from "./scope/setop-arms.js";
+export { dialectSymbols, dialectVocabulary, type DialectSymbols, type DialectVocabulary } from "./dialect-symbols.js";
+export { reservedKeywords, type KeywordEntry, type KeywordReservation } 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 } from "./dialect-behavior/public-fold.js";

package/dist/api.js

@@ -204,7 +204,7 @@ export { SqlDocument, } from "./document/document.js";
 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";
+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.
@@ -223,9 +223,16 @@ export { FN_DOCS, lookupFnDoc } from "./signature/docs.js";
 // cursor offset. The core primitive behind LSP references / documentHighlight / codeLens / rename.
 // Total: never throws; returns null off-symbol.
 export { referencesAt } from "./references/references.js";
+// Frame / clause / set-op-arm geometry: the SQL debugger's marker-planting primitives, which frame
+// (CTE) a document position sits in, that frame's ordered clause list, and set-op arm spans. Total:
+// never throws; frameAt/clausesOf/setOpArmsOf all degrade to undefined/[] off-symbol or off-shape.
+export { frameAt } from "./scope/frame.js";
+export { clausesOf } from "./scope/clauses.js";
+export { setOpArmsOf } from "./scope/setop-arms.js";
 // Per-dialect function/keyword/type-name membership sets — for lint-style "is this identifier a
 // known X for this dialect?" checks. Computed once per dialect and cached.
-export { dialectSymbols } from "./dialect-symbols.js";
+export { dialectSymbols, dialectVocabulary } from "./dialect-symbols.js";
+export { reservedKeywords } from "./dialect-symbols.js";
 // The catalog interface the whole pipeline resolves against, plus its resolve-on-demand
 // implementation. `Schema` (a full upfront mapping) and `CallbackSchema` (a host-driven
 // lazy resolver whose prime() bumps a version to invalidate SqlDocument.analyze's memo) both

package/dist/bigquery/lower.js

@@ -1482,9 +1482,11 @@ function lowerLeaf(node) {
         case P.RULE_floating_point_literal:
         case P.RULE_date_or_time_literal:
         case P.RULE_range_literal:
+            return { kind: "literal", text: node.getText(), cst: node };
         case P.RULE_parameter_expression:
+            return lowerParameterExpression(node);
         case P.RULE_system_variable_expression:
-            return { kind: "literal", text: node.getText(), cst: node };
+            return lowerSystemVariableExpression(node);
         case P.RULE_identifier:
             return { kind: "column", parts: [identText(node)], partSpans: partSpansOf([node]), cst: node };
         case P.RULE_path_expression:
@@ -1844,7 +1846,12 @@ function columnsOf(expr, acc, clause) {
             break;
         case "subscript":
             columnsOf(expr.base, acc, clause);
-            columnsOf(expr.index, acc, clause);
+            if (expr.index)
+                columnsOf(expr.index, acc, clause);
+            if (expr.end)
+                columnsOf(expr.end, acc, clause);
+            if (expr.step)
+                columnsOf(expr.step, acc, clause);
             break;
         case "lambda":
             columnsOf(expr.body, acc, clause);
@@ -1949,6 +1956,25 @@ function extractExpressionSubqueries(select, fromQueries) {
     return out;
 }
 // --- name helpers ----------------------------------------------------------------
+/** parameter_expression: named_parameter_expression | QUESTION_SYMBOL
+ *  (cloud.google.com/bigquery/docs/parameterized-queries). Bare `?` carries no name/ordinal —
+ *  BigQuery's positional form has no explicit index, so `ordinal` stays a consumer derivation,
+ *  never fabricated here. `@name` resolves through named_parameter_expression's single
+ *  dot_identifier; reusing pathParts is safe since that rule holds exactly one dot_identifier
+ *  and no identifier head, so it degenerates to a one-element (dot-split, backtick-stripped) path. */
+function lowerParameterExpression(node) {
+    const named = firstOfRule(node, P.RULE_named_parameter_expression);
+    if (!named)
+        return { kind: "parameter", text: node.getText(), cst: node };
+    return { kind: "parameter", text: node.getText(), name: pathParts(named).join("."), cst: node };
+}
+/** system_variable_expression: ATAT_SYMBOL dot_identifier (DOT_SYMBOL dot_identifier)* — a script-
+ *  level system variable (cloud.google.com/bigquery/docs/reference/system-variables), e.g.
+ *  `@@dataset_id` or the dotted `@@a.b`. `name` is the dotted path with the `@@` sigil stripped;
+ *  pathParts already handles this shape (no identifier head, one-or-more dot_identifier tail). */
+function lowerSystemVariableExpression(node) {
+    return { kind: "variable", text: node.getText(), name: pathParts(node).join("."), system: true, cst: node };
+}
 /** path_expression: identifier (DOT dot_identifier)* — the dotted parts. The head is an identifier;
  *  later parts are dot_identifier (which may be a reserved keyword after the dot). A single
  *  backtick-quoted identifier may itself hold a dotted path (`proj.ds.t`), so split each part on `.`. */

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

@@ -0,0 +1,2 @@
+import type { KeywordReservation } from "../dialect-symbols.js";
+export declare const BIGQUERY_RESERVED: Record<string, KeywordReservation>;

package/dist/bigquery/reserved.generated.js

@@ -0,0 +1,325 @@
+export const BIGQUERY_RESERVED = {
+    ABORT: { reserved: false, alias: true, column: true, table: true },
+    ACCESS: { reserved: false, alias: true, column: true, table: true },
+    ACTION: { reserved: false, alias: true, column: true, table: true },
+    ACYCLIC: { reserved: false, alias: true, column: true, table: true },
+    ADD: { reserved: false, alias: true, column: true, table: true },
+    AFTER: { reserved: false, alias: true, column: true, table: true },
+    AGGREGATE: { reserved: false, alias: true, column: true, table: true },
+    ALL: { reserved: true, alias: false, column: false, table: false },
+    ALTER: { reserved: false, alias: true, column: true, table: true },
+    ALWAYS: { reserved: false, alias: true, column: true, table: true },
+    ANALYZE: { reserved: false, alias: true, column: true, table: true },
+    AND: { reserved: true, alias: false, column: false, table: false },
+    ANY: { reserved: true, alias: false, column: false, table: false },
+    APPROX: { reserved: false, alias: true, column: true, table: true },
+    ARE: { reserved: false, alias: true, column: true, table: true },
+    ARRAY: { reserved: true, alias: false, column: false, table: false },
+    AS: { reserved: true, alias: false, column: false, table: false },
+    ASC: { reserved: true, alias: false, column: false, table: false },
+    ASCENDING: { reserved: false, alias: true, column: true, table: true },
+    ASSERT: { reserved: false, alias: true, column: true, table: true },
+    ASSERT_ROWS_MODIFIED: { reserved: true, alias: false, column: false, table: false },
+    AT: { reserved: false, alias: true, column: true, table: true },
+    BATCH: { reserved: false, alias: true, column: true, table: true },
+    BEGIN: { reserved: false, alias: true, column: true, table: true },
+    BETWEEN: { reserved: true, alias: false, column: false, table: false },
+    BIGDECIMAL: { reserved: false, alias: true, column: true, table: true },
+    BIGNUMERIC: { reserved: false, alias: true, column: true, table: true },
+    BREAK: { reserved: false, alias: true, column: true, table: true },
+    BY: { reserved: true, alias: false, column: false, table: false },
+    CALL: { reserved: false, alias: true, column: true, table: true },
+    CASCADE: { reserved: false, alias: true, column: true, table: true },
+    CASE: { reserved: true, alias: false, column: false, table: false },
+    CAST: { reserved: true, alias: false, column: false, table: false },
+    CHEAPEST: { reserved: false, alias: true, column: true, table: true },
+    CHECK: { reserved: false, alias: true, column: true, table: true },
+    CLAMPED: { reserved: false, alias: true, column: true, table: true },
+    CLONE: { reserved: false, alias: true, column: true, table: true },
+    CLUSTER: { reserved: false, alias: true, column: true, table: true },
+    COLLATE: { reserved: true, alias: false, column: false, table: false },
+    COLUMN: { reserved: false, alias: true, column: true, table: true },
+    COLUMNS: { reserved: false, alias: true, column: true, table: true },
+    COMMIT: { reserved: false, alias: true, column: true, table: true },
+    CONFLICT: { reserved: false, alias: true, column: true, table: true },
+    CONNECTION: { reserved: false, alias: true, column: true, table: true },
+    CONSTANT: { reserved: false, alias: true, column: true, table: true },
+    CONSTRAINT: { reserved: false, alias: true, column: true, table: true },
+    CONTINUE: { reserved: false, alias: true, column: true, table: true },
+    COPY: { reserved: false, alias: true, column: true, table: true },
+    CORRESPONDING: { reserved: false, alias: true, column: true, table: true },
+    COST: { reserved: false, alias: true, column: true, table: true },
+    CREATE: { reserved: true, alias: false, column: false, table: false },
+    CROSS: { reserved: true, alias: false, column: false, table: false },
+    CUBE: { reserved: true, alias: false, column: false, table: false },
+    CURRENT: { reserved: true, alias: false, column: false, table: false },
+    CYCLE: { reserved: false, alias: true, column: true, table: true },
+    DATA: { reserved: false, alias: true, column: true, table: true },
+    DATABASE: { reserved: false, alias: true, column: true, table: true },
+    DATE: { reserved: false, alias: true, column: true, table: true },
+    DATETIME: { reserved: false, alias: true, column: true, table: true },
+    DECIMAL: { reserved: false, alias: true, column: true, table: true },
+    DECLARE: { reserved: false, alias: true, column: true, table: true },
+    DEFAULT: { reserved: true, alias: false, column: false, table: false },
+    DEFINE: { reserved: true, alias: false, column: false, table: false },
+    DEFINER: { reserved: false, alias: true, column: true, table: true },
+    DELETE: { reserved: false, alias: true, column: true, table: true },
+    DELETION: { reserved: false, alias: true, column: true, table: true },
+    DELTA: { reserved: false, alias: true, column: true, table: true },
+    DEPTH: { reserved: false, alias: true, column: true, table: true },
+    DESC: { reserved: true, alias: false, column: false, table: false },
+    DESCENDING: { reserved: false, alias: true, column: true, table: true },
+    DESCRIBE: { reserved: false, alias: true, column: true, table: true },
+    DESCRIPTOR: { reserved: false, alias: true, column: true, table: true },
+    DESTINATION: { reserved: false, alias: true, column: true, table: true },
+    DETERMINISTIC: { reserved: false, alias: true, column: true, table: true },
+    DIFFERENTIAL_PRIVACY: { reserved: false, alias: true, column: true, table: true },
+    DISTINCT: { reserved: true, alias: false, column: false, table: false },
+    DO: { reserved: false, alias: true, column: true, table: true },
+    DROP: { reserved: false, alias: true, column: true, table: true },
+    DYNAMIC: { reserved: false, alias: true, column: true, table: true },
+    EDGE: { reserved: false, alias: true, column: true, table: true },
+    ELSE: { reserved: true, alias: false, column: false, table: false },
+    ELSEIF: { reserved: false, alias: true, column: true, table: true },
+    END: { reserved: true, alias: false, column: false, table: false },
+    ENFORCED: { reserved: false, alias: true, column: true, table: true },
+    ENUM: { reserved: true, alias: false, column: false, table: false },
+    EPSILON: { reserved: false, alias: true, column: true, table: true },
+    ERROR: { reserved: false, alias: true, column: true, table: true },
+    EXCEPT: { reserved: true, alias: false, column: false, table: false },
+    EXCEPTION: { reserved: false, alias: true, column: true, table: true },
+    EXCLUDE: { reserved: true, alias: false, column: false, table: false },
+    EXECUTE: { reserved: false, alias: true, column: true, table: true },
+    EXISTS: { reserved: true, alias: false, column: false, table: false },
+    EXPLAIN: { reserved: false, alias: true, column: true, table: true },
+    EXPORT: { reserved: false, alias: true, column: true, table: true },
+    EXTEND: { reserved: false, alias: true, column: true, table: true },
+    EXTERNAL: { reserved: false, alias: true, column: true, table: true },
+    EXTRACT: { reserved: true, alias: false, column: false, table: false },
+    FALSE: { reserved: false, alias: false, column: true, table: false },
+    FILES: { reserved: false, alias: true, column: true, table: true },
+    FILL: { reserved: false, alias: true, column: true, table: true },
+    FILTER: { reserved: false, alias: true, column: true, table: true },
+    FIRST: { reserved: false, alias: true, column: true, table: true },
+    FOLLOWING: { reserved: true, alias: false, column: false, table: false },
+    FOR: { reserved: true, alias: false, column: false, table: false },
+    FOREIGN: { reserved: false, alias: true, column: true, table: true },
+    FORK: { reserved: false, alias: true, column: true, table: true },
+    FORMAT: { reserved: false, alias: true, column: true, table: true },
+    FROM: { reserved: true, alias: false, column: false, table: false },
+    FULL: { reserved: true, alias: false, column: false, table: false },
+    FUNCTION: { reserved: false, alias: true, column: true, table: true },
+    GENERATED: { reserved: false, alias: true, column: true, table: true },
+    GRANT: { reserved: false, alias: true, column: true, table: true },
+    GRAPH: { reserved: false, alias: true, column: true, table: true },
+    GRAPH_TABLE: { reserved: false, alias: true, column: true, table: true },
+    GROUP: { reserved: true, alias: false, column: false, table: false },
+    GROUPING: { reserved: true, alias: false, column: false, table: false },
+    GROUP_ROWS: { reserved: false, alias: true, column: true, table: true },
+    HASH: { reserved: true, alias: false, column: false, table: false },
+    HAVING: { reserved: true, alias: false, column: false, table: false },
+    HIDDEN: { reserved: false, alias: true, column: true, table: true },
+    IDENTITY: { reserved: false, alias: true, column: true, table: true },
+    IF: { reserved: true, alias: false, column: false, table: false },
+    IGNORE: { reserved: true, alias: false, column: false, table: false },
+    IMMEDIATE: { reserved: false, alias: true, column: true, table: true },
+    IMMUTABLE: { reserved: false, alias: true, column: true, table: true },
+    IMPORT: { reserved: false, alias: true, column: true, table: true },
+    IN: { reserved: true, alias: false, column: false, table: false },
+    INCLUDE: { reserved: false, alias: true, column: true, table: true },
+    INCREMENT: { reserved: false, alias: true, column: true, table: true },
+    INDEX: { reserved: false, alias: true, column: true, table: true },
+    INNER: { reserved: true, alias: false, column: false, table: false },
+    INOUT: { reserved: false, alias: true, column: true, table: true },
+    INPUT: { reserved: false, alias: true, column: true, table: true },
+    INSERT: { reserved: false, alias: true, column: true, table: true },
+    INTERLEAVE: { reserved: false, alias: true, column: true, table: true },
+    INTERSECT: { reserved: true, alias: false, column: false, table: false },
+    INTERVAL: { reserved: true, alias: false, column: false, table: false },
+    INTO: { reserved: true, alias: false, column: false, table: false },
+    INVOKER: { reserved: false, alias: true, column: true, table: true },
+    IS: { reserved: true, alias: false, column: false, table: false },
+    ISOLATION: { reserved: false, alias: true, column: true, table: true },
+    ITERATE: { reserved: false, alias: true, column: true, table: true },
+    JOIN: { reserved: true, alias: false, column: false, table: false },
+    JSON: { reserved: false, alias: true, column: true, table: true },
+    KEY: { reserved: false, alias: true, column: true, table: true },
+    KW_MATCH_RECOGNIZE_NONRESERVED: { reserved: false, alias: true, column: true, table: true },
+    LABEL: { reserved: false, alias: true, column: true, table: true },
+    LABELED: { reserved: false, alias: true, column: true, table: true },
+    LANGUAGE: { reserved: false, alias: true, column: true, table: true },
+    LAST: { reserved: false, alias: true, column: true, table: true },
+    LATERAL: { reserved: true, alias: false, column: false, table: false },
+    LEAVE: { reserved: false, alias: true, column: true, table: true },
+    LEFT: { reserved: true, alias: false, column: false, table: false },
+    LET: { reserved: false, alias: true, column: true, table: true },
+    LEVEL: { reserved: false, alias: true, column: true, table: true },
+    LIKE: { reserved: true, alias: false, column: false, table: false },
+    LIMIT: { reserved: true, alias: false, column: false, table: false },
+    LOAD: { reserved: false, alias: true, column: true, table: true },
+    LOG: { reserved: false, alias: true, column: true, table: true },
+    LOOKUP: { reserved: true, alias: false, column: false, table: false },
+    LOOP: { reserved: false, alias: true, column: true, table: true },
+    MACRO: { reserved: false, alias: true, column: true, table: true },
+    MAP: { reserved: false, alias: true, column: true, table: true },
+    MATCH: { reserved: false, alias: true, column: true, table: true },
+    MATCHED: { reserved: false, alias: true, column: true, table: true },
+    MATCH_RECOGNIZE: { reserved: true, alias: false, column: false, table: false },
+    MATERIALIZED: { reserved: false, alias: true, column: true, table: true },
+    MAX: { reserved: false, alias: true, column: true, table: true },
+    MAXVALUE: { reserved: false, alias: true, column: true, table: true },
+    MAX_GROUPS_CONTRIBUTED: { reserved: false, alias: true, column: true, table: true },
+    MEASURES: { reserved: false, alias: true, column: true, table: true },
+    MERGE: { reserved: true, alias: false, column: false, table: false },
+    MESSAGE: { reserved: false, alias: true, column: true, table: true },
+    METADATA: { reserved: false, alias: true, column: true, table: true },
+    MIN: { reserved: false, alias: true, column: true, table: true },
+    MINVALUE: { reserved: false, alias: true, column: true, table: true },
+    MODEL: { reserved: false, alias: true, column: true, table: true },
+    MODULE: { reserved: false, alias: true, column: true, table: true },
+    NAME: { reserved: false, alias: true, column: true, table: true },
+    NATURAL: { reserved: true, alias: false, column: false, table: false },
+    NEW: { reserved: true, alias: false, column: false, table: false },
+    NEXT: { reserved: false, alias: true, column: true, table: true },
+    NO: { reserved: true, alias: false, column: false, table: false },
+    NODE: { reserved: false, alias: true, column: true, table: true },
+    NOT: { reserved: true, alias: false, column: false, table: false },
+    NOTHING: { reserved: true, alias: false, column: false, table: false },
+    NULL: { reserved: false, alias: false, column: true, table: false },
+    NULLS: { reserved: true, alias: false, column: false, table: false },
+    NULL_FILTERED: { reserved: false, alias: true, column: true, table: true },
+    NUMERIC: { reserved: false, alias: true, column: true, table: true },
+    OF: { reserved: true, alias: false, column: false, table: false },
+    OFFSET: { reserved: false, alias: true, column: true, table: true },
+    ON: { reserved: true, alias: false, column: false, table: false },
+    ONLY: { reserved: false, alias: true, column: true, table: true },
+    OPTIONAL: { reserved: false, alias: true, column: true, table: true },
+    OPTIONS: { reserved: false, alias: true, column: true, table: true },
+    OR: { reserved: true, alias: false, column: false, table: false },
+    ORDER: { reserved: true, alias: false, column: false, table: false },
+    OUT: { reserved: false, alias: true, column: true, table: true },
+    OUTER: { reserved: true, alias: false, column: false, table: false },
+    OUTPUT: { reserved: false, alias: true, column: true, table: true },
+    OVER: { reserved: true, alias: false, column: false, table: false },
+    OVERWRITE: { reserved: false, alias: true, column: true, table: true },
+    PARENT: { reserved: false, alias: true, column: true, table: true },
+    PARTITION: { reserved: true, alias: false, column: false, table: false },
+    PARTITIONS: { reserved: false, alias: true, column: true, table: true },
+    PAST: { reserved: false, alias: true, column: true, table: true },
+    PATH: { reserved: false, alias: true, column: true, table: true },
+    PATHS: { reserved: false, alias: true, column: true, table: true },
+    PATTERN: { reserved: false, alias: true, column: true, table: true },
+    PER: { reserved: false, alias: true, column: true, table: true },
+    PERCENT: { reserved: false, alias: true, column: true, table: true },
+    PIVOT: { reserved: false, alias: true, column: true, table: true },
+    POLICIES: { reserved: false, alias: true, column: true, table: true },
+    POLICY: { reserved: false, alias: true, column: true, table: true },
+    PRECEDING: { reserved: true, alias: false, column: false, table: false },
+    PRIMARY: { reserved: false, alias: true, column: true, table: true },
+    PRIVACY_UNIT_COLUMN: { reserved: false, alias: true, column: true, table: true },
+    PRIVATE: { reserved: false, alias: true, column: true, table: true },
+    PRIVILEGE: { reserved: false, alias: true, column: true, table: true },
+    PRIVILEGES: { reserved: false, alias: true, column: true, table: true },
+    PROCEDURE: { reserved: false, alias: true, column: true, table: true },
+    PROJECT: { reserved: false, alias: true, column: true, table: true },
+    PROPERTIES: { reserved: false, alias: true, column: true, table: true },
+    PROPERTY: { reserved: false, alias: true, column: true, table: true },
+    PROTO: { reserved: true, alias: false, column: false, table: false },
+    PUBLIC: { reserved: false, alias: true, column: true, table: true },
+    QUALIFY: { reserved: true, alias: false, column: false, table: false },
+    RAISE: { reserved: false, alias: true, column: true, table: true },
+    RANGE: { reserved: true, alias: false, column: false, table: false },
+    READ: { reserved: false, alias: true, column: true, table: true },
+    RECURSIVE: { reserved: true, alias: false, column: false, table: false },
+    REFERENCES: { reserved: false, alias: true, column: true, table: true },
+    REMOTE: { reserved: false, alias: true, column: true, table: true },
+    REMOVE: { reserved: false, alias: true, column: true, table: true },
+    RENAME: { reserved: false, alias: true, column: true, table: true },
+    REPEAT: { reserved: false, alias: true, column: true, table: true },
+    REPEATABLE: { reserved: false, alias: true, column: true, table: true },
+    REPLACE: { reserved: false, alias: true, column: true, table: true },
+    REPLACE_FIELDS: { reserved: false, alias: true, column: true, table: true },
+    REPLICA: { reserved: false, alias: true, column: true, table: true },
+    REPORT: { reserved: false, alias: true, column: true, table: true },
+    RESPECT: { reserved: true, alias: false, column: false, table: false },
+    RESTRICT: { reserved: false, alias: true, column: true, table: true },
+    RESTRICTION: { reserved: false, alias: true, column: true, table: true },
+    RETURN: { reserved: false, alias: true, column: true, table: true },
+    RETURNS: { reserved: false, alias: true, column: true, table: true },
+    REVOKE: { reserved: false, alias: true, column: true, table: true },
+    RIGHT: { reserved: true, alias: false, column: false, table: false },
+    ROLLBACK: { reserved: false, alias: true, column: true, table: true },
+    ROLLUP: { reserved: true, alias: false, column: false, table: false },
+    ROW: { reserved: false, alias: true, column: true, table: true },
+    ROWS: { reserved: true, alias: false, column: false, table: false },
+    RUN: { reserved: false, alias: true, column: true, table: true },
+    SAFE_CAST: { reserved: false, alias: true, column: true, table: true },
+    SCHEMA: { reserved: false, alias: true, column: true, table: true },
+    SEARCH: { reserved: false, alias: true, column: true, table: true },
+    SECURITY: { reserved: false, alias: true, column: true, table: true },
+    SELECT: { reserved: true, alias: false, column: false, table: false },
+    SEQUENCE: { reserved: false, alias: true, column: true, table: true },
+    SET: { reserved: true, alias: false, column: false, table: false },
+    SETS: { reserved: false, alias: true, column: true, table: true },
+    SHORTEST: { reserved: true, alias: false, column: false, table: false },
+    SHOW: { reserved: false, alias: true, column: true, table: true },
+    SIMPLE: { reserved: false, alias: true, column: true, table: true },
+    SKIP: { reserved: false, alias: true, column: true, table: true },
+    SLASH: { reserved: true, alias: false, column: false, table: false },
+    SNAPSHOT: { reserved: false, alias: true, column: true, table: true },
+    SOME: { reserved: true, alias: false, column: false, table: false },
+    SOURCE: { reserved: false, alias: true, column: true, table: true },
+    SQL: { reserved: false, alias: true, column: true, table: true },
+    STABLE: { reserved: false, alias: true, column: true, table: true },
+    START: { reserved: false, alias: true, column: true, table: true },
+    STATIC_DESCRIBE: { reserved: false, alias: true, column: true, table: true },
+    STORED: { reserved: false, alias: true, column: true, table: true },
+    STORING: { reserved: false, alias: true, column: true, table: true },
+    STRICT: { reserved: false, alias: true, column: true, table: true },
+    STRUCT: { reserved: true, alias: false, column: false, table: false },
+    SYSTEM: { reserved: false, alias: true, column: true, table: true },
+    SYSTEM_TIME: { reserved: false, alias: true, column: true, table: true },
+    TABLE: { reserved: false, alias: true, column: true, table: true },
+    TABLES: { reserved: false, alias: true, column: true, table: true },
+    TABLESAMPLE: { reserved: true, alias: false, column: false, table: false },
+    TARGET: { reserved: false, alias: true, column: true, table: true },
+    TEE: { reserved: false, alias: true, column: true, table: true },
+    TEMP: { reserved: false, alias: true, column: true, table: true },
+    TEMPORARY: { reserved: false, alias: true, column: true, table: true },
+    THEN: { reserved: true, alias: false, column: false, table: false },
+    TIME: { reserved: false, alias: true, column: true, table: true },
+    TIMESTAMP: { reserved: false, alias: true, column: true, table: true },
+    TO: { reserved: true, alias: false, column: false, table: false },
+    TRAIL: { reserved: false, alias: true, column: true, table: true },
+    TRANSACTION: { reserved: false, alias: true, column: true, table: true },
+    TRANSFORM: { reserved: false, alias: true, column: true, table: true },
+    TRUE: { reserved: false, alias: false, column: true, table: false },
+    TRUNCATE: { reserved: false, alias: true, column: true, table: true },
+    TYPE: { reserved: false, alias: true, column: true, table: true },
+    UNBOUNDED: { reserved: true, alias: false, column: false, table: false },
+    UNDROP: { reserved: false, alias: true, column: true, table: true },
+    UNION: { reserved: true, alias: false, column: false, table: false },
+    UNIQUE: { reserved: false, alias: true, column: true, table: true },
+    UNKNOWN: { reserved: false, alias: true, column: true, table: true },
+    UNNEST: { reserved: true, alias: false, column: false, table: false },
+    UNPIVOT: { reserved: false, alias: true, column: true, table: true },
+    UNTIL: { reserved: false, alias: true, column: true, table: true },
+    UPDATE: { reserved: false, alias: true, column: true, table: true },
+    USING: { reserved: true, alias: false, column: false, table: false },
+    VALUE: { reserved: false, alias: true, column: true, table: true },
+    VALUES: { reserved: false, alias: true, column: true, table: true },
+    VECTOR: { reserved: false, alias: true, column: true, table: true },
+    VIEW: { reserved: false, alias: true, column: true, table: true },
+    VIEWS: { reserved: false, alias: true, column: true, table: true },
+    VOLATILE: { reserved: false, alias: true, column: true, table: true },
+    WALK: { reserved: false, alias: true, column: true, table: true },
+    WEIGHT: { reserved: false, alias: true, column: true, table: true },
+    WHEN: { reserved: true, alias: false, column: false, table: false },
+    WHERE: { reserved: true, alias: false, column: false, table: false },
+    WHILE: { reserved: false, alias: true, column: true, table: true },
+    WINDOW: { reserved: true, alias: false, column: false, table: false },
+    WITH: { reserved: true, alias: false, column: false, table: false },
+    WRITE: { reserved: false, alias: true, column: true, table: true },
+    YIELD: { reserved: false, alias: true, column: true, table: true },
+    ZONE: { reserved: false, alias: true, column: true, table: true },
+};

package/dist/completion/complete.d.ts

@@ -1,19 +1,107 @@
 import type { SqlDocument } from "../document/document.js";
+import { type PartSpan } from "../ir/part-span.js";
 import type { SchemaProvider } from "../qualify/schema-provider.js";
-/** One completion candidate. The editor filters this list by the typed prefix and applies the
- *  chosen label at the caret; we only produce the labels, anchored at the caret offset. The
- *  `"template"` kind is a host candidate for a jinja call slot (a dbt model for a ref's arg). */
+import { type TemplateCall } from "../qualify/template-provider.js";
+import { type ResolvedSource } from "../scope/scope.js";
+/** One completion candidate, already pruned to the typed prefix (2026-07-12 ruling) and applied at
+ *  the caret / `CompletionResult.replaceRange`. The `"template"` kind is a host candidate for a
+ *  jinja call slot (a dbt model for a ref's arg) — its own, separately-decided contract (the
+ *  consumer still filters those by the typed prefix; see complete.jinja-candidates.test.ts). */
 export interface Completion {
     label: string;
     kind: "keyword" | "column" | "table" | "cte" | "namespace" | "function" | "template";
     /** Extra display info, e.g. a column's type when the schema knows it. */
     detail?: string;
+    /** Long-form documentation for the candidate. completeAt's own resolution never fills this in —
+     *  it is set ONLY by a `decorate` hook (CompleteOptions.decorate) answering one. Absent when no
+     *  hook ran, or the hook answered nothing for this candidate. */
+    documentation?: string;
+}
+/** The caret-anchored span of the partial identifier/keyword the candidates were pruned against —
+ *  `text.slice(start, end)` is what's already typed. `start` includes an opening delimiter when the
+ *  caret sits inside a quoted/bracketed/backtick-quoted identifier (`"my_t`, `` `my_t ``, `[my_t`),
+ *  so an editor that replaces this span never leaves a stray leading quote. `end` never extends past
+ *  the caret (`offset`) — even where a dialect's lexer greedily swallows an unterminated quoted
+ *  identifier past the caret, only the already-typed portion is ever reported or matched. */
+export interface ReplaceRange {
+    start: number;
+    end: number;
+}
+/** completeAt()'s result: an ordinary `Completion[]` (`.map`/`.filter`/iteration/`.length` all work
+ *  exactly as before — every existing consumer sees no change) carrying one optional extra
+ *  property, the same "array with named extras" shape TypeScript's own `RegExpMatchArray` uses for
+ *  `String.prototype.match`. `replaceRange` is present only when the caret sits inside a partially
+ *  typed word; an empty-prefix caret (a token boundary — nothing typed yet) returns a plain array
+ *  with no `replaceRange`, byte-identical to the pre-pruning contract. */
+export interface CompletionResult extends Array<Completion> {
+    replaceRange?: ReplaceRange;
+}
+/** The decoration hook's answer for ONE candidate — display text supplied from real structure,
+ *  merged onto the Completion completeAt is about to return. Every field optional: an absent field
+ *  leaves that part of the candidate as completeAt itself produced it (a schema-fed column's own
+ *  `detail` survives unless the hook overrides it); returning nothing at all leaves the candidate
+ *  wholly undecorated. */
+export interface CandidateDecoration {
+    detail?: string;
+    documentation?: string;
+}
+/**
+ * The STRUCTURAL identity of a candidate completeAt is about to return — anvil's decoration-hook ask
+ * (channel, 2026-07-20): "hand back STRUCTURAL identity, not just the label string". Discriminated by
+ * the candidate's own `kind`. Every extra field is present ONLY when completeAt's own resolution
+ * already produced it (never-wrong: nothing here is synthesized or re-derived) — e.g. a "column"
+ * candidate from the broken-input FROM/JOIN token-stream fallback (fromRelationColumns /
+ * qualifiedFallbackColumns) carries no `source`, because no ResolvedSource exists on that path.
+ *
+ * `"template"` covers the jinja call-slot candidates (a dbt model name for a `ref('|` arg, a source
+ * name for `source('|`) — the "table candidate that resolves through a templated call" from the
+ * ask: its `call` is the SAME TemplateCall (`JinjaSlot.call`) `templateCandidates` was already asked
+ * with, so a consumer names the model/source without re-parsing the call text.
+ */
+export type CandidateIdentity = {
+    kind: "keyword";
+} | {
+    kind: "function";
+} | {
+    kind: "namespace";
+} | {
+    kind: "table";
+} | {
+    kind: "cte";
+    /** The CTE name's own declaration span (`CteDef.nameCst`, falling back to the whole
+     *  `CteDef.cst` when the name has no real token) — pins the RIGHT declaration even when
+     *  another CTE of the same name shadows it in a nested scope. Absent only when the CTE
+     *  itself has no real token to key on (a broken/nameless mid-edit CTE). */
+    declarationSpan?: PartSpan;
+} | {
+    kind: "column";
+    /** The resolved scope source this column came from (the same ResolvedSource
+     *  scope/qualify already produced — a table/CTE/subquery/lateral/relation/graphtable/pivot).
+     *  Absent when the column came from the broken-input token-stream fallback, which has no
+     *  ResolvedSource to carry. */
+    source?: ResolvedSource;
+} | {
+    kind: "template";
+    call: TemplateCall;
+};
+/** Per-candidate decoration hook (`CompleteOptions.decorate`): completeAt calls this once for each
+ *  candidate it is about to return, with the candidate as built so far and its structural identity,
+ *  and merges the answer's `detail`/`documentation` onto it. The candidate SET is unaffected — this
+ *  only supplies display text, never adds/removes/reorders a candidate. Total-safe: a throwing hook
+ *  degrades to the undecorated candidate (never breaks completeAt), the same total-by-contract
+ *  posture every other completeAt internal failure gets (SQLLENS_DEBUG=1 rethrows — src/debug.ts). */
+export type DecorateCandidate = (candidate: Completion, identity: CandidateIdentity) => CandidateDecoration | undefined | void;
+/** completeAt's options — currently just the decoration hook. Additive: every existing 3-arg call
+ *  site keeps compiling and behaving byte-identically (no `opts`, no decoration). */
+export interface CompleteOptions {
+    decorate?: DecorateCandidate;
 }
 /**
- * Completion candidates for the caret at `offset` in `doc`. Schema-aware when a `Schema` is given
- * (table names + column types). NEVER throws: on broken / mid-edit input it still returns the
- * keyword candidates the walk can reach.
+ * Completion candidates for the caret at `offset` in `doc`, pruned to the identifier/keyword
+ * fragment already typed there (case-insensitive, dialect-fold-aware; plain prefix match — never
+ * fuzzy). Schema-aware when a `Schema` is given (table names + column types). NEVER throws: on
+ * broken / mid-edit input it still returns the keyword candidates the walk can reach.
  */
-export declare function completeAt(doc: SqlDocument, offset: number, schema?: SchemaProvider): Completion[];
+export declare function completeAt(doc: SqlDocument, offset: number, schema?: SchemaProvider, opts?: CompleteOptions): CompletionResult;
 /** @deprecated Use completeAt — same function, uniform cursor-verb naming. */
 export declare const complete: typeof completeAt;