sqllens 1.6.0 → 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, type CompletionResult, type ReplaceRange, } 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 { 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

@@ -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, 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/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,5 +1,8 @@
 import type { SqlDocument } from "../document/document.js";
+import { type PartSpan } from "../ir/part-span.js";
 import type { SchemaProvider } from "../qualify/schema-provider.js";
+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
@@ -9,6 +12,10 @@ export interface Completion {
     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
@@ -29,12 +36,72 @@ export interface ReplaceRange {
 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`, 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): CompletionResult;
+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;