feat: add core foundation benchmarking support

[niteshpurohit]

• Introduced a new benchmarking framework within the Laghu project.
• Added LaghuBenchmarks.cmake to configure benchmark targets and validation tests.
• Created core_foundation.cpp and runner.cpp for the core foundation workload and its execution.
• Implemented metrics handling in metrics.hpp and workload.hpp to track performance.
• Added a script for running benchmarks, ensuring proper command-line argument handling.
• Created tests for benchmark metrics to validate percentile calculations.
• Updated CMake configuration to include benchmark targets and validation tests.
• Removed the empty .gitkeep file from the bench directory.

closes: #81

[Copilot]

🟡 Changes recommended

Benchmark validation fails for FULL/CUSTOM builds, with additional FreeBSD and release-exclusion gaps.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a core foundation benchmarking harness with JSON metrics, workload execution, CMake integration, validation, and percentile tests.

Changes:

• Added benchmark runner, workload, metrics, and execution script.
• Integrated benchmark targets, metadata, static analysis, and validation.
• Added release-exclusion checks and removed the obsolete .gitkeep.

File summaries

File	Description
tests/benchmarks/metrics.cpp	Tests percentile calculations.
scripts/benchmark	Builds and runs configured benchmarks.
CMakeLists.txt	Integrates benchmark configuration and targets.
cmake/RunStaticAnalysis.cmake	Includes benchmark sources in analysis.
cmake/LaghuStaticAnalysis.cmake	Discovers benchmark analysis targets.
cmake/LaghuBuildIdentity.cmake	Exposes build identity metadata.
cmake/LaghuBenchmarks.cmake	Defines benchmark targets and validation.
cmake/ExpectBenchmarkRunner.cmake	Validates benchmark output and CLI behavior.
cmake/ExpectBenchmarkReleaseExclusion.cmake	Verifies benchmark release exclusion.
bench/runner.cpp	Executes workloads and emits JSON metrics.
bench/private/laghu/benchmark/internal/workload.hpp	Defines workload counters and interface.
bench/private/laghu/benchmark/internal/metrics.hpp	Implements percentile summarization.
bench/core_foundation.cpp	Implements the foundation workload.
bench/.gitkeep	Removes the obsolete placeholder.

Review details

Suppressed comments (2)

cmake/ExpectBenchmarkReleaseExclusion.cmake:36

• The test installs into STAGE_DIRECTORY but never inspects that directory; nm is run only on the build-tree archive and CLI passed as ARCHIVE and EXECUTABLE. An accidentally installed benchmark executable would therefore pass this release-exclusion test. Check the staged files for benchmark artifacts after installation.

foreach(artifact IN ITEMS "${ARCHIVE}" "${EXECUTABLE}")
  execute_process(COMMAND "${NM}" -a "${artifact}"
    RESULT_VARIABLE nm_result
    OUTPUT_VARIABLE symbols
    ERROR_VARIABLE diagnostics)
  if(NOT nm_result EQUAL 0)
    message(FATAL_ERROR "Laghu benchmark exclusion expectation failed: nm=${artifact}; diagnostics=${diagnostics}")
  endif()
  if(symbols MATCHES "laghu.*benchmark|benchmark_core_foundation")
    message(FATAL_ERROR "Laghu benchmark exclusion expectation failed: instrumentation_leaked artifact=${artifact}")
  endif()

scripts/benchmark:27

• The script rejects only the literal 0, so values such as 00 pass this check but are parsed as numeric zero by the runner and rejected only after the workload has been built. Reject all-zero digit strings here so the script's argument validation is consistent with the executable.

      case "$2" in ''|*[!0-9]*|0) usage; exit 64 ;; esac

• Files reviewed: 14/14 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Validation currently fails, and staging, memory-copy, and build-identity issues remain.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

bench/runner.cpp:234

• On Linux, value is a view into metric.text (the buffer filled by read), so this copy has overlapping source and destination ranges for a normal model name line. std::memcpy is undefined for overlapping ranges and can corrupt the CPU description; use std::memmove or copy through a separate buffer.

cmake/ExpectReproducibleStaging.cmake:13

• The staged source now configures laghu.benchmark.runner, which invokes ${CMAKE_SOURCE_DIR}/scripts/benchmark, but this copy list omits scripts. As a result, the benchmark validation test in either reproducible staging tree points at a nonexistent executable; include scripts in the staged source entries.

  foreach(entry IN ITEMS CMakeLists.txt CMakePresets.json VERSION bench cmake docs src tests)

• Files reviewed: 15/15 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Address the two moderate bench/runner.cpp resource-metric issues involving missing instrumentation and warmup counters.

Review details

Suppressed comments (2)

bench/runner.cpp:343

• These fields are always reported with instrumented:true, but run_core_foundation explicitly discards the counters and this change contains no allocation or syscall hooks, so both values are unconditionally zero. That makes the result claim measurements that the harness does not actually collect once a workload performs either operation; implement the instrumentation or report the metrics as unavailable until they are measured.

      writer.append("}},\"metrics\":{\"allocation_count\":{\"instrumented\":true,\"value\":") &&
      writer.append_number(counters.allocation_count) &&
      writer.append("},\"cpu_time_ns\":") &&
      append_numeric_metric(writer, cpu_time) &&
      writer.append(",\"laghu_syscall_count\":{\"instrumented\":true,\"value\":") &&
      writer.append_number(counters.laghu_syscall_count) &&

bench/runner.cpp:383

• counters is populated by both warmup and measured calls, but it is emitted as the measured allocation/syscall result without being reset after the warmup loop. Any workload that records either counter will therefore make the reported resource metrics depend on the warmup count, unlike the latency and CPU metrics; reset or snapshot the counters at the measured-phase boundary.

  WorkloadCounters counters{};
  std::uint64_t checksum{};
  for (std::uint64_t interval = 0U; interval < options.warmup_intervals; ++interval) {
    checksum ^= laghu::benchmark::internal::run_core_foundation(interval + 1U, counters);

• Files reviewed: 16/16 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Invalid-interval validation cases use the wrong build directory and return 66 instead of the expected 64.

Review details

Suppressed comments (1)

cmake/ExpectBenchmarkRunner.cmake:98

• These three invalid-interval cases pass ${BUILD_DIRECTORY}/missing, but scripts/benchmark checks the build directory before validating --intervals, so each invocation returns 66 (missing directory) instead of the expected 64. Use the real ${BUILD_DIRECTORY} for these cases so the interval parser is exercised and the validation test can pass.

    set(arguments --build "${BUILD_DIRECTORY}/missing" --workload core-foundation --warmup 1 --intervals 0)
  elseif(case STREQUAL "zero-padded-intervals")
    set(arguments --build "${BUILD_DIRECTORY}/missing" --workload core-foundation --warmup 1 --intervals 00)
  elseif(case STREQUAL "zero-tripled-intervals")
    set(arguments --build "${BUILD_DIRECTORY}/missing" --workload core-foundation --warmup 1 --intervals 000)

• Files reviewed: 17/17 changed files
• Comments generated: 0 new
• Review effort level: Lite