sample_test.cpp

// SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
//
// SPDX-License-Identifier: Apache-2.0

#include <algorithm>
#include <array>
#include <chrono>
#include <cstdint>
#include <cstring>
#include <format>
#include <iomanip>
#include <iostream>
#include <string>
#include <string_view>
#include <thread>
#include <unordered_map>
#include <vector>

#include "astl/astl.h"
#include "astl/astl_telemetry.h"
#include "astl_cxx_compat.hpp"

namespace {
auto ValueToString(const astl_value_t& value, astl_value_type_t type) -> std::string {
  switch (type) {
    case ASTL_VALUE_UINT8:
      return std::to_string(value.ui8);
    case ASTL_VALUE_UINT16:
      return std::to_string(value.ui16);
    case ASTL_VALUE_UINT32:
      return std::to_string(value.ui32);
    case ASTL_VALUE_UINT64:
      return std::to_string(value.ui64);
    case ASTL_VALUE_FLOAT32:
      return std::to_string(static_cast<double>(value.fp32));
    case ASTL_VALUE_FLOAT64:
      return std::to_string(value.fp64);
    case ASTL_VALUE_BOOL8:
      return value.b8 ? "true" : "false";
    case ASTL_VALUE_UNKNOWN:
    default:
      return "<unknown>";
  }
}

auto UnitsToString(astl_units_t units) -> std::string {
  switch (units) {
    case ASTL_UNITS_NONE:
      return "";
    case ASTL_UNITS_TICKS:
      return "ticks";
    case ASTL_UNITS_SECONDS:
      return "s";
    case ASTL_UNITS_CELSIUS:
      return "°C";
    case ASTL_UNITS_JOULES:
      return "J";
    case ASTL_UNITS_WATTS:
      return "W";
    case ASTL_UNITS_VOLTS:
      return "V";
    case ASTL_UNITS_AMPS:
      return "A";
    case ASTL_UNITS_BYTES:
      return "B";
    case ASTL_UNITS_MBYTESPERSEC:
      return "MB/s";
    case ASTL_UNITS_MHZ:
      return "MHz";
    case ASTL_UNITS_PERCENT:
      return "%";
    case ASTL_UNITS_UNKNOWN:
    default:
      return "?";
  }
}

auto NormalizeTargetName(std::string_view target_name) -> std::string_view {
  constexpr std::array<std::string_view, 3> known_prefixes = {"scmi-mockscmi-", "scmi_", "scmi-"};
  for (const auto prefix : known_prefixes) {
    if (target_name.starts_with(prefix)) {
      return target_name.substr(prefix.size());
    }
  }
  return target_name;
}

auto TargetNamesMatch(std::string_view requested_name, std::string_view discovered_name) -> bool {
  return requested_name == discovered_name ||
         NormalizeTargetName(requested_name) == NormalizeTargetName(discovered_name);
}

}  // namespace

// NOLINTBEGIN
using AstlArgMap = std::unordered_map<std::string, std::string>;
auto ParseArgs(int argc, char* argv[]) -> AstlArgMap {
  std::unordered_map<std::string, std::string> args;

  for (int i = 1; i < argc; ++i) {
    std::string arg = argv[i];
    if (arg.starts_with("--")) {
      auto eq = arg.find('=');
      if (eq != std::string::npos) {
        args[arg.substr(2, eq - 2)] = arg.substr(eq + 1);
      } else {
        args[arg.substr(2)] = "true";
      }
    } else if (arg.starts_with("-") && i + 1 < argc) {
      args[arg.substr(1)] = argv[++i];
    }
  }
  return args;
}
// NOLINTEND

auto PrintHelp() -> void {
  std::cout << "Usage: sample_test [options]\n\n"
            << "Options:\n"
            << "  --help              Show this help message.\n"
            << "  --version           Print version and exit.\n"
            << "  --group=<name>      Specify metric group to collect.\n"
            << "  --load=<path>       Load a saved session (.astl) before querying targets/metrics.\n"
            << "  --save=<path>       Save a session (.astl) after collection.\n"
            << "  --immediate         Trigger immediate sample read.\n"
            << "  --interval=<n>      Trigger interval sample read period in milliseconds.\n"
            << "  --duration=<n>      Collection duration in seconds.\n"
            << "  --config=<path>     Path to  json config file for ASTL.\n"
            << "  Default: interval mode, 10 seconds duration and 500 milliseconds sampling interval.\n";
}

auto PrintVersion() -> void {
  astl_version_t version = astlVersion();
  std::cout << "ASTL v" << version.major << "." << version.minor << "." << version.micro << "\n";
  std::cout << "Version string: " << astlVersionString() << "\n";
}

auto PrintSystemInfo() -> void {
  astl_platform_props_t system_info{};
  system_info.size = sizeof(astl_platform_props_t);
  ASTL_INIT_STRUCT(astl_get_system_info_params_t, get_system_info_params, .flags = 0, .system_info = &system_info);
  const auto status = astlGetSystemInfo(&get_system_info_params);
  std::cout << "System info status: " << astlStatusString(status) << "\n";
  if (status != ASTL_STATUS_SUCCESS) {
    return;
  }

  const auto print_field = [](const char* name, const char* value) {
    std::cout << "  " << name << ": " << (value ? value : "<unknown>") << '\n';
  };

  std::cout << "System info:\n";
  print_field("SoC", system_info.soc_name);
  print_field("Vendor ID", system_info.vendor_id);
  print_field("OS", system_info.os_name);
  print_field("Kernel", system_info.kernel_name);
  print_field("Kernel release", system_info.kernel_release);
  print_field("Kernel version", system_info.kernel_version);
  print_field("Firmware", system_info.firmware_version);
  print_field("Host", system_info.hostname);
  print_field("Architecture", system_info.architecture);
}

auto GetIntervalArgument(const std::unordered_map<std::string, std::string>& args)
    -> astl::compat::expected<std::chrono::milliseconds, int> {
  if (args.contains("interval")) {
    try {
      int tmp_interval = std::stoi(args.at("interval"));
      if (tmp_interval <= 0) {
        std::cerr << "Interval must be a positive integer.\n";
        return astl::compat::unexpected<int>(1);
      }
      auto sampling_interval_ms = std::chrono::milliseconds(tmp_interval);
      std::cout << "Interval set to: " << sampling_interval_ms.count() << " milliseconds\n";
      return sampling_interval_ms;
    } catch (const std::exception& e) {
      // Include exception details to aid debugging and ensure variable is referenced (avoids unused warning)
      std::cerr << "Invalid value for --interval (" << e.what() << ")\n";
      return astl::compat::unexpected<int>(1);
    }
  }
  return std::chrono::milliseconds{};
}
auto GetDurationArgument(const std::unordered_map<std::string, std::string>& args)
    -> astl::compat::expected<std::chrono::seconds, int> {
  if (args.contains("duration")) {
    try {
      int tmp_duration = std::stoi(args.at("duration"));
      if (tmp_duration <= 0) {
        std::cerr << "Duration must be a positive integer.\n";
        return astl::compat::unexpected<int>(1);
      }
      auto duration_seconds = std::chrono::seconds(tmp_duration);
      std::cout << "Duration set to: " << duration_seconds.count() << " seconds\n";
      return duration_seconds;
    } catch (const std::exception&) {
      std::cerr << "Invalid value for --duration\n";
      return astl::compat::unexpected<int>(1);
    }
  }
  return std::chrono::seconds{};
}

auto GetMetricGroupArgument(const std::unordered_map<std::string, std::string>& args) -> std::string {
  if (args.contains("group")) {
    std::string metric_group = args.at("group");
    std::cout << "Metric group set to: " << metric_group << "\n";
    return metric_group;
  }
  return std::string{};
}

auto GetTargetByName(std::string const& target_name, std::vector<astl_target_props_t>& target_properties_buffer,
                     astl_target_props_t& target_properties) -> astl_status_code {
  uint32_t target_count = 0;
  ASTL_INIT_STRUCT(astl_get_target_count_params_t, get_target_count_params, .flags = 0, .target_count = &target_count);
  astl_status_code status = astlGetTargetCount(&get_target_count_params);
  std::cout << "Target count: " << target_count << "\n";
  if (status != ASTL_STATUS_SUCCESS) {
    return status;
  }
  target_properties_buffer.resize(target_count);

  /// @todo ASTL-167 After https://github.com/Arm-Debug/ASTL/pull/180 is merged,
  /// we should probably make this sample test fail when zero targets are detected.
  if (target_count == 0) {
    return ASTL_STATUS_SUCCESS;
  }

  target_properties_buffer[0].size = sizeof(astl_target_props_t);
  ASTL_INIT_STRUCT(astl_get_targets_params_t, get_targets_params, .flags = 0,
                   .targets = target_properties_buffer.data(), .target_count = &target_count);
  status = astlGetTargets(&get_targets_params);
  target_properties_buffer.resize(target_count);
  std::cout << "astlGetTargets Status: " << astlStatusString(status) << '\n';

  if (target_count > 0 && (status == ASTL_STATUS_SUCCESS || status == ASTL_STATUS_BUFFER_LARGER_THAN_NEEDED)) {
    const astl_target_props_t* exact_match      = nullptr;
    const astl_target_props_t* normalized_match = nullptr;

    for (const auto& target_properties_entry : target_properties_buffer) {
      std::cout << "Target info:" << '\n';
      std::cout << "  Name:        " << (target_properties_entry.name ? target_properties_entry.name : "<null>")
                << '\n';
      std::cout << "  Description: "
                << (target_properties_entry.description ? target_properties_entry.description : "<null>") << '\n';
      std::cout << "compare to target_name:" << target_name << '\n';

      if (!target_properties_entry.name) {
        continue;
      }

      const std::string_view discovered_name{target_properties_entry.name};
      if (discovered_name == target_name) {
        exact_match = &target_properties_entry;
        break;
      }
      if (!normalized_match && TargetNamesMatch(target_name, discovered_name)) {
        normalized_match = &target_properties_entry;
      }
    }

    const auto* selected_target = exact_match ? exact_match : normalized_match;
    if (!selected_target) {
      std::cerr << "Requested target '" << target_name << "' was not found.\n";
      return ASTL_STATUS_INVALID_TARGET_HANDLE;
    }

    target_properties = *selected_target;
    std::cout << "  --> Selected target\n";
    if (!exact_match) {
      std::cout << "Matched requested target alias '" << target_name << "' to discovered target '"
                << selected_target->name << "'\n";
    }
    return ASTL_STATUS_SUCCESS;
  }

  std::cerr << "Failed to get target info.\n";
  return ASTL_STATUS_INTERNAL_ERROR;
}

auto GetTargets(std::vector<astl_target_props_t>& target_properties_buffer, astl_target_props_t& target_properties)
    -> astl_status_code {
  uint32_t target_count = 0;
  ASTL_INIT_STRUCT(astl_get_target_count_params_t, get_target_count_params, .flags = 0, .target_count = &target_count);
  astl_status_code status = astlGetTargetCount(&get_target_count_params);
  std::cout << "Target count: " << target_count << "\n";
  if (status != ASTL_STATUS_SUCCESS) {
    return status;
  }

  target_properties_buffer.resize(target_count);

  if (target_count == 0) {
    return ASTL_STATUS_NO_TARGET_FOUND;
  }

  target_properties_buffer[0].size = sizeof(astl_target_props_t);
  ASTL_INIT_STRUCT(astl_get_targets_params_t, get_targets_params, .flags = 0,
                   .targets = target_properties_buffer.data(), .target_count = &target_count);
  status = astlGetTargets(&get_targets_params);
  target_properties_buffer.resize(target_count);
  std::cout << "astlGetTargets Status: " << astlStatusString(status) << '\n';

  if (target_count > 0 && (status == ASTL_STATUS_SUCCESS || status == ASTL_STATUS_BUFFER_LARGER_THAN_NEEDED)) {
    std::ranges::for_each(target_properties_buffer, [](const auto target_properties) {
      std::cout << "Target info:" << '\n';
      std::cout << "  Name:        " << (target_properties.name ? target_properties.name : "<null>") << '\n';
      std::cout << "  Description: " << (target_properties.description ? target_properties.description : "<null>")
                << '\n';
    });
    target_properties = target_properties_buffer[0];
    return ASTL_STATUS_SUCCESS;
  }

  std::cerr << "Failed to get target info.\n";
  return ASTL_STATUS_INTERNAL_ERROR;
}

auto GetCountersOnTarget(const astl_target_props_t& target_properties)
    -> astl::compat::expected<std::vector<astl_counter_props_t>, astl_status_code> {
  uint32_t counter_count{};
  ASTL_INIT_STRUCT(astl_get_counter_count_params_t, get_counter_count_params, .flags = 0,
                   .target_handle = target_properties.handle, .counter_count = &counter_count);
  auto status = astlGetCounterCountOnTarget(&get_counter_count_params);
  std::cout << "Counter count: " << counter_count << "\n";
  if (status != ASTL_STATUS_SUCCESS) {
    std::cout << "astlGetCounterCountOnTarget Status: " << astlStatusString(status) << '\n';
    std::cout << "target_handle: " << target_properties.handle << " \n";
    return astl::compat::unexpected{status};
  }
  if (counter_count == 0) {
    std::cout << "No counters found for target.\n";
    return {};
  }
  std::vector<astl_counter_props_t> counter_buffer;
  counter_buffer.resize(counter_count);
  for (auto& counter : counter_buffer) {
    counter.size = sizeof(astl_counter_props_t);
  }
  ASTL_INIT_STRUCT(astl_get_counters_params_t, get_counters_params, .flags = 0,
                   .target_handle = target_properties.handle, .counters = counter_buffer.data(),
                   .counter_count = &counter_count);
  status = astlGetCountersOnTarget(&get_counters_params);
  std::cout << "astlGetCountersOnTarget Status: " << astlStatusString(status) << '\n';
  if (status != ASTL_STATUS_SUCCESS) {
    return astl::compat::unexpected{status};
  }
  return astl::compat::expected<std::vector<astl_counter_props_t>, astl_status_code>(std::move(counter_buffer));
}

void PrintCounters(std::vector<astl_counter_props_t> const& counter_buffer) {
  for (const auto& counter_props : counter_buffer) {
    std::cout << "Counter info:" << '\n';
    std::cout << "  Name:        " << (counter_props.name ? counter_props.name : "<null>") << '\n';
    std::cout << "  Description: " << (counter_props.description ? counter_props.description : "<null>") << '\n';
  }
}

auto GetMetricsOnTarget(const astl_target_props_t& target_properties, std::vector<astl_metric_props_t>& metric_buffer,
                        uint32_t& metric_count) -> astl_status_code {
  ASTL_INIT_STRUCT(astl_get_metric_count_params_t, get_metric_count_params, .flags = 0,
                   .target_handle = target_properties.handle, .metric_count = &metric_count);
  astl_status_code status = astlGetMetricCountOnTarget(&get_metric_count_params);
  std::cout << "Metric count: " << metric_count << '\n';
  if (status != ASTL_STATUS_SUCCESS) {
    std::cout << "astlGetMetricCountOnTarget Status: " << astlStatusString(status) << '\n';
    std::cout << "target_handle: " << target_properties.handle << " \n";
    std::cout << "&metric_count: " << &metric_count << " \n";
    return status;
  }

  metric_buffer.resize(metric_count);

  if (metric_count == 0) {
    return ASTL_STATUS_NO_METRICS_FOUND;
  }

  if (metric_count > 0) {
    metric_buffer[0].size = sizeof(astl_metric_props_t);
  }
  ASTL_INIT_STRUCT(astl_get_metrics_params_t, get_metrics_params, .flags = 0, .target_handle = target_properties.handle,
                   .metrics = metric_buffer.data(), .metric_count = &metric_count);
  status = astlGetMetricsOnTarget(&get_metrics_params);
  std::cout << "astlGetMetricsOnTarget Status: " << astlStatusString(status) << '\n';
  return status;
}

auto GetMetricsInGroup(const astl_target_props_t& target_properties, const std::string& group_name)
    -> astl::compat::expected<std::vector<astl_metric_props_t>, astl_status_code> {
  uint32_t metric_group_count{0};
  ASTL_INIT_STRUCT(astl_get_metric_group_count_on_target_params_t, get_metric_group_count_params, .flags = 0,
                   .target_handle = target_properties.handle, .metric_group_count = &metric_group_count);
  auto status = astlGetMetricGroupCountOnTarget(&get_metric_group_count_params);
  if (status != ASTL_STATUS_SUCCESS) {
    std::cout << "astlGetMetricGroupCountOnTarget Status: " << astlStatusString(status) << '\n';
    return astl::compat::unexpected<astl_status_code>(status);
  }
  std::cout << "astlGetMetricGroupCountOnTarget: " << metric_group_count << '\n';
  if (metric_group_count == 0) {
    return std::vector<astl_metric_props_t>{};
  }
  std::vector<astl_metric_group_props_t> metric_groups_properties(metric_group_count);
  metric_groups_properties[0].size = sizeof(astl_metric_group_props_t);

  // retrieve the metric groups
  ASTL_INIT_STRUCT(astl_get_metric_groups_on_target_params_t, get_metric_groups_params, .flags = 0,
                   .target_handle = target_properties.handle, .metric_groups = metric_groups_properties.data(),
                   .metric_group_count = &metric_group_count);
  status = astlGetMetricGroupsOnTarget(&get_metric_groups_params);
  if (status != ASTL_STATUS_SUCCESS) {
    std::cout << "astlGetMetricGroupsOnTarget Status: " << astlStatusString(status) << '\n';
    return astl::compat::unexpected<astl_status_code>(status);
  }

  // find the requested metric group
  auto metric_group = std::find_if(metric_groups_properties.begin(), metric_groups_properties.end(),
                                   [&group_name](const astl_metric_group_props_t& group_props) {
                                     return group_props.name != nullptr && group_name == group_props.name;
                                   });
  if (metric_group == metric_groups_properties.end()) {
    std::cout << "Metric group '" << group_name << "' not found.\n";
    return std::vector<astl_metric_props_t>{};
  }

  uint32_t metric_count = 0;
  ASTL_INIT_STRUCT(astl_get_metric_group_metric_count_on_target_params_t, get_metric_group_metric_count_params,
                   .flags = 0, .target_handle = target_properties.handle, .metric_group_handle = metric_group->handle,
                   .metric_count = &metric_count);
  status = astlGetMetricGroupMetricCountOnTarget(&get_metric_group_metric_count_params);
  if (status != ASTL_STATUS_SUCCESS) {
    std::cout << "astlGetMetricGroupMetricCountOnTarget Status: " << astlStatusString(status) << '\n';
    return astl::compat::unexpected(status);
  }
  if (metric_count == 0) {
    return std::vector<astl_metric_props_t>{};
  }

  std::vector<astl_metric_props_t> metrics_properties(metric_count);
  metrics_properties[0].size = sizeof(astl_metric_props_t);

  ASTL_INIT_STRUCT(astl_get_metric_group_metrics_on_target_params_t, get_metric_group_metrics_params, .flags = 0,
                   .target_handle = target_properties.handle, .metric_group_handle = metric_group->handle,
                   .metrics = metrics_properties.data(), .metric_count = &metric_count);
  status = astlGetMetricGroupMetricsOnTarget(&get_metric_group_metrics_params);
  if (status != ASTL_STATUS_SUCCESS) {
    std::cout << "astlGetMetricGroupMetricsOnTarget Status: " << astlStatusString(status) << '\n';
    return astl::compat::unexpected(status);
  }
  metrics_properties.resize(metric_count);
  return metrics_properties;
}

auto ConfigureAndRunCollection(const astl_target_props_t&              target_properties,
                               const std::vector<astl_metric_props_t>& metric_buffer, bool do_interval,
                               std::chrono::seconds duration_seconds, std::chrono::milliseconds sampling_interval)
    -> astl_status_code {
  ASTL_INIT_STRUCT(astl_collection_params_t, collection_params,
                   .flags             = ASTL_COLLECTION_PARAMETERS_FLAG_OPTIMIZE_OVERHEAD,
                   .sampling_interval = do_interval ? static_cast<uint32_t>(sampling_interval.count()) : 0,
                   .collection_mode   = do_interval ? ASTL_COLLECTION_MODE_SAMPLING : ASTL_COLLECTION_MODE_IMMEDIATE);

  // Build a vector of metric handles from metric_buffer
  std::vector<astl_metric_handle_t> metric_handles_vec;
  metric_handles_vec.reserve(metric_buffer.size());
  std::transform(metric_buffer.begin(), metric_buffer.end(), std::back_inserter(metric_handles_vec),
                 [](const astl_metric_props_t& metric_properties) { return metric_properties.handle; });

  const auto metric_count = static_cast<uint32_t>(metric_handles_vec.size());
  // Lint: readability-qualified-auto -> express pointer constness explicitly
  const auto* const target_handle = target_properties.handle;

  ASTL_INIT_STRUCT(astl_configure_metric_collection_on_target_params_t, configure_params, .flags = 0,
                   .target_handle = target_handle, .collection_params = &collection_params,
                   .metric_handles = metric_handles_vec.data(), .metric_count = metric_count);
  astl_status_code status = astlConfigureMetricCollectionOnTarget(&configure_params);
  std::cout << "astlConfigureMetricCollectionOnTarget Status: " << astlStatusString(status) << '\n';
  if (status != ASTL_STATUS_SUCCESS) {
    std::cout << "Failed to configure metric collection - exiting early" << '\n';
    return status;
  }

  ASTL_INIT_STRUCT(astl_start_collection_on_target_params_t, start_params, .flags = 0, .target_handle = target_handle);
  status = astlStartCollectionOnTarget(&start_params);
  std::cout << "astlStartCollectionOnTarget Status: " << astlStatusString(status) << '\n';

  if (do_interval && duration_seconds > std::chrono::seconds::zero()) {
    std::this_thread::sleep_for(duration_seconds);
  }

  if (!do_interval) {
    ASTL_INIT_STRUCT(astl_read_immediate_on_target_params_t, read_params, .flags = 0, .target_handle = target_handle);
    status = astlReadImmediateOnTarget(&read_params);
    std::cout << "ReadImmediate: " << astlStatusString(status) << '\n';
  }

  ASTL_INIT_STRUCT(astl_stop_collection_on_target_params_t, stop_params, .flags = 0, .target_handle = target_handle);
  status = astlStopCollectionOnTarget(&stop_params);
  std::cout << "astlStopCollectionOnTarget Status: " << astlStatusString(status) << '\n';

  return status;
}

auto RetrieveSamples(astl_target_handle_t target_handle, const std::vector<astl_metric_props_t>& metric_buffer)
    -> void {
  for (const auto& metric_props : metric_buffer) {
    if (!metric_props.name) {
      continue;  // skip nameless metrics
    }
    if (std::strncmp(metric_props.name, "AP1", 3) == 0) {
      continue;  // skip AP1 as MockScmi doesn't implement the AP1 events listed in example_scmi_specification.json
    }
    uint32_t sample_count{};
    ASTL_INIT_STRUCT(astl_get_metric_sample_count_on_target_params_t, get_metric_sample_count_params, .flags = 0,
                     .target_handle = target_handle, .metric_handle = metric_props.handle,
                     .sample_count = &sample_count, .start_ts = 0, .end_ts = 0);
    auto status = astlGetMetricSampleCountOnTarget(&get_metric_sample_count_params);
    std::cout << "astlGetMetricSampleCountOnTarget Status: " << astlStatusString(status) << " (count=" << sample_count
              << ")\n";
    if (status != ASTL_STATUS_SUCCESS || sample_count == 0) {
      continue;
    }

    std::vector<astl_sample_t> samples(sample_count);
    ASTL_INIT_STRUCT(astl_get_metric_samples_on_target_params_t, get_metric_samples_params, .flags = 0,
                     .target_handle = target_handle, .metric_handle = metric_props.handle, .samples = samples.data(),
                     .sample_count = &sample_count, .start_ts = 0, .end_ts = 0);
    status = astlGetMetricSamplesOnTarget(&get_metric_samples_params);
    std::cout << "astlGetMetricSamplesOnTarget Status: " << astlStatusString(status) << '\n';
    if (status != ASTL_STATUS_SUCCESS || sample_count == 0) {
      continue;
    }
    samples.resize(sample_count);

    // Check if all samples are non-zero
    bool all_samples_non_zero =
        std::all_of(samples.begin(), samples.end(), [](const astl_sample_t& sample) { return sample.value.ui64 != 0; });

    std::cout << "Collected Samples for metric '" << metric_props.name << "':\n";
    for (size_t i = 0; i < samples.size(); ++i) {
      const auto& sample_entry = samples[i];
      std::cout << "  [" << i << "] ts=" << sample_entry.timestamp
                << " value=" << ValueToString(sample_entry.value, metric_props.value_type) << '\n';
    }
    if (!all_samples_non_zero) {
      std::cout << "Collected samples contain zero values" << '\n';
    }
  }
}

auto PrintMinMaxAvgSummary(astl_target_handle_t target_handle, const std::vector<astl_metric_props_t>& metric_buffer)
    -> void {
  std::cout << "\n--- Min/Max/Avg Summary ---\n";
  for (const auto& metric_props : metric_buffer) {
    if (!metric_props.name) {
      continue;  // skip nameless metrics
    }
    if (std::strncmp(metric_props.name, "AP1", 3) == 0) {
      continue;  // skip AP1 as MockScmi doesn't implement the AP1 events
    }
    astl_metric_statistics_t summary{};
    summary.size  = sizeof(astl_metric_statistics_t);
    summary.flags = ASTL_METRIC_STATISTICS_FLAG_REGULAR_AVG;
    ASTL_INIT_STRUCT(astl_get_metric_statistics_on_target_params_t, get_metric_statistics_params, .flags = 0,
                     .target_handle = target_handle, .metric_handle = metric_props.handle, .summary = &summary,
                     .start_ts = 0, .end_ts = 0);
    auto        status      = astlGetMetricStatisticsOnTarget(&get_metric_statistics_params);
    const char* metric_name = metric_props.name ? metric_props.name : "<null>";
    if (status == ASTL_STATUS_NOT_SUPPORTED) {
      std::cout << "  " << metric_name << ": summary not supported for this value type\n";
      continue;
    }
    if (status != ASTL_STATUS_SUCCESS) {
      std::cout << "  " << metric_name << ": astlGetMetricStatisticsOnTarget Status: " << astlStatusString(status)
                << '\n';
      continue;
    }
    if (summary.count == 0) {
      std::cout << "  " << metric_name << ": no samples collected\n";
      continue;
    }
    const std::string  unit = UnitsToString(metric_props.units);
    std::ostringstream avg_ss;
    avg_ss << std::fixed << std::setprecision(2);
    avg_ss << "  " << metric_name << " count=" << summary.count
           << " min=" << ValueToString(summary.min, metric_props.value_type)
           << " max=" << ValueToString(summary.max, metric_props.value_type) << " avg=" << summary.avg.fp64
           << (unit.empty() ? "" : " unit=" + unit) << '\n';
    std::cout << avg_ss.str();
  }
}

/**
 * @brief  Example ASTL usage: version, init, target discovery, metric collection.
 *
 * Supported options:
 *   --help          Show usage
 *   --version       Print ASTL version and exit
 *   --immediate     Trigger an immediate metric sample. This is default behavior.
 *   --interval=<n>  Trigger interval sampling every <n> milliseconds
 *   --config=<path> Path to json config file for ASTL
 *   --load=<path>   Load ASTL state from a saved session (.astl)
 *   --save=<path>   Save ASTL state to a session file (.astl)
 *
 * A lightweight argument parser interprets these flags and
 * runs the corresponding ASTL actions.
 */
auto main(int argc, char* argv[]) -> int {
  auto args = ParseArgs(argc, argv);

  if (args.contains("help")) {
    PrintHelp();
    return 0;
  }

  if (args.contains("version")) {
    PrintVersion();
    return 0;
  }

  PrintSystemInfo();

  astl_status_code status{ASTL_STATUS_SUCCESS};

  const bool do_load_session = args.contains("load");
  if (do_load_session) {
    const std::string& input_file_path = args.at("load");
    if (input_file_path == "true") {
      std::cerr << "--load requires a value (use --load=<path>)\n";
      return 2;
    }

    ASTL_INIT_STRUCT(astl_load_params_t, load_params, .flags = 0, .input_file_path = input_file_path.c_str(),
                     .chunk_size_bytes = 0);
    status = astlLoadCollection(&load_params);
    std::cout << "astlLoadCollection Status: " << astlStatusString(status) << '\n';
    if (status != ASTL_STATUS_SUCCESS) {
      return 6;
    }
  }

  auto metric_group_name = GetMetricGroupArgument(args);

  std::chrono::seconds duration_seconds(10);  // Default duration
  auto                 duration_result = GetDurationArgument(args);
  if (!duration_result) {
    return duration_result.error();
  }
  if (duration_result->count() > 0) {
    duration_seconds = *duration_result;
  }

  const bool do_immediate = args.contains("immediate");
  bool       do_interval  = args.contains("interval");
  if (!do_immediate && !do_interval) {
    do_interval = true;
    std::cout << "Neither --immediate nor --interval specified; defaulting to interval mode\n";
  }

  std::chrono::milliseconds sampling_interval_ms(500);  // Default sampling interval
  if (do_interval) {
    auto interval_result = GetIntervalArgument(args);
    if (!interval_result) {
      return interval_result.error();
    }
    if (interval_result->count() > 0) {
      sampling_interval_ms = *interval_result;
    }
  }

  // Get targets
  std::vector<astl_target_props_t> target_properties_buffer;
  astl_target_props_t              target_properties{};
  if (args.contains("target")) {
    status = GetTargetByName(args["target"], target_properties_buffer, target_properties);
  } else {
    status = GetTargets(target_properties_buffer, target_properties);
  }
  if (status != ASTL_STATUS_SUCCESS) {
    if (status == ASTL_STATUS_NO_TARGET_FOUND) {
      std::cout << "No targets discovered; exiting successfully for integration environment.\n";
      return 0;  // treat absence of targets as non-fatal in integration runs
    }
    return 4;
  }

  // Get and print counters
  auto counters_result = GetCountersOnTarget(target_properties);
  if (counters_result) {
    PrintCounters(*counters_result);
  }

  // Get metrics
  std::vector<astl_metric_props_t> metric_buffer;
  if (!metric_group_name.empty()) {
    auto metrics_or_error = GetMetricsInGroup(target_properties, metric_group_name);
    if (!metrics_or_error) {
      std::cout << "Error retrieving metrics for group '" << metric_group_name
                << "': " << astlStatusString(metrics_or_error.error()) << "\n";
      return 5;
    }
    metric_buffer = *metrics_or_error;
  } else {
    uint32_t metric_count{};
    status = GetMetricsOnTarget(target_properties, metric_buffer, metric_count);
    if (status != ASTL_STATUS_SUCCESS) {
      std::cout << "Masking error code " << status
                << " from GetMetricsOnTarget so sample integration tests will pass w/out MockScmi\n";
      // Note - this is masking error codes, but our CTest integration tests expect these sample tests to function
      // even without MockScmi running
      return 0;
    }
  }

  if (metric_buffer.empty()) {
    std::cout << "no metrics available to collect on target: " << target_properties.name << '\n';
    return 0;
  }

  // Configure and run collection
  if (!do_load_session) {
    status = ConfigureAndRunCollection(target_properties, metric_buffer, do_interval, duration_seconds,
                                       sampling_interval_ms);
    if (status != ASTL_STATUS_SUCCESS) {
      // Note - this is masking error codes, but our CTest integration tests expect these sample tests to function
      // even without MockScmi running
      return 0;
    }
  }

  if (args.contains("save")) {
    const std::string& output_file_path = args.at("save");
    if (output_file_path == "true") {
      std::cerr << "--save requires a value (use --save=<path>)\n";
      return 2;
    }

    ASTL_INIT_STRUCT(astl_save_params_t, save_params, .flags = 0, .output_file_path = output_file_path.c_str());
    status = astlSaveCollection(&save_params);
    std::cout << "astlSaveCollection Status: " << astlStatusString(status) << '\n';
    if (status != ASTL_STATUS_SUCCESS) {
      return 7;
    }
  }

  // Retrieve and display samples
  // Currently unimplemented. For the first milestone, just read from debug logs
  // TODO(ASTL-60) - Print samples using basic text writer plugin
  RetrieveSamples(target_properties.handle, metric_buffer);

  // Print min/max/avg summary for all collected metrics
  PrintMinMaxAvgSummary(target_properties.handle, metric_buffer);

  return 0;
}