@tablecraft-app/plugin-api 0.0.0-stage → 1.2.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) };
+}