///|
/// Electrical metadata: actuator and sensor specifications, PCB envelopes, wire
/// runs, and the power/IO budget derived from a component tree.
///
/// These records are additive; geometry and kinematics stay in `Component` and
/// `BodyPart`.

///|
/// The kind of actuator a component represents.
pub(all) enum ActuatorKind {
  Stepper
  Bldc
  Servo
  Hub
}

///|
/// Electrical and mechanical ratings for one actuator.
pub(all) struct ActuatorSpec {
  kind : ActuatorKind
  model : String
  voltage_v : Double
  current_rated_a : Double
  current_stall_a : Double
  torque_rated_nm : Double
  driver : String
  /// Control interface, e.g. `"STEP/DIR"`, `"CAN"`, `"PWM"`.
  interface : String
  /// Feedback, e.g. `"none"` or `"magnetic 14-bit"`.
  encoder : String
}

///|
pub fn ActuatorSpec::new(
  kind : ActuatorKind,
  model~ : String = "",
  voltage_v~ : Double = 0.0,
  current_rated_a~ : Double = 0.0,
  current_stall_a~ : Double = 0.0,
  torque_rated_nm~ : Double = 0.0,
  driver~ : String = "",
  interface~ : String = "",
  encoder~ : String = "",
) -> ActuatorSpec {
  {
    kind,
    model,
    voltage_v,
    current_rated_a,
    current_stall_a,
    torque_rated_nm,
    driver,
    interface,
    encoder,
  }
}

///|
/// The kind of sensor a component represents.
pub(all) enum SensorKind {
  LimitSwitch
  Encoder
  Imu
  Camera
  Force
}

///|
/// Electrical and measuring characteristics for one sensor.
pub(all) struct SensorSpec {
  kind : SensorKind
  model : String
  /// Electrical interface, e.g. `"GPIO"`, `"I2C"`, `"SPI"`, `"USB"`.
  interface : String
  voltage_v : Double
  current_ma : Double
  range : String
  resolution : String
}

///|
pub fn SensorSpec::new(
  kind : SensorKind,
  model~ : String = "",
  interface~ : String = "",
  voltage_v~ : Double = 0.0,
  current_ma~ : Double = 0.0,
  range~ : String = "",
  resolution~ : String = "",
) -> SensorSpec {
  { kind, model, interface, voltage_v, current_ma, range, resolution, }
}

///|
/// One component placement from a KiCad position file or equivalent.
pub(all) struct PcbPlacement {
  reference : String
  value : String
  footprint : String
  x_mm : Double
  y_mm : Double
  rotation_deg : Double
  side : String
}

///|
pub fn PcbPlacement::new(
  reference~ : String = "",
  value~ : String = "",
  footprint~ : String = "",
  x_mm~ : Double = 0.0,
  y_mm~ : Double = 0.0,
  rotation_deg~ : Double = 0.0,
  side~ : String = "",
) -> PcbPlacement {
  { reference, value, footprint, x_mm, y_mm, rotation_deg, side, }
}

///|
/// A PCB envelope: outline, thickness, mounting holes, height limit, and the
/// connectors that must be reachable.
pub(all) struct PcbSpec {
  model : String
  length_mm : Double
  width_mm : Double
  thickness_mm : Double
  mounting_holes : Int32
  mounting_hole_diam_mm : Double
  max_component_height_mm : Double
  connectors : Array[String]
  placements : Array[PcbPlacement]
}

///|
pub fn PcbSpec::new(
  model~ : String = "",
  length_mm~ : Double = 0.0,
  width_mm~ : Double = 0.0,
  thickness_mm~ : Double = 1.6,
  mounting_holes~ : Int32 = 4,
  mounting_hole_diam_mm~ : Double = 2.7,
  max_component_height_mm~ : Double = 0.0,
  connectors~ : Array[String] = [],
  placements~ : Array[PcbPlacement] = [],
) -> PcbSpec {
  {
    model,
    length_mm,
    width_mm,
    thickness_mm,
    mounting_holes,
    mounting_hole_diam_mm,
    max_component_height_mm,
    connectors,
    placements,
  }
}

///|
/// One point-to-point cable run.
pub(all) struct WireRun {
  name : String
  from_component : String
  from_port : String
  to_component : String
  to_port : String
  gauge_awg : Int32
  length_mm : Double
  notes : String
}

///|
pub fn WireRun::new(
  name : String,
  from_component~ : String,
  from_port~ : String,
  to_component~ : String,
  to_port~ : String,
  gauge_awg~ : Int32 = 24,
  length_mm~ : Double = 0.0,
  notes~ : String = "",
) -> WireRun {
  {
    name,
    from_component,
    from_port,
    to_component,
    to_port,
    gauge_awg,
    length_mm,
    notes,
  }
}

///|
/// One actuator line in the power budget.
pub(all) struct ActuatorLine {
  path : String
  spec : ActuatorSpec
}

///|
/// One sensor line in the power budget.
pub(all) struct SensorLine {
  path : String
  spec : SensorSpec
}

///|
/// One port line in the IO map.
pub(all) struct PortLine {
  path : String
  name : String
  kind : String
  spec : String
}

///|
/// One wire line in the harness report.
pub(all) struct WireLine {
  path : String
  run : WireRun
}

///|
/// One routed cable bundle in the harness report.
pub(all) struct RouteLine {
  path : String
  route : CableRoute
}

///|
/// The electrical budget for a component tree.
pub(all) struct PowerBudget {
  actuators : Array[ActuatorLine]
  sensors : Array[SensorLine]
  ports : Array[PortLine]
  wires : Array[WireLine]
  routes : Array[RouteLine]
}

///|
pub fn PowerBudget::new() -> PowerBudget {
  { actuators: [], sensors: [], ports: [], wires: [], routes: [], }
}

///|
/// Renders the power, IO, and wiring report.
pub fn PowerBudget::to_text(self : PowerBudget) -> String {
  let mut out = "Power and IO budget\n===================\n\nActuators\n---------\n"
  if self.actuators.length() == 0 {
    out = out + "(none)\n"
  }
  for line in self.actuators {
    let spec = line.spec
    out = out +
      leaf_name(line.path) +
      " | " +
      spec.model +
      " | " +
      actuator_kind_name(spec.kind) +
      " | " +
      spec.voltage_v.to_string() +
      " V | " +
      spec.current_rated_a.to_string() +
      " A rated / " +
      spec.current_stall_a.to_string() +
      " A stall | " +
      spec.torque_rated_nm.to_string() +
      " N·m | " +
      spec.driver +
      " | " +
      spec.interface +
      " | " +
      spec.encoder +
      "\n"
  }
  out = out + "\nPower summary\n-------------\n"
  let voltages : Array[Double] = []
  for line in self.actuators {
    push_unique_voltage(voltages, line.spec.voltage_v)
  }
  for line in self.sensors {
    push_unique_voltage(voltages, line.spec.voltage_v)
  }
  if voltages.length() == 0 {
    out = out + "(none)\n"
  }
  for voltage in voltages {
    let mut actuator_count = 0
    let mut sensor_count = 0
    let mut rated_a = 0.0
    let mut stall_a = 0.0
    let mut sensor_ma = 0.0
    for line in self.actuators {
      if line.spec.voltage_v == voltage {
        actuator_count = actuator_count + 1
        rated_a = rated_a + line.spec.current_rated_a
        stall_a = stall_a + line.spec.current_stall_a
      }
    }
    for line in self.sensors {
      if line.spec.voltage_v == voltage {
        sensor_count = sensor_count + 1
        sensor_ma = sensor_ma + line.spec.current_ma
      }
    }
    out = out +
      voltage.to_string() +
      " V: " +
      actuator_count.to_string() +
      " actuator(s), " +
      sensor_count.to_string() +
      " sensor(s) | " +
      rated_a.to_string() +
      " A rated (" +
      round2(voltage * rated_a).to_string() +
      " W), " +
      stall_a.to_string() +
      " A stall (" +
      round2(voltage * stall_a).to_string() +
      " W), sensors " +
      sensor_ma.to_string() +
      " mA\n"
  }
  out = out + "\nSensors\n-------\n"
  if self.sensors.length() == 0 {
    out = out + "(none)\n"
  }
  for line in self.sensors {
    let spec = line.spec
    out = out +
      leaf_name(line.path) +
      " | " +
      spec.model +
      " | " +
      sensor_kind_name(spec.kind) +
      " | " +
      spec.interface +
      " | " +
      spec.voltage_v.to_string() +
      " V | " +
      spec.current_ma.to_string() +
      " mA | " +
      spec.range +
      " | " +
      spec.resolution +
      "\n"
  }
  out = out + "\nPorts\n-----\n"
  if self.ports.length() == 0 {
    out = out + "(none)\n"
  }
  for port in self.ports {
    out = out +
      leaf_name(port.path) +
      " | " +
      port.name +
      " | " +
      port.kind +
      " | " +
      port.spec +
      "\n"
  }
  out = out + "\nWiring\n------\n"
  if self.wires.length() == 0 {
    out = out + "(none)\n"
  }
  for wire in self.wires {
    let run = wire.run
    out = out +
      run.name +
      " | " +
      run.from_component +
      "." +
      run.from_port +
      " -> " +
      run.to_component +
      "." +
      run.to_port +
      " | AWG " +
      run.gauge_awg.to_string() +
      " | " +
      run.length_mm.to_string() +
      " mm | " +
      run.notes +
      "\n"
  }
  out = out + "\nCable routes\n------------\n"
  if self.routes.length() == 0 {
    out = out + "(none)\n"
  }
  for entry in self.routes {
    let route = entry.route
    out = out +
      route_label(entry.path, route.name) +
      " | jacket " +
      route.jacket_diameter_mm.to_string() +
      " mm | " +
      round2(route.length_mm()).to_string() +
      " mm | " +
      route.material +
      " | wires: " +
      array_join(route.wire_names, ", ") +
      "\n"
  }
  out
}

///|
fn actuator_kind_name(kind : ActuatorKind) -> String {
  match kind {
    Stepper => "stepper"
    Bldc => "bldc"
    Servo => "servo"
    Hub => "hub"
  }
}

///|
fn sensor_kind_name(kind : SensorKind) -> String {
  match kind {
    LimitSwitch => "limit switch"
    Encoder => "encoder"
    Imu => "imu"
    Camera => "camera"
    Force => "force"
  }
}

///|
fn port_kind_name(kind : PortKind) -> String {
  match kind {
    Mechanical => "mechanical"
    Power => "power"
    Signal => "signal"
    Bus => "bus"
    Fluid => "fluid"
    Sensor => "sensor"
    Ground => "ground"
  }
}

///|
fn round2(value : Double) -> Double {
  let scale = 100.0
  let scaled = value * scale
  (scaled + 0.5).to_int().to_double() / scale
}

///|
fn push_unique_voltage(voltages : Array[Double], voltage : Double) -> Unit {
  let seen = voltages.fold(init=false, fn(acc, value) {
    acc || value == voltage
  })
  if !seen {
    voltages.push(voltage)
  }
}

///|
/// Walks the tree and collects actuator, sensor, port, and wire data.
pub fn Component::power_budget(self : Component) -> PowerBudget {
  let budget = PowerBudget::new()
  self.collect_power_budget(self.name, budget)
  budget
}

///|
/// The full power/IO/wiring report for this component tree.
pub fn Component::report_text(self : Component) -> String {
  self.power_budget().to_text()
}

///|
fn Component::collect_power_budget(
  self : Component,
  path : String,
  budget : PowerBudget,
) -> Unit {
  match self.actuator {
    Some(spec) => budget.actuators.push({ path, spec, })
    None => ()
  }
  match self.sensor {
    Some(spec) => budget.sensors.push({ path, spec, })
    None => ()
  }
  for port in self.ports {
    budget.ports.push({
      path,
      name: port.name,
      kind: port_kind_name(port.kind),
      spec: port.spec,
    })
  }
  for run in self.wiring {
    budget.wires.push({ path, run, })
  }
  for route in self.cables {
    budget.routes.push({ path, route, })
  }
  for att in self.attachments {
    att.child.collect_power_budget(path + "/" + att.child.name, budget)
  }
}

///|
/// Sets the actuator ratings for this component.
pub fn Component::with_actuator(
  self : Component,
  actuator : ActuatorSpec,
) -> Component {
  { ..self, actuator: Some(actuator), }
}

///|
/// Sets the sensor characteristics for this component.
pub fn Component::with_sensor(
  self : Component,
  sensor : SensorSpec,
) -> Component {
  { ..self, sensor: Some(sensor), }
}

///|
/// Sets the PCB envelope metadata for this component.
pub fn Component::with_pcb(self : Component, pcb : PcbSpec) -> Component {
  { ..self, pcb: Some(pcb), }
}

///|
/// Adds a point-to-point cable run to this component's harness.
pub fn Component::add_wire_run(self : Component, run : WireRun) -> Component {
  self.wiring.push(run)
  self
}

///|
/// Checks electrical metadata for problems: invalid ratings, missing
/// interfaces, bad PCB dimensions, and incomplete wire runs.
fn Component::collect_electronics_checks(
  self : Component,
  path : String,
  warnings : Array[String],
) -> Unit {
  match self.actuator {
    Some(spec) => {
      if spec.voltage_v <= 0.0 {
        warnings.push(path + ": actuator has no supply voltage")
      }
      if spec.current_rated_a <= 0.0 {
        warnings.push(path + ": actuator has no rated current")
      }
      if spec.current_stall_a < spec.current_rated_a {
        warnings.push(path + ": actuator stall current is below rated current")
      }
      if spec.torque_rated_nm <= 0.0 {
        warnings.push(path + ": actuator has no rated torque")
      }
      if spec.interface == "" {
        warnings.push(path + ": actuator has no control interface")
      }
    }
    None => ()
  }
  match self.sensor {
    Some(spec) => {
      if spec.voltage_v <= 0.0 {
        warnings.push(path + ": sensor has no supply voltage")
      }
      if spec.current_ma < 0.0 {
        warnings.push(path + ": sensor has negative current draw")
      }
      if spec.interface == "" {
        warnings.push(path + ": sensor has no interface")
      }
    }
    None => ()
  }
  match self.pcb {
    Some(spec) => {
      if spec.length_mm <= 0.0 || spec.width_mm <= 0.0 {
        warnings.push(path + ": PCB has no outline")
      }
      if spec.thickness_mm <= 0.0 {
        warnings.push(path + ": PCB has no thickness")
      }
      if spec.mounting_holes < 0 {
        warnings.push(path + ": PCB has a negative mounting-hole count")
      }
      if spec.max_component_height_mm <= 0.0 {
        warnings.push(path + ": PCB has no component height limit")
      }
    }
    None => ()
  }
  for run in self.wiring {
    if run.from_component == "" || run.from_port == "" {
      warnings.push(path + ": wire '" + run.name + "' has no source")
    }
    if run.to_component == "" || run.to_port == "" {
      warnings.push(path + ": wire '" + run.name + "' has no destination")
    }
    if run.gauge_awg < 10 || run.gauge_awg > 30 {
      warnings.push(path + ": wire '" + run.name + "' has an invalid gauge")
    }
    if run.length_mm <= 0.0 {
      warnings.push(path + ": wire '" + run.name + "' has no length")
    }
  }
}