bitfab 0.68.0 → 0.69.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c05530ec639d246b474f368fae48df4ed2230e4275272f2d903c9ef81bc96b6b
-  data.tar.gz: 1019089f79f07cafb3b0e8be5604717ed32a1a894f28a7ae6b26d71cf05c1889
+  metadata.gz: 7c5044f5cc55988582b4a4428242ac2c0ea12fb87ba228054ad7c01a08e760ca
+  data.tar.gz: f410e0a0560c11fd3185c4f237bb30d37ac16ed5dcb3c0d4beb2d08d5b62f863
 SHA512:
-  metadata.gz: 551641d9eb87d4c98d16d17cf5f6dcfe3f795f84a8fe1c155ba14d5db41bb5e53b04229ce0424ecac59430f854e79790c1460fb9fbc7ba10a2e0cb2bf739acd4
-  data.tar.gz: 28c329c02e65d57a75af5ae12895be94bc525dfa6ef01e2203a7485e3998a5d6c0e04209e2e78694f6085777bdad2009dba36c6d8ee4b7e75bb95bf8d98e6f0f
+  metadata.gz: 680f7e7b023a94951496fba7b6b2aef5bb61f4250d3a3cfa5d2db3dae7a91038a0c3f03474419eb65e9defa0fc0c3811d7ee4346a4d9b50c15f2fa29a3bda703
+  data.tar.gz: b6230d97bb985ad5748e7e45121f89fdc4cbf65861eaa7ac815bd028bd34d43774a36f4ab3941b54e830121c7c097e2ee98da013834d783a69147a7b3a4dc570

data/lib/bitfab/client.rb

@@ -140,15 +140,23 @@ module Bitfab
     #   such as an environment override or a forced feature flag. Kept on the
     #   experiment next to its name (max 10,000 characters).
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
-    # @param code_change_description [String, nil] optional rationale for the
-    #   code change being tested in this replay (stored on the experiment).
-    #   When supplied without code_change_files, this text is preserved while
-    #   the SDK automatically captures the files.
-    #   Pass nil when the replay should have no description; use
-    #   code_change_files: nil to suppress automatic file capture.
-    # @param code_change_files [Array<Hash>, nil] optional list of edited files,
-    #   each as { path:, before:, after: } (use "" for new/deleted files).
-    #   Omit to capture automatically, or pass nil to suppress file capture.
+    # @param code_change [String] required. Which code change this replay
+    #   tests, stored on the experiment so it can be reviewed alongside the
+    #   results. A replay without it raises ArgumentError before any request.
+    #   "working-tree" is the uncommitted changes vs HEAD; "last-branch" the
+    #   diff against the branch this one was cut from, such as the branch below
+    #   it in a stack, else the default branch; "default-branch" the diff
+    #   against where HEAD split from the default branch (origin/HEAD, else
+    #   origin/main, origin/master, main, master); "skip" no code change, such
+    #   as for a baseline run; "manual" the files in code_change_files. The
+    #   three git choices include uncommitted edits and untracked files, and
+    #   warn and attach nothing when they find no changed files.
+    # @param code_change_description [String, nil] description of the code
+    #   change, stored on the experiment. Defaults to one generated from the
+    #   captured files. Not accepted with "skip".
+    # @param code_change_files [Array<Hash>, nil] the edited files when
+    #   code_change is "manual", and only then, each as { path:, before:, after: }
+    #   (use "" for new/deleted files).
     # @param experiment_group_id [String, nil] optional UUID grouping multiple
     #   replay runs into a single experiment batch. The run joins that group,
     #   and an id no group has yet creates it
@@ -214,7 +222,7 @@ module Bitfab
     # @return [Hash] with :items, :experiment_id, :experiment_url, and the
     #   deprecated aliases :test_run_id and :test_run_url carrying the same values
     def replay(receiver, method_name = nil, trace_function_key:, limit: nil, trace_ids: nil, concurrency: nil, max_concurrency: ReplayConcurrency::UNSET,
-      name: nil, notes: nil, metadata: nil, code_change_description: Replay::CODE_CHANGE_UNSET, code_change_files: Replay::CODE_CHANGE_UNSET, experiment_group_id: nil, experiment_group_name: nil, dataset_id: nil, dataset_ids: nil, grader_ids: nil, mock: "marked", attempts: ReplayConcurrency::UNSET, only_with_assertions: false, skip_assertion_judging: false, judge_assertions: nil, dry_run: false,
+      name: nil, notes: nil, metadata: nil, code_change: nil, code_change_description: nil, code_change_files: nil, experiment_group_id: nil, experiment_group_name: nil, dataset_id: nil, dataset_ids: nil, grader_ids: nil, mock: "marked", attempts: ReplayConcurrency::UNSET, only_with_assertions: false, skip_assertion_judging: false, judge_assertions: nil, dry_run: false,
       adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil,
       on_experiment_start: nil, experimental_selective_replay: nil)
       Replay.run(
@@ -234,6 +242,7 @@ module Bitfab
         skip_assertion_judging:,
         judge_assertions:,
         dry_run:,
+        code_change:,
         code_change_description:,
         code_change_files:,
         experiment_group_id:,

data/lib/bitfab/cloudReplay.py

@@ -147,8 +147,9 @@ RENAMED_FLAGS = {
     "--cloud-include": "nothing: new files that git does not ignore are already in the snapshot",
 }
 SEED_FLAGS = ("--seed", "--cases", "--from-trace", "--run")
-PATH_FLAGS = ("--registry", "--params", "--code-change")
-CODE_CHANGE_FLAGS = ("--code-change", "--no-code-change")
+PATH_FLAGS = ("--registry", "--params", "--code-change-file")
+CODE_CHANGE_FLAG = "--code-change"
+BRANCH_CODE_CHANGES = ("last-branch", "default-branch")
 CHECKOUT_DEPTH = 2
 CODE_CHANGE_PATH_ENV = "BITFAB_CODE_CHANGE_PATH"
 CODE_CHANGE_MAX_FILES = 60
@@ -1022,6 +1023,21 @@ def branch_point(root):
     return None
 
 
+def default_branch_point(root):
+    default = default_branch(root)
+    sha = quiet_git(root, "merge-base", "HEAD", default) if default else ""
+    return {"sha": sha, "ref": default} if sha else None
+
+
+def code_change_base(root, replay):
+    kind = flag_value(replay, CODE_CHANGE_FLAG)
+    if kind == "last-branch":
+        return branch_point(root)
+    if kind == "default-branch":
+        return default_branch_point(root)
+    return None
+
+
 def replay_artifact(path):
     return path == ".bitfab" or path.startswith(".bitfab/")
 
@@ -1126,11 +1142,10 @@ def snapshot(
         }
         if preview:
             return summary
-        code_change_base = request.get("codeChangeBase") or {}
+        branch_base = str((request.get("codeChangeBase") or {}).get("sha", ""))
         extra_parent = (
-            ["-p", code_change_base["sha"]]
-            if not any(not replay_artifact(path) for _, path in changes)
-            and SHA.fullmatch(str(code_change_base.get("sha", "")))
+            ["-p", branch_base]
+            if SHA.fullmatch(branch_base) and branch_base != head
             else []
         )
         sha = git(
@@ -1461,9 +1476,9 @@ def submit(root, repo, workflow, parsed, path):
     branch = current_branch(root)
     if branch:
         request["branch"] = branch
-    code_change_base = branch_point(root)
-    if code_change_base:
-        request["codeChangeBase"] = code_change_base
+    base = code_change_base(root, parsed["replay"])
+    if base:
+        request["codeChangeBase"] = base
     check_arguments(parsed["replay"])
     allowed = allowed_files(root, parsed)
     if "--cloud-preview" in parsed["switches"]:
@@ -2121,15 +2136,19 @@ def check_out_snapshot_base(root, commit, branch):
     return base
 
 
-def replay_name(args):
+def flag_value(args, flag):
     for index, value in enumerate(args):
-        if value.startswith("--name="):
+        if value.startswith(f"{flag}="):
             return value.partition("=")[2]
-        if value == "--name" and index + 1 < len(args):
+        if value == flag and index + 1 < len(args):
             return args[index + 1]
     return None
 
 
+def replay_name(args):
+    return flag_value(args, "--name")
+
+
 def git_blob(root, ref, path):
     try:
         size = int(git(root, "cat-file", "-s", f"{ref}:{path}"))
@@ -2209,7 +2228,10 @@ def branch_code_change(root, base, commit, request):
         and SHA.fullmatch(sha)
         and isinstance(ref, str)
         and BRANCH_NAME.fullmatch(ref)
-        and quiet_git(root, "rev-parse", "--verify", "-q", f"{commit}^2") == sha
+        and (
+            sha == base
+            or quiet_git(root, "rev-parse", "--verify", "-q", f"{commit}^2") == sha
+        )
     ):
         return None
     return snapshot_code_change(
@@ -2217,6 +2239,17 @@ def branch_code_change(root, base, commit, request):
     )
 
 
+def runner_code_change(root, base, commit, request):
+    kind = flag_value(request["args"], CODE_CHANGE_FLAG)
+    if kind == "working-tree":
+        change = snapshot_code_change(root, base, commit, replay_name(request["args"]))
+    elif kind in BRANCH_CODE_CHANGES:
+        change = branch_code_change(root, base, commit, request)
+    else:
+        return None
+    return change or {"files": []}
+
+
 def write_code_change(change):
     handle, path = tempfile.mkstemp(
         prefix="bitfab-code-change-",
@@ -2247,22 +2280,11 @@ def execute():
     if environment:
         workflow_environment_conflicts(root, environment)
         print(f"Setting {', '.join(sorted(environment))} from the request", flush=True)
-    names = {option_name(value) for value in request["args"]}
-    explicit_change = bool(names & set(CODE_CHANGE_FLAGS))
-    change = (
-        None
-        if explicit_change or base is None
-        else snapshot_code_change(root, base, commit, replay_name(request["args"]))
-        or branch_code_change(root, base, commit, request)
-    )
+    change = None if base is None else runner_code_change(root, base, commit, request)
     run_environment = dict(environment)
-    if change:
+    if change is not None:
         run_environment[CODE_CHANGE_PATH_ENV] = write_code_change(change)
-    args = [
-        *replay_command(),
-        *request["args"],
-        *([] if explicit_change or change else ["--no-code-change"]),
-    ]
+    args = [*replay_command(), *request["args"]]
     if dry_run(request["args"]):
         run_check_command(directory, environment)
     experiment = {}

data/lib/bitfab/replay.rb

@@ -142,7 +142,12 @@ module Bitfab
 
   # Replay historical traces through a traced method and create an experiment.
   module Replay
-    CODE_CHANGE_UNSET = Object.new.freeze
+    # The values Client#replay accepts for +code_change:+.
+    CODE_CHANGE_TYPES = %w[working-tree last-branch default-branch skip manual].freeze
+    # The +code_change:+ choices, as named in the errors that refuse a replay.
+    CODE_CHANGE_CHOICES = '"working-tree" (uncommitted changes vs HEAD), "last-branch" (the diff against the ' \
+      'branch this one was cut from), "default-branch" (the diff against the default branch), "skip" (no code ' \
+      'change), or "manual" (pass the files yourself)'
     UNSET_DEFAULT = Object.new.freeze
     OPTION_DEFAULTS = {mock: "marked"}.freeze
     PERSISTENCE_TIMEOUT_SECONDS = 30.0
@@ -199,7 +204,7 @@ module Bitfab
     def explicit_replay_options(options)
       options.reject do |option, value|
         value.nil? || value == false || value.equal?(ReplayConcurrency::UNSET) ||
-          value.equal?(CODE_CHANGE_UNSET) || value == OPTION_DEFAULTS.fetch(option, UNSET_DEFAULT)
+          value == OPTION_DEFAULTS.fetch(option, UNSET_DEFAULT)
       end
     end
 
@@ -225,15 +230,23 @@ module Bitfab
     #   such as an environment override or a forced feature flag. Kept on the
     #   experiment next to its name (max 10,000 characters).
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
-    # @param code_change_description [String, nil] optional rationale for the
-    #   code change being tested in this replay (stored on the experiment).
-    #   When supplied without code_change_files, this text is preserved while
-    #   the SDK automatically captures the files.
-    #   Pass nil when the replay should have no description; use
-    #   code_change_files: nil to suppress automatic file capture.
-    # @param code_change_files [Array<Hash>, nil] optional list of edited files,
-    #   each as { path:, before:, after: } (empty string for new/deleted files).
-    #   Omit to capture automatically, or pass nil to suppress file capture.
+    # @param code_change [String] required. Which code change this replay
+    #   tests, stored on the experiment so it can be reviewed alongside the
+    #   results. A replay without it raises ArgumentError before any request.
+    #   "working-tree" is the uncommitted changes vs HEAD; "last-branch" the
+    #   diff against the branch this one was cut from, such as the branch below
+    #   it in a stack, else the default branch; "default-branch" the diff
+    #   against where HEAD split from the default branch (origin/HEAD, else
+    #   origin/main, origin/master, main, master); "skip" no code change, such
+    #   as for a baseline run; "manual" the files in code_change_files. The
+    #   three git choices include uncommitted edits and untracked files, and
+    #   warn and attach nothing when they find no changed files.
+    # @param code_change_description [String, nil] description of the code
+    #   change, stored on the experiment. Defaults to one generated from the
+    #   captured files. Not accepted with "skip".
+    # @param code_change_files [Array<Hash>, nil] the edited files when
+    #   code_change is "manual", and only then, each as { path:, before:, after: }
+    #   (empty string for new/deleted files).
     # @param experiment_group_id [String, nil] optional UUID grouping multiple
     #   replay runs into a single experiment batch. The run joins that group,
     #   and an id no group has yet creates it
@@ -300,10 +313,11 @@ module Bitfab
     #   The experiment fields are nil for a dry run, which creates no experiment,
     #   and progress events then carry a nil :experiment_id too.
     def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil, notes: nil, metadata: nil,
-      concurrency: nil, max_concurrency: ReplayConcurrency::UNSET, code_change_description: CODE_CHANGE_UNSET, code_change_files: CODE_CHANGE_UNSET, experiment_group_id: nil, experiment_group_name: nil,
+      concurrency: nil, max_concurrency: ReplayConcurrency::UNSET, code_change: nil, code_change_description: nil, code_change_files: nil, experiment_group_id: nil, experiment_group_name: nil,
       dataset_id: nil, dataset_ids: nil, grader_ids: nil, mock: "marked", attempts: ReplayConcurrency::UNSET, only_with_assertions: false, skip_assertion_judging: false, judge_assertions: nil, dry_run: false,
       adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil,
       on_experiment_start: nil, experimental_selective_replay: nil)
+      validate_code_change(code_change, code_change_description, code_change_files)
       explicit_options = method(:run).parameters.filter_map { |type, option| [option, binding.local_variable_get(option)] if type == :key }
       skip_assertion_judging = resolve_skip_assertion_judging(skip_assertion_judging, judge_assertions)
       concurrency_options = ReplayConcurrency.resolve(concurrency, attempts, max_concurrency)
@@ -382,18 +396,7 @@ module Bitfab
 
       include_db_branch_lease = db_branch_enabled?(db_branch) && !dry_run
 
-      # code_change_files controls capture: omitted auto-captures, an array
-      # wins, and explicit nil opts out. Preserve a caller-supplied description
-      # while filling only the omitted files.
-      if code_change_files.equal?(CODE_CHANGE_UNSET)
-        captured = resolve_auto_code_change(name)
-        unless captured.nil?
-          code_change_files = captured[1]
-          code_change_description = captured[0] if code_change_description.equal?(CODE_CHANGE_UNSET)
-        end
-      end
-      code_change_description = nil if code_change_description.equal?(CODE_CHANGE_UNSET)
-      code_change_files = nil if code_change_files.equal?(CODE_CHANGE_UNSET)
+      code_change_description, code_change_files = resolve_code_change(code_change, code_change_description, code_change_files, name)
 
       resolved_db_branch_settings = db_branch_settings(db_branch)
       replay_data = http_client.start_replay(
@@ -591,10 +594,6 @@ module Bitfab
       result
     end
 
-    # Read the code-change payload the replay wrapper captured and pointed us at
-    # via BITFAB_CODE_CHANGE_PATH. Returns [description, files] or nil.
-    # Best-effort: any error (no env var, missing file, bad JSON) yields nil so
-    # the replay proceeds with no code change rather than raising.
     CC_MAX_FILES = 60
     CC_MAX_FILE_BYTES = 500_000
     CC_MAX_TOTAL_BYTES = 2_000_000
@@ -655,21 +654,36 @@ module Bitfab
       settings.empty? ? nil : settings
     end
 
-    # Auto-capture the code change to attach when the caller passed none. Lives
-    # in replay() (the one call guaranteed to run on every replay) so it works no
-    # matter how the replay was launched. Precedence: a BITFAB_CODE_CHANGE_PATH
-    # override, else the git diff of the working tree vs HEAD (or vs the
-    # merge-base with BITFAB_CODE_CHANGE_BASE). A clean working tree falls back to
-    # the point where HEAD split from the default branch, so committed branch work
-    # still shows. Best-effort: any failure yields nil.
-    # An explicit code_change_files always wins over this.
-    def resolve_auto_code_change(label = nil)
-      return nil if ENV["BITFAB_DISABLE_CODE_CHANGE_CAPTURE"]
-
-      from_env = read_code_change_file
-      return from_env unless from_env.nil?
-
-      capture_code_change_from_git(Dir.pwd, label)
+    def validate_code_change(code_change, description, files)
+      if code_change.nil?
+        raise ArgumentError, "replay needs a code_change naming the code this run tests: #{CODE_CHANGE_CHOICES}."
+      end
+      unless CODE_CHANGE_TYPES.include?(code_change)
+        raise ArgumentError, "Unknown code_change #{code_change.inspect}. Pass #{CODE_CHANGE_CHOICES}."
+      end
+      if code_change == "manual" && files.nil?
+        raise ArgumentError,
+          'code_change "manual" needs code_change_files: the path and before/after contents of each edited file.'
+      end
+      if code_change != "manual" && !files.nil?
+        raise ArgumentError, "code_change_files only applies with code_change \"manual\" (got \"#{code_change}\")."
+      end
+      if code_change == "skip" && !description.nil?
+        raise ArgumentError, 'code_change "skip" attaches no code change, so it cannot take a code_change_description.'
+      end
+      code_change
+    end
+
+    def resolve_code_change(code_change, description, files, label = nil)
+      return [nil, nil] if code_change == "skip"
+      return [description, files] if code_change == "manual"
+
+      captured = read_code_change_file || capture_code_change_from_git(Dir.pwd, code_change, label)
+      if captured.nil? || captured[1].nil? || captured[1].empty?
+        warn "Bitfab: code_change \"#{code_change}\" found no changed files, so this replay has no code change attached."
+        return [description, nil]
+      end
+      [description || captured[0], captured[1]]
     end
 
     def read_code_change_file
@@ -679,8 +693,6 @@ module Bitfab
       begin
         parsed = JSON.parse(File.read(path))
         files = parsed["files"]
-        # A malformed payload (non-array, or entries that aren't hashes) must
-        # yield no code change, never crash normalize_code_change_files.
         files = nil unless files.is_a?(Array) && files.all?(Hash)
         description = parsed["description"]
         description = nil unless description.is_a?(String)
@@ -700,18 +712,20 @@ module Bitfab
       !git(root, ["rev-parse", "--verify", "#{ref}^{object}"]).nil?
     end
 
-    # Returns [base, against]. HEAD by default, so only uncommitted edits show;
-    # BITFAB_CODE_CHANGE_BASE moves the base to the merge-base with that ref.
-    def cc_resolve_base(root)
-      forced = ENV["BITFAB_CODE_CHANGE_BASE"]
-      if forced && cc_ref_exists?(root, forced)
-        mb = git(root, ["merge-base", "HEAD", forced])
-        return [mb.strip, "vs #{forced}"] if mb && !mb.strip.empty?
-
-        rp = git(root, ["rev-parse", "--verify", forced])
-        return (rp && !rp.strip.empty?) ? [rp.strip, "vs #{forced}"] : nil
+    def cc_resolve_base(root, type)
+      case type
+      when "last-branch" then cc_resolve_branch_point(root)
+      when "default-branch" then cc_resolve_default_branch_point(root)
+      else cc_ref_exists?(root, "HEAD") ? ["HEAD", "uncommitted (vs HEAD)"] : nil
       end
-      cc_ref_exists?(root, "HEAD") ? ["HEAD", "uncommitted (vs HEAD)"] : nil
+    end
+
+    def cc_resolve_default_branch_point(root)
+      default = cc_default_branch(root)
+      return nil if default.nil?
+
+      base = (git(root, ["merge-base", "HEAD", default]) || "").strip
+      base.empty? ? nil : [base, "vs #{default}"]
     end
 
     def cc_list_changes(root, base)
@@ -794,22 +808,15 @@ module Bitfab
       0
     end
 
-    def capture_code_change_from_git(cwd, label = nil)
+    def capture_code_change_from_git(cwd, type, label = nil)
       root = git(cwd, ["rev-parse", "--show-toplevel"])
       return nil if root.nil? || root.strip.empty?
 
       root = root.strip
-      resolved = cc_resolve_base(root)
+      resolved = cc_resolve_base(root, type)
       return nil if resolved.nil?
 
       entries = cc_list_changes(root, resolved[0])
-      if entries.empty? && resolved[0] == "HEAD"
-        branch_point = cc_resolve_branch_point(root)
-        if branch_point
-          resolved = branch_point
-          entries = cc_list_changes(root, branch_point[0])
-        end
-      end
       return nil if entries.empty?
 
       base, against = resolved
@@ -819,15 +826,10 @@ module Bitfab
       entries.each do |status, before_path, path|
         break if files.length >= CC_MAX_FILES
 
-        # Skip oversized files by size BEFORE reading their full contents, so a
-        # huge changed file can't OOM/stall replay just to be discarded.
         before_bytes = (status == "A") ? 0 : cc_blob_bytes(root, base, before_path)
         after_bytes = (status == "D") ? 0 : cc_working_bytes(root, path)
         next if before_bytes > CC_MAX_FILE_BYTES || after_bytes > CC_MAX_FILE_BYTES
 
-        # Normalize CRLF -> LF on both sides: git's blob is already LF-normalized
-        # (autocrlf clean), so a raw CRLF working file would otherwise skew every
-        # line as changed. Comparing/storing LF keeps the diff meaningful.
         before = (status == "A") ? "" : (git(root, ["show", "#{base}:#{before_path}"]) || "").gsub("\r\n", "\n")
         after = (status == "D") ? "" : cc_read_working_file(root, path).gsub("\r\n", "\n")
         next if before == after

data/lib/bitfab/replay_cli.rb

@@ -47,7 +47,8 @@ module Bitfab
 
     def check_arguments(argv)
       _, replay_argv = parse(argv)
-      ReplayCli.parse(nil, replay_argv)
+      args = ReplayCli.parse(nil, replay_argv)
+      ReplayCli.require_code_change(args) unless args[:seed] || args[:from_trace]
       0
     end
 

data/lib/bitfab/replay_registry.rb

@@ -19,8 +19,7 @@ module Bitfab
   # Project-owned registry of production replay roots.
   class ReplayRegistry
     OPTION_NAMES = %i[
-      limit trace_ids name notes metadata concurrency max_concurrency code_change_description
-      code_change_files experiment_group_id experiment_group_name dataset_id dataset_ids grader_ids mock
+      limit trace_ids name notes metadata concurrency max_concurrency experiment_group_id experiment_group_name dataset_id dataset_ids grader_ids mock
       mock_override adapt_inputs db_branch attempts only_with_assertions skip_assertion_judging judge_assertions dry_run on_item_finish
     ].freeze
 
@@ -141,6 +140,7 @@ module Bitfab
     def run(registry, argv: ARGV, stdout: $stdout, stderr: $stderr)
       args = parse(registry, argv.dup)
       return SeedCli.run(registry, argv:, stdout:, stderr:) if args[:seed] || args[:from_trace]
+      require_code_change(args)
       stderr.puts "Bitfab: #{Replay::JUDGE_ASSERTIONS_DEPRECATION}" if args[:judge_assertions]
 
       registration = registry.fetch(args.fetch(:pipeline))
@@ -203,13 +203,11 @@ module Bitfab
         end
       end
 
-      if args[:code_change]
-        code_change = load_code_change(args[:code_change])
+      options[:code_change] = args.fetch(:code_change)
+      if args[:code_change_file]
+        code_change = load_code_change(args[:code_change_file])
         options[:code_change_description] = code_change.fetch("description")
         options[:code_change_files] = code_change.fetch("files")
-      elsif args[:no_code_change]
-        options[:code_change_description] = nil
-        options[:code_change_files] = nil
       end
 
       if options[:concurrency] || args[:primitive] || args.key?(:memory_throttle)
@@ -305,6 +303,7 @@ module Bitfab
       if argv.include?("--db-branch") && argv.include?("--no-db-branch")
         raise OptionParser::InvalidArgument, "--db-branch and --no-db-branch cannot be used together"
       end
+      raise ArgumentError, "--no-code-change was replaced by --code-change skip." if argv.include?("--no-code-change")
       args = {}
       parser = OptionParser.new do |options|
         options.banner = "Usage: bitfab-replay <#{registry ? registry.names.join("|") : "pipeline"}> [options]"
@@ -338,7 +337,19 @@ module Bitfab
         options.on("--max-concurrency N", Integer) do |value|
           args[:max_concurrency] = positive_integer("--max-concurrency", value)
         end
-        options.on("--code-change PATH") { |value| args[:code_change] = value }
+        options.on("--code-change working-tree|last-branch|default-branch|skip|manual",
+          "Required: the code change this run tests; working-tree is the uncommitted changes vs HEAD, " \
+            "last-branch the diff against the branch this one was cut from, default-branch the diff against the " \
+            "default branch, skip none, manual the edits in --code-change-file.") do |value|
+          unless Replay::CODE_CHANGE_TYPES.include?(value)
+            raise ArgumentError,
+              "Unknown --code-change '#{value}'. Pass #{Replay::CODE_CHANGE_CHOICES}. " \
+                "A file of edits goes in --code-change manual --code-change-file PATH."
+          end
+          args[:code_change] = value
+        end
+        options.on("--code-change-file PATH",
+          "With --code-change manual: a JSON file of { description, files }.") { |value| args[:code_change_file] = value }
         options.on("--experiment-group-id UUID",
           "Add this run to an experiment group. A UUID no group has yet creates the group.") { |value| args[:experiment_group_id] = value }
         options.on("--experiment-group-name NAME",
@@ -360,7 +371,6 @@ module Bitfab
         options.on("--mock STRATEGY", %w[none all marked]) { |value| args[:mock] = value }
         options.on("--db-branch") { args[:db_branch] = true }
         options.on("--no-db-branch") { args[:db_branch] = false }
-        options.on("--no-code-change") { args[:no_code_change] = true }
         options.on("--params PATH") { |value| args[:params] = value }
         options.on("--param NAME=VALUE") { |value| (args[:param] ||= []) << value }
       end
@@ -369,9 +379,6 @@ module Bitfab
         raise OptionParser::InvalidArgument,
           "--trace-ids and --dataset-ids select different replay sources and cannot be used together"
       end
-      if args[:code_change] && args[:no_code_change]
-        raise OptionParser::InvalidArgument, "--code-change and --no-code-change cannot be used together"
-      end
       pipeline = argv.shift
       known = pipeline && (registry.nil? || registry.names.include?(pipeline))
       raise OptionParser::MissingArgument, parser.banner unless known
@@ -380,6 +387,17 @@ module Bitfab
       args.merge(pipeline:)
     end
 
+    def require_code_change(args)
+      if args[:code_change].nil?
+        raise ArgumentError,
+          "--code-change is required: #{Replay::CODE_CHANGE_CHOICES}. \"manual\" takes the edits from --code-change-file PATH."
+      end
+      return args if (args[:code_change] == "manual") == !args[:code_change_file].nil?
+
+      raise ArgumentError,
+        "--code-change-file goes with --code-change manual, and --code-change manual needs --code-change-file PATH."
+    end
+
     def registry_dataset_ids(options)
       dataset_id = options[:dataset_id]
       dataset_ids = options[:dataset_ids]
@@ -416,7 +434,7 @@ module Bitfab
     def load_code_change(path)
       value = JSON.parse(File.read(path))
       unless value.is_a?(Hash) && value["description"].is_a?(String) && value["files"].is_a?(Array)
-        raise ArgumentError, "Invalid --code-change file '#{path}': expected { description, files }."
+        raise ArgumentError, "Invalid --code-change-file '#{path}': expected { description, files }."
       end
 
       value

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.68.0"
+  VERSION = "0.69.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.68.0
+  version: 0.69.0
 platform: ruby
 authors:
 - Harvest Team