///|
/// DEX 注解与 encoded_value 语义解码:encoded_value 全 18 种 value_type、
/// encoded_array、encoded_annotation、annotation_item / annotation_set_item。
/// 规范依据:AOSP dex-format 的 annotation_directory_item / annotation_set_item /
/// annotation_item / encoded_annotation / encoded_value / encoded_array 章节。
/// 布局实证(2026-11-07):javac 21 + d8(build-tools 35.0.0)生成样本与
/// tvshell-debug / motionshell 真实 classes.dex 的 `dexdump -d -a` 输出逐值核对:
/// - format 字节 = (value_arg << 5) | value_type,value_arg = 字节数 - 1;
/// - 整型右对齐符号/零扩展(最小宽度),float/double **左对齐**、低位补零
///   (dex 格式原文 "zero-extended to the right",实测 3.5f 存 `60 40` 两字节);
/// - value_type 码表:byte=0x00 short=0x02 char=0x03 int=0x04 long=0x06
///   float=0x10 double=0x11 method_type=0x15 method_handle=0x16
///   string=0x17 type=0x18 field=0x19 method=0x1a enum=0x1b array=0x1c
///   annotation=0x1d null=0x1e boolean=0x1f。

///|
/// annotation_item.visibility:0=BUILD(编译期可见)、1=RUNTIME、2=SYSTEM(VM 注解)。
pub(all) enum AnnotationVisibility {
  VisibilityBuild
  VisibilityRuntime
  VisibilitySystem
}

///|
/// encoded_value 全 18 种 value_type 的结构化解码结果。
/// 引用类值(string/type/field/method/enum)在解码时按表解析为名字
/// (字段/方法/枚举沿用 smali 风格 `Lcls;->name:type` / `Lcls;->name(sig)ret`);
/// 整型/字符为扩展后的数值;float/double 为 IEEE-754 位模式还原值。
pub(all) enum EncodedValue {
  ValueByte(Int32)
  ValueShort(Int32)
  ValueChar(Int32)
  ValueInt(Int32)
  ValueLong(Int64)
  ValueFloat(Float)
  ValueDouble(Double)
  ValueString(String)
  ValueType(String)
  ValueField(String)
  ValueMethod(String)
  ValueEnum(String)
  /// DEX 038+:VALUE_METHOD_TYPE(proto 引用,`(params)ret` 文本)
  ValueMethodType(String)
  /// DEX 038+:VALUE_METHOD_HANDLE(method_handles 表引用,` ` 文本)
  ValueMethodHandle(String)
  ValueArray(Array[EncodedValue])
  ValueAnnotation(EncodedAnnotation)
  ValueNull
  ValueBoolean(Bool)
}

///|
/// 注解元素:元素名(name_idx 已解析)与值。
pub(all) struct AnnotationElement {
  name : String
  value : EncodedValue
}

///|
/// encoded_annotation:注解类型描述符 + 元素序列(保持文件内顺序,
/// 合法 DEX 中按元素名升序)。
pub(all) struct EncodedAnnotation {
  type_descriptor : String
  elements : Array[AnnotationElement]
}

///|
/// annotation_item:可见性 + encoded_annotation。
pub(all) struct Annotation {
  visibility : AnnotationVisibility
  annotation : EncodedAnnotation
}

///|
/// annotation_set_item:一个成员的注解集合(合法 DEX 中按类型描述符升序)。
pub(all) struct AnnotationSet {
  annotations : Array[Annotation]
}

///|
/// 字段注解目录项(annotation_directory_item.field_annotations)。
pub(all) struct FieldAnnotations {
  field_index : Int32
  annotations : AnnotationSet
}

///|
/// 方法注解目录项(annotation_directory_item.method_annotations)。
pub(all) struct MethodAnnotations {
  method_index : Int32
  annotations : AnnotationSet
}

///|
/// 方法参数注解目录项(annotation_directory_item.parameter_annotations →
/// annotation_set_ref_list)。`parameters` 与形参一一对应,空 `AnnotationSet`
/// 表示该参数无注解(ref 列表中偏移为 0)。
pub(all) struct ParameterAnnotations {
  method_index : Int32
  parameters : Array[AnnotationSet]
}

///|
/// annotation_directory_item 解码结果:class / field / method / parameter
/// 四类注解目录。字段/方法索引为 field_ids / method_ids 表索引。
pub(all) struct AnnotationsDirectory {
  class_annotations : AnnotationSet
  field_annotations : Array[FieldAnnotations]
  method_annotations : Array[MethodAnnotations]
  parameter_annotations : Array[ParameterAnnotations]
}

///|
/// 读取 n 字节小端无符号值(零扩展到 Int64),n ∈ 1..8。
fn read_sized_le(data : Bytes, pos : Int32, n : Int32) -> Int64 {
  let mut v = 0L
  let mut i = n - 1
  while i >= 0 {
    v = (v << 8) | (byte_at(data, pos + i).to_int64() & 0xffL)
    i = i - 1
  }
  v
}

///|
/// 读取 n 字节小端值并符号扩展到 Int64(整型最小宽度编码的还原)。
fn read_sized_signed(data : Bytes, pos : Int32, n : Int32) -> Int64 {
  let raw = read_sized_le(data, pos, n)
  let bits = n * 8
  if bits >= 64 {
    raw
  } else {
    let sign_bit = 1L << (bits - 1)
    if (raw & sign_bit) != 0L {
      raw | (-1L << bits)
    } else {
      raw
    }
  }
}

///|
/// float 32 位模式还原:payload 为高 n 字节、低位补零(左对齐)。
fn read_float_bits(data : Bytes, pos : Int32, n : Int32) -> Int32 {
  (read_sized_le(data, pos, n) << ((4 - n) * 8)).to_int()
}

///|
/// double 64 位模式还原:payload 为高 n 字节、低位补零(左对齐)。
fn read_double_bits(data : Bytes, pos : Int32, n : Int32) -> Int64 {
  read_sized_le(data, pos, n) << ((8 - n) * 8)
}

///|
/// 校验 `data[pos..pos+n]` 仍在界内,否则抛 `UnexpectedEof`。
fn need_bytes(data : Bytes, pos : Int32, n : Int32) -> Unit raise DexError {
  if pos < 0 || n < 0 || pos + n > data.length() {
    raise DexError::UnexpectedEof(pos)
  }
}

///|
/// 校验 unsigned 索引(Int32 位模式)落在 [0, size) 内,返回 Int32。
fn check_index(
  kind : TableKind,
  idx_raw : Int64,
  size : Int32,
) -> Int32 raise DexError {
  if idx_raw < 0L || idx_raw >= size.to_int64() {
    raise DexError::InvalidIndex(kind, idx_raw.to_int())
  }
  idx_raw.to_int()
}

///|
/// 读 uleb128;截断/溢出抛 `BadTableOffset(ClassDef, off)`。
fn uleb_ann(data : Bytes, off : Int32) -> (Int32, Int32) raise DexError {
  match try_uleb128(data, off) {
    Some(r) => r
    None => raise DexError::BadTableOffset(TableKind::ClassDef, off)
  }
}

///|
/// 解码 encoded_array 主体(uleb128 size + value×size),返回 (值列表, 结束偏移)。
fn decode_array_body(
  ctx : Ctx,
  data : Bytes,
  pos : Int32,
) -> (Array[EncodedValue], Int32) raise DexError {
  let (size, p0) = uleb_ann(data, pos)
  if size < 0 || size > data.length() {
    raise DexError::BadTableOffset(TableKind::ClassDef, pos)
  }
  let mut p = p0
  let out : Array[EncodedValue] = []
  for _ in 0.. (EncodedAnnotation, Int32) raise DexError {
  let (type_raw, p1) = uleb_ann(data, pos)
  let type_idx = check_index(
    TableKind::TypeId,
    type_raw.to_int64(),
    ctx.types.length(),
  )
  let (count, p2) = uleb_ann(data, p1)
  let mut p = p2
  if count < 0 || count > data.length() {
    raise DexError::BadTableOffset(TableKind::ClassDef, pos)
  }
  let elements : Array[AnnotationElement] = []
  for _ in 0.. (EncodedValue, Int32) raise DexError {
  need_bytes(data, pos, 1)
  let fmt = byte_at(data, pos)
  let vtype = fmt & 0x1f
  let size = (fmt >> 5) + 1
  if vtype == 0x00 {
    // VALUE_BYTE:1 字节符号扩展
    need_bytes(data, pos + 1, 1)
    (ValueByte(read_sized_signed(data, pos + 1, 1).to_int()), pos + 2)
  } else if vtype == 0x02 {
    // VALUE_SHORT:右对齐符号扩展(1..2 字节)
    if size > 2 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    (
      ValueShort(read_sized_signed(data, pos + 1, size).to_int()),
      pos + 1 + size,
    )
  } else if vtype == 0x03 {
    // VALUE_CHAR:右对齐零扩展(1..2 字节)
    if size > 2 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    (ValueChar(read_sized_le(data, pos + 1, size).to_int()), pos + 1 + size)
  } else if vtype == 0x04 {
    // VALUE_INT:右对齐符号扩展(1..4 字节)
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    (ValueInt(read_sized_signed(data, pos + 1, size).to_int()), pos + 1 + size)
  } else if vtype == 0x06 {
    // VALUE_LONG:右对齐符号扩展(1..8 字节)
    if size > 8 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    (ValueLong(read_sized_signed(data, pos + 1, size)), pos + 1 + size)
  } else if vtype == 0x10 {
    // VALUE_FLOAT:左对齐、低位补零(1..4 字节)
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    (
      ValueFloat(
        Float::reinterpret_from_int(read_float_bits(data, pos + 1, size)),
      ),
      pos + 1 + size,
    )
  } else if vtype == 0x11 {
    // VALUE_DOUBLE:左对齐、低位补零(1..8 字节)
    if size > 8 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    (
      ValueDouble(read_double_bits(data, pos + 1, size).reinterpret_as_double()),
      pos + 1 + size,
    )
  } else if vtype == 0x15 {
    // VALUE_METHOD_TYPE(DEX 038+,仅 call_site 上下文合法):proto 引用
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    let idx = check_index(
      TableKind::ProtoId,
      read_sized_le(data, pos + 1, size),
      ctx.protos.length(),
    )
    (ValueMethodType(fmt_proto_sig(ctx.protos[idx])), pos + 1 + size)
  } else if vtype == 0x16 {
    // VALUE_METHOD_HANDLE(DEX 038+):method_handles 表引用
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    let idx = check_index(
      TableKind::MethodHandle,
      read_sized_le(data, pos + 1, size),
      ctx.handles.length(),
    )
    (ValueMethodHandle(fmt_method_handle_ref(ctx, idx)), pos + 1 + size)
  } else if vtype == 0x17 {
    // VALUE_STRING:字符串池索引(1..4 字节零扩展)
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    let idx = check_index(
      TableKind::StringId,
      read_sized_le(data, pos + 1, size),
      ctx.strings.length(),
    )
    (ValueString(ctx.strings[idx]), pos + 1 + size)
  } else if vtype == 0x18 {
    // VALUE_TYPE:类型索引
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    let idx = check_index(
      TableKind::TypeId,
      read_sized_le(data, pos + 1, size),
      ctx.types.length(),
    )
    (ValueType(ctx.types[idx]), pos + 1 + size)
  } else if vtype == 0x19 {
    // VALUE_FIELD:字段引用
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    let idx = check_index(
      TableKind::FieldId,
      read_sized_le(data, pos + 1, size),
      ctx.fields.length(),
    )
    (ValueField(fmt_field_ref(ctx, idx)), pos + 1 + size)
  } else if vtype == 0x1a {
    // VALUE_METHOD:方法引用
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    let idx = check_index(
      TableKind::MethodId,
      read_sized_le(data, pos + 1, size),
      ctx.methods.length(),
    )
    (ValueMethod(fmt_method_ref(ctx, idx)), pos + 1 + size)
  } else if vtype == 0x1b {
    // VALUE_ENUM:枚举常量(字段引用)
    if size > 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    need_bytes(data, pos + 1, size)
    let idx = check_index(
      TableKind::FieldId,
      read_sized_le(data, pos + 1, size),
      ctx.fields.length(),
    )
    (ValueEnum(fmt_field_ref(ctx, idx)), pos + 1 + size)
  } else if vtype == 0x1c {
    // VALUE_ARRAY:内嵌 encoded_array
    if fmt >> 5 != 0 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    let (arr, endp) = decode_array_body(ctx, data, pos + 1)
    (ValueArray(arr), endp)
  } else if vtype == 0x1d {
    // VALUE_ANNOTATION:内嵌 encoded_annotation(无可见性字节)
    if fmt >> 5 != 0 {
      raise DexError::BadTableOffset(TableKind::ClassDef, pos)
    }
    let (ann, endp) = decode_encoded_annotation_body(ctx, data, pos + 1)
    (ValueAnnotation(ann), endp)
  } else if vtype == 0x1e {
    // VALUE_NULL
    (ValueNull, pos + 1)
  } else if vtype == 0x1f {
    // VALUE_BOOLEAN:值 = value_arg & 1,无 payload
    (ValueBoolean(((fmt >> 5) & 1) == 1), pos + 1)
  } else {
    // 0x01/0x05/0x07-0x0f/0x12-0x14 为保留码(0x15/0x16 已在上面单独处理)
    raise DexError::BadTableOffset(TableKind::ClassDef, pos)
  }
}

///|
/// 解码 annotation_item(u8 visibility + encoded_annotation)。
fn decode_annotation_item_body(
  ctx : Ctx,
  data : Bytes,
  off : Int32,
) -> Annotation raise DexError {
  need_bytes(data, off, 1)
  let vis = byte_at(data, off)
  let visibility = if vis == 0 {
    VisibilityBuild
  } else if vis == 1 {
    VisibilityRuntime
  } else if vis == 2 {
    VisibilitySystem
  } else {
    raise DexError::BadTableOffset(TableKind::ClassDef, off)
  }
  let (ann, _) = decode_encoded_annotation_body(ctx, data, off + 1)
  Annotation::{ visibility, annotation: ann, }
}

///|
/// 解码 annotation_set_item(u32 size + u32 offset×size)。
fn decode_annotation_set_body(
  ctx : Ctx,
  data : Bytes,
  off : Int32,
) -> AnnotationSet raise DexError {
  need_bytes(data, off, 4)
  let size = read_u32(data, off)
  if size < 0 || size > (data.length() - off - 4) / 4 {
    raise DexError::BadTableOffset(TableKind::ClassDef, off)
  }
  let annotations : Array[Annotation] = []
  for i in 0..= data.length() {
      raise DexError::BadTableOffset(TableKind::ClassDef, item_off)
    }
    annotations.push(decode_annotation_item_body(ctx, data, item_off))
  }
  AnnotationSet::{ annotations, }
}