///|
/// 注解目录(annotation_directory_item)与静态初值(static_values_off → encoded_array)
/// 的公开入口。全部入口自含:调用方传原始 DEX 字节 `data`(所有权归调用方,不缓存)
/// 与 class_defs 表位置;内部复用 `read_ctx`(与 `parse` 相同的头部校验 + 六表读取),
/// 不解码 class_def / code_item,因此比 `parse` 轻量。
/// 批量遍历全类时请用 `annotations_index(data)` 建一次索引再复用查询方法:
/// 单次查询入口每次都会重建一次六表,对 N 个类逐类调用即 O(N × 表规模),
/// 在真实规模 DEX 上会退化为分钟级;CLI 的 summary / --json 已接线索引。
/// 多 dex 组合维持 `MultiDexNotMerged` 语义:本文件只处理单个 DEX 字节流。

///|
/// 读取 class_defs[class_index] 的 annotations_off(+20)与 static_values_off(+28)。
/// `class_index` 为 class_defs 表位置(与 `DexFile::methods` 参数同义);
/// 越界抛 `InvalidIndex(ClassDef, ...)`,表损坏抛 `BadTableOffset`。
fn class_aux_offs(
  data : Bytes,
  class_index : Int32,
) -> (Int32, Int32) raise DexError {
  let file_size = data.length()
  let class_defs_size = read_u32(data, 0x60)
  let class_defs_off = read_u32(data, 0x64)
  if class_index < 0 || class_index >= class_defs_size {
    raise DexError::InvalidIndex(TableKind::ClassDef, class_index)
  }
  let base = class_defs_off + class_index * 32
  if base < 0x70 || base + 32 > file_size {
    raise DexError::BadTableOffset(TableKind::ClassDef, class_defs_off)
  }
  let annotations_off = read_u32(data, base + 20)
  let static_values_off = read_u32(data, base + 28)
  for off in [annotations_off, static_values_off] {
    if off != 0 && (off < 0x70 || off >= file_size) {
      raise DexError::BadTableOffset(TableKind::ClassDef, off)
    }
  }
  (annotations_off, static_values_off)
}

///|
/// 注解 / 静态初值索引(加法性新增,2026-11-09):一次 `read_ctx` 建立解析上下文,
/// 之后按 class_defs 位置 O(1) 局部解码,避免批量查询时逐类重建六张表。
///
/// - 构建:`annotations_index(data)` 执行与 `parse` 相同的头部校验与六表读取;
/// - 查询:`AnnotationsIndex::class_annotations` / `::static_values` 与同名全局
///   入口语义逐字一致(含 `InvalidIndex(ClassDef, ...)`、`BadTableOffset` 等错误);
/// - 复杂度:构建 O(表规模) 一次,每次查询只解码该类自身的注解目录 / encoded_array;
/// - 逐 dex 使用,不缓存、不跨 dex 合并(`MultiDexNotMerged` 口径维持);
/// - 不透明 `pub struct`、私有字段,构建后视为只读;纯函数,无全局状态,可并发。
/// - 实现注记:`Ctx` 为包内私有类型,公开结构不得直接依赖它;此处平铺保存其
///   公开类型的表字段,查询时在包内重组 `Ctx`(只搬表引用,不复制表内容)。
pub struct AnnotationsIndex {
  data : Bytes
  strings : Array[String]
  types : Array[String]
  protos : Array[ProtoId]
  fields : Array[FieldDef]
  methods : Array[MethodDef]
  handles : Array[MethodHandleItem]
  call_sites : Array[CallSiteItem]
}

///|
/// 查询时重组包内解析上下文(只搬表引用,O(1),不复制表内容)。
fn AnnotationsIndex::ctx(self : AnnotationsIndex) -> Ctx {
  Ctx::{
    strings: self.strings,
    types: self.types,
    protos: self.protos,
    fields: self.fields,
    methods: self.methods,
    handles: self.handles,
    call_sites: self.call_sites,
  }
}

///|
/// 为单份 DEX 字节建立注解索引(一次全表读取 + 头部校验)。
/// 批量遍历所有类时只调用一次,再复用两个查询方法。
pub fn annotations_index(data : Bytes) -> AnnotationsIndex raise DexError {
  let ctx = read_ctx(data)
  AnnotationsIndex::{
    data,
    strings: ctx.strings,
    types: ctx.types,
    protos: ctx.protos,
    fields: ctx.fields,
    methods: ctx.methods,
    handles: ctx.handles,
    call_sites: ctx.call_sites,
  }
}

///|
/// 索引视图:解析指定类的注解目录;`annotations_off == 0` 直接返回 `None`,
/// 不重复解码任何索引表。错误同全局 `class_annotations`。
pub fn AnnotationsIndex::class_annotations(
  self : AnnotationsIndex,
  class_index : Int32,
) -> AnnotationsDirectory? raise DexError {
  let (annotations_off, _) = class_aux_offs(self.data, class_index)
  if annotations_off == 0 {
    None
  } else {
    Some(
      decode_annotations_directory_body(self.ctx(), self.data, annotations_off),
    )
  }
}

///|
/// 索引视图:解析指定类的静态字段初值;`static_values_off == 0` 返回空数组。
/// 错误同全局 `static_values`。
pub fn AnnotationsIndex::static_values(
  self : AnnotationsIndex,
  class_index : Int32,
) -> Array[EncodedValue] raise DexError {
  let (_, static_values_off) = class_aux_offs(self.data, class_index)
  if static_values_off == 0 {
    return []
  }
  let (values, _) = decode_array_body(self.ctx(), self.data, static_values_off)
  values
}

///|
/// 解码 annotation_directory_item 主体:
/// u32 class_annotations_off + 3×u32 size + 12 字节条目×(fields + methods + params)。
fn decode_annotations_directory_body(
  ctx : Ctx,
  data : Bytes,
  off : Int32,
) -> AnnotationsDirectory raise DexError {
  need_bytes(data, off, 16)
  let class_annotations_off = read_u32(data, off)
  let fields_size = read_u32(data, off + 4)
  let methods_size = read_u32(data, off + 8)
  let params_size = read_u32(data, off + 12)
  for size in [fields_size, methods_size, params_size] {
    if size < 0 || size > (data.length() - off - 16) / 12 {
      raise DexError::BadTableOffset(TableKind::ClassDef, off)
    }
  }
  let class_annotations = if class_annotations_off == 0 {
    AnnotationSet::{ annotations: [], }
  } else {
    decode_annotation_set_body(ctx, data, class_annotations_off)
  }
  let field_annotations : Array[FieldAnnotations] = []
  let mut pos = off + 16
  for _ in 0..= ctx.fields.length() {
      raise DexError::InvalidIndex(TableKind::FieldId, field_index)
    }
    let annotations = if set_off == 0 {
      AnnotationSet::{ annotations: [], }
    } else {
      decode_annotation_set_body(ctx, data, set_off)
    }
    field_annotations.push(FieldAnnotations::{ field_index, annotations, })
  }
  let method_annotations : Array[MethodAnnotations] = []
  for _ in 0..= ctx.methods.length() {
      raise DexError::InvalidIndex(TableKind::MethodId, method_index)
    }
    let annotations = if set_off == 0 {
      AnnotationSet::{ annotations: [], }
    } else {
      decode_annotation_set_body(ctx, data, set_off)
    }
    method_annotations.push(MethodAnnotations::{ method_index, annotations, })
  }
  let parameter_annotations : Array[ParameterAnnotations] = []
  for _ in 0..= ctx.methods.length() {
      raise DexError::InvalidIndex(TableKind::MethodId, method_index)
    }
    // annotation_set_ref_list:u32 size + u32 set_off×size(0 = 该参数无注解)
    need_bytes(data, ref_list_off, 4)
    let count = read_u32(data, ref_list_off)
    if count < 0 || count > (data.length() - ref_list_off - 4) / 4 {
      raise DexError::BadTableOffset(TableKind::ClassDef, ref_list_off)
    }
    let parameters : Array[AnnotationSet] = []
    for j in 0.. AnnotationsDirectory? raise DexError {
  let index = annotations_index(data)
  index.class_annotations(class_index)
}

///|
/// 解码指定偏移处的 annotation_set_item。`off` 为文件内偏移(0x70 起)。
/// 错误同 `class_annotations`。
pub fn annotation_set(
  data : Bytes,
  off : Int32,
) -> AnnotationSet raise DexError {
  let ctx = read_ctx(data)
  if off < 0x70 || off >= data.length() {
    raise DexError::BadTableOffset(TableKind::ClassDef, off)
  }
  decode_annotation_set_body(ctx, data, off)
}

///|
/// 解码指定偏移处的 annotation_item(u8 visibility + encoded_annotation)。
/// 错误同 `class_annotations`。
pub fn annotation_item(data : Bytes, off : Int32) -> Annotation raise DexError {
  let ctx = read_ctx(data)
  if off < 0x70 || off >= data.length() {
    raise DexError::BadTableOffset(TableKind::ClassDef, off)
  }
  decode_annotation_item_body(ctx, data, off)
}

///|
/// 解码指定偏移处的 encoded_array(uleb128 size + encoded_value×size)。
/// 注解默认值(AnnotationDefault)、静态初值等场景的通用入口。
/// 错误同 `class_annotations`。
pub fn encoded_array(
  data : Bytes,
  off : Int32,
) -> Array[EncodedValue] raise DexError {
  let ctx = read_ctx(data)
  if off < 0x70 || off >= data.length() {
    raise DexError::BadTableOffset(TableKind::ClassDef, off)
  }
  let (values, _) = decode_array_body(ctx, data, off)
  values
}

///|
/// 解析指定类的静态字段初值(class_def.static_values_off → encoded_array)。
/// 加密字符串入口:静态常量字符串/整型初值在此展开为结构化常量值。
///
/// - 返回:与 `ClassDef::static_fields` **前缀**一一对应的值数组;
///   DEX 只编码非默认值的前缀,尾部默认值被省略(返回数组长度 ≤ static_fields 长度)。
///   `static_values_off == 0` 时返回空数组。
/// - 错误:同 `class_annotations`。
/// - 批量:同 `class_annotations`,遍历全类请用 `annotations_index(data)`。
pub fn static_values(
  data : Bytes,
  class_index : Int32,
) -> Array[EncodedValue] raise DexError {
  let index = annotations_index(data)
  index.static_values(class_index)
}