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

package/dist/sql/objects.js

@@ -0,0 +1,222 @@
+import { PluginError, } from "@tablecraft-app/plugin-api";
+/** The action a dialect applies when a foreign key names none, which a design leaves null. */
+const DEFAULT_ACTIONS = new Set(["NO ACTION", "RESTRICT"]);
+/** The referential actions a design may name, as SQL spells them. */
+export const REFERENTIAL_ACTIONS = ["CASCADE", "SET NULL", "SET DEFAULT", "RESTRICT", "NO ACTION"];
+/** A failure the user fixes in the dialog, so the host shows it as the dialog's error. */
+export function designError(message) {
+    return new PluginError("statementFailed", message);
+}
+/**
+ * The design of a described table (decision 052). `columnDefault` turns the catalog's default into
+ * the expression a `DEFAULT` clause takes, for a dialect whose catalog stores it otherwise.
+ */
+export function tableDesignOf(relation, columnDefault = (column) => column.default) {
+    const primary = new Set(relation.primaryKey === null ? [] : [relation.primaryKey.name]);
+    return {
+        name: relation.name,
+        comment: relation.comment,
+        columns: relation.columns.map((column) => ({
+            name: column.name,
+            type: column.type,
+            nullable: column.nullable,
+            default: columnDefault(column),
+            autoIncrement: column.autoIncrement,
+            comment: column.comment,
+            original: column.name,
+        })),
+        primaryKey: relation.primaryKey?.columns ?? [],
+        primaryKeyName: relation.primaryKey?.name ?? null,
+        indexes: relation.indexes
+            .filter((index) => !index.primary && !primary.has(index.name))
+            .map((index) => ({
+            name: index.name,
+            columns: index.columns,
+            unique: index.unique,
+            original: index.name,
+        })),
+        foreignKeys: relation.foreignKeys.map((key) => ({
+            name: key.name,
+            columns: key.columns,
+            target: key.target,
+            onDelete: referentialAction(key.onDelete),
+            onUpdate: referentialAction(key.onUpdate),
+            original: key.name,
+        })),
+        checks: [],
+    };
+}
+function referentialAction(action) {
+    const spelled = action.toUpperCase();
+    return DEFAULT_ACTIONS.has(spelled) ? null : spelled;
+}
+function trimmed(text) {
+    return text.trim();
+}
+/** Throws a `designError` naming the first thing in `design` no dialect can create. */
+export function validateDesign(design) {
+    if (trimmed(design.name) === "")
+        throw designError("Name the table.");
+    if (design.columns.length === 0)
+        throw designError("Add a column: a table needs at least one.");
+    const names = new Set();
+    for (const column of design.columns) {
+        if (trimmed(column.name) === "")
+            throw designError("Name every column.");
+        if (names.has(column.name))
+            throw designError(`Two columns are named ${column.name}; rename one.`);
+        if (trimmed(column.type) === "")
+            throw designError(`Give column ${column.name} a type.`);
+        names.add(column.name);
+    }
+    const known = (columns, what) => {
+        if (columns.length === 0)
+            throw designError(`Pick the columns of ${what}.`);
+        const missing = columns.find((column) => !names.has(column));
+        if (missing !== undefined)
+            throw designError(`${what} names column ${missing}, which the table does not have.`);
+    };
+    if (design.primaryKey.length > 0)
+        known(design.primaryKey, "The primary key");
+    for (const index of design.indexes) {
+        if (trimmed(index.name) === "")
+            throw designError("Name every index.");
+        known(index.columns, `Index ${index.name}`);
+    }
+    for (const key of design.foreignKeys) {
+        if (trimmed(key.name) === "")
+            throw designError("Name every foreign key.");
+        known(key.columns, `Foreign key ${key.name}`);
+        if (trimmed(key.target.relation) === "")
+            throw designError(`Pick the table foreign key ${key.name} references.`);
+        for (const action of [key.onDelete, key.onUpdate]) {
+            if (action !== null && !REFERENTIAL_ACTIONS.some((known) => known === action)) {
+                throw designError(`Foreign key ${key.name} names action ${action}; pick one of ${REFERENTIAL_ACTIONS.join(", ")}.`);
+            }
+        }
+        if (key.target.columns.length !== key.columns.length) {
+            throw designError(`Foreign key ${key.name} needs as many referenced columns as it has columns.`);
+        }
+    }
+    for (const check of design.checks) {
+        if (trimmed(check.name) === "")
+            throw designError("Name every check.");
+        if (trimmed(check.expression) === "")
+            throw designError(`Give check ${check.name} an expression.`);
+    }
+}
+function sameList(left, right) {
+    return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+function sameIndex(left, right) {
+    return left.name === right.name && left.unique === right.unique && sameList(left.columns, right.columns);
+}
+function sameForeignKey(left, right) {
+    return (left.name === right.name &&
+        sameList(left.columns, right.columns) &&
+        sameList(left.target.path, right.target.path) &&
+        left.target.relation === right.target.relation &&
+        sameList(left.target.columns, right.target.columns) &&
+        left.onDelete === right.onDelete &&
+        left.onUpdate === right.onUpdate);
+}
+function sameCheck(left, right) {
+    return left.name === right.name && left.expression.trim() === right.expression.trim();
+}
+/** Whether a column's definition, everything but its name, differs. */
+export function columnChanged(before, after) {
+    return (before.type.trim() !== after.type.trim() ||
+        before.nullable !== after.nullable ||
+        (before.default ?? "").trim() !== (after.default ?? "").trim() ||
+        before.autoIncrement !== after.autoIncrement ||
+        (before.comment ?? "") !== (after.comment ?? ""));
+}
+/**
+ * Parts matched by `original`: one whose original is gone from `after` was dropped, one without an
+ * original was added, and a changed index, key or check is dropped and added again.
+ */
+function partsDiff(before, after, same) {
+    const kept = new Map(after.filter((part) => part.original !== null).map((part) => [part.original, part]));
+    const dropped = [];
+    const added = after.filter((part) => part.original === null);
+    for (const part of before) {
+        const next = kept.get(part.name);
+        if (next === undefined)
+            dropped.push(part);
+        else if (!same(part, next)) {
+            dropped.push(part);
+            added.push(next);
+        }
+    }
+    return { dropped, added };
+}
+export function tableDifference(before, after) {
+    const byOriginal = new Map(after.columns.filter((column) => column.original !== null).map((c) => [c.original, c]));
+    const changedColumns = [];
+    const droppedColumns = [];
+    for (const column of before.columns) {
+        const next = byOriginal.get(column.name);
+        if (next === undefined)
+            droppedColumns.push(column);
+        else if (next.name !== column.name || columnChanged(column, next)) {
+            changedColumns.push({ before: column, after: next });
+        }
+    }
+    const indexes = partsDiff(before.indexes, after.indexes, sameIndex);
+    const foreignKeys = partsDiff(before.foreignKeys, after.foreignKeys, sameForeignKey);
+    const checks = partsDiff(before.checks, after.checks, sameCheck);
+    return {
+        renamedTo: after.name === before.name ? null : after.name,
+        commentChanged: (before.comment ?? "") !== (after.comment ?? ""),
+        droppedColumns,
+        addedColumns: after.columns.filter((column) => column.original === null),
+        changedColumns,
+        primaryKeyChanged: !sameList(before.primaryKey, after.primaryKey),
+        droppedIndexes: indexes.dropped,
+        addedIndexes: indexes.added,
+        droppedForeignKeys: foreignKeys.dropped,
+        addedForeignKeys: foreignKeys.added,
+        droppedChecks: checks.dropped,
+        addedChecks: checks.added,
+    };
+}
+/** Whether a difference holds no change at all. */
+export function unchanged(difference) {
+    return (difference.renamedTo === null &&
+        !difference.commentChanged &&
+        !difference.primaryKeyChanged &&
+        [
+            difference.droppedColumns,
+            difference.addedColumns,
+            difference.changedColumns,
+            difference.droppedIndexes,
+            difference.addedIndexes,
+            difference.droppedForeignKeys,
+            difference.addedForeignKeys,
+            difference.droppedChecks,
+            difference.addedChecks,
+        ].every((parts) => parts.length === 0));
+}
+/** A script of `statements` with nothing around them. */
+export function ddlScript(statements, options) {
+    return {
+        prepare: options.prepare ?? [],
+        statements,
+        verify: options.verify ?? [],
+        finish: options.finish ?? [],
+        transactional: options.transactional,
+        notes: options.notes ?? [],
+    };
+}
+/** `NOTHING_TO_CHANGE` is the note an alter without a difference carries, so the dialog can say so. */
+export const NOTHING_TO_CHANGE = "The design matches the table; there is nothing to run.";
+/** The `REFERENCES` tail of a foreign key, actions only where they differ from the default. */
+export function referencesClause(key, qualifiedTarget, name) {
+    const actions = [
+        key.onDelete === null ? "" : ` ON DELETE ${key.onDelete}`,
+        key.onUpdate === null ? "" : ` ON UPDATE ${key.onUpdate}`,
+    ].join("");
+    return `FOREIGN KEY (${key.columns.map(name).join(", ")}) REFERENCES ${qualifiedTarget} (${key.target.columns
+        .map(name)
+        .join(", ")})${actions}`;
+}

package/dist/sql/parameters.d.ts

@@ -0,0 +1,20 @@
+import { type ParameterStyle, type SqlLanguage } from "@tablecraft-app/plugin-api";
+import { type SqlDialectOptions } from "./tokens.js";
+/**
+ * How a driver spells the placeholders it binds: `$1` once per value (node-postgres), `?` once per
+ * occurrence (mysql2, SQLite), `:1` once per occurrence (node-oracledb, which binds an array by
+ * position of occurrence), or `@p1` once per value (tedious, which binds by name).
+ */
+export type NativePlaceholder = "numbered" | "positional" | "colonNumbered" | "atNumbered";
+/** What `sqlParameters` needs to know about a dialect (decision 043). */
+export interface ParameterOptions {
+    readonly dialect: SqlDialectOptions;
+    /** The placeholder forms a statement may hold; anything else is left as SQL. */
+    readonly styles: readonly ParameterStyle[];
+    readonly native: NativePlaceholder;
+}
+/**
+ * Detection and binding of `:name`, `$1` and `?` placeholders on the lexer the splitter uses
+ * (decision 043), so nothing inside a string, quoted identifier, comment or dollar quote counts.
+ */
+export declare function sqlParameters(options: ParameterOptions): Pick<SqlLanguage, "parameters" | "bind">;

package/dist/sql/parameters.js

@@ -0,0 +1,88 @@
+import { PluginError, } from "@tablecraft-app/plugin-api";
+import { Lexer } from "./tokens.js";
+const NATIVE_FORMS = {
+    numbered: { perName: true, spell: (number) => `$${String(number)}` },
+    positional: { perName: false, spell: () => "?" },
+    colonNumbered: { perName: false, spell: (number) => `:${String(number)}` },
+    atNumbered: { perName: true, spell: (number) => `@p${String(number)}` },
+};
+const NAMED_PREFIX = ":";
+const POSITIONAL_MARK = "?";
+const NUMBERED = /^\$[1-9]\d*$/;
+const NAME_START = /^[A-Za-z_\u0080-\uffff]/;
+/** A `:` after one of these is a slice bound, a label or the second half of `::`, not a parameter. */
+const NOT_BEFORE_NAMED = /[A-Za-z0-9_$:\u0080-\uffff\]]/;
+function namedAt(text, colon, next) {
+    if (next?.kind !== "word" || next.from !== colon.to)
+        return null;
+    if (!NAME_START.test(text.charAt(next.from)))
+        return null;
+    const before = colon.from > 0 ? text.charAt(colon.from - 1) : "";
+    return NOT_BEFORE_NAMED.test(before) ? null : next;
+}
+function missingValue(name) {
+    return new PluginError("statementFailed", `No value for the parameter ${name}; run the statement again and give it one.`);
+}
+/**
+ * Detection and binding of `:name`, `$1` and `?` placeholders on the lexer the splitter uses
+ * (decision 043), so nothing inside a string, quoted identifier, comment or dollar quote counts.
+ */
+export function sqlParameters(options) {
+    const styles = new Set(options.styles);
+    const parameters = (statement) => {
+        const lexer = new Lexer(statement, options.dialect);
+        const found = [];
+        let positional = 0;
+        let token = lexer.next();
+        while (token !== null) {
+            const next = lexer.next();
+            const text = statement.slice(token.from, token.to);
+            if (token.kind === "symbol" && text === NAMED_PREFIX && styles.has("named")) {
+                const name = namedAt(statement, token, next);
+                if (name !== null) {
+                    found.push({ name: statement.slice(token.from, name.to), from: token.from, to: name.to, style: "named" });
+                    token = lexer.next();
+                    continue;
+                }
+            }
+            else if (token.kind === "symbol" && text === POSITIONAL_MARK && styles.has("positional")) {
+                positional += 1;
+                found.push({
+                    name: `${POSITIONAL_MARK}${String(positional)}`,
+                    from: token.from,
+                    to: token.to,
+                    style: "positional",
+                });
+            }
+            else if (token.kind === "word" && styles.has("numbered") && NUMBERED.test(text)) {
+                found.push({ name: text, from: token.from, to: token.to, style: "numbered" });
+            }
+            token = next;
+        }
+        return found;
+    };
+    const bind = (statement, values) => {
+        const found = parameters(statement);
+        const form = NATIVE_FORMS[options.native];
+        const params = [];
+        const numbers = new Map();
+        let sql = "";
+        let at = 0;
+        for (const parameter of found) {
+            if (!Object.hasOwn(values, parameter.name))
+                throw missingValue(parameter.name);
+            const value = values[parameter.name] ?? null;
+            let number = form.perName ? numbers.get(parameter.name) : undefined;
+            if (number === undefined) {
+                params.push(value);
+                number = params.length;
+                numbers.set(parameter.name, number);
+            }
+            const placeholder = form.spell(number);
+            sql += statement.slice(at, parameter.from) + placeholder;
+            at = parameter.to;
+        }
+        return { sql: sql + statement.slice(at), params };
+    };
+    return { parameters, bind };
+}

package/dist/sql/resolution.d.ts

@@ -0,0 +1,73 @@
+import { type CompletionCatalog, type Namespace, type Relation } from "@tablecraft-app/plugin-api";
+import type { ServerIdentity } from "./functions.js";
+import { type NamespaceTarget } from "./namespace.js";
+import type { Cte, Identifier, Query, Source } from "./scope.js";
+import type { SqlDialectOptions } from "./tokens.js";
+/** How a dialect reads unquoted names: PostgreSQL folds them to lower case, MySQL and SQLite compare them as written. */
+export type IdentifierFolding = "lower" | "upper" | "none";
+/** What name resolution needs to know about a dialect; a subset of `CompleterOptions`. */
+export interface NameOptions {
+    readonly dialect: SqlDialectOptions;
+    readonly identifierFolding: IdentifierFolding;
+    /** 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;
+}
+/** CTEs that read each other stop expanding here, so a recursive one cannot loop. */
+export declare const MAX_EXPANSION_DEPTH = 4;
+export interface ColumnInfo {
+    readonly name: string;
+    readonly type: string | null;
+}
+export interface FoundRelation {
+    readonly path: readonly string[];
+    readonly relation: Relation;
+}
+export declare function samePath(left: readonly string[] | null, right: readonly string[] | null): boolean;
+/** Whether `namespace` is one `target` can switch to (found live, plan 022). */
+export declare function targetable(target: NamespaceTarget, namespace: Namespace): boolean;
+/** Every query level from `query` outwards. */
+export declare function levels(query: Query): Query[];
+export declare function visibleCtes(query: Query): Cte[];
+/** The name a source is referred to by: its alias, else its relation's name. */
+export declare function referenceName(source: Source): Identifier | null;
+/**
+ * The dialect's name rules and a catalog reader over them, shared by completion, navigation and
+ * inspections (decision 028, plan 108) so all three agree on what a name denotes.
+ */
+export declare function nameRules(options: NameOptions): {
+    fold: (name: string) => string;
+    denotes: (identifier: Identifier, catalogName: string) => boolean;
+    sameIdentifier: (left: Identifier, right: Identifier) => boolean;
+    cteNamed: (query: Query, name: Identifier) => Cte | undefined;
+    sourceNamed: (query: Query, name: Identifier) => Source | undefined;
+    serverOf: (catalog: CompletionCatalog) => ServerIdentity | null;
+    Lookup: {
+        new (catalog: CompletionCatalog): {
+            readonly "__#private@#catalog": CompletionCatalog;
+            "__#private@#namespaces": Promise<readonly Namespace[]> | null;
+            readonly "__#private@#relations": Map<string, Promise<readonly Relation[]>>;
+            "__#private@#current": readonly string[] | null;
+            get server(): ServerIdentity | null;
+            get current(): readonly string[] | null;
+            /**
+             * Makes the script's own namespace current: the nearest statement before `offset` that moves
+             * the session's namespace, when one of its targets exists (plan 022 decision 7).
+             */
+            follow(text: string, offset: number): Promise<void>;
+            /** Moves `current` to the namespace `target` names, when the catalog has one. */
+            switchTo(target: NamespaceTarget): Promise<void>;
+            namespaces(): Promise<readonly Namespace[]>;
+            relations(path: readonly string[]): Promise<readonly Relation[]>;
+            referencing(path: readonly string[], relation: string): Promise<readonly import("@tablecraft-app/plugin-api").IncomingForeignKey[] | never[]>;
+            /** The namespace a qualifier names: its trailing path parts, as written. */
+            namespace(qualifier: readonly Identifier[]): Promise<Namespace | undefined>;
+            relation(qualifier: readonly Identifier[], name: Identifier): Promise<FoundRelation | null>;
+            columnsOf(source: Source, query: Query, depth?: number): Promise<ColumnInfo[]>;
+            cteColumns(cte: Cte, depth: number): Promise<ColumnInfo[]>;
+            /** A subquery's select list, `*` expanded through its own sources. */
+            selectColumns(query: Query, depth: number): Promise<ColumnInfo[]>;
+        };
+    };
+};
+export type NameRules = ReturnType<typeof nameRules>;
+export type Lookup = InstanceType<NameRules["Lookup"]>;

package/dist/sql/resolution.js

@@ -0,0 +1,192 @@
+import { switchableTo } from "@tablecraft-app/plugin-api";
+import { namespaceTarget } from "./namespace.js";
+import { sqlSplitter } from "./splitter.js";
+/** CTEs that read each other stop expanding here, so a recursive one cannot loop. */
+export const MAX_EXPANSION_DEPTH = 4;
+export function samePath(left, right) {
+    return (left !== null && right !== null && left.length === right.length && left.every((part, at) => part === right[at]));
+}
+/** Whether `namespace` is one `target` can switch to (found live, plan 022). */
+export function targetable(target, namespace) {
+    return switchableTo(target.kind === "database" ? "topLevel" : "schema", namespace);
+}
+/** Every query level from `query` outwards. */
+export function levels(query) {
+    const found = [];
+    for (let level = query; level !== null; level = level.parent)
+        found.push(level);
+    return found;
+}
+export function visibleCtes(query) {
+    return levels(query).flatMap((level) => level.ctes);
+}
+/** The name a source is referred to by: its alias, else its relation's name. */
+export function referenceName(source) {
+    return source.alias ?? (source.kind === "relation" ? source.name : null);
+}
+/**
+ * The dialect's name rules and a catalog reader over them, shared by completion, navigation and
+ * inspections (decision 028, plan 108) so all three agree on what a name denotes.
+ */
+export function nameRules(options) {
+    const split = sqlSplitter(options.dialect);
+    function fold(name) {
+        switch (options.identifierFolding) {
+            case "lower":
+                return name.toLowerCase();
+            case "upper":
+                return name.toUpperCase();
+            case "none":
+                return name;
+        }
+    }
+    /** Whether a name as written denotes `catalogName`: quoted exactly, unquoted folded, or case-blind where nothing folds. */
+    function denotes(identifier, catalogName) {
+        if (options.identifierFolding === "none")
+            return identifier.name.toLowerCase() === catalogName.toLowerCase();
+        return (identifier.quoted ? identifier.name : fold(identifier.name)) === catalogName;
+    }
+    function sameIdentifier(left, right) {
+        const key = (identifier) => options.identifierFolding === "none"
+            ? identifier.name.toLowerCase()
+            : identifier.quoted
+                ? identifier.name
+                : fold(identifier.name);
+        return key(left) === key(right);
+    }
+    function cteNamed(query, name) {
+        return visibleCtes(query).find((cte) => sameIdentifier(cte.name, name));
+    }
+    function sourceNamed(query, name) {
+        for (const level of levels(query)) {
+            const source = level.sources.find((candidate) => {
+                const reference = referenceName(candidate);
+                return reference !== null && sameIdentifier(reference, name);
+            });
+            if (source !== undefined)
+                return source;
+        }
+        return undefined;
+    }
+    function serverOf(catalog) {
+        const version = catalog.server.version;
+        return version === null || options.server === undefined ? null : options.server(version);
+    }
+    /** One request's view of the catalog: every read is caught, and each namespace is asked once. */
+    class Lookup {
+        #catalog;
+        #namespaces = null;
+        #relations = new Map();
+        #current;
+        constructor(catalog) {
+            this.#catalog = catalog;
+            this.#current = catalog.current;
+        }
+        get server() {
+            return serverOf(this.#catalog);
+        }
+        get current() {
+            return this.#current;
+        }
+        /**
+         * Makes the script's own namespace current: the nearest statement before `offset` that moves
+         * the session's namespace, when one of its targets exists (plan 022 decision 7).
+         */
+        async follow(text, offset) {
+            const preceding = split(text).filter((span) => span.to < offset);
+            for (let at = preceding.length - 1; at >= 0; at -= 1) {
+                const span = preceding[at];
+                const target = span === undefined ? null : namespaceTarget(span.sql, options.dialect);
+                if (target === null)
+                    continue;
+                await this.switchTo(target);
+                return;
+            }
+        }
+        /** Moves `current` to the namespace `target` names, when the catalog has one. */
+        async switchTo(target) {
+            const namespaces = (await this.namespaces()).filter((namespace) => targetable(target, namespace));
+            for (const candidate of target.candidates) {
+                const found = namespaces.find((namespace) => denotes(candidate, namespace.path.at(-1) ?? ""));
+                if (found !== undefined) {
+                    this.#current = found.path;
+                    return;
+                }
+            }
+        }
+        namespaces() {
+            this.#namespaces ??= this.#catalog.namespaces().catch(() => []);
+            return this.#namespaces;
+        }
+        relations(path) {
+            const key = JSON.stringify(path);
+            let found = this.#relations.get(key);
+            if (found === undefined) {
+                found = this.#catalog.relations(path).catch(() => []);
+                this.#relations.set(key, found);
+            }
+            return found;
+        }
+        referencing(path, relation) {
+            return this.#catalog.referencing(path, relation).catch(() => []);
+        }
+        /** The namespace a qualifier names: its trailing path parts, as written. */
+        async namespace(qualifier) {
+            if (qualifier.length === 0)
+                return undefined;
+            const namespaces = await this.namespaces();
+            const matches = (namespace) => {
+                const tail = namespace.path.slice(-qualifier.length);
+                return tail.length === qualifier.length && qualifier.every((part, at) => denotes(part, tail[at] ?? ""));
+            };
+            return namespaces.find((namespace) => matches(namespace) && !namespace.system) ?? namespaces.find(matches);
+        }
+        async relation(qualifier, name) {
+            const path = qualifier.length === 0 ? this.current : ((await this.namespace(qualifier))?.path ?? null);
+            if (path === null)
+                return null;
+            const relations = await this.relations(path);
+            const relation = relations.find((candidate) => candidate.name === name.name) ??
+                relations.find((candidate) => denotes(name, candidate.name));
+            return relation === undefined ? null : { path, relation };
+        }
+        async columnsOf(source, query, depth = 0) {
+            if (source.kind === "derived")
+                return this.selectColumns(source.query, depth + 1);
+            if (source.qualifier.length === 0) {
+                const cte = cteNamed(query, source.name);
+                if (cte !== undefined)
+                    return this.cteColumns(cte, depth + 1);
+            }
+            const found = await this.relation(source.qualifier, source.name);
+            return found?.relation.columns.map((column) => ({ name: column.name, type: column.type })) ?? [];
+        }
+        cteColumns(cte, depth) {
+            if (cte.columns !== null)
+                return Promise.resolve(cte.columns.map((column) => ({ name: column.name, type: null })));
+            return this.selectColumns(cte.query, depth);
+        }
+        /** A subquery's select list, `*` expanded through its own sources. */
+        async selectColumns(query, depth) {
+            if (depth > MAX_EXPANSION_DEPTH)
+                return [];
+            const columns = [];
+            for (const item of query.select) {
+                if (item.kind === "named") {
+                    columns.push({ name: item.name.name, type: null });
+                    continue;
+                }
+                const sources = item.qualifier === null
+                    ? query.sources
+                    : query.sources.filter((source) => {
+                        const reference = referenceName(source);
+                        return reference !== null && item.qualifier !== null && sameIdentifier(reference, item.qualifier);
+                    });
+                for (const source of sources)
+                    columns.push(...(await this.columnsOf(source, query, depth)));
+            }
+            return columns;
+        }
+    }
+    return { fold, denotes, sameIdentifier, cteNamed, sourceNamed, serverOf, Lookup };
+}

package/dist/sql/routines.d.ts

@@ -0,0 +1,27 @@
+import { type ParameterValue, type Routine, type RoutineArgument, type RoutineParameter } from "@tablecraft-app/plugin-api";
+/** What a dialect's routine call writes for one parameter (decision 090). */
+export type RoutineSlot = {
+    readonly kind: "value";
+    readonly parameter: RoutineParameter;
+    readonly position: number;
+    readonly marker: string;
+} | {
+    readonly kind: "default";
+    readonly parameter: RoutineParameter;
+    readonly position: number;
+} | {
+    readonly kind: "out";
+    readonly parameter: RoutineParameter;
+    readonly position: number;
+};
+export interface RoutineSlots {
+    readonly slots: readonly RoutineSlot[];
+    /** Keyed by marker with its colon, as `RoutineCall.params` is. */
+    readonly params: Readonly<Record<string, ParameterValue>>;
+}
+/**
+ * Pairs each parameter with its argument and gives every value a named `:marker` (`:` + the
+ * parameter's name when it is a plain identifier, else `:arg<position>`), unique in the call.
+ * Throws a `PluginError` coded `statementFailed` when the arguments do not fit the parameters.
+ */
+export declare function routineSlots(routine: Routine, args: readonly RoutineArgument[]): RoutineSlots;

package/dist/sql/routines.js

@@ -0,0 +1,42 @@
+import { PluginError, } from "@tablecraft-app/plugin-api";
+/** A name every dialect's placeholder scanner reads whole after the colon. */
+const PLAIN_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const POSITIONAL_PREFIX = "arg";
+/**
+ * Pairs each parameter with its argument and gives every value a named `:marker` (`:` + the
+ * parameter's name when it is a plain identifier, else `:arg<position>`), unique in the call.
+ * Throws a `PluginError` coded `statementFailed` when the arguments do not fit the parameters.
+ */
+export function routineSlots(routine, args) {
+    if (args.length !== routine.parameters.length) {
+        throw new PluginError("statementFailed", `${routine.name} takes ${String(routine.parameters.length)} arguments, one per parameter; ${String(args.length)} were given. Describe the routine again and fill every parameter.`);
+    }
+    const used = new Set();
+    const params = {};
+    const slots = routine.parameters.map((parameter, index) => {
+        const position = index + 1;
+        if (parameter.mode === "out")
+            return { kind: "out", parameter, position };
+        const argument = args[index] ?? { kind: "default" };
+        if (argument.kind === "default") {
+            if (!parameter.hasDefault) {
+                throw new PluginError("statementFailed", `Parameter ${parameter.name ?? String(position)} of ${routine.name} has no default. Give it a value or NULL.`);
+            }
+            return { kind: "default", parameter, position };
+        }
+        const marker = uniqueMarker(parameter, position, used);
+        used.add(marker);
+        params[marker] = argument.value;
+        return { kind: "value", parameter, position, marker };
+    });
+    return { slots, params };
+}
+function uniqueMarker(parameter, position, used) {
+    const base = parameter.name !== null && PLAIN_NAME.test(parameter.name)
+        ? `:${parameter.name}`
+        : `:${POSITIONAL_PREFIX}${String(position)}`;
+    let marker = base;
+    for (let suffix = 2; used.has(marker); suffix++)
+        marker = `${base}_${String(suffix)}`;
+    return marker;
+}