@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/formula/compile/compiled-formula.js

@@ -0,0 +1,383 @@
+/**
+ * Compiled Formula — The output of the full compilation pipeline.
+ *
+ * A `CompiledFormula` packages together:
+ * - The original `FormulaInstance` metadata
+ * - The bound expression tree (from the binder)
+ * - Static dependency information
+ * - Metadata flags (volatile, dynamic refs, etc.)
+ *
+ * ## Static Dependency Extraction
+ *
+ * Dependencies are extracted from the `BoundExpr` tree. Since names and
+ * structured refs are already resolved by the binder, the dependency
+ * extraction is a simple tree walk that collects `BoundCellRef` and
+ * `BoundAreaRef` nodes.
+ *
+ * Runtime-dependent references (INDIRECT, OFFSET) cannot be captured
+ * statically — the `hasDynamicRefs` flag marks formulas that may have
+ * additional runtime dependencies. Those functions re-parse their dynamic
+ * arguments at evaluation time using their own parser invocation (the raw
+ * AST is not retained on the CompiledFormula).
+ */
+import { NodeType } from "../syntax/ast.js";
+import { stripFunctionPrefix } from "../syntax/token-types.js";
+import { BoundExprKind } from "./bound-ast.js";
+import { resolveStructuredRefRows, buildTableGeometry, resolveStructuredRefColumns } from "./structured-ref-utils.js";
+/**
+ * Extract static dependencies from a bound expression tree.
+ *
+ * @param expr - The bound expression tree to analyze
+ * @param snapshot - Optional snapshot for resolving structured references
+ * @param nameResolver - Optional resolver for formula-based defined name dependencies
+ */
+export function extractStaticDeps(expr, snapshot, nameResolver) {
+    const cells = [];
+    const areas = [];
+    walkDeps(expr, cells, areas, snapshot?.tablesByName, nameResolver, new Set());
+    // Deduplicate — a formula like `=A1+A1+A1` would otherwise add three
+    // copies of A1 to the dep list, bloating both the dependency graph's
+    // intermediate storage and the `expandRefsToKeys` pass downstream. We
+    // use positional keys that mirror the Set<string> dedup logic that the
+    // graph builder already applies, so we can pay the cost here once
+    // instead of in every consumer. (R6 architectural note #5)
+    return { cells: dedupeCells(cells), areas: dedupeAreas(areas) };
+}
+function dedupeCells(cells) {
+    if (cells.length < 2) {
+        return cells;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const c of cells) {
+        const key = `${c.sheet}\u0000${c.row}\u0001${c.col}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+function dedupeAreas(areas) {
+    if (areas.length < 2) {
+        return areas;
+    }
+    const seen = new Set();
+    const out = [];
+    for (const a of areas) {
+        const key = `${a.sheet}\u0000${a.top}\u0001${a.left}\u0002${a.bottom}\u0003${a.right}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(a);
+    }
+    return out;
+}
+function walkDeps(expr, cells, areas, tablesByName, nameResolver, visitedNames) {
+    switch (expr.kind) {
+        case BoundExprKind.CellRef:
+            cells.push({ sheet: expr.sheet, row: expr.row, col: expr.col });
+            break;
+        case BoundExprKind.AreaRef:
+            areas.push({
+                sheet: expr.sheet,
+                top: expr.top,
+                left: expr.left,
+                bottom: expr.bottom,
+                right: expr.right
+            });
+            break;
+        case BoundExprKind.ColRangeRef:
+            areas.push({
+                sheet: expr.sheet,
+                top: 1,
+                left: expr.leftCol,
+                bottom: 1048576,
+                right: expr.rightCol
+            });
+            break;
+        case BoundExprKind.RowRangeRef:
+            areas.push({
+                sheet: expr.sheet,
+                top: expr.topRow,
+                left: 1,
+                bottom: expr.bottomRow,
+                right: 16384
+            });
+            break;
+        case BoundExprKind.Ref3D:
+            for (const sheet of expr.sheets) {
+                if (expr.inner.kind === BoundExprKind.CellRef) {
+                    cells.push({ sheet, row: expr.inner.row, col: expr.inner.col });
+                }
+                else {
+                    areas.push({
+                        sheet,
+                        top: expr.inner.top,
+                        left: expr.inner.left,
+                        bottom: expr.inner.bottom,
+                        right: expr.inner.right
+                    });
+                }
+            }
+            break;
+        case BoundExprKind.BinaryOp:
+            walkDeps(expr.left, cells, areas, tablesByName, nameResolver, visitedNames);
+            walkDeps(expr.right, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case BoundExprKind.UnaryOp:
+            walkDeps(expr.operand, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case BoundExprKind.Percent:
+            walkDeps(expr.operand, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case BoundExprKind.Call:
+            for (const arg of expr.args) {
+                walkDeps(arg, cells, areas, tablesByName, nameResolver, visitedNames);
+            }
+            break;
+        case BoundExprKind.SpecialCall:
+            for (const arg of expr.args) {
+                walkDeps(arg, cells, areas, tablesByName, nameResolver, visitedNames);
+            }
+            break;
+        case BoundExprKind.Array:
+            for (const row of expr.rows) {
+                for (const elem of row) {
+                    walkDeps(elem, cells, areas, tablesByName, nameResolver, visitedNames);
+                }
+            }
+            break;
+        case BoundExprKind.Lambda:
+            walkDeps(expr.body, cells, areas, tablesByName, nameResolver, visitedNames);
+            break;
+        case BoundExprKind.StructuredRef:
+            // Try to resolve structured reference to static deps using the table index.
+            // Only possible when we have the table name and the table exists in the snapshot.
+            if (tablesByName && expr.tableName) {
+                const resolved = tablesByName.get(expr.tableName.toLowerCase());
+                if (resolved) {
+                    const t = resolved.table;
+                    const geo = buildTableGeometry(t);
+                    // Permissive column resolution — static-deps is conservative, so
+                    // unknown column names fall back to the full table width rather
+                    // than being treated as errors.
+                    const colRange = resolveStructuredRefColumns(expr.columns, t, "permissive");
+                    if (colRange === "error") {
+                        // Not reachable in permissive mode, but guard for exhaustiveness.
+                        break;
+                    }
+                    // #This Row can't be resolved statically; we still record the data
+                    // range as a conservative dependency bound.
+                    const rowRange = resolveStructuredRefRows(expr.specials, geo);
+                    let rowTop = geo.dataRowStart;
+                    let rowBottom = geo.dataRowEnd;
+                    if (rowRange !== "thisRow" && rowRange !== "error") {
+                        rowTop = rowRange.rowTop;
+                        rowBottom = rowRange.rowBottom;
+                    }
+                    areas.push({
+                        sheet: resolved.sheetName,
+                        top: rowTop,
+                        left: colRange.colLeft,
+                        bottom: rowBottom,
+                        right: colRange.colRight
+                    });
+                    break;
+                }
+            }
+            // Cannot resolve — no static deps (will be handled at runtime)
+            break;
+        case BoundExprKind.Literal:
+            // No static dependencies
+            break;
+        case BoundExprKind.NameExpr:
+            // Try to resolve the defined name and extract its dependencies.
+            // Guard against infinite recursion with visitedNames.
+            if (nameResolver && visitedNames && !visitedNames.has(expr.upperName)) {
+                visitedNames.add(expr.upperName);
+                const resolved = nameResolver(expr.upperName);
+                if (resolved) {
+                    for (const c of resolved.deps.cells) {
+                        cells.push(c);
+                    }
+                    for (const a of resolved.deps.areas) {
+                        areas.push(a);
+                    }
+                }
+            }
+            break;
+    }
+}
+// ============================================================================
+// Volatility / Dynamic Ref / Dynamic Array Detection
+// ============================================================================
+// Excel's volatile-function list: any formula containing one of these
+// must be re-evaluated on every calc pass, because the result can change
+// without any explicit input change. INDIRECT / OFFSET are additionally
+// flagged as "dynamic ref" (their dependency set isn't known at compile
+// time), but they're also volatile in the usual sense — the target
+// cell's value may change even when the INDIRECT string itself is
+// constant. INFO and CELL with the "row"/"col" info-type also qualify
+// but those require per-invocation arg inspection; the coarse opt-in
+// below is intentionally conservative.
+const VOLATILE_FUNCTIONS = new Set([
+    "RAND",
+    "RANDBETWEEN",
+    "RANDARRAY",
+    "NOW",
+    "TODAY",
+    "INDIRECT",
+    "OFFSET",
+    "INFO",
+    "CELL"
+]);
+const DYNAMIC_REF_FUNCTIONS = new Set(["INDIRECT", "OFFSET"]);
+/**
+ * Function names that naturally produce arrays and should trigger spill
+ * behavior even when `isDynamicArray` is not explicitly set in the XLSX model.
+ */
+const DYNAMIC_ARRAY_FUNCTION_NAMES = new Set([
+    "FILTER",
+    "SORT",
+    "UNIQUE",
+    "SORTBY",
+    "SEQUENCE",
+    "RANDARRAY",
+    "TOCOL",
+    "TOROW",
+    "CHOOSEROWS",
+    "CHOOSECOLS",
+    "VSTACK",
+    "HSTACK",
+    "WRAPROWS",
+    "WRAPCOLS",
+    "EXPAND",
+    "TAKE",
+    "DROP"
+]);
+/**
+ * Check if the formula's top-level expression is a known dynamic array
+ * function. Checks both the raw AST (for prefixed names like `_XLFN.FILTER`)
+ * and the bound expression (for the canonical uppercase name).
+ */
+export function detectDynamicArrayFunction(ast, bound) {
+    // Check AST level (handles _XLFN. prefixed names)
+    if (ast.type === NodeType.FunctionCall) {
+        const upper = ast.name.toUpperCase();
+        if (DYNAMIC_ARRAY_FUNCTION_NAMES.has(upper)) {
+            return true;
+        }
+        const canonical = stripFunctionPrefix(upper);
+        if (DYNAMIC_ARRAY_FUNCTION_NAMES.has(canonical)) {
+            return true;
+        }
+    }
+    // Check bound expression level
+    if (bound.kind === BoundExprKind.Call && DYNAMIC_ARRAY_FUNCTION_NAMES.has(bound.name)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if the formula's top-level expression is SUBTOTAL or AGGREGATE.
+ *
+ * Excel's SUBTOTAL/AGGREGATE functions deliberately skip any cell whose
+ * own source formula is itself a SUBTOTAL or AGGREGATE call — this is
+ * what makes the classic "totals row inside a filtered range" case not
+ * double-count. `buildRangeArray` reads this flag off the compiled
+ * formula to decide whether to set `subtotalMask[r][c]`.
+ */
+export function detectSubtotalOutput(ast, bound) {
+    if (ast.type === NodeType.FunctionCall) {
+        const upper = ast.name.toUpperCase();
+        const canonical = stripFunctionPrefix(upper);
+        if (canonical === "SUBTOTAL" || canonical === "AGGREGATE") {
+            return true;
+        }
+    }
+    if (bound.kind === BoundExprKind.Call &&
+        (bound.name === "SUBTOTAL" || bound.name === "AGGREGATE")) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Analyze a bound expression for volatile functions and dynamic references.
+ *
+ * @param nameResolver - Optional; if a NameExpr resolves to a formula-based
+ *   defined name containing INDIRECT/OFFSET, the outer formula inherits
+ *   `hasDynamicRefs = true`.
+ */
+export function analyzeExpr(expr, nameResolver) {
+    let isVolatile = false;
+    let hasDynamicRefs = false;
+    let containsLambda = false;
+    walkAnalyze(expr);
+    return { isVolatile, hasDynamicRefs, containsLambda };
+    function walkAnalyze(e) {
+        switch (e.kind) {
+            case BoundExprKind.Call:
+                if (VOLATILE_FUNCTIONS.has(e.name)) {
+                    isVolatile = true;
+                }
+                for (const arg of e.args) {
+                    walkAnalyze(arg);
+                }
+                break;
+            case BoundExprKind.SpecialCall:
+                if (DYNAMIC_REF_FUNCTIONS.has(e.name)) {
+                    hasDynamicRefs = true;
+                }
+                if (VOLATILE_FUNCTIONS.has(e.name)) {
+                    isVolatile = true;
+                }
+                for (const arg of e.args) {
+                    walkAnalyze(arg);
+                }
+                break;
+            case BoundExprKind.Lambda:
+                containsLambda = true;
+                walkAnalyze(e.body);
+                break;
+            case BoundExprKind.NameExpr:
+                // If the name resolves to a formula that contains dynamic refs
+                // or volatile functions, the outer formula inherits both flags.
+                // Forgetting to propagate `isVolatile` meant that a defined name
+                // pointing at `NOW()` stayed cached between calculations — the
+                // bug drove R5-P0-5.
+                if (nameResolver) {
+                    const resolved = nameResolver(e.upperName);
+                    if (resolved?.hasDynamicRefs) {
+                        hasDynamicRefs = true;
+                    }
+                    if (resolved?.isVolatile) {
+                        isVolatile = true;
+                    }
+                }
+                break;
+            case BoundExprKind.BinaryOp:
+                walkAnalyze(e.left);
+                walkAnalyze(e.right);
+                break;
+            case BoundExprKind.UnaryOp:
+                walkAnalyze(e.operand);
+                break;
+            case BoundExprKind.Percent:
+                walkAnalyze(e.operand);
+                break;
+            case BoundExprKind.Array:
+                for (const row of e.rows) {
+                    for (const elem of row) {
+                        walkAnalyze(elem);
+                    }
+                }
+                break;
+            default:
+                // Literal, CellRef, AreaRef, etc. — no children to analyze
+                break;
+        }
+    }
+}

package/dist/browser/modules/formula/compile/dependency-analysis.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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
+ */
+/**
+ * The dependency graph structure.
+ *
+ * - `dependsOn`: formula cell key → set of cell keys it reads from
+ * - `dependedBy`: cell key → set of formula cell keys that read from it
+ * - `formulaKeys`: ordered list of all formula cell keys
+ * - `circularKeys`: set of formula cell keys involved in circular references
+ */
+export interface DependencyGraph {
+    /** Forward edges: formula → cells it depends on */
+    readonly dependsOn: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Reverse edges: cell → formulas that depend on it */
+    readonly dependedBy: ReadonlyMap<string, ReadonlySet<string>>;
+    /** All formula cell keys in insertion order */
+    readonly formulaKeys: readonly string[];
+    /** Formula cell keys that are part of a circular reference cycle */
+    readonly circularKeys: ReadonlySet<string>;
+}
+/**
+ * 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 declare function buildDependencyGraphFromDeps(compiled: ReadonlyMap<string, {
+    instance: {
+        sheetName: string;
+        row: number;
+        col: number;
+        isDynamicArray?: boolean;
+    };
+    /**
+     * Whether this formula's top-level function is a known dynamic-
+     * array producer (SEQUENCE / FILTER / SORT / …). Used to collapse
+     * downstream `A1:A5`-style range dependencies into a single edge
+     * on the master so dependency ordering stays correct on the first
+     * calc pass (before ghost cells exist in the snapshot).
+     */
+    isDynamicArrayFunction?: boolean;
+    staticDeps: {
+        cells: readonly {
+            sheet: string;
+            row: number;
+            col: number;
+        }[];
+        areas: readonly {
+            sheet: string;
+            top: number;
+            left: number;
+            bottom: number;
+            right: number;
+        }[];
+    };
+}>, producerMap?: ReadonlyMap<string, string>): DependencyGraph;
+/**
+ * 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 declare function mergeDynamicDeps(graph: DependencyGraph, dynamicDeps: ReadonlyMap<string, ReadonlySet<string>>): {
+    graph: DependencyGraph;
+    changed: boolean;
+};
+/**
+ * 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 declare function topologicalSort(graph: DependencyGraph): string[];