@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/calculation/compiler/CompilerUtils.d.ts

@@ -0,0 +1,331 @@
+import { FormulaError, IFunction, IRuntime } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { ISymbolRegistry } from '../symbol';
+import { TokenType } from '../TokenType';
+import { CompiledFormula, ParseError } from './Types';
+import { ASTNode } from './ASTTypes';
+import { FormulaSeparators } from './FormulaSeparators';
+/**
+ * Walks the ancestor path (root → parent order) and returns the nearest ancestor
+ * matching the given type, or undefined if none exists.
+ */
+export declare function findAncestor(path: ASTNode[], type: TokenType): ASTNode | undefined;
+/**
+ * @param preserveExpression Editing mode: token `text` must reproduce the TYPED source exactly, so a
+ * scoped reference prepends its raw typed sheet prefix (`value.scopeImage` — `sheet2!`, `'Sheet 1'!`).
+ * Display mode (`false`) leaves `text` as the bare part; `resolveTokenSymbols` re-synthesizes the
+ * qualifier from the resolved (rename-safe) sheet name.
+ */
+export declare function generateFormulaTokens(rootNode: ASTNode, preserveExpression?: boolean, emitSeparators?: FormulaSeparators): ICalculation.FormulaToken[];
+/**
+ * Concatenate a token stream back to source text (each token's raw `text`, falling back to a string
+ * `value`; synthesized tokens like `Empty` contribute nothing). Used by the editing-mode compiler to
+ * verify a token stream is FAITHFUL — that it reproduces the typed expression char-for-char — before
+ * handing it to an editor that lays colored spans over the raw text by offset.
+ *
+ * A scoped reference's token captures only its own part (`A1`, `MyName`, `#REF!`) — the sheet
+ * qualifier is re-synthesized from the structured `value`'s scope (a Cell's coords, a Named's
+ * NamedReference, an error reference's ErrorRef, resolved through `symbols` when linked), mirroring
+ * what the display layer (`resolveTokenSymbols`) does, so `Sheet2!A1`, `Sheet1!MyName` and
+ * `Data!#REF!` reconstruct.
+ */
+export declare function tokensToText(tokens: readonly ICalculation.FormulaToken[], symbols?: ISymbolRegistry | null): string;
+/**
+ * Returns the tokens for the subtree rooted at the node with the given evalIndex.
+ */
+export declare function getSubtreeTokens(ast: ASTNode, evalIndex: number): ICalculation.FormulaToken[];
+/**
+ * Post-processes the AST after {@link linkSymbols} to normalize every
+ * `TableReference` node so its `value` holds a pre-built
+ * {@link StructuredReference} query object instead of a raw table-name string.
+ *
+ * @remarks
+ * - Must run **after** {@link linkSymbols} (stable IDs already in place) and
+ *   **before** {@link compileAST}.
+ * - Child nodes (TableColumn, TableSpecifier, Prefix '@', etc.) remain in
+ *   `inputs` for formula-text rendering.  They are skipped during compilation
+ *   via a {@link findAncestor} path check on `TokenType.TableReference`.
+ * - Both explicit refs (`Table1[Col]`, value = stable ID) and implicit refs
+ *   (`[Col]`, value = `''`) are handled identically — the `tableId` field of
+ *   the resulting {@link StructuredReference} carries the distinction.
+ */
+export declare function normalizeStructuredRefs(ast: ASTNode): ASTNode;
+/**
+ * Rewrites `[#This Row]` specifier syntax inside `TableReference` inputs to the
+ * canonical `@` prefix form used for internal storage and display.
+ *
+ * `Table1[[#This Row],[Column]]` → `Table1[@[Column]]`
+ *
+ * Call after parsing from XLSX (import / setValue).  Not called during transient
+ * UI editing so the formula bar preserves exactly what the user typed.
+ *
+ * @returns A new AST (structurally shared where unchanged).
+ */
+export declare function rewriteThisRowToAt(ast: ASTNode): ASTNode;
+/**
+ * Sorts the items inside every `TableReference` into Excel's canonical order — section specifiers
+ * in band order (`#All` | `#Headers`, `#Data`, `#Totals`), then the column selector.
+ *
+ * `Table1[[#Data],[#Headers]]` → `Table1[[#Headers],[#Data]]`
+ *
+ * @remarks
+ * Excel ACCEPTS the out-of-order form on entry and silently rewrites it on commit, so this is a
+ * round-trip requirement, not a correctness one: evaluation never cared (`_buildStructuredReference`
+ * reduces the items to order-independent flags), but a file written in the typed order does not
+ * match what Excel would have stored.
+ *
+ * Commit-path only — `preserveExpression` (formula-editor) mode keeps exactly what the user typed,
+ * the same boundary {@link rewriteThisRowToAt} observes. Runs AFTER that rewrite, which has already
+ * folded `[#This Row]` into the `@` prefix, so only the four band specifiers need a rank.
+ *
+ * @returns A new AST (structurally shared where unchanged).
+ */
+export declare function reorderStructuredRefItems(ast: ASTNode): ASTNode;
+export declare function compileAST(runtime: IRuntime, symbols: ISymbolRegistry | undefined, original: ASTNode, preserveExpression?: boolean, error?: ParseError | null, getFunction?: ((name: string) => IFunction | null) | null): CompiledFormula;
+/**
+ * Convert a chevrotain error into a {@link FormulaError.Parse}.
+ *
+ * The message is the raw error text (`Missing closing parenthesis ')'`) — NOT prefixed with its
+ * position. Position lives structurally on the error (`getDetails()` → `{ line, column }`), so a
+ * consumer decides how to present it: a tooltip can show just the text, while a caller that wants the
+ * caret can read the coordinates (or run them back through {@link ParserUtils.formatParseErrorMessage}).
+ *
+ * @param error Any error from chevrotain.
+ */
+export declare function formatChevrotainError(error: any): FormulaError.Known;
+export declare function copyTrivia(target: ASTNode, source: ASTNode): ASTNode;
+export declare const binaryOperatorsPrecedence: readonly string[][];
+export declare const rangeSpanOperators: readonly string[];
+export declare const rangedOperators: readonly string[];
+export declare const rangesOperators: readonly string[];
+/**
+ * Used to determine is a node is a range node for writing dynamic arrays to Excel
+ */
+export declare const isRangedNode: (node: ASTNode) => boolean;
+/**
+ * Finds an implicit-intersection operand that cannot possibly be a reference, or `null` if the
+ * formula has none.
+ *
+ * @param root The root of the formula's AST.
+ * @param getFunction Resolves a function's stableId to its declaration, or `null`.
+ *
+ * @remarks
+ * Implicit intersection (the whitespace operator) is defined over LOCATIONS — `A1:A10 B1:B10` is
+ * the cells they have in common. Handing it something that computes a value is not a runtime
+ * failure, it is a formula that never had a meaning, and Excel refuses the entry outright rather
+ * than evaluating it (verified against Excel 16.0 by
+ * `spreadsheetbench/formula-tests/probe-space-paren.ps1`, which walks the operand kinds:
+ * `INDEX(...)` — reference-returning — is accepted on both sides, `RANDBETWEEN(...)`, `(3)`,
+ * `(H1:H5+0)` and `TRUE` are all rejected).
+ *
+ * This matters most for a formula that LOOKS like a function call: `=SEQUENCE (3)` is not a call at
+ * all, because the space keeps the `(` from binding to the name — it is the name `SEQUENCE`
+ * intersected with `(3)`. Left to evaluate, the answer depended on what the operands happened to
+ * lex as, so one typo produced #NAME?, #REF! or #NULL! for the same mistake.
+ *
+ * The one place we knowingly diverge from Excel: when the LEFT operand is a built-in function name
+ * (`=SUM (H1:H5)`), Excel rejects it because `SUM` is reserved and cannot be a name, while we let it
+ * resolve and report #NAME?. Recognizing that case needs a function table at PARSE time, which the
+ * parse path has no access to — and "SUM is not a defined name" is an honest answer.
+ */
+export declare const findNonReferenceIntersectionOperand: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => ASTNode | null;
+/**
+ * Finds an array constant whose rows are not all the same length — a JAGGED literal such as
+ * `{1,2;3}`.
+ *
+ * @param root The root of the formula's AST.
+ * @returns A human-readable description of the first jagged array, or `null`.
+ *
+ * @remarks
+ * **An array constant is rectangular, or it is not a formula.** Excel refuses a jagged one at
+ * ENTRY; it does not pad the short row with `#N/A`. The refusal is about SHAPE alone — neither
+ * content nor position changes it. Measured against Excel 16.0
+ * (`spreadsheetbench/formula-tests/probe-jagged-array.ps1`): `{1,2;3}`, `{1;2,3}`, `{1,2;3;4,5}`,
+ * `{1,2;3,4,5}`, `{"a","b";"c"}`, `{TRUE,FALSE;TRUE}`, `{#REF!,1;2}`, `SUM({1,2;3})`,
+ * `SUM(1,{1,2;3})`, `{1,2;3}+1` and `INDEX({1,2;3},1,1)` are all refused, while every rectangular
+ * control (`{1}`, `{1,2,3}`, `{1;2;3}`, `{1,2;3,4}`, `{1,2;3,4;5,6}`) is accepted and spills to
+ * exactly its written shape.
+ *
+ * Deciding it HERE rather than at evaluation is the same lesson as `findArityViolation`, and for a
+ * sharper reason: accepting a jagged literal is not a harmless superset, because the writer emits
+ * whatever parsed. A jagged `<f>` ON DISK makes the workbook UNOPENABLE — Excel declines the whole
+ * file rather than repairing the one cell (`probe-jagged-array2.ps1` patches `{1,2;3}` into an
+ * otherwise healthy saved sheet, after which `Workbooks.Open` fails outright while the unpatched
+ * seed opens fine). So this is a roundtrip guard, not merely entry parity.
+ *
+ * Reported here rather than in `FormulaParser._ruleLiteralArray` because on an Array node
+ * `error` already MEANS "the closing brace was never consumed" — `CompilerUtils`' token emitter
+ * suppresses the `}` when it is set. Since a parse-errored formula re-images from its tokens,
+ * flagging the node would silently rewrite the user's text to `={1,2;3`.
+ */
+export declare const findJaggedArrayLiteral: (root: ASTNode) => string | null;
+/**
+ * Finds a call whose ARGUMENT COUNT the declaration cannot accept — too many, or a required
+ * parameter with no argument.
+ *
+ * @param root The root of the formula's AST.
+ * @param getFunction Resolves a function name to its declaration; `null` disables the check.
+ * @returns A human-readable description of the first violation, or `null`.
+ *
+ * @remarks
+ * Arity is decidable from the AST — argument count from the call, declared arity from the
+ * registry — so by the "only the compiler emits `#PARSE!`" rule it belongs here. Excel agrees:
+ * `=IMAGE()` with too few arguments cannot be typed in at all.
+ *
+ * **This is the "when" half of CALC-ISSUES item 29, and it converts a silent failure into a
+ * loud one.** Previously arity was checked during EVALUATION (`TypedFunction`'s
+ * `RuntimeError.ARGS_TOO_MANY` / `PARAM_MISSING`), which raised `#PARSE!` at calc time —
+ * and `#PARSE!` is precisely what `WorksheetEmitter` refuses to write, so the cell was
+ * downgraded to a literal string and the formula vanished on save with no warning. Deciding
+ * it at compile time surfaces it where the user is typing.
+ *
+ * It does NOT fix a WRONG declaration: an arity stricter than Excel's still rejects a legal
+ * call, just earlier. That is the other half of item 29 and needs the COM sweep. The runtime
+ * checks stay as a backstop for paths that never compile (`IFunction.execute`, item 35).
+ */
+export declare const findArityViolation: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => string | null;
+/**
+ * Finds an argument that is STATICALLY KNOWN to compute a value sitting in a reference-only
+ * (`r:'p'`) parameter — `COLUMN(1)`, `OFFSET(ABS(A1),1,1)`, `SUBTOTAL(9,A1+0)`.
+ *
+ * @param root The root of the formula's AST.
+ * @param getFunction Resolves a function name to its declaration; `null` disables the check.
+ * @returns The offending argument node, or `null`.
+ *
+ * @remarks
+ * **Excel decides this at ENTRY, and so must we** (measured over 34 operand kinds x
+ * `OFFSET`/`COLUMN`, `spreadsheetbench/formula-tests/probe-ref-slot-entry-boundary.ps1`; both
+ * outers agree on every row, so this is the SLOT's rule, not one function's validation). Excel
+ * has two channels: what it can PROVE is not a reference is refused outright and the formula
+ * cannot exist; what it cannot prove is accepted and fails at evaluation with `#VALUE!`. Excel
+ * Online persists a refused formula as a literal STRING — measured in a user-authored
+ * `error-offset.xlsx`, where `=OFFSET(ABS(a1),1,1)` came back as `<c t="s">` while
+ * `=OFFSET(IF(TRUE,1),1,1)` came back as a real `<f>` with a cached `#VALUE!`.
+ *
+ * Deciding it HERE is what makes that faithful. Previously the runtime guessed from the value's
+ * shape and could not tell `IF(TRUE,1)` from a typed `1` once both were the number 1, so it
+ * answered `#PARSE!` for a formula Excel accepts — and `#PARSE!` is exactly what
+ * `WorksheetEmitter` refuses to write, so the cell was saved as text and the formula was lost.
+ *
+ * The provability test is the callee's declared RETURN: a scalar return proves it (`ABS`, `SUM`,
+ * `IFERROR`), a ranged return does not (`IF`, `CHOOSE`, `INDEX`). Note a ranged return is
+ * currently ambiguous between "array" (`SEQUENCE`, `FILTER` — Excel refuses these) and
+ * "may be a reference" (`IF`, `INDEX` — Excel accepts), so we are deliberately PERMISSIVE there:
+ * those cases keep today's behavioral and stay reachable only by hand, never from an
+ * Excel-authored file. Splitting them needs a distinct `unknown` return type (CALC-ISSUES 39).
+ */
+export declare const findValueInReferenceOnlySlot: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => ASTNode | null;
+/**
+ * Finds a `Call` whose callee is STATICALLY KNOWN to produce a value — `=SUM(2)(3)`, `=3(1)`,
+ * `="x"(1)`, `={1,2}(1)`, `=(1+1)(3)` — which Excel refuses at ENTRY.
+ *
+ * @param root The root of the formula's AST.
+ * @param getFunction Resolves a function name to its declaration; `null` disables the check.
+ * @returns The first violation's message, or `null`.
+ *
+ * @remarks
+ * The application design's one rule (§3.1, measured over 34 operands run through BOTH slots):
+ * the callee slot and the intersection slot share a single predicate — the operand's declared
+ * return must not be provably a value. So this is {@link isDefinitelyNotReferenceNode} asked at a
+ * `Call` node's `inputs[0]`, nothing more: a lambda-returning declaration passes (`getLambda()`),
+ * an untyped one passes (`IF(TRUE,1,2)(3)` is accepted and fails at runtime — the decisive probe
+ * row: no flow analysis, no constant folding), a reference passes (`=A1(3)` is a runtime `#REF!`),
+ * and only a provable value is refused.
+ */
+export declare const findInvalidCallee: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => string | null;
+/**
+ * Rewrites every call to an UNKNOWN function into a name application —
+ * `Call(Named(name), …args)`.
+ *
+ * @param root The parsed AST (pre-{@link bindScopes}, pre-{@link linkSymbols}).
+ * @param getFunction Resolves a function name to its declaration; `null` disables the rewrite.
+ * @returns A new root, or the SAME root when nothing changed (copy-on-write).
+ *
+ * @remarks
+ * The lexer's FunctionToken fires on ANY identifier touching a `(`, so `MyLam(3)` — the way a
+ * NAMED LAMBDA is called — arrives as a Function node and previously died at `#NAME?` without the
+ * name ever being consulted. Excel's model has no function-call node at all (`App { head, args }`,
+ * with an unknown head resolving as a name — application §8.1); this rewrite is that rule at the
+ * one place it differs for us.
+ *
+ * What falls out, on purpose:
+ * - `=Doubler(3)` against `Doubler = LAMBDA(x,x*2)` resolves the name, gets the lambda value, and
+ *   applies it — the L2 headline.
+ * - The Named callee registers a real `namedIds` edge, so entering `=Doubler(3)` BEFORE the name
+ *   exists is `#NAME?` that HEALS when the name is defined — a Function node never did.
+ * - A genuinely unknown name still answers `#NAME?` (the callee errors and the Call propagates
+ *   it), and a KNOWN function is never touched, so `_xlfn.`-prefixed spellings and the whole
+ *   registry path stay exactly as they were.
+ */
+export declare function rewriteUnknownFunctionCalls(root: ASTNode, getFunction: ((name: string) => IFunction | null) | null): ASTNode;
+/**
+ * Annotates the `LET`/`LAMBDA` scopes in a parsed AST: each declaration position is marked a
+ * BINDER and every use its scope covers is bound to that binder's slot.
+ *
+ * @param root The parsed AST (post read-transform, pre {@link linkSymbols}).
+ * @param getFunction Resolves a function name to its declaration; see {@link _binderKind}.
+ * @returns A new root, or the SAME root when nothing is bound (copy-on-write).
+ *
+ * @remarks
+ * **Runs before {@link linkSymbols}, and that is the point.** A bound node is claimed here, so no
+ * `NamedFormula` symbol is minted for it, no dependency edge is drawn, and no dead id is left
+ * behind: a parameter is not a name. The node stays a `named` node — the public lite view (and so
+ * io-xlsx's `_xlpm.` spelling) is unchanged — but it stops being a REFERENCE and reads its value
+ * from its binding rather than from the resolver.
+ *
+ * Declaration positions are purely syntactic, the same rule io-xlsx's `_prefixScopeParameters`
+ * proved on the lite tree:
+ * - `LAMBDA` — every argument except the last declares; the last is the body.
+ * - `LET` — the even-indexed arguments except the last declare, the odd ones are their values, and
+ *   the last is the body.
+ *
+ * Binding ORDER is the one rule the shape does not give away, and it is measured: a `LET` name is
+ * in scope only from the argument AFTER its own value, so the same spelling in an earlier one is
+ * the outer / defined name — `LET(zz,zz,zz)` binds only the third `zz`.
+ *
+ * Shadowing needs no special case: the environment is a stack and a use takes the INNERMOST
+ * binding, so an inner scope's name wins over an outer one's, and a parameter wins over a defined
+ * name (it never reaches the resolver at all).
+ */
+export declare function bindScopes(root: ASTNode, getFunction?: ((name: string) => IFunction | null) | null): ASTNode;
+/**
+ * Finds a malformed `LET`/`LAMBDA` scope — a shape Excel refuses at ENTRY.
+ *
+ * @param root The root of the formula's AST.
+ * @param getFunction Resolves a function name to its declaration; see {@link _binderKind}.
+ * @returns The first violation's message, or `null`.
+ *
+ * @remarks
+ * Same channel and same reason as {@link findArityViolation}: Excel decides these before the
+ * formula can exist, so we do too — a refused shape is a parse error, not a cell that evaluates to
+ * something. Read from the shipping Excel Online analyzer
+ * (`d:/dev/excel-calc-ref/excelOnlineCalc.min.js`, `applySpecificWorksheetFunctionChecks`), which
+ * reports `Duplicate_binder` / `Invalid_binder` / `Missing_binder` per declaration and
+ * `Insufficient_function_arguments` with `numArgsExpected: max(3, n + 1 + n % 2)` for `LET` — the
+ * `n % 2` term being exactly the even-argument-count refusal.
+ *
+ * Duplicates compare case-INSENSITIVELY (Excel keys them in a `stringCompareCI` map), the same
+ * normalization a name comparison gets everywhere else.
+ */
+export declare const findBinderViolation: (root: ASTNode, getFunction: ((name: string) => IFunction | null) | null) => string | null;
+/**
+ * Visits the AST and links display names to stable IDs using the symbol registry.
+ *
+ * @param ast The root AST node to start the traversal.
+ * @param symbols The symbol registry used to resolve display names to stable IDs.
+ * @param scope The sheet this formula is written on, or `null`/omitted when there is none.
+ *   Only defined names need it, and only because they can be sheet-scoped: `MonthName` on January
+ *   and the same text on February are two different names when each sheet defines its own, so the
+ *   vantage is part of the question. Without it every reference binds to whichever definition
+ *   happened to win globally.
+ * @returns The updated AST with linked symbols.
+ */
+export declare function linkSymbols(ast: ASTNode, symbols: ISymbolRegistry, scope?: string | null): ASTNode;
+/**
+ * Returns a new AST with every relative Cell node's coordinates shifted by (rowDelta, colDelta),
+ * wrapping out-of-bounds results within [0, max) (Excel behavioral).
+ * Absolute ($) coords and whole-row/whole-column sentinels (Number.MIN_SAFE_INTEGER) are untouched.
+ * Unchanged subtrees are structurally shared (copy-on-write via visitAST).
+ */
+export declare function translateCellNodes(ast: ASTNode, rowDelta: number, colDelta: number, maxRow?: number, maxCol?: number): ASTNode;
+//# sourceMappingURL=CompilerUtils.d.ts.map

package/types/src/calculation/compiler/CompilerUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompilerUtils.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/compiler/CompilerUtils.ts"],"names":[],"mappings":"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"}

package/types/src/calculation/compiler/FormulaCompiler.d.ts

@@ -0,0 +1,69 @@
+import { IFunction, IRuntime } from '@sheetxl/primitives';
+import { ISymbolRegistry } from '../symbol';
+import { ICalculation } from '../ICalculation';
+import { IFormulaCompiler, CompiledFormula } from './Types';
+import { FormulaParseOptions } from './FormulaParser';
+/**
+ * How the compiler balances speed against error recovery. The two are per-INSTANCE (not per-call)
+ * because they change what a compile produces, not just how hard it tries — a caller holds the
+ * compiler that matches its needs.
+ */
+export type FormulaCompilerProfile = 
+/**
+ * The bulk path (load / commit / recalc). Expressions are normalized (e.g. `[#This Row]` → `@`) and a
+ * parse failure costs nothing extra: the result is a single `unparsed` token carrying the raw text
+ * plus the error — nothing is lost on save, and no recovery work is spent.
+ */
+'calc'
+/**
+ * The editor path (`createFormula` while typing). Expressions are preserved exactly as
+ * typed, and a parse failure buys maximum recovery: the longest parseable prefix is compiled (its
+ * references are real) and `getTokens()` is guaranteed FAITHFUL — concatenating the tokens
+ * reproduces the source char-for-char, with everything un-parseable as `unparsed` token(s).
+ */
+ | 'editing';
+/**
+ * Options for constructing a {@link FormulaCompiler}.
+ */
+export interface FormulaCompilerOptions extends FormulaParseOptions {
+    /**
+     * The speed/recovery profile. Defaults to `'calc'`.
+     */
+    profile?: FormulaCompilerProfile;
+}
+export declare class FormulaCompiler implements IFormulaCompiler {
+    private readonly _parser;
+    /** `true` for the `'editing'` profile — preserve the typed expression + maximum recovery. */
+    private readonly _editing;
+    constructor(options?: FormulaCompilerOptions);
+    /** @inheritdoc IFormulaCompiler.compile */
+    compile(runtime: IRuntime, rowIndex: number, colIndex: number, expression: string, symbols?: ISymbolRegistry, getFunction?: ((name: string) => IFunction | null) | null, scope?: string | null, formulaTransform?: ICalculation.FormulaTransform): CompiledFormula;
+    /** @inheritdoc IFormulaCompiler.autoCorrect */
+    autoCorrect(expression: string): string | null;
+    /**
+     * The zero-recovery parse-failure result: a compiled formula whose only token is the raw expression
+     * as `unparsed`, evaluating to the parse error. Nothing is lost (the text round-trips), nothing is
+     * spent — this is the calc profile's entire failure path, and editing's last resort.
+     */
+    private _compileUnparsed;
+    /**
+     * Recover a fully-COMPILED formula for an expression the parser couldn't parse faithfully: the longest
+     * parseable prefix, compiled (so `getReferences()` + tokens are real), presented as an error. Candidate
+     * prefixes end at TOKEN boundaries (from a tolerant re-lex — character trimming could land mid-token,
+     * where e.g. a long string literal never re-lexes), longest first. A prefix is accepted only when it
+     * compiles AND its tokens reproduce the prefix text exactly; the un-parseable tail is then appended as
+     * `unparsed` token(s) (see {@link _appendUnparsedTail}), so the WHOLE result round-trips the source.
+     * Returns `null` when nothing down to the attempt cap parses. Only reached on a parse failure, so its
+     * cost is off the common (valid) path.
+     */
+    private _recoverCompiled;
+    /**
+     * Append the un-parseable `tail` to `tokens` as `unparsed` token(s): stamp the enclosing function
+     * context (from the last token that has one) so a caret in the tail still resolves to the right
+     * function + argument, and split off a trailing identifier run (`[A-Za-z_][A-Za-z0-9_]*` at a token
+     * boundary, not glued to a preceding digit like `12abc`) as its own `isLookup` token, so a partial
+     * name being typed can still drive autocomplete.
+     */
+    private _appendUnparsedTail;
+}
+//# sourceMappingURL=FormulaCompiler.d.ts.map

package/types/src/calculation/compiler/FormulaCompiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormulaCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/compiler/FormulaCompiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIlF,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EACL,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAC5C,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAwD,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEjH;;;;GAIG;AACH,MAAM,MAAM,sBAAsB;AAChC;;;;GAIG;AACD,MAAM;AACR;;;;;GAKG;GACD,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE;;OAEG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AASD,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;gBAEvB,OAAO,CAAC,EAAE,sBAAsB;IAQ5C,2CAA2C;IAC3C,OAAO,CACL,OAAO,EAAE,QAAQ,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,eAAe,EACzB,WAAW,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,GAAG,IAAI,CAAC,GAAG,IAAI,EACzD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,EACrB,gBAAgB,CAAC,EAAE,YAAY,CAAC,gBAAgB,GAC/C,eAAe;IAsIlB,+CAA+C;IAC/C,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA4B9C;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAiCxB;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IA4ExB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;CAmC5B"}

package/types/src/calculation/compiler/FormulaLexer.d.ts

@@ -0,0 +1,85 @@
+import { ILexingResult, TokenType as CTokenType } from 'chevrotain';
+import { FormulaSeparators, CANONICAL_SEPARATORS, formulaSeparatorsForDecimal } from './FormulaSeparators';
+import { CompilerLocale } from './CompilerLocale';
+export { type FormulaSeparators, CANONICAL_SEPARATORS, formulaSeparatorsForDecimal };
+export interface FormulaLexerOptions {
+    /**
+     * Maximum column index (1-based). Defaults to Excel's 16,384 (XFD).
+     */
+    maxColumn?: number;
+    /**
+     * Maximum row index (1-based). Defaults to Excel's 1,048,576.
+     */
+    maxRow?: number;
+    /**
+     * The locale to tokenize for — separators (Plane 1) plus the localized boolean/error alternates
+     * (Plane 3) the lexer adds alongside the always-lexed canonical set. Defaults to
+     * {@link CANONICAL_LOCALE} (canonical separators, English-only literals).
+     */
+    locale?: CompilerLocale;
+}
+/**
+ * Used for tokenizing a string using formula tokens.
+ */
+export declare class FormulaLexer {
+    private readonly _lexer;
+    /** The token vocabulary passed to the Chevrotain parser. */
+    private readonly _vocabulary;
+    /** The locale this lexer tokenizes with — shared with the parser (actions) and emit path. */
+    private readonly _locale;
+    /** Grid bounds the cell/column matchers were built against — see {@link getMaxRow}. */
+    private readonly _maxColumn;
+    private readonly _maxRow;
+    /**
+     * A lexer for this exact configuration, built at most once.
+     *
+     * Construction is not cheap — the whole token set is rebuilt, and bucketing
+     * `_nameStartCharsHint` alone measures ~0.4 ms — and a `FormulaLexer` was previously built
+     * per `FormulaParser`, i.e. per `Sheet`. Nothing here is mutable after construction
+     * (every field is `readonly`, `tokenize` returns a fresh result), so one instance serves
+     * every caller with the same configuration.
+     *
+     * Keyed on the locale by IDENTITY rather than by value. The lexer reads separators, error
+     * literals and boolean spellings off that object, so the same object always means the same
+     * tokens; two equal-but-distinct locale objects merely miss the cache, which costs a build
+     * and never correctness.
+     */
+    static shared(config?: FormulaLexerOptions): FormulaLexer;
+    constructor(config?: FormulaLexerOptions);
+    /**
+     * Break an expression into tokens.
+     *
+     * @param expression The text to tokenize.
+     * @param throwOnError If `false`, lexing errors do not throw — the partial result (the tokens that
+     * DID lex, plus `errors`) is returned as-is. Used by editing-mode recovery to find the last clean
+     * token boundary in an expression whose tail can't lex (e.g. an unterminated string).
+     * @returns The result of lexing, including the list of tokens and any errors.
+     */
+    tokenize(expression: string, throwOnError?: boolean): ILexingResult;
+    /**
+     * Return the token vocabulary, which maps token names to Chevrotain token types.
+     */
+    getVocabulary(): Record<string, CTokenType>;
+    /**
+     * The locale this lexer tokenizes with. The parser reads it for its actions (mapping typed booleans/
+     * errors/numbers → canonical AST values); it also carries the separators the emit path re-images with.
+     */
+    getLocale(): CompilerLocale;
+    /** The last valid column (1-based) — `A1`/`AC` beyond it lex as a name, not a reference. */
+    getMaxColumn(): number;
+    /**
+     * The last valid row (1-based).
+     *
+     * The cell matcher applies this itself (`A1048577` falls through to a NAME), but a whole-row
+     * operand cannot: a bare digit run lexes as a NUMBER, and only the parser knows it sits beside a
+     * range operator. The parser reads this to bound that conversion — Excel refuses `1:1048577` and
+     * `0:1` outright (`spreadsheetbench/formula-tests/probe-mixed-range-operand4.ps1`).
+     */
+    getMaxRow(): number;
+    /**
+     * The fully-resolved separators this lexer tokenizes with. The parser reads `separatorDecimal`
+     * to normalize number images (`1,5` → `1.5`); the emit path reads all four to localize display.
+     */
+    getSeparators(): FormulaSeparators;
+}
+//# sourceMappingURL=FormulaLexer.d.ts.map

package/types/src/calculation/compiler/FormulaLexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormulaLexer.d.ts","sourceRoot":"","sources":["../../../../../src/calculation/compiler/FormulaLexer.ts"],"names":[],"mappings":"AAAA,OAAO,EAE2D,KAAK,aAAa,EAClF,KAAK,SAAS,IAAI,UAAU,EAC7B,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,KAAK,iBAAiB,EAAE,oBAAoB,EAAE,2BAA2B,EAC1E,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,cAAc,EAAoB,MAAM,kBAAkB,CAAC;AAEzE,OAAO,EAAE,KAAK,iBAAiB,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,CAAC;AAKrF,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,YAAY;gBAkB7C,MAAM,CAAC,EAAE,mBAAmB;IA+QxC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,GAAE,OAAY,GAAG,aAAa;IAqBvE;;OAEG;IACH,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;IAI3C;;;OAGG;IACH,SAAS,IAAI,cAAc;IAI3B,4FAA4F;IAC5F,YAAY,IAAI,MAAM;IAItB;;;;;;;OAOG;IACH,SAAS,IAAI,MAAM;IAInB;;;OAGG;IACH,aAAa,IAAI,iBAAiB;CAGnC"}