@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/cjs/modules/formula/compile/address-utils.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Formula Address Utilities — Shared helpers for address parsing and conversion.
+ *
+ * These pure functions are used across the compile, runtime, and materialize
+ * layers. Centralizing them here eliminates duplication and ensures consistent
+ * behavior.
+ *
+ * ## Design Constraint
+ *
+ * This module must NOT import from `@excel/utils/col-cache` or any live
+ * workbook type. All functions are self-contained.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colLetterToNumber = colLetterToNumber;
+exports.parseDefinedNameRange = parseDefinedNameRange;
+exports.parseSimpleAddress = parseSimpleAddress;
+exports.parseRefRange = parseRefRange;
+// ============================================================================
+// Column Letter ↔ Number
+// ============================================================================
+/**
+ * Convert a column letter string (e.g. "A", "AA", "XFD") to a 1-based number.
+ *
+ * - `"A"` → 1
+ * - `"Z"` → 26
+ * - `"AA"` → 27
+ * - `"XFD"` → 16384
+ */
+function colLetterToNumber(col) {
+    let result = 0;
+    for (let i = 0; i < col.length; i++) {
+        result = result * 26 + (col.charCodeAt(i) - 64); // 'A' = 65
+    }
+    return result;
+}
+const DEFINED_NAME_RANGE_RE = /^(?:'([^']*(?:''[^']*)*)'|([^!]+))!\$([A-Z]+)\$(\d+)(?::\$([A-Z]+)\$(\d+))?$/;
+/**
+ * Parse a defined-name range string like `"Sheet1!$A$1:$B$2"` or `"'Sheet Name'!$C$3"`
+ * into a `ParsedNameRange`. Returns `null` if the format is unrecognized.
+ */
+function parseDefinedNameRange(rangeStr) {
+    const m = DEFINED_NAME_RANGE_RE.exec(rangeStr);
+    if (!m) {
+        return null;
+    }
+    // Sheet name: quoted (group 1, with '' unescaping) or unquoted (group 2)
+    const sheet = m[1] !== undefined ? m[1].replace(/''/g, "'") : m[2];
+    const startCol = colLetterToNumber(m[3]);
+    const startRow = parseInt(m[4], 10);
+    const endCol = m[5] ? colLetterToNumber(m[5]) : startCol;
+    const endRow = m[6] ? parseInt(m[6], 10) : startRow;
+    return { sheet, startRow, startCol, endRow, endCol };
+}
+/**
+ * Parse a simple cell address like `"A1"`, `"$B$2"`, or `"AA100"`.
+ * Dollar signs are stripped. Returns `null` on parse failure.
+ */
+function parseSimpleAddress(addr) {
+    const m = /^([A-Z]+)(\d+)$/.exec(addr.replace(/\$/g, ""));
+    if (!m) {
+        return null;
+    }
+    return {
+        row: parseInt(m[2], 10),
+        col: colLetterToNumber(m[1])
+    };
+}
+/**
+ * Parse a cell range string like `"A1:B2"` into a `ParsedRefRange`.
+ * Returns `null` if the format is unrecognized.
+ */
+function parseRefRange(ref) {
+    const parts = ref.split(":");
+    if (parts.length !== 2) {
+        return null;
+    }
+    const tl = parseSimpleAddress(parts[0]);
+    const br = parseSimpleAddress(parts[1]);
+    if (!tl || !br) {
+        return null;
+    }
+    return {
+        top: Math.min(tl.row, br.row),
+        left: Math.min(tl.col, br.col),
+        bottom: Math.max(tl.row, br.row),
+        right: Math.max(tl.col, br.col)
+    };
+}

package/dist/cjs/modules/formula/compile/binder.js

@@ -0,0 +1,489 @@
+"use strict";
+/**
+ * Binder — Transform raw AST into BoundExpr.
+ *
+ * The binder performs static symbol resolution:
+ * - Cell/range references → BoundCellRef / BoundAreaRef with resolved sheet
+ * - Defined names → BoundCellRef / BoundAreaRef (if resolvable) or BoundNameExpr
+ * - Structured references → BoundCellRef / BoundAreaRef
+ * - Function calls → BoundCall or BoundSpecialCall
+ * - 3D references → BoundRef3D
+ *
+ * The binder operates on snapshot data only — no live workbook objects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bind = bind;
+const workbook_snapshot_1 = require("../integration/workbook-snapshot");
+const token_types_1 = require("../syntax/token-types");
+const address_utils_1 = require("./address-utils");
+const bound_ast_1 = require("./bound-ast");
+const structured_ref_utils_1 = require("./structured-ref-utils");
+// ============================================================================
+// Special Form Registry
+// ============================================================================
+const SPECIAL_FORMS = new Set([
+    "IF",
+    "IFERROR",
+    "IFNA",
+    "IFS",
+    "SWITCH",
+    "CHOOSE",
+    "LET",
+    "LAMBDA",
+    "INDIRECT",
+    "OFFSET",
+    "MAP",
+    "REDUCE",
+    "SCAN",
+    "MAKEARRAY",
+    "BYROW",
+    "BYCOL"
+]);
+/**
+ * Map prefixed names to their canonical special form name.
+ */
+function canonicalSpecialForm(name) {
+    const canonical = (0, token_types_1.stripFunctionPrefix)(name);
+    if (SPECIAL_FORMS.has(canonical)) {
+        return canonical;
+    }
+    return undefined;
+}
+// ============================================================================
+// Main Bind Function
+// ============================================================================
+/**
+ * Bind a raw AST node to produce a BoundExpr.
+ *
+ * This is the main entry point for the compilation phase. It recursively
+ * walks the AST and resolves all symbols against the snapshot.
+ */
+function bind(node, ctx) {
+    switch (node.type) {
+        case 1 /* NodeType.Number */:
+            return (0, bound_ast_1.boundLiteral)(node.value);
+        case 2 /* NodeType.String */:
+            return (0, bound_ast_1.boundLiteral)(node.value);
+        case 3 /* NodeType.Boolean */:
+            return (0, bound_ast_1.boundLiteral)(node.value);
+        case 4 /* NodeType.Error */:
+            return (0, bound_ast_1.boundErrorLiteral)(node.value);
+        case 16 /* NodeType.Missing */:
+            return (0, bound_ast_1.boundLiteral)(null);
+        case 5 /* NodeType.CellRef */:
+            return bindCellRef(node, ctx);
+        case 6 /* NodeType.RangeRef */:
+            return bindRangeRef(node, ctx);
+        case 13 /* NodeType.ColRangeRef */:
+            return bindColRangeRef(node, ctx);
+        case 14 /* NodeType.RowRangeRef */:
+            return bindRowRangeRef(node, ctx);
+        case 7 /* NodeType.BinaryOp */:
+            return {
+                kind: 7 /* BoundExprKind.BinaryOp */,
+                op: node.op,
+                left: bind(node.left, ctx),
+                right: bind(node.right, ctx)
+            };
+        case 8 /* NodeType.UnaryOp */:
+            return {
+                kind: 8 /* BoundExprKind.UnaryOp */,
+                op: node.op,
+                operand: bind(node.operand, ctx)
+            };
+        case 11 /* NodeType.Percent */:
+            return {
+                kind: 9 /* BoundExprKind.Percent */,
+                operand: bind(node.operand, ctx)
+            };
+        case 9 /* NodeType.FunctionCall */:
+            return bindFunctionCall(node.name, node.args, ctx);
+        case 10 /* NodeType.Array */:
+            return {
+                kind: 12 /* BoundExprKind.Array */,
+                rows: node.rows.map(row => row.map(elem => bind(elem, ctx)))
+            };
+        case 12 /* NodeType.Name */:
+            return bindName(node.name, ctx);
+        case 15 /* NodeType.StructuredRef */:
+            return bindStructuredRef(node.tableName, node.columns, node.specials, ctx);
+        default:
+            return assertNever(node);
+    }
+}
+/**
+ * Exhaustiveness helper: triggers a compile-time error if `bind` misses a
+ * discriminated-union variant. At runtime, this path is unreachable.
+ */
+function assertNever(x) {
+    throw new Error(`unexpected AST node: ${JSON.stringify(x)}`);
+}
+// ============================================================================
+// Cell Reference Binding
+// ============================================================================
+function bindCellRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const row = parseInt(node.row, 10);
+    const col = (0, address_utils_1.colLetterToNumber)(node.col);
+    // Excel's cell coordinate range is 1..1048576 for rows, 1..16384 for
+    // columns. The tokenizer enforces these when recognising cell refs,
+    // but we re-check here because the same binder runs on defined-name
+    // range strings that bypass the tokenizer and could carry arbitrary
+    // large values.
+    if (row < 1 || row > 1048576 || col < 1 || col > 16384) {
+        return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
+    // 3D cell reference: Sheet1:Sheet3!A1
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+        }
+        const inner = (0, bound_ast_1.boundCellRef)(sheets[0], row, col);
+        return {
+            kind: 6 /* BoundExprKind.Ref3D */,
+            sheets,
+            inner
+        };
+    }
+    // Validate sheet exists
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
+    return (0, bound_ast_1.boundCellRef)(sheet, row, col);
+}
+function bindRangeRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const startRow = parseInt(node.start.row, 10);
+    const startCol = (0, address_utils_1.colLetterToNumber)(node.start.col);
+    const endRow = parseInt(node.end.row, 10);
+    const endCol = (0, address_utils_1.colLetterToNumber)(node.end.col);
+    const top = Math.min(startRow, endRow);
+    const bottom = Math.max(startRow, endRow);
+    const left = Math.min(startCol, endCol);
+    const right = Math.max(startCol, endCol);
+    // 3D range reference: Sheet1:Sheet3!A1:B2
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+        }
+        const inner = (0, bound_ast_1.boundAreaRef)(sheets[0], top, left, bottom, right);
+        return {
+            kind: 6 /* BoundExprKind.Ref3D */,
+            sheets,
+            inner
+        };
+    }
+    return (0, bound_ast_1.boundAreaRef)(sheet, top, left, bottom, right);
+}
+function bindColRangeRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const startCol = (0, address_utils_1.colLetterToNumber)(node.startCol);
+    const endCol = (0, address_utils_1.colLetterToNumber)(node.endCol);
+    const leftCol = Math.min(startCol, endCol);
+    const rightCol = Math.max(startCol, endCol);
+    // Validate sheet exists
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
+    // 3D col range: Sheet1:Sheet3!A:B
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+        }
+        // Return Ref3D wrapping an area for the full column range
+        const inner = (0, bound_ast_1.boundAreaRef)(sheets[0], 1, leftCol, 1048576, rightCol);
+        return {
+            kind: 6 /* BoundExprKind.Ref3D */,
+            sheets,
+            inner
+        };
+    }
+    return {
+        kind: 4 /* BoundExprKind.ColRangeRef */,
+        sheet,
+        leftCol,
+        rightCol
+    };
+}
+function bindRowRangeRef(node, ctx) {
+    const sheet = node.sheet ?? ctx.currentSheet;
+    const topRow = Math.min(node.startRow, node.endRow);
+    const bottomRow = Math.max(node.startRow, node.endRow);
+    // Validate sheet exists
+    if (!ctx.snapshot.worksheetsByName.has(sheet.toLowerCase())) {
+        return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
+    // 3D row range: Sheet1:Sheet3!1:5
+    if (node.endSheet) {
+        const sheets = getSheetsInRange(ctx.snapshot, sheet, node.endSheet);
+        if (!sheets) {
+            return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+        }
+        const inner = (0, bound_ast_1.boundAreaRef)(sheets[0], topRow, 1, bottomRow, 16384);
+        return {
+            kind: 6 /* BoundExprKind.Ref3D */,
+            sheets,
+            inner
+        };
+    }
+    return {
+        kind: 5 /* BoundExprKind.RowRangeRef */,
+        sheet,
+        topRow,
+        bottomRow
+    };
+}
+// ============================================================================
+// Name Binding
+// ============================================================================
+function bindName(name, ctx) {
+    // A lambda parameter (or other compile-time local) shadows any
+    // workbook-level defined name. Without this short-circuit,
+    // `LAMBDA(x, x*2)(10)` would pick up a defined name called `x` that
+    // resolves to a cell reference, computing the cell's value × 2
+    // instead of the lambda argument × 2.
+    if (ctx.localNames && ctx.localNames.has(name.toUpperCase())) {
+        return (0, bound_ast_1.boundNameExpr)(name);
+    }
+    // Try to resolve as a defined name that maps to a cell/range.
+    // Respects scope precedence: sheet-local > workbook-global.
+    const dn = (0, workbook_snapshot_1.resolveDefinedName)(ctx.snapshot.definedNames, name, ctx.currentSheet);
+    if (dn) {
+        return resolveDefinedName(dn, ctx);
+    }
+    // Unresolved — could be a LET-bound local variable, a formula-based name,
+    // or a truly unknown name. Return BoundNameExpr for runtime resolution.
+    return (0, bound_ast_1.boundNameExpr)(name);
+}
+function resolveDefinedName(dn, ctx) {
+    if (dn.ranges.length === 0) {
+        return (0, bound_ast_1.boundErrorLiteral)("#NAME?");
+    }
+    // Multi-area names are not supported
+    if (dn.ranges.length > 1) {
+        return (0, bound_ast_1.boundErrorLiteral)("#VALUE!");
+    }
+    const rangeStr = dn.ranges[0];
+    // Try to parse as a cell/range reference
+    const parsed = (0, address_utils_1.parseDefinedNameRange)(rangeStr);
+    if (parsed) {
+        // Single cell
+        if (parsed.startRow === parsed.endRow && parsed.startCol === parsed.endCol) {
+            return (0, bound_ast_1.boundCellRef)(parsed.sheet, parsed.startRow, parsed.startCol);
+        }
+        // Range
+        return (0, bound_ast_1.boundAreaRef)(parsed.sheet, Math.min(parsed.startRow, parsed.endRow), Math.min(parsed.startCol, parsed.endCol), Math.max(parsed.startRow, parsed.endRow), Math.max(parsed.startCol, parsed.endCol));
+    }
+    // The range string is a formula expression (e.g. "LAMBDA(x,y,x+y)").
+    // This must be resolved at runtime since it may produce a lambda or
+    // depend on the evaluation context. Return a BoundNameExpr.
+    return (0, bound_ast_1.boundNameExpr)(dn.name);
+}
+// ============================================================================
+// Structured Reference Binding
+// ============================================================================
+function bindStructuredRef(tableName, columns, specials, ctx) {
+    // If the table name is empty (implicit @) or specials include #This Row,
+    // we need runtime context (current cell position) to resolve.
+    // Defer to the evaluator.
+    const needsRuntime = tableName === "" || specials.includes("#This Row");
+    // Find the table in the snapshot
+    const table = findTable(ctx.snapshot, tableName);
+    if (!table) {
+        if (needsRuntime) {
+            // Defer to runtime — return BoundStructuredRef
+            return {
+                kind: 15 /* BoundExprKind.StructuredRef */,
+                tableName,
+                columns: [...columns],
+                specials: [...specials]
+            };
+        }
+        return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
+    // If #This Row is present, defer to runtime even if table is found
+    if (needsRuntime) {
+        return {
+            kind: 15 /* BoundExprKind.StructuredRef */,
+            tableName: table.table.name,
+            columns: [...columns],
+            specials: [...specials]
+        };
+    }
+    const resolved = resolveStructuredRefBounds(table, columns, specials);
+    if (!resolved) {
+        return (0, bound_ast_1.boundErrorLiteral)("#REF!");
+    }
+    if (resolved.top === resolved.bottom && resolved.left === resolved.right) {
+        return (0, bound_ast_1.boundCellRef)(resolved.sheet, resolved.top, resolved.left);
+    }
+    return (0, bound_ast_1.boundAreaRef)(resolved.sheet, resolved.top, resolved.left, resolved.bottom, resolved.right);
+}
+function findTable(snapshot, tableName) {
+    if (!tableName) {
+        return null;
+    }
+    // Use the pre-built tablesByName index for O(1) lookup
+    const resolved = snapshot.tablesByName.get(tableName.toLowerCase());
+    if (resolved) {
+        return { table: resolved.table, sheetName: resolved.sheetName };
+    }
+    return null;
+}
+function resolveStructuredRefBounds(tw, columns, specials) {
+    const t = tw.table;
+    const geo = (0, structured_ref_utils_1.buildTableGeometry)(t);
+    const colRange = (0, structured_ref_utils_1.resolveStructuredRefColumns)(columns, t, "strict");
+    if (colRange === "error") {
+        return null;
+    }
+    const rowRange = (0, structured_ref_utils_1.resolveStructuredRefRows)(specials, geo);
+    let rowTop;
+    let rowBottom;
+    if (rowRange === "error") {
+        return null;
+    }
+    else if (rowRange === "thisRow") {
+        // #This Row requires runtime context — use data range as static fallback
+        rowTop = geo.dataRowStart;
+        rowBottom = geo.dataRowEnd;
+    }
+    else {
+        rowTop = rowRange.rowTop;
+        rowBottom = rowRange.rowBottom;
+    }
+    return {
+        sheet: tw.sheetName,
+        top: rowTop,
+        left: colRange.colLeft,
+        bottom: rowBottom,
+        right: colRange.colRight
+    };
+}
+// ============================================================================
+// Function Call Binding
+// ============================================================================
+function bindFunctionCall(name, args, ctx) {
+    const upperName = name.toUpperCase();
+    // Check for special forms (lazy evaluation)
+    const specialName = canonicalSpecialForm(upperName);
+    if (specialName) {
+        // LAMBDA is special: bind it into a BoundLambda if possible
+        if (specialName === "LAMBDA" && args.length >= 1) {
+            return bindLambda(args, ctx);
+        }
+        // LET has the shape LET(name, value, name, value, …, body). The
+        // `name` slots must be treated as pure locals, not resolved against
+        // workbook defined names, or e.g. a defined-name `X` pointing at
+        // `$A$1` would hijack `LET(X, 5, X+1)` and route the final body to
+        // `A1+1` instead of `5+1`. We extend `localNames` to cover every
+        // name slot before recursively binding the rest.
+        if (specialName === "LET" && args.length >= 3) {
+            return bindLet(args, ctx);
+        }
+        // All other special forms: bind args recursively but wrap as BoundSpecialCall
+        const boundArgs = args.map(arg => bind(arg, ctx));
+        return (0, bound_ast_1.boundSpecialCall)(specialName, boundArgs);
+    }
+    // Reference functions that need AST-level access (ROW, COLUMN, ROWS, COLUMNS)
+    // are bound as regular calls — the evaluator handles the AST → BoundExpr
+    // mapping for these since they work the same way with BoundExpr.
+    // Standard eager function call
+    const boundArgs = args.map(arg => bind(arg, ctx));
+    return (0, bound_ast_1.boundCall)(upperName, boundArgs);
+}
+/**
+ * Bind `LET(name1, value1, …, nameN, valueN, body)` with lexical scoping.
+ *
+ * Even-indexed slots (0, 2, 4, …) are Name AST nodes that introduce new
+ * locals. We add each such name to `localNames` progressively — Excel
+ * allows later `value_i` expressions to reference earlier LET-bound
+ * variables, but NOT the variable being defined on the same slot. The
+ * `body` (last arg) sees every local.
+ */
+function bindLet(args, ctx) {
+    // args = [name1, value1, name2, value2, …, body]; length must be odd.
+    if (args.length < 3 || args.length % 2 === 0) {
+        return (0, bound_ast_1.boundErrorLiteral)("#VALUE!");
+    }
+    const locals = ctx.localNames ? new Set(ctx.localNames) : new Set();
+    const boundArgs = [];
+    for (let i = 0; i + 1 < args.length; i += 2) {
+        const nameNode = args[i];
+        if (nameNode.type !== 12 /* NodeType.Name */) {
+            // Not a Name-shaped slot: preserve whatever the user wrote so the
+            // evaluator's own LET implementation can report the error with
+            // better context.
+            boundArgs.push(bind(nameNode, ctx));
+        }
+        else {
+            // Bind the name slot as a runtime-resolved NameExpr rather than
+            // letting `bindName` eagerly pick up a workbook-level defined name.
+            boundArgs.push((0, bound_ast_1.boundNameExpr)(nameNode.name));
+        }
+        // Bind the value expression with locals-so-far in scope.
+        const valueCtx = { ...ctx, localNames: new Set(locals) };
+        boundArgs.push(bind(args[i + 1], valueCtx));
+        // The just-bound name is now available to subsequent value slots
+        // and to the body.
+        if (nameNode.type === 12 /* NodeType.Name */) {
+            locals.add(nameNode.name.toUpperCase());
+        }
+    }
+    const bodyCtx = { ...ctx, localNames: locals };
+    boundArgs.push(bind(args[args.length - 1], bodyCtx));
+    return (0, bound_ast_1.boundSpecialCall)("LET", boundArgs);
+}
+function bindLambda(args, ctx) {
+    if (args.length < 1) {
+        return (0, bound_ast_1.boundErrorLiteral)("#VALUE!");
+    }
+    const paramNodes = args.slice(0, -1);
+    const bodyNode = args[args.length - 1];
+    const params = [];
+    // Detect duplicate parameter names up front. Excel rejects
+    // `LAMBDA(x, x, x*2)` with #VALUE! rather than silently letting the
+    // second occurrence shadow the first.
+    const seen = new Set();
+    for (const pNode of paramNodes) {
+        if (pNode.type !== 12 /* NodeType.Name */) {
+            return (0, bound_ast_1.boundErrorLiteral)("#VALUE!");
+        }
+        const upper = pNode.name.toUpperCase();
+        if (seen.has(upper)) {
+            return (0, bound_ast_1.boundErrorLiteral)("#VALUE!");
+        }
+        seen.add(upper);
+        params.push(upper);
+    }
+    // Extend the local-name scope with the lambda's parameters so nested
+    // name lookups inside the body bind to runtime locals rather than
+    // same-named workbook defined names.
+    const mergedLocals = ctx.localNames ? new Set(ctx.localNames) : new Set();
+    for (const p of params) {
+        mergedLocals.add(p);
+    }
+    const bodyCtx = { ...ctx, localNames: mergedLocals };
+    return {
+        kind: 14 /* BoundExprKind.Lambda */,
+        params,
+        body: bind(bodyNode, bodyCtx)
+    };
+}
+// ============================================================================
+// 3D Reference Helpers
+// ============================================================================
+function getSheetsInRange(snapshot, startSheet, endSheet) {
+    const allSheets = snapshot.worksheets;
+    const startIdx = allSheets.findIndex(s => s.name.toLowerCase() === startSheet.toLowerCase());
+    const endIdx = allSheets.findIndex(s => s.name.toLowerCase() === endSheet.toLowerCase());
+    if (startIdx === -1 || endIdx === -1) {
+        return null;
+    }
+    const lo = Math.min(startIdx, endIdx);
+    const hi = Math.max(startIdx, endIdx);
+    return allSheets.slice(lo, hi + 1).map(s => s.name);
+}

package/dist/cjs/modules/formula/compile/bound-ast.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Bound Expression AST — The output of the compilation (binding) phase.
+ *
+ * After parsing produces a raw AST, the binder resolves all static symbols:
+ * - Defined names → resolved cell/range references or formula expressions
+ * - Structured references → resolved cell/range references
+ * - Sheet names → validated against the snapshot
+ * - Function names → validated against the registry
+ *
+ * The result is a `BoundExpr` tree where every reference is resolved and
+ * every function call is validated. The runtime evaluator only executes
+ * `BoundExpr` nodes — it never needs to perform symbol resolution.
+ *
+ * ## Node Types (compile output)
+ *
+ * After binding, only these node types exist:
+ *
+ * - `BoundLiteral` — number, string, boolean, error, null (missing)
+ * - `BoundCellRef` — resolved cell reference (sheet + row + col)
+ * - `BoundAreaRef` — resolved rectangular range (sheet + bounds)
+ * - `BoundColRangeRef` — resolved whole-column range
+ * - `BoundRowRangeRef` — resolved whole-row range
+ * - `BoundRef3D` — resolved 3D reference (multiple sheets)
+ * - `BoundBinaryOp` — binary operation
+ * - `BoundUnaryOp` — unary operation (including @)
+ * - `BoundPercent` — postfix %
+ * - `BoundCall` — function call (eagerly evaluated args)
+ * - `BoundSpecialCall` — special form (IF, LET, LAMBDA, etc.) with lazy args
+ * - `BoundArray` — array constant {1,2;3,4}
+ * - `BoundNameExpr` — UNRESOLVED name (only for names that must be resolved at runtime,
+ *   e.g. formula-based defined names that produce lambdas, or truly unknown names)
+ * - `BoundLambda` — LAMBDA expression (params + body)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundLiteral = boundLiteral;
+exports.boundCellRef = boundCellRef;
+exports.boundAreaRef = boundAreaRef;
+exports.boundCall = boundCall;
+exports.boundSpecialCall = boundSpecialCall;
+exports.boundNameExpr = boundNameExpr;
+exports.boundErrorLiteral = boundErrorLiteral;
+// ============================================================================
+// Constructor Helpers
+// ============================================================================
+function boundLiteral(value, errorCode) {
+    return errorCode !== undefined
+        ? { kind: 1 /* BoundExprKind.Literal */, value, errorCode }
+        : { kind: 1 /* BoundExprKind.Literal */, value };
+}
+function boundCellRef(sheet, row, col) {
+    return { kind: 2 /* BoundExprKind.CellRef */, sheet, row, col };
+}
+function boundAreaRef(sheet, top, left, bottom, right) {
+    return { kind: 3 /* BoundExprKind.AreaRef */, sheet, top, left, bottom, right };
+}
+function boundCall(name, args) {
+    return { kind: 10 /* BoundExprKind.Call */, name, args };
+}
+function boundSpecialCall(name, args) {
+    return { kind: 11 /* BoundExprKind.SpecialCall */, name, args };
+}
+function boundNameExpr(name) {
+    return { kind: 13 /* BoundExprKind.NameExpr */, name, upperName: name.toUpperCase() };
+}
+function boundErrorLiteral(errorCode) {
+    return { kind: 1 /* BoundExprKind.Literal */, value: null, errorCode };
+}