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

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;

package/dist/sql/explain.js

@@ -0,0 +1,108 @@
+import { classifyTokens } from "./classify.js";
+import { sqlSplitter } from "./splitter.js";
+import { significantTokens } from "./tokens.js";
+import { EXPLAIN_VERBS, mainVerb, words } from "./words.js";
+export const NOTHING_TO_EXPLAIN = "There is no statement to explain; put the caret in one.";
+export const EXPLAIN_ONE_STATEMENT = "Explain one statement at a time.";
+export const ALREADY_EXPLAIN = "This statement is already an EXPLAIN; run it with Run to see its rows.";
+const CREATE = "CREATE";
+const TABLE = "TABLE";
+const AS = "AS";
+/** How `ExplainableOptions` names `CREATE TABLE … AS`, which `CREATE TABLE` alone is not. */
+export const CREATE_TABLE_AS = "CREATE TABLE … AS";
+function anyOf(items) {
+    if (items.length <= 1)
+        return items.join("");
+    return `${items.slice(0, -1).join(", ")} or ${items.at(-1) ?? ""}`;
+}
+function isCreateTableAs(list) {
+    if (list[0]?.word !== CREATE)
+        return false;
+    const table = list.findIndex((entry) => entry.depth === 0 && entry.word === TABLE);
+    return table > 0 && list.some((entry, at) => at > table && entry.depth === 0 && entry.word === 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 function commonExplainRefusal(sql, dialect) {
+    const spans = sqlSplitter(dialect)(sql);
+    if (spans.length === 0)
+        return NOTHING_TO_EXPLAIN;
+    if (spans.length > 1)
+        return EXPLAIN_ONE_STATEMENT;
+    const first = words(sql, significantTokens(sql, dialect))[0]?.word;
+    return first !== undefined && EXPLAIN_VERBS.has(first) ? ALREADY_EXPLAIN : 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 function explainedVerb(sql, dialect) {
+    const list = words(sql, significantTokens(sql, dialect));
+    return isCreateTableAs(list) ? CREATE_TABLE_AS : (list[mainVerb(list)]?.word ?? "");
+}
+/**
+ * `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 function sqlExplainable(options) {
+    const verbs = new Set(options.verbs);
+    const analyzeVerbs = new Set(options.analyzeVerbs);
+    const explainable = (sql, { analyze }) => {
+        const common = commonExplainRefusal(sql, options.dialect);
+        if (common !== null)
+            return { ok: false, reason: common };
+        const statement = sqlSplitter(options.dialect)(sql)[0]?.sql ?? sql;
+        const verb = explainedVerb(statement, options.dialect);
+        if (!verbs.has(verb)) {
+            return {
+                ok: false,
+                reason: `${options.name} cannot explain a ${verb} statement. Explain ${anyOf(options.verbs)} instead.`,
+            };
+        }
+        if (analyze && !analyzeVerbs.has(verb)) {
+            return {
+                ok: false,
+                reason: analyzeVerbs.size === 0
+                    ? `${options.name} cannot run Explain Analyse; use Explain Plan.`
+                    : `${options.name} analyses only ${anyOf(options.analyzeVerbs)} statements; use Explain Plan for this ${verb}.`,
+            };
+        }
+        return { ok: true, writes: classifyTokens(statement, options.dialect).kind !== "read" };
+    };
+    return { explainable };
+}
+const LINE_BREAK = "\n";
+/** The first cell of every row as text, one row per line: what an EXPLAIN printed. */
+export function planText(rows) {
+    return rows
+        .map((row) => {
+        const cell = row[0];
+        if (cell === null || cell === undefined)
+            return "";
+        if (typeof cell === "object")
+            return cell.kind === "json" ? cell.text : JSON.stringify(cell);
+        return String(cell);
+    })
+        .join(LINE_BREAK);
+}
+/**
+ * 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 function planPropertyValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return null;
+        const flat = value.every((item) => item === null || typeof item !== "object");
+        return flat ? value.map((item) => String(item)).join(", ") : JSON.stringify(value);
+    }
+    return JSON.stringify(value);
+}

package/dist/sql/format.d.ts

@@ -0,0 +1,26 @@
+import type { ParameterStyle, SqlLanguage } from "@tablecraft-app/plugin-api";
+import { type DialectOptions } from "sql-formatter";
+import { type SqlDialectOptions } from "./tokens.js";
+/** The `sql-formatter` dialects plugins may name (decisions 042 and 100). */
+export declare const FORMAT_DIALECTS: {
+    readonly postgresql: DialectOptions;
+    readonly mysql: DialectOptions;
+    readonly sqlite: DialectOptions;
+    readonly plsql: DialectOptions;
+    readonly transactsql: DialectOptions;
+};
+export type FormatDialect = keyof typeof FORMAT_DIALECTS;
+export interface FormatterOptions {
+    readonly dialect: FormatDialect;
+    /** The same dialect options the splitter gets; `delimiterCommand` makes a `DELIMITER` line refuse. */
+    readonly lexer: SqlDialectOptions;
+    /** The placeholders `SqlLanguage.parameters` reads, so the formatter keeps `:id` and `$1` whole. */
+    readonly parameters: readonly ParameterStyle[];
+}
+/**
+ * `SqlLanguage.format`: the aligned layout (decision 061) or `sql-formatter`'s (decision 042), which
+ * also takes every statement the aligned one does not read (decision 062). Throws an `Error` with a
+ * one-line reason rather than returning half-formatted text; comments and literals pass through as
+ * written.
+ */
+export declare function sqlFormatter(options: FormatterOptions): Pick<SqlLanguage, "format">;