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

package/dist/sql/suggest.js

@@ -0,0 +1,36 @@
+/** How many "Did you mean" fixes an unresolved name offers. */
+export const MAX_SUGGESTIONS = 3;
+/** A candidate this close is always offered; longer names allow a third of their length. */
+const MIN_SUGGESTION_DISTANCE = 2;
+const SUGGESTION_LENGTH_RATIO = 3;
+/** The edit distance between two names, compared case-blind. */
+export function editDistance(left, right) {
+    const a = left.toLowerCase();
+    const b = right.toLowerCase();
+    let previous = Array.from({ length: b.length + 1 }, (_, at) => at);
+    for (let row = 1; row <= a.length; row += 1) {
+        const current = [row];
+        for (let column = 1; column <= b.length; column += 1) {
+            const substitution = (previous[column - 1] ?? 0) + (a.charAt(row - 1) === b.charAt(column - 1) ? 0 : 1);
+            current.push(Math.min((previous[column] ?? 0) + 1, (current[column - 1] ?? 0) + 1, substitution));
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+/** The closest `candidates` to `name`, nearest first, within max(2, a third of its length). */
+export function suggestions(name, candidates) {
+    const threshold = Math.max(MIN_SUGGESTION_DISTANCE, Math.floor(name.length / SUGGESTION_LENGTH_RATIO));
+    const scored = new Map();
+    for (const candidate of candidates) {
+        if (scored.has(candidate) || candidate.toLowerCase() === name.toLowerCase())
+            continue;
+        const distance = editDistance(name, candidate);
+        if (distance <= threshold)
+            scored.set(candidate, distance);
+    }
+    return [...scored]
+        .sort(([leftName, left], [rightName, right]) => left - right || leftName.localeCompare(rightName))
+        .slice(0, MAX_SUGGESTIONS)
+        .map(([candidate]) => candidate);
+}

package/dist/sql/tokens.d.ts

@@ -0,0 +1,62 @@
+/** What a dialect needs the shared splitter and classifier to know (decision 023). */
+export interface SqlDialectOptions {
+    /** PostgreSQL `$tag$ … $tag$` strings. */
+    readonly dollarQuotes?: boolean;
+    /** MySQL `'\''`: a backslash escapes the next character in strings and double-quoted text. */
+    readonly backslashEscapes?: boolean;
+    /** The MySQL client's `DELIMITER //` line, which changes what ends a statement. */
+    readonly delimiterCommand?: boolean;
+    /** PostgreSQL block comments nest: a comment inside a comment needs its own close. */
+    readonly nestedBlockComments?: boolean;
+    /** MySQL `# comment`; PostgreSQL uses `#` as an operator. */
+    readonly hashComments?: boolean;
+    /** Keywords that open a body holding semicolons, closed by `END`, inside `CREATE TRIGGER`, `FUNCTION` and the like. */
+    readonly blockKeywords?: readonly string[];
+    /** The statements that move the session's current namespace in this dialect (plan 022). */
+    readonly namespaceStatements?: readonly NamespaceStatementForm[];
+    /** SQL Server `[name]`, where `]]` is a `]` inside the name (decision 100). */
+    readonly bracketIdentifiers?: boolean;
+    /**
+     * A line that ends a batch and belongs to no statement: SQL Server's `GO` (optionally `GO 3`) or
+     * Oracle's `/`. A routine definition, and under `slash` an anonymous block, keeps its own `;` and
+     * runs to that line (decision 100).
+     */
+    readonly batchSeparator?: BatchSeparator;
+    /** Oracle `q'[…]'` strings, whose delimiter is chosen per string. */
+    readonly qQuotes?: boolean;
+    /** `N'…'` national character strings. */
+    readonly nationalStrings?: boolean;
+}
+export type BatchSeparator = "go" | "slash";
+/**
+ * `use` is MySQL's `USE db`; `searchPath` is PostgreSQL's `SET [SESSION | LOCAL] search_path`,
+ * `SET SCHEMA` and `RESET search_path` / `RESET ALL`.
+ */
+export type NamespaceStatementForm = "use" | "searchPath";
+export type TokenKind = "word" | "quoted" | "string" | "comment" | "symbol" | "delimiter";
+export interface Token {
+    readonly kind: TokenKind;
+    readonly from: number;
+    readonly to: number;
+}
+export declare const DEFAULT_DELIMITER = ";";
+/** A hand-written scanner: it knows quoting and comments, never grammar, so it cannot reject a statement. */
+export declare class Lexer {
+    #private;
+    readonly text: string;
+    readonly options: SqlDialectOptions;
+    position: number;
+    constructor(text: string, options: SqlDialectOptions);
+    /** The next token after whitespace, or null at the end. `delimiter` ends a statement wherever it starts outside quotes. */
+    next(delimiter?: string): Token | null;
+}
+/** A batch separator line: where it ends, and `GO <n>`'s count. */
+export interface SeparatorLine {
+    readonly to: number;
+    readonly repeat: number | undefined;
+}
+/** The separator line `token` starts, or null when `token` is not alone on its line as one. */
+export declare function separatorLineAt(text: string, token: Token, separator: BatchSeparator): SeparatorLine | null;
+/** Every token of `text` but comments, as one dialect reads it. */
+export declare function significantTokens(text: string, options: SqlDialectOptions): Token[];
+export declare function wordOf(text: string, token: Token): string;

package/dist/sql/tokens.js

@@ -0,0 +1,227 @@
+export const DEFAULT_DELIMITER = ";";
+const NEWLINE = "\n";
+const FIRST_NON_ASCII = 0x80;
+const DOLLAR_TAG = /\$(?:[A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/y;
+/** PostgreSQL's `E'…'` string, where backslashes escape whatever the dialect's default. */
+const ESCAPE_STRING_PREFIX = /^[eE]$/;
+const NATIONAL_STRING_PREFIX = /^[nN]$/;
+/** Oracle's `q'…'` and `Nq'…'`. */
+const Q_QUOTE_PREFIX = /^[nN]?[qQ]$/;
+const Q_QUOTE_PAIRS = new Map([
+    ["[", "]"],
+    ["{", "}"],
+    ["(", ")"],
+    ["<", ">"],
+]);
+const STRING_QUOTE = "'";
+const BRACKET_OPEN = "[";
+const BRACKET_CLOSE = "]";
+function isSpace(char) {
+    return char === " " || char === "\t" || char === "\n" || char === "\r" || char === "\f" || char === "\v";
+}
+function isWordChar(char) {
+    const code = char.charCodeAt(0);
+    if (code >= FIRST_NON_ASCII)
+        return true;
+    return ((char >= "a" && char <= "z") ||
+        (char >= "A" && char <= "Z") ||
+        (char >= "0" && char <= "9") ||
+        char === "_" ||
+        char === "$");
+}
+/** A hand-written scanner: it knows quoting and comments, never grammar, so it cannot reject a statement. */
+export class Lexer {
+    text;
+    options;
+    position = 0;
+    constructor(text, options) {
+        this.text = text;
+        this.options = options;
+    }
+    /** The next token after whitespace, or null at the end. `delimiter` ends a statement wherever it starts outside quotes. */
+    next(delimiter = DEFAULT_DELIMITER) {
+        const text = this.text;
+        let at = this.position;
+        while (at < text.length && isSpace(text.charAt(at)))
+            at += 1;
+        if (at >= text.length) {
+            this.position = at;
+            return null;
+        }
+        const char = text.charAt(at);
+        const following = text.charAt(at + 1);
+        let token;
+        if (char === "-" && following === "-")
+            token = this.#lineComment(at);
+        else if (char === "#" && this.options.hashComments === true)
+            token = this.#lineComment(at);
+        else if (char === "/" && following === "*")
+            token = this.#blockComment(at);
+        else if (text.startsWith(delimiter, at))
+            token = { kind: "delimiter", from: at, to: at + delimiter.length };
+        else if (char === "'")
+            token = this.#quoted(at, "'", "string", this.options.backslashEscapes === true);
+        else if (char === '"')
+            token = this.#quoted(at, '"', "quoted", this.options.backslashEscapes === true);
+        else if (char === "`")
+            token = this.#quoted(at, "`", "quoted", false);
+        else if (char === BRACKET_OPEN && this.options.bracketIdentifiers === true)
+            token = this.#bracketed(at);
+        else if (char === "$" && this.options.dollarQuotes === true && this.#dollarTag(at) !== null) {
+            token = this.#dollarQuoted(at, this.#dollarTag(at) ?? "");
+        }
+        else if (isWordChar(char))
+            token = this.#word(at, delimiter);
+        else
+            token = { kind: "symbol", from: at, to: at + 1 };
+        this.position = token.to;
+        return token;
+    }
+    #lineComment(from) {
+        const end = this.text.indexOf(NEWLINE, from);
+        return { kind: "comment", from, to: end < 0 ? this.text.length : end };
+    }
+    #blockComment(from) {
+        const text = this.text;
+        const nested = this.options.nestedBlockComments === true;
+        let depth = 1;
+        let at = from + 2;
+        while (at < text.length && depth > 0) {
+            if (text.startsWith("*/", at)) {
+                depth -= 1;
+                at += 2;
+            }
+            else if (nested && text.startsWith("/*", at)) {
+                depth += 1;
+                at += 2;
+            }
+            else {
+                at += 1;
+            }
+        }
+        return { kind: "comment", from, to: Math.min(at, text.length) };
+    }
+    /** A doubled quote is the quote itself; an unterminated one runs to the end of the text. */
+    #quoted(from, quote, kind, backslashEscapes) {
+        const text = this.text;
+        let at = from + 1;
+        while (at < text.length) {
+            const char = text.charAt(at);
+            if (backslashEscapes && char === "\\") {
+                at += 2;
+            }
+            else if (char === quote) {
+                if (text.charAt(at + 1) !== quote)
+                    return { kind, from, to: at + 1 };
+                at += 2;
+            }
+            else {
+                at += 1;
+            }
+        }
+        return { kind, from, to: text.length };
+    }
+    /** `]]` is a `]` inside the name; `[` needs no escape. */
+    #bracketed(from) {
+        const text = this.text;
+        let at = from + 1;
+        while (at < text.length) {
+            if (text.charAt(at) === BRACKET_CLOSE) {
+                if (text.charAt(at + 1) !== BRACKET_CLOSE)
+                    return { kind: "quoted", from, to: at + 1 };
+                at += 2;
+            }
+            else {
+                at += 1;
+            }
+        }
+        return { kind: "quoted", from, to: text.length };
+    }
+    /** `q'<open>…<close>'`, where `[`, `{`, `(` and `<` close with their pair and any other character with itself. */
+    #qQuoted(from, quote) {
+        const open = this.text.charAt(quote + 1);
+        if (open === "" || isSpace(open))
+            return null;
+        const terminator = (Q_QUOTE_PAIRS.get(open) ?? open) + STRING_QUOTE;
+        const end = this.text.indexOf(terminator, quote + 2);
+        return { kind: "string", from, to: end < 0 ? this.text.length : end + terminator.length };
+    }
+    #dollarTag(at) {
+        if (at > 0 && isWordChar(this.text.charAt(at - 1)))
+            return null;
+        DOLLAR_TAG.lastIndex = at;
+        return DOLLAR_TAG.exec(this.text)?.[0] ?? null;
+    }
+    #dollarQuoted(from, tag) {
+        const end = this.text.indexOf(tag, from + tag.length);
+        return { kind: "string", from, to: end < 0 ? this.text.length : end + tag.length };
+    }
+    #word(from, delimiter) {
+        const text = this.text;
+        const customDelimiter = delimiter !== DEFAULT_DELIMITER;
+        let at = from;
+        while (at < text.length && isWordChar(text.charAt(at))) {
+            if (customDelimiter && at > from && text.startsWith(delimiter, at))
+                break;
+            at += 1;
+        }
+        if (text.charAt(at) !== STRING_QUOTE)
+            return { kind: "word", from, to: at };
+        const prefix = text.slice(from, at);
+        if (ESCAPE_STRING_PREFIX.test(prefix)) {
+            const string = this.#quoted(at, STRING_QUOTE, "string", true);
+            return { kind: "string", from, to: string.to };
+        }
+        if (this.options.qQuotes === true && Q_QUOTE_PREFIX.test(prefix)) {
+            const string = this.#qQuoted(from, at);
+            if (string !== null)
+                return string;
+        }
+        if (this.options.nationalStrings === true && NATIONAL_STRING_PREFIX.test(prefix)) {
+            const string = this.#quoted(at, STRING_QUOTE, "string", this.options.backslashEscapes === true);
+            return { kind: "string", from, to: string.to };
+        }
+        return { kind: "word", from, to: at };
+    }
+}
+const GO = "GO";
+const SLASH = "/";
+/** What may follow `GO` on its line: a count, then a comment, as `sqlcmd` reads it. */
+const GO_REST = /^(?:[ \t]+([1-9]\d*))?[ \t]*(?:--.*)?\r?$/;
+const SLASH_REST = /^[ \t]*\r?$/;
+const LINE_INDENT = /^[ \t]*$/;
+/** The separator line `token` starts, or null when `token` is not alone on its line as one. */
+export function separatorLineAt(text, token, separator) {
+    const lineStart = text.lastIndexOf(NEWLINE, token.from - 1) + 1;
+    if (!LINE_INDENT.test(text.slice(lineStart, token.from)))
+        return null;
+    const newline = text.indexOf(NEWLINE, token.to);
+    const lineEnd = newline < 0 ? text.length : newline;
+    const rest = text.slice(token.to, lineEnd);
+    const word = text.slice(token.from, token.to);
+    if (separator === "slash") {
+        return token.kind === "symbol" && word === SLASH && SLASH_REST.test(rest)
+            ? { to: lineEnd, repeat: undefined }
+            : null;
+    }
+    if (token.kind !== "word" || word.toUpperCase() !== GO)
+        return null;
+    const match = GO_REST.exec(rest);
+    if (match === null)
+        return null;
+    const count = match[1];
+    return { to: lineEnd, repeat: count === undefined ? undefined : Number(count) };
+}
+/** Every token of `text` but comments, as one dialect reads it. */
+export function significantTokens(text, options) {
+    const lexer = new Lexer(text, options);
+    const tokens = [];
+    for (let token = lexer.next(); token !== null; token = lexer.next()) {
+        if (token.kind !== "comment")
+            tokens.push(token);
+    }
+    return tokens;
+}
+export function wordOf(text, token) {
+    return text.slice(token.from, token.to).toUpperCase();
+}

package/dist/sql/words.d.ts

@@ -0,0 +1,23 @@
+import { type Token } from "./tokens.js";
+export interface Word {
+    readonly word: string;
+    /** Parentheses around it; 0 is the statement's own level. */
+    readonly depth: number;
+}
+/** The statement's words, upper-cased, each with its parenthesis depth. */
+export declare function words(sql: string, tokens: readonly Token[]): Word[];
+/** The verb that decides what a `WITH …` statement does: the first one outside the CTEs' parentheses. */
+export declare function mainVerb(list: readonly Word[]): number;
+/** MySQL reads `DESCRIBE` and `DESC` before a statement as `EXPLAIN`, `ANALYZE` included. */
+export declare const EXPLAIN_VERBS: ReadonlySet<string>;
+export interface ExplainPrefix {
+    /** Whether the statement runs: `ANALYZE` bare, or on inside the parenthesised options. */
+    readonly analyze: boolean;
+    /** The index in the word list where the explained statement starts. */
+    readonly statementAt: number;
+}
+/**
+ * Reads `EXPLAIN [ANALYZE | ANALYSE] [VERBOSE] [( … )] [FORMAT = x] [QUERY PLAN] <statement>`
+ * (decision 031); null when the list does not start with `EXPLAIN`, `DESCRIBE` or `DESC`.
+ */
+export declare function explainPrefix(list: readonly Word[]): ExplainPrefix | null;

package/dist/sql/words.js

@@ -0,0 +1,72 @@
+import { wordOf } from "./tokens.js";
+const OPEN_PAREN = "(";
+const CLOSE_PAREN = ")";
+const WITH = "WITH";
+const MAIN_VERBS = new Set(["SELECT", "INSERT", "UPDATE", "DELETE", "MERGE"]);
+/** The statement's words, upper-cased, each with its parenthesis depth. */
+export function words(sql, tokens) {
+    const found = [];
+    let depth = 0;
+    for (const token of tokens) {
+        if (token.kind === "symbol") {
+            const char = sql.charAt(token.from);
+            if (char === OPEN_PAREN)
+                depth += 1;
+            else if (char === CLOSE_PAREN)
+                depth = Math.max(0, depth - 1);
+        }
+        else if (token.kind === "word") {
+            found.push({ word: wordOf(sql, token), depth });
+        }
+    }
+    return found;
+}
+/** The verb that decides what a `WITH …` statement does: the first one outside the CTEs' parentheses. */
+export function mainVerb(list) {
+    if (list[0]?.word !== WITH)
+        return 0;
+    const index = list.findIndex((entry, at) => at > 0 && entry.depth === 0 && MAIN_VERBS.has(entry.word));
+    return index < 0 ? 0 : index;
+}
+/** MySQL reads `DESCRIBE` and `DESC` before a statement as `EXPLAIN`, `ANALYZE` included. */
+export const EXPLAIN_VERBS = new Set(["EXPLAIN", "DESCRIBE", "DESC"]);
+const ANALYZE_WORDS = new Set(["ANALYZE", "ANALYSE"]);
+/** PostgreSQL's boolean option values that turn `ANALYZE` off inside `EXPLAIN ( … )`. */
+const FALSE_WORDS = new Set(["FALSE", "OFF", "0"]);
+/** Words between `EXPLAIN` and the statement that take no value. */
+const FLAG_WORDS = new Set(["VERBOSE", "QUERY", "PLAN", "EXTENDED", "PARTITIONS"]);
+const FORMAT = "FORMAT";
+/**
+ * Reads `EXPLAIN [ANALYZE | ANALYSE] [VERBOSE] [( … )] [FORMAT = x] [QUERY PLAN] <statement>`
+ * (decision 031); null when the list does not start with `EXPLAIN`, `DESCRIBE` or `DESC`.
+ */
+export function explainPrefix(list) {
+    const first = list[0]?.word;
+    if (first === undefined || !EXPLAIN_VERBS.has(first))
+        return null;
+    let analyze = false;
+    let at = 1;
+    for (let entry = list[at]; entry !== undefined; entry = list[at]) {
+        if (entry.depth > 0) {
+            if (ANALYZE_WORDS.has(entry.word)) {
+                const value = list[at + 1];
+                analyze = !(value !== undefined && value.depth > 0 && FALSE_WORDS.has(value.word));
+            }
+            at += 1;
+        }
+        else if (ANALYZE_WORDS.has(entry.word)) {
+            analyze = true;
+            at += 1;
+        }
+        else if (entry.word === FORMAT) {
+            at += 2;
+        }
+        else if (FLAG_WORDS.has(entry.word)) {
+            at += 1;
+        }
+        else {
+            break;
+        }
+    }
+    return { analyze, statementAt: Math.min(at, list.length) };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,177 @@
+import { z, type DatasourcePlugin, type PluginManifest, type Routine, type RoutineArgument, type Row, type ServerMessage } from "@tablecraft-app/plugin-api";
+export interface ContractFixture {
+    /** The plugin's parsed `table-craft-plugin.json`, whose connection form the suite checks. */
+    readonly manifest: PluginManifest;
+    /** Configuration that connects to a reachable, writable database seeded with `TYPE_PROBE_TABLE`. */
+    readonly config: unknown;
+    /** The same database with a wrong password; omitted by plugins that do not authenticate. */
+    readonly wrongPasswordConfig?: unknown;
+    readonly statements?: {
+        /** A statement that runs for `seconds`; required when the plugin declares `cancel`. */
+        readonly sleep?: (seconds: number) => string;
+        /**
+         * A write that succeeds on a writable session and leaves the fixture unchanged, such as an
+         * update setting a column to itself; the read-only case is skipped without one.
+         */
+        readonly write?: string;
+        /**
+         * A statement the server answers with a warning or notice, and the level and code of the
+         * first one; required when the plugin declares `serverMessages`.
+         */
+        readonly message?: {
+            readonly sql: string;
+            readonly level: ServerMessage["level"];
+            readonly code: string | null;
+        };
+        /**
+         * A statement with a syntax error and the 0-based offset the plugin's `PluginError.position`
+         * must resolve to; leave it out for a database that cannot locate one.
+         */
+        readonly syntaxError?: {
+            readonly sql: string;
+            readonly offset: number;
+        };
+    };
+    readonly typeProbe: {
+        /** The rows of `SELECT * FROM type_probe ORDER BY id`, as wire values. */
+        readonly expected: readonly Row[];
+        /**
+         * Creates `TYPE_PROBE_COPY_TABLE` with `type_probe`'s columns and declared types; the literal
+         * round trip creates and drops it. `CREATE TABLE … AS` will not do where it drops declared types.
+         */
+        readonly copyTable: string;
+    };
+    /** Scripts only this dialect splits, and the statements `language.split` must find in each. */
+    readonly scripts?: readonly SplitCase[];
+    /** Required when the plugin declares `schemaTree`. */
+    readonly catalog?: {
+        /** The namespace the fixture tables live in, which is also the connection's current one. */
+        readonly path: readonly string[];
+        /** An identifier that needs quoting, and what `qualifiedName(path, name)` must return for it. */
+        readonly quoted: {
+            readonly name: string;
+            readonly qualified: string;
+        };
+        /** `LINE_ITEMS_TABLE` as the dialect writes it in a statement, which completion must insert. */
+        readonly lineItems: string;
+        /** The name `orders`' check constraint carries, which its definition must show. */
+        readonly ordersCheck: string;
+        /** `customers`' table comment; null where the dialect has no comments. */
+        readonly customersComment: string | null;
+    };
+    /** Required when the plugin declares `currentNamespace`, which also needs `catalog`. */
+    readonly namespaceSwitch?: {
+        /** A statement that makes another namespace current, such as `USE archive`. */
+        readonly statement: string;
+        /** The path `currentNamespace` reports after it. */
+        readonly path: readonly string[];
+        /** A switch to a namespace that does not exist, where the dialect rejects one. */
+        readonly missing?: string;
+    };
+    /** Required when the plugin declares `sessions`, which also needs `statements.sleep` and `write`. */
+    readonly sessions?: {
+        /** Connects as an account that sees every session and may stop any, such as a superuser. */
+        readonly monitorConfig: unknown;
+        /** An account that sees only its own sessions, and what the listing's note must say about it. */
+        readonly limited?: {
+            readonly config: unknown;
+            readonly note: RegExp;
+        };
+    };
+    /** Required when the plugin declares `routineCall`, which also needs `catalog`. */
+    readonly routines?: {
+        /** Every routine the fixture seeds in `catalog.path`, as `describe` lists them. */
+        readonly expected: readonly Routine[];
+        /** A function given values, and the rows its call returns. */
+        readonly function: RoutineCase;
+        /** A call with one argument NULL, which must bind as SQL NULL. */
+        readonly nullArgument: RoutineCase;
+        /** A procedure whose OUT values come back as the last statement's rows. */
+        readonly procedureOut: RoutineCase;
+        /** A call that leaves a parameter to its default; omitted where the dialect has no defaults. */
+        readonly defaulted?: RoutineCase;
+    };
+    /** The statements whose text differs by dialect; each defaults to the text PostgreSQL, MySQL and SQLite accept. */
+    readonly sql?: ContractSql;
+    /**
+     * How the database stores an unquoted fixture name, such as Oracle's upper case; identity by
+     * default. `LINE_ITEMS_TABLE` is quoted in every dialect and never folded.
+     */
+    readonly foldName?: (name: string) => string;
+}
+/** Dialect-specific text the suite runs; every member is optional (decision 100). */
+export interface ContractSql {
+    /** A one-row query of `expressions`; Oracle adds `FROM DUAL`. */
+    readonly select?: (expressions: string) => string;
+    /** At least 100,000 rows; built from `select` by default. */
+    readonly largeResult?: string;
+    /** A join over `orders` and `customers` that plans with more than one step. */
+    readonly explainJoin?: string;
+    /** Replaces the scripts every other dialect splits the same way. */
+    readonly sharedScripts?: readonly SplitCase[];
+    /** Drops table `name` where it exists and does nothing where it does not. */
+    readonly dropTableIfExists?: (name: string) => string;
+    /** Creates a session-scoped table from `name`, and the name later statements reach it by. */
+    readonly temporaryTable?: (name: string, columns: string) => {
+        readonly create: string;
+        readonly name: string;
+    };
+    /** Opens a transaction explicitly in auto-commit mode. */
+    readonly begin?: string;
+}
+/** One routine call: which routine (from `routines.expected`), its arguments, and the rows it returns. */
+export interface RoutineCase {
+    readonly name: string;
+    readonly kind: Routine["kind"];
+    readonly signature: string;
+    readonly args: readonly RoutineArgument[];
+    readonly rows: readonly Row[];
+}
+export interface SplitCase {
+    readonly text: string;
+    readonly statements: readonly string[];
+}
+/** The table every fixture database carries, one column per value rule the contract pins. */
+export declare const TYPE_PROBE_TABLE = "type_probe";
+/** Where the literal round trip inserts `type_probe`'s rows; created and dropped by the suite. */
+export declare const TYPE_PROBE_COPY_TABLE = "type_probe_copy";
+export declare const TYPE_PROBE_COLUMNS: readonly ["id", "small_int", "big_int", "exact_decimal", "unicode_text", "flag", "doc", "payload", "day", "moment"];
+/** A fixture table whose name needs quoting in every dialect, for completion's quoting. */
+export declare const LINE_ITEMS_TABLE = "Line Items";
+/** The relations every fixture database carries, sorted by name as `describe` returns them. */
+export declare const FIXTURE_RELATIONS: readonly [{
+    readonly name: "customer_totals";
+    readonly kind: "view";
+}, {
+    readonly name: "customers";
+    readonly kind: "table";
+}, {
+    readonly name: "orders";
+    readonly kind: "table";
+}, {
+    readonly name: "edit_probe";
+    readonly kind: "table";
+}, {
+    readonly name: "no_key_probe";
+    readonly kind: "table";
+}, {
+    readonly name: "type_probe";
+    readonly kind: "table";
+}, {
+    readonly name: "Line Items";
+    readonly kind: "table";
+}];
+/** The data editor's table (decision 026): a serial key and a default for every other column. */
+export declare const EDIT_PROBE_TABLE = "edit_probe";
+/** The statements the suite runs for `fixture`, each default filled in. */
+export declare function contractSql(fixture: Pick<ContractFixture, "sql">): Required<ContractSql>;
+/**
+ * Where a manifest's connection form and the plugin's `connectionSchema` disagree (decision 019),
+ * one sentence per problem; empty when they agree.
+ */
+export declare function connectionFormProblems(manifest: PluginManifest, connectionSchema: z.ZodType): string[];
+/**
+ * The behaviour every plugin owes the host, gated on the capabilities it declares (decision 013).
+ * Call it from a Vitest file; it registers one `describe` block.
+ */
+export declare function runPluginContract(plugin: DatasourcePlugin, fixture: ContractFixture): void;