tiny.profiling.options

1const std = @import("std");2const namespace = @import("root.zig");34const analyze = namespace.analyze;5const baseline = namespace.baseline;6const catalog = namespace.catalog;7const cycle = namespace.cycle;8const driver = namespace.driver;9const execute = namespace.execute;10const host = namespace.host;11const plan = namespace.plan;12const perturbation = namespace.perturbation;13const question = namespace.question;14const report = namespace.report.memory;15const record = namespace.record;16const web = namespace.report;17const Allocator = std.mem.Allocator;1819pub const PlanOptions = struct {20    suite: catalog.Suite = .standard,21    filters: []const []const u8 = &.{},22    json: bool = false,23};2425pub const RunOptions = struct {26    plan: PlanOptions = .{},27    dry_run: bool = false,28    continue_on_failure: bool = false,29    output_dir: []const u8 = record.default_output_dir,30    run_id: ?[]const u8 = null,31    save_baseline: ?[]const u8 = null,32    host_lanes: host.Options = .{},33    execution_scope: execute.Scope = .binary,34    warmup_repeat: u32 = 0,35    measure_repeat: u32 = 1,36    interleave_seed: ?u64 = null,37    capture_control: perturbation.Options = .{},38    trace_allocations: bool = false,39    tracy: bool = false,40    control: execute.BenchControl = .{},41    forwarded: []const []const u8 = &.{},42};4344const ExperimentOptions = struct {45    plan_path: []const u8,46    output_dir: []const u8 = record.default_output_dir,47    run_id: ?[]const u8 = null,48    dry_run: bool = false,49    json: bool = false,50};5152const IterationOptions = ExperimentOptions;5354const QuestionOptions = struct {55    route: question.Options,56    json: bool = false,57};5859const InterleaveArgs = struct {60    seed: ?u64 = null,6162    fn parse(self: *InterleaveArgs, args: []const []const u8, index: *usize) !bool {63        const arg = args[index.*];64        if (std.mem.startsWith(u8, arg, "--interleave-seed=")) {65            self.seed = try parseInterleaveSeed(arg["--interleave-seed=".len..]);66            index.* += 1;67            return true;68        }69        if (std.mem.eql(u8, arg, "--interleave-seed")) {70            index.* += 1;71            if (index.* >= args.len) return error.MissingArgument;72            self.seed = try parseInterleaveSeed(args[index.*]);73            index.* += 1;74            return true;75        }76        return false;77    }78};7980const CaptureControlArgs = struct {81    options: perturbation.Options = .{},8283    fn parse(self: *CaptureControlArgs, args: []const []const u8, index: *usize) !bool {84        const arg = args[index.*];85        if (std.mem.startsWith(u8, arg, "--capture-control-repeat=")) {86            self.options.repeat = try parseCaptureControlRepeat(87                arg["--capture-control-repeat=".len..],88            );89            index.* += 1;90            return true;91        }92        if (std.mem.eql(u8, arg, "--capture-control-repeat")) {93            index.* += 1;94            if (index.* >= args.len) return error.MissingArgument;95            self.options.repeat = try parseCaptureControlRepeat(args[index.*]);96            index.* += 1;97            return true;98        }99        if (std.mem.startsWith(u8, arg, "--capture-control-seed=")) {100            self.options.seed = try parseCaptureControlSeed(101                arg["--capture-control-seed=".len..],102            );103            index.* += 1;104            return true;105        }106        if (std.mem.eql(u8, arg, "--capture-control-seed")) {107            index.* += 1;108            if (index.* >= args.len) return error.MissingArgument;109            self.options.seed = try parseCaptureControlSeed(args[index.*]);110            index.* += 1;111            return true;112        }113        return false;114    }115};116117const CounterArgs = struct {118    enabled: bool = false,119    energy: bool = false,120    events: ?[]const u8 = null,121    group_size: ?u32 = null,122    repeat: ?u32 = null,123124    fn parse(self: *CounterArgs, args: []const []const u8, index: *usize) !bool {125        const arg = args[index.*];126        if (std.mem.eql(u8, arg, "--counters")) {127            self.enabled = true;128            index.* += 1;129            return true;130        }131        if (std.mem.eql(u8, arg, "--energy")) {132            self.energy = true;133            index.* += 1;134            return true;135        }136        if (std.mem.startsWith(u8, arg, "--counter-events=")) {137            self.events = arg["--counter-events=".len..];138            index.* += 1;139            return true;140        }141        if (std.mem.eql(u8, arg, "--counter-events")) {142            index.* += 1;143            if (index.* >= args.len) return error.MissingArgument;144            self.events = args[index.*];145            index.* += 1;146            return true;147        }148        if (std.mem.startsWith(u8, arg, "--counter-group-size=")) {149            self.group_size = try parseCounterGroupSize(150                arg["--counter-group-size=".len..],151            );152            index.* += 1;153            return true;154        }155        if (std.mem.eql(u8, arg, "--counter-group-size")) {156            index.* += 1;157            if (index.* >= args.len) return error.MissingArgument;158            self.group_size = try parseCounterGroupSize(args[index.*]);159            index.* += 1;160            return true;161        }162        if (std.mem.startsWith(u8, arg, "--counter-repeat=")) {163            self.repeat = try parseCounterRepeat(arg["--counter-repeat=".len..]);164            index.* += 1;165            return true;166        }167        if (std.mem.eql(u8, arg, "--counter-repeat")) {168            index.* += 1;169            if (index.* >= args.len) return error.MissingArgument;170            self.repeat = try parseCounterRepeat(args[index.*]);171            index.* += 1;172            return true;173        }174        return false;175    }176177    fn value(self: CounterArgs) !?host.counters.Options {178        if (self.energy and self.events != null) return error.EnergyCounterEventsConflict;179        if (self.energy and (self.group_size orelse 0) != 0) {180            return error.EnergyCounterGroupingConflict;181        }182        if (!self.enabled and !self.energy and self.events == null and183            self.group_size == null and self.repeat == null) return null;184        return .{185            .events = if (self.energy)186                host.counters.energy_events187            else188                self.events orelse host.counters.default_events,189            .group_size = self.group_size orelse 0,190            .repeat = self.repeat orelse host.counters.default_repeat,191            .system_wide = self.energy,192        };193    }194};195196const SamplingArgs = struct {197    enabled: bool = false,198    frequency: ?u32 = null,199    min_samples: ?u64 = null,200201    fn parse(self: *SamplingArgs, args: []const []const u8, index: *usize) !bool {202        const arg = args[index.*];203        if (std.mem.eql(u8, arg, "--sampled")) {204            self.enabled = true;205            index.* += 1;206            return true;207        }208        if (std.mem.startsWith(u8, arg, "--sampled-frequency=")) {209            self.frequency = try parseSamplingFrequency(210                arg["--sampled-frequency=".len..],211            );212            index.* += 1;213            return true;214        }215        if (std.mem.eql(u8, arg, "--sampled-frequency")) {216            index.* += 1;217            if (index.* >= args.len) return error.MissingArgument;218            self.frequency = try parseSamplingFrequency(args[index.*]);219            index.* += 1;220            return true;221        }222        if (std.mem.startsWith(u8, arg, "--sampled-min-samples=")) {223            self.min_samples = try parseMinimumSampleCount(224                arg["--sampled-min-samples=".len..],225            );226            index.* += 1;227            return true;228        }229        if (std.mem.eql(u8, arg, "--sampled-min-samples")) {230            index.* += 1;231            if (index.* >= args.len) return error.MissingArgument;232            self.min_samples = try parseMinimumSampleCount(args[index.*]);233            index.* += 1;234            return true;235        }236        return false;237    }238239    fn value(self: SamplingArgs) ?host.sampling.Options {240        if (!self.enabled and self.frequency == null and self.min_samples == null) {241            return null;242        }243        return .{244            .frequency = self.frequency orelse host.sampling.default_frequency,245            .min_samples = self.min_samples orelse host.sampling.default_min_samples,246        };247    }248};249250pub fn parseIterationArgs(251    args: []const []const u8,252) !IterationOptions {253    return parseTypedPlanArgs(254        args,255        error.MissingIterationPlan,256    );257}258259pub fn parseQuestionArgs(260    args: []const []const u8,261) !QuestionOptions {262    var kind: ?question.Kind = null;263    var workload: ?[]const u8 = null;264    var plan_path: ?[]const u8 = null;265    var baseline_input: ?[]const u8 = null;266    var run_id: ?[]const u8 = null;267    var json_output = false;268    var index: usize = 0;269    while (index < args.len) {270        const arg = args[index];271        if (std.mem.eql(u8, arg, "--json")) {272            json_output = true;273            index += 1;274        } else if (std.mem.startsWith(u8, arg, "--workload=")) {275            workload = try nonempty(arg["--workload=".len..]);276            index += 1;277        } else if (std.mem.eql(u8, arg, "--workload")) {278            index += 1;279            if (index >= args.len) return error.MissingArgument;280            workload = try nonempty(args[index]);281            index += 1;282        } else if (std.mem.startsWith(u8, arg, "--plan=")) {283            plan_path = try nonempty(arg["--plan=".len..]);284            index += 1;285        } else if (std.mem.eql(u8, arg, "--plan")) {286            index += 1;287            if (index >= args.len) return error.MissingArgument;288            plan_path = try nonempty(args[index]);289            index += 1;290        } else if (std.mem.startsWith(u8, arg, "--baseline=")) {291            baseline_input = try nonempty(292                arg["--baseline=".len..],293            );294            index += 1;295        } else if (std.mem.eql(u8, arg, "--baseline")) {296            index += 1;297            if (index >= args.len) return error.MissingArgument;298            baseline_input = try nonempty(args[index]);299            index += 1;300        } else if (std.mem.startsWith(u8, arg, "--run-id=")) {301            run_id = try nonempty(arg["--run-id=".len..]);302            index += 1;303        } else if (std.mem.eql(u8, arg, "--run-id")) {304            index += 1;305            if (index >= args.len) return error.MissingArgument;306            run_id = try nonempty(args[index]);307            index += 1;308        } else if (std.mem.startsWith(u8, arg, "-")) {309            return error.UnknownArgument;310        } else {311            if (kind != null) return error.UnexpectedArgument;312            kind = question.Kind.parse(arg) orelse313                return error.UnknownProfilingQuestion;314            index += 1;315        }316    }317    return .{318        .route = .{319            .kind = kind orelse return error.MissingProfilingQuestion,320            .workload = workload,321            .plan = plan_path,322            .baseline = baseline_input,323            .run_id = run_id,324        },325        .json = json_output,326    };327}328329pub fn parseExperimentArgs(args: []const []const u8) !ExperimentOptions {330    return parseTypedPlanArgs(331        args,332        error.MissingExperimentPlan,333    );334}335336fn parseTypedPlanArgs(337    args: []const []const u8,338    missing_plan: anyerror,339) !ExperimentOptions {340    var plan_path: ?[]const u8 = null;341    var output_dir: []const u8 = record.default_output_dir;342    var run_id: ?[]const u8 = null;343    var dry_run = false;344    var json = false;345    var index: usize = 0;346    while (index < args.len) {347        const arg = args[index];348        if (std.mem.eql(u8, arg, "--dry-run")) {349            dry_run = true;350            index += 1;351        } else if (std.mem.eql(u8, arg, "--json")) {352            json = true;353            index += 1;354        } else if (std.mem.startsWith(u8, arg, "--output-dir=")) {355            output_dir = try nonempty(356                arg["--output-dir=".len..],357            );358            index += 1;359        } else if (std.mem.eql(u8, arg, "--output-dir")) {360            index += 1;361            if (index >= args.len) return error.MissingArgument;362            output_dir = try nonempty(args[index]);363            index += 1;364        } else if (std.mem.startsWith(u8, arg, "--run-id=")) {365            run_id = try nonempty(arg["--run-id=".len..]);366            index += 1;367        } else if (std.mem.eql(u8, arg, "--run-id")) {368            index += 1;369            if (index >= args.len) return error.MissingArgument;370            run_id = try nonempty(args[index]);371            index += 1;372        } else if (std.mem.startsWith(u8, arg, "-")) {373            return error.UnknownArgument;374        } else {375            if (plan_path != null) return error.UnexpectedArgument;376            plan_path = arg;377            index += 1;378        }379    }380    return .{381        .plan_path = plan_path orelse return missing_plan,382        .output_dir = output_dir,383        .run_id = run_id,384        .dry_run = dry_run,385        .json = json,386    };387}388389fn nonempty(value: []const u8) ![]const u8 {390    if (value.len == 0) return error.MissingArgument;391    return value;392}393394pub fn validateRunOptions(options: RunOptions) !void {395    try options.host_lanes.validate();396    try driver.validateMeasureRepeat(397        options.measure_repeat,398        options.host_lanes,399        options.tracy,400        options.control.causal,401    );402    try perturbation.validateCompatibility(403        options.capture_control,404        options.measure_repeat,405        options.execution_scope,406        options.host_lanes,407        options.tracy,408        options.trace_allocations,409        options.control.causal,410    );411    try driver.validateInterleave(412        options.interleave_seed,413        selectionFromPlan(options.plan).count(),414        options.measure_repeat,415        options.continue_on_failure,416    );417    if (options.tracy and options.execution_scope != .binary) {418        return error.TracyRequiresBinaryScope;419    }420}421422pub fn parseCycleArgs(allocator: Allocator, args: []const []const u8) !cycle.Options {423    var filters: std.ArrayList([]const u8) = .empty;424    var options = cycle.Options{};425    var counter_args: CounterArgs = .{};426    var sampling_args: SamplingArgs = .{};427    var capture_control_args: CaptureControlArgs = .{};428    var interleave_args: InterleaveArgs = .{};429    var baseline_explicit = false;430    var index: usize = 0;431    while (index < args.len) {432        const arg = args[index];433        if (!std.mem.eql(u8, arg, "--") and try counter_args.parse(args, &index)) {434            continue;435        }436        if (!std.mem.eql(u8, arg, "--") and try sampling_args.parse(args, &index)) {437            continue;438        }439        if (!std.mem.eql(u8, arg, "--") and try capture_control_args.parse(args, &index)) {440            continue;441        }442        if (!std.mem.eql(u8, arg, "--") and try interleave_args.parse(args, &index)) {443            continue;444        }445        if (std.mem.eql(u8, arg, "--")) {446            options.forwarded = args[index + 1 ..];447            break;448        } else if (std.mem.eql(u8, arg, "--stop-on-failure")) {449            options.stop_on_failure = true;450            index += 1;451        } else if (std.mem.startsWith(u8, arg, "--workload=")) {452            try filters.append(allocator, arg["--workload=".len..]);453            index += 1;454        } else if (std.mem.eql(u8, arg, "--workload")) {455            index += 1;456            if (index >= args.len) return error.MissingArgument;457            try filters.append(allocator, args[index]);458            index += 1;459        } else if (std.mem.startsWith(u8, arg, "--suite=")) {460            options.suite = catalog.Suite.parse(arg["--suite=".len..]) orelse return error.UnknownSuite;461            index += 1;462        } else if (std.mem.eql(u8, arg, "--suite")) {463            index += 1;464            if (index >= args.len) return error.MissingArgument;465            options.suite = catalog.Suite.parse(args[index]) orelse return error.UnknownSuite;466            index += 1;467        } else if (std.mem.startsWith(u8, arg, "--baseline=")) {468            options.baseline_name = arg["--baseline=".len..];469            baseline_explicit = true;470            index += 1;471        } else if (std.mem.eql(u8, arg, "--baseline")) {472            index += 1;473            if (index >= args.len) return error.MissingArgument;474            options.baseline_name = args[index];475            baseline_explicit = true;476            index += 1;477        } else if (std.mem.startsWith(u8, arg, "--execution-scope=")) {478            options.execution_scope = execute.Scope.parse(arg["--execution-scope=".len..]) orelse return error.UnknownExecutionScope;479            index += 1;480        } else if (std.mem.eql(u8, arg, "--execution-scope")) {481            index += 1;482            if (index >= args.len) return error.MissingArgument;483            options.execution_scope = execute.Scope.parse(args[index]) orelse return error.UnknownExecutionScope;484            index += 1;485        } else if (std.mem.startsWith(u8, arg, "--measure-repeat=")) {486            options.measure_repeat = try parseMeasureRepeat(487                arg["--measure-repeat=".len..],488            );489            index += 1;490        } else if (std.mem.eql(u8, arg, "--measure-repeat")) {491            index += 1;492            if (index >= args.len) return error.MissingArgument;493            options.measure_repeat = try parseMeasureRepeat(args[index]);494            index += 1;495        } else if (std.mem.startsWith(u8, arg, "--warmup-repeat=")) {496            options.warmup_repeat = try parseWarmupRepeat(497                arg["--warmup-repeat=".len..],498            );499            index += 1;500        } else if (std.mem.eql(u8, arg, "--warmup-repeat")) {501            index += 1;502            if (index >= args.len) return error.MissingArgument;503            options.warmup_repeat = try parseWarmupRepeat(args[index]);504            index += 1;505        } else if (std.mem.startsWith(u8, arg, "--output-dir=")) {506            options.output_dir = arg["--output-dir=".len..];507            index += 1;508        } else if (std.mem.eql(u8, arg, "--output-dir")) {509            index += 1;510            if (index >= args.len) return error.MissingArgument;511            options.output_dir = args[index];512            index += 1;513        } else if (std.mem.startsWith(u8, arg, "--keep=")) {514            options.keep = try std.fmt.parseInt(usize, arg["--keep=".len..], 10);515            index += 1;516        } else if (std.mem.eql(u8, arg, "--keep")) {517            index += 1;518            if (index >= args.len) return error.MissingArgument;519            options.keep = try std.fmt.parseInt(usize, args[index], 10);520            index += 1;521        } else if (std.mem.startsWith(u8, arg, "--threshold=")) {522            options.threshold_percent = try std.fmt.parseFloat(f64, arg["--threshold=".len..]);523            index += 1;524        } else if (std.mem.eql(u8, arg, "--threshold")) {525            index += 1;526            if (index >= args.len) return error.MissingArgument;527            options.threshold_percent = try std.fmt.parseFloat(f64, args[index]);528            index += 1;529        } else if (std.mem.startsWith(u8, arg, "--top=")) {530            options.top = try std.fmt.parseInt(usize, arg["--top=".len..], 10);531            index += 1;532        } else if (std.mem.eql(u8, arg, "--top")) {533            index += 1;534            if (index >= args.len) return error.MissingArgument;535            options.top = try std.fmt.parseInt(usize, args[index], 10);536            index += 1;537        } else {538            return error.UnknownArgument;539        }540    }541    options.filters = filters.items;542    options.interleave_seed = interleave_args.seed;543    if (!baseline_explicit) options.baseline_name = cycle.defaultBaselineName(options.execution_scope);544    options.host_lanes.counters = try counter_args.value();545    options.host_lanes.sampling = sampling_args.value();546    options.capture_control = capture_control_args.options;547    return options;548}549550const WebOptions = struct {551    site: web.Options = .{},552    serve: bool = false,553    port: u16 = 8787,554    address: []const u8 = "127.0.0.1",555    json: bool = false,556};557558pub fn parseWebArgs(args: []const []const u8) !WebOptions {559    var options = WebOptions{};560    var index: usize = 0;561    while (index < args.len) {562        const arg = args[index];563        if (std.mem.eql(u8, arg, "--json")) {564            options.json = true;565            index += 1;566        } else if (std.mem.startsWith(u8, arg, "--profiling-dir=")) {567            options.site.profiling_dir = arg["--profiling-dir=".len..];568            index += 1;569        } else if (std.mem.eql(u8, arg, "--profiling-dir")) {570            index += 1;571            if (index >= args.len) return error.MissingArgument;572            options.site.profiling_dir = args[index];573            index += 1;574        } else if (std.mem.startsWith(u8, arg, "--output=")) {575            options.site.output_dir = arg["--output=".len..];576            index += 1;577        } else if (std.mem.eql(u8, arg, "--output")) {578            index += 1;579            if (index >= args.len) return error.MissingArgument;580            options.site.output_dir = args[index];581            index += 1;582        } else if (std.mem.eql(u8, arg, "--serve")) {583            options.serve = true;584            index += 1;585        } else if (std.mem.startsWith(u8, arg, "--port=")) {586            options.port = try std.fmt.parseInt(u16, arg["--port=".len..], 10);587            options.serve = true;588            index += 1;589        } else if (std.mem.eql(u8, arg, "--port")) {590            index += 1;591            if (index >= args.len) return error.MissingArgument;592            options.port = try std.fmt.parseInt(u16, args[index], 10);593            options.serve = true;594            index += 1;595        } else if (std.mem.startsWith(u8, arg, "--address=")) {596            options.address = arg["--address=".len..];597            options.serve = true;598            index += 1;599        } else if (std.mem.eql(u8, arg, "--address")) {600            index += 1;601            if (index >= args.len) return error.MissingArgument;602            options.address = args[index];603            options.serve = true;604            index += 1;605        } else {606            return error.UnknownArgument;607        }608    }609    return options;610}611612pub fn parseAnalyzeArgs(args: []const []const u8) !analyze.Options {613    if (args.len == 0) return error.MissingArgument;614    var options = analyze.Options{ .input = args[0] };615    var index: usize = 1;616    while (index < args.len) {617        const arg = args[index];618        if (std.mem.eql(u8, arg, "--json")) {619            options.json = true;620            index += 1;621        } else if (std.mem.startsWith(u8, arg, "--baseline=")) {622            options.baseline_input = arg["--baseline=".len..];623            index += 1;624        } else if (std.mem.eql(u8, arg, "--baseline")) {625            index += 1;626            if (index >= args.len) return error.MissingArgument;627            options.baseline_input = args[index];628            index += 1;629        } else if (std.mem.startsWith(u8, arg, "--threshold=")) {630            options.regression_threshold_percent = try std.fmt.parseFloat(f64, arg["--threshold=".len..]);631            index += 1;632        } else if (std.mem.eql(u8, arg, "--threshold")) {633            index += 1;634            if (index >= args.len) return error.MissingArgument;635            options.regression_threshold_percent = try std.fmt.parseFloat(f64, args[index]);636            index += 1;637        } else if (std.mem.startsWith(u8, arg, "--top=")) {638            options.top = try std.fmt.parseInt(usize, arg["--top=".len..], 10);639            index += 1;640        } else if (std.mem.eql(u8, arg, "--top")) {641            index += 1;642            if (index >= args.len) return error.MissingArgument;643            options.top = try std.fmt.parseInt(usize, args[index], 10);644            index += 1;645        } else {646            return error.UnknownArgument;647        }648    }649    return options;650}651652pub fn parsePlanArgs(allocator: Allocator, args: []const []const u8) !PlanOptions {653    var filters: std.ArrayList([]const u8) = .empty;654    var options = PlanOptions{};655    var index: usize = 0;656    while (index < args.len) {657        const arg = args[index];658        if (std.mem.eql(u8, arg, "--json")) {659            options.json = true;660            index += 1;661        } else if (std.mem.startsWith(u8, arg, "--suite=")) {662            options.suite = catalog.Suite.parse(arg["--suite=".len..]) orelse return error.UnknownSuite;663            index += 1;664        } else if (std.mem.eql(u8, arg, "--suite")) {665            index += 1;666            if (index >= args.len) return error.MissingArgument;667            options.suite = catalog.Suite.parse(args[index]) orelse return error.UnknownSuite;668            index += 1;669        } else if (std.mem.startsWith(u8, arg, "--workload=")) {670            try filters.append(allocator, arg["--workload=".len..]);671            index += 1;672        } else if (std.mem.eql(u8, arg, "--workload")) {673            index += 1;674            if (index >= args.len) return error.MissingArgument;675            try filters.append(allocator, args[index]);676            index += 1;677        } else {678            return error.UnknownArgument;679        }680    }681    options.filters = filters.items;682    return options;683}684685pub fn parseRunArgs(allocator: Allocator, args: []const []const u8) !RunOptions {686    var filters: std.ArrayList([]const u8) = .empty;687    var options = RunOptions{};688    var counter_args: CounterArgs = .{};689    var sampling_args: SamplingArgs = .{};690    var capture_control_args: CaptureControlArgs = .{};691    var interleave_args: InterleaveArgs = .{};692    var dhat_enabled = false;693    var offcpu_enabled = false;694    var coverage_enabled = false;695    var offcpu_tool: ?[]const u8 = null;696    var offcpu_mode: ?host.offcpu.Mode = null;697    var index: usize = 0;698    while (index < args.len) {699        const arg = args[index];700        if (!std.mem.eql(u8, arg, "--") and try counter_args.parse(args, &index)) {701            continue;702        }703        if (!std.mem.eql(u8, arg, "--") and try sampling_args.parse(args, &index)) {704            continue;705        }706        if (!std.mem.eql(u8, arg, "--") and try capture_control_args.parse(args, &index)) {707            continue;708        }709        if (!std.mem.eql(u8, arg, "--") and try interleave_args.parse(args, &index)) {710            continue;711        }712        if (std.mem.eql(u8, arg, "--")) {713            options.forwarded = args[index + 1 ..];714            break;715        } else if (std.mem.eql(u8, arg, "--json")) {716            options.plan.json = true;717            index += 1;718        } else if (std.mem.eql(u8, arg, "--dry-run")) {719            options.dry_run = true;720            index += 1;721        } else if (std.mem.eql(u8, arg, "--continue-on-failure")) {722            options.continue_on_failure = true;723            index += 1;724        } else if (std.mem.eql(u8, arg, "--coverage")) {725            coverage_enabled = true;726            index += 1;727        } else if (std.mem.startsWith(u8, arg, "--bench-filter=")) {728            options.control.filter = arg["--bench-filter=".len..];729            index += 1;730        } else if (std.mem.eql(u8, arg, "--bench-filter")) {731            index += 1;732            if (index >= args.len) return error.MissingArgument;733            options.control.filter = args[index];734            index += 1;735        } else if (std.mem.eql(u8, arg, "--causal")) {736            options.control.causal = true;737            index += 1;738        } else if (std.mem.startsWith(u8, arg, "--causal-min-time=")) {739            options.control.min_time_ns = try parseCausalMinTime(740                arg["--causal-min-time=".len..],741            );742            options.control.causal = true;743            index += 1;744        } else if (std.mem.eql(u8, arg, "--causal-min-time")) {745            index += 1;746            if (index >= args.len) return error.MissingArgument;747            options.control.min_time_ns = try parseCausalMinTime(args[index]);748            options.control.causal = true;749            index += 1;750        } else if (std.mem.startsWith(u8, arg, "--causal-filter=")) {751            options.control.filter = arg["--causal-filter=".len..];752            options.control.causal = true;753            index += 1;754        } else if (std.mem.eql(u8, arg, "--causal-filter")) {755            index += 1;756            if (index >= args.len) return error.MissingArgument;757            options.control.filter = args[index];758            options.control.causal = true;759            index += 1;760        } else if (std.mem.eql(u8, arg, "--dhat")) {761            dhat_enabled = true;762            index += 1;763        } else if (std.mem.eql(u8, arg, "--tracy")) {764            options.tracy = true;765            index += 1;766        } else if (std.mem.eql(u8, arg, "--trace-allocations")) {767            options.trace_allocations = true;768            index += 1;769        } else if (std.mem.eql(u8, arg, "--offcpu")) {770            offcpu_enabled = true;771            index += 1;772        } else if (std.mem.startsWith(u8, arg, "--offcpu-tool=")) {773            offcpu_tool = arg["--offcpu-tool=".len..];774            index += 1;775        } else if (std.mem.eql(u8, arg, "--offcpu-tool")) {776            index += 1;777            if (index >= args.len) return error.MissingArgument;778            offcpu_tool = args[index];779            index += 1;780        } else if (std.mem.startsWith(u8, arg, "--offcpu-mode=")) {781            offcpu_mode = host.offcpu.Mode.parse(arg["--offcpu-mode=".len..]) orelse return error.UnknownOffcpuMode;782            index += 1;783        } else if (std.mem.eql(u8, arg, "--offcpu-mode")) {784            index += 1;785            if (index >= args.len) return error.MissingArgument;786            offcpu_mode = host.offcpu.Mode.parse(args[index]) orelse return error.UnknownOffcpuMode;787            index += 1;788        } else if (std.mem.startsWith(u8, arg, "--output-dir=")) {789            options.output_dir = arg["--output-dir=".len..];790            index += 1;791        } else if (std.mem.eql(u8, arg, "--output-dir")) {792            index += 1;793            if (index >= args.len) return error.MissingArgument;794            options.output_dir = args[index];795            index += 1;796        } else if (std.mem.startsWith(u8, arg, "--run-id=")) {797            options.run_id = arg["--run-id=".len..];798            index += 1;799        } else if (std.mem.eql(u8, arg, "--run-id")) {800            index += 1;801            if (index >= args.len) return error.MissingArgument;802            options.run_id = args[index];803            index += 1;804        } else if (std.mem.startsWith(u8, arg, "--save-baseline=")) {805            options.save_baseline = arg["--save-baseline=".len..];806            index += 1;807        } else if (std.mem.eql(u8, arg, "--save-baseline")) {808            index += 1;809            if (index >= args.len) return error.MissingArgument;810            options.save_baseline = args[index];811            index += 1;812        } else if (std.mem.startsWith(u8, arg, "--execution-scope=")) {813            options.execution_scope = execute.Scope.parse(arg["--execution-scope=".len..]) orelse return error.UnknownExecutionScope;814            index += 1;815        } else if (std.mem.eql(u8, arg, "--execution-scope")) {816            index += 1;817            if (index >= args.len) return error.MissingArgument;818            options.execution_scope = execute.Scope.parse(args[index]) orelse return error.UnknownExecutionScope;819            index += 1;820        } else if (std.mem.startsWith(u8, arg, "--measure-repeat=")) {821            options.measure_repeat = try parseMeasureRepeat(822                arg["--measure-repeat=".len..],823            );824            index += 1;825        } else if (std.mem.eql(u8, arg, "--measure-repeat")) {826            index += 1;827            if (index >= args.len) return error.MissingArgument;828            options.measure_repeat = try parseMeasureRepeat(args[index]);829            index += 1;830        } else if (std.mem.startsWith(u8, arg, "--warmup-repeat=")) {831            options.warmup_repeat = try parseWarmupRepeat(832                arg["--warmup-repeat=".len..],833            );834            index += 1;835        } else if (std.mem.eql(u8, arg, "--warmup-repeat")) {836            index += 1;837            if (index >= args.len) return error.MissingArgument;838            options.warmup_repeat = try parseWarmupRepeat(args[index]);839            index += 1;840        } else if (std.mem.startsWith(u8, arg, "--suite=")) {841            options.plan.suite = catalog.Suite.parse(arg["--suite=".len..]) orelse return error.UnknownSuite;842            index += 1;843        } else if (std.mem.eql(u8, arg, "--suite")) {844            index += 1;845            if (index >= args.len) return error.MissingArgument;846            options.plan.suite = catalog.Suite.parse(args[index]) orelse return error.UnknownSuite;847            index += 1;848        } else if (std.mem.startsWith(u8, arg, "--workload=")) {849            try filters.append(allocator, arg["--workload=".len..]);850            index += 1;851        } else if (std.mem.eql(u8, arg, "--workload")) {852            index += 1;853            if (index >= args.len) return error.MissingArgument;854            try filters.append(allocator, args[index]);855            index += 1;856        } else {857            return error.UnknownArgument;858        }859    }860    options.plan.filters = filters.items;861    options.interleave_seed = interleave_args.seed;862    options.host_lanes.counters = try counter_args.value();863    options.host_lanes.sampling = sampling_args.value();864    options.capture_control = capture_control_args.options;865    if (dhat_enabled) {866        options.host_lanes.dhat = .{};867    }868    if (offcpu_enabled or offcpu_tool != null or offcpu_mode != null) {869        options.host_lanes.offcpu = .{ .tool = offcpu_tool, .mode = offcpu_mode orelse .time };870    }871    if (coverage_enabled) {872        options.host_lanes.coverage = .{};873    }874    return options;875}876877fn parseCausalMinTime(text: []const u8) !u64 {878    const seconds = std.fmt.parseUnsigned(u64, text, 10) catch return error.InvalidCausalMinTime;879    return std.math.mul(u64, seconds, std.time.ns_per_s) catch error.InvalidCausalMinTime;880}881882fn parseCounterRepeat(text: []const u8) !u32 {883    const value = std.fmt.parseUnsigned(u32, text, 10) catch884        return error.InvalidCounterRepeat;885    if (!host.process.validRepeat(value)) return error.InvalidCounterRepeat;886    return value;887}888889fn parseMeasureRepeat(text: []const u8) !u32 {890    const value = std.fmt.parseUnsigned(u32, text, 10) catch891        return error.InvalidMeasureRepeat;892    if (!host.process.validRepeat(value)) {893        return error.InvalidMeasureRepeat;894    }895    return value;896}897898fn parseInterleaveSeed(text: []const u8) !u64 {899    return std.fmt.parseUnsigned(u64, text, 10) catch900        error.InvalidInterleaveSeed;901}902903fn parseWarmupRepeat(text: []const u8) !u32 {904    const value = std.fmt.parseUnsigned(u32, text, 10) catch905        return error.InvalidWarmupRepeat;906    if (!host.process.validWarmupRepeat(value)) {907        return error.InvalidWarmupRepeat;908    }909    return value;910}911912fn parseCaptureControlRepeat(text: []const u8) !u32 {913    const value = std.fmt.parseUnsigned(u32, text, 10) catch914        return error.InvalidCaptureControlRepeat;915    if (value == 0 or value > perturbation.max_pairs) {916        return error.InvalidCaptureControlRepeat;917    }918    return value;919}920921fn parseCaptureControlSeed(text: []const u8) !u64 {922    return std.fmt.parseUnsigned(u64, text, 10) catch923        error.InvalidCaptureControlSeed;924}925926fn parseCounterGroupSize(text: []const u8) !u32 {927    const value = std.fmt.parseUnsigned(u32, text, 10) catch928        return error.InvalidCounterGroupSize;929    if (value > host.counters.max_group_size) return error.InvalidCounterGroupSize;930    return value;931}932933fn parseSamplingFrequency(text: []const u8) !u32 {934    const value = std.fmt.parseUnsigned(u32, text, 10) catch935        return error.InvalidSamplingFrequency;936    if (value == 0) return error.InvalidSamplingFrequency;937    return value;938}939940fn parseMinimumSampleCount(text: []const u8) !u64 {941    const value = std.fmt.parseUnsigned(u64, text, 10) catch942        return error.InvalidMinimumSampleCount;943    if (value == 0) return error.InvalidMinimumSampleCount;944    return value;945}946947pub fn parseMemoryArgs(args: []const []const u8) !report.Options {948    if (args.len == 0) return error.MissingArgument;949    var options = report.Options{ .input = args[0] };950    var index: usize = 1;951    while (index < args.len) {952        const arg = args[index];953        if (std.mem.eql(u8, arg, "--json")) {954            options.json = true;955            index += 1;956        } else if (std.mem.startsWith(u8, arg, "--top=")) {957            options.top = try std.fmt.parseInt(usize, arg["--top=".len..], 10);958            index += 1;959        } else if (std.mem.eql(u8, arg, "--top")) {960            index += 1;961            if (index >= args.len) return error.MissingArgument;962            options.top = try std.fmt.parseInt(usize, args[index], 10);963            index += 1;964        } else if (std.mem.startsWith(u8, arg, "--min-bytes=")) {965            options.min_bytes = try std.fmt.parseInt(usize, arg["--min-bytes=".len..], 10);966            index += 1;967        } else if (std.mem.eql(u8, arg, "--min-bytes")) {968            index += 1;969            if (index >= args.len) return error.MissingArgument;970            options.min_bytes = try std.fmt.parseInt(usize, args[index], 10);971            index += 1;972        } else {973            return error.UnknownArgument;974        }975    }976    return options;977}978979pub fn parseBaselinePruneArgs(args: []const []const u8) !baseline.PruneOptions {980    var options = baseline.PruneOptions{};981    var index: usize = 0;982    while (index < args.len) {983        const arg = args[index];984        if (std.mem.eql(u8, arg, "--dry-run")) {985            options.dry_run = true;986            index += 1;987        } else if (std.mem.startsWith(u8, arg, "--keep-last=")) {988            options.keep_last = try std.fmt.parseInt(usize, arg["--keep-last=".len..], 10);989            index += 1;990        } else if (std.mem.eql(u8, arg, "--keep-last")) {991            index += 1;992            if (index >= args.len) return error.MissingArgument;993            options.keep_last = try std.fmt.parseInt(usize, args[index], 10);994            index += 1;995        } else if (std.mem.startsWith(u8, arg, "--older-than=")) {996            options.older_than_ns = try parseDurationNs(arg["--older-than=".len..]);997            index += 1;998        } else if (std.mem.eql(u8, arg, "--older-than")) {999            index += 1;1000            if (index >= args.len) return error.MissingArgument;1001            options.older_than_ns = try parseDurationNs(args[index]);1002            index += 1;1003        } else {1004            return error.UnknownArgument;1005        }1006    }1007    if (options.keep_last == null and options.older_than_ns == null) return error.MissingPruneRule;1008    return options;1009}10101011fn parseDurationNs(value: []const u8) !i128 {1012    if (value.len < 2) return error.InvalidDuration;1013    const suffix = value[value.len - 1];1014    const multiplier: i128 = switch (suffix) {1015        's' => std.time.ns_per_s,1016        'm' => std.time.ns_per_min,1017        'h' => std.time.ns_per_hour,1018        'd' => std.time.ns_per_day,1019        else => return error.InvalidDuration,1020    };1021    const number = try std.fmt.parseInt(i128, value[0 .. value.len - 1], 10);1022    if (number < 0) return error.InvalidDuration;1023    return number * multiplier;1024}10251026pub fn selectionFromPlan(options: PlanOptions) plan.Selection {1027    return .{ .suite = options.suite, .filters = options.filters };1028}10291030test "profiling CLI parses plan options" {1031    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1032    defer arena_state.deinit();1033    const options = try parsePlanArgs(arena_state.allocator(), &.{ "--suite", "smoke", "--workload", "smg-bench", "--json" });1034    try std.testing.expectEqual(catalog.Suite.smoke, options.suite);1035    try std.testing.expect(options.json);1036    try std.testing.expectEqual(@as(usize, 1), options.filters.len);1037    try std.testing.expectEqualStrings("smg-bench", options.filters[0]);1038}10391040test "profiling CLI parses run forwarded args" {1041    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1042    defer arena_state.deinit();1043    const options = try parseRunArgs(arena_state.allocator(), &.{ "--suite=all", "--dry-run", "--tracy", "--trace-allocations", "--execution-scope=binary", "--warmup-repeat=2", "--measure-repeat=1", "--output-dir", "zig-out/custom", "--run-id", "run-a", "--save-baseline", "main", "--", "--test-filter", "bench:" });1044    try std.testing.expectEqual(catalog.Suite.all, options.plan.suite);1045    try std.testing.expect(options.dry_run);1046    try std.testing.expectEqualStrings("zig-out/custom", options.output_dir);1047    try std.testing.expectEqualStrings("run-a", options.run_id.?);1048    try std.testing.expectEqualStrings("main", options.save_baseline.?);1049    try std.testing.expectEqual(execute.Scope.binary, options.execution_scope);1050    try std.testing.expectEqual(@as(u32, 2), options.warmup_repeat);1051    try std.testing.expectEqual(@as(u32, 1), options.measure_repeat);1052    try std.testing.expect(options.tracy);1053    try std.testing.expect(options.trace_allocations);1054    try std.testing.expectEqual(@as(usize, 2), options.forwarded.len);1055}10561057test "profiling CLI defaults runtime runs to prepared binaries" {1058    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1059    defer arena_state.deinit();1060    const options = try parseRunArgs(arena_state.allocator(), &.{});1061    try std.testing.expectEqual(execute.Scope.binary, options.execution_scope);1062    try std.testing.expectEqual(1063        std.builtin.OptimizeMode.fast,1064        driver.effectiveOptimize(options.host_lanes),1065    );1066    try std.testing.expectError(1067        error.UnknownArgument,1068        parseRunArgs(arena_state.allocator(), &.{ "--optimize", "ReleaseSafe" }),1069    );1070}10711072test "profiling CLI limits Tracy capture to prepared binaries" {1073    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1074    defer arena_state.deinit();1075    const step_options = try parseRunArgs(1076        arena_state.allocator(),1077        &.{ "--tracy", "--execution-scope=step" },1078    );1079    try std.testing.expectError(error.TracyRequiresBinaryScope, validateRunOptions(step_options));1080    const mixed_options = try parseRunArgs(1081        arena_state.allocator(),1082        &.{ "--tracy", "--execution-scope=mixed" },1083    );1084    try std.testing.expectError(error.TracyRequiresBinaryScope, validateRunOptions(mixed_options));1085}10861087test "profiling CLI validates workload filters" {1088    try plan.validateFilters(&.{"smg.graph"});1089    try std.testing.expectError(error.UnknownWorkload, plan.validateFilters(&.{"missing"}));1090}10911092test "profiling CLI causal stretch and filter imply the causal lane" {1093    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1094    defer arena_state.deinit();1095    const options = try parseRunArgs(arena_state.allocator(), &.{ "--causal-min-time", "30", "--causal-filter=small alloc" });1096    try std.testing.expect(options.control.causal);1097    try std.testing.expectEqual(@as(?u64, 30_000_000_000), options.control.min_time_ns);1098    try std.testing.expectEqualStrings("small alloc", options.control.filter.?);10991100    const bare = try parseRunArgs(arena_state.allocator(), &.{"--causal"});1101    try std.testing.expect(bare.control.causal);1102    try std.testing.expectEqual(@as(?u64, null), bare.control.min_time_ns);1103    try std.testing.expect(bare.control.filter == null);11041105    try std.testing.expectError(error.InvalidCausalMinTime, parseRunArgs(arena_state.allocator(), &.{ "--causal-min-time", "30s" }));1106}11071108test "profiling CLI benchmark filter preserves the ordinary lane" {1109    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1110    defer arena_state.deinit();1111    const allocator = arena_state.allocator();1112    const joined = try parseRunArgs(1113        allocator,1114        &.{"--bench-filter=program image cache"},1115    );1116    try std.testing.expect(!joined.control.causal);1117    try std.testing.expectEqualStrings(1118        "program image cache",1119        joined.control.filter.?,1120    );1121    const split = try parseRunArgs(1122        allocator,1123        &.{ "--bench-filter", "small alloc" },1124    );1125    try std.testing.expect(!split.control.causal);1126    try std.testing.expectEqualStrings("small alloc", split.control.filter.?);1127}11281129test "profiling CLI parses sampling support controls" {1130    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1131    defer arena_state.deinit();1132    const allocator = arena_state.allocator();1133    const options = try parseRunArgs(1134        allocator,1135        &.{ "--sampled-frequency", "997", "--sampled-min-samples=900" },1136    );1137    const sampling = options.host_lanes.sampling.?;1138    try std.testing.expectEqual(@as(u32, 997), sampling.frequency);1139    try std.testing.expectEqual(@as(u64, 900), sampling.min_samples);1140    try std.testing.expectError(1141        error.InvalidSamplingFrequency,1142        parseRunArgs(allocator, &.{ "--sampled-frequency", "0" }),1143    );1144    try std.testing.expectError(1145        error.InvalidMinimumSampleCount,1146        parseRunArgs(allocator, &.{ "--sampled-min-samples", "0" }),1147    );1148    try std.testing.expectError(1149        error.UnknownArgument,1150        parseRunArgs(allocator, &.{ "--sampled-scope", "step" }),1151    );1152}11531154test "profiling CLI parses bounded counter groups and repetitions" {1155    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1156    defer arena_state.deinit();1157    const allocator = arena_state.allocator();1158    const defaults = try parseRunArgs(allocator, &.{"--counters"});1159    try std.testing.expectEqualStrings(1160        host.counters.default_events,1161        defaults.host_lanes.counters.?.events,1162    );1163    try std.testing.expectEqual(1164        host.counters.default_repeat,1165        defaults.host_lanes.counters.?.repeat,1166    );1167    const single = try parseRunArgs(allocator, &.{"--counter-repeat=1"});1168    try std.testing.expectEqual(@as(u32, 1), single.host_lanes.counters.?.repeat);1169    const options = try parseRunArgs(1170        allocator,1171        &.{ "--counter-events", "cycles,instructions", "--counter-group-size=1", "--counter-repeat=3" },1172    );1173    const counters = options.host_lanes.counters.?;1174    try std.testing.expectEqualStrings("cycles,instructions", counters.events);1175    try std.testing.expectEqual(@as(u32, 1), counters.group_size);1176    try std.testing.expectEqual(@as(u32, 3), counters.repeat);1177    const repeated_cycle = try parseCycleArgs(allocator, &.{"--counter-repeat=4"});1178    try std.testing.expectEqual(1179        @as(u32, 4),1180        repeated_cycle.host_lanes.counters.?.repeat,1181    );1182    try std.testing.expectError(1183        error.InvalidCounterRepeat,1184        parseRunArgs(allocator, &.{ "--counter-repeat", "0" }),1185    );1186    try std.testing.expectError(1187        error.InvalidCounterRepeat,1188        parseCycleArgs(allocator, &.{"--counter-repeat=101"}),1189    );1190    try std.testing.expectError(1191        error.InvalidCounterGroupSize,1192        parseRunArgs(allocator, &.{"--counter-group-size=101"}),1193    );1194}11951196test "profiling CLI selects paired system domain energy evidence" {1197    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1198    defer arena_state.deinit();1199    const allocator = arena_state.allocator();1200    const options = try parseRunArgs(1201        allocator,1202        &.{ "--energy", "--counter-repeat=4" },1203    );1204    const counters = options.host_lanes.counters.?;1205    try std.testing.expectEqualStrings(host.counters.energy_events, counters.events);1206    try std.testing.expectEqual(@as(u32, 4), counters.repeat);1207    try std.testing.expectEqual(@as(u32, 0), counters.group_size);1208    try std.testing.expect(counters.system_wide);1209    const cycle_options_value = try parseCycleArgs(allocator, &.{"--energy"});1210    try std.testing.expect(cycle_options_value.host_lanes.counters.?.system_wide);1211    try std.testing.expectError(1212        error.EnergyCounterEventsConflict,1213        parseRunArgs(allocator, &.{ "--energy", "--counter-events=cycles" }),1214    );1215    try std.testing.expectError(1216        error.EnergyCounterGroupingConflict,1217        parseRunArgs(allocator, &.{ "--energy", "--counter-group-size=1" }),1218    );1219}12201221test "profiling CLI parses bounded ordinary process repetitions" {1222    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1223    defer arena_state.deinit();1224    const allocator = arena_state.allocator();1225    const options = try parseRunArgs(allocator, &.{"--measure-repeat=3"});1226    try std.testing.expectEqual(@as(u32, 3), options.measure_repeat);1227    const cycle_options_value = try parseCycleArgs(1228        allocator,1229        &.{ "--measure-repeat", "4" },1230    );1231    try std.testing.expectEqual(@as(u32, 4), cycle_options_value.measure_repeat);1232    try std.testing.expectError(1233        error.InvalidMeasureRepeat,1234        parseRunArgs(allocator, &.{ "--measure-repeat", "0" }),1235    );1236    try std.testing.expectError(1237        error.InvalidMeasureRepeat,1238        parseCycleArgs(allocator, &.{"--measure-repeat=101"}),1239    );1240}12411242test "profiling CLI parses deterministic repetition interleaving" {1243    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1244    defer arena_state.deinit();1245    const allocator = arena_state.allocator();1246    const options = try parseRunArgs(1247        allocator,1248        &.{ "--measure-repeat=9", "--interleave-seed", "42", "--continue-on-failure" },1249    );1250    try std.testing.expectEqual(@as(?u64, 42), options.interleave_seed);1251    try std.testing.expect(options.continue_on_failure);1252    try validateRunOptions(options);1253    const cycle_options_value = try parseCycleArgs(1254        allocator,1255        &.{ "--measure-repeat", "7", "--interleave-seed=99" },1256    );1257    try std.testing.expectEqual(@as(?u64, 99), cycle_options_value.interleave_seed);1258    try std.testing.expectError(1259        error.InvalidInterleaveSeed,1260        parseRunArgs(allocator, &.{ "--interleave-seed", "random" }),1261    );1262}12631264test "profiling CLI parses bounded unmeasured process warmups" {1265    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1266    defer arena_state.deinit();1267    const allocator = arena_state.allocator();1268    const zero = try parseRunArgs(allocator, &.{"--warmup-repeat=0"});1269    try std.testing.expectEqual(@as(u32, 0), zero.warmup_repeat);1270    const maximum = try parseCycleArgs(1271        allocator,1272        &.{ "--warmup-repeat", "100" },1273    );1274    try std.testing.expectEqual(@as(u32, 100), maximum.warmup_repeat);1275    try std.testing.expectError(1276        error.InvalidWarmupRepeat,1277        parseRunArgs(allocator, &.{ "--warmup-repeat", "101" }),1278    );1279    try std.testing.expectError(1280        error.InvalidWarmupRepeat,1281        parseCycleArgs(allocator, &.{"--warmup-repeat=invalid"}),1282    );1283}12841285test "profiling CLI parses bounded capture control pairs" {1286    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1287    defer arena_state.deinit();1288    const allocator = arena_state.allocator();1289    const options = try parseRunArgs(allocator, &.{1290        "--sampled",1291        "--capture-control-repeat=5",1292        "--capture-control-seed",1293        "42",1294    });1295    try std.testing.expectEqual(@as(u32, 5), options.capture_control.repeat);1296    try std.testing.expectEqual(@as(u64, 42), options.capture_control.seed);1297    try validateRunOptions(options);1298    const cycle_options_value = try parseCycleArgs(allocator, &.{1299        "--sampled",1300        "--capture-control-repeat",1301        "4",1302        "--capture-control-seed=7",1303    });1304    try std.testing.expectEqual(1305        @as(u32, 4),1306        cycle_options_value.capture_control.repeat,1307    );1308    try std.testing.expectEqual(1309        @as(u64, 7),1310        cycle_options_value.capture_control.seed,1311    );1312    try std.testing.expectError(1313        error.InvalidCaptureControlRepeat,1314        parseRunArgs(allocator, &.{ "--capture-control-repeat", "0" }),1315    );1316    try std.testing.expectError(1317        error.InvalidCaptureControlRepeat,1318        parseCycleArgs(allocator, &.{"--capture-control-repeat=51"}),1319    );1320    try std.testing.expectError(1321        error.InvalidCaptureControlSeed,1322        parseRunArgs(allocator, &.{ "--capture-control-seed", "seed" }),1323    );1324}13251326test "profiling CLI rejects incompatible capture control designs" {1327    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1328    defer arena_state.deinit();1329    const allocator = arena_state.allocator();1330    const no_capture = try parseRunArgs(1331        allocator,1332        &.{ "--capture-control-repeat", "3" },1333    );1334    try std.testing.expectError(1335        error.CaptureControlRequiresCapture,1336        validateRunOptions(no_capture),1337    );1338    const step_scope = try parseRunArgs(allocator, &.{1339        "--sampled",1340        "--execution-scope=step",1341        "--capture-control-repeat=3",1342    });1343    try std.testing.expectError(1344        error.CaptureControlRequiresBinaryScope,1345        validateRunOptions(step_scope),1346    );1347    const mixed_scope = try parseRunArgs(allocator, &.{1348        "--sampled",1349        "--execution-scope=mixed",1350        "--capture-control-repeat=3",1351    });1352    try std.testing.expectError(1353        error.CaptureControlRequiresBinaryScope,1354        validateRunOptions(mixed_scope),1355    );1356    const repeated = try parseRunArgs(allocator, &.{1357        "--sampled",1358        "--measure-repeat=2",1359        "--capture-control-repeat=3",1360    });1361    try std.testing.expectError(1362        error.MeasureRepeatConflictsWithCapture,1363        validateRunOptions(repeated),1364    );1365    const causal = try parseRunArgs(allocator, &.{1366        "--tracy",1367        "--causal",1368        "--capture-control-repeat=3",1369    });1370    try std.testing.expectError(1371        error.CaptureControlConflictsWithCausal,1372        validateRunOptions(causal),1373    );1374    const counter_matrix = try parseRunArgs(allocator, &.{1375        "--counter-repeat=2",1376        "--capture-control-repeat=3",1377    });1378    try std.testing.expectError(1379        error.CaptureControlConflictsWithCounterMatrix,1380        validateRunOptions(counter_matrix),1381    );1382}13831384test "profiling CLI parses source coverage lane" {1385    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1386    defer arena_state.deinit();1387    const options = try parseRunArgs(arena_state.allocator(), &.{"--coverage"});1388    try std.testing.expect(options.host_lanes.coverage != null);1389    try std.testing.expect(options.host_lanes.requiresDirect());1390    try std.testing.expectEqual(1391        std.builtin.OptimizeMode.debug,1392        driver.effectiveOptimize(options.host_lanes),1393    );1394}13951396test "profiling CLI parses cycle options" {1397    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1398    defer arena_state.deinit();1399    const options = try parseCycleArgs(arena_state.allocator(), &.{ "--suite", "standard", "--workload", "mprompt.smoke", "--baseline", "weekly", "--execution-scope", "step", "--warmup-repeat", "2", "--measure-repeat", "4", "--output-dir", "zig-out/custom", "--keep=3", "--threshold", "7.5", "--top=4", "--stop-on-failure", "--", "--warmup", "0" });1400    try std.testing.expectEqual(catalog.Suite.standard, options.suite);1401    try std.testing.expectEqual(@as(usize, 1), options.filters.len);1402    try std.testing.expectEqualStrings("mprompt.smoke", options.filters[0]);1403    try std.testing.expectEqualStrings("weekly", options.baseline_name);1404    try std.testing.expectEqual(execute.Scope.step, options.execution_scope);1405    try std.testing.expectEqual(@as(u32, 2), options.warmup_repeat);1406    try std.testing.expectEqual(@as(u32, 4), options.measure_repeat);1407    try std.testing.expectEqualStrings("zig-out/custom", options.output_dir);1408    try std.testing.expectEqual(@as(usize, 3), options.keep);1409    try std.testing.expectEqual(@as(f64, 7.5), options.threshold_percent);1410    try std.testing.expectEqual(@as(usize, 4), options.top);1411    try std.testing.expect(options.stop_on_failure);1412    try std.testing.expectEqual(@as(usize, 2), options.forwarded.len);1413}14141415test "profiling CLI cycle defaults roll the smoke suite" {1416    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1417    defer arena_state.deinit();1418    const options = try parseCycleArgs(arena_state.allocator(), &.{});1419    try std.testing.expectEqual(catalog.Suite.smoke, options.suite);1420    try std.testing.expectEqual(@as(usize, 0), options.filters.len);1421    try std.testing.expectEqual(execute.Scope.binary, options.execution_scope);1422    try std.testing.expectEqualStrings("cycle-binary", options.baseline_name);1423    try std.testing.expectEqual(@as(usize, 7), options.keep);1424    try std.testing.expect(!options.stop_on_failure);1425}14261427test "profiling CLI cycle parses sampling support controls" {1428    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1429    defer arena_state.deinit();1430    const options = try parseCycleArgs(1431        arena_state.allocator(),1432        &.{ "--sampled-frequency=499", "--sampled-min-samples", "800" },1433    );1434    const sampling = options.host_lanes.sampling.?;1435    try std.testing.expectEqual(@as(u32, 499), sampling.frequency);1436    try std.testing.expectEqual(@as(u64, 800), sampling.min_samples);1437}14381439test "profiling CLI step cycle defaults to the legacy baseline" {1440    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1441    defer arena_state.deinit();1442    const options = try parseCycleArgs(arena_state.allocator(), &.{ "--execution-scope", "step" });1443    try std.testing.expectEqual(execute.Scope.step, options.execution_scope);1444    try std.testing.expectEqualStrings("cycle", options.baseline_name);1445}14461447test "profiling CLI mixed cycle uses an isolated baseline" {1448    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1449    defer arena_state.deinit();1450    const options = try parseCycleArgs(arena_state.allocator(), &.{ "--execution-scope", "mixed" });1451    try std.testing.expectEqual(execute.Scope.mixed, options.execution_scope);1452    try std.testing.expectEqualStrings("cycle-mixed", options.baseline_name);1453}14541455test "profiling CLI parses analyze options" {1456    const options = try parseAnalyzeArgs(&.{ "zig-out/profiling/run-a", "--baseline", "main", "--threshold", "7.5", "--top=3", "--json" });1457    try std.testing.expectEqualStrings("zig-out/profiling/run-a", options.input);1458    try std.testing.expectEqualStrings("main", options.baseline_input.?);1459    try std.testing.expectEqual(@as(usize, 3), options.top);1460    try std.testing.expect(options.json);1461}14621463test "profiling CLI parses memory options" {1464    const options = try parseMemoryArgs(&.{ "zig-out/profiling/run-a", "--top", "7", "--min-bytes=32", "--json" });1465    try std.testing.expectEqualStrings("zig-out/profiling/run-a", options.input);1466    try std.testing.expectEqual(@as(usize, 7), options.top);1467    try std.testing.expectEqual(@as(usize, 32), options.min_bytes);1468    try std.testing.expect(options.json);1469}14701471test "profiling CLI parses baseline prune options" {1472    const options = try parseBaselinePruneArgs(&.{ "--keep-last", "3", "--older-than=14d", "--dry-run" });1473    try std.testing.expectEqual(@as(usize, 3), options.keep_last.?);1474    try std.testing.expectEqual(@as(i128, 14 * std.time.ns_per_day), options.older_than_ns.?);1475    try std.testing.expect(options.dry_run);1476    try std.testing.expectError(error.MissingPruneRule, parseBaselinePruneArgs(&.{"--dry-run"}));1477}14781479test "profiling CLI parses typed experiment options" {1480    const options = try parseExperimentArgs(&.{1481        "experiment.json",1482        "--output-dir=zig-out/evidence",1483        "--run-id",1484        "candidate-a",1485        "--dry-run",1486        "--json",1487    });1488    try std.testing.expectEqualStrings("experiment.json", options.plan_path);1489    try std.testing.expectEqualStrings("zig-out/evidence", options.output_dir);1490    try std.testing.expectEqualStrings("candidate-a", options.run_id.?);1491    try std.testing.expect(options.dry_run);1492    try std.testing.expect(options.json);1493    try std.testing.expectError(1494        error.MissingExperimentPlan,1495        parseExperimentArgs(&.{"--json"}),1496    );1497    try std.testing.expectError(1498        error.UnexpectedArgument,1499        parseExperimentArgs(&.{ "first.json", "second.json" }),1500    );1501}15021503test "profiling CLI parses typed iteration options" {1504    const options = try parseIterationArgs(&.{1505        "iteration.json",1506        "--output-dir=zig-out/evidence",1507        "--run-id",1508        "edit-a",1509        "--dry-run",1510        "--json",1511    });1512    try std.testing.expectEqualStrings("iteration.json", options.plan_path);1513    try std.testing.expectEqualStrings("zig-out/evidence", options.output_dir);1514    try std.testing.expectEqualStrings("edit-a", options.run_id.?);1515    try std.testing.expect(options.dry_run);1516    try std.testing.expect(options.json);1517    try std.testing.expectError(1518        error.MissingIterationPlan,1519        parseIterationArgs(&.{"--json"}),1520    );1521}15221523test "profiling CLI parses question routing inputs" {1524    const options = try parseQuestionArgs(&.{1525        "hotspot",1526        "--workload",1527        "gpalloc.allocator",1528        "--run-id=hot-a",1529        "--baseline",1530        "main",1531        "--json",1532    });1533    try std.testing.expectEqual(question.Kind.hotspot, options.route.kind);1534    try std.testing.expectEqualStrings(1535        "gpalloc.allocator",1536        options.route.workload.?,1537    );1538    try std.testing.expectEqualStrings("hot-a", options.route.run_id.?);1539    try std.testing.expectEqualStrings("main", options.route.baseline.?);1540    try std.testing.expect(options.json);1541    try std.testing.expectError(1542        error.MissingProfilingQuestion,1543        parseQuestionArgs(&.{"--json"}),1544    );1545}

1pub const options = @import("options.zig");