@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/compile/dependency-analysis.js

@@ -0,0 +1,432 @@
+/**
+ * Dependency Graph for Formula Calculation
+ *
+ * Builds a dependency graph from compiled formulas' static dependencies,
+ * then produces a topological evaluation order with circular reference
+ * detection.
+ *
+ * Key exports:
+ * - `buildDependencyGraphFromDeps()` — build graph from CompiledFormula static deps
+ * - `topologicalSort()` — produce evaluation order, detecting circular refs
+ */
+// ============================================================================
+// Cell Key Helpers
+// ============================================================================
+function makeKey(sheet, row, col) {
+    return `${sheet}!${row}:${col}`;
+}
+// ============================================================================
+// Dependency Reference → Cell Key Expansion
+// ============================================================================
+/**
+ * Type guard: is this a range reference (has `top` property)?
+ */
+function isRange(ref) {
+    return "top" in ref;
+}
+/**
+ * Expand a set of DepRefs into concrete cell keys.
+ * For single-cell refs, the key is produced directly.
+ * For range refs, we check which formula cells fall within the range rather
+ * than enumerating every cell (which would be prohibitively expensive for
+ * whole-column ranges like A:A).
+ */
+function expandRefsToKeys(refs, formulaKeySet, formulaCellCoordsBySheet) {
+    const keys = new Set();
+    for (const ref of refs) {
+        if (isRange(ref)) {
+            const rangeSize = (ref.bottom - ref.top + 1) * (ref.right - ref.left + 1);
+            if (rangeSize <= 10000) {
+                // Small-to-medium range: enumerate every cell
+                for (let r = ref.top; r <= ref.bottom; r++) {
+                    for (let c = ref.left; c <= ref.right; c++) {
+                        keys.add(makeKey(ref.sheet, r, c));
+                    }
+                }
+            }
+            else {
+                // Large range (e.g. whole column A:A): scan formula cells in the
+                // referenced sheet only and check containment.
+                const sheetCoords = formulaCellCoordsBySheet.get(ref.sheet);
+                if (sheetCoords) {
+                    for (const [fKey, coord] of sheetCoords) {
+                        if (coord.row >= ref.top &&
+                            coord.row <= ref.bottom &&
+                            coord.col >= ref.left &&
+                            coord.col <= ref.right) {
+                            keys.add(fKey);
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            // Single cell — always add
+            keys.add(makeKey(ref.sheet, ref.row, ref.col));
+        }
+    }
+    return keys;
+}
+// ============================================================================
+// Build Dependency Graph from CompiledFormula StaticDeps
+// ============================================================================
+/**
+ * Build a dependency graph from compiled formulas' static dependencies.
+ *
+ * Operates on the already-resolved `StaticDependencySet` from each compiled
+ * formula. Since names and structured references are already resolved by
+ * the binder, the dependency edges are complete.
+ *
+ * @param compiled - Map from formula cell key to compiled formula with static deps
+ * @param producerMap - Optional map from cell key → formula key that produces
+ *   that cell's value (via CSE distribution or dynamic-array spill). Allows
+ *   dependency edges to be added to the producer even when the target cell
+ *   isn't itself a formula.
+ * @returns The complete dependency graph
+ */
+export function buildDependencyGraphFromDeps(compiled, producerMap) {
+    // Build a lookup of all formula cell coordinates for range intersection.
+    // We group by sheet so that large-range containment scans only visit the
+    // relevant sheet's formula cells instead of the entire workbook.
+    const formulaKeySet = new Set();
+    const formulaCellCoordsBySheet = new Map();
+    const formulaKeys = [];
+    for (const [key, cf] of compiled) {
+        formulaKeySet.add(key);
+        // Use the instance's already-known coordinates instead of reverse-parsing
+        // the key string — saves two lastIndexOf calls and two parseInt calls
+        // per formula on cold-start.
+        const inst = cf.instance;
+        const coord = { sheet: inst.sheetName, row: inst.row, col: inst.col };
+        let list = formulaCellCoordsBySheet.get(inst.sheetName);
+        if (!list) {
+            list = [];
+            formulaCellCoordsBySheet.set(inst.sheetName, list);
+        }
+        list.push([key, coord]);
+        formulaKeys.push(key);
+    }
+    // Forward edges: formula key → set of keys it depends on
+    const dependsOn = new Map();
+    // Reverse edges: cell key → set of formula keys that depend on it
+    const dependedBy = new Map();
+    for (const [key, cf] of compiled) {
+        const deps = cf.staticDeps;
+        // Convert StaticDependencySet to DepRef[]
+        const refs = [];
+        // Direct cell deps always pass through verbatim.
+        for (const cell of deps.cells) {
+            refs.push({ sheet: cell.sheet, row: cell.row, col: cell.col });
+        }
+        // Area deps normally expand into every cell in the range. For areas
+        // that start at a dynamic-array master (e.g. the `A1:A5` in
+        // `SUM(A1:A5)` where A1 is a live `=SEQUENCE(5)`), we replace the
+        // expansion with a single dependency on the master. Evaluator-time
+        // `getCellValue` then reads the master's cached array result for
+        // the ghost positions, so downstream formulas see the full spill
+        // in the same calc pass. Without this, A2..A5 aren't yet in the
+        // snapshot on the first run and the SUM only picks up A1.
+        const dynMasterDeps = [];
+        for (const area of deps.areas) {
+            const topLeftKey = makeKey(area.sheet, area.top, area.left);
+            const masterCf = compiled.get(topLeftKey);
+            const isDynMaster = masterCf !== undefined &&
+                (masterCf.instance.isDynamicArray || masterCf.isDynamicArrayFunction);
+            if (isDynMaster) {
+                dynMasterDeps.push(topLeftKey);
+                continue;
+            }
+            refs.push({
+                sheet: area.sheet,
+                top: area.top,
+                left: area.left,
+                bottom: area.bottom,
+                right: area.right
+            });
+        }
+        // Expand to concrete cell keys
+        const depKeys = expandRefsToKeys(refs, formulaKeySet, formulaCellCoordsBySheet);
+        for (const mk of dynMasterDeps) {
+            depKeys.add(mk);
+        }
+        // Remap producer keys: if a dep points to a cell that's not a formula
+        // but IS produced by another formula (CSE target or spill target),
+        // depend on the producer instead.
+        if (producerMap && producerMap.size > 0) {
+            const remapped = new Set();
+            for (const depKey of depKeys) {
+                if (!formulaKeySet.has(depKey)) {
+                    const producer = producerMap.get(depKey);
+                    if (producer) {
+                        remapped.add(producer);
+                        continue;
+                    }
+                }
+                remapped.add(depKey);
+            }
+            dependsOn.set(key, remapped);
+            for (const depKey of remapped) {
+                let set = dependedBy.get(depKey);
+                if (!set) {
+                    set = new Set();
+                    dependedBy.set(depKey, set);
+                }
+                set.add(key);
+            }
+            continue;
+        }
+        dependsOn.set(key, depKeys);
+        // Build reverse index
+        for (const depKey of depKeys) {
+            let set = dependedBy.get(depKey);
+            if (!set) {
+                set = new Set();
+                dependedBy.set(depKey, set);
+            }
+            set.add(key);
+        }
+    }
+    // Detect circular references
+    const { circularKeys } = detectCircularRefs(formulaKeys, dependsOn);
+    return {
+        dependsOn,
+        dependedBy,
+        formulaKeys,
+        circularKeys
+    };
+}
+// ============================================================================
+// Merge Runtime Dynamic Dependencies
+// ============================================================================
+/**
+ * Merge runtime-discovered dynamic dependencies into a dependency graph.
+ *
+ * After evaluating formulas that contain INDIRECT/OFFSET, the runtime
+ * dependency recorder has collected the actual cell accesses. This function
+ * incorporates those dynamic edges into the graph and re-detects cycles.
+ *
+ * Returns a new graph if edges were added, or the original graph if no
+ * dynamic deps were recorded.
+ */
+export function mergeDynamicDeps(graph, dynamicDeps) {
+    if (dynamicDeps.size === 0) {
+        return { graph, changed: false };
+    }
+    // First pass: detect whether any new edges would actually be added.
+    // Cloning the full dependsOn/dependedBy maps is expensive for large
+    // workbooks; skip it entirely when there's no real work to do.
+    let needsClone = false;
+    for (const [formulaKey, accessedKeys] of dynamicDeps) {
+        const existing = graph.dependsOn.get(formulaKey);
+        for (const k of accessedKeys) {
+            if (!existing || !existing.has(k)) {
+                needsClone = true;
+                break;
+            }
+        }
+        if (needsClone) {
+            break;
+        }
+    }
+    if (!needsClone) {
+        return { graph, changed: false };
+    }
+    // Clone forward and reverse edges
+    const newDependsOn = new Map();
+    for (const [k, v] of graph.dependsOn) {
+        newDependsOn.set(k, new Set(v));
+    }
+    const newDependedBy = new Map();
+    for (const [k, v] of graph.dependedBy) {
+        newDependedBy.set(k, new Set(v));
+    }
+    // Add dynamic edges
+    for (const [formulaKey, accessedKeys] of dynamicDeps) {
+        let deps = newDependsOn.get(formulaKey);
+        if (!deps) {
+            deps = new Set();
+            newDependsOn.set(formulaKey, deps);
+        }
+        for (const accessedKey of accessedKeys) {
+            if (!deps.has(accessedKey)) {
+                deps.add(accessedKey);
+                // Update reverse edge
+                let rev = newDependedBy.get(accessedKey);
+                if (!rev) {
+                    rev = new Set();
+                    newDependedBy.set(accessedKey, rev);
+                }
+                rev.add(formulaKey);
+            }
+        }
+    }
+    // Re-detect cycles with the augmented graph
+    const { circularKeys } = detectCircularRefs(graph.formulaKeys, newDependsOn);
+    return {
+        graph: {
+            dependsOn: newDependsOn,
+            dependedBy: newDependedBy,
+            formulaKeys: graph.formulaKeys,
+            circularKeys
+        },
+        changed: true
+    };
+}
+// ============================================================================
+// Circular Reference Detection
+// ============================================================================
+/**
+ * Detect circular references using Tarjan's SCC algorithm.
+ *
+ * A formula is "circular" if it belongs to a strongly connected component
+ * of size > 1, or if it has a direct self-loop (A = f(A)).
+ *
+ * This correctly identifies ALL nodes in cycles, including nodes reachable
+ * only through cross-edges to already-visited SCC members — a case that
+ * a simple 3-color DFS misses (e.g. diamond cycles like A→B→C→A plus A→D→C).
+ */
+function detectCircularRefs(formulaKeys, dependsOn) {
+    const circularKeys = new Set();
+    // Tarjan's iterative SCC
+    const index = new Map();
+    const lowlink = new Map();
+    const onStack = new Set();
+    const sccStack = [];
+    let nextIndex = 0;
+    for (const startKey of formulaKeys) {
+        if (index.has(startKey)) {
+            continue;
+        }
+        const dfsStack = [];
+        index.set(startKey, nextIndex);
+        lowlink.set(startKey, nextIndex);
+        nextIndex++;
+        sccStack.push(startKey);
+        onStack.add(startKey);
+        dfsStack.push({
+            key: startKey,
+            iter: (dependsOn.get(startKey) ?? new Set())[Symbol.iterator](),
+            pendingChild: null
+        });
+        while (dfsStack.length > 0) {
+            const frame = dfsStack[dfsStack.length - 1];
+            // If we just returned from a child, update our lowlink
+            if (frame.pendingChild !== null) {
+                const childLow = lowlink.get(frame.pendingChild);
+                lowlink.set(frame.key, Math.min(lowlink.get(frame.key), childLow));
+                frame.pendingChild = null;
+            }
+            const next = frame.iter.next();
+            if (next.done) {
+                // Finished processing all children — check if this is an SCC root
+                if (lowlink.get(frame.key) === index.get(frame.key)) {
+                    const scc = [];
+                    let node;
+                    do {
+                        node = sccStack.pop();
+                        onStack.delete(node);
+                        scc.push(node);
+                    } while (node !== frame.key);
+                    // Mark as circular if SCC has > 1 node, OR if it's a self-loop
+                    const hasSelfLoop = scc.length === 1 && dependsOn.get(scc[0])?.has(scc[0]);
+                    if (scc.length > 1 || hasSelfLoop) {
+                        for (const k of scc) {
+                            circularKeys.add(k);
+                        }
+                    }
+                }
+                dfsStack.pop();
+                // Record returning to parent so it can update its lowlink
+                if (dfsStack.length > 0) {
+                    dfsStack[dfsStack.length - 1].pendingChild = frame.key;
+                }
+                continue;
+            }
+            const depKey = next.value;
+            if (!index.has(depKey)) {
+                // Unvisited — push new frame
+                index.set(depKey, nextIndex);
+                lowlink.set(depKey, nextIndex);
+                nextIndex++;
+                sccStack.push(depKey);
+                onStack.add(depKey);
+                dfsStack.push({
+                    key: depKey,
+                    iter: (dependsOn.get(depKey) ?? new Set())[Symbol.iterator](),
+                    pendingChild: null
+                });
+            }
+            else if (onStack.has(depKey)) {
+                // Back edge — update lowlink with dep's index
+                lowlink.set(frame.key, Math.min(lowlink.get(frame.key), index.get(depKey)));
+            }
+            // Cross edge to fully-processed SCC: skip (correct Tarjan behavior)
+        }
+    }
+    return { circularKeys };
+}
+// ============================================================================
+// Topological Sort (Kahn's Algorithm)
+// ============================================================================
+/**
+ * Produce a topological evaluation order for formula cells using Kahn's algorithm.
+ * Cells with no dependencies are evaluated first. Circular references are
+ * appended at the end in their original order.
+ */
+export function topologicalSort(graph) {
+    const { formulaKeys, dependsOn, circularKeys } = graph;
+    const formulaKeySet = new Set(formulaKeys);
+    const inDegree = new Map();
+    for (const key of formulaKeys) {
+        if (circularKeys.has(key)) {
+            continue;
+        }
+        const deps = dependsOn.get(key);
+        if (!deps) {
+            inDegree.set(key, 0);
+            continue;
+        }
+        let count = 0;
+        for (const depKey of deps) {
+            if (formulaKeySet.has(depKey) && !circularKeys.has(depKey)) {
+                count++;
+            }
+        }
+        inDegree.set(key, count);
+    }
+    const queue = [];
+    for (const key of formulaKeys) {
+        if (circularKeys.has(key)) {
+            continue;
+        }
+        if ((inDegree.get(key) ?? 0) === 0) {
+            queue.push(key);
+        }
+    }
+    const sorted = [];
+    let head = 0;
+    while (head < queue.length) {
+        const key = queue[head++];
+        sorted.push(key);
+        const dependents = graph.dependedBy.get(key);
+        if (dependents) {
+            for (const depKey of dependents) {
+                if (circularKeys.has(depKey) || !formulaKeySet.has(depKey)) {
+                    continue;
+                }
+                const deg = (inDegree.get(depKey) ?? 1) - 1;
+                inDegree.set(depKey, deg);
+                if (deg === 0) {
+                    queue.push(depKey);
+                }
+            }
+        }
+    }
+    // Append circular reference cells at the end in original order
+    for (const key of formulaKeys) {
+        if (circularKeys.has(key)) {
+            sorted.push(key);
+        }
+    }
+    return sorted;
+}

package/dist/browser/modules/formula/compile/structured-ref-utils.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared utilities for structured reference (table) row-range resolution.
+ *
+ * The row-range logic for structured references is needed in three places:
+ * - binder (compile-time range resolution)
+ * - compiled-formula (static dependency extraction)
+ * - evaluator (runtime evaluation)
+ *
+ * This module provides the canonical implementation to avoid triplication.
+ */
+/**
+ * Minimum subset of table snapshot fields required to derive geometry
+ * and resolve structured-reference columns.
+ *
+ * Declared structurally (not as a nominal import of `TableSnapshot`) so
+ * this module stays dependency-free and can serve both compile- and
+ * runtime-side callers that carry their own table-shape types.
+ */
+export interface TableLike {
+    readonly topLeft: {
+        readonly row: number;
+        readonly col: number;
+    };
+    readonly dataRowCount: number;
+    readonly hasHeaderRow: boolean;
+    readonly hasTotalsRow: boolean;
+    readonly columns: readonly {
+        readonly name: string;
+    }[];
+}
+/**
+ * Table geometry needed for structured ref resolution.
+ */
+export interface TableGeometry {
+    /** Top-left row of the table (including header if present). */
+    readonly topLeftRow: number;
+    /** First row of the data body. */
+    readonly dataRowStart: number;
+    /** Last row of the data body. */
+    readonly dataRowEnd: number;
+    /** Whether the table has a header row. */
+    readonly hasHeaderRow: boolean;
+    /** Whether the table has a totals row. */
+    readonly hasTotalsRow: boolean;
+}
+/**
+ * Derive `TableGeometry` from a table's snapshot fields.
+ *
+ * The data row range excludes the header (if any) but also excludes the
+ * totals row — totals, when present, occupy `dataRowEnd + 1`.
+ */
+export declare function buildTableGeometry(table: TableLike): TableGeometry;
+/**
+ * Resolve a list of structured-reference column names to a contiguous
+ * column range `[colLeft, colRight]` in absolute sheet coordinates.
+ *
+ * @param columns - Requested column names (case-insensitive match).
+ * @param table - Table whose columns are searched.
+ * @param mode -
+ *   - `"strict"` — return `"error"` if any name is missing (used by
+ *     binder and evaluator — unknown columns are `#REF!` errors).
+ *   - `"permissive"` — ignore missing names; if ALL names are missing,
+ *     falls back to the full table width (used by static-deps extraction,
+ *     where a conservative over-estimate is acceptable).
+ * @returns `{ colLeft, colRight }`, or `"error"` in strict mode when a
+ *   column name is not found. If `columns` is empty, returns the full
+ *   table width.
+ */
+export declare function resolveStructuredRefColumns(columns: readonly string[], table: TableLike, mode: "strict" | "permissive"): {
+    colLeft: number;
+    colRight: number;
+} | "error";
+/**
+ * Result of resolving structured reference specials to a row range.
+ *
+ * - `{rowTop, rowBottom}` — resolved range
+ * - `"thisRow"` — the `#This Row` special was used; caller must resolve
+ *   using the current cell address
+ * - `"error"` — invalid special combination (e.g., #Totals on a table
+ *   without a totals row)
+ */
+export type StructuredRefRowRange = {
+    rowTop: number;
+    rowBottom: number;
+} | "thisRow" | "error";
+/**
+ * Resolve structured reference specials to a row range.
+ *
+ * This is the single source of truth for the mapping from
+ * `#All`, `#Headers`, `#Data`, `#Totals`, `#This Row` (and their
+ * combinations) to concrete row numbers.
+ */
+export declare function resolveStructuredRefRows(specials: readonly string[], geo: TableGeometry): StructuredRefRowRange;

package/dist/browser/modules/formula/compile/structured-ref-utils.js

@@ -0,0 +1,136 @@
+/**
+ * Shared utilities for structured reference (table) row-range resolution.
+ *
+ * The row-range logic for structured references is needed in three places:
+ * - binder (compile-time range resolution)
+ * - compiled-formula (static dependency extraction)
+ * - evaluator (runtime evaluation)
+ *
+ * This module provides the canonical implementation to avoid triplication.
+ */
+/**
+ * Derive `TableGeometry` from a table's snapshot fields.
+ *
+ * The data row range excludes the header (if any) but also excludes the
+ * totals row — totals, when present, occupy `dataRowEnd + 1`.
+ */
+export function buildTableGeometry(table) {
+    const topLeftRow = table.topLeft.row;
+    const dataRowStart = topLeftRow + (table.hasHeaderRow ? 1 : 0);
+    const dataRowEnd = dataRowStart + table.dataRowCount - 1;
+    return {
+        topLeftRow,
+        dataRowStart,
+        dataRowEnd,
+        hasHeaderRow: table.hasHeaderRow,
+        hasTotalsRow: table.hasTotalsRow
+    };
+}
+/**
+ * Resolve a list of structured-reference column names to a contiguous
+ * column range `[colLeft, colRight]` in absolute sheet coordinates.
+ *
+ * @param columns - Requested column names (case-insensitive match).
+ * @param table - Table whose columns are searched.
+ * @param mode -
+ *   - `"strict"` — return `"error"` if any name is missing (used by
+ *     binder and evaluator — unknown columns are `#REF!` errors).
+ *   - `"permissive"` — ignore missing names; if ALL names are missing,
+ *     falls back to the full table width (used by static-deps extraction,
+ *     where a conservative over-estimate is acceptable).
+ * @returns `{ colLeft, colRight }`, or `"error"` in strict mode when a
+ *   column name is not found. If `columns` is empty, returns the full
+ *   table width.
+ */
+export function resolveStructuredRefColumns(columns, table, mode) {
+    const tl = table.topLeft;
+    const width = table.columns.length;
+    if (columns.length === 0) {
+        return { colLeft: tl.col, colRight: tl.col + width - 1 };
+    }
+    const indices = [];
+    for (const colName of columns) {
+        const idx = table.columns.findIndex(c => c.name.toLowerCase() === colName.toLowerCase());
+        if (idx === -1) {
+            if (mode === "strict") {
+                return "error";
+            }
+            continue;
+        }
+        indices.push(idx);
+    }
+    if (indices.length === 0) {
+        // permissive + all names missing → conservative full-width fallback
+        return { colLeft: tl.col, colRight: tl.col + width - 1 };
+    }
+    return {
+        colLeft: tl.col + Math.min(...indices),
+        colRight: tl.col + Math.max(...indices)
+    };
+}
+/**
+ * Resolve structured reference specials to a row range.
+ *
+ * This is the single source of truth for the mapping from
+ * `#All`, `#Headers`, `#Data`, `#Totals`, `#This Row` (and their
+ * combinations) to concrete row numbers.
+ */
+export function resolveStructuredRefRows(specials, geo) {
+    // Tokenizer stashes unknown `[#Something]` tokens with a sentinel
+    // prefix. Surface them as errors rather than let them alias to the
+    // default-data-range path below.
+    for (const s of specials) {
+        if (s.startsWith("#__INVALID__")) {
+            return "error";
+        }
+    }
+    const hasAll = specials.includes("#All");
+    const hasHeaders = specials.includes("#Headers");
+    const hasTotals = specials.includes("#Totals");
+    const hasData = specials.includes("#Data");
+    const hasThisRow = specials.includes("#This Row");
+    if (hasAll) {
+        return {
+            rowTop: geo.topLeftRow,
+            rowBottom: geo.hasTotalsRow ? geo.dataRowEnd + 1 : geo.dataRowEnd
+        };
+    }
+    if (hasThisRow) {
+        return "thisRow";
+    }
+    if (hasHeaders && hasTotals) {
+        return {
+            rowTop: geo.topLeftRow,
+            rowBottom: geo.hasTotalsRow ? geo.dataRowEnd + 1 : geo.dataRowEnd
+        };
+    }
+    if (hasHeaders && hasData) {
+        return {
+            rowTop: geo.hasHeaderRow ? geo.topLeftRow : geo.dataRowStart,
+            rowBottom: geo.dataRowEnd
+        };
+    }
+    if (hasData && hasTotals) {
+        return {
+            rowTop: geo.dataRowStart,
+            rowBottom: geo.hasTotalsRow ? geo.dataRowEnd + 1 : geo.dataRowEnd
+        };
+    }
+    if (hasHeaders) {
+        if (geo.hasHeaderRow) {
+            return { rowTop: geo.topLeftRow, rowBottom: geo.topLeftRow };
+        }
+        // Table without a header row: Excel reports #REF! rather than silently
+        // aliasing to the first data row. Returning the data row here would
+        // route `Table1[#Headers]` to real data values, masking user mistakes.
+        return "error";
+    }
+    if (hasTotals) {
+        if (geo.hasTotalsRow) {
+            return { rowTop: geo.dataRowEnd + 1, rowBottom: geo.dataRowEnd + 1 };
+        }
+        return "error";
+    }
+    // #Data or no specials → data range
+    return { rowTop: geo.dataRowStart, rowBottom: geo.dataRowEnd };
+}