Polish public API module boundaries

Author: smiggleworth

README.md

@@ -358,6 +358,12 @@ Files are written under `target/stress/{suite}/`:
 
 The JSON artifact contains tool version, run profile, environment, benchmark specs, raw samples, summaries, diagnostics, quality, and comparisons. Unknown environment fields are explicit `"unknown"` or `null`.
 
+## Import Migration
+
+Common benchmark files do not change: keep using root imports such as `stress`, `stress_main`, `black_box`, `StressContext`, `StressRunner`, `StressRunnerConfig`, `StressRunnerOptions`, and `RunProfile`.
+
+Advanced imports moved out of the crate root. Result and schema types are under `cntryl_stress::artifact`, reporters and console formatting helpers are under `cntryl_stress::reporting`, and run gate helpers are under `cntryl_stress::runner`.
+
 ## Programmatic Runner
 
 ```rust

core/src/result.rs core/src/artifact.rscore/src/result.rs renamed to core/src/artifact.rs

@@ -942,7 +942,7 @@ impl StressRun {
 
 /// Summarize one benchmark from raw samples.
 #[must_use]
-pub fn summarize_benchmark(spec: &BenchmarkSpec, samples: &[Sample]) -> BenchmarkSummary {
+pub(crate) fn summarize_benchmark(spec: &BenchmarkSpec, samples: &[Sample]) -> BenchmarkSummary {
     let measured: Vec<&Sample> = samples
         .iter()
         .filter(|sample| sample.benchmark_id == spec.id && sample.phase == SamplePhase::Measured)
@@ -1034,7 +1034,7 @@ pub fn summarize_benchmark(spec: &BenchmarkSpec, samples: &[Sample]) -> Benchmar
 
 /// Compare current summaries to baseline summaries.
 #[must_use]
-pub fn compare_summaries(
+pub(crate) fn compare_summaries(
     current: &[BenchmarkSummary],
     baseline: &[BenchmarkSummary],
     threshold: f64,
@@ -1061,7 +1061,7 @@ pub fn compare_summaries(
 }
 
 /// Add regression diagnostics to summaries after baseline comparison.
-pub fn attach_regression_diagnostics(
+pub(crate) fn attach_regression_diagnostics(
     summaries: &mut [BenchmarkSummary],
     comparisons: &[ComparisonResult],
 ) {

core/src/bin/cargo-stress.rs

@@ -34,7 +34,7 @@
 
 use anyhow::{bail, Context, Result};
 use clap::{Parser, Subcommand};
-use cntryl_stress::{format_console_runs, StressRun};
+use cntryl_stress::{artifact::StressRun, reporting::format_console_runs};
 use std::ffi::OsStr;
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -891,7 +891,7 @@ fn report_child_failures(results: &[StressRunResult]) {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use cntryl_stress::{
+    use cntryl_stress::artifact::{
         BenchmarkBudgets, BenchmarkMode, BenchmarkSpec, BenchmarkSummary, CorrectnessCounters,
         CorrectnessSummary, EnvironmentInfo, MeasurementIntent, PrimaryMetric, ProfileConfig,
         QualityClass, RunProfile, Sample, SamplePhase, SummaryStats, SCHEMA_VERSION,

core/src/config.rs

@@ -1,6 +1,6 @@
 //! Configuration and profile resolution for stress runs.
 
-use crate::result::{
+use crate::artifact::{
     BenchmarkMode, BenchmarkModeKind, ProfileConfig, QualityClass, RunProfile, MAX_TIER,
 };
 use std::collections::HashMap;

core/src/context.rs

@@ -1,7 +1,7 @@
 //! Benchmark context for named measurements, workload facts, and correctness counters.
 
 use crate::allocation;
-use crate::result::{BenchmarkMode, CorrectnessCounters, MeasurementIntent};
+use crate::artifact::{BenchmarkMode, CorrectnessCounters, MeasurementIntent};
 use std::collections::BTreeMap;
 use std::future::Future;
 use std::time::{Duration, Instant};
@@ -44,11 +44,11 @@ pub(crate) struct MeasurementOverrides {
 }
 
 impl MeasurementOverrides {
-    pub fn target_for_phase(self, phase: crate::result::SamplePhase, default: usize) -> usize {
+    pub fn target_for_phase(self, phase: crate::artifact::SamplePhase, default: usize) -> usize {
         match phase {
-            crate::result::SamplePhase::Warmup => self.warmup_samples.unwrap_or(default),
-            crate::result::SamplePhase::Measured => self.samples.unwrap_or(default),
-            crate::result::SamplePhase::Cooldown => self.cooldown_samples.unwrap_or(default),
+            crate::artifact::SamplePhase::Warmup => self.warmup_samples.unwrap_or(default),
+            crate::artifact::SamplePhase::Measured => self.samples.unwrap_or(default),
+            crate::artifact::SamplePhase::Cooldown => self.cooldown_samples.unwrap_or(default),
         }
     }
 }

core/src/harness.rs

@@ -1,7 +1,7 @@
 //! Harness for auto-discovered stress benchmarks.
 
+use crate::artifact::{BenchmarkBudgets, BenchmarkModeKind, BenchmarkSpec, RunProfile};
 use crate::config::{parse_bool_env, StressRunnerConfig};
-use crate::result::{BenchmarkBudgets, BenchmarkModeKind, BenchmarkSpec, RunProfile};
 use crate::runner::{evaluate_run_gate, RunGate, StressRunner};
 use crate::StressContext;
 use std::collections::BTreeMap;
@@ -305,11 +305,13 @@ impl StressRunnerOptions {
 }
 
 /// Run all registered benchmarks with default options.
+#[allow(dead_code)]
 pub fn run_registered_benchmarks() {
     run_with_options(StressRunnerOptions::new());
 }
 
 /// Run all registered benchmarks with programmatic options.
+#[allow(dead_code)]
 pub fn run_with_options(options: StressRunnerOptions) {
     let args = StressBinaryArgs {
         workload: options.workload,
@@ -465,7 +467,7 @@ fn run_with_resolved_config(resolved: ResolvedStressConfig) {
             name: display_name,
             tier: entry.tier,
             mode: config_for_specs.mode_for_kind(entry.mode),
-            intent: crate::result::MeasurementIntent::General,
+            intent: crate::artifact::MeasurementIntent::General,
             budgets: entry.budgets,
             parameters: BTreeMap::new(),
             metadata,
@@ -694,6 +696,7 @@ pub fn list_benchmarks() -> Vec<&'static str> {
 
 /// Get the number of registered benchmarks.
 #[must_use]
+#[allow(dead_code)]
 pub fn benchmark_count() -> usize {
     STRESS_BENCHMARKS.len()
 }

core/src/lib.rs

@@ -45,12 +45,12 @@
 //! ```
 
 mod allocation;
+pub mod artifact;
 mod config;
-mod context;
+pub mod context;
 mod harness;
-mod report;
-mod result;
-mod runner;
+pub mod reporting;
+pub mod runner;
 
 #[cfg(test)]
 #[global_allocator]
@@ -64,37 +64,22 @@ static CNTRYL_STRESS_TEST_ALLOCATOR: allocation::StressAllocator =
 static CNTRYL_STRESS_TEST_ALLOCATOR_INSTALLATION: fn() =
     allocation::stress_allocator_installed_marker;
 
-pub use allocation::StressAllocator;
+pub use artifact::RunProfile;
 pub use config::StressRunnerConfig;
-pub use context::{CorrectnessRecorder, StressContext};
-pub use report::{
-    format_console_run, format_console_runs, ConsoleReporter, GitHubActionsReporter, JsonReporter,
-    MultiReporter, Reporter,
-};
-pub use result::{
-    BenchmarkBudgets, BenchmarkDiagnostic, BenchmarkMode, BenchmarkModeKind, BenchmarkSpec,
-    BenchmarkSummary, BudgetResult, ComparisonClass, ComparisonResult, ConfidenceInterval,
-    CorrectnessCounters, CorrectnessSummary, DiagnosticSeverity, EnvironmentInfo,
-    MeasurementIntent, PrimaryMetric, ProfileConfig, QualityClass, RunProfile, Sample, SamplePhase,
-    StressRun, SummaryStats, MAX_TIER, SCHEMA_VERSION,
-};
-pub use runner::{evaluate_run_gate, RunGate, StressRunner};
+pub use context::StressContext;
+pub use runner::StressRunner;
 pub use std::hint::black_box;
 
 pub use cntryl_stress_macros::{stress, stress_main};
-pub use harness::stress_binary_main;
-pub use harness::{benchmark_count, list_benchmarks};
-pub use harness::{
-    run_from_env_and_args, run_registered_benchmarks, run_with_options, StressRunnerOptions,
-};
+pub use harness::StressRunnerOptions;
 
 /// Private module for macro internals.
 #[doc(hidden)]
 pub mod __private {
     pub use crate::allocation::{
-        stress_allocator_installed_marker, STRESS_ALLOCATOR_INSTALLATIONS,
+        stress_allocator_installed_marker, StressAllocator, STRESS_ALLOCATOR_INSTALLATIONS,
     };
-    pub use crate::harness::{linkme, BenchmarkEntry, STRESS_BENCHMARKS};
+    pub use crate::harness::{linkme, stress_binary_main, BenchmarkEntry, STRESS_BENCHMARKS};
 
     /// Run a future to completion without requiring a runtime dependency.
     pub fn block_on<F: std::future::Future>(future: F) -> F::Output {
@@ -132,7 +117,8 @@ pub mod __private {
 macro_rules! stress_allocator {
     () => {
         #[global_allocator]
-        static CNTRYL_STRESS_ALLOCATOR: $crate::StressAllocator = $crate::StressAllocator::new();
+        static CNTRYL_STRESS_ALLOCATOR: $crate::__private::StressAllocator =
+            $crate::__private::StressAllocator::new();
 
         #[allow(non_upper_case_globals)]
         #[::cntryl_stress::__private::linkme::distributed_slice(

core/src/report.rs core/src/reporting.rscore/src/report.rs renamed to core/src/reporting.rs

@@ -1,10 +1,10 @@
 //! Pluggable reporters for current stress artifacts.
 
-use crate::config::StressRunnerConfig;
-use crate::result::{
+use crate::artifact::{
     BenchmarkDiagnostic, BenchmarkSummary, ComparisonClass, ComparisonResult, CorrectnessSummary,
     PrimaryMetric, QualityClass, StressRun, SummaryStats,
 };
+use crate::config::StressRunnerConfig;
 use std::collections::{BTreeMap, BTreeSet};
 use std::fmt::Write as FmtWrite;
 use std::io::Write;
@@ -1282,7 +1282,7 @@ fn budget_note(summary: &BenchmarkSummary) -> String {
         .join(", ")
 }
 
-fn allocation_budget_unavailable(result: &crate::result::BudgetResult) -> bool {
+fn allocation_budget_unavailable(result: &crate::artifact::BudgetResult) -> bool {
     matches!(
         result.metric.as_str(),
         "max_allocs_per_op" | "max_bytes_per_op"
@@ -1759,7 +1759,7 @@ fn format_duration_ns(nanos: u128) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::result::{
+    use crate::artifact::{
         BenchmarkBudgets, BenchmarkMode, BenchmarkSpec, BudgetResult, ComparisonResult,
         CorrectnessCounters, CorrectnessSummary, DiagnosticSeverity, EnvironmentInfo,
         MeasurementIntent, Sample, SamplePhase, SummaryStats, SCHEMA_VERSION,
@@ -1804,7 +1804,7 @@ mod tests {
 
     fn run_with_summaries(summaries: Vec<BenchmarkSummary>) -> StressRun {
         let profile_config =
-            crate::config::StressRunnerConfig::for_profile(crate::result::RunProfile::Release)
+            crate::config::StressRunnerConfig::for_profile(crate::artifact::RunProfile::Release)
                 .profile_config();
         StressRun {
             schema_version: SCHEMA_VERSION.to_string(),

core/src/runner.rs

@@ -1,13 +1,13 @@
 //! Stress runner that records raw samples and derives current artifacts.
 
-use crate::config::StressRunnerConfig;
-use crate::context::{MeasurementRecord, StressContext};
-use crate::report::{ConsoleReporter, JsonReporter, JsonStdoutReporter, Reporter};
-use crate::result::{
+use crate::artifact::{
     attach_regression_diagnostics, compare_summaries, summarize_benchmark, BenchmarkModeKind,
     BenchmarkSpec, ComparisonClass, EnvironmentInfo, MeasurementIntent, Sample, SamplePhase,
     StressRun, MAX_TIER, SCHEMA_VERSION,
 };
+use crate::config::StressRunnerConfig;
+use crate::context::{MeasurementRecord, StressContext};
+use crate::reporting::{ConsoleReporter, JsonReporter, JsonStdoutReporter, Reporter};
 use std::collections::BTreeMap;
 use std::path::Path;
 use std::process::Command;
@@ -19,7 +19,7 @@ pub struct StressRunner {
     config: StressRunnerConfig,
     benchmark_specs: Vec<BenchmarkSpec>,
     samples: Vec<Sample>,
-    summaries: Vec<crate::result::BenchmarkSummary>,
+    summaries: Vec<crate::artifact::BenchmarkSummary>,
     suite_start: Instant,
     reporters: Vec<Box<dyn Reporter>>,
     metadata: BTreeMap<String, String>,
@@ -129,7 +129,7 @@ impl StressRunner {
                 .config
                 .mode_for_kind(BenchmarkModeKind::FixedOperations),
             intent: MeasurementIntent::General,
-            budgets: crate::result::BenchmarkBudgets::default(),
+            budgets: crate::artifact::BenchmarkBudgets::default(),
             parameters: BTreeMap::new(),
             metadata: BTreeMap::new(),
         };
@@ -229,7 +229,7 @@ impl StressRunner {
         Ok(self.finish_inner(comparisons))
     }
 
-    fn finish_inner(mut self, comparisons: Vec<crate::result::ComparisonResult>) -> StressRun {
+    fn finish_inner(mut self, comparisons: Vec<crate::artifact::ComparisonResult>) -> StressRun {
         attach_regression_diagnostics(&mut self.summaries, &comparisons);
         let run = StressRun {
             schema_version: SCHEMA_VERSION.to_string(),
@@ -580,7 +580,7 @@ pub fn evaluate_run_gate(run: &StressRun) -> RunGate {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::result::{
+    use crate::artifact::{
         BenchmarkBudgets, BenchmarkMode, BenchmarkModeKind, CorrectnessCounters, PrimaryMetric,
         RunProfile,
     };
@@ -644,7 +644,7 @@ mod tests {
                 operations_per_sample: 1,
             },
             intent: MeasurementIntent::General,
-            budgets: crate::result::BenchmarkBudgets::default(),
+            budgets: crate::artifact::BenchmarkBudgets::default(),
             parameters: BTreeMap::new(),
             metadata: BTreeMap::new(),
         };
@@ -670,7 +670,7 @@ mod tests {
                 operations_per_sample: 1,
             },
             intent: MeasurementIntent::General,
-            budgets: crate::result::BenchmarkBudgets::default(),
+            budgets: crate::artifact::BenchmarkBudgets::default(),
             parameters: BTreeMap::new(),
             metadata: BTreeMap::new(),
         };
@@ -739,7 +739,7 @@ mod tests {
                 sample_duration: Duration::from_millis(1),
             },
             intent: MeasurementIntent::General,
-            budgets: crate::result::BenchmarkBudgets::default(),
+            budgets: crate::artifact::BenchmarkBudgets::default(),
             parameters: BTreeMap::new(),
             metadata: BTreeMap::new(),
         };