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

package/dist/sql/layout.js

@@ -0,0 +1,114 @@
+import { sqlSplitter } from "./splitter.js";
+import { Lexer } from "./tokens.js";
+import { isLineComment, parseStatement, Unsupported } from "./layoutNodes.js";
+import { AlignedPrinter } from "./layoutPrint.js";
+export { ALIAS_ALIGN_LIMIT, CASE_INLINE_LIMIT, RIGHT_MARGIN } from "./layoutPrint.js";
+const LINE_BREAK = "\n";
+const DELIMITER = ";";
+const SPACE = " ";
+/** The statements of `text` with the comments around them, so none is lost between statements. */
+function segment(text, dialect) {
+    const lexer = new Lexer(text, dialect);
+    const pieces = [];
+    let cursor = 0;
+    for (const span of sqlSplitter(dialect)(text)) {
+        lexer.position = cursor;
+        let start = span.from;
+        for (let token = lexer.next(); token !== null && token.from < span.from; token = lexer.next()) {
+            if (token.kind === "comment") {
+                start = token.from;
+                break;
+            }
+        }
+        lexer.position = span.to;
+        let end = span.to;
+        let delimited = false;
+        for (let token = lexer.next(); token !== null; token = lexer.next()) {
+            if (token.kind === "comment") {
+                end = token.to;
+                continue;
+            }
+            delimited = token.kind === "delimiter";
+            cursor = delimited ? token.to : end;
+            break;
+        }
+        if (!delimited)
+            cursor = end;
+        const after = [];
+        if (delimited) {
+            lexer.position = cursor;
+            for (let token = lexer.next(); token !== null && token.kind === "comment"; token = lexer.next()) {
+                if (text.slice(cursor, token.from).includes(LINE_BREAK))
+                    break;
+                after.push(text.slice(token.from, token.to));
+                cursor = token.to;
+            }
+        }
+        pieces.push({ text: text.slice(start, end), delimited, after });
+    }
+    const tail = [];
+    lexer.position = cursor;
+    for (let token = lexer.next(); token !== null; token = lexer.next()) {
+        if (token.kind === "comment")
+            tail.push(text.slice(token.from, token.to));
+    }
+    return { pieces, tail };
+}
+function tokenStream(text, dialect) {
+    const lexer = new Lexer(text, dialect);
+    const stream = [];
+    for (let token = lexer.next(); token !== null; token = lexer.next()) {
+        const content = text.slice(token.from, token.to);
+        stream.push(token.kind === "word" ? content.toUpperCase() : content);
+    }
+    return stream;
+}
+function sameTokens(before, after, dialect) {
+    const expected = tokenStream(before, dialect);
+    const actual = tokenStream(after, dialect);
+    return expected.length === actual.length && expected.every((token, index) => token === actual[index]);
+}
+function lastIsLineComment(text, dialect) {
+    const lexer = new Lexer(text, dialect);
+    let last = null;
+    for (let token = lexer.next(); token !== null; token = lexer.next()) {
+        last = token.kind === "comment" ? text.slice(token.from, token.to) : null;
+    }
+    return last !== null && isLineComment(last);
+}
+/**
+ * The aligned layout (decision 061), statement by statement. A statement it does not read, or one
+ * whose tokens it would change, goes to `standard` as written (decision 062).
+ */
+export function formatAligned(text, format, dialect, standard) {
+    const { pieces, tail } = segment(text, dialect);
+    if (pieces.length === 0)
+        return standard(text);
+    const printer = new AlignedPrinter(format);
+    const statement = (sql) => {
+        try {
+            const parsed = parseStatement(sql, dialect);
+            const printed = printer.print(parsed.nodes, parsed.tail);
+            if (!sameTokens(sql, printed.text, dialect))
+                throw new Unsupported("the layout would change a token");
+            return printed;
+        }
+        catch (cause) {
+            if (!(cause instanceof Unsupported))
+                throw cause;
+            const fallback = standard(sql);
+            return { text: fallback, endsInLineComment: lastIsLineComment(fallback, dialect) };
+        }
+    };
+    const blocks = pieces.map((piece) => {
+        const formatted = statement(piece.text);
+        let block = formatted.text;
+        if (piece.delimited)
+            block += formatted.endsInLineComment ? LINE_BREAK + DELIMITER : DELIMITER;
+        for (const comment of piece.after)
+            block += SPACE + comment;
+        return block;
+    });
+    const joined = blocks.join(LINE_BREAK.repeat(format.linesBetweenStatements + 1));
+    return tail.length === 0 ? joined : [joined, ...tail].join(LINE_BREAK);
+}

package/dist/sql/layoutNodes.d.ts

@@ -0,0 +1,46 @@
+import { type SqlDialectOptions } from "./tokens.js";
+/** Raised for SQL the aligned layout does not read; the statement then goes to `sql-formatter` (decision 062). */
+export declare class Unsupported extends Error {
+}
+export interface Tok {
+    readonly type: "tok";
+    readonly kind: "word" | "quoted" | "string" | "symbol";
+    readonly text: string;
+    readonly upper: string;
+    /** Whitespace or a comment stood between it and the token before it in the source. */
+    readonly spaced: boolean;
+    /** Read as a keyword: cased by `keywordCase`, and a `(` after it gets a space. */
+    keyword: boolean;
+    /** Comments on their own lines before it. */
+    readonly leading: string[];
+    /** Comments after it on its line. */
+    readonly trailing: string[];
+}
+export interface Group {
+    readonly type: "group";
+    readonly open: Tok;
+    readonly children: Node[];
+    readonly close: Tok;
+}
+/** `CASE … END`, a node so its `WHEN a AND b` never splits a condition list. */
+export interface CaseNode {
+    readonly type: "case";
+    readonly head: Tok;
+    readonly children: Node[];
+    readonly end: Tok;
+}
+export type Node = Tok | Group | CaseNode;
+export interface Statement {
+    readonly nodes: Node[];
+    /** Comments on their own lines after the last token. */
+    readonly tail: string[];
+}
+export declare function isLineComment(comment: string): boolean;
+/** The statement as tokens nested by parentheses and `CASE … END`; throws `Unsupported` when they do not balance. */
+export declare function parseStatement(text: string, dialect: SqlDialectOptions): Statement;
+export declare function firstTok(node: Node): Tok;
+export declare function lastTok(node: Node): Tok;
+/** `node` is the keyword `word`. */
+export declare function isWord(node: Node | undefined, word: string): node is Tok;
+/** `node` is a word spelled `word`, keyword or not (a clause the layout reads structurally). */
+export declare function spells(node: Node | undefined, word: string): node is Tok;

package/dist/sql/layoutNodes.js

@@ -0,0 +1,317 @@
+import { Lexer } from "./tokens.js";
+/** Raised for SQL the aligned layout does not read; the statement then goes to `sql-formatter` (decision 062). */
+export class Unsupported extends Error {
+}
+const OPERATOR_CHARS = new Set("+-*/<>=~!@#%^&|`?:");
+const OPEN = "(";
+const CLOSE = ")";
+const COMMA = ",";
+const DOT = ".";
+const CAST = "::";
+const CASE = "CASE";
+const END = "END";
+const LINE_BREAK = "\n";
+/** Reserved in PostgreSQL or MySQL, so never a bare column or table name worth keeping in its case. */
+const RESERVED = new Set([
+    "ALL",
+    "AND",
+    "ANY",
+    "AS",
+    "ASC",
+    "BETWEEN",
+    "BY",
+    "CASE",
+    "CROSS",
+    "DEFAULT",
+    "DELETE",
+    "DESC",
+    "DISTINCT",
+    "DISTINCTROW",
+    "DIV",
+    "ELSE",
+    "END",
+    "ESCAPE",
+    "EXCEPT",
+    "EXISTS",
+    "FALSE",
+    "FETCH",
+    "FOR",
+    "FROM",
+    "FULL",
+    "GROUP",
+    "HAVING",
+    "HIGH_PRIORITY",
+    "IGNORE",
+    "ILIKE",
+    "IN",
+    "INNER",
+    "INSERT",
+    "INTERSECT",
+    "INTERVAL",
+    "INTO",
+    "IS",
+    "ISNULL",
+    "JOIN",
+    "LATERAL",
+    "LEFT",
+    "LIKE",
+    "LIMIT",
+    "LOW_PRIORITY",
+    "NATURAL",
+    "NOT",
+    "NOTNULL",
+    "NULL",
+    "OFFSET",
+    "ON",
+    "OR",
+    "ORDER",
+    "OUTER",
+    "OVER",
+    "PARTITION",
+    "RECURSIVE",
+    "REGEXP",
+    "RETURNING",
+    "RIGHT",
+    "RLIKE",
+    "SELECT",
+    "SET",
+    "SIMILAR",
+    "SOME",
+    "SQL_BIG_RESULT",
+    "SQL_BUFFER_RESULT",
+    "SQL_CACHE",
+    "SQL_CALC_FOUND_ROWS",
+    "SQL_NO_CACHE",
+    "SQL_SMALL_RESULT",
+    "STRAIGHT_JOIN",
+    "TABLESAMPLE",
+    "THEN",
+    "TRUE",
+    "UNION",
+    "UPDATE",
+    "USING",
+    "VALUES",
+    "WHEN",
+    "WHERE",
+    "WINDOW",
+    "WITH",
+    "XOR",
+]);
+/** Keywords that are also functions; glued to a `(` as written they are the function, cased as written. */
+const FUNCTION_KEYWORDS = new Set(["DEFAULT", "INSERT", "INTERVAL", "LEFT", "RIGHT", "VALUES"]);
+/** Pairs where the second word is a keyword only after the first (`USE INDEX`, `NULLS LAST`). */
+const CONTEXTUAL_PAIRS = [
+    [new Set(["USE", "FORCE", "IGNORE"]), new Set(["INDEX", "KEY"])],
+    [new Set(["ON"]), new Set(["DUPLICATE", "CONFLICT", "CONSTRAINT"])],
+    [new Set(["DUPLICATE"]), new Set(["KEY"])],
+    [new Set(["DO"]), new Set(["NOTHING", "UPDATE"])],
+    [new Set(["NULLS"]), new Set(["FIRST", "LAST"])],
+    [new Set(["LOCK"]), new Set(["IN"])],
+    [new Set(["SHARE"]), new Set(["MODE"])],
+    [new Set(["FOR"]), new Set(["SHARE", "NO", "KEY"])],
+    [new Set(["NO"]), new Set(["KEY"])],
+    [new Set(["KEY"]), new Set(["SHARE", "UPDATE"])],
+    [new Set(["SKIP"]), new Set(["LOCKED"])],
+    [new Set(["FETCH"]), new Set(["FIRST", "NEXT"])],
+    [new Set(["ROW", "ROWS"]), new Set(["ONLY"])],
+    [new Set(["WITH"]), new Set(["TIES"])],
+    [new Set(["FROM", "JOIN", "UPDATE"]), new Set(["ONLY"])],
+    [new Set(["AS", "NOT"]), new Set(["MATERIALIZED"])],
+    [new Set(["UPDATE", "SHARE"]), new Set(["NOWAIT"])],
+];
+/** The first word of a pair that is a keyword itself once its second word follows. */
+const CONTEXTUAL_LEADS = new Set(["USE", "FORCE", "DUPLICATE", "DO", "NULLS", "LOCK", "SHARE", "NO", "KEY", "SKIP"]);
+/** Inside `OVER ( … )`: the frame clause. */
+const WINDOW_WORDS = new Set([
+    "ROWS",
+    "RANGE",
+    "GROUPS",
+    "UNBOUNDED",
+    "PRECEDING",
+    "FOLLOWING",
+    "CURRENT",
+    "ROW",
+    "EXCLUDE",
+    "TIES",
+    "OTHERS",
+    "NO",
+]);
+/** Operator characters next to each other are one operator, so the layout never puts a space inside `>=` or `->>`. */
+function mergeOperators(text, tokens) {
+    const merged = [];
+    for (const token of tokens) {
+        const last = merged.at(-1);
+        if (last !== undefined &&
+            token.kind === "symbol" &&
+            last.kind === "symbol" &&
+            last.to === token.from &&
+            OPERATOR_CHARS.has(text.charAt(token.from)) &&
+            OPERATOR_CHARS.has(text.charAt(last.from))) {
+            merged[merged.length - 1] = { kind: "symbol", from: last.from, to: token.to };
+        }
+        else {
+            merged.push(token);
+        }
+    }
+    return merged;
+}
+export function isLineComment(comment) {
+    return !comment.startsWith("/*");
+}
+function flatten(text, dialect) {
+    const lexer = new Lexer(text, dialect);
+    const significant = [];
+    const comments = [];
+    for (let token = lexer.next(); token !== null; token = lexer.next()) {
+        if (token.kind === "delimiter")
+            throw new Unsupported("a statement holding a delimiter");
+        (token.kind === "comment" ? comments : significant).push(token);
+    }
+    const tokens = mergeOperators(text, significant);
+    const flat = tokens.map((token, index) => {
+        const before = tokens[index - 1];
+        return {
+            token,
+            text: text.slice(token.from, token.to),
+            spaced: before === undefined || before.to < token.from,
+            leading: [],
+            trailing: [],
+        };
+    });
+    const tail = [];
+    let next = 0;
+    for (const comment of comments) {
+        while (next < flat.length && (flat[next]?.token.from ?? 0) < comment.from)
+            next += 1;
+        const content = text.slice(comment.from, comment.to);
+        const previous = flat[next - 1];
+        if (previous !== undefined && !text.slice(previous.token.to, comment.from).includes(LINE_BREAK)) {
+            previous.trailing.push(content);
+        }
+        else if (next < flat.length) {
+            flat[next]?.leading.push(content);
+        }
+        else {
+            tail.push(content);
+        }
+    }
+    moveCommentsPastCommas(flat);
+    return { flat, tail };
+}
+/** `a -- note` then `, b` reads as `a, -- note`; a comment on its own line before a comma goes after it. */
+function moveCommentsPastCommas(flat) {
+    flat.forEach((entry, index) => {
+        if (entry.text !== COMMA)
+            return;
+        const previous = flat[index - 1];
+        if (previous !== undefined && previous.trailing.some(isLineComment)) {
+            entry.trailing.unshift(...previous.trailing.splice(0));
+        }
+        const following = flat[index + 1];
+        if (following !== undefined && entry.leading.length > 0)
+            following.leading.unshift(...entry.leading.splice(0));
+    });
+}
+function keywordFlags(flat) {
+    const uppers = flat.map((entry) => (entry.token.kind === "word" ? entry.text.toUpperCase() : ""));
+    const flags = flat.map((entry, index) => {
+        const upper = uppers[index] ?? "";
+        if (!RESERVED.has(upper))
+            return false;
+        const previous = flat[index - 1];
+        if (previous?.text === CAST || (previous?.text === DOT && !entry.spaced))
+            return false;
+        const next = flat[index + 1];
+        return !(FUNCTION_KEYWORDS.has(upper) && next?.text === OPEN && !next.spaced);
+    });
+    uppers.forEach((upper, index) => {
+        const next = uppers[index + 1] ?? "";
+        for (const [first, second] of CONTEXTUAL_PAIRS) {
+            if (!first.has(upper) || !second.has(next))
+                continue;
+            flags[index + 1] = true;
+            if (CONTEXTUAL_LEADS.has(upper))
+                flags[index] = true;
+        }
+    });
+    const overDepths = [];
+    let depth = 0;
+    flat.forEach((entry, index) => {
+        if (entry.text === OPEN) {
+            depth += 1;
+            if (uppers[index - 1] === "OVER")
+                overDepths.push(depth);
+        }
+        else if (entry.text === CLOSE) {
+            if (overDepths.at(-1) === depth)
+                overDepths.pop();
+            depth -= 1;
+        }
+        else if (overDepths.at(-1) === depth && WINDOW_WORDS.has(uppers[index] ?? "")) {
+            flags[index] = true;
+        }
+    });
+    return flags;
+}
+/** The statement as tokens nested by parentheses and `CASE … END`; throws `Unsupported` when they do not balance. */
+export function parseStatement(text, dialect) {
+    const { flat, tail } = flatten(text, dialect);
+    const flags = keywordFlags(flat);
+    const stack = [{ opener: null, kind: "root", children: [] }];
+    const top = () => stack[stack.length - 1] ?? { opener: null, kind: "root", children: [] };
+    flat.forEach((entry, index) => {
+        const kind = entry.token.kind === "comment" || entry.token.kind === "delimiter" ? "symbol" : entry.token.kind;
+        const tok = {
+            type: "tok",
+            kind,
+            text: entry.text,
+            upper: entry.text.toUpperCase(),
+            spaced: entry.spaced,
+            keyword: flags[index] ?? false,
+            leading: entry.leading,
+            trailing: entry.trailing,
+        };
+        if (tok.text === OPEN) {
+            stack.push({ opener: tok, kind: "group", children: [] });
+        }
+        else if (tok.text === CLOSE) {
+            const frame = stack.pop();
+            if (frame?.kind !== "group" || frame.opener === null)
+                throw new Unsupported("an unbalanced parenthesis");
+            top().children.push({ type: "group", open: frame.opener, children: frame.children, close: tok });
+        }
+        else if (tok.keyword && tok.upper === CASE) {
+            stack.push({ opener: tok, kind: "case", children: [] });
+        }
+        else if (tok.keyword && tok.upper === END) {
+            const frame = stack.pop();
+            if (frame?.kind !== "case" || frame.opener === null)
+                throw new Unsupported("an END without its CASE");
+            top().children.push({ type: "case", head: frame.opener, children: frame.children, end: tok });
+        }
+        else {
+            top().children.push(tok);
+        }
+    });
+    if (stack.length !== 1)
+        throw new Unsupported("an unclosed parenthesis or CASE");
+    return { nodes: top().children, tail };
+}
+export function firstTok(node) {
+    if (node.type === "tok")
+        return node;
+    return node.type === "group" ? node.open : node.head;
+}
+export function lastTok(node) {
+    if (node.type === "tok")
+        return node;
+    return node.type === "group" ? node.close : node.end;
+}
+/** `node` is the keyword `word`. */
+export function isWord(node, word) {
+    return node?.type === "tok" && node.keyword && node.upper === word;
+}
+/** `node` is a word spelled `word`, keyword or not (a clause the layout reads structurally). */
+export function spells(node, word) {
+    return node?.type === "tok" && node.kind === "word" && node.upper === word;
+}

package/dist/sql/layoutPrint.d.ts

@@ -0,0 +1,60 @@
+import type { FormatOptions } from "@tablecraft-app/plugin-api";
+import { type Node, type Tok } from "./layoutNodes.js";
+import { Writer } from "./layoutWriter.js";
+/** Past this width an aliased expression neither pads to the alias column nor pushes it right. */
+export declare const ALIAS_ALIGN_LIMIT = 80;
+/** A `CASE` up to this width stays on one line. */
+export declare const CASE_INLINE_LIMIT = 60;
+/** A parenthesised condition group ending past this column opens one condition per line (DataGrip's margin). */
+export declare const RIGHT_MARGIN = 120;
+interface Clause {
+    readonly name: string;
+    readonly keywords: Tok[];
+    readonly body: Node[];
+}
+interface InlineOptions {
+    /** The source's own spacing between every two tokens (the `EXPLAIN` prefix, where `FORMAT=JSON` stays). */
+    readonly preserve?: boolean;
+    /** A `(` after a name gets a space (`INSERT INTO t (a, b)`, `WITH x (a) AS`). */
+    readonly spaceBeforeGroup?: boolean;
+}
+/** The aligned layout of one statement (decision 061). Throws `Unsupported` for what it does not read. */
+export declare class AlignedPrinter {
+    #private;
+    readonly options: FormatOptions;
+    constructor(options: FormatOptions);
+    text(tok: Tok): string;
+    print(nodes: readonly Node[], tail: readonly string[]): {
+        text: string;
+        endsInLineComment: boolean;
+    };
+    statement(writer: Writer, nodes: readonly Node[], base: number): void;
+    withQuery(writer: Writer, nodes: readonly Node[], base: number): void;
+    setQuery(writer: Writer, nodes: readonly Node[], base: number): void;
+    select(writer: Writer, nodes: readonly Node[], base: number): void;
+    clause(writer: Writer, clause: Clause): void;
+    selectClause(writer: Writer, clause: Clause): void;
+    /** One item per line under the first; aliases after `AS` line up (rule 5). */
+    selectList(writer: Writer, nodes: readonly Node[], column: number): void;
+    measure(column: number, render: (writer: Writer) => void): {
+        width: number;
+        multiline: boolean;
+    };
+    /** `SET a = 1,` with each further assignment under the first and the `=` lined up like aliases. */
+    assignments(writer: Writer, nodes: readonly Node[], column: number): void;
+    /** Tables one per line under the first; each join on its own line at the same column (rules 7-8). */
+    fromItems(writer: Writer, nodes: readonly Node[], column: number): void;
+    /**
+     * The first condition on the keyword's line, each further `AND` / `OR` on its own line ending
+     * where the keyword ends, or starting under it when the keyword is shorter (rule 9).
+     */
+    conditions(writer: Writer, nodes: readonly Node[], keywordStart: number, keywordEnd: number): void;
+    /** A parenthesised group of conditions too wide for its line opens one condition per line (rule 10). */
+    condition(writer: Writer, nodes: readonly Node[], anchor: number, leadSpace: boolean): void;
+    insert(writer: Writer, nodes: readonly Node[], base: number): void;
+    update(writer: Writer, nodes: readonly Node[], base: number): void;
+    delete(writer: Writer, nodes: readonly Node[], base: number): void;
+    inline(writer: Writer, nodes: readonly Node[], leadSpace: boolean, options?: InlineOptions): void;
+    node(writer: Writer, node: Node, space: boolean, options?: InlineOptions): void;
+}
+export {};