@jacobknightley/fabric-format 0.0.1

package/dist/formatters/sparksql/output-builder.js

@@ -0,0 +1,191 @@
+/**
+ * Output Builder - Token Output and Column Tracking
+ *
+ * This module handles the construction of the formatted output string.
+ * It tracks column position for line-width decisions and provides
+ * utilities for spacing and newline insertion.
+ */
+import { SqlBaseLexer } from './token-utils.js';
+/**
+ * Builds the formatted output string with column tracking.
+ */
+export class OutputBuilder {
+    output = [];
+    currentColumn = 0;
+    /**
+     * Push text to output and update column tracking.
+     */
+    push(text) {
+        this.output.push(text);
+        this.updateColumn(text);
+    }
+    /**
+     * Get the current column position.
+     */
+    getColumn() {
+        return this.currentColumn;
+    }
+    /**
+     * Get the last character that was output.
+     */
+    getLastChar() {
+        if (this.output.length === 0)
+            return '';
+        const lastStr = this.output[this.output.length - 1];
+        return lastStr.charAt(lastStr.length - 1);
+    }
+    /**
+     * Check if output is empty.
+     */
+    isEmpty() {
+        return this.output.length === 0;
+    }
+    /**
+     * Check if the last output ends with a newline.
+     */
+    endsWithNewline() {
+        return this.getLastChar() === '\n';
+    }
+    /**
+     * Get the final formatted string.
+     */
+    toString() {
+        return this.output.join('').trim();
+    }
+    /**
+     * Update column tracking based on text content.
+     */
+    updateColumn(text) {
+        const lastNewline = text.lastIndexOf('\n');
+        if (lastNewline >= 0) {
+            this.currentColumn = text.length - lastNewline - 1;
+        }
+        else {
+            this.currentColumn += text.length;
+        }
+    }
+    /**
+     * Add a space if needed before the next token.
+     */
+    addSpaceIfNeeded() {
+        const lastChar = this.getLastChar();
+        if (lastChar !== '' && lastChar !== ' ' && lastChar !== '\n' &&
+            lastChar !== '(' && lastChar !== '[') {
+            this.push(' ');
+        }
+    }
+    /**
+     * Ensure we're at the start of a new line.
+     */
+    ensureNewline() {
+        if (!this.isEmpty() && !this.endsWithNewline()) {
+            this.push('\n');
+        }
+    }
+}
+/**
+ * Outputs pending comments with proper formatting.
+ */
+export function outputComments(builder, comments, addSpaceBefore = true) {
+    if (comments.length === 0) {
+        return { outputAny: false, lastWasMultilineBlock: false };
+    }
+    let lastWasMultilineBlock = false;
+    for (const comment of comments) {
+        // Preserve blank line before comment if it existed in the original
+        if (comment.hadBlankLineBefore && !builder.isEmpty()) {
+            builder.ensureNewline();
+            builder.push('\n'); // Add extra newline for blank line
+        }
+        else if (addSpaceBefore && !builder.isEmpty()) {
+            const lastChar = builder.getLastChar();
+            // Don't add space after newline or space
+            // For line comments, add space even after open paren
+            const isLineComment = comment.type === SqlBaseLexer.SIMPLE_COMMENT;
+            if (lastChar !== '\n' && lastChar !== ' ') {
+                if (lastChar !== '(' || isLineComment) {
+                    builder.push(' ');
+                }
+            }
+        }
+        builder.push(comment.text);
+        // Track if this is a multi-line block comment
+        lastWasMultilineBlock = comment.type === SqlBaseLexer.BRACKETED_COMMENT &&
+            comment.text.includes('\n');
+        // Add newline after multi-line block comment
+        if (lastWasMultilineBlock) {
+            builder.push('\n');
+        }
+        addSpaceBefore = true;
+    }
+    return { outputAny: true, lastWasMultilineBlock };
+}
+/**
+ * Determines if a space should be skipped before the current token.
+ */
+export function shouldSkipSpace(builder, text, context) {
+    const lastChar = builder.getLastChar();
+    // Check for hex/binary literals: X'...' or B'...' (case-insensitive)
+    const prevWasHexBinaryPrefix = (context.prevTokenText.toUpperCase() === 'X' ||
+        context.prevTokenText.toUpperCase() === 'B') &&
+        context.currentTokenIsStringLiteral;
+    // Skip space after dot ONLY if previous token was actually a DOT token (member access)
+    // Not if it's a decimal literal ending with . like "1."
+    const prevWasMemberAccessDot = lastChar === '.' && context.prevWasDotToken;
+    // IMPORTANT: Don't skip space between consecutive unary operators like "- -5"
+    // Otherwise it becomes "--5" which is a line comment!
+    const prevWasUnaryAndCurrentIsUnary = context.prevTokenWasUnaryOperator && context.currentTokenIsUnaryOperator;
+    // Inside complex types (ARRAY<INT>, MAP<STRING, INT>, STRUCT<a:INT>)
+    // Skip spaces around angle brackets and before commas
+    const inComplexType = context.complexTypeDepth > 0;
+    const isComplexTypeBracket = text === '<' || text === '>';
+    const prevWasComplexTypeBracket = lastChar === '<' || lastChar === '>';
+    // If prev was unary and current is also unary (like "- -5"), don't skip space!
+    if (prevWasUnaryAndCurrentIsUnary) {
+        return false; // Need space to avoid "--" becoming a comment
+    }
+    return (lastChar === '(' ||
+        prevWasMemberAccessDot ||
+        lastChar === '\n' ||
+        text === ')' ||
+        text === '.' ||
+        text === ',' || // Never add space before comma
+        text === '::' ||
+        context.prevIsDoubleColon ||
+        (text === '(' && (context.prevWasFunctionName || context.prevWasBuiltInFunctionKeyword)) ||
+        context.isLateralViewComma ||
+        context.justOutputCommaFirstStyle ||
+        context.justOutputMultiArgFunctionNewline ||
+        context.justOutputWindowNewline ||
+        context.justOutputInListWrapNewline ||
+        context.afterWhereKeyword ||
+        context.afterHavingKeyword ||
+        context.prevTokenWasUnaryOperator ||
+        lastChar === '[' ||
+        text === '[' ||
+        text === ']' ||
+        prevWasHexBinaryPrefix ||
+        // Complex type handling: no spaces around < and > and : (for struct fields like a:INT)
+        (inComplexType && isComplexTypeBracket) ||
+        (inComplexType && prevWasComplexTypeBracket) ||
+        (text === ':' && inComplexType) || // No space before : in struct field (a:INT)
+        (lastChar === ':' && inComplexType) // No space after : in struct field
+    );
+}
+/**
+ * Determines if a comma-space should be added.
+ */
+export function shouldAddCommaSpace(builder, insideParens, justOutputCommaFirstStyle) {
+    return builder.getLastChar() === ',' &&
+        insideParens > 0 &&
+        !justOutputCommaFirstStyle;
+}
+/**
+ * Format hint content: uppercase hint names, preserve table names.
+ * Example: "broadcast(t1), merge(t2)" → "BROADCAST(t1), MERGE(t2)"
+ */
+export function formatHintContent(content) {
+    return content.replace(/([a-zA-Z_][a-zA-Z0-9_]*)\s*(\()/g, (match, name, paren) => {
+        return name.toUpperCase() + paren;
+    });
+}

package/dist/formatters/sparksql/parse-tree-analyzer.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Parse Tree Analyzer - Collects Formatting Context from AST
+ *
+ * This visitor walks the ANTLR parse tree and collects information about:
+ * - Identifier tokens (preserve casing)
+ * - Function call tokens (uppercase)
+ * - Clause-starting tokens (newline before)
+ * - List item separators (commas in SELECT, GROUP BY, ORDER BY)
+ * - Condition separators (AND/OR in WHERE/HAVING)
+ * - Subquery boundaries
+ * - And many more context-specific positions
+ *
+ * This is 100% grammar-driven - no hardcoded keyword lists.
+ */
+import SqlBaseParserVisitor from './generated/SqlBaseParserVisitor.js';
+import type { AnalyzerResult, MultiArgFunctionInfo, WindowDefInfo, SimpleQueryInfo, PivotInfo, InListInfo } from './types.js';
+/**
+ * Visitor that collects context information from parse tree.
+ * After visiting, call getResult() to get the analysis.
+ */
+export declare class ParseTreeAnalyzer extends SqlBaseParserVisitor {
+    identifierTokens: Set<number>;
+    functionCallTokens: Set<number>;
+    clauseStartTokens: Set<number>;
+    qualifiedNameTokens: Set<number>;
+    listItemCommas: Set<number>;
+    listFirstItems: Set<number>;
+    multiItemClauses: Set<number>;
+    conditionOperators: Set<number>;
+    multilineConditionClauses: Set<number>;
+    betweenAndTokens: Set<number>;
+    subqueryDepth: number;
+    tokenDepthMap: Map<number, number>;
+    subqueryOpenParens: Set<number>;
+    subqueryCloseParens: Set<number>;
+    setOperandParens: Set<number>;
+    aliasInsertPositions: Set<number>;
+    tableAliasAsTokens: Set<number>;
+    joinOnTokens: Set<number>;
+    cteCommas: Set<number>;
+    cteMainSelectTokens: Set<number>;
+    ddlColumnCommas: Set<number>;
+    ddlOpenParens: Set<number>;
+    ddlCloseParens: Set<number>;
+    ddlFirstColumn: Set<number>;
+    ddlMultiColumn: Set<number>;
+    valuesCommas: Set<number>;
+    valuesHasTuples: boolean;
+    setClauseCommas: Set<number>;
+    setKeywordToken: number;
+    multiWhenCaseTokens: Set<number>;
+    caseWhenTokens: Set<number>;
+    caseElseTokens: Set<number>;
+    caseEndTokens: Set<number>;
+    simpleCaseTokens: Set<number>;
+    simpleCaseValueEndTokens: Set<number>;
+    groupingAnalyticsParens: Set<number>;
+    private insideGroupingAnalytics;
+    exceptClauseTokens: Set<number>;
+    setConfigTokens: Set<number>;
+    mergeUsingTokens: Set<number>;
+    mergeOnTokens: Set<number>;
+    mergeWhenTokens: Set<number>;
+    lateralViewCommas: Set<number>;
+    groupByAllTokens: Set<number>;
+    multiArgFunctionInfo: Map<number, MultiArgFunctionInfo>;
+    windowDefInfo: Map<number, WindowDefInfo>;
+    pivotInfo: Map<number, PivotInfo>;
+    inListInfo: Map<number, InListInfo>;
+    simpleQueries: Map<number, SimpleQueryInfo>;
+    private currentSelectToken;
+    /**
+     * Get the complete analysis result after visiting.
+     */
+    getResult(): AnalyzerResult;
+    visit(ctx: any): any;
+    visitChildren(ctx: any): any;
+    visitIdentifier(ctx: any): any;
+    visitStrictIdentifier(ctx: any): any;
+    visitQuotedIdentifier(ctx: any): any;
+    visitBackQuotedIdentifier(ctx: any): any;
+    visitUnquotedIdentifier(ctx: any): any;
+    visitErrorCapturingIdentifier(ctx: any): any;
+    /**
+     * Visit qualified name (e.g., table.column, db.schema.table.column)
+     * GRAMMAR-DRIVEN: qualifiedName : identifier (DOT identifier)*
+     *
+     * Context-sensitive keyword handling: In qualified names, even tokens that are
+     * keywords (like USER, TABLE) should be treated as identifiers and preserve casing.
+     * This is because the grammar context (qualifiedName rule) makes them identifiers.
+     */
+    visitQualifiedName(ctx: any): any;
+    /**
+     * Visit dereference (field access like user.address, table.column)
+     * GRAMMAR-DRIVEN: base=primaryExpression DOT fieldName=identifier
+     *
+     * When a keyword like USER or TABLE appears before DOT, it should be treated
+     * as an identifier (table/column alias), not as a keyword.
+     * Similarly, keywords appearing as field names (like KEY, ORDER) should preserve casing.
+     */
+    visitDereference(ctx: any): any;
+    visitFunctionCall(ctx: any): any;
+    visitFunctionName(ctx: any): any;
+    visitFirst(ctx: any): any;
+    visitLast(ctx: any): any;
+    visitAny_value(ctx: any): any;
+    visitStruct(ctx: any): any;
+    visitExtract(ctx: any): any;
+    visitCast(ctx: any): any;
+    visitPosition(ctx: any): any;
+    visitTimestampadd(ctx: any): any;
+    visitTimestampdiff(ctx: any): any;
+    visitLateralView(ctx: any): any;
+    visitSearchedCase(ctx: any): any;
+    visitSimpleCase(ctx: any): any;
+    visitExceptClause(ctx: any): any;
+    visitFromClause(ctx: any): any;
+    /**
+     * Visit table alias context and mark AS tokens for suppression.
+     * Style guide says table aliases should NOT have AS keyword.
+     * Grammar: tableAlias: (AS? strictIdentifier identifierList?)?
+     */
+    visitTableAlias(ctx: any): any;
+    visitAggregationClause(ctx: any): any;
+    visitGroupingAnalytics(ctx: any): any;
+    visitQueryOrganization(ctx: any): any;
+    visitSortItem(ctx: any): any;
+    visitLimitClause(ctx: any): any;
+    visitJoinRelation(ctx: any): any;
+    visitWindowDef(ctx: any): any;
+    visitPivotClause(ctx: any): any;
+    visitUnpivotClause(ctx: any): any;
+    visitSetOperation(ctx: any): any;
+    visitSelectClause(ctx: any): any;
+    visitNamedExpression(ctx: any): any;
+    visitNamedExpressionSeq(ctx: any): any;
+    visitGroupByClause(ctx: any): any;
+    visitWhereClause(ctx: any): any;
+    visitHavingClause(ctx: any): any;
+    visitPredicate(ctx: any): any;
+    visitQuery(ctx: any): any;
+    private _findFirstSelectToken;
+    visitCtes(ctx: any): any;
+    visitNamedQuery(ctx: any): any;
+    visitAliasedQuery(ctx: any): any;
+    visitExists(ctx: any): any;
+    visitSubqueryExpression(ctx: any): any;
+    visitSubquery(ctx: any): any;
+    visitCreateTableHeader(ctx: any): any;
+    visitCreateTable(ctx: any): any;
+    visitCreateUserDefinedFunction(ctx: any): any;
+    visitInsertInto(ctx: any): any;
+    visitInlineTable(ctx: any): any;
+    visitUpdateTable(ctx: any): any;
+    visitSetConfiguration(ctx: any): any;
+    visitResetConfiguration(ctx: any): any;
+    visitMergeIntoTable(ctx: any): any;
+    visitQuerySpecification(ctx: any): any;
+    visitRegularQuerySpecification(ctx: any): any;
+    private _visitQuerySpec;
+    /**
+     * Check if a context is inside a CREATE VIEW/TABLE statement at the top level.
+     * Queries inside these DDL statements should never be compacted.
+     */
+    private _isInsideCreateStatement;
+    /**
+     * Analyze if a query is simple enough to stay on one line.
+     * Simple query criteria:
+     * - SELECT has 1 item (including *, t.*)
+     * - FROM has 1 table (no JOINs)
+     * - WHERE has 0 or 1 condition (no AND/OR at top level)
+     * - No GROUP BY, ORDER BY, HAVING, or single-item versions
+     * - No LIMIT/OFFSET or simple LIMIT
+     * - NOT inside a CREATE VIEW/TABLE statement (those always expand)
+     */
+    private _analyzeSimpleQuery;
+    /**
+     * Check if FROM clause contains any JOINs.
+     */
+    private _hasJoinInFromClause;
+    /**
+     * Check if FROM clause contains PIVOT or UNPIVOT with many items.
+     * Simple PIVOT with few items can stay compact.
+     */
+    private _hasPivotUnpivotInFromClause;
+    /**
+     * Check if SELECT clause has a single item (*, t.*, or one expression).
+     */
+    private _hasSingleSelectItem;
+    /**
+     * Check if a clause contains a CASE expression with multiple WHEN clauses.
+     * Such CASE expressions force expansion and make the query non-compact.
+     */
+    private _hasMultiWhenCase;
+    /**
+     * Check if WHERE/HAVING clause has multiple conditions (AND/OR at top level).
+     */
+    private _hasMultipleConditions;
+    /**
+     * Calculate the expected formatted span length of a context.
+     *
+     * This walks all tokens within the context and sums:
+     * - Each token's text length
+     * - One space between each pair of tokens (standard formatting)
+     *
+     * This gives an accurate estimate of the formatted output length.
+     *
+     * @param ctx The parse tree context
+     * @param forExpansion If true, returns Infinity for multi-line constructs
+     *                     to prevent already-expanded constructs from collapsing.
+     *                     If false, calculates actual span (for simple query detection).
+     */
+    private _calculateSpanLength;
+    /**
+     * Calculate normalized span length independent of input formatting.
+     * This sums up token text lengths + single spaces between tokens,
+     * giving a consistent "single-line" representation length.
+     *
+     * CRITICAL FOR IDEMPOTENCY: Using character positions (_calculateSpanLength)
+     * varies based on how the input is formatted (line breaks, extra spaces).
+     * This causes different expansion decisions on subsequent passes.
+     * By using token text lengths, we get consistent results regardless of input formatting.
+     */
+    private _calculateNormalizedSpanLength;
+    private _collectMultiArgFunctionInfo;
+    private _collectWindowDefInfo;
+    /**
+     * Collect IN list information for potential wrapping.
+     * Structure: expr IN (value1, value2, value3, ...)
+     * We want to track the IN list so we can wrap it at max line width.
+     */
+    private _collectInListInfo;
+    /**
+     * Collect PIVOT/UNPIVOT clause information for potential expansion.
+     * Structure: PIVOT (aggregates FOR column IN (values))
+     */
+    private _collectPivotInfo;
+    private _analyzeCaseExpression;
+    private _findTokenInContext;
+    private _analyzeJoinConditions;
+    private _findOnToken;
+    private _findSubqueryContext;
+    private _markAllDescendantTokens;
+    private _markIdentifier;
+    private _markClauseStart;
+    private _markListContext;
+    private _markCommasInContext;
+    private _markListCommasExcludingGroupingAnalytics;
+    private _markGroupByAllToken;
+    private _findAllTokenInGroupByExpression;
+    private _analyzeConditionClause;
+    private _countConditionOperators;
+    private _scanForBetweenAnd;
+    private _markSubqueryParens;
+    private _markDdlColumnList;
+    private _markDdlCommasInContext;
+    private _markValuesCommas;
+    private _markSetClause;
+    private _markSetConfigTokens;
+    private _markResetConfigTokens;
+    private _markSetConfigTokensRecursive;
+    private _markMergeClauses;
+    private _markDepthForContext;
+}