@jacobknightley/fabric-format 0.0.3 → 0.0.5

package/README.md

@@ -50,13 +50,11 @@ Format Fabric notebooks directly in your browser with a single click.
 
 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
+3. Load the unpacked extension in your browser:
+   - **Chrome:** [Install an unpacked extension](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world#load-unpacked)
+   - **Edge:** [Sideload an extension](https://learn.microsoft.com/en-us/microsoft-edge/extensions-chromium/getting-started/extension-sideloading)
 
-> **Note:** Plan to eventually support directly in Chrome and Edge extension stores.
+> **Note:** Plan to eventually publish to the Chrome Web Store and Edge Add-ons.
 
 ### Usage
 

package/dist/index.d.ts

@@ -12,7 +12,7 @@
 export { formatSql, needsFormatting } from './formatters/sparksql/index.js';
 export { getFormatterRegistry, detectLanguage, SqlFormatter, getSqlFormatter, isSqlCode, PythonFormatter, getPythonFormatter, isPythonCode, type LanguageFormatter, type FormatterOptions, type FormatResult, type FormatterConfig, type FormatterRegistry, } from './formatters/index.js';
 export { formatCell, formatCellSync, initializePythonFormatter, isPythonFormatterReady, type FormatCellResult, type CellType, } from './cell-formatter.js';
-export { parseNotebook, formatNotebook, type NotebookCell, type FabricNotebook, type FormatStats, } from './notebook-formatter.js';
+export { parseNotebook, formatNotebook, NotebookStructureError, type NotebookCell, type FabricNotebook, type FormatStats, } from './notebook-formatter.js';
 export { DEFAULT_RUFF_CONFIG, RUFF_WASM_CONFIG, type RuffConfig, type RuffFormatConfig, type WasmInitOptions, } from './formatters/python/index.js';
 export { hasFormatOff, detectCollapseDirectives, hasCollapseDirective, type FormatDirectiveInfo } from './formatters/sparksql/index.js';
 export type { AnalyzerResult, FormattingState, MultiArgFunctionInfo, WindowDefInfo, TokenContext, PendingComment, ExpandedFunction, ExpandedWindow } from './formatters/sparksql/types.js';

package/dist/index.js

@@ -30,7 +30,7 @@ export { formatCell, formatCellSync, initializePythonFormatter, isPythonFormatte
 // ============================================================================
 // Notebook Formatter (High-level API)
 // ============================================================================
-export { parseNotebook, formatNotebook, } from './notebook-formatter.js';
+export { parseNotebook, formatNotebook, NotebookStructureError, } from './notebook-formatter.js';
 // ============================================================================
 // Configuration (Python/Ruff)
 // ============================================================================

package/dist/notebook-formatter.d.ts

@@ -79,6 +79,14 @@ export interface FormatStats {
     cellsSkipped: number;
     errors: string[];
 }
+/** Error thrown when a notebook cell has invalid structure */
+export declare class NotebookStructureError extends Error {
+    readonly cellIndex: number;
+    readonly lineNumber: number;
+    readonly metadataLanguage: string;
+    readonly fileDefaultLanguage: string;
+    constructor(message: string, cellIndex: number, lineNumber: number, metadataLanguage: string, fileDefaultLanguage: string);
+}
 /**
  * Parse a Fabric notebook file into cells.
  * @param content The file content

package/dist/notebook-formatter.js

@@ -66,12 +66,68 @@ const R_CONFIG = {
     fabricHeader: '# Fabric notebook source', // Check if R has different header
     defaultLanguage: 'r',
 };
+/** Error thrown when a notebook cell has invalid structure */
+export class NotebookStructureError extends Error {
+    cellIndex;
+    lineNumber;
+    metadataLanguage;
+    fileDefaultLanguage;
+    constructor(message, cellIndex, lineNumber, metadataLanguage, fileDefaultLanguage) {
+        super(message);
+        this.cellIndex = cellIndex;
+        this.lineNumber = lineNumber;
+        this.metadataLanguage = metadataLanguage;
+        this.fileDefaultLanguage = fileDefaultLanguage;
+        this.name = 'NotebookStructureError';
+    }
+}
 // ============================================================================
 // INTERNAL UTILITIES
 // ============================================================================
-// ============================================================================
-// INTERNAL UTILITIES
-// ============================================================================
+/**
+ * Get the valid raw (uncommented) languages for a file type.
+ * Raw cells must match the file's native language - other languages must use MAGIC prefix.
+ */
+function getValidRawLanguages(defaultLanguage) {
+    switch (defaultLanguage) {
+        case 'python':
+            // Python files: raw cells can be python or pyspark
+            return new Set(['python', 'pyspark']);
+        case 'sparksql':
+            // SQL files: raw cells must be sparksql
+            return new Set(['sparksql']);
+        case 'scala':
+            // Scala files: raw cells must be scala
+            return new Set(['scala']);
+        case 'r':
+            // R files: raw cells must be r
+            return new Set(['r']);
+        default:
+            return new Set([defaultLanguage]);
+    }
+}
+/**
+ * Validate that a raw cell's metadata language matches the file type.
+ * Throws NotebookStructureError if there's a mismatch.
+ */
+function validateRawCellLanguage(metadataLanguage, isRawCell, config, cellIndex, lineNumber) {
+    if (!isRawCell || !metadataLanguage) {
+        // MAGIC cells can have any language, and cells without metadata are fine
+        return;
+    }
+    const validRawLanguages = getValidRawLanguages(config.defaultLanguage);
+    const normalizedLanguage = metadataLanguage.toLowerCase();
+    if (!validRawLanguages.has(normalizedLanguage)) {
+        const fileType = config.defaultLanguage === 'python' ? '.py' :
+            config.defaultLanguage === 'sparksql' ? '.sql' :
+                config.defaultLanguage === 'scala' ? '.scala' :
+                    config.defaultLanguage === 'r' ? '.r' :
+                        `.${config.defaultLanguage}`;
+        throw new NotebookStructureError(`Invalid notebook structure: Cell ${cellIndex + 1} (line ${lineNumber + 1}) has metadata language "${metadataLanguage}" ` +
+            `but is not wrapped with MAGIC prefix. In ${fileType} files, only ${config.defaultLanguage} cells can be raw/uncommented. ` +
+            `Other languages (like ${metadataLanguage}) must use the "${config.magicPrefix}%%" prefix.`, cellIndex, lineNumber, metadataLanguage, config.defaultLanguage);
+    }
+}
 /**
  * Line ending constant - this library standardizes on LF.
  */
@@ -291,6 +347,9 @@ export function parseNotebook(content, fileExtension) {
                 const magicCommand = extractMagicCommand(originalLines, config);
                 // Check if it's a MAGIC cell
                 const isMagicCell = originalLines.some(l => l.trim().startsWith(config.magicPrefix.trim()));
+                // Validate that raw cells have a language matching the file type
+                const cellIndex = result.cells.length;
+                validateRawCellLanguage(metadataLanguage, !isMagicCell, config, cellIndex, j);
                 // Extract content
                 let content;
                 let contentStartLine = j;
@@ -333,15 +392,27 @@ export function parseNotebook(content, fileExtension) {
 function replaceCell(fileContent, cell, formattedContent, config) {
     const lines = fileContent.split(/\r?\n/);
     let newLines;
-    if (cell.isMagicCell) {
-        newLines = addMagicPrefix(formattedContent, config);
+    if (cell.isMagicCell && cell.magicCommand) {
+        // For magic cells, prepend the magic command (without trailing whitespace)
+        const magicCommandLine = config.magicPrefix + '%%' + cell.magicCommand;
+        newLines = [magicCommandLine, ...addMagicPrefix(formattedContent, config)];
+        // Find where the magic command line starts (search backwards from contentStartLine)
+        let magicLineIndex = cell.contentStartLine - 1;
+        while (magicLineIndex >= 0 && !lines[magicLineIndex].trim().startsWith(config.magicPrefix + '%%')) {
+            magicLineIndex--;
+        }
+        const before = lines.slice(0, magicLineIndex >= 0 ? magicLineIndex : cell.contentStartLine);
+        const after = lines.slice(cell.contentEndLine + 1);
+        return [...before, ...newLines, ...after].join(LINE_ENDING);
     }
     else {
-        newLines = formattedContent.split(/\r?\n/);
+        newLines = cell.isMagicCell
+            ? addMagicPrefix(formattedContent, config)
+            : formattedContent.split(/\r?\n/);
+        const before = lines.slice(0, cell.contentStartLine);
+        const after = lines.slice(cell.contentEndLine + 1);
+        return [...before, ...newLines, ...after].join(LINE_ENDING);
     }
-    const before = lines.slice(0, cell.contentStartLine);
-    const after = lines.slice(cell.contentEndLine + 1);
-    return [...before, ...newLines, ...after].join(LINE_ENDING);
 }
 /**
  * Format all cells in a Fabric notebook.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacobknightley/fabric-format",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "A fast, opinionated formatter for Microsoft Fabric notebooks with Spark SQL and Python support",
   "main": "dist/index.js",