@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/cjs/modules/formula/materialize/build-writeback-plan.js

@@ -0,0 +1,475 @@
+"use strict";
+/**
+ * Build Writeback Plan — Convert evaluation results into a WritebackPlan.
+ *
+ * This module takes the evaluation results from the evaluator and
+ * produces a declarative `WritebackPlan` that describes all cell mutations.
+ * The plan is then applied by `apply-writeback-plan.ts`.
+ *
+ * ## Responsibilities
+ *
+ * 1. Classify each formula's result as scalar, CSE, or dynamic-array.
+ * 2. Check spill availability and detect #SPILL! conflicts.
+ * 3. Generate cleanup operations for stale ghost cells.
+ * 4. Track spill regions and ghost snapshots for persistence.
+ *
+ * ## Key Principle
+ *
+ * This module does NOT touch any live workbook objects. It reads only
+ * from the `WorkbookSnapshot` and the evaluation results.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWritebackPlan = buildWritebackPlan;
+const address_utils_1 = require("../compile/address-utils");
+const workbook_snapshot_1 = require("../integration/workbook-snapshot");
+// ============================================================================
+// Build Writeback Plan
+// ============================================================================
+/**
+ * Build a complete `WritebackPlan` from evaluation results.
+ *
+ * @param snapshot - The workbook snapshot
+ * @param compiled - All compiled formulas in evaluation order
+ * @param results - Raw evaluation results, keyed by formula cell key
+ * @param previousSpills - Persistent spill regions from previous calculation
+ * @param previousGhosts - Persistent ghost snapshots from previous calculation
+ */
+function buildWritebackPlan(snapshot, compiled, results, previousSpills, previousGhosts) {
+    const operations = [];
+    const spillRegions = new Map();
+    const ghostSnapshots = new Map();
+    const removedSpillKeys = [];
+    // Target cells already claimed by a spill produced EARLIER in this
+    // calc pass. Without this set, two dynamic-array formulas whose spill
+    // regions overlap would each pass the availability check against the
+    // immutable snapshot and then silently clobber each other during
+    // apply. See R5-P0-6.
+    const activeSpillTargets = new Set();
+    // Build a set of current formula cell keys (using worksheet-id-based keys)
+    const formulaKeys = new Set();
+    for (const cf of compiled) {
+        formulaKeys.add((0, workbook_snapshot_1.spillCellKeyFromId)(cf.instance.sheetId, cf.instance.row, cf.instance.col));
+    }
+    // Build ghost map from previous spills (validated against snapshot)
+    const ghostMap = new Map();
+    for (const [srcKey, region] of previousSpills) {
+        for (let r = 0; r < region.rows; r++) {
+            for (let c = 0; c < region.cols; c++) {
+                if (r === 0 && c === 0) {
+                    continue;
+                }
+                const targetRow = region.sourceRow + r;
+                const targetCol = region.sourceCol + c;
+                const targetKey = (0, workbook_snapshot_1.spillCellKeyFromId)(region.worksheetId, targetRow, targetCol);
+                // Validate ghost cell is still unmodified
+                const ws = snapshot.worksheetsById.get(region.worksheetId);
+                if (ws) {
+                    const cell = ws.cells.get((0, workbook_snapshot_1.snapshotCellKey)(targetRow, targetCol));
+                    if (isGhostUnmodified(cell, targetKey, previousGhosts)) {
+                        ghostMap.set(targetKey, srcKey);
+                    }
+                }
+            }
+        }
+    }
+    // Clean up stale spill regions (source formula no longer exists)
+    for (const [srcKey, region] of previousSpills) {
+        if (!formulaKeys.has(srcKey)) {
+            const ws = snapshot.worksheetsById.get(region.worksheetId);
+            if (ws) {
+                emitPreviousSpillCleanup(region, previousGhosts, snapshot, operations, ws.name, region.worksheetId);
+            }
+            removedSpillKeys.push(srcKey);
+        }
+    }
+    // Process each compiled formula's result
+    for (const cf of compiled) {
+        const inst = cf.instance;
+        const fKey = (0, workbook_snapshot_1.formulaCellKey)(inst.sheetName, inst.row, inst.col);
+        const result = results.get(fKey);
+        if (result === undefined) {
+            continue;
+        }
+        const isCSE = inst.kind === "cse" && inst.targetRef;
+        const isDynamic = inst.isDynamicArray || cf.isDynamicArrayFunction;
+        if (isCSE) {
+            // CSE array formula
+            const op = buildCSEWrite(inst, result);
+            if (op) {
+                operations.push(op);
+            }
+        }
+        else if (isDynamic &&
+            result.kind === 5 /* RVKind.Array */ &&
+            (result.height > 1 || result.width > 1)) {
+            // Dynamic array formula with array result
+            const srcKey = (0, workbook_snapshot_1.spillCellKeyFromId)(inst.sheetId, inst.row, inst.col);
+            // Check spill availability
+            const spillResult = buildSpillWrite(inst, result, srcKey, ghostMap, previousSpills.get(srcKey), previousGhosts, snapshot, spillRegions, ghostSnapshots, operations, activeSpillTargets);
+            if (spillResult === "error") {
+                operations.push({
+                    type: "spill-error",
+                    sheetName: inst.sheetName,
+                    sheetId: inst.sheetId,
+                    row: inst.row,
+                    col: inst.col
+                });
+            }
+        }
+        else {
+            // Scalar result (or 1x1 array)
+            const scalar = scalarFromResult(result);
+            // If this formula previously had a spill region, clean it up
+            const srcKey = (0, workbook_snapshot_1.spillCellKeyFromId)(inst.sheetId, inst.row, inst.col);
+            const prevRegion = previousSpills.get(srcKey);
+            if (prevRegion) {
+                emitPreviousSpillCleanup(prevRegion, previousGhosts, snapshot, operations, inst.sheetName, inst.sheetId);
+                removedSpillKeys.push(srcKey);
+            }
+            if (shouldPreserve(scalar, inst, snapshot)) {
+                operations.push({
+                    type: "preserve",
+                    sheetName: inst.sheetName,
+                    row: inst.row,
+                    col: inst.col
+                });
+            }
+            else {
+                operations.push({
+                    type: "scalar",
+                    sheetName: inst.sheetName,
+                    row: inst.row,
+                    col: inst.col,
+                    value: runtimeToSnapshotValue(scalar)
+                });
+            }
+        }
+    }
+    return {
+        operations,
+        spillState: {
+            spillRegions,
+            ghostSnapshots,
+            removedSpillKeys
+        }
+    };
+}
+// ============================================================================
+// CSE Write
+// ============================================================================
+function buildCSEWrite(inst, result) {
+    const ref = inst.targetRef;
+    if (!ref) {
+        return null;
+    }
+    const range = (0, address_utils_1.parseRefRange)(ref);
+    if (!range) {
+        return null;
+    }
+    if (result.kind === 5 /* RVKind.Array */) {
+        const results = [];
+        const numRows = range.bottom - range.top + 1;
+        const numCols = range.right - range.left + 1;
+        for (let r = 0; r < numRows; r++) {
+            const row = [];
+            for (let c = 0; c < numCols; c++) {
+                // When the array result is smaller than the CSE target range,
+                // positions outside the array get #N/A (Excel behaviour) — not
+                // BLANK, which is what the previous `?? { kind: Blank }` gave
+                // us. R6-P1-3.
+                const inBounds = r < result.height && c < result.width;
+                const val = inBounds
+                    ? result.rows[r][c]
+                    : { kind: 4 /* RVKind.Error */, code: "#N/A" };
+                row.push(runtimeToSnapshotValue(val));
+            }
+            results.push(row);
+        }
+        return {
+            type: "cse",
+            sheetName: inst.sheetName,
+            top: range.top,
+            left: range.left,
+            bottom: range.bottom,
+            right: range.right,
+            results
+        };
+    }
+    // Scalar fill
+    const scalarVal = runtimeToSnapshotValue(scalarFromResult(result));
+    return {
+        type: "cse",
+        sheetName: inst.sheetName,
+        top: range.top,
+        left: range.left,
+        bottom: range.bottom,
+        right: range.right,
+        results: [],
+        scalarFill: scalarVal
+    };
+}
+// ============================================================================
+// Spill Write
+// ============================================================================
+function buildSpillWrite(inst, arr, srcKey, ghostMap, previousRegion, previousGhosts, snapshot, spillRegions, ghostSnapshotsOut, operations, 
+/**
+ * Target cell keys claimed by spill regions produced EARLIER in this
+ * same calc pass. The snapshot is immutable during a pass, so without
+ * an explicit set the availability check wouldn't see the A1→A1:A5
+ * spill that the previous iteration just committed, and a subsequent
+ * formula spilling over A3:A7 would silently overwrite half of it.
+ */
+activeSpillTargets) {
+    const ws = snapshot.worksheetsByName.get(inst.sheetName.toLowerCase());
+    if (!ws) {
+        return "error";
+    }
+    // 1x1 result: just write scalar, no spilling
+    if (arr.height <= 1 && arr.width <= 1) {
+        const val = arr.height > 0 && arr.width > 0 ? arr.rows[0][0] : { kind: 0 /* RVKind.Blank */ };
+        operations.push({
+            type: "scalar",
+            sheetName: inst.sheetName,
+            row: inst.row,
+            col: inst.col,
+            value: runtimeToSnapshotValue(val)
+        });
+        // Clean up previous spill if any
+        if (previousRegion) {
+            emitPreviousSpillCleanup(previousRegion, previousGhosts, snapshot, operations, inst.sheetName, inst.sheetId);
+        }
+        return "ok";
+    }
+    // Reject if the spill region would extend past the sheet's maximum
+    // dimensions (1048576 rows x 16384 columns) — Excel reports #SPILL! here.
+    if (inst.row + arr.height - 1 > 1048576 || inst.col + arr.width - 1 > 16384) {
+        return "error";
+    }
+    // Check spill availability: verify all target ghost cells are unoccupied
+    for (let r = 0; r < arr.height; r++) {
+        for (let c = 0; c < arr.width; c++) {
+            if (r === 0 && c === 0) {
+                continue; // Source cell is always available
+            }
+            const targetRow = inst.row + r;
+            const targetCol = inst.col + c;
+            const targetKey = (0, workbook_snapshot_1.spillCellKeyFromId)(inst.sheetId, targetRow, targetCol);
+            // Another spill in this calc pass already claimed this cell —
+            // report #SPILL! rather than silently overwrite.
+            if (activeSpillTargets.has(targetKey)) {
+                return "error";
+            }
+            // Check if the cell is a ghost from ANY previous spill.
+            // If the user hasn't modified it, it's safe to overwrite — the
+            // originating formula will clean it up (or we'll overwrite it).
+            if (ghostMap.has(targetKey)) {
+                const cell = ws.cells.get((0, workbook_snapshot_1.snapshotCellKey)(targetRow, targetCol));
+                if (!isGhostUnmodified(cell, targetKey, previousGhosts)) {
+                    return "error"; // User wrote into a ghost → #SPILL!
+                }
+                continue;
+            }
+            // Check if the cell is occupied by another formula or has a value
+            const cell = ws.cells.get((0, workbook_snapshot_1.snapshotCellKey)(targetRow, targetCol));
+            if (cell && cell.value !== null && cell.formulaKind === "none") {
+                // Non-empty, non-formula cell → blocked
+                return "error";
+            }
+            if (cell && cell.formulaKind !== "none") {
+                // Formula cell → blocked (not our ghost)
+                return "error";
+            }
+        }
+    }
+    // Now that availability is confirmed, claim the target cells so the
+    // next spill in this pass sees them as occupied.
+    for (let r = 0; r < arr.height; r++) {
+        for (let c = 0; c < arr.width; c++) {
+            if (r === 0 && c === 0) {
+                continue;
+            }
+            const targetRow = inst.row + r;
+            const targetCol = inst.col + c;
+            activeSpillTargets.add((0, workbook_snapshot_1.spillCellKeyFromId)(inst.sheetId, targetRow, targetCol));
+        }
+    }
+    // Clean up previous spill region if size changed
+    if (previousRegion) {
+        emitPreviousSpillCleanup(previousRegion, previousGhosts, snapshot, operations, inst.sheetName, inst.sheetId);
+    }
+    // Build spill write operation
+    const results = [];
+    for (let r = 0; r < arr.height; r++) {
+        const row = [];
+        for (let c = 0; c < arr.width; c++) {
+            const val = arr.rows[r]?.[c] ?? { kind: 0 /* RVKind.Blank */ };
+            const sv = runtimeToSnapshotValue(val);
+            row.push(sv);
+            // Record ghost snapshot
+            if (r !== 0 || c !== 0) {
+                const targetKey = (0, workbook_snapshot_1.spillCellKeyFromId)(inst.sheetId, inst.row + r, inst.col + c);
+                ghostSnapshotsOut.set(targetKey, sv);
+            }
+        }
+        results.push(row);
+    }
+    operations.push({
+        type: "spill",
+        sheetName: inst.sheetName,
+        sheetId: inst.sheetId,
+        row: inst.row,
+        col: inst.col,
+        results
+    });
+    // Record spill region
+    spillRegions.set(srcKey, {
+        worksheetId: inst.sheetId,
+        sourceRow: inst.row,
+        sourceCol: inst.col,
+        rows: arr.height,
+        cols: arr.width
+    });
+    return "ok";
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function collectStaleGhosts(region, previousGhosts, snapshot) {
+    const cells = [];
+    const ws = snapshot.worksheetsById.get(region.worksheetId);
+    if (!ws) {
+        return cells;
+    }
+    for (let r = 0; r < region.rows; r++) {
+        for (let c = 0; c < region.cols; c++) {
+            if (r === 0 && c === 0) {
+                continue;
+            }
+            const targetRow = region.sourceRow + r;
+            const targetCol = region.sourceCol + c;
+            const targetKey = (0, workbook_snapshot_1.spillCellKeyFromId)(region.worksheetId, targetRow, targetCol);
+            const cell = ws.cells.get((0, workbook_snapshot_1.snapshotCellKey)(targetRow, targetCol));
+            if (isGhostUnmodified(cell, targetKey, previousGhosts)) {
+                cells.push({ row: targetRow, col: targetCol });
+            }
+        }
+    }
+    return cells;
+}
+/**
+ * Emit a cleanup operation for a previous spill region whose ghosts are
+ * still unmodified.
+ *
+ * Collects the stale ghost cells and, if any remain, pushes a single
+ * `CleanupWrite` onto `operations`. The caller is responsible for
+ * updating `removedSpillKeys` / `spillRegions` as appropriate for its
+ * situation (this helper deliberately does not touch them since the
+ * three callsites have slightly different follow-up actions).
+ */
+function emitPreviousSpillCleanup(previousRegion, previousGhosts, snapshot, operations, sheetName, sheetId) {
+    const cleanupCells = collectStaleGhosts(previousRegion, previousGhosts, snapshot);
+    if (cleanupCells.length === 0) {
+        return;
+    }
+    operations.push({
+        type: "cleanup",
+        sheetName,
+        sheetId,
+        cells: cleanupCells
+    });
+}
+function isGhostUnmodified(cell, ghostKey, previousGhosts) {
+    if (!cell) {
+        return true;
+    }
+    if (cell.value === null) {
+        return true;
+    }
+    if (cell.formulaKind !== "none") {
+        return false;
+    }
+    const snapshot = previousGhosts.get(ghostKey);
+    if (snapshot === undefined) {
+        return true; // No snapshot — assume unmodified (conservative)
+    }
+    return snapshotValuesEqual(cell.value, snapshot);
+}
+/**
+ * Structural comparison for snapshot values.
+ * Handles error objects (which are reference types and fail `===` comparison)
+ * as well as primitives.
+ */
+function snapshotValuesEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    // Both are error objects — compare by error code
+    if (a !== null &&
+        typeof a === "object" &&
+        "error" in a &&
+        b !== null &&
+        typeof b === "object" &&
+        "error" in b) {
+        return a.error === b.error;
+    }
+    return false;
+}
+function scalarFromResult(v) {
+    if (v.kind === 5 /* RVKind.Array */) {
+        if (v.height > 0 && v.width > 0) {
+            return v.rows[0][0];
+        }
+        return { kind: 0 /* RVKind.Blank */ };
+    }
+    if (v.kind === 0 /* RVKind.Blank */ ||
+        v.kind === 1 /* RVKind.Number */ ||
+        v.kind === 2 /* RVKind.String */ ||
+        v.kind === 3 /* RVKind.Boolean */ ||
+        v.kind === 4 /* RVKind.Error */) {
+        return v;
+    }
+    return { kind: 0 /* RVKind.Blank */ };
+}
+function runtimeToSnapshotValue(v) {
+    switch (v.kind) {
+        case 0 /* RVKind.Blank */:
+            return null;
+        case 1 /* RVKind.Number */:
+            // Boundary guard: never let NaN or ±Infinity leak into the
+            // persisted workbook. Either comes from arithmetic the per-
+            // function guards missed (for example extreme ROUND digit
+            // counts before the R6-P1-2 clamp). Convert to #NUM! here so
+            // downstream readers see a clean error instead of a stringified
+            // "NaN" / "Infinity" value. See R6 architectural note.
+            if (!Number.isFinite(v.value)) {
+                return { error: "#NUM!" };
+            }
+            return v.value;
+        case 2 /* RVKind.String */:
+            return v.value;
+        case 3 /* RVKind.Boolean */:
+            return v.value;
+        case 4 /* RVKind.Error */:
+            return { error: v.code };
+        case 5 /* RVKind.Array */:
+            // Take top-left
+            if (v.height > 0 && v.width > 0) {
+                return runtimeToSnapshotValue(v.rows[0][0]);
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+function shouldPreserve(computed, inst, snapshot) {
+    if (computed.kind !== 4 /* RVKind.Error */ || computed.code !== "#NAME?") {
+        return false;
+    }
+    // Check if cell has a cached result in the snapshot
+    const ws = snapshot.worksheetsByName.get(inst.sheetName.toLowerCase());
+    if (!ws) {
+        return false;
+    }
+    const cell = ws.cells.get((0, workbook_snapshot_1.snapshotCellKey)(inst.row, inst.col));
+    return cell?.cachedResult !== undefined && cell.cachedResult !== null;
+}

package/dist/cjs/modules/formula/materialize/spill-engine.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Spill Engine — Persistent state management for dynamic array formulas.
+ *
+ * Manages persistent spill metadata that survives across
+ * `calculateFormulas()` invocations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPersistentSpillMap = getPersistentSpillMap;
+exports.getGhostSnapshots = getGhostSnapshots;
+// ============================================================================
+// Persistent State (WeakMap keyed by workbook — survives across invocations)
+// ============================================================================
+/**
+ * Persistent spill metadata: survives across calculateFormulas invocations.
+ * Key: "ws:<id>!row:col" of the source cell → SpillRegion.
+ * Stored in a WeakMap keyed by the workbook object to allow GC.
+ */
+const persistentSpillRegions = new WeakMap();
+function getPersistentSpillMap(workbook) {
+    let map = persistentSpillRegions.get(workbook);
+    if (!map) {
+        map = new Map();
+        persistentSpillRegions.set(workbook, map);
+    }
+    return map;
+}
+/**
+ * Persistent snapshot of values written to ghost (spill target) cells.
+ * Key: ghost cell key "ws:<id>!row:col" → raw value written by spill.
+ * Used to detect whether a ghost cell has been modified by the user since
+ * the last calculation.
+ */
+const persistentGhostSnapshots = new WeakMap();
+function getGhostSnapshots(workbook) {
+    let map = persistentGhostSnapshots.get(workbook);
+    if (!map) {
+        map = new Map();
+        persistentGhostSnapshots.set(workbook, map);
+    }
+    return map;
+}

package/dist/cjs/modules/formula/materialize/types.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Structural interfaces the formula engine consumes.
+ *
+ * The engine talks to these interfaces only — never to the concrete
+ * `Workbook` / `Worksheet` / `Cell` classes from the `excel` module. Any
+ * host that wants to drive the engine (including the Node/browser
+ * Workbook in `@excel/*`) must implement these shapes.
+ *
+ * This is what keeps the Layer 3 ↔ Layer 4 dependency one-way: the
+ * `excel` module imports from `formula`, never the reverse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CellValueTypeLike = void 0;
+// ============================================================================
+// ValueType — numeric mirror of `@excel/enums` ValueType
+// ============================================================================
+/**
+ * Numeric cell-type tag exposed by host cells. The engine only compares
+ * against `Null` and `Formula`; any other value is treated as a scalar
+ * literal.
+ *
+ * Kept as inline numeric literals (not an enum) so this file stays free
+ * of runtime dependencies. The `const` object and `type` alias share a
+ * name via TypeScript's declaration merging — the value form
+ * (`CellValueTypeLike.Null`, `CellValueTypeLike.Formula`) is used at
+ * comparison sites, the type form annotates `CellLike.type`.
+ */
+exports.CellValueTypeLike = {
+    Null: 0,
+    Formula: 6
+};

package/dist/cjs/modules/formula/materialize/writeback-plan.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Writeback Plan — Declarative description of formula calculation results.
+ *
+ * The engine never directly mutates workbook cells. Instead, it produces a
+ * `WritebackPlan` — a list of write operations that describe what values
+ * should be written where. A thin adapter layer then applies the plan to
+ * the live workbook.
+ *
+ * ## Design Principles
+ *
+ * 1. **Declarative** — the plan describes *what* to write, not *how*.
+ * 2. **Deterministic** — #SPILL! conflicts are detected during plan
+ *    construction, not during application.
+ * 3. **Ordered** — operations are applied in the order they appear.
+ * 4. **Independent** — each operation stands alone; the adapter does not
+ *    need engine internals to apply the plan.
+ *
+ * ## Operation Types
+ *
+ * - `ScalarWrite` — write a single value to a formula cell's result.
+ * - `CSEWrite` — distribute an array across a CSE formula's target range.
+ * - `SpillWrite` — write a dynamic array result to adjacent cells (spill).
+ * - `SpillErrorWrite` — write #SPILL! to the source cell (conflict detected).
+ * - `CleanupWrite` — clear stale ghost cells from a previous spill.
+ * - `PreserveWrite` — keep the cell's existing cached result (unsupported fn).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });