///|
/// debug_info_item 状态机展开视图(W5)。
///
/// 既有 `parse_code_item` 保留 debug 流原始字节(B8 深度限制),
/// 本文件按 DEX 规范 debug_info_item 状态机逐 opcode 展开为
/// `DebugEvent` 序列,含行号推进、局部变量、文件切换等信息。
/// 不改既有 raw `debug_info` 字段与 `BadDebugInfo` 触发口径(P4/P5 防火墙律)。
///
/// opcode 0x00–0xFF 规范:
///   - 0x00 DBG_END_SEQUENCE(终止,不产事件)
///   - 0x01 DBG_ADVANCE_PC(uleb128 addr_diff)
///   - 0x02 DBG_ADVANCE_LINE(sleb128 line_diff)
///   - 0x03 DBG_START_LOCAL(uleb reg, uleb name_idx, uleb type_idx)
///   - 0x04 DBG_START_LOCAL_EXTENDED(uleb reg, uleb name_idx, uleb type_idx, uleb sig_idx)
///   - 0x05 DBG_START_LOCAL(Same as 0x03 but end of scope; deprecated alias)
///   - 0x06 DBG_END_LOCAL(uleb reg)
///   - 0x07 DBG_RESTART_LOCAL(uleb reg)
///   - 0x08 DBG_SET_PROLOGUE_END
///   - 0x09 DBG_SET_EPILOGUE_BEGIN
///   - 0x0A DBG_SET_FILE(uleb name_idx)
///   - 0x0B reserved → BadDebugInfo
///   - 0x0C–0xFF special opcode: line += DBG_LINE_BASE + (adj % DBG_LINE_RANGE),
///     address += adj / DBG_LINE_RANGE(adj = opcode - 0x0A)
/// DBG_LINE_BASE = -4, DBG_LINE_RANGE = 15, DBG_FIRST_SPECIAL = 0x0A
///
/// 名字/类型经 string_ids / type_ids 表解析(MUTF-8)。
/// 越界/截断/坏 uleb/sleb → BadDebugInfo,无 panic。

///|
/// 当前文件名字符串表已解析(name_idx → String)。
priv struct StringCache {
  names : Array[String?]
}

///|
/// 状态机事件。
pub(all) enum DebugEvent {
  AdvancePc(Int32)
  AdvanceLine(Int32)
  StartLocal(Int32, String, String) // (reg, name, type)
  StartLocalExtended(Int32, String, String, String) // (reg, name, type, sig)
  EndLocal(Int32)
  RestartLocal(Int32)
  SetPrologueEnd
  SetEpilogueBegin
  SetFile(String)
}

///|
/// debug_info_item 展开视图。
pub(all) struct DebugInfoView {
  line_start : Int32
  parameter_names : Array[String?] // NO_INDEX(0xFFFFFFFF) → None
  events : Array[DebugEvent]
}

///|
/// 展开 `code_off` 处 code_item 的 debug_info 流为 `DebugInfoView`。
/// - `data`:完整 DEX 字节(需访问 string_ids / type_ids 表)。
/// - `code_off`:code_item 的字节偏移。
/// - debug_info_off == 0 时返回空 events(方法无 debug info)。
/// - 越界/截断/坏 uleb/sleb → BadDebugInfo;索引越界 → InvalidIndex。
pub fn debug_info_view(
  data : Bytes,
  code_off : Int32,
) -> DebugInfoView raise DexError {
  // validate code_off
  if code_off < 0x70 || code_off + 16 > data.length() {
    raise DexError::BadDebugInfo(code_off, "code_off out of bounds")
  }
  let debug_info_off = read_u32(data, code_off + 8)
  if debug_info_off == 0 {
    return DebugInfoView::{ line_start: 0, parameter_names: [], events: [], }
  }
  if debug_info_off < 0x70 || debug_info_off >= data.length() {
    raise DexError::BadDebugInfo(debug_info_off, "debug_info_off out of bounds")
  }
  let cache = build_string_cache(data)
  parse_debug_stream(data, debug_info_off, cache)
}

///|
/// 构建 string_ids + type_ids 的 String 缓存,用于 debug opcode 的名字/类型解析。
fn build_string_cache(data : Bytes) -> StringCache {
  let str_size = read_u32(data, 0x38)
  let str_off = read_u32(data, 0x3C)
  let names : Array[String?] = []
  // Pre-resolve string table
  for i in 0..= data.length() {
      names.push(None)
    } else {
      match try_uleb128(data, s_off) {
        Some((_, body_off)) =>
          match try_mutf8(data, body_off) {
            Some((s, _)) => names.push(Some(s))
            _ => names.push(None)
          }
        _ => names.push(None)
      }
    }
  }
  StringCache::{ names, }
}

///|
/// type table: type_idx → descriptor string → resolved string table name.
fn type_name(
  data : Bytes,
  cache : StringCache,
  type_idx : Int32,
) -> String raise DexError {
  let type_size = read_u32(data, 0x40)
  let type_off = read_u32(data, 0x44)
  if type_idx < 0 || type_idx >= type_size {
    raise DexError::InvalidIndex(TableKind::TypeId, type_idx)
  }
  let string_idx = read_u32(data, type_off + type_idx * 4)
  if string_idx < 0 || string_idx >= cache.names.length() {
    raise DexError::InvalidIndex(TableKind::StringId, string_idx)
  }
  match cache.names[string_idx] {
    Some(s) => s
    None => raise DexError::InvalidIndex(TableKind::StringId, string_idx)
  }
}

///|
/// string table: name_idx → string。name_idx == NO_INDEX(-1) → "?" 占位。
fn string_name(
  cache : StringCache,
  name_idx : Int32,
  dbg_off : Int32,
) -> String raise DexError {
  let count = cache.names.length()
  if name_idx < -1 || name_idx >= count {
    raise DexError::BadDebugInfo(
      dbg_off,
      "name_idx " + name_idx.to_string() + " out of range",
    )
  }
  if name_idx == -1 {
    return "?" // NO_INDEX
  }
  match cache.names[name_idx] {
    Some(s) => s
    None =>
      raise DexError::BadDebugInfo(
        dbg_off,
        "name_idx " + name_idx.to_string() + " invalid",
      )
  }
}

///|
/// 核心状态机解析。与 `debug_stream_len` 同构但收集结构化事件。
/// DBG_LINE_BASE = -4, DBG_LINE_RANGE = 15, DBG_FIRST_SPECIAL = 0x0A.
fn parse_debug_stream(
  data : Bytes,
  dbg_off : Int32,
  cache : StringCache,
) -> DebugInfoView raise DexError {
  let mut pos = dbg_off
  // Prologue
  let (raw_line, p1) = uleb_debug(data, pos, dbg_off)
  let line_start = raw_line - 1 // uleb128p1
  pos = p1
  let (param_size_raw, p2) = uleb_debug(data, pos, dbg_off)
  let param_size = param_size_raw - 1
  pos = p2
  let params : Array[String?] = []
  for _ in 0..= cache.names.length() {
        params.push(None)
      } else {
        params.push(cache.names[si])
      }
    }
    pos = pn
  }
  // State machine
  let events : Array[DebugEvent] = []
  let mut done = false
  let mut current_line = line_start
  let mut current_addr = 0
  while !done {
    if pos >= data.length() {
      raise DexError::BadDebugInfo(dbg_off, "debug_info stream truncated")
    }
    let op = byte_at(data, pos)
    pos = pos + 1
    if op == 0x00 {
      done = true
    } else if op == 0x01 {
      let (delta, p) = uleb_debug(data, pos, dbg_off)
      current_addr = current_addr + delta
      events.push(DebugEvent::AdvancePc(delta))
      pos = p
    } else if op == 0x02 {
      match try_sleb128(data, pos) {
        Some((delta, p)) => {
          current_line = current_line + delta
          events.push(DebugEvent::AdvanceLine(delta))
          pos = p
        }
        None =>
          raise DexError::BadDebugInfo(
            dbg_off,
            "malformed sleb128 at " + pos.to_string(),
          )
      }
    } else if op == 0x03 || op == 0x05 {
      let (reg, q1) = uleb_debug(data, pos, dbg_off)
      let (name_idx, q2) = uleb_debug(data, q1, dbg_off)
      let (type_idx, q3) = uleb_debug(data, q2, dbg_off)
      let name = string_name(cache, name_idx, dbg_off)
      let ty = type_name(data, cache, type_idx)
      events.push(DebugEvent::StartLocal(reg, name, ty))
      pos = q3
    } else if op == 0x04 {
      let (reg, q1) = uleb_debug(data, pos, dbg_off)
      let (name_idx, q2) = uleb_debug(data, q1, dbg_off)
      let (type_idx, q3) = uleb_debug(data, q2, dbg_off)
      let (sig_idx, q4) = uleb_debug(data, q3, dbg_off)
      let name = string_name(cache, name_idx, dbg_off)
      let ty = type_name(data, cache, type_idx)
      let sig = string_name(cache, sig_idx, dbg_off)
      events.push(DebugEvent::StartLocalExtended(reg, name, ty, sig))
      pos = q4
    } else if op == 0x06 {
      let (reg, p) = uleb_debug(data, pos, dbg_off)
      events.push(DebugEvent::EndLocal(reg))
      pos = p
    } else if op == 0x07 {
      let (reg, p) = uleb_debug(data, pos, dbg_off)
      events.push(DebugEvent::RestartLocal(reg))
      pos = p
    } else if op == 0x08 {
      events.push(DebugEvent::SetPrologueEnd)
    } else if op == 0x09 {
      events.push(DebugEvent::SetEpilogueBegin)
    } else if op == 0x0A {
      let (name_idx, p) = uleb_debug(data, pos, dbg_off)
      let name = string_name(cache, name_idx, dbg_off)
      events.push(DebugEvent::SetFile(name))
      pos = p
    } else if op == 0x0B {
      raise DexError::BadDebugInfo(dbg_off, "reserved debug opcode 0x0B")
    } else {
      // Special opcode: 0x0C–0xFF
      let adj = op - 0x0A
      let line_delta = -4 + adj % 15
      let addr_delta = adj / 15
      current_line = current_line + line_delta
      current_addr = current_addr + addr_delta
      events.push(DebugEvent::AdvancePc(addr_delta))
      if line_delta != 0 {
        events.push(DebugEvent::AdvanceLine(line_delta))
      }
    }
  }
  DebugInfoView::{ line_start, parameter_names: params, events, }
}