@jacobknightley/fabric-format 0.0.1

package/README.md

@@ -0,0 +1,196 @@
+# fabric-format
+
+A zero-config formatter for **Microsoft Fabric notebooks**.
+
+## Packages
+
+| Package                                      | Description                                |
+| -------------------------------------------- | ------------------------------------------ |
+| [@jacobknightley/fabric-format](./packages/core) | Core formatting library (npm package)      |
+| [fabric-format-chromium](./packages/chromium)    | Chrome/Edge extension for Fabric notebooks |
+
+## Philosophy
+
+**Opinionated by design.** This formatter has one style, enforced everywhere, with no configuration options—and no plans to add any.
+
+Built this for teams who want consistent notebook formatting without endless debates over style guides. The decisions are made. Your code looks the same every time.
+
+The focus is on clean, consistent output—not tailored experiences or nuanced edge cases.
+
+## CLI
+
+### Installation
+
+```bash
+npm install -g @jacobknightley/fabric-format
+```
+
+### Usage
+
+```bash
+# format
+fabfmt format notebook.py                                # Format a single file
+fabfmt format ./src                                      # Format all files in directory
+fabfmt format query.sql --print                          # Print formatted output
+fabfmt format --type sparksql -i "select * from t"       # Format inline string
+echo "select * from t" | fabfmt format --type sparksql   # Format from stdin
+
+# check (exit 1 if changes needed)
+fabfmt check notebook.py                                # Check a single file
+fabfmt check ./src                                      # Check all files in directory
+fabfmt check --type sparksql -i "select * from t"       # Check inline string
+echo "select * from t" | fabfmt check --type sparksql   # Check from stdin
+```
+
+## Browser Extension
+
+Format Fabric notebooks directly in your browser with a single click.
+
+### Installation
+
+1. Download `fabric-format-chromium.zip` from the [latest release](https://github.com/jacobknightley/fabric-format/releases)
+2. Extract the zip file
+3. Open your browser's extension page:
+   - **Chrome:** `chrome://extensions`
+   - **Edge:** `edge://extensions`
+4. Enable **Developer mode** (toggle in top-right)
+5. Click **Load unpacked** and select the extracted folder
+
+> **Note:** Plan to eventually support directly in Chrome and Edge extension stores.
+
+### Usage
+
+1. Open a notebook in Microsoft Fabric
+2. Click the **Format** button in the notebook toolbar
+
+   ![Format button in Fabric notebook toolbar](assets/extension-format-button.png)
+
+3. All cells in the notebook are formatted instantly
+
+## Supported File Types
+
+- `.py` — Python notebooks
+- `.scala` — Scala notebooks
+- `.r` — R notebooks
+- `.sql` — SQL notebooks
+
+## Supported Languages
+
+- Spark SQL
+- Python
+
+> **Note:** All other language cells are preserved as-is.
+
+### Spark SQL
+
+---
+
+Custom formatter built on [Apache Spark's official ANTLR grammar](https://github.com/apache/spark/tree/master/sql/api/src/main/antlr4/org/apache/spark/sql/catalyst/parser). If Spark supports the syntax, fabric-format formats it correctly.
+
+#### Style Overview
+
+| Element                | Formatting                 |
+| ---------------------- | -------------------------- |
+| Keywords               | `UPPERCASE`                |
+| Built-in functions     | `UPPERCASE()`              |
+| User-defined functions | `preserveCase()`           |
+| Identifiers            | `preserveCase`             |
+| Indentation            | 4 spaces                   |
+| Expression line width  | 140 characters (then wrap) |
+| Commas                 | Leading (comma-first)      |
+
+See [SQL_STYLE_GUIDE.md](./SQL_STYLE_GUIDE.md) for complete rules and examples.
+
+#### Format Directives
+
+##### `fmt: off`
+
+Skip formatting entirely—preserves original whitespace and casing. Applicable only to the statement directly after it.
+
+```sql
+-- fmt: off
+select  Col_A,Col_B B,Col_C   from   t;
+select  Col_A,Col_B B,Col_C   from   t;
+```
+
+⬇️ Output
+
+```sql
+-- fmt: off
+select  Col_A,Col_B B,Col_C   from   t;
+
+SELECT
+     Col_A
+    ,Col_B AS B
+    ,Col_C
+FROM t;
+```
+
+##### `fmt: inline`
+
+Suppress line wrapping for long expressions that are wrapped by default at 140 characters.
+
+```sql
+SELECT
+     conv(right(md5(upper(concat(coalesce(VeryLongTable.VeryLongColumnName, AnotherLongAlias.AnotherLongColumn), SomeOtherReallyLongColumnName))), 16), 16, -10) AS A-- fmt: inline
+    ,conv(right(md5(upper(concat(coalesce(VeryLongTable.VeryLongColumnName, AnotherLongAlias.AnotherLongColumn), SomeOtherReallyLongColumnName))), 16), 16, -10) AS B
+FROM t
+```
+
+⬇️ Output
+
+```sql
+SELECT
+     CONV(RIGHT(MD5(UPPER(CONCAT(COALESCE(VeryLongTable.VeryLongColumnName, AnotherLongAlias.AnotherLongColumn), SomeOtherReallyLongColumnName))), 16), 16, -10) AS A -- fmt: inline
+    ,CONV(
+         RIGHT(
+             MD5(UPPER(CONCAT(
+                 COALESCE(VeryLongTable.VeryLongColumnName, AnotherLongAlias.AnotherLongColumn)
+                ,SomeOtherReallyLongColumnName
+            )))
+            ,16
+        )
+        ,16
+        ,-10
+    ) AS B
+FROM t
+```
+
+### Python
+
+---
+
+Formatted via [Ruff](https://docs.astral.sh/ruff/) with sensible defaults:
+
+- 140 character line width
+- 4-space indentation
+- Double quotes
+- PEP 8 compliant
+
+Magic commands (`%%sql`, `%run`, etc.) are preserved.
+
+#### Format Directives
+
+##### `fmt: off` / `fmt: on`
+
+Disable formatting for a block of code:
+
+```python
+# fmt: off
+matrix = [
+    1, 0, 0,
+    0, 1, 0,
+    0, 0, 1,
+]
+# fmt: on
+```
+
+##### `fmt: skip`
+
+Skip formatting for a single statement:
+
+```python
+result = some_function(a, b,    c,d,  e)  # fmt: skip
+```
+
+See [Ruff's documentation](https://docs.astral.sh/ruff/formatter/#format-suppression) for more details.

package/dist/cell-formatter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Cell Formatter
+ *
+ * Low-level API for formatting raw cell content by type.
+ * Use this when you already know the cell type (e.g., from a Chrome extension
+ * that reads the cell metadata directly).
+ *
+ * @example
+ * ```typescript
+ * import { formatCell, formatCellSync, initializePythonFormatter } from '@jacobknightley/fabric-format';
+ *
+ * // Format Spark SQL (synchronous)
+ * const result = formatCellSync('select * from table', 'sparksql');
+ * console.log(result.formatted); // 'SELECT * FROM table'
+ *
+ * // Format Python (async - needs initialization)
+ * await initializePythonFormatter();
+ * const result = formatCell('x=1', 'python');
+ * console.log(result.formatted); // 'x = 1'
+ * ```
+ */
+import { type WasmInitOptions } from './formatters/python/index.js';
+/** Result from formatCell */
+export interface FormatCellResult {
+    /** The formatted content */
+    formatted: string;
+    /** Whether the content was changed */
+    changed: boolean;
+    /** Error message if formatting failed */
+    error?: string;
+}
+/** Supported cell types for formatCell */
+export type CellType = 'sparksql' | 'python' | 'pyspark';
+/**
+ * Initialize the Python formatter (must be called before formatting Python cells).
+ * This is async because the Ruff WASM module needs to be loaded.
+ *
+ * @param options - Optional WASM initialization options for browser environments.
+ *   - wasmUrl: URL to the .wasm file (use this in Chrome extensions with chrome.runtime.getURL)
+ *   - wasmBinary: WASM binary as ArrayBuffer or Uint8Array (for sync initialization)
+ */
+export declare function initializePythonFormatter(options?: WasmInitOptions): Promise<void>;
+/**
+ * Check if Python formatter is ready.
+ */
+export declare function isPythonFormatterReady(): boolean;
+/**
+ * Format a single cell's content based on its type.
+ *
+ * This is the low-level API for formatting raw code content.
+ * Use this when you already know the cell type (e.g., from a Chrome extension
+ * that reads the cell metadata directly).
+ *
+ * @param content Raw cell content (no comment wrappers like `# MAGIC`)
+ * @param cellType The cell type from metadata (e.g., 'sparksql', 'python', 'pyspark')
+ * @returns Formatted content and status
+ *
+ * @example
+ * ```typescript
+ * // Format Spark SQL
+ * const result = formatCell('select * from table', 'sparksql');
+ * console.log(result.formatted); // 'SELECT * FROM table'
+ *
+ * // Format Python (must initialize first)
+ * await initializePythonFormatter();
+ * const result = formatCell('x=1', 'python');
+ * console.log(result.formatted); // 'x = 1'
+ * ```
+ */
+export declare function formatCell(content: string, cellType: CellType): FormatCellResult;
+/**
+ * Synchronous version of formatCell for Spark SQL only.
+ * Use this when you only need SQL formatting and don't want async.
+ */
+export declare function formatCellSync(content: string, cellType: 'sparksql'): FormatCellResult;

package/dist/cell-formatter.js

@@ -0,0 +1,144 @@
+/**
+ * Cell Formatter
+ *
+ * Low-level API for formatting raw cell content by type.
+ * Use this when you already know the cell type (e.g., from a Chrome extension
+ * that reads the cell metadata directly).
+ *
+ * @example
+ * ```typescript
+ * import { formatCell, formatCellSync, initializePythonFormatter } from '@jacobknightley/fabric-format';
+ *
+ * // Format Spark SQL (synchronous)
+ * const result = formatCellSync('select * from table', 'sparksql');
+ * console.log(result.formatted); // 'SELECT * FROM table'
+ *
+ * // Format Python (async - needs initialization)
+ * await initializePythonFormatter();
+ * const result = formatCell('x=1', 'python');
+ * console.log(result.formatted); // 'x = 1'
+ * ```
+ */
+import { getFormatterRegistry } from './formatters/index.js';
+import { formatSql as formatSqlDirect } from './formatters/sparksql/index.js';
+import { getPythonFormatter, resetPythonFormatter } from './formatters/python/index.js';
+// ============================================================================
+// Python Formatter State
+// ============================================================================
+/** State for Python formatter initialization */
+let pythonFormatterReady = false;
+let pythonFormatterInitPromise = null;
+/**
+ * Initialize the Python formatter (must be called before formatting Python cells).
+ * This is async because the Ruff WASM module needs to be loaded.
+ *
+ * @param options - Optional WASM initialization options for browser environments.
+ *   - wasmUrl: URL to the .wasm file (use this in Chrome extensions with chrome.runtime.getURL)
+ *   - wasmBinary: WASM binary as ArrayBuffer or Uint8Array (for sync initialization)
+ */
+export async function initializePythonFormatter(options) {
+    if (pythonFormatterReady)
+        return;
+    if (pythonFormatterInitPromise)
+        return pythonFormatterInitPromise;
+    pythonFormatterInitPromise = (async () => {
+        // If options provided, reset the formatter to use new options
+        if (options) {
+            resetPythonFormatter();
+        }
+        // Get or create the formatter with options
+        const pythonFormatter = getPythonFormatter(options);
+        // Re-register in the registry so formatCell uses the correct instance
+        const registry = getFormatterRegistry();
+        registry.register(pythonFormatter);
+        if (!pythonFormatter.isReady()) {
+            await pythonFormatter.initialize();
+        }
+        pythonFormatterReady = true;
+    })();
+    return pythonFormatterInitPromise;
+}
+/**
+ * Check if Python formatter is ready.
+ */
+export function isPythonFormatterReady() {
+    return pythonFormatterReady;
+}
+// ============================================================================
+// Cell Formatting API
+// ============================================================================
+/**
+ * Format a single cell's content based on its type.
+ *
+ * This is the low-level API for formatting raw code content.
+ * Use this when you already know the cell type (e.g., from a Chrome extension
+ * that reads the cell metadata directly).
+ *
+ * @param content Raw cell content (no comment wrappers like `# MAGIC`)
+ * @param cellType The cell type from metadata (e.g., 'sparksql', 'python', 'pyspark')
+ * @returns Formatted content and status
+ *
+ * @example
+ * ```typescript
+ * // Format Spark SQL
+ * const result = formatCell('select * from table', 'sparksql');
+ * console.log(result.formatted); // 'SELECT * FROM table'
+ *
+ * // Format Python (must initialize first)
+ * await initializePythonFormatter();
+ * const result = formatCell('x=1', 'python');
+ * console.log(result.formatted); // 'x = 1'
+ * ```
+ */
+export function formatCell(content, cellType) {
+    const type = cellType.toLowerCase();
+    switch (type) {
+        case 'sparksql':
+            try {
+                const formatted = formatSqlDirect(content);
+                return {
+                    formatted,
+                    changed: formatted !== content,
+                };
+            }
+            catch (error) {
+                return {
+                    formatted: content,
+                    changed: false,
+                    error: `Spark SQL format error: ${error}`,
+                };
+            }
+        case 'python':
+        case 'pyspark':
+            const registry = getFormatterRegistry();
+            const pythonFormatter = registry.get('python');
+            if (!pythonFormatter?.isReady()) {
+                return {
+                    formatted: content,
+                    changed: false,
+                    error: 'Python formatter not initialized. Call initializePythonFormatter() first.',
+                };
+            }
+            const result = pythonFormatter.format(content, {
+                stripTrailingNewline: true,
+            });
+            return {
+                formatted: result.formatted,
+                changed: result.changed,
+                error: result.error,
+            };
+        default:
+            // Unsupported cell type - return unchanged
+            return {
+                formatted: content,
+                changed: false,
+            };
+    }
+}
+/**
+ * Synchronous version of formatCell for Spark SQL only.
+ * Use this when you only need SQL formatting and don't want async.
+ */
+export function formatCellSync(content, cellType) {
+    return formatCell(content, cellType);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};