/// 单元格内容:字面值或公式源码。
pub(all) enum Cell {
  /// 字面值(数字/文本/布尔/错误/空白)。
  Literal(Value)
  /// 公式源码(前导 `=` 可有可无)。
  Formula(String)
} derive(Show, Debug, Eq)

/// 单元格网格:引擎的唯一输入数据契约。
///
/// `cells` 的键为限定地址:默认表用裸 `A1`,其它表用 `SHEET!A1`
/// (表名 ASCII 大写;含特殊字符的表名保留单引号写法 `'MY SHEET'!A1`,
/// 由 `@value.sheet_key` 生成)。
pub(all) struct Grid {
  /// 地址 → 单元格内容。未出现的地址按空白处理。
  cells : Map[String, Cell]
  /// 工作簿级定义名称:ASCII 大写名称 → 引用文本(如 `Data!A1:B2`)。
  /// 名称体在求值时重新解析,因此必须自包含工作表限定(默认表可裸写)。
  names : Map[String, String]
} derive(Show, Debug)

/// 创建一个空的单元格网格。
pub fn new_grid() -> Grid {
  { cells: Map::new(), names: Map::new() }
}

/// 求值选项。
pub(all) struct EvalOptions {
  /// 调用方注入的时钟(Excel 序列日,含小数)。`TODAY`/`NOW` 依赖它;
  /// `None` 时按显式契约返回 `#NUM!`(核心从不读取系统时钟)。
  now : Double?
} derive(Show, Debug)

/// 单格/单公式求值结果。
pub(all) struct EvalOutput {
  /// 标量化后的值(`Blank`→0;多格区域按值模型规则处理)。
  value : Value
  /// 该格是否落在循环引用环上(环上结果固定为 0)。
  circular : Bool
} derive(Show, Debug)

/// 全网格重算结果。
pub(all) struct RecalcOutput {
  /// 公式格的结果(字面值格不出现)。
  cells : Map[String, EvalOutput]
  /// 解析失败的格与原因(地址, 消息);这些格的结果为 `#VALUE!`。
  parse_errors : Array[(String, String)]
}

struct Ctx {
  grid : Grid
  cache : Map[String, Value]
  range_cache : Map[String, Value]
  ast_cache : Map[String, CachedAst]?
  stack : Array[String]
  on_stack : Map[String, Bool]
  circular : Map[String, Bool]
  parse_errors : Array[(String, String)]
  now : Double?
  /// 当前公式的宿主工作表(`""` = 默认表);裸引用按它限定。
  mut current_sheet : String
  /// 每表 used-range 右下角缓存:表名 → (max_row, max_col);(0,0) = 该表不存在。
  bounds_cache : Map[String, (Int, Int)]
}

fn new_ctx(
  grid : Grid,
  options : EvalOptions,
  ast_cache : Map[String, CachedAst]?
) -> Ctx {
  {
    grid,
    cache: Map::new(),
    range_cache: Map::new(),
    ast_cache,
    stack: [],
    on_stack: Map::new(),
    circular: Map::new(),
    parse_errors: [],
    now: options.now,
    current_sheet: "",
    bounds_cache: Map::new(),
  }
}

/// 名称定义递归上限(防御恶意/意外的名称链)。
let max_name_depth : Int = 32

/// 该表 used-range 的右下角(含)。默认表恒存在且至少 1×1;其它表若无任何单元格
/// 返回 (0,0),对它的引用按缺表 `#REF!` 处理(与 Excel 一致)。
fn used_bounds(ctx : Ctx, sheet : String) -> (Int, Int) {
  match ctx.bounds_cache.get(sheet) {
    Some(b) => b
    None => {
      let mut mr = if sheet == "" { 1 } else { 0 }
      let mut mc = if sheet == "" { 1 } else { 0 }
      for k, _ in ctx.grid.cells {
        let (s, text) = @value.split_key(k)
        if s == sheet {
          match @value.parse_addr(text) {
            Some(a) => {
              if a.row > mr {
                mr = a.row
              }
              if a.col > mc {
                mc = a.col
              }
            }
            None => ()
          }
        }
      }
      let b = (mr, mc)
      ctx.bounds_cache[sheet] = b
      b
    }
  }
}

/// 该表是否存在:默认表恒存在;其它表只要含至少一个单元格即存在。
fn grid_sheet_exists(grid : Grid, sheet : String) -> Bool {
  if sheet == "" {
    return true
  }
  for k, _ in grid.cells {
    if @value.split_key(k).0 == sheet {
      return true
    }
  }
  false
}

/// 物化 [lo, hi] 区域(含端点)。同一 (表, 区域) 在一次求值上下文内共享结果。
fn materialize_range(
  ctx : Ctx,
  sheet : String,
  lo : CellAddr,
  hi : CellAddr
) -> Value {
  let rkey = @value.sheet_key(sheet, lo) + ":" + @value.sheet_key(sheet, hi)
  match ctx.range_cache.get(rkey) {
    Some(v) => v
    None => {
      let rows = hi.row - lo.row + 1
      let cols = hi.col - lo.col + 1
      let cells : Array[Value] = []
      for r in lo.row..=hi.row {
        for c in lo.col..=hi.col {
          let a : CellAddr = { row: r, col: c, abs_row: false, abs_col: false }
          cells.push(cell_value(ctx, @value.sheet_key(sheet, a)))
        }
      }
      let v = Value::Range({ rows, cols, cells })
      ctx.range_cache[rkey] = v
      v
    }
  }
}

/// 名称体解析失败按 `#VALUE!` 处理;名称体自身不产生 parse_errors(不伪造单元格)。
fn parse_name_body(text : String) -> @syntax.Expr? {
  try @syntax.parse(text) catch { _ => None } noraise { e => Some(e) }
}

/// 求值定义名称。名称在解析期与求值期都不做缓存(可随时被引擎以外修改),
/// 只以 `NAME:` 前缀的栈标记做环守卫:环上按真实 Excel 答案键返回 `#NAME?`
/// (见 corpus/cases/refs.json refs-names-011/012)。
fn eval_name(ctx : Ctx, name : String) -> Value {
  let text = match ctx.grid.names.get(name) {
    Some(t) => t
    None => return Value::Err(XlError::Name)
  }
  let guard_key = "NAME:" + name
  if ctx.on_stack.contains(guard_key) {
    // 真实 Excel 答案键(corpus/cases/refs.json refs-names-011/012,2026-11-17 桌面
    // Excel 2610):循环定义名称求值为 #NAME?——Excel 把无法收敛的名称视为不可解析,
    // 而不是迭代关闭下的 0。故环上不返回 0、也不标 circular。
    return Value::Err(XlError::Name)
  }
  let mut depth = 0
  for k in ctx.stack {
    if k.has_prefix("NAME:") {
      depth += 1
    }
  }
  if depth >= max_name_depth {
    return Value::Err(XlError::Name)
  }
  let saved_sheet = ctx.current_sheet
  ctx.current_sheet = ""
  let expr = parse_name_body(text)
  ctx.current_sheet = saved_sheet
  match expr {
    None => Value::Err(XlError::Value)
    Some(e) => {
      ctx.stack.push(guard_key)
      ctx.on_stack[guard_key] = true
      let v = eval_expr(ctx, e)
      let _ = ctx.stack.pop()
      let _ = ctx.on_stack.remove(guard_key)
      v
    }
  }
}

// None = uncached fast path (plain recalc): unique-text workloads must not pay
// cache hashing overhead. Some = content-addressed cache shared across cells
// and/or recalcs (recalc_cached).
fn parse_formula(ctx : Ctx, key : String, src : String) -> @syntax.Expr? {
  match ctx.ast_cache {
    None =>
      try @syntax.parse(src) catch {
        @syntax.ParseError(msg) => {
          ctx.parse_errors.push((key, msg))
          None
        }
      } noraise { e => Some(e) }
    Some(cache) =>
      match cache.get(src) {
        Some(Ast(e)) => Some(e)
        Some(Bad(msg)) => {
          ctx.parse_errors.push((key, msg))
          None
        }
        None =>
          try @syntax.parse(src) catch {
            @syntax.ParseError(msg) => {
              cache[src] = Bad(msg)
              ctx.parse_errors.push((key, msg))
              None
            }
          } noraise { e => {
            cache[src] = Ast(e)
            Some(e)
          } }
      }
  }
}

fn cell_value(ctx : Ctx, key : String) -> Value {
  if ctx.cache.get(key) is Some(v) {
    return v
  }
  if ctx.on_stack.contains(key) {
    // Excel default with iterative calculation off: every cell on the
    // cycle evaluates to 0. Mark only the cycle suffix of the DFS path.
    let mut i = 0
    while i < ctx.stack.length() && ctx.stack[i] != key {
      i += 1
    }
    for j in i.. Value::Blank
    Some(Literal(lit)) => lit
    Some(Formula(src)) => {
      let expr = parse_formula(ctx, key, src)
      match expr {
        None => Value::Err(XlError::Value)
        Some(e) => {
          let saved_sheet = ctx.current_sheet
          ctx.current_sheet = @value.split_key(key).0
          ctx.stack.push(key)
          ctx.on_stack[key] = true
          let r = eval_expr(ctx, e)
          let _ = ctx.stack.pop()
          let _ = ctx.on_stack.remove(key)
          ctx.current_sheet = saved_sheet
          if ctx.circular.contains(key) { Value::Num(0.0) } else { r }
        }
      }
    }
  }
  ctx.cache[key] = v
  v
}

fn eval_expr(ctx : Ctx, e : @syntax.Expr) -> Value {
  match e {
    Lit(v) => v
    // A reference stays a 1x1 range so aggregates apply the reference
    // channel (ignore text/bool/blank) while literals coerce.
    Ref(addr) =>
      match cell_value(ctx, @value.sheet_key(ctx.current_sheet, addr)) {
        Range(r) => Value::Range(r)
        v => Value::Range({ rows: 1, cols: 1, cells: [v] })
      }
    // Cell values are immutable within one evaluation context, so a
    // materialized range can be shared by every formula referencing it.
    Range(lo, hi) => materialize_range(ctx, ctx.current_sheet, lo, hi)
    Sheet(sheet, inner) => {
      // 缺表:Excel 对不存在工作表的引用报 `#REF!`;引用文本里的表名不区分大小写。
      if sheet != "" && used_bounds(ctx, sheet) == (0, 0) {
        Value::Err(XlError::Ref)
      } else {
        let saved_sheet = ctx.current_sheet
        ctx.current_sheet = sheet
        let v = eval_expr(ctx, inner)
        ctx.current_sheet = saved_sheet
        v
      }
    }
    WholeCols(c1, c2) => {
      // 整列按该表 used-range 展开(空表 1 行),不做静默截断。
      let (mr, _) = used_bounds(ctx, ctx.current_sheet)
      let lo : CellAddr = { row: 1, col: c1, abs_row: false, abs_col: false }
      let hi : CellAddr = {
        row: if mr == 0 { 1 } else { mr },
        col: c2,
        abs_row: false,
        abs_col: false,
      }
      materialize_range(ctx, ctx.current_sheet, lo, hi)
    }
    WholeRows(r1, r2) => {
      // 整行按该表 used-range 展开(空表 1 列)。
      let (_, mc) = used_bounds(ctx, ctx.current_sheet)
      let lo : CellAddr = { row: r1, col: 1, abs_row: false, abs_col: false }
      let hi : CellAddr = {
        row: r2,
        col: if mc == 0 { 1 } else { mc },
        abs_row: false,
        abs_col: false,
      }
      materialize_range(ctx, ctx.current_sheet, lo, hi)
    }
    Name(n) => eval_name(ctx, n)
    Unary(op, sub) => {
      // Postfix % is not nesting-counted by the parser, so chains like
      // 1%%%... up to the length limit must fold iteratively, like binary
      // spines. Inside-out application order matches the recursive version.
      let ops : Array[@syntax.UnOp] = [op]
      let mut cur = sub
      while true {
        match cur {
          Unary(o2, sub2) => {
            ops.push(o2)
            cur = sub2
          }
          _ => break
        }
      }
      let mut v = scalarize(eval_expr(ctx, cur))
      let mut i = ops.length() - 1
      while i >= 0 {
        // Excel unary plus is an identity operator: +"3" stays text "3" and
        // +TRUE stays boolean TRUE; only unary minus / percent coerce.
        v = match ops[i] {
          Pos => v
          Neg =>
            match to_number(v) {
              Err(e) => Value::Err(e)
              Ok(d) => Value::Num(-d)
            }
          Percent =>
            match to_number(v) {
              Err(e) => Value::Err(e)
              Ok(d) => Value::Num(d / 100.0)
            }
        }
        i -= 1
      }
      v
    }
    Binary(op, l, r) => eval_binary(ctx, op, l, r)
    Call(name, args) => eval_call(ctx, name, args)
  }
}

fn pow_excel(a : Double, b : Double) -> Value {
  if a == 0.0 {
    if b == 0.0 {
      return Value::Err(XlError::Num)
    }
    if b < 0.0 {
      return Value::Err(XlError::Div0)
    }
    return Value::Num(0.0)
  }
  if a < 0.0 && b != b.trunc() {
    // Excel allows negative bases only when the exponent is an integer or the
    // reciprocal of an odd integer: (-8)^(1/3) = -2, (-8)^(2/3) = #NUM!.
    let inv = 1.0 / b
    let k = inv.round()
    if (inv - k).abs() > 1.0e-10 || k.trunc() != k || k % 2.0 == 0.0 {
      return Value::Err(XlError::Num)
    }
    let p = (-a).pow(b)
    if p.is_finite() {
      return Value::Num(-p)
    }
    return Value::Err(XlError::Num)
  }
  let p = a.pow(b)
  if p.is_finite() { Value::Num(p) } else { Value::Err(XlError::Num) }
}

fn eval_binary(
  ctx : Ctx,
  op : @syntax.BinOp,
  l : @syntax.Expr,
  r : @syntax.Expr
) -> Value {
  // All binary operators are left-associative, so chains form a left-deep
  // tree. Fold the left spine iteratively: an 8192-char formula must not
  // overflow the wasm-gc stack. Evaluation order (left subtree fully before
  // each right operand) and leftmost-error-wins are preserved.
  let spine : Array[(@syntax.BinOp, @syntax.Expr)] = []
  let mut cur = l
  let mut o = op
  let mut rhs = r
  while true {
    spine.push((o, rhs))
    match cur {
      Binary(o2, l2, r2) => {
        o = o2
        rhs = r2
        cur = l2
      }
      _ => break
    }
  }
  let mut acc = scalarize(eval_expr(ctx, cur))
  let mut i = spine.length() - 1
  while i >= 0 {
    let (o2, re) = spine[i]
    let rv = scalarize(eval_expr(ctx, re))
    acc = apply_binary(o2, acc, rv)
    i -= 1
  }
  acc
}

fn apply_binary(op : @syntax.BinOp, lv : Value, rv : Value) -> Value {
  // Error propagation: leftmost error wins.
  match lv {
    Err(e) => return Value::Err(e)
    _ => ()
  }
  match rv {
    Err(e) => return Value::Err(e)
    _ => ()
  }
  match op {
    Concat =>
      match to_text(scalarize(lv)) {
        Err(e) => Value::Err(e)
        Ok(a) =>
          match to_text(scalarize(rv)) {
            Err(e) => Value::Err(e)
            Ok(b) => Value::Text(a + b)
          }
      }
    Eq | Ne | Lt | Le | Gt | Ge =>
      match compare_values(lv, rv) {
        Err(e) => Value::Err(e)
        Ok(c) =>
          Value::Bool(
            match op {
              Eq => c == 0
              Ne => c != 0
              Lt => c < 0
              Le => c <= 0
              Gt => c > 0
              Ge => c >= 0
              _ => false
            },
          )
      }
    _ => {
      let a = match to_number(scalarize(lv)) {
        Ok(d) => d
        Err(e) => return Value::Err(e)
      }
      let b = match to_number(scalarize(rv)) {
        Ok(d) => d
        Err(e) => return Value::Err(e)
      }
      let d = match op {
        Add => a + b
        Sub => a - b
        Mul => a * b
        Div =>
          if b == 0.0 {
            return Value::Err(XlError::Div0)
          } else {
            a / b
          }
        Pow => return pow_excel(a, b)
        _ => return Value::Err(XlError::Value)
      }
      if d.is_finite() { Value::Num(d) } else { Value::Err(XlError::Num) }
    }
  }
}

fn eval_call(ctx : Ctx, name : String, args : Array[@syntax.Expr]) -> Value {
  match lookup_fn(name) {
    None => Value::Err(XlError::Name)
    Some(spec) => {
      if args.length() < spec.min || args.length() > spec.max {
        return Value::Err(XlError::Value)
      }
      let thunks : Array[Thunk] = args.map(a => () => eval_expr(ctx, a))
      (spec.call)(ctx, thunks)
    }
  }
}

/// 解析并求值单条公式(不写入网格)。引用会递归求值。
///
/// 解析失败返回 `Err(ParseError)`;求值阶段的错误值(如 `#DIV/0!`)作为 `Ok` 中的
/// `Value::Err` 返回。超过 Excel 公式限制(8192 字符 / 64 层嵌套)按解析失败处理。
pub fn eval_formula(
  formula : String,
  grid : Grid,
  options : EvalOptions
) -> Result[EvalOutput, @syntax.ParseError] {
  let expr = try @syntax.parse(formula) catch { e => return Err(e) }
  let ctx = new_ctx(grid, options, None)
  let v = eval_expr(ctx, expr)
  Ok({ value: scalar_output(v), circular: ctx.circular.length() > 0 })
}

/// 求值网格中某个限定地址(`A1` 或 `SHEET!A1`);空白格返回 `Blank`。
/// 循环引用语义与 `recalc` 一致。
pub fn eval_at_key(
  key : String,
  grid : Grid,
  options : EvalOptions
) -> EvalOutput {
  let (sheet, text) = @value.split_key(key)
  let k = match @value.parse_addr(text) {
    Some(a) => @value.sheet_key(sheet, a)
    None => key
  }
  let ctx = new_ctx(grid, options, None)
  let v = scalar_output(cell_value(ctx, k))
  { value: v, circular: ctx.circular.contains(k) }
}

/// 求值网格中某个单元格;空白格返回 `Blank`。循环引用语义与 `recalc` 一致。
pub fn eval_at(
  addr : CellAddr,
  grid : Grid,
  options : EvalOptions
) -> EvalOutput {
  eval_at_key(addr.key(), grid, options)
}

/// 按依赖关系重算整个网格(DFS + 记忆化 + 环检测)。
///
/// 循环引用复刻 Excel 默认(迭代计算关闭):环上单元格结果为 0,元数据 `circular: true`。
pub fn recalc(grid : Grid, options : EvalOptions) -> RecalcOutput {
  recalc_impl(grid, options, None).0
}