@jacobknightley/fabric-format 0.0.1

package/dist/formatters/python/python-formatter.js

@@ -0,0 +1,180 @@
+/**
+ * Python Formatter
+ *
+ * Uses Ruff WASM to format Python/PySpark code.
+ * Handles Jupyter/IPython magic commands by preserving them.
+ */
+import { RUFF_WASM_CONFIG } from './config.js';
+// Dynamic import for ruff WASM (loaded on demand)
+let ruffModule = null;
+let workspace = null;
+/**
+ * Python formatter using Ruff WASM.
+ */
+export class PythonFormatter {
+    language = 'python';
+    displayName = 'Python (Ruff)';
+    initialized = false;
+    initError = null;
+    wasmOptions;
+    /**
+     * Create a new Python formatter.
+     * @param options - Optional WASM initialization options for browser environments
+     */
+    constructor(options) {
+        this.wasmOptions = options;
+    }
+    isReady() {
+        return this.initialized && !this.initError;
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            // Dynamic import of ruff WASM
+            ruffModule = await import('@astral-sh/ruff-wasm-web');
+            // Initialize WASM module - this must be called before using any classes
+            // The default export is the init function that loads the .wasm binary
+            if (this.wasmOptions?.wasmBinary) {
+                // Use synchronous initialization with provided binary
+                ruffModule.initSync({ module: this.wasmOptions.wasmBinary });
+            }
+            else if (this.wasmOptions?.wasmUrl) {
+                // Use async initialization with provided URL
+                await ruffModule.default({ module_or_path: this.wasmOptions.wasmUrl });
+            }
+            else {
+                // Default: let ruff-wasm-web use import.meta.url to find the WASM file
+                // This works in Node.js and ESM environments but may fail in bundled IIFE
+                await ruffModule.default();
+            }
+            // Create workspace with config
+            // Note: ruff WASM prints debug info to stdout during Workspace creation
+            // We suppress this by temporarily replacing stdout.write (Node.js only)
+            const hasProcess = typeof process !== 'undefined' && process.stdout?.write;
+            const originalWrite = hasProcess ? process.stdout.write.bind(process.stdout) : null;
+            if (originalWrite) {
+                process.stdout.write = () => true; // Suppress output
+            }
+            try {
+                workspace = new ruffModule.Workspace(RUFF_WASM_CONFIG, ruffModule.PositionEncoding.Utf32);
+            }
+            finally {
+                if (originalWrite) {
+                    process.stdout.write = originalWrite; // Restore output
+                }
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            this.initError = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to initialize Python formatter: ${this.initError}`);
+        }
+    }
+    format(code, options) {
+        if (!this.isReady() || !workspace) {
+            return {
+                formatted: code,
+                changed: false,
+                error: this.initError ?? 'Python formatter not initialized'
+            };
+        }
+        try {
+            // Check if the cell starts with a cell magic (%%magic)
+            // %%pyspark and %%python contain Python code - format everything after the magic line
+            // Other cell magics (%%sql, %%scala, %%r, %%sh, etc.) are not Python - return as-is
+            const cellMagicMatch = code.match(/^(%%(\w+).*)\n?/);
+            if (cellMagicMatch) {
+                const magicLine = cellMagicMatch[1];
+                const magicType = cellMagicMatch[2].toLowerCase();
+                // Only format Python-based cell magics
+                if (magicType === 'pyspark' || magicType === 'python') {
+                    // Extract the code after the magic line
+                    const codeAfterMagic = code.slice(cellMagicMatch[0].length);
+                    if (!codeAfterMagic.trim()) {
+                        return { formatted: code, changed: false };
+                    }
+                    // Format the Python code
+                    let formatted = workspace.format(codeAfterMagic);
+                    // Strip trailing newline if configured
+                    if (options?.stripTrailingNewline) {
+                        formatted = formatted.replace(/\n+$/, '');
+                    }
+                    // Recombine with magic line
+                    const result = magicLine + '\n' + formatted;
+                    return { formatted: result, changed: result !== code };
+                }
+                // Non-Python cell magics - return as-is
+                return { formatted: code, changed: false };
+            }
+            // Handle line magics (%magic) at the start of lines
+            const lines = code.split('\n');
+            const magicPrefix = [];
+            let pythonStartIndex = 0;
+            // Collect leading line magics and comments
+            for (let i = 0; i < lines.length; i++) {
+                const trimmed = lines[i].trim();
+                if (trimmed.startsWith('%') || trimmed.startsWith('#') || trimmed === '') {
+                    magicPrefix.push(lines[i]);
+                    pythonStartIndex = i + 1;
+                }
+                else {
+                    break;
+                }
+            }
+            // If entire code is magics/comments, return as-is
+            if (pythonStartIndex >= lines.length) {
+                return { formatted: code, changed: false };
+            }
+            // Extract Python code to format
+            const pythonCode = lines.slice(pythonStartIndex).join('\n');
+            // Format the Python portion
+            let formatted = workspace.format(pythonCode);
+            // Post-processing: Strip trailing newline if configured
+            if (options?.stripTrailingNewline) {
+                formatted = formatted.replace(/\n+$/, '');
+            }
+            // Recombine with magic prefix
+            if (magicPrefix.length > 0) {
+                formatted = magicPrefix.join('\n') + '\n' + formatted;
+            }
+            const changed = formatted !== code;
+            return { formatted, changed };
+        }
+        catch (error) {
+            return {
+                formatted: code,
+                changed: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    needsFormatting(code, options) {
+        const result = this.format(code, options);
+        return result.changed;
+    }
+}
+/**
+ * Detect if a cell/file is Python/PySpark.
+ */
+export function isPythonCode(cellType) {
+    return cellType === 'python' || cellType === 'pyspark';
+}
+/** Singleton instance */
+let pythonFormatterInstance = null;
+/**
+ * Get the Python formatter instance (creates on first call).
+ * @param options - Optional WASM initialization options. Only used on first call.
+ */
+export function getPythonFormatter(options) {
+    if (!pythonFormatterInstance) {
+        pythonFormatterInstance = new PythonFormatter(options);
+    }
+    return pythonFormatterInstance;
+}
+/**
+ * Reset the Python formatter instance (for testing or reinitialization with different options).
+ */
+export function resetPythonFormatter() {
+    pythonFormatterInstance = null;
+}

package/dist/formatters/sparksql/constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Formatting Constants
+ *
+ * Central location for configurable formatting thresholds and limits.
+ * These values control line-width based expansion decisions.
+ *
+ * Line width checks use: currentColumn + expressionSpan > threshold
+ * This ensures the FULL LINE (including indentation) stays under the limit,
+ * consistent with formatters like ruff, prettier, etc.
+ */
+/**
+ * Maximum desired line width.
+ * Expressions are expanded to multiple lines if they would cause the
+ * full line (including indentation) to exceed this width.
+ */
+export declare const MAX_LINE_WIDTH = 140;

package/dist/formatters/sparksql/constants.js

@@ -0,0 +1,16 @@
+/**
+ * Formatting Constants
+ *
+ * Central location for configurable formatting thresholds and limits.
+ * These values control line-width based expansion decisions.
+ *
+ * Line width checks use: currentColumn + expressionSpan > threshold
+ * This ensures the FULL LINE (including indentation) stays under the limit,
+ * consistent with formatters like ruff, prettier, etc.
+ */
+/**
+ * Maximum desired line width.
+ * Expressions are expanded to multiple lines if they would cause the
+ * full line (including indentation) to exceed this width.
+ */
+export const MAX_LINE_WIDTH = 140;

package/dist/formatters/sparksql/fmt-detector.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Format Directive Detection - Identifies formatting suppression directives
+ *
+ * Supports two types of format directives:
+ * 1. Statement-level: "-- fmt: off" or block comment at start of statement
+ *    - Bypasses all formatting for the entire statement
+ * 2. Line-level inline: "-- fmt: inline" or block comment version
+ *    - Suppresses multi-line expansion while keeping other formatting
+ */
+/**
+ * A token range that should be forced inline (no expansion).
+ * Used for fmt:inline directive processing.
+ */
+export interface ForceInlineRange {
+    /** Opening token index (e.g., LEFT_PAREN of function) */
+    openTokenIndex: number;
+    /** Closing token index (e.g., RIGHT_PAREN of function) */
+    closeTokenIndex: number;
+}
+/**
+ * Information about format directives in the SQL.
+ */
+export interface FormatDirectiveInfo {
+    /** Set of 1-based line numbers with fmt:inline directives (legacy, for backward compat) */
+    collapsedLines: Set<number>;
+    /** Token ranges that should be forced inline (grammar-driven approach) */
+    forceInlineRanges: ForceInlineRange[];
+}
+/**
+ * Check if a statement starts with a fmt:off directive (full bypass).
+ *
+ * @param statement - The SQL statement to check
+ * @returns true if the statement should bypass formatting entirely
+ */
+export declare function hasFormatOff(statement: string): boolean;
+/**
+ * Detect all fmt:inline directives in a SQL string.
+ *
+ * @param sql - The SQL string to scan
+ * @returns FormatDirectiveInfo with line numbers that have inline directives
+ */
+export declare function detectCollapseDirectives(sql: string): FormatDirectiveInfo;
+/**
+ * Check if a specific line has an inline directive.
+ *
+ * @param formatDirectives - The FormatDirectiveInfo from detectCollapseDirectives
+ * @param lineNumber - 1-based line number to check
+ * @returns true if the line has fmt:inline
+ */
+export declare function hasCollapseDirective(formatDirectives: FormatDirectiveInfo, lineNumber: number): boolean;
+/**
+ * Check if a comment text contains a fmt:inline directive.
+ *
+ * @param commentText - The comment text to check (including -- or /* markers)
+ * @returns true if the comment contains fmt:inline
+ */
+export declare function isFmtInlineComment(commentText: string): boolean;
+/**
+ * Check if a token index falls within any force-inline range.
+ *
+ * @param tokenIndex - The token index to check
+ * @param ranges - Array of force-inline ranges
+ * @returns true if the token is within a force-inline range
+ */
+export declare function isInForceInlineRange(tokenIndex: number, ranges: ForceInlineRange[]): boolean;

package/dist/formatters/sparksql/fmt-detector.js

@@ -0,0 +1,84 @@
+/**
+ * Format Directive Detection - Identifies formatting suppression directives
+ *
+ * Supports two types of format directives:
+ * 1. Statement-level: "-- fmt: off" or block comment at start of statement
+ *    - Bypasses all formatting for the entire statement
+ * 2. Line-level inline: "-- fmt: inline" or block comment version
+ *    - Suppresses multi-line expansion while keeping other formatting
+ */
+// ============================================================================
+// REGEX PATTERNS
+// ============================================================================
+/**
+ * Pattern to detect statement-level fmt:off at the start of a statement.
+ * Matches: "-- fmt: off" or "-- fmt:off" or block comment version (case-insensitive)
+ */
+const STATEMENT_OFF_PATTERN = /^\s*(?:--\s*fmt\s*:\s*off\s*$|--\s*fmt\s*:\s*off\s+|\/\*\s*fmt\s*:\s*off\s*\*\/)/i;
+/**
+ * Pattern to detect line-level fmt:inline anywhere on a line.
+ * Matches: "-- fmt: inline" or "-- fmt:inline" or block comment version (case-insensitive)
+ */
+const COLLAPSE_PATTERN = /(?:--\s*fmt\s*:\s*inline|\/\*\s*fmt\s*:\s*inline\s*\*\/)/i;
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+/**
+ * Check if a statement starts with a fmt:off directive (full bypass).
+ *
+ * @param statement - The SQL statement to check
+ * @returns true if the statement should bypass formatting entirely
+ */
+export function hasFormatOff(statement) {
+    return STATEMENT_OFF_PATTERN.test(statement);
+}
+/**
+ * Detect all fmt:inline directives in a SQL string.
+ *
+ * @param sql - The SQL string to scan
+ * @returns FormatDirectiveInfo with line numbers that have inline directives
+ */
+export function detectCollapseDirectives(sql) {
+    const collapsedLines = new Set();
+    const lines = sql.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        if (COLLAPSE_PATTERN.test(lines[i])) {
+            collapsedLines.add(i + 1); // 1-based line numbers
+        }
+    }
+    return { collapsedLines, forceInlineRanges: [] };
+}
+/**
+ * Check if a specific line has an inline directive.
+ *
+ * @param formatDirectives - The FormatDirectiveInfo from detectCollapseDirectives
+ * @param lineNumber - 1-based line number to check
+ * @returns true if the line has fmt:inline
+ */
+export function hasCollapseDirective(formatDirectives, lineNumber) {
+    return formatDirectives.collapsedLines.has(lineNumber);
+}
+/**
+ * Check if a comment text contains a fmt:inline directive.
+ *
+ * @param commentText - The comment text to check (including -- or /* markers)
+ * @returns true if the comment contains fmt:inline
+ */
+export function isFmtInlineComment(commentText) {
+    return COLLAPSE_PATTERN.test(commentText);
+}
+/**
+ * Check if a token index falls within any force-inline range.
+ *
+ * @param tokenIndex - The token index to check
+ * @param ranges - Array of force-inline ranges
+ * @returns true if the token is within a force-inline range
+ */
+export function isInForceInlineRange(tokenIndex, ranges) {
+    for (const range of ranges) {
+        if (tokenIndex >= range.openTokenIndex && tokenIndex <= range.closeTokenIndex) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/formatters/sparksql/formatter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Spark SQL Formatter - Main Entry Point
+ *
+ * This is the 100% grammar-driven SQL formatter for Apache Spark SQL.
+ * NO HARDCODED KEYWORD, FUNCTION, OR CLAUSE LISTS.
+ * Everything derived from ANTLR lexer symbolicNames and parse tree context.
+ *
+ * Architecture:
+ * - types.ts: TypeScript interfaces
+ * - token-utils.ts: Grammar-derived token detection
+ * - parse-tree-analyzer.ts: AST visitor that collects formatting context
+ * - formatting-context.ts: State management during formatting
+ * - output-builder.ts: Output construction with column tracking
+ * - formatter.ts (this file): Main orchestration
+ */
+/**
+ * Format SQL - Main entry point.
+ * Handles magic commands, semicolon-separated statements, and formatting.
+ */
+export declare function formatSql(sql: string): string;
+/**
+ * Check if SQL needs formatting.
+ */
+export declare function needsFormatting(sql: string): boolean;