@tablecraft-app/plugin-api 0.0.0-stage → 1.1.0

package/dist/sql/classify.js

@@ -0,0 +1,95 @@
+import { namespaceTarget } from "./namespace.js";
+import { significantTokens } from "./tokens.js";
+import { explainPrefix, mainVerb, words } from "./words.js";
+const KINDS = new Map([
+    ...["SELECT", "SHOW", "EXPLAIN", "DESCRIBE", "DESC", "VALUES", "TABLE"].map((word) => [word, "read"]),
+    ...["INSERT", "UPDATE", "DELETE", "MERGE", "REPLACE", "UPSERT", "COPY", "LOAD"].map((word) => [word, "write"]),
+    ...["CREATE", "ALTER", "DROP", "TRUNCATE", "RENAME", "COMMENT"].map((word) => [word, "ddl"]),
+    ...["BEGIN", "COMMIT", "ROLLBACK", "SAVEPOINT", "RELEASE", "END", "ABORT"].map((word) => [word, "transaction"]),
+]);
+const START = "START";
+const TRANSACTION = "TRANSACTION";
+const WHERE = "WHERE";
+const LIMIT = "LIMIT";
+const WITH = "WITH";
+/** Prefixes the explained statement's destructive reason, so the confirmation says why it matters. */
+export const EXPLAIN_ANALYZE_REASON_PREFIX = "EXPLAIN ANALYZE runs it: ";
+function hasTopLevel(list, from, word) {
+    return list.some((entry, at) => at > from && entry.depth === 0 && entry.word === word);
+}
+function destructiveReason(list, verbAt) {
+    const verb = list[verbAt]?.word;
+    switch (verb) {
+        case "DELETE":
+            if (hasTopLevel(list, verbAt, WHERE))
+                return null;
+            return hasTopLevel(list, verbAt, LIMIT)
+                ? "DELETE without WHERE (LIMIT does not choose the rows)"
+                : "DELETE without WHERE";
+        case "UPDATE":
+            return hasTopLevel(list, verbAt, WHERE) ? null : "UPDATE without WHERE";
+        case "DROP": {
+            const object = list[verbAt + 1]?.word;
+            return object === undefined ? "DROP" : `DROP ${object}`;
+        }
+        case "TRUNCATE":
+            return "TRUNCATE";
+        default:
+            return null;
+    }
+}
+/**
+ * A token-level classifier plugins may build `SqlLanguage.classify` on (decision 023). The first
+ * keyword picks the kind; `UPDATE` or `DELETE` without a top-level `WHERE`, `DROP` and `TRUNCATE`
+ * are destructive (decision 011). `EXPLAIN` is a read unless it analyses, which runs the statement,
+ * so `EXPLAIN ANALYZE` takes the statement's kind and destructive reason (decision 031). It never
+ * parses, so it never rejects a statement.
+ */
+export function classifyTokens(sql, options = {}) {
+    const statementClass = classifyWords(words(sql, significantTokens(sql, options)));
+    return namespaceTarget(sql, options) === null ? statementClass : { ...statementClass, setsNamespace: true };
+}
+function classifyWords(list) {
+    const first = list[0]?.word;
+    if (first === undefined)
+        return { kind: "other", destructive: null };
+    if (first === START) {
+        return { kind: list[1]?.word === TRANSACTION ? "transaction" : "other", destructive: null };
+    }
+    const explain = explainPrefix(list);
+    if (explain !== null) {
+        if (!explain.analyze)
+            return { kind: "read", destructive: null };
+        const inner = classifyWords(list.slice(explain.statementAt));
+        return {
+            kind: inner.kind,
+            destructive: inner.destructive === null ? null : `${EXPLAIN_ANALYZE_REASON_PREFIX}${inner.destructive}`,
+        };
+    }
+    const verbAt = mainVerb(list);
+    const verb = list[verbAt]?.word ?? first;
+    const kind = first === WITH && verbAt === 0 ? "read" : (KINDS.get(verb) ?? "other");
+    return { kind, destructive: destructiveReason(list, verbAt) };
+}
+const ENDS = new Set(["COMMIT", "END", "ABORT"]);
+const ROLLBACK = "ROLLBACK";
+const TO = "TO";
+const PREPARE = "PREPARE";
+/**
+ * Whether a statement opens or ends a transaction, for plugins that track `Transactions.open` in
+ * auto mode: `BEGIN` and `START TRANSACTION` open one; `COMMIT`, `ROLLBACK` (not `ROLLBACK TO`),
+ * `END`, `ABORT` and `PREPARE TRANSACTION` end it. Null for anything else.
+ */
+export function transactionEffect(sql, options = {}) {
+    const list = words(sql, significantTokens(sql, options)).map((entry) => entry.word);
+    const [first, second] = list;
+    if (first === "BEGIN" || (first === START && second === TRANSACTION))
+        return "begin";
+    if (first !== undefined && ENDS.has(first))
+        return "end";
+    if (first === PREPARE && second === TRANSACTION)
+        return "end";
+    if (first === ROLLBACK)
+        return list.includes(TO) ? null : "end";
+    return null;
+}

package/dist/sql/complete.d.ts

@@ -0,0 +1,23 @@
+import type { SqlLanguage } from "@tablecraft-app/plugin-api";
+import { type FunctionSpec, type ServerIdentity } from "./functions.js";
+import { type IdentifierFolding } from "./resolution.js";
+import type { SqlDialectOptions } from "./tokens.js";
+export type { IdentifierFolding } from "./resolution.js";
+/** What the shared completer needs to know about a dialect (decision 028). */
+export interface CompleterOptions {
+    readonly dialect: SqlDialectOptions;
+    readonly identifierFolding: IdentifierFolding;
+    /** A name the dialect reads back unchanged without quotes; any other is quoted when inserted. */
+    readonly plainIdentifier: RegExp;
+    readonly quoteIdentifier: (name: string) => string;
+    /** Offered where a keyword fits; a name that spells one is quoted. Upper case. */
+    readonly keywords: readonly string[];
+    /** Built-in functions; a spec brings its signatures, summary and server range (decision 097). */
+    readonly functions: readonly (string | FunctionSpec)[];
+    /** Reads the catalog's server version into the flavour and version the specs' ranges name; null when it cannot. */
+    readonly server?: (version: string) => ServerIdentity | null;
+}
+/** Reserved words every built-in dialect shares; a plugin adds its own. */
+export declare const SQL_KEYWORDS: readonly string[];
+/** The shared completion and navigation every built-in plugin spreads into its `SqlLanguage` (decision 028). */
+export declare function sqlCompleter(options: CompleterOptions): Pick<SqlLanguage, "complete" | "resolve"> & Required<Pick<SqlLanguage, "selectSource" | "signatureAt">>;

package/dist/sql/complete.js

@@ -0,0 +1,480 @@
+import { functionItem, functionName, isAvailable } from "./functions.js";
+import { callAt } from "./signature.js";
+import { parseSimpleSelect, SELECT_READ_ONLY_REASONS } from "./select.js";
+import { scopeAt } from "./scope.js";
+import { namespaceSlotAt } from "./namespace.js";
+import { levels, nameRules, referenceName, samePath, targetable, visibleCtes, } from "./resolution.js";
+/** Reserved words every built-in dialect shares; a plugin adds its own. */
+export const SQL_KEYWORDS = [
+    "ALL",
+    "AND",
+    "AS",
+    "ASC",
+    "BETWEEN",
+    "BY",
+    "CASE",
+    "CREATE",
+    "CROSS",
+    "DELETE",
+    "DESC",
+    "DISTINCT",
+    "DROP",
+    "ELSE",
+    "END",
+    "EXISTS",
+    "FALSE",
+    "FROM",
+    "FULL",
+    "GROUP",
+    "HAVING",
+    "IN",
+    "INNER",
+    "INSERT",
+    "INTO",
+    "IS",
+    "JOIN",
+    "LEFT",
+    "LIKE",
+    "LIMIT",
+    "NOT",
+    "NULL",
+    "OFFSET",
+    "ON",
+    "OR",
+    "ORDER",
+    "OUTER",
+    "RIGHT",
+    "SELECT",
+    "SET",
+    "TABLE",
+    "THEN",
+    "TRUE",
+    "UNION",
+    "UPDATE",
+    "USING",
+    "VALUES",
+    "WHEN",
+    "WHERE",
+    "WITH",
+];
+/** Ranks items the typed prefix matches equally well (plan 009 decision 12). */
+const BOOST = {
+    join: 50,
+    column: 40,
+    cte: 35,
+    table: 30,
+    view: 30,
+    alias: 20,
+    namespace: 10,
+    function: 0,
+    keyword: -10,
+};
+const UNQUOTED_WORD = "^[A-Za-z0-9_$]*$";
+const ALIAS_WORD_BREAK = /[^A-Za-z0-9]+|(?<=[a-z0-9])(?=[A-Z])/;
+const FALLBACK_ALIAS = "t";
+const QUOTES = new Set(['"', "`", "["]);
+/** Below every other namespace: `USE mysql` is legitimate but rarely meant. */
+const SYSTEM_NAMESPACE_BOOST = -20;
+const CURRENT_DETAIL = "current";
+function relationKind(relation) {
+    return relation.kind === "table" ? "table" : "view";
+}
+/** The shared completion and navigation every built-in plugin spreads into its `SqlLanguage` (decision 028). */
+export function sqlCompleter(options) {
+    const reserved = new Set(options.keywords.map((keyword) => keyword.toUpperCase()));
+    const { denotes, sameIdentifier, cteNamed, sourceNamed, serverOf, Lookup } = nameRules(options);
+    const specs = new Map();
+    for (const spec of options.functions) {
+        if (typeof spec === "string")
+            continue;
+        const key = spec.name.toUpperCase();
+        specs.set(key, [...(specs.get(key) ?? []), spec]);
+    }
+    function specNamed(name, server) {
+        return specs.get(name.toUpperCase())?.find((spec) => isAvailable(spec, server));
+    }
+    function quoted(name) {
+        return options.plainIdentifier.test(name) && !reserved.has(name.toUpperCase())
+            ? name
+            : options.quoteIdentifier(name);
+    }
+    function item(kind, label, apply, detail) {
+        return { label, kind, detail, apply, boost: BOOST[kind], info: null, caret: null };
+    }
+    function relationItems(relations, namespace) {
+        return relations.map((relation) => item(relationKind(relation), relation.name, quoted(relation.name), namespace));
+    }
+    function columnItems(columns) {
+        const seen = new Set();
+        return columns
+            .filter((column) => !seen.has(column.name) && seen.add(column.name))
+            .map((column) => item("column", column.name, quoted(column.name), column.type));
+    }
+    function keywordItems(except = new Set()) {
+        return options.keywords
+            .filter((keyword) => !except.has(keyword.toUpperCase()))
+            .map((keyword) => item("keyword", keyword, keyword, null));
+    }
+    function availableFunctions(server) {
+        const offered = new Set();
+        return options.functions.filter((spec) => {
+            const name = functionName(spec).toUpperCase();
+            if (offered.has(name) || (typeof spec !== "string" && !isAvailable(spec, server)))
+                return false;
+            offered.add(name);
+            return true;
+        });
+    }
+    async function qualifiedItems(scope, lookup) {
+        const { qualifier, query, clause } = scope;
+        const last = qualifier.at(-1);
+        if (last === undefined)
+            return [];
+        const relational = clause === "relation" || clause === "join";
+        if (qualifier.length === 1 && !relational) {
+            const source = sourceNamed(query, last);
+            if (source !== undefined)
+                return columnItems(await lookup.columnsOf(source, query));
+            const cte = cteNamed(query, last);
+            if (cte !== undefined)
+                return columnItems(await lookup.cteColumns(cte, 1));
+        }
+        const namespace = await lookup.namespace(qualifier);
+        if (namespace !== undefined)
+            return relationItems(await lookup.relations(namespace.path), null);
+        if (relational)
+            return [];
+        const found = await lookup.relation(qualifier.slice(0, -1), last);
+        return found === null ? [] : columnItems(found.relation.columns);
+    }
+    async function relationContextItems(scope, lookup) {
+        const current = lookup.current;
+        const namespaces = await lookup.namespaces();
+        const currentName = namespaces.find((namespace) => samePath(namespace.path, current))?.name ?? null;
+        const relations = current === null ? [] : await lookup.relations(current);
+        const items = [
+            ...visibleCtes(scope.query).map((cte) => item("cte", cte.name.name, quoted(cte.name.name), null)),
+            ...relationItems(relations, currentName),
+            ...namespaces
+                .filter((namespace) => !namespace.system && !samePath(namespace.path, current))
+                .map((namespace) => item("namespace", namespace.name, quoted(namespace.name), namespace.kind)),
+        ];
+        if (scope.clause !== "join")
+            return items;
+        return [...(await joinItems(scope, lookup)), ...items];
+    }
+    function aliasFor(name, taken) {
+        const initials = name
+            .split(ALIAS_WORD_BREAK)
+            .filter((word) => word !== "")
+            .map((word) => word.charAt(0).toLowerCase())
+            .join("");
+        const base = initials === "" || !options.plainIdentifier.test(initials) ? FALLBACK_ALIAS : initials;
+        let alias = base;
+        for (let suffix = 1; taken.has(alias) || reserved.has(alias.toUpperCase()); suffix += 1)
+            alias = `${base}${String(suffix)}`;
+        taken.add(alias);
+        return alias;
+    }
+    function relationReference(path, name, current) {
+        const namespace = path.at(-1);
+        return samePath(path, current) || namespace === undefined ? quoted(name) : `${quoted(namespace)}.${quoted(name)}`;
+    }
+    /** `customers c ON c.id = o.customer_id` for each foreign key to or from a relation already in scope (plan 009 decision 7). */
+    async function joinItems(scope, lookup) {
+        const before = scope.query.sources.filter((source) => source.kind === "relation" && source.to <= scope.prefixFrom);
+        const taken = new Set(scope.query.sources
+            .map((source) => referenceName(source))
+            .filter((name) => name !== null)
+            .map((name) => name.name.toLowerCase()));
+        const items = [];
+        const seen = new Set();
+        const add = (label, detail) => {
+            if (seen.has(label))
+                return;
+            seen.add(label);
+            items.push(item("join", label, label, detail));
+        };
+        for (const source of before) {
+            if (source.qualifier.length === 0 && cteNamed(scope.query, source.name) !== undefined)
+                continue;
+            const found = await lookup.relation(source.qualifier, source.name);
+            if (found === null)
+                continue;
+            const near = source.alias === null
+                ? relationReference(found.path, found.relation.name, lookup.current)
+                : quoted(source.alias.name);
+            for (const key of found.relation.foreignKeys) {
+                const alias = aliasFor(key.target.relation, new Set(taken));
+                const on = key.columns
+                    .map((column, at) => `${alias}.${quoted(key.target.columns[at] ?? column)} = ${near}.${quoted(column)}`)
+                    .join(" AND ");
+                add(`${relationReference(key.target.path, key.target.relation, lookup.current)} ${alias} ON ${on}`, key.name);
+            }
+            for (const incoming of await lookup.referencing(found.path, found.relation.name)) {
+                const key = incoming.foreignKey;
+                const alias = aliasFor(incoming.relation, new Set(taken));
+                const on = key.columns
+                    .map((column, at) => `${alias}.${quoted(column)} = ${near}.${quoted(key.target.columns[at] ?? column)}`)
+                    .join(" AND ");
+                add(`${relationReference(incoming.path, incoming.relation, lookup.current)} ${alias} ON ${on}`, key.name);
+            }
+        }
+        return items;
+    }
+    async function inScopeColumnItems(scope, lookup) {
+        const { query } = scope;
+        const perSource = await Promise.all(query.sources.map((source) => lookup.columnsOf(source, query)));
+        const owners = new Map();
+        for (const columns of perSource) {
+            for (const name of new Set(columns.map((column) => column.name)))
+                owners.set(name, (owners.get(name) ?? 0) + 1);
+        }
+        const items = [];
+        const seen = new Set();
+        query.sources.forEach((source, at) => {
+            const reference = referenceName(source);
+            for (const column of perSource[at] ?? []) {
+                const shared = (owners.get(column.name) ?? 0) > 1 && reference !== null;
+                const prefix = shared ? `${quoted(reference.name)}.` : "";
+                const label = shared ? `${reference.name}.${column.name}` : column.name;
+                if (seen.has(label))
+                    continue;
+                seen.add(label);
+                items.push(item("column", label, `${prefix}${quoted(column.name)}`, column.type));
+            }
+        });
+        const aliases = query.sources
+            .filter((source) => source.alias !== null)
+            .map((source) => item("alias", source.alias?.name ?? "", quoted(source.alias?.name ?? ""), source.kind === "relation" ? source.name.name : null));
+        const functions = availableFunctions(lookup.server);
+        const functionNames = new Set(functions.map((spec) => functionName(spec).toUpperCase()));
+        return [
+            ...items,
+            ...aliases,
+            ...functions.map((spec) => functionItem(spec, BOOST.function)),
+            ...keywordItems(functionNames),
+        ];
+    }
+    async function itemsFor(scope, lookup) {
+        if (scope.clause === "none")
+            return [];
+        if (scope.qualifier.length > 0)
+            return qualifiedItems(scope, lookup);
+        switch (scope.clause) {
+            case "relation":
+            case "join":
+                return relationContextItems(scope, lookup);
+            case "columns":
+                return inScopeColumnItems(scope, lookup);
+            case "insertColumns": {
+                const target = scope.query.insert?.source;
+                const found = target === undefined ? null : await lookup.relation(target.qualifier, target.name);
+                return found === null ? [] : columnItems(found.relation.columns);
+            }
+            case "keywords":
+                return keywordItems();
+        }
+    }
+    /** Inside a quoted name every name is offered quoted, since the editor filters on what was typed. */
+    function quotedLabels(items) {
+        return items.map((entry) => entry.kind === "keyword" || entry.kind === "function" || entry.kind === "join"
+            ? entry
+            : { ...entry, label: options.quoteIdentifier(entry.label) });
+    }
+    /** A clause body with `scope.relation` in scope reads as the WHERE of a `SELECT` from it. */
+    function wrap(request) {
+        if (request.scope === undefined)
+            return { text: request.text, offset: request.offset, shift: 0 };
+        const { path, relation } = request.scope;
+        const namespace = path.at(-1);
+        const table = namespace === undefined
+            ? options.quoteIdentifier(relation)
+            : `${options.quoteIdentifier(namespace)}.${options.quoteIdentifier(relation)}`;
+        const head = `SELECT * FROM ${table} WHERE `;
+        return { text: head + request.text, offset: request.offset + head.length, shift: head.length };
+    }
+    /** Decision 2 and 3 of plan 029: what a `USE` or search path element can name, as the caret's quote needs it. */
+    async function namespaceItems(slot, lookup) {
+        const target = { kind: slot.kind, candidates: [] };
+        const namespaces = (await lookup.namespaces()).filter((namespace) => targetable(target, namespace) &&
+            !slot.listed.some((listed) => denotes(listed, namespace.path.at(-1) ?? namespace.name)));
+        const ordered = [
+            ...namespaces.filter((namespace) => !namespace.system),
+            ...namespaces.filter((namespace) => namespace.system),
+        ];
+        const quote = slot.quote;
+        return ordered.map((namespace) => {
+            const name = namespace.path.at(-1) ?? namespace.name;
+            const apply = quote === null
+                ? quoted(name)
+                : name.replaceAll(quote.char, quote.char + quote.char) + (quote.closed ? "" : quote.char);
+            const detail = samePath(namespace.path, lookup.current) ? CURRENT_DETAIL : null;
+            const entry = item("namespace", name, apply, detail);
+            return namespace.system ? { ...entry, boost: SYSTEM_NAMESPACE_BOOST } : entry;
+        });
+    }
+    async function complete(request, catalog) {
+        if (request.scope === undefined) {
+            const slot = namespaceSlotAt(request.text, request.offset, options.dialect);
+            if (slot !== null) {
+                const lookup = new Lookup(catalog);
+                await lookup.follow(request.text, request.offset);
+                const items = await namespaceItems(slot, lookup);
+                return { from: slot.from, to: slot.to, items, validFor: slot.quote === null ? UNQUOTED_WORD : null };
+            }
+        }
+        const { text, offset, shift } = wrap(request);
+        const scope = scopeAt(text, offset, options.dialect);
+        const lookup = new Lookup(catalog);
+        if (request.scope === undefined)
+            await lookup.follow(text, offset);
+        const items = await itemsFor(scope, lookup);
+        const typedQuote = QUOTES.has(text.charAt(scope.prefixFrom)) && scope.prefixFrom < offset;
+        return {
+            from: scope.prefixFrom - shift,
+            to: offset - shift,
+            items: typedQuote ? quotedLabels(items) : items,
+            validFor: typedQuote ? null : UNQUOTED_WORD,
+        };
+    }
+    function sourceDeclaring(query, word) {
+        for (const level of levels(query)) {
+            for (const source of level.sources) {
+                if (source.kind === "relation" && (source.name.from === word.from || source.alias?.from === word.from))
+                    return source;
+            }
+        }
+        return undefined;
+    }
+    async function relationDeclaration(lookup, qualifier, name) {
+        const found = await lookup.relation(qualifier, name);
+        return found === null ? null : { kind: "relation", path: found.path, relation: found.relation.name };
+    }
+    async function columnDeclaration(lookup, source, query, column) {
+        if (source.kind !== "relation")
+            return null;
+        if (source.qualifier.length === 0 && cteNamed(query, source.name) !== undefined)
+            return null;
+        const found = await lookup.relation(source.qualifier, source.name);
+        const meta = found?.relation.columns.find((candidate) => denotes(column, candidate.name));
+        return found === null || meta === undefined
+            ? null
+            : { kind: "column", path: found.path, relation: found.relation.name, column: meta.name };
+    }
+    async function resolve(request, catalog) {
+        const scope = scopeAt(request.text, request.offset, options.dialect, "resolve");
+        const { word, qualifier, query } = scope;
+        if (word === null || scope.clause === "none")
+            return null;
+        const lookup = new Lookup(catalog);
+        await lookup.follow(request.text, request.offset);
+        const cte = visibleCtes(query).find((candidate) => candidate.name.from === word.from);
+        if (cte !== undefined)
+            return { kind: "cte", from: cte.name.from, to: cte.name.to };
+        const declaring = sourceDeclaring(query, word);
+        if (declaring !== undefined) {
+            if (declaring.alias?.from === word.from)
+                return { kind: "alias", from: declaring.from, to: declaring.to };
+            if (declaring.qualifier.length === 0) {
+                const named = cteNamed(query, word);
+                if (named !== undefined)
+                    return { kind: "cte", from: named.name.from, to: named.name.to };
+            }
+            return relationDeclaration(lookup, declaring.qualifier, declaring.name);
+        }
+        if (qualifier.length === 0) {
+            const source = sourceNamed(query, word);
+            if (source !== undefined && (scope.dotAfter || source.alias !== null)) {
+                if (source.alias !== null)
+                    return { kind: "alias", from: source.from, to: source.to };
+                if (source.kind === "relation")
+                    return relationDeclaration(lookup, source.qualifier, source.name);
+            }
+            const named = cteNamed(query, word);
+            if (named !== undefined)
+                return { kind: "cte", from: named.name.from, to: named.name.to };
+            if (!scope.dotAfter && scope.clause === "columns") {
+                for (const candidate of query.sources) {
+                    const declaration = await columnDeclaration(lookup, candidate, query, word);
+                    if (declaration !== null)
+                        return declaration;
+                }
+            }
+            return relationDeclaration(lookup, [], word);
+        }
+        if (qualifier.length === 1 && qualifier[0] !== undefined) {
+            const source = sourceNamed(query, qualifier[0]);
+            if (source !== undefined)
+                return columnDeclaration(lookup, source, query, word);
+        }
+        const asRelation = await relationDeclaration(lookup, qualifier, word);
+        if (asRelation !== null)
+            return asRelation;
+        const owner = qualifier.at(-1);
+        if (owner === undefined)
+            return null;
+        const found = await lookup.relation(qualifier.slice(0, -1), owner);
+        const meta = found?.relation.columns.find((candidate) => denotes(word, candidate.name));
+        return found === null || meta === undefined
+            ? null
+            : { kind: "column", path: found.path, relation: found.relation.name, column: meta.name };
+    }
+    /** Whether a qualifier written before a column or `*` names the one table the SELECT reads. */
+    function namesTable(qualifier, select) {
+        const last = qualifier.at(-1);
+        if (last === undefined)
+            return true;
+        if (select.alias !== null)
+            return qualifier.length === 1 && sameIdentifier(last, select.alias);
+        const written = [...select.qualifier, select.name];
+        const tail = written.slice(-qualifier.length);
+        return (tail.length === qualifier.length &&
+            qualifier.every((part, at) => {
+                const other = tail[at];
+                return other !== undefined && sameIdentifier(part, other);
+            }));
+    }
+    async function selectSource(sql, catalog) {
+        const select = parseSimpleSelect(sql, options.dialect);
+        if ("readOnly" in select)
+            return { kind: "readOnly", reason: select.readOnly };
+        const found = await new Lookup(catalog).relation(select.qualifier, select.name);
+        if (found === null)
+            return { kind: "readOnly", reason: `the catalog does not know ${select.name.name}` };
+        const tableColumns = found.relation.columns.map((column) => column.name);
+        const columns = [];
+        for (const item of select.items) {
+            if (item.kind === "expression") {
+                columns.push(null);
+                continue;
+            }
+            const qualifier = item.kind === "star" ? (item.qualifier === null ? [] : [item.qualifier]) : item.qualifier;
+            if (!namesTable(qualifier, select))
+                return { kind: "readOnly", reason: SELECT_READ_ONLY_REASONS.notSelect };
+            if (item.kind === "star") {
+                columns.push(...tableColumns);
+                continue;
+            }
+            columns.push(tableColumns.find((name) => denotes(item.name, name)) ?? null);
+        }
+        return { kind: "table", path: found.path, relation: found.relation.name, columns };
+    }
+    function signatureAt(request, catalog) {
+        const { text, offset, shift } = wrap(request);
+        const server = serverOf(catalog);
+        const call = callAt(text, offset, options.dialect, reserved, (name) => specNamed(name, server) !== undefined);
+        const spec = call === null ? undefined : specNamed(call.name, server);
+        if (call === null || spec === undefined)
+            return Promise.resolve(null);
+        return Promise.resolve({
+            name: spec.name.toLowerCase(),
+            summary: spec.summary,
+            signatures: spec.signatures,
+            argument: call.argument,
+            from: call.from - shift,
+            to: call.to - shift,
+        });
+    }
+    return { complete, resolve, selectSource, signatureAt };
+}

package/dist/sql/explain.d.ts

@@ -0,0 +1,42 @@
+import type { Row, SqlLanguage } from "@tablecraft-app/plugin-api";
+import { type SqlDialectOptions } from "./tokens.js";
+/** What `sqlExplainable` needs to know about a dialect's EXPLAIN (decision 031). */
+export interface ExplainableOptions {
+    readonly dialect: SqlDialectOptions;
+    /** The database's name, as a refusal names it: `PostgreSQL`. */
+    readonly name: string;
+    /**
+     * The verbs EXPLAIN accepts, as the verb that decides what a statement does (`SELECT`, or the one
+     * after `WITH …`); `CREATE_TABLE_AS` stands for `CREATE TABLE … AS`.
+     */
+    readonly verbs: readonly string[];
+    /** The verbs Explain Analyse accepts, a subset of `verbs`; empty where the dialect cannot analyse. */
+    readonly analyzeVerbs: readonly string[];
+}
+export declare const NOTHING_TO_EXPLAIN = "There is no statement to explain; put the caret in one.";
+export declare const EXPLAIN_ONE_STATEMENT = "Explain one statement at a time.";
+export declare const ALREADY_EXPLAIN = "This statement is already an EXPLAIN; run it with Run to see its rows.";
+/** How `ExplainableOptions` names `CREATE TABLE … AS`, which `CREATE TABLE` alone is not. */
+export declare const CREATE_TABLE_AS = "CREATE TABLE \u2026 AS";
+/**
+ * The refusals every dialect shares: nothing to explain, more than one statement, and a statement
+ * that already is an EXPLAIN. Null when none applies.
+ */
+export declare function commonExplainRefusal(sql: string, dialect: SqlDialectOptions): string | null;
+/**
+ * The verb that decides what `sql` does, upper case: `SELECT`, the verb after `WITH …`, or
+ * `CREATE_TABLE_AS`; empty for no statement. A plugin picks its EXPLAIN format by it.
+ */
+export declare function explainedVerb(sql: string, dialect: SqlDialectOptions): string;
+/**
+ * `SqlLanguage.explainable` from a dialect's verb lists: the shared refusals, then the statement's
+ * main verb against what the dialect explains and analyses. A statement writes when it is not a read.
+ */
+export declare function sqlExplainable(options: ExplainableOptions): Required<Pick<SqlLanguage, "explainable">>;
+/** The first cell of every row as text, one row per line: what an EXPLAIN printed. */
+export declare function planText(rows: readonly Row[]): string;
+/**
+ * A plan property's value as one line of text: strings as they are, lists joined with commas,
+ * anything nested as JSON. Null for nothing worth showing: null, or an empty list.
+ */
+export declare function planPropertyValue(value: unknown): string | null;