bitfab 0.69.0 → 0.71.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c5044f5cc55988582b4a4428242ac2c0ea12fb87ba228054ad7c01a08e760ca
-  data.tar.gz: f410e0a0560c11fd3185c4f237bb30d37ac16ed5dcb3c0d4beb2d08d5b62f863
+  metadata.gz: a84477fef0e70e513ab93e7ef81a0ef9021d5f09adefe8021075d89fbb26a64d
+  data.tar.gz: 39795db6575ecc859004b3db5af4d35b13747234d8fafd43f444819c4e2425dc
 SHA512:
-  metadata.gz: 680f7e7b023a94951496fba7b6b2aef5bb61f4250d3a3cfa5d2db3dae7a91038a0c3f03474419eb65e9defa0fc0c3811d7ee4346a4d9b50c15f2fa29a3bda703
-  data.tar.gz: b6230d97bb985ad5748e7e45121f89fdc4cbf65861eaa7ac815bd028bd34d43774a36f4ab3941b54e830121c7c097e2ee98da013834d783a69147a7b3a4dc570
+  metadata.gz: 0327c9092bb7b6d9071546c6a54ae5f64e49083518c6e35c3049eb04455b32eed4fa976df0c35a7d59d9231d0107cff212eca5a8287f5d4d043d1e566b5e1a58
+  data.tar.gz: bab39d209b61f795eb681bafdf7e5e19b6707977864e6c7a5b72d5ee02af449a8c1f0a3b8c29a06229ef32f099326dfe3c6ba1890156cdf9a37308daab137bf9

data/lib/bitfab/client.rb

@@ -147,16 +147,22 @@ module Bitfab
     #   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.
+    #   origin/main, origin/master, main, master); "ref" the diff against where
+    #   HEAD split from the branch or commit in code_change_base; "skip" no code
+    #   change, such as for a baseline run; "manual" the files in
+    #   code_change_files. The four 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 code_change_base [String, nil] the branch or commit to diff
+    #   against when code_change is "ref", and only then, such as "dev",
+    #   "release/2.3", or a commit SHA. A branch that exists only on the remote
+    #   is read as origin/<name>. A name git cannot resolve raises ArgumentError.
     # @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
@@ -222,7 +228,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: 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,
+      name: nil, notes: nil, metadata: nil, code_change: nil, code_change_description: nil, code_change_files: nil, code_change_base: 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(
@@ -245,6 +251,7 @@ module Bitfab
         code_change:,
         code_change_description:,
         code_change_files:,
+        code_change_base:,
         experiment_group_id:,
         experiment_group_name:,
         dataset_id:,

data/lib/bitfab/cloudReplay.py

@@ -149,7 +149,10 @@ RENAMED_FLAGS = {
 SEED_FLAGS = ("--seed", "--cases", "--from-trace", "--run")
 PATH_FLAGS = ("--registry", "--params", "--code-change-file")
 CODE_CHANGE_FLAG = "--code-change"
-BRANCH_CODE_CHANGES = ("last-branch", "default-branch")
+CODE_CHANGE_BASE_FLAG = "--code-change-base"
+BRANCH_CODE_CHANGES = ("last-branch", "default-branch", "ref")
+GIT_CODE_CHANGES = ("working-tree", *BRANCH_CODE_CHANGES)
+DESCRIBED_REF = re.compile(r"[^\x00-\x1f\x7f]{1,200}")
 CHECKOUT_DEPTH = 2
 CODE_CHANGE_PATH_ENV = "BITFAB_CODE_CHANGE_PATH"
 CODE_CHANGE_MAX_FILES = 60
@@ -220,7 +223,9 @@ Options added by --cloud:
                          checkout of the repository, with GitHub access that can
                          read it and run Actions (a job token needs contents: read
                          and actions: write, passed as GH_TOKEN), and a workflow on
-                         BRANCH that declares a request input.
+                         BRANCH that declares a request input. With no snapshot
+                         there is nothing to diff against, so it takes
+                         --code-change skip or manual, as does a dispatched run.
 
 A workflow can also dispatch bitfab-replay.yml itself on any branch other than a
 bitfab-replay/ snapshot branch, passing the replay as JSON in the request input:
@@ -1029,8 +1034,30 @@ def default_branch_point(root):
     return {"sha": sha, "ref": default} if sha else None
 
 
+def chosen_base_point(root, chosen):
+    if not chosen or chosen.startswith("-"):
+        return None
+    for ref in (chosen, f"origin/{chosen}"):
+        if quiet_git(root, "rev-parse", "--verify", "-q", f"{ref}^{{commit}}"):
+            sha = quiet_git(root, "merge-base", "HEAD", ref)
+            return {"sha": sha, "ref": chosen} if sha else None
+    raise ValueError(
+        f"{CODE_CHANGE_BASE_FLAG} {chosen} names no branch or commit in this repository; pass a branch name or a commit SHA, and fetch it first if it only exists on the remote"
+    )
+
+
+def refuse_git_code_change(replay, where):
+    kind = flag_value(replay, CODE_CHANGE_FLAG)
+    if kind in GIT_CODE_CHANGES:
+        raise ValueError(
+            f"{where} as it is on GitHub, with no snapshot of a checkout, so --code-change {kind} has nothing to compare against there; pass --code-change skip, or --code-change manual with --code-change-file, or start it with bitfab-replay --cloud and no --cloud-ref, which resolves {kind} from your checkout before upload"
+        )
+
+
 def code_change_base(root, replay):
     kind = flag_value(replay, CODE_CHANGE_FLAG)
+    if kind == "ref":
+        return chosen_base_point(root, flag_value(replay, CODE_CHANGE_BASE_FLAG))
     if kind == "last-branch":
         return branch_point(root)
     if kind == "default-branch":
@@ -1839,6 +1866,7 @@ def submit_as_is(root, repo, workflow, parsed, path):
     branch = parsed["cloud"]["--cloud-ref"]
     request, _ = replay_request(root, parsed)
     check_arguments(parsed["replay"])
+    refuse_git_code_change(parsed["replay"], f"--cloud-ref replays {branch}")
     sha = branch_head(repo, branch)
     if "--cloud-preview" in parsed["switches"]:
         return {
@@ -2089,6 +2117,7 @@ def dispatched_request():
         raise ValueError("The request id does not match the execution_id input")
     args = request.get("args")
     validate_arguments(args)
+    refuse_git_code_change(args, f"A dispatched replay runs {branch}")
     if request.get("check") is True and "--dry-run" not in args:
         args = [*args, "--dry-run"]
     normalized = {
@@ -2227,7 +2256,7 @@ def branch_code_change(root, base, commit, request):
         isinstance(sha, str)
         and SHA.fullmatch(sha)
         and isinstance(ref, str)
-        and BRANCH_NAME.fullmatch(ref)
+        and DESCRIBED_REF.fullmatch(ref)
         and (
             sha == base
             or quiet_git(root, "rev-parse", "--verify", "-q", f"{commit}^2") == sha

data/lib/bitfab/http_client.rb

@@ -253,6 +253,9 @@ module Bitfab
     # Start a replay session by fetching historical traces.
     # Blocking call. Returns hash with experimentId, experimentUrl, and items array.
     #
+    # @param code_change_type [String, nil] the code change choice this replay
+    #   named, such as "default-branch" or "skip"; stored on the experiment so
+    #   the dashboard can say what the run was compared against
     # @param code_change_description [String, nil] optional rationale for the
     #   code change being tested in this replay
     # @param code_change_files [Array<Hash>, nil] optional list of edited files,
@@ -273,7 +276,7 @@ module Bitfab
     #   directly to this experiment, graded as the union with the dataset's
     #   runnable graders at completion; each must be an active/live grader in the
     #   same org and trace function or the server rejects the replay
-    def start_replay(trace_function_key, limit, trace_ids: nil, code_change_description: nil,
+    def start_replay(trace_function_key, limit, trace_ids: nil, code_change_type: nil, code_change_description: nil,
       code_change_files: nil, experiment_group_id: nil, experiment_group_name: nil, name: nil, notes: nil, metadata: nil, include_db_branch_lease: false, dataset_ids: nil,
       grader_ids: nil, db_branch_settings: nil, attempts: 1, only_with_assertions: false, skip_assertion_judging: false, include_original_metadata: false, experimental_selective_replay: nil, dry_run: false, invocation: nil)
       payload = {
@@ -286,6 +289,7 @@ module Bitfab
       payload["name"] = name unless name.nil?
       payload["notes"] = notes unless notes.nil?
       payload["metadata"] = metadata unless metadata.nil?
+      payload["codeChangeType"] = code_change_type unless code_change_type.nil?
       payload["codeChangeDescription"] = code_change_description unless code_change_description.nil?
       payload["codeChangeFiles"] = normalize_code_change_files(code_change_files) unless code_change_files.nil?
       payload["experimentGroupId"] = experiment_group_id unless experiment_group_id.nil?

data/lib/bitfab/replay.rb

@@ -143,11 +143,11 @@ module Bitfab
   # Replay historical traces through a traced method and create an experiment.
   module Replay
     # The values Client#replay accepts for +code_change:+.
-    CODE_CHANGE_TYPES = %w[working-tree last-branch default-branch skip manual].freeze
+    CODE_CHANGE_TYPES = %w[working-tree last-branch default-branch ref 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)'
+      'branch this one was cut from), "default-branch" (the diff against the default branch), "ref" (the diff ' \
+      'against a branch or commit you name), "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
@@ -237,16 +237,22 @@ module Bitfab
     #   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.
+    #   origin/main, origin/master, main, master); "ref" the diff against where
+    #   HEAD split from the branch or commit in code_change_base; "skip" no code
+    #   change, such as for a baseline run; "manual" the files in
+    #   code_change_files. The four 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 code_change_base [String, nil] the branch or commit to diff
+    #   against when code_change is "ref", and only then, such as "dev",
+    #   "release/2.3", or a commit SHA. A branch that exists only on the remote
+    #   is read as origin/<name>. A name git cannot resolve raises ArgumentError.
     # @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
@@ -313,11 +319,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: nil, code_change_description: nil, code_change_files: nil, 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, code_change_base: 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)
+      validate_code_change(code_change, code_change_description, code_change_files, code_change_base)
       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)
@@ -396,7 +402,7 @@ module Bitfab
 
       include_db_branch_lease = db_branch_enabled?(db_branch) && !dry_run
 
-      code_change_description, code_change_files = resolve_code_change(code_change, code_change_description, code_change_files, name)
+      code_change_description, code_change_files = resolve_code_change(code_change, code_change_description, code_change_files, name, code_change_base)
 
       resolved_db_branch_settings = db_branch_settings(db_branch)
       replay_data = http_client.start_replay(
@@ -406,6 +412,7 @@ module Bitfab
         name:,
         notes:,
         metadata:,
+        code_change_type: code_change,
         code_change_description:,
         code_change_files:,
         experiment_group_id:,
@@ -654,7 +661,7 @@ module Bitfab
       settings.empty? ? nil : settings
     end
 
-    def validate_code_change(code_change, description, files)
+    def validate_code_change(code_change, description, files, base = nil)
       if code_change.nil?
         raise ArgumentError, "replay needs a code_change naming the code this run tests: #{CODE_CHANGE_CHOICES}."
       end
@@ -668,17 +675,24 @@ module Bitfab
       if code_change != "manual" && !files.nil?
         raise ArgumentError, "code_change_files only applies with code_change \"manual\" (got \"#{code_change}\")."
       end
+      if code_change == "ref" && !(base.is_a?(String) && !base.strip.empty? && !base.strip.start_with?("-"))
+        raise ArgumentError,
+          'code_change "ref" needs code_change_base: the branch or commit to diff against, such as "dev" or a commit SHA.'
+      end
+      if code_change != "ref" && !base.nil?
+        raise ArgumentError, "code_change_base only applies with code_change \"ref\" (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)
+    def resolve_code_change(code_change, description, files, label = nil, base = 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)
+      captured = read_code_change_file || capture_code_change_from_git(Dir.pwd, code_change, label, base&.strip)
       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]
@@ -712,8 +726,21 @@ module Bitfab
       !git(root, ["rev-parse", "--verify", "#{ref}^{object}"]).nil?
     end
 
-    def cc_resolve_base(root, type)
+    def cc_resolve_chosen_base(root, chosen)
+      [chosen, "origin/#{chosen}"].each do |ref|
+        next unless cc_ref_exists?(root, "#{ref}^{commit}")
+
+        base = (git(root, ["merge-base", "HEAD", ref]) || "").strip
+        return base.empty? ? nil : [base, "vs #{chosen}"]
+      end
+      raise ArgumentError,
+        "code_change_base \"#{chosen}\" names no branch or commit in this repository. Pass a branch name, such as " \
+          "\"dev\", or a commit SHA; fetch it first if it only exists on the remote."
+    end
+
+    def cc_resolve_base(root, type, chosen = nil)
       case type
+      when "ref" then chosen ? cc_resolve_chosen_base(root, chosen) : nil
       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
@@ -808,12 +835,12 @@ module Bitfab
       0
     end
 
-    def capture_code_change_from_git(cwd, type, label = nil)
+    def capture_code_change_from_git(cwd, type, label = nil, chosen = nil)
       root = git(cwd, ["rev-parse", "--show-toplevel"])
       return nil if root.nil? || root.strip.empty?
 
       root = root.strip
-      resolved = cc_resolve_base(root, type)
+      resolved = cc_resolve_base(root, type, chosen)
       return nil if resolved.nil?
 
       entries = cc_list_changes(root, resolved[0])
@@ -848,6 +875,8 @@ module Bitfab
       head = ((label && !label.strip.empty?) ? label.strip : nil) || (subject.empty? ? nil : subject) || "Working-tree change"
       word = (files.length == 1) ? "file" : "files"
       ["#{head} (#{files.length} #{word} changed #{against})", files]
+    rescue ArgumentError
+      raise
     rescue
       nil
     end

data/lib/bitfab/replay_registry.rb

@@ -204,6 +204,7 @@ module Bitfab
       end
 
       options[:code_change] = args.fetch(:code_change)
+      options[:code_change_base] = args[:code_change_base] if args[:code_change_base]
       if args[:code_change_file]
         code_change = load_code_change(args[:code_change_file])
         options[:code_change_description] = code_change.fetch("description")
@@ -337,10 +338,11 @@ module Bitfab
         options.on("--max-concurrency N", Integer) do |value|
           args[:max_concurrency] = positive_integer("--max-concurrency", value)
         end
-        options.on("--code-change working-tree|last-branch|default-branch|skip|manual",
+        options.on("--code-change working-tree|last-branch|default-branch|ref|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|
+            "default branch, ref the diff against --code-change-base, 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}. " \
@@ -350,6 +352,8 @@ module Bitfab
         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("--code-change-base BRANCH|COMMIT",
+          "With --code-change ref: the branch or commit to diff against.") { |value| args[:code_change_base] = 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",
@@ -390,12 +394,17 @@ module Bitfab
     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."
+          "--code-change is required: #{Replay::CODE_CHANGE_CHOICES}. \"ref\" takes the branch or commit from " \
+            "--code-change-base, and \"manual\" takes the edits from --code-change-file PATH."
       end
-      return args if (args[:code_change] == "manual") == !args[:code_change_file].nil?
+      unless (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
+      return args if (args[:code_change] == "ref") == !args[:code_change_base].nil?
 
       raise ArgumentError,
-        "--code-change-file goes with --code-change manual, and --code-change manual needs --code-change-file PATH."
+        "--code-change-base goes with --code-change ref, and --code-change ref needs --code-change-base BRANCH|COMMIT."
     end
 
     def registry_dataset_ids(options)

data/lib/bitfab/version.rb

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

metadata

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