duel 0.1.0 → 0.1.1

data/docs/json.md

@@ -47,6 +47,7 @@ A run that found one regression, abridged to two benchmarks:
   "status": "failed",
   "exit": 1,
   "message": null,
+  "comment": "post",
   "settings": {
     "confidence": 0.99,
     "limit": 1.02,
@@ -189,7 +190,8 @@ A run with nothing to compare has the same keys, with nothing compared:
   "duel_version": "0.1.0",
   "status": "nothing_to_compare",
   "exit": 0,
-  "message": "duel: lib, ext unchanged since the baseline, so there's nothing to compare (--force to anyway)",
+  "message": "duel: lib, ext, duel, .duel.rb unchanged since the baseline, so there's nothing to compare (--force to anyway)",
+  "comment": "change",
   "settings": {"confidence": 0.99, "limit": 1.02, "filter": "", "jobs": 4, "processes": 3, "timeout": 60.0, "warm": null, "force": false},
   "seconds": null,
   "baseline": null,
@@ -217,6 +219,7 @@ jq -r '.benchmarks[] | select(.verdict == "regressed") | .name' tmp/duel.json
 | `status` | `"passed"`, `"failed"`, `"nothing_to_compare"`, or `"error"` (Duel couldn't compare). |
 | `exit` | The exit status of `duel`: `0` for passed or nothing to compare, `1` for failed, `2` for an error. |
 | `message` | What Duel said, for nothing to compare or an error, such as `"duel: no release tag (v*) before HEAD to compare against"`. Otherwise `null`. |
+| `comment` | Whether the workflow that `duel init` writes comments on a pull request with the report, as [`c.comment`](configuration.md#choose-when-to-comment-on-a-pull-request) (or `--comment`) decides for this run: `"post"` a new comment, `"change"`, which posts one only if the workflow commented on the pull request before and its last comment's status differs from this run's, or `"none"`. See [Comment on a pull request](ci.md#comment-on-a-pull-request). |
 | `settings` | The settings that the run used (see below). |
 | `seconds` | How long the comparison took. `null` without a comparison. |
 | `baseline`, `candidate` | The two versions (see below). `null` without a comparison. |
@@ -247,7 +250,7 @@ was slower across the board and confirmed (`"confirmed": true`).
 |---|---|
 | `ref` | The baseline's git ref: the one `--base` named, the release tag for `--base last-release`, or the main branch, such as `"origin/main"`, by default, where the baseline is the commit where `HEAD` left that branch. `null` for a baseline directory. |
 | `commit` | The full hash of the commit compared. `null` for a baseline directory, or for a candidate outside a git repository. |
-| `uncommitted_changes` | The candidate only: whether what `c.watch` names has changes that aren't committed. `null` outside a git repository. |
+| `uncommitted_changes` | The candidate only: whether what Duel watches (`c.watch`, the benchmarks, and the rest that a change must touch to be compared: see [Configure Duel](configuration.md)) has changes that aren't committed. `null` outside a git repository. |
 | `root` | The tree that was compared, as an absolute path. |
 | `ruby` | The version's Ruby, as its `RUBY_DESCRIPTION`. |
 

data/docs/troubleshooting.md

@@ -5,11 +5,12 @@ comparison doesn't go as you expect, and what to do about it.
 
 ## Duel says there's nothing to compare
 
-If nothing under `lib/` or `ext/` changed since the baseline, there's
-nothing to compare, and Duel passes. To compare anyway, use `--force`.
-With nothing changed, Duel compares your code with itself, which checks
-that your benchmarks run. To change what a change must touch to be
-compared, set `c.watch`. See [Configure Duel](configuration.md).
+If nothing under `lib/` or `ext/`, your benchmarks, or `.duel.rb`
+changed since the baseline, there's nothing to compare, and Duel passes.
+To compare anyway, use `--force`. With nothing changed, Duel compares
+your code with itself, which checks that your benchmarks run. To change
+what a change must touch to be compared, set `c.watch`. See
+[Choose what a change must touch to be compared](configuration.md#choose-what-a-change-must-touch-to-be-compared).
 
 Against `--base last-release`, Duel also reports that there's nothing to
 compare against until you tag your first release. Releases are tagged

data/lib/duel/baseline.rb

@@ -4,6 +4,7 @@ require "digest"
 require "fileutils"
 require "open3"
 require_relative "../duel"
+require_relative "rubies"
 
 module Duel
   # The version to compare against: a directory (Settings#base_dir), or a
@@ -39,17 +40,30 @@ module Duel
       end
     end
 
-    # Whether nothing Config#watch names changed since the baseline (only
-    # for a git baseline compared with the working tree).
+    # Whether nothing #watched changed since the baseline (only for a git
+    # baseline compared with the working tree).
     def unchanged?
       return false if @settings.base_dir || @settings.candidate_dir
 
       # (There's a ref: CLI#run checks first.)
       commit = ref #: String
-      _, status = Open3.capture2e("git", "-C", @config.root, "diff", "--quiet", commit, "--", *@config.watch)
+      _, status = Open3.capture2e("git", "-C", @config.root, "diff", "--quiet", commit, "--", *watched)
       status.success?
     end
 
+    # What a change must touch to be compared, from the root: the code
+    # (Config#watch), and what decides how it's measured. Each version
+    # runs the candidate's benchmarks and configuration, so a change to
+    # only those compares the code with itself, which checks them. They
+    # are the benchmarks' directory (the glob's, up to its first
+    # wildcard), the configuration's file, and with each version on its
+    # own Ruby, the version files at the root.
+    def watched
+      measured = [benchmarks, config_file]
+      measured.concat(version_files) if (@settings.ruby || @config.ruby) == :version_file
+      (@config.watch + measured).uniq
+    end
+
     # The baseline's tree, checked out and built if it's a commit.
     def root
       base_dir = @settings.base_dir
@@ -129,6 +143,20 @@ module Duel
 
     private
 
+    # The benchmarks' directory (see #watched), or for benchmarks at the
+    # root, their glob, as git matches one.
+    def benchmarks
+      glob = @config.benchmarks
+      dir = glob.split("/").take_while { |part| !part.match?(/[*?\[{]/) }.join("/")
+      dir.empty? ? ":(glob)#{glob}" : dir
+    end
+
+    # The configuration's file, from the root (which is its directory).
+    def config_file = File.basename(@settings.config_path || ".duel.rb")
+
+    # The version files at the root (see Rubies).
+    def version_files = Rubies::VERSION_FILES.select { |name| File.exist?(File.join(@config.root, name)) }
+
     # Where HEAD left the main branch: their merge base, which there isn't
     # when their histories are unrelated, or in a shallow clone (CI's,
     # fetched without the history), where git fails saying nothing.

data/lib/duel/cli.rb

@@ -16,9 +16,11 @@ module Duel
   # rake task or a CI expression can't pass as an option can be set in
   # the environment (DUEL_BASE, DUEL_FILTER, DUEL_FORCE), and options win.
   # On GitHub Actions (GITHUB_STEP_SUMMARY), it adds its report to the
-  # job's summary, in Markdown (see Summary). --markdown writes that to a
-  # file, and --json the report as JSON (see JSONReport), whatever the
-  # run's outcome, but not for a command line that isn't valid.
+  # job's summary, in Markdown (see Summary), and tells the step's
+  # outputs (GITHUB_OUTPUT) what to do about the comment on a pull
+  # request (see .comment). --markdown writes the Markdown to a file, and
+  # --json the report as JSON (see JSONReport), whatever the run's
+  # outcome, but not for a command line that isn't valid.
   # @api private
   class CLI
     USAGE = "Usage: duel [options]\n       duel init [options]\n\n" \
@@ -27,6 +29,18 @@ module Duel
     # Where GitHub Actions has a step add to its job's summary.
     STEP_SUMMARY = "GITHUB_STEP_SUMMARY"
 
+    # Where GitHub Actions has a step set its outputs.
+    STEP_OUTPUT = "GITHUB_OUTPUT"
+
+    # The statuses (as the JSON report has them) that the workflow
+    # comments on, by when it does (Config#comment, but :never, which
+    # comments on none).
+    COMMENTED = {always: %w[passed failed nothing_to_compare error], results: %w[passed failed error], failures: %w[failed error]}.freeze #: Hash[Config::comment, Array[String]]
+
+    # A run's status (as the JSON report has it) as the comment's marker
+    # has it: passed, failed (or couldn't compare), or neutral.
+    MARKED = {"passed" => "passed", "failed" => "failed", "error" => "failed", "nothing_to_compare" => "neutral"}.freeze
+
     # The variables that set options, to their values, and the one that
     # sets a flag by being set at all.
     ENV_OPTIONS = {"DUEL_BASE" => "--base", "DUEL_FILTER" => "--filter"}.freeze
@@ -45,11 +59,11 @@ module Duel
       return Init.new(@argv.drop(1), out: @out, err: @err).run if @argv.first == "init"
 
       settings = @settings = catch(:version) { parse } or return 0
-      config = settings.config_path ? Duel.load_config(settings.config_path) : Config.new
+      config = @config = settings.config_path ? Duel.load_config(settings.config_path) : Config.new
       Lock.hold(File.join(config.root, "tmp", "duel")) { compare(config, settings) }
     rescue Error => e
       @err.puts "duel: #{e}"
-      unfinished("couldn't compare", "error", "duel: #{e}", 2)
+      unfinished(Summary::FAILED_MARK, "couldn't compare", "error", e.to_s, 2)
     rescue OptionParser::ParseError => e
       @err.puts "duel: #{e}"
       2
@@ -63,6 +77,25 @@ module Duel
       raise OptionParser::InvalidArgument, "#{source} (#{e})"
     end
 
+    # Whether the workflow comments on a pull request, when it comments as
+    # +mode+ says (Config#comment) and the run's +status+ is the JSON
+    # report's: "post" a new comment, "change", posting one only if it
+    # commented on the pull request before and its last comment's status
+    # (see MARKED) isn't this run's, or "none". It never edits a comment,
+    # so the pull request keeps every one.
+    def self.comment(mode, status)
+      return "none" if mode == :never
+
+      COMMENTED.fetch(mode).include?(status) ? "post" : "change"
+    end
+
+    # The mode --comment names (see Config#comment), or an invalid
+    # argument.
+    def self.comment_mode(name)
+      Config::COMMENTS.find { |mode| mode.to_s == name } or
+        raise OptionParser::InvalidArgument, "#{name} (give #{Config::COMMENTS.join(", ")})"
+    end
+
     # The settings, from the environment and then the options.
     def parse
       settings = Settings.defaults
@@ -83,9 +116,12 @@ module Duel
         @out.puts "duel: removed tmp/duel and its baseline's worktree"
         return 0
       end
-      return nothing("no release tag (#{config.release_tags}) before HEAD to compare against") if settings.base_dir.nil? && baseline.ref.nil?
+      if settings.base_dir.nil? && baseline.ref.nil?
+        return nothing("no release to compare against", "no release tag (#{config.release_tags}) before HEAD to compare against")
+      end
       if !settings.force && baseline.unchanged?
-        return nothing("#{config.watch.join(", ")} unchanged since the baseline, so there's nothing to compare (--force to anyway)")
+        return nothing("nothing to compare",
+          "#{baseline.watched.join(", ")} unchanged since the baseline, so there's nothing to compare (--force to anyway)")
       end
 
       candidate = settings.candidate_dir || config.root
@@ -96,42 +132,62 @@ module Duel
       results = runner.run
       status = runner.passed?(results) ? 0 : 1
       publish(
+        status.zero? ? "passed" : "failed",
         -> {
           Summary.new(runner, results, settings: settings, baseline: described_baseline(config, settings, baseline),
             candidate: described_candidate(config, settings)).markdown
         },
-        -> {
-          JSONReport.new(runner, results, settings: settings, exit: status, baseline: baseline_json(config, settings, baseline, base_root),
-            candidate: candidate_json(config, settings)).to_h
+        ->(comment) {
+          JSONReport.new(runner, results, settings: settings, exit: status, comment: comment,
+            baseline: baseline_json(config, settings, baseline, base_root), candidate: candidate_json(config, settings)).to_h
         }
       )
       status
     end
 
-    # Says there's nothing to compare, and why, and passes.
-    def nothing(why)
+    # Says there's nothing to compare (+title+, in Markdown), and +why+,
+    # and passes.
+    def nothing(title, why)
       @out.puts "duel: #{why}"
-      unfinished("nothing to compare", "nothing_to_compare", "duel: #{why}", 0)
+      unfinished(Summary::NEUTRAL_MARK, title, "nothing_to_compare", why, 0)
     end
 
-    # Reports a run that didn't compare (+title+ says why in Markdown,
-    # and +status+ in JSON) with +message+, and returns +exit+.
-    def unfinished(title, status, message, exit)
-      # (Parsed, so set, where there's JSON to write: see #publish.)
+    # Reports a run that didn't compare (+mark+ and +title+ say so in
+    # Markdown, and +status+ in JSON), and +why+, and returns +exit+.
+    def unfinished(mark, title, status, why, exit)
+      # (Parsed, so set: see #run.)
       settings = @settings #: Settings
-      publish(-> { Summary.note(title, message) }, -> { JSONReport.note(status, exit, message, settings) })
+      publish(status, -> { Summary.note(mark, title, why) }, ->(comment) { JSONReport.note(status, exit, "duel: #{why}", settings, comment) })
       exit
     end
 
-    # Writes the reports where they're asked for: the JSON +json+ makes
-    # to the file --json names, and the Markdown +markdown+ makes to the
-    # file --markdown names, and added to the job's summary on GitHub
-    # Actions (STEP_SUMMARY). Each is only made if it's written.
-    def publish(markdown, json)
+    # What the workflow does about its comment on a pull request (see
+    # .comment), for a run whose +status+ is the JSON report's: as
+    # --comment says, or else the configuration, or the default where the
+    # configuration didn't load.
+    def commenting(status)
+      # (Parsed, so set: see #run.)
+      settings = @settings #: Settings
+      CLI.comment(settings.comment || (@config || Config.new).comment, status)
+    end
+
+    # Writes the reports of a run whose +status+ is the JSON report's
+    # where they're asked for: the JSON +json+ makes, given what the
+    # workflow does about its comment (see #commenting), to the file
+    # --json names, and the Markdown +markdown+ makes to the file
+    # --markdown names, and added to the job's summary on GitHub Actions
+    # (STEP_SUMMARY). Each is only made if it's written. On GitHub
+    # Actions, it also sets the step's outputs (STEP_OUTPUT) for the job
+    # that comments on a pull request: +comment+, and +status+ as the
+    # comment's marker has it (MARKED).
+    def publish(status, markdown, json)
+      comment = commenting(status)
+      set = variables
+      File.write(set.fetch(STEP_OUTPUT), "comment=#{comment}\nstatus=#{MARKED.fetch(status)}\n", mode: "a") if set.key?(STEP_OUTPUT)
       path = @json
-      write(path, "#{JSON.pretty_generate(json.call)}\n") if path
+      write(path, "#{JSON.pretty_generate(json.call(comment))}\n") if path
       path = @markdown
-      summary = (variables.fetch(STEP_SUMMARY) if variables.key?(STEP_SUMMARY))
+      summary = (set.fetch(STEP_SUMMARY) if set.key?(STEP_SUMMARY))
       return unless path || summary
 
       text = markdown.call
@@ -145,31 +201,42 @@ module Duel
       File.write(path, text)
     end
 
-    # The baseline, in Markdown: its directory, or its commit, and what
-    # named it.
+    # The baseline, in Markdown: its directory, or its commit, bare (so
+    # GitHub links it) and followed by a space, never punctuation, and
+    # what chose it: the main branch, the push (on GitHub Actions, the
+    # commit before it, from DUEL_BASE), the last release, or --base.
     def described_baseline(config, settings, baseline)
       dir = settings.base_dir
       return Summary.code(dir) if dir
 
       # (There's one: #compare checked.)
       ref = baseline.ref #: String
-      commit = Summary.code(git(config.root, "rev-parse", "--short", "#{ref}^{commit}").first.chomp)
-      case settings.base
-      when nil then "#{commit}, where HEAD left #{Summary.code(baseline.main_branch)}"
-      when Baseline::LAST_RELEASE then "#{Summary.code(ref)} (#{commit}), the last release"
-      else ref.match?(/\A\h+\z/) ? commit : "#{Summary.code(ref)} (#{commit})"
+      commit = git(config.root, "rev-parse", "--short", "#{ref}^{commit}").first.chomp
+      set = variables
+      chosen = case settings.base
+      when nil then "where HEAD left #{Summary.code(baseline.main_branch)}"
+      when Baseline::LAST_RELEASE then "the last release, #{Summary.code(ref)}"
+      else
+        pushed = set.key?("GITHUB_EVENT_NAME") && set.fetch("GITHUB_EVENT_NAME") == "push" && set.key?("DUEL_BASE") &&
+          set.fetch("DUEL_BASE") == ref
+        if !ref.match?(/\A\h+\z/) then Summary.code(ref)
+        elsif pushed then "the commit before the push"
+        else "from --base"
+        end
       end
+      "#{commit} (#{chosen})"
     end
 
-    # The candidate, in Markdown: its directory, or its commit, and
-    # whether what Config#watch names has changes not committed.
+    # The candidate, in Markdown: its directory, or its commit, bare (see
+    # #described_baseline), and whether what's watched (Baseline#watched)
+    # has changes not committed.
     def described_candidate(config, settings)
       dir = settings.candidate_dir || config.root
       head, found = git(dir, "rev-parse", "--short", "HEAD")
       return Summary.code(dir) unless found.success?
 
-      _, clean = git(dir, "diff", "--quiet", "HEAD", "--", *config.watch)
-      "#{Summary.code(head.chomp)}#{", with changes not committed" unless clean.success?}"
+      _, clean = git(dir, "diff", "--quiet", "HEAD", "--", *Baseline.new(config, settings).watched)
+      "#{head.chomp}#{" (with changes not committed)" unless clean.success?}"
     end
 
     # The baseline, for JSON: the ref that named it (the main branch,
@@ -189,15 +256,15 @@ module Duel
       described.merge("ref" => named, "commit" => git(config.root, "rev-parse", "#{ref}^{commit}").first.chomp)
     end
 
-    # The candidate, for JSON: its commit, and whether what Config#watch
-    # names has changes not committed (each nil outside a repository), and
-    # its tree.
+    # The candidate, for JSON: its commit, and whether what's watched
+    # (Baseline#watched) has changes not committed (each nil outside a
+    # repository), and its tree.
     def candidate_json(config, settings)
       dir = File.expand_path(settings.candidate_dir || config.root)
       head, found = git(dir, "rev-parse", "HEAD")
       return {"commit" => nil, "uncommitted_changes" => nil, "root" => dir} unless found.success?
 
-      _, clean = git(dir, "diff", "--quiet", "HEAD", "--", *config.watch)
+      _, clean = git(dir, "diff", "--quiet", "HEAD", "--", *Baseline.new(config, settings).watched)
       {"commit" => head.chomp, "uncommitted_changes" => !clean.success?, "root" => dir}
     end
 
@@ -253,6 +320,8 @@ module Duel
         o.on("--markdown PATH", "Also write the report to PATH in Markdown, for a pull request comment (on GitHub",
           "Actions, it's added to the job's summary too)") { |v| @markdown = v }
         o.on("--json PATH", "Also write the report to PATH as JSON, for a program to read") { |v| @json = v }
+        o.on("--comment MODE", "When the workflow comments on a pull request: always, results (passed or failed),",
+          "failures, or never (default: c.comment, or failures)") { |v| settings.comment = CLI.comment_mode(v) }
         o.on("--clean", "Remove tmp/duel, and the baseline's git worktree, and stop") { @clean = true }
         o.on("-v", "--version", "Print the version") do
           @out.puts "duel #{VERSION}"

data/lib/duel/config.rb

@@ -11,7 +11,8 @@ module Duel
   # - a project with ext/ is built with `bundle exec rake compile` when
   #   a baseline is checked out
   # - a change is compared with where it left the branch origin/HEAD
-  #   points to (origin/main, say), when lib/ or ext/ changed
+  #   points to (origin/main, say), when lib/ or ext/ changed, or what
+  #   decides how they're measured (see #watch)
   # - releases are tagged v*
   #
   # .duel.rb, at the root, changes what doesn't fit:
@@ -33,8 +34,11 @@ module Duel
     # A glob, from the root, of the files defining benchmarks.
     attr_accessor :benchmarks
 
-    # Paths, from the root, whose changes a comparison is about: when none
-    # of them changed since the baseline, there's nothing to compare.
+    # Paths, from the root, of the code whose changes a comparison is
+    # about: when none of them changed since the baseline, nor what
+    # decides how it's measured (the benchmarks' directory, the
+    # configuration's file, and with each version on its own Ruby, the
+    # version files at the root), there's nothing to compare.
     attr_accessor :watch
 
     # The library to require from each version, as `require` takes it,
@@ -62,6 +66,35 @@ module Duel
     #   c.ruby = ->(root) { File.join(Dir.home, ".rubies", File.read(File.join(root, ".ruby-version")).strip, "bin", "ruby") }
     attr_accessor :ruby
 
+    # When the workflow that `duel init` writes comments on a pull request
+    # with the report (`duel --comment` overrides it):
+    #
+    # - :always, on every run
+    # - :results, when a run passed or failed, but not with nothing
+    #   compared
+    # - :failures (the default), only when a run failed or couldn't
+    #   compare
+    # - :never
+    #
+    # It never edits a comment: each is a new one, so the pull request
+    # keeps them all. Once it has commented, a run that it wouldn't
+    # comment on still does, but :never's, when its status differs from
+    # the last comment's, so the last comment is never stale: after a
+    # failure, the first run that passes says so. Duel tells the workflow
+    # which to do (see CLI.comment).
+    #
+    #   c.comment = :results
+    attr_reader :comment
+
+    # The values #comment takes.
+    COMMENTS = %i[always results failures never].freeze #: Array[comment]
+
+    def comment=(mode)
+      raise Error, "c.comment = #{mode.inspect}: give #{COMMENTS.map(&:inspect).join(", ")}" unless COMMENTS.include?(mode)
+
+      @comment = mode
+    end
+
     # The metrics #metric added, in order (classes: a Duel::Metric
     # subclass, or running totals' Snapshot), for a plugin's tests to
     # look at (their .measures and .settings).
@@ -81,6 +114,7 @@ module Duel
       @library = :conventional
       @build = :conventional
       @release_tags = "v*"
+      @comment = :failures
       @prepares = SCOPES.to_h { |scope| [scope, []] }
       @metrics = []
       @in_workers = []

data/lib/duel/init.rb

@@ -156,14 +156,22 @@ module Duel
       steps << "Set c.library in .duel.rb to what each version's workers require." unless required
       steps << "Replace the example in #{benchmark_file} with benchmarks of your own code."
       steps << "Run `bundle exec duel --force`. It compares the code with itself, and passes when the benchmarks are sound."
-      steps << "Commit and push. On a pull request, the workflow compares the code with the main branch, and comments with the report."
+      steps << "Commit and push. On a pull request, the workflow compares the code with the main branch, and comments with the " \
+        "report when a benchmark fails (c.comment in .duel.rb says when)."
       "\nNext:\n#{steps.each_with_index.map { |step, i| "  #{i + 1}. #{step}\n" }.join}"
     end
 
     def render(name) = ERB.new(File.read(File.join(TEMPLATES, "#{name}.erb")), trim_mode: "-").result(binding)
 
+    # The project's configuration, as the conventions have it.
+    def config = Config.new(@root)
+
     # The library the gemspec names (see Config#library), or nil.
-    def library = Config.new(@root).library
+    def library = config.library
+
+    # The glob release tags match (Config#release_tags), for the workflow
+    # to find the last release as Duel does.
+    def release_tags = config.release_tags
 
     # The library, without a gemspec: lib/'s only Ruby file, or nil.
     def guess

data/lib/duel/json_report.rb

@@ -16,17 +16,18 @@ module Duel
     SCHEMA = 1
 
     # A run that didn't compare: +status+ ("nothing_to_compare", or
-    # "error"), its +exit+ status, and +message+, what it said.
-    def self.note(status, exit, message, settings)
+    # "error"), its +exit+ status, +message+, what it said, and what the
+    # workflow does about its +comment+ (see CLI.comment).
+    def self.note(status, exit, message, settings, comment)
       none = [] #: Array[value]
       nothing = {} #: report
-      head(status, exit, message, settings).merge("seconds" => nil, "baseline" => nil, "candidate" => nil, "plugins" => none,
+      head(status, exit, message, settings, comment).merge("seconds" => nil, "baseline" => nil, "candidate" => nil, "plugins" => none,
         "benchmarks" => none, "across" => nothing, "errors" => none)
     end
 
     # What every report starts with.
-    def self.head(status, exit, message, settings)
-      {"schema" => SCHEMA, "duel_version" => VERSION, "status" => status, "exit" => exit, "message" => message,
+    def self.head(status, exit, message, settings, comment)
+      {"schema" => SCHEMA, "duel_version" => VERSION, "status" => status, "exit" => exit, "message" => message, "comment" => comment,
        "settings" => {"confidence" => settings.confidence, "limit" => settings.limit, "filter" => settings.filter.source,
                       "jobs" => settings.jobs, "processes" => settings.processes, "timeout" => settings.timeout,
                       "warm" => settings.warm, "force" => settings.force}}
@@ -34,19 +35,20 @@ module Duel
 
     # +runner+ ran, and made +results+, comparing +baseline+ with
     # +candidate+ (each {"ref", "commit", "root"} or {"commit",
-    # "uncommitted_changes", "root"}) as +settings+ say, and exits with
-    # +exit+.
-    def initialize(runner, results, settings:, exit:, baseline:, candidate:)
+    # "uncommitted_changes", "root"}) as +settings+ say, exits with
+    # +exit+, and has the workflow do +comment+ (see CLI.comment).
+    def initialize(runner, results, settings:, exit:, comment:, baseline:, candidate:)
       @runner = runner
       @results = results
       @settings = settings
       @exit = exit
+      @comment = comment
       @versions = {"baseline" => baseline, "candidate" => candidate}
     end
 
     def to_h
       rubies = @runner.rubies
-      JSONReport.head(@exit.zero? ? "passed" : "failed", @exit, nil, @settings).merge(
+      JSONReport.head(@exit.zero? ? "passed" : "failed", @exit, nil, @settings, @comment).merge(
         "seconds" => @runner.seconds,
         **@versions.to_h { |side, version| [side, version.merge("ruby" => rubies.fetch(side))] },
         "plugins" => @runner.plugins.map(&:to_s),

data/lib/duel/runner.rb

@@ -30,7 +30,7 @@ module Duel
   # How a run is set up (see Duel::CLI for where each comes from).
   # @api private
   Settings = Struct.new(:base, :base_dir, :candidate_dir, :filter, :jobs, :processes, :limit, :confidence, :warm, :force,
-    :config_path, :timeout, :ruby) do
+    :config_path, :timeout, :ruby, :comment) do
     # @type self: singleton(Settings)
     def self.defaults = new(filter: //, jobs: 1, processes: 3, limit: 1.02, confidence: 0.99, warm: nil, force: false,
       timeout: 60.0)