///|
/// A zone-name to UTC-offset table used to resolve `TZID=` parameters.
///
/// Offsets are seconds east of UTC. iCalendar defines `TZID` case-sensitively,
/// but real feeds are sloppy (Google emits `Asia/Shanghai`, some Outlook
/// exports `ASIA/SHANGHAI`), so keys are normalised before comparison.
///
/// Only explicit fixed bindings are usable: UTC aliases, caller inserts, or
/// a provably fixed VTIMEZONE. Regional names are not guessed. Unsupported
/// feed declarations are retained as rejections and shadow default bindings.
#derive(Debug)
pub struct ZoneTable {
  entries : Map[String, Int32]
  rejected : Map[String, String]
}

///|
pub extend ZoneTable with @moonbitlang/core/debug.Debug::{to_repr}

///|
/// An empty table: every `TZID` fails to resolve until zones are added.
pub fn ZoneTable::empty() -> ZoneTable {
  { entries: Map([]), rejected: Map([]), }
}

///|
/// Intrinsically fixed UTC aliases only. Regional names need an explicit
/// caller binding or a provably fixed feed declaration.
pub fn ZoneTable::builtin_common() -> ZoneTable {
  let zones : Map[String, Int32] = { "UTC": 0, "GMT": 0, "Z": 0 }
  { entries: zones, rejected: Map([]), }
}

///|
/// Normalise a zone name for table keys and lookups.
fn normalize_zone_id(tzid : String) -> String {
  tzid.to_string_view().trim(chars=" \t".to_string_view()).to_upper().to_owned()
}

///|
/// Explicitly bind a fixed offset. Later caller inserts win and remove a
/// prior rejection. This is an assertion by the caller, not IANA resolution.
pub fn ZoneTable::insert(
  self : ZoneTable,
  tzid : String,
  seconds : Int32,
) -> Unit {
  let key = normalize_zone_id(tzid)
  self.entries[key] = seconds
  self.rejected.remove(key)
}

///|
/// UTC defaults overridden by feed declarations, including rejections.
/// A malformed same-name declaration must not fall back to a default.
pub fn ZoneTable::with_builtin(feed : ZoneTable) -> ZoneTable {
  let table = ZoneTable::builtin_common()
  for name, seconds in feed.entries {
    table.entries[name] = seconds
  }
  for name, reason in feed.rejected {
    table.entries.remove(name)
    table.rejected[name] = reason
  }
  table
}

///|
/// Look a zone up, case-insensitively; the most recently inserted match wins.
pub fn ZoneTable::lookup(self : ZoneTable, tzid : String) -> Int32? {
  self.entries.get(normalize_zone_id(tzid))
}

///|
/// Parse an iCalendar UTC-offset value (RFC 5545 §3.3.14): `+0800`,
/// `-0500`, `+0530`, `+053030`, or a bare `+08` (a deliberate lenience —
/// the RFC grammar requires the minutes). Raises [`ParseError`] on
/// anything else: an offset whose shape or components are not read whole
/// would silently shift every event in a calendar, which is how the
/// pre-S12 half-read of `+05:30` lost half an hour.
///
/// # Example
/// ```mbt nocheck
/// fn test_example() raise {
///   assert_eq(
///     @model.parse_utc_offset("+0530", line_no=1, raw="+0530"),
///     5 * 3600 + 30 * 60,
///   )
///   assert_eq(
///     @model.parse_utc_offset("-0800", line_no=1, raw="-0800"),
///     -(8 * 3600),
///   )
/// }
/// ```
pub fn parse_utc_offset(
  text : String,
  line_no~ : Int32,
  raw~ : String,
) -> Int32 raise {
  let v = text.to_string_view()
  let n = v.length()
  // Sign, two-digit hour, optional two-digit minute, optional two-digit
  // second — and nothing else. The exact length is the whole check: a
  // colon form or a stray tail used to be read by its first five
  // characters with the rest silently dropped.
  if n != 3 && n != 5 && n != 7 {
    raise @text.ParseError::BadLine(
      line_no~,
      line=raw,
      message="UTC offset must be +hh, +hhmm, or +hhmmss: \{text}",
    )
  }
  let sign = if v[0] == '-' {
    -1
  } else if v[0] == '+' {
    1
  } else {
    raise @text.ParseError::BadLine(
      line_no~,
      line=raw,
      message="UTC offset needs a sign: \{text}",
    )
  }
  let hours = digits(v, 1, 2)
  let minutes = if n >= 5 { digits(v, 3, 2) } else { Some(0) }
  let seconds = if n == 7 { digits(v, 5, 2) } else { Some(0) }
  match (hours, minutes, seconds) {
    (Some(h), Some(m), Some(s)) =>
      // RFC 5545 §3.3.14 bounds every component: hour at 23, minute and
      // second at 59. An hour past 23 is not an offset any zone declares;
      // accepting it would shift a whole calendar by imaginary hours.
      if h > 23 || m > 59 || s > 59 {
        raise @text.ParseError::BadLine(
          line_no~,
          line=raw,
          message="UTC offset component out of range: \{text}",
        )
      } else {
        sign * (h * 3600 + m * 60 + s)
      }
    _ =>
      raise @text.ParseError::BadLine(
        line_no~,
        line=raw,
        message="malformed UTC offset: \{text}",
      )
  }
}

///|
/// Collect provably fixed feed declarations without interpreting dynamic
/// transitions. Invalid or unsupported declarations shadow defaults and
/// fail only when a date property references their TZID. A fixed STANDARD
/// has a local DTSTART and equal FROM/TO offsets, with no transition rules.
///
/// # Example
/// ```mbt nocheck
/// fn test_example() raise {
///   let roots = @model.parse_components([
///     "BEGIN:VCALENDAR", "BEGIN:VTIMEZONE", "TZID:MY-ZONE", "BEGIN:STANDARD", "DTSTART:19700101T000000",
///     "TZOFFSETFROM:+0930", "TZOFFSETTO:+0930", "END:STANDARD", "END:VTIMEZONE", "END:VCALENDAR",
///   ])
///   let table = @model.build_zone_table(roots)
///   assert_eq(table.lookup("my-zone"), Some(9 * 3600 + 30 * 60))
/// }
/// ```
pub fn build_zone_table(roots : Array[Component]) -> ZoneTable {
  let table = ZoneTable::empty()
  for root in roots {
    for child in root.children {
      if child.kind == "VTIMEZONE" {
        register_vtimezone(table, child)
      }
    }
  }
  table
}

///|
fn register_vtimezone(table : ZoneTable, vtz : Component) -> Unit {
  let ids = vtz.properties_named("TZID")
  if ids.length() != 1 {
    for id in ids {
      let key = normalize_zone_id(id.value)
      table.entries.remove(key)
      table.rejected[key] = "VTIMEZONE has duplicate TZID properties"
    }
    return
  }
  let tzid = ids[0]
  let key = normalize_zone_id(tzid.value)
  let fixed = fixed_vtimezone(vtz) catch { _ => None }
  // Duplicate definitions cannot establish an unambiguous fixed binding.
  if table.entries.contains(key) || table.rejected.contains(key) {
    table.entries.remove(key)
    table.rejected[key] = "conflicting VTIMEZONE declarations"
  } else {
    match fixed {
      Some(seconds) => table.insert(key, seconds)
      None => table.rejected[key] = "VTIMEZONE is dynamic or not provably fixed"
    }
  }
}

///|
/// Why a feed declaration cannot be used as a fixed binding, if present.
pub fn ZoneTable::rejection_reason(self : ZoneTable, tzid : String) -> String? {
  self.rejected.get(normalize_zone_id(tzid))
}

///|
fn fixed_vtimezone(vtz : Component) -> Int32? raise {
  if vtz.properties_named("TZID").length() != 1 {
    return None
  }
  let mut fixed : Int32? = None
  let mut seen = false
  for child in vtz.children {
    if child.kind == "DAYLIGHT" {
      return None
    }
    if child.kind != "STANDARD" {
      return None
    }
    seen = true
    for name in ["DTSTART", "TZOFFSETFROM", "TZOFFSETTO"] {
      if child.properties_named(name).length() != 1 {
        return None
      }
    }
    // Transition recurrence machinery is outside the fixed subset.
    if child.properties_named("RRULE").length() > 0 ||
      child.properties_named("RDATE").length() > 0 {
      return None
    }
    let start = parse_date_time(
      child.property("DTSTART").unwrap(),
      ZoneTable::empty(),
    )
    if start.all_day || !start.is_floating() {
      return None
    }
    let from_line = child.property("TZOFFSETFROM").unwrap()
    let to_line = child.property("TZOFFSETTO").unwrap()
    let from_seconds = parse_utc_offset(
      from_line.value,
      line_no=from_line.line_no,
      raw=from_line.value,
    )
    let seconds = parse_utc_offset(
      to_line.value,
      line_no=to_line.line_no,
      raw=to_line.value,
    )
    if from_seconds != seconds {
      return None
    }
    match fixed {
      Some(previous) => if previous != seconds { return None }
      None => fixed = Some(seconds)
    }
  }
  if seen {
    fixed
  } else {
    None
  }
}