mulmoclaude 2.6.0 → 2.8.0

package/src/plugins/spreadsheet/engine/financial-math.ts

@@ -1,114 +0,0 @@
-/**
- * Annuity math for the financial functions, as pure numeric helpers.
- *
- * Excel's cash-flow sign convention: money received is positive, money paid out
- * is negative — so a loan's `pv` is positive and its payment and interest come
- * back negative. Keeping the per-period split as plain number-in / number-out
- * functions lets it be tested against known Excel values without routing string
- * arguments back through the formula evaluator.
- */
-
-import { NUM_ERROR, type SpreadsheetError } from "./spreadsheet-errors";
-
-/** Future value after `nper` periods. `type` is 0 (end of period) or 1 (begin). */
-export function computeFv(rate: number, nper: number, pmt: number, pv: number, type: number): number {
-  if (rate === 0) return -(pv + pmt * nper);
-  const growth = Math.pow(1 + rate, nper);
-  return -pv * growth - (pmt * (growth - 1) * (1 + rate * type)) / rate;
-}
-
-/** Constant per-period payment amortising a present value `pv` to `fv`. */
-export function computePmt(rate: number, nper: number, pv: number, fv: number, type: number): number {
-  if (rate === 0) return -(fv + pv) / nper;
-  const growth = Math.pow(1 + rate, nper);
-  return (-rate * (fv + pv * growth)) / ((growth - 1) * (1 + rate * type));
-}
-
-/** Interest portion of the `per`-th payment. */
-export function computeIpmt(rate: number, per: number, nper: number, pv: number, fv: number, type: number): number {
-  const pmt = computePmt(rate, nper, pv, fv, type);
-  if (per === 1 && type === 1) return 0;
-  const priorPeriods = type === 1 ? per - 2 : per - 1;
-  // Interest is the rate applied to the balance outstanding at the start of the
-  // period. computeFv already carries the payment-negative sign, so this product
-  // is the interest as a (negative) cash outflow — negating it again inverted the
-  // sign (IPMT came back +1250 for a -1250 payment) and PPMT amplified the error.
-  const interest = computeFv(rate, priorPeriods, pmt, pv, type) * rate;
-  return type === 1 ? interest / (1 + rate) : interest;
-}
-
-/** Principal portion of the `per`-th payment (total payment minus interest). */
-export function computePpmt(rate: number, per: number, nper: number, pv: number, fv: number, type: number): number {
-  return computePmt(rate, nper, pv, fv, type) - computeIpmt(rate, per, nper, pv, fv, type);
-}
-
-/** Present value of an annuity that grows to `fv` after `nper` payments of `pmt`. */
-export function computePv(rate: number, nper: number, pmt: number, fv: number, type: number): number {
-  if (rate === 0) return -(fv + pmt * nper);
-  const growth = Math.pow(1 + rate, nper);
-  return (-fv - (pmt * (growth - 1) * (1 + rate * type)) / rate) / growth;
-}
-
-/** Number of periods needed to amortise `pv` to `fv` at constant `pmt`. */
-export function computeNper(rate: number, pmt: number, pv: number, fv: number, type: number): number {
-  if (rate === 0) return -(fv + pv) / pmt;
-  const pmtWithType = pmt * (1 + rate * type);
-  return Math.log((pmtWithType - fv * rate) / (pmtWithType + pv * rate)) / Math.log(1 + rate);
-}
-
-// Newton-Raphson is iterative; a valid annuity / cash-flow series converges well
-// inside these bounds. A series with no real solution never does, so exhausting
-// the loop means "no answer" — Excel reports #NUM! there, and returning the last
-// iterate instead would hand back a divergent value or NaN as if it were a rate.
-const NEWTON_MAX_ITERATIONS = 100;
-const NEWTON_TOLERANCE = 1e-7;
-
-/** Interest rate per period solving the annuity equation, via Newton-Raphson. */
-export function computeRate(nper: number, pmt: number, pv: number, fv: number, type: number, guess: number): number | SpreadsheetError {
-  let rate = guess;
-  for (let i = 0; i < NEWTON_MAX_ITERATIONS; i++) {
-    if (Math.abs(rate) < NEWTON_TOLERANCE) rate = NEWTON_TOLERANCE; // avoid division by zero
-    const growth = Math.pow(1 + rate, nper);
-    const f = pv * growth + pmt * ((growth - 1) / rate) * (1 + rate * type) + fv;
-    const df =
-      nper * pv * Math.pow(1 + rate, nper - 1) +
-      (pmt * (1 + rate * type) * (nper * Math.pow(1 + rate, nper - 1) * rate - (growth - 1))) / (rate * rate) +
-      pmt * type * ((growth - 1) / rate);
-    const newRate = rate - f / df;
-    if (Math.abs(newRate - rate) < NEWTON_TOLERANCE) return Number.isFinite(newRate) ? newRate : NUM_ERROR;
-    rate = newRate;
-  }
-  return NUM_ERROR;
-}
-
-/** Net present value of `cashflows`, each discounted one period further into the future. */
-export function computeNpv(rate: number, cashflows: number[]): number {
-  return cashflows.reduce((npv, value, index) => npv + value / Math.pow(1 + rate, index + 1), 0);
-}
-
-/** The present value of `values` (element 0 at period 0) discounted at `rate`,
- *  together with its derivative — the pair one Newton-Raphson step needs. */
-function discountedSeries(values: number[], rate: number): { npv: number; dnpv: number } {
-  return values.reduce(
-    (totals, value, period) => {
-      const factor = Math.pow(1 + rate, period);
-      return { npv: totals.npv + value / factor, dnpv: totals.dnpv - (period * value) / (factor * (1 + rate)) };
-    },
-    { npv: 0, dnpv: 0 },
-  );
-}
-
-/** Internal rate of return of `values` (element 0 at period 0), via Newton-Raphson. */
-export function computeIrr(values: number[], guess: number): number | SpreadsheetError {
-  let rate = guess;
-  for (let i = 0; i < NEWTON_MAX_ITERATIONS; i++) {
-    const { npv, dnpv } = discountedSeries(values, rate);
-    if (Math.abs(npv) < NEWTON_TOLERANCE) return rate;
-    // A flat derivative leaves nowhere to step: the series has no root here.
-    if (Math.abs(dnpv) < NEWTON_TOLERANCE) return NUM_ERROR;
-    const newRate = rate - npv / dnpv;
-    if (Math.abs(newRate - rate) < NEWTON_TOLERANCE) return Number.isFinite(newRate) ? newRate : NUM_ERROR;
-    rate = newRate;
-  }
-  return NUM_ERROR;
-}

package/src/plugins/spreadsheet/engine/formatter.ts

@@ -1,158 +0,0 @@
-/**
- * Number Formatting Utilities
- *
- * Handles Excel-style format codes for currency, percentages, decimals, dates, etc.
- */
-
-import { serialToDate, MONTH_NAMES_SHORT, MONTH_NAMES_FULL, DAY_NAMES_SHORT, DAY_NAMES_FULL } from "./date-utils";
-
-/**
- * Check if a format code is for dates
- */
-function isDateFormat(format: string): boolean {
-  // Date formats contain date/time tokens: Y, M, D, h, m, s
-  // But not percentage (which also has 'm' in format like #,##0)
-  // Look for specific date patterns
-  return /[YMD]|MMM|DD|YYYY|h:mm|AM\/PM/i.test(format);
-}
-
-/**
- * Format a number as a date according to Excel format code
- *
- * Supported formats:
- * - MM/DD/YYYY, M/D/YYYY
- * - DD/MM/YYYY, D/M/YYYY
- * - YYYY-MM-DD
- * - DD-MMM-YYYY, D-MMM-YYYY
- * - MMM D, YYYY, MMMM D, YYYY
- * - h:mm AM/PM, HH:mm:ss
- *
- * @param serial - Excel serial number
- * @param format - Date format code
- * @returns Formatted date string
- */
-// Every token, longest-first within each family so `MMMM` wins over `MMM` and
-// `MM`. Matched in ONE pass: a sequence of `replace` calls re-scans its own
-// output, so an inserted "March" had its `M` rewritten by the later month-number
-// step and "AM/PM" was destroyed before the meridiem branch could see it.
-const DATE_TOKEN_RE = /YYYY|YY|MMMM|MMM|MM|M|dddd|ddd|DD|D|AM\/PM|am\/pm|HH|H|hh|h|mm|ss/g;
-
-function formatDate(serial: number, format: string): string {
-  const date = serialToDate(serial);
-
-  const year = date.getUTCFullYear();
-  const month = date.getUTCMonth(); // 0-11
-  const day = date.getUTCDate();
-  const hours = date.getUTCHours();
-  const minutes = date.getUTCMinutes();
-  const seconds = date.getUTCSeconds();
-  const dayOfWeek = date.getUTCDay(); // 0-6
-
-  // `h` means the 12-hour clock only when the format also asks for a meridiem;
-  // decided from the ORIGINAL format, before any substitution.
-  const uses12Hour = /AM\/PM|am\/pm/.test(format);
-  const hours12 = hours % 12 || 12; // 0 becomes 12
-  const isPM = hours >= 12;
-
-  const replacements: Record<string, string> = {
-    YYYY: year.toString(),
-    YY: (year % 100).toString().padStart(2, "0"),
-    MMMM: MONTH_NAMES_FULL[month] ?? MONTH_NAMES_FULL[0],
-    MMM: MONTH_NAMES_SHORT[month] ?? MONTH_NAMES_SHORT[0],
-    MM: (month + 1).toString().padStart(2, "0"),
-    M: (month + 1).toString(),
-    dddd: DAY_NAMES_FULL[dayOfWeek] ?? DAY_NAMES_FULL[0],
-    ddd: DAY_NAMES_SHORT[dayOfWeek] ?? DAY_NAMES_SHORT[0],
-    DD: day.toString().padStart(2, "0"),
-    D: day.toString(),
-    "AM/PM": isPM ? "PM" : "AM",
-    "am/pm": isPM ? "pm" : "am",
-    HH: hours.toString().padStart(2, "0"),
-    H: hours.toString(),
-    hh: (uses12Hour ? hours12 : hours).toString().padStart(2, "0"),
-    h: (uses12Hour ? hours12 : hours).toString(),
-    mm: minutes.toString().padStart(2, "0"),
-    ss: seconds.toString().padStart(2, "0"),
-  };
-
-  return format.replace(DATE_TOKEN_RE, (token) => replacements[token] ?? token);
-}
-
-const THOUSANDS_GROUP_SIZE = 3;
-
-/**
- * Insert thousands separators into a run of digits ("1234567" → "1,234,567").
- * Regex free on purpose: the classic `\B(?=(\d{3})+(?!\d))` lookahead
- * backtracks badly on a long run of digits.
- */
-export const groupThousands = (digits: string): string =>
-  Array.from(digits).reduce((grouped, digit, index) => {
-    const needsSeparator = index > 0 && (digits.length - index) % THOUSANDS_GROUP_SIZE === 0;
-    return needsSeparator ? `${grouped},${digit}` : `${grouped}${digit}`;
-  }, "");
-
-/** Group the integer part of a formatted number ("1234567.89" → "1,234,567.89"),
- *  leaving any fractional part after the decimal point untouched. */
-export const addThousandSeparators = (formatted: string): string => {
-  const [whole, ...fraction] = formatted.split(".");
-  if (whole === undefined) return formatted;
-  return [groupThousands(whole), ...fraction].join(".");
-};
-
-/**
- * Format a number according to Excel format code
- *
- * Supported formats:
- * - Currency: $#,##0.00, $#,##0
- * - Percentage: 0.00%, 0.0%
- * - Integer with commas: #,##0
- * - Decimal: 0.00, 0.000
- * - Dates: MM/DD/YYYY, DD-MMM-YYYY, etc.
- *
- * @param value - The numeric value to format
- * @param format - The Excel format code
- * @returns Formatted string representation
- */
-export function formatNumber(value: number, format: string): string {
-  if (!format) return value.toString();
-
-  try {
-    // Check if it's a date format
-    if (isDateFormat(format)) {
-      return formatDate(value, format);
-    }
-
-    // Handle currency formats
-    if (format.includes("$")) {
-      const decimals = (format.match(/\.0+/) || [""])[0].length - 1;
-      const magnitude = Math.abs(value).toFixed(decimals >= 0 ? decimals : 0);
-      const grouped = format.includes(",") ? addThousandSeparators(magnitude) : magnitude;
-      const withSymbol = "$" + grouped;
-      return value < 0 ? "-" + withSymbol : withSymbol;
-    }
-
-    // Handle percentage
-    if (format.includes("%")) {
-      const decimals = (format.match(/\.0+/) || [""])[0].length - 1;
-      return (value * 100).toFixed(decimals >= 0 ? decimals : 2) + "%";
-    }
-
-    // Handle comma separator
-    if (format.includes(",")) {
-      const decimals = (format.match(/\.0+/) || [""])[0].length - 1;
-      const grouped = addThousandSeparators(Math.abs(value).toFixed(decimals >= 0 ? decimals : 0));
-      return value < 0 ? "-" + grouped : grouped;
-    }
-
-    // Handle decimal places
-    const decimals = (format.match(/\.0+/) || [""])[0].length - 1;
-    if (decimals >= 0) {
-      return value.toFixed(decimals);
-    }
-
-    return value.toString();
-  } catch (error) {
-    console.error("Format error:", error);
-    return value.toString();
-  }
-}

package/src/plugins/spreadsheet/engine/formulaError.ts

@@ -1,67 +0,0 @@
-/**
- * Typed formula-evaluation errors
- *
- * A failed formula must surface as a typed error with an Excel-style error value
- * in the cell, never as a swallowed bare string (issue #2359). This module holds
- * the error taxonomy, the throwable carrier, and the pure helpers that classify a
- * thrown error and propagate an error value across cell references. No engine
- * state is captured — every export is input → output only.
- */
-
-import type { CalculationError } from "./types";
-import type { SpreadsheetErrorCode } from "./spreadsheet-errors";
-
-/** The evaluator-facing error kinds: every `CalculationError["type"]` except
- *  `circular`, which the calculator raises directly (not via a thrown error). */
-export type FormulaErrorType = Exclude<CalculationError["type"], "circular">;
-
-/** The error code shown for each kind, matching Excel's error literals. */
-export const FORMULA_ERROR_VALUES: Record<FormulaErrorType, SpreadsheetErrorCode> = {
-  div_zero: "#DIV/0!",
-  invalid_ref: "#REF!",
-  syntax: "#NAME?",
-  unknown: "#ERROR!",
-};
-
-/** Reverse map for propagation: an error code back to the kind it represents.
- *  Codes without a dedicated kind (`#N/A`, `#NUM!`, …) propagate as `unknown`. */
-const ERROR_VALUE_TO_TYPE: Record<string, FormulaErrorType> = {
-  [FORMULA_ERROR_VALUES.div_zero]: "div_zero",
-  [FORMULA_ERROR_VALUES.invalid_ref]: "invalid_ref",
-  [FORMULA_ERROR_VALUES.syntax]: "syntax",
-};
-
-/** A recoverable formula failure carrying the kind and the code to show. */
-export class FormulaError extends Error {
-  constructor(
-    readonly errorType: FormulaErrorType,
-    readonly display: SpreadsheetErrorCode,
-    message?: string,
-  ) {
-    super(message ?? display);
-    this.name = "FormulaError";
-  }
-}
-
-export const isFormulaError = (error: unknown): error is FormulaError => error instanceof FormulaError;
-
-export const divZeroError = (): FormulaError => new FormulaError("div_zero", FORMULA_ERROR_VALUES.div_zero, "Division by zero");
-
-export const invalidRefError = (ref: string): FormulaError => new FormulaError("invalid_ref", FORMULA_ERROR_VALUES.invalid_ref, `Invalid reference: ${ref}`);
-
-export const nameError = (funcName: string): FormulaError => new FormulaError("syntax", FORMULA_ERROR_VALUES.syntax, `Unknown function: ${funcName}`);
-
-export const unknownError = (message?: string): FormulaError => new FormulaError("unknown", FORMULA_ERROR_VALUES.unknown, message);
-
-/** The FormulaError that re-raises an error read from a referenced cell or a
- *  nested call, so `=A1+1` inherits A1's error instead of corrupting into
- *  `"#DIV/0!"+1`. */
-export const propagatedError = (value: SpreadsheetErrorCode): FormulaError =>
-  new FormulaError(ERROR_VALUE_TO_TYPE[value] ?? "unknown", value, `Propagated error: ${value}`);
-
-/** Map any thrown value onto the typed entry the calculator records. A
- *  `FormulaError` keeps its own kind and display; anything else is `unknown`. */
-export const classifyThrownError = (error: unknown): { type: FormulaErrorType; display: SpreadsheetErrorCode } => {
-  if (isFormulaError(error)) return { type: error.errorType, display: error.display };
-  return { type: "unknown", display: FORMULA_ERROR_VALUES.unknown };
-};

package/src/plugins/spreadsheet/engine/formulaRefs.ts

@@ -1,202 +0,0 @@
-/**
- * Extract the set of cells that a formula references.
- *
- * Extracted from `src/plugins/spreadsheet/View.vue` (was the body of
- * `extractCellReferences`, cognitive complexity 32). The original
- * function combined regex scanning, range expansion, single-cell
- * parsing, and deduplication all in one body; splitting each concern
- * into a named helper brings the top-level function well under the
- * sonarjs/cognitive-complexity threshold of 15 and makes the pure
- * logic unit-testable in isolation (see
- * `test/plugins/spreadsheet/engine/test_formulaRefs.ts`).
- *
- * Tracks #175. No behavioural change — the wrapper in View.vue
- * still returns exactly the same `{ row, col }` list as before.
- */
-
-import { columnToIndex } from "./parser.js";
-
-export interface CellCoord {
-  row: number;
-  col: number;
-}
-
-// `A1:B10`, `$A$1:$B$10`, `Sheet` refs are out of scope here — the
-// caller only passes the formula body, and cross-sheet ranges never
-// reached the original regex anyway. Keeping the patterns identical
-// to the pre-refactor code preserves behaviour exactly.
-const RANGE_REGEX = /\$?[A-Z]+\$?\d+:\$?[A-Z]+\$?\d+/g;
-const CELL_REGEX = /\$?[A-Z]+\$?\d+/g;
-
-// Excel formulas start with `=`. Strip it for uniform handling.
-// Keeps any inner `=` intact (Excel does not allow them but the
-// caller may pass partial text during live editing).
-export function stripFormulaPrefix(formula: string): string {
-  return formula.startsWith("=") ? formula.slice(1) : formula;
-}
-
-const A1_REGEX = /^([A-Z]+)(\d+)$/;
-
-// One `A1` token as its column index (0-based) and its row NUMBER as written
-// (1-based). The single place a column letter + row digit pair is read, so the
-// range and single-cell parsers below cannot drift apart.
-function parseA1Token(token: string): { col: number; rowNumber: number } | null {
-  const [, column, row] = token.match(A1_REGEX) ?? [];
-  if (column === undefined || row === undefined) return null;
-  return { col: columnToIndex(column), rowNumber: parseInt(row, 10) };
-}
-
-// The two endpoints of an `A1:B3` range, or null for anything that is not
-// exactly two `A1` tokens joined by one colon.
-function parseRangeEndpoints(body: string): { start: { col: number; rowNumber: number }; end: { col: number; rowNumber: number } } | null {
-  const [startToken, endToken, ...extra] = body.split(":");
-  if (startToken === undefined || endToken === undefined || extra.length > 0) return null;
-  const start = parseA1Token(startToken);
-  const end = parseA1Token(endToken);
-  return start && end ? { start, end } : null;
-}
-
-// Expand a single range token (`A1:B3`, `$A$1:$C$5`) into every
-// coordinate the range covers. Returns an empty array for malformed
-// input so callers never have to handle exceptions; the worst case
-// is "we silently ignored a weird-looking substring," which matches
-// the original inline behaviour.
-export function expandRange(rangeStr: string): CellCoord[] {
-  const endpoints = parseRangeEndpoints(rangeStr.replace(/\$/g, ""));
-  if (!endpoints) return [];
-  const { start, end } = endpoints;
-  const cells: CellCoord[] = [];
-  for (let row = start.rowNumber - 1; row <= end.rowNumber - 1; row++) {
-    for (let col = start.col; col <= end.col; col++) {
-      cells.push({ row, col });
-    }
-  }
-  return cells;
-}
-
-// Expand a range OR a single cell into coordinates, upcasing first so
-// lowercase references (`a1:b2`, which spreadsheets accept) are not dropped,
-// and falling back to a single cell when there is no colon. `collectRangeValues`
-// in the calculator used a range-only, case-sensitive regex, so `A1`,
-// `$A$1:$A$10` and `a1:a10` all silently produced no values (#2356). Ordering
-// matches `expandRange`: top-to-bottom, left-to-right.
-export function expandRangeOrCell(ref: string): CellCoord[] | null {
-  const upper = ref.trim().toUpperCase();
-  if (upper.includes(":")) {
-    const cells = expandRange(upper);
-    return cells.length > 0 ? cells : null;
-  }
-  const single = parseSingleCellRef(upper);
-  return single ? [single] : null;
-}
-
-// Parse a single cell ref (`A1`, `$A$1`, `AA100`) into a coord.
-// Returns null for malformed input rather than throwing — keeps the
-// caller's loop flat (the engine-layer `parseCellRef` throws, which
-// is fine for the evaluator but wrong for a best-effort scanner).
-export function parseSingleCellRef(refStr: string): CellCoord | null {
-  const parsed = parseA1Token(refStr.replace(/\$/g, ""));
-  return parsed ? { col: parsed.col, row: parsed.rowNumber - 1 } : null;
-}
-
-// Numeric bounds of a `A2:C10` range, with any `Sheet1!` / `'My Sheet'!`
-// prefix kept verbatim so callers can rebuild sheet-qualified refs. Columns
-// are 0-based (via `columnToIndex`); rows stay 1-based, matching A1 notation.
-export interface RangeBounds {
-  sheetPrefix: string;
-  startCol: number;
-  startRow: number;
-  endCol: number;
-  endRow: number;
-}
-
-// Split an optional sheet prefix from a range, then parse the `A2:C10` body.
-// The prefix is everything up to and including the last `!`, so a quoted sheet
-// name that itself contains no `!` (the common case) is preserved intact. The
-// lookup functions each carried their own copy of this parse; one copy ran a
-// sheet-unaware regex against the whole string and threw on `Sheet1!A2:C10`
-// before the sheet-aware copy could run (#2390). Returns null for anything that
-// is not a two-endpoint range so callers surface one "Invalid range" message.
-export function parseRangeBounds(range: string): RangeBounds | null {
-  const bang = range.lastIndexOf("!");
-  const sheetPrefix = bang >= 0 ? range.slice(0, bang + 1) : "";
-  const body = bang >= 0 ? range.slice(bang + 1) : range;
-  const endpoints = parseRangeEndpoints(body);
-  if (!endpoints) return null;
-  const { start, end } = endpoints;
-  return { sheetPrefix, startCol: start.col, startRow: start.rowNumber, endCol: end.col, endRow: end.rowNumber };
-}
-
-// Excel's `0` row/column index selects the entire row/column. This scalar engine
-// returns a single cell, so `0` is representable only when that dimension is one
-// line long; otherwise it is out of range.
-const WHOLE_LINE_INDEX = 0;
-const FIRST_INDEX = 1;
-
-// Map a 1-based INDEX position onto a 0-based offset within a `size`-long line,
-// truncating toward zero as Excel does. Returns null when the position falls
-// outside the line — including a `0` (whole-line) request the scalar engine
-// cannot collapse to one cell. Callers turn null into #REF!.
-function lineOffset(position: number, size: number): number | null {
-  const index = Math.trunc(position);
-  if (!Number.isFinite(index)) return null;
-  if (index === WHOLE_LINE_INDEX) return size === 1 ? 0 : null;
-  if (index < FIRST_INDEX || index > size) return null;
-  return index - FIRST_INDEX;
-}
-
-// Resolve INDEX(range, rowNum, colNum)'s 1-based position to an absolute cell
-// within the range, or null (→ #REF!) when it falls outside. The former handler
-// computed the target with no bounds check, so an out-of-range index silently
-// read a cell outside the range (#2390: `INDEX(A1:A3,5)` read A5, `INDEX(A2:B5,
-// 0,1)` read A1). Returned column is 0-based; row is 1-based (A1 notation).
-export function resolveIndexTarget(bounds: RangeBounds, rowNum: number, colNum: number): { colIndex: number; row: number } | null {
-  const rowOffset = lineOffset(rowNum, bounds.endRow - bounds.startRow + 1);
-  const colOffset = lineOffset(colNum, bounds.endCol - bounds.startCol + 1);
-  if (rowOffset === null || colOffset === null) return null;
-  return { colIndex: bounds.startCol + colOffset, row: bounds.startRow + rowOffset };
-}
-
-// VLOOKUP's col_index_num / HLOOKUP's row_index_num as a 0-based offset inside
-// the table, or null (→ #REF!) when it points outside. Excel rejects an index
-// past the table's width; without the check the handler addressed a cell beyond
-// the range and returned whatever lived there — usually a silent 0 (#2360).
-export function resolveTableOffset(position: number, size: number): number | null {
-  // Not `lineOffset`: INDEX reads a `0` position as "the whole line", which it
-  // can collapse to one cell when the line is one long. A lookup index has no
-  // such meaning — VLOOKUP's columns are numbered from 1 — so `0` is out of
-  // range even for a single-column table (Codex review).
-  const index = Math.trunc(position);
-  if (!Number.isFinite(index)) return null;
-  if (index < FIRST_INDEX || index > size) return null;
-  return index - FIRST_INDEX;
-}
-
-// Top-level: scan the formula, expand any ranges, then pick up
-// remaining single-cell refs, deduplicating as we go. Kept short
-// (~15 lines) so the cognitive-complexity signal lands on the
-// helpers if anything grows here.
-export function extractCellReferences(formula: string): CellCoord[] {
-  const clean = stripFormulaPrefix(formula);
-  const refs: CellCoord[] = [];
-  const seen = new Set<string>();
-  const addUnique = (coord: CellCoord): void => {
-    const key = `${coord.row},${coord.col}`;
-    if (seen.has(key)) return;
-    seen.add(key);
-    refs.push(coord);
-  };
-
-  for (const range of clean.match(RANGE_REGEX) ?? []) {
-    for (const coord of expandRange(range)) addUnique(coord);
-  }
-  // Strip matched ranges so the cell-regex doesn't re-emit their
-  // endpoints as standalone refs (mirrors the original's second
-  // `.replace(rangeRegex, "")` pass).
-  const withoutRanges = clean.replace(RANGE_REGEX, "");
-  for (const cellStr of withoutRanges.match(CELL_REGEX) ?? []) {
-    const coord = parseSingleCellRef(cellStr);
-    if (coord) addUnique(coord);
-  }
-  return refs;
-}