duel 0.1.0 → 0.1.1

data/lib/duel/summary.rb

@@ -4,11 +4,11 @@ require_relative "runner"
 
 module Duel
   # A run's report in Markdown, for a pull request: GitHub Actions' job
-  # summary, or a comment (see CLI). It has the verdict, the two versions
-  # (and their Rubies, where they differ), a table of the benchmarks that
-  # changed, regressions first, each regression explained as the terminal
-  # report explains it, those unsettled and those that failed. The rest
-  # are collapsed, so it stays short with hundreds of benchmarks.
+  # summary, or a comment (see CLI). In view, only what the author needs:
+  # the verdict, the two commits, and what failed, in a table. The rest is
+  # collapsed: what made each regression, every benchmark's timings, the
+  # verdicts across the board, each version's Ruby where they differ, and
+  # how Duel decides. So it stays short with hundreds of benchmarks.
   # @api private
   class Summary
     # The most characters it has (a GitHub comment has at most 65,536):
@@ -26,6 +26,19 @@ module Duel
     # The verdicts that fail a run, which stand out.
     FAILED = %w[regressed error].freeze
 
+    # What the heading starts with: a run that passed, one that failed (or
+    # couldn't compare), and one with nothing compared.
+    PASSED_MARK = "🟢"
+    FAILED_MARK = "🔻"
+    NEUTRAL_MARK = "⬜"
+
+    # What an unsettled timing means.
+    UNSETTLED = "An unsettled timing was too close to the limit to settle. It doesn't fail the run, but one that's unsettled " \
+      "in run after run is noisy."
+
+    # How Duel decides that a timing is slower, in its docs.
+    DECIDES = "https://github.com/sferik/duel-ruby/blob/main/docs/how-it-works.md#how-duel-tells-a-regression-from-noise"
+
     # +text+ as code, in Markdown: in a span of more backticks than any it
     # has (and spaced from one at either end).
     def self.code(text)
@@ -34,8 +47,17 @@ module Duel
       "#{ticks}#{padded}#{ticks}"
     end
 
-    # A run that didn't compare (+title+ says why), with what it said.
-    def self.note(title, message) = "### Duel: #{title}\n\n#{block(message)}\n"
+    # +text+ as it is, in Markdown: what Markdown, or the HTML in it, would
+    # take for something else, escaped.
+    def self.escape(text) = text.gsub(/[\\`*_\[\]<>|~&#]/) { |char| "\\#{char}" }
+
+    # A run that didn't compare: a heading of +mark+ and +title+, and the
+    # first line of +reason+, with all of it collapsed if it has more.
+    def self.note(mark, title, reason)
+      first, _, rest = reason.partition("\n")
+      more = "\n\n<details>\n<summary>The whole message</summary>\n\n#{block(reason)}\n\n</details>" unless rest.empty?
+      "### #{mark} Duel: #{title}\n\n#{escape(first)}#{more}\n"
+    end
 
     # +text+ in a fenced block of its own: fenced with more backticks than
     # any run of them it has, three at least.
@@ -67,13 +89,16 @@ module Duel
     end
 
     # +runner+ ran, and made +results+, comparing +baseline+ with
-    # +candidate+ (each a description, in Markdown) as +settings+ say.
+    # +candidate+ (each a description, in Markdown, whose commit stands
+    # bare, so GitHub links it) as +settings+ say.
     def initialize(runner, results, settings:, baseline:, candidate:)
       @runner = runner
       @results = results
       @settings = settings
-      @versions = {"baseline" => baseline, "candidate" => candidate}
+      @baseline = baseline
+      @candidate = candidate
       @regressed = results.select { |r| Summary.verdict(r) == "regressed" }
+      @failed = @regressed + results.select(&:error)
     end
 
     # The Markdown: every regression explained, or as many as LIMIT has
@@ -89,38 +114,89 @@ module Duel
 
     # The Markdown, with the first +explained+ regressions explained.
     def render(explained)
-      same, changed = sorted.partition { |r| Summary.verdict(r) == "same" }
-      [heading, versions, overview, table(changed), regressions(explained), across, unsettled, errors, unchanged(same)]
-        .compact.join("\n\n") + "\n"
+      [heading, compared, failures, across(confirmed: true), details(explained)].compact.join("\n\n") + "\n"
     end
 
+    # The verdict: what failed (benchmarks, or a metric across the board),
+    # or that every benchmark compared passed, and those skipped.
     def heading
-      errors = @results.count(&:error)
-      failed = [(Runner.count(@regressed.size, "regression") unless @regressed.empty?),
-        ("slower across the board" unless @runner.regressed_across.empty?),
-        (Runner.count(errors, "error") unless errors.zero?)].compact
-      return "### Duel failed: #{failed.join(", ")}" unless failed.empty?
+      skipped = @results.count(&:skipped)
+      compared = @results.size > skipped
+      slower = @runner.regressed_across
+      said = [("#{Runner.count(@failed.size, "benchmark")} failed" unless @failed.empty?),
+        ("slower across the board in #{slower.join(", ")}" unless slower.empty?)].compact
+      mark = if said.any? then FAILED_MARK
+      elsif compared then PASSED_MARK
+      else NEUTRAL_MARK
+      end
+      said << (compared ? "100% of benchmarks passed" : "no benchmarks compared") if said.empty?
+      said << "#{skipped} skipped" if skipped.positive?
+      "### #{mark} Duel: #{said.join(", ")}"
+    end
 
-      "### Duel passed: none of #{Runner.count(@results.size, "benchmark")} slower"
+    # The two versions, and why any benchmark was skipped.
+    def compared
+      skipped = @results.count(&:skipped)
+      why = " The baseline can't run the skipped #{(skipped == 1) ? "benchmark" : "benchmarks"}." if skipped.positive?
+      "Compared #{@candidate} with #{@baseline}.#{why}"
     end
 
-    # Each version, on its Ruby where theirs differ, and the plugins
-    # used.
-    def versions
-      rubies = @runner.rubies
-      plugins = @runner.plugins
-      lines = @versions.map do |side, described|
-        ruby = " on #{Summary.code(rubies.fetch(side))}" if rubies.values.uniq.size > 1
-        "- **#{side.capitalize}:** #{described}#{ruby}"
+    # The benchmarks that failed: what got worse and by how much, or the
+    # error, and where the most extra CPU went, if a profile says.
+    def failures
+      return if @failed.empty?
+
+      header = ["Benchmark", "Failure"]
+      header << "Most extra CPU in" unless @failed.all? { |r| top(r).empty? }
+      rows = @failed.map { |r| row([Summary.code(cell(r.name)), failure(r), top(r)].first(header.size)) }
+      ([row(header), "|#{"---|" * header.size}"] + rows).join("\n")
+    end
+
+    # What got worse, or the error's first line.
+    def failure(result)
+      error = result.error
+      return "error: #{Summary.code(cell(error.partition("\n").first))}" if error
+
+      worse = result.regressed.map do |metric|
+        timed = result.timed[metric]
+        counted = result.counted[metric]
+        if timed then format("%s %+.1f%%", metric, (timed.fetch("median") - 1) * 100)
+        elsif counted
+          n = counted.fetch("n")
+          format("%s %.4g → %.4g", metric, counted.fetch("baseline").fdiv(n), counted.fetch("candidate").fdiv(n))
+        else
+          # (Peak memory, which grew too much.)
+          memory = result.memory #: Hash[String, Integer]
+          "#{metric} #{mb(memory.fetch("baseline"))} → #{mb(memory.fetch("candidate"))}"
+        end
       end
-      lines << "- **Plugins:** #{plugins.map { |plugin| Summary.code(plugin.to_s) }.join(", ")}" unless plugins.empty?
-      lines.join("\n")
+      worse.join(result.mixed? ? " or " : ", ")
+    end
+
+    # The frame whose own share of the CPU grew the most, and by how much,
+    # if there's a profile with one (or "").
+    def top(result)
+      profile = result.profile
+      return "" unless profile && !profile.key?("unavailable")
+
+      # (A Profile's: Steep doesn't narrow on key?.)
+      grew = profile.fetch("grew") #: Array[Profile::growth]
+      most = grew.first
+      return "" unless most
+
+      frame, own, = most
+      format("%s %+.1f%%", Summary.code(cell(frame)), own * 100)
     end
 
-    def overview
-      format("%s in %.0fs. A timing is slower when a %s%% confidence interval for its ratio, the candidate's to the " \
-        "baseline's, is above %s.", Runner.count(@results.size, "benchmark"), @runner.seconds,
-        (@settings.confidence * 100).round(1), @settings.limit)
+    # The rest, collapsed: each regression explained, the errors, every
+    # benchmark, the verdicts across the board, the Rubies, and how Duel
+    # decides.
+    def details(explained)
+      unsettled = @results.count { |r| Summary.verdict(r) == "unsettled" }
+      title = format("Details: %s in %.0fs%s", Runner.count(@results.size, "benchmark"), @runner.seconds,
+        (", #{unsettled} unsettled" if unsettled.positive?))
+      body = [*regressions(explained), *errors, table, (UNSETTLED if unsettled.positive?), across(confirmed: false), rubies, decides]
+      "<details>\n<summary>#{title}</summary>\n\n#{body.compact.join("\n\n")}\n\n</details>"
     end
 
     # The results, in the order of their VERDICTS, and the run's order in
@@ -130,36 +206,30 @@ module Duel
       VERDICTS.flat_map { |shown| grouped.fetch(shown, []) }
     end
 
-    def table(changed)
-      return if changed.empty?
+    # Every benchmark, with its timings, and its counts where any changed.
+    def table
+      return if @results.empty?
 
-      rows = changed.map do |r|
+      rows = sorted.map do |r|
         shown = Summary.verdict(r)
-        row(Summary.code(name(r)), FAILED.include?(shown) ? "**#{shown}**" : shown, timings(r), counts(r))
+        [Summary.code(cell(r.name)), FAILED.include?(shown) ? "**#{shown}**" : shown, timings(r), counts(r)]
       end
-      ([row("Benchmark", "Verdict", "Timings (ratio [interval])", "Counts an iteration"), "|---|---|---|---|"] + rows).join("\n")
-    end
-
-    # Those that didn't change, collapsed.
-    def unchanged(same)
-      return if same.empty?
-
-      rows = same.map { |r| row(Summary.code(name(r)), timings(r)) }
-      "<details>\n<summary>#{Runner.count(same.size, "benchmark")} unchanged</summary>\n\n" \
-        "#{[row("Benchmark", "Timings (ratio [interval])"), "|---|---|", *rows].join("\n")}\n\n</details>"
+      header = ["Benchmark", "Verdict", "Timings (ratio [interval])", "Counts an iteration"]
+      columns = (rows.any? { |cells| !cells.last.empty? }) ? 4 : 3
+      ([row(header.first(columns)), "|#{"---|" * columns}"] + rows.map { |cells| row(cells.first(columns)) }).join("\n")
     end
 
     # A table's row of +cells+.
-    def row(*cells) = "| #{cells.join(" | ")} |"
+    def row(cells) = "| #{cells.join(" | ")} |"
 
-    # A benchmark's name, for a table's cell.
-    def name(result) = result.name.tr("\n", " ").gsub("|", "\\|")
+    # +text+ for a table's cell, on one line.
+    def cell(text) = text.tr("\n", " ").gsub("|", "\\|")
 
     # Each timed measure's ratio and its interval, with its verdict where
     # it isn't the same (or why it was skipped).
     def timings(result)
       skipped = result.skipped
-      return skipped.gsub("|", "\\|") if skipped
+      return cell(skipped) if skipped
 
       result.timed.map do |metric, t|
         low, high = t.fetch("interval")
@@ -186,8 +256,6 @@ module Duel
     # The first +explained+ regressions, explained as the terminal report
     # explains them (and the rest named).
     def regressions(explained)
-      return if @regressed.empty?
-
       shown = @regressed.first(explained).map do |r|
         what = r.mixed? ? "slower in every measurement, by one of #{r.regressed.join(", ")}" : "worse #{r.regressed.join(", ")} in every measurement"
         lines = @runner.explained(r)
@@ -196,42 +264,46 @@ module Duel
       end
       rest = @regressed.size - shown.size
       shown << "#{Runner.count(rest, shown.empty? ? "regression" : "more regression")} explained in the job's log." if rest.positive?
-      "#### Regressions\n\n#{shown.join("\n\n")}"
+      shown
     end
 
     # The verdicts across the board, of the metrics with enough
-    # benchmarks to tell.
-    def across
+    # benchmarks to tell: those slower in both measurements, which fail
+    # the run (+confirmed+), or the rest.
+    def across(confirmed:)
       lines = @runner.across.filter_map do |metric, v|
         low, high = v.fetch("interval")
-        next unless low
+        next unless low && v.fetch("confirmed", false) == confirmed
 
-        confirmed = " in both measurements" if v["confirmed"]
-        format("- %s %.3f [%.3f, %.3f] %s%s (limit %.4f, %s)", metric, v.fetch("median"), low, high, v.fetch("verdict"), confirmed,
-          v.fetch("limit"), Runner.count(v.fetch("benchmarks"), "benchmark"))
+        format("- %s %.3f [%.3f, %.3f] %s%s (limit %.4f, %s)", metric, v.fetch("median"), low, high, v.fetch("verdict"),
+          (" in both measurements" if confirmed), v.fetch("limit"), Runner.count(v.fetch("benchmarks"), "benchmark"))
       end
-      "#### Across the board\n\n#{lines.join("\n")}" unless lines.empty?
-    end
-
-    def unsettled
-      names = @results.select { |r| Summary.verdict(r) == "unsettled" }.map { |r| Summary.code(r.name) }
-      return if names.empty?
-
-      "#### Unsettled\n\nA timing too close to the limit to settle doesn't fail the run, but one that's unsettled in run " \
-        "after run is noisy: #{names.join(", ")}."
+      "Across the board:\n\n#{lines.join("\n")}" unless lines.empty?
     end
 
+    # The errors of more than a line, all of them (up to ERROR_LINES):
+    # their first lines are in view.
     def errors
-      failed = @results.select(&:error)
-      return if failed.empty?
-
-      shown = failed.map do |r|
+      @failed.select { |r| r.error.to_s.chomp.include?("\n") }.map do |r|
         error = r.error #: String
         lines = error.lines
         cut = "\n(#{Runner.count(lines.size - ERROR_LINES, "more line")} in the job's log)" if lines.size > ERROR_LINES
         "**#{Summary.code(r.name)}**\n\n#{Summary.block(lines.first(ERROR_LINES).join)}#{cut}"
       end
-      "#### Errors\n\n#{shown.join("\n\n")}"
+    end
+
+    # Each version's Ruby, where they differ.
+    def rubies
+      rubies = @runner.rubies
+      return if rubies.values.uniq.size == 1
+
+      "Baseline on #{Summary.code(rubies.fetch("baseline"))}, candidate on #{Summary.code(rubies.fetch("candidate"))}."
+    end
+
+    # How Duel decides that a timing is slower, as the settings have it.
+    def decides
+      format("A timing is slower when a %s%% confidence interval for its ratio, the candidate's to the baseline's, is above %s. " \
+        "[How Duel decides](%s)", (@settings.confidence * 100).round(1), @settings.limit, DECIDES)
     end
   end
 end

data/lib/duel/templates/duel.rb.erb

@@ -4,8 +4,8 @@
 #
 # Duel follows conventions, so set only what differs: benchmarks are in
 # duel/**/*_duel.rb, each version's lib/ is first on the load path, a
-# change is compared when it touches lib/ or ext/, and releases are
-# tagged v*.
+# change is compared when it touches lib/ or ext/ (or the benchmarks, or
+# this file), and releases are tagged v*.
 Duel.configure do |c|
 <% if library -%>
   # The library each version's workers require (from the gemspec, unless
@@ -32,4 +32,9 @@ Duel.configure do |c|
   # branch that upgrades Ruby is compared on each version's Ruby.
   c.ruby = :version_file
 <% end -%>
+
+  # When the workflow comments on a pull request with the report: :always,
+  # :results (passed or failed), :failures (failed, or couldn't compare),
+  # or :never.
+  # c.comment = :failures
 end

data/lib/duel/templates/perf.yml.erb

@@ -8,14 +8,20 @@ on:
     - cron: "0 4 * * *"
   workflow_dispatch:
 
+# The Duel job runs the branch's code (its benchmarks too), so it only
+# reads. Commenting is the Comment job's, which runs none of it.
 permissions:
   contents: read
-  pull-requests: write # to comment on a pull request with the report
 
 jobs:
   duel:
     name: Duel
     runs-on: ubuntu-latest
+    # Whether the Comment job comments (post, change or none), and the
+    # run's status (passed, failed or neutral), from Duel.
+    outputs:
+      comment: ${{ steps.compare.outputs.comment }}
+      status: ${{ steps.compare.outputs.status }}
 <% if working_directory -%>
     # The project is in a subdirectory of the repository: Duel runs there,
     # and checks out the whole repository for the baseline.
@@ -27,27 +33,56 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # the baseline comes from history, tags included
+          persist-credentials: false
       # (And whatever else your tests need set up: packages, services.)
 <% if version_file -%>
       # Each version runs on the Ruby its own .ruby-version names (see
-      # .duel.rb): for a pull request that upgrades Ruby, the main branch's
-      # too, linked where Duel finds it (as chruby would). It's set up
-      # before the project's own Ruby, which runs Duel.
+      # .duel.rb). When the baseline's names another Ruby than this code's,
+      # that one is installed too, and linked where Duel finds it (as
+      # chruby would), before the project's own Ruby, which runs Duel. The
+      # baseline is the Compare step's: where HEAD left the main branch
+      # (for a pull request, and run by hand), the commit before a push, or
+      # on a schedule the last release, the newest tag before HEAD that
+      # RELEASE_TAGS matches. (If .duel.rb sets c.main_branch or
+      # c.release_tags, set MAIN_BRANCH or RELEASE_TAGS to match.)
       - name: Find the baseline's Ruby
         id: baseline
-        if: github.event_name == 'pull_request'
-        run: echo "ruby=$(git show "origin/$GITHUB_BASE_REF:./.ruby-version" 2>/dev/null)" >> "$GITHUB_OUTPUT"
+        env:
+          BEFORE: ${{ github.event.before }}
+          MAIN_BRANCH: origin/${{ github.event.repository.default_branch }}
+          RELEASE_TAGS: "<%= release_tags %>"
+        run: |
+          case "$GITHUB_EVENT_NAME" in
+            push) base=$BEFORE ;;
+            schedule) base=$(git describe --tags --abbrev=0 --match "$RELEASE_TAGS" HEAD^ 2>/dev/null) || base= ;;
+            *) base=$(git merge-base HEAD "$MAIN_BRANCH" 2>/dev/null) || base= ;;
+          esac
+          ruby_of() { git show "$1:./.ruby-version" 2>/dev/null | awk 'NF { print $1; exit }'; }
+          ruby=
+          # (None without a baseline: a branch's first push, or no release yet.)
+          if [ -n "$base" ] && git cat-file -e "$base^{commit}" 2>/dev/null; then
+            ruby=$(ruby_of "$base")
+            [ "$ruby" = "$(ruby_of HEAD)" ] && ruby=
+          fi
+          echo "ruby=$ruby" >> "$GITHUB_OUTPUT"
       - uses: ruby/setup-ruby@v1
         id: baseline-ruby
         if: steps.baseline.outputs.ruby != ''
         with:
+<% if working_directory -%>
+          working-directory: <%= working_directory %>
+<% end -%>
           ruby-version: ${{ steps.baseline.outputs.ruby }}
+          # The bundle for this Ruby too, which the baseline's workers load.
+          # (Gems installed for one Ruby version don't load on another.)
+          bundler-cache: true
       - name: Link the baseline's Ruby where Duel finds it
         if: steps.baseline.outputs.ruby != ''
+        env:
+          PREFIX: ${{ steps.baseline-ruby.outputs.ruby-prefix }}
         run: |
-          prefix="${{ steps.baseline-ruby.outputs.ruby-prefix }}"
           mkdir -p ~/.rubies
-          ln -sfn "$prefix" ~/.rubies/ruby-"$("$prefix/bin/ruby" -e 'print RUBY_VERSION')"
+          ln -sfn "$PREFIX" ~/.rubies/ruby-"$("$PREFIX/bin/ruby" -e 'print RUBY_VERSION')"
 <% end -%>
       - uses: ruby/setup-ruby@v1
         with:
@@ -60,9 +95,11 @@ jobs:
           bundler-cache: true
       # Against the main branch for a pull request, what was there before
       # for a push, and the last release on a schedule (slow creep). Duel
-      # adds its report to the job's summary, and writes it to duel.md for
-      # the comment.
+      # adds its report to the job's summary, writes it to duel.md for the
+      # comment, and sets the step's outputs to say whether to comment, as
+      # c.comment in .duel.rb says, whatever the outcome.
       - name: Compare
+        id: compare
         env:
           DUEL_BASE: ${{ github.event_name == 'schedule' && 'last-release' || github.event_name == 'push' && github.event.before || '' }}
           # (Run by hand, it compares anyway: with nothing changed, the code
@@ -76,22 +113,52 @@ jobs:
             exit 0
           fi
           bundle exec duel --markdown "$RUNNER_TEMP/duel.md"
-      # The report, as a comment on the pull request: one comment, updated
-      # on every push. (A pull request from a fork gets no comment, as its
-      # token can't write one: the job's summary has the report.)
+      # The report, for the Comment job.
+      - name: Keep the report
+        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: duel-report
+          path: ${{ runner.temp }}/duel.md
+          if-no-files-found: ignore # none when Duel didn't get to compare
+          retention-days: 1
+
+  # The report, as a new comment on the pull request, when Duel says to:
+  # always (post), or only when its last comment's status differs from
+  # this run's (change), so the latest comment is never stale. It never
+  # edits or deletes a comment. This job checks nothing out and runs none
+  # of the branch's code, so it alone can write. (A pull request from a
+  # fork gets no comment, as its token can't write one: the Duel job's
+  # summary has the report.)
+  comment:
+    name: Comment
+    needs: duel
+    if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && (needs.duel.outputs.comment == 'post' || needs.duel.outputs.comment == 'change') }}
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write # to comment on the pull request with the report
+    steps:
+      - name: Get the report
+        id: report
+        continue-on-error: true # there's none when the Duel job failed before comparing
+        uses: actions/download-artifact@v8
+        with:
+          name: duel-report
+          path: ${{ runner.temp }}/report
       - name: Comment on the pull request
-        if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
+        if: steps.report.outcome == 'success'
         env:
           GH_TOKEN: ${{ github.token }}
           PR: ${{ github.event.pull_request.number }}
+          COMMENT: ${{ needs.duel.outputs.comment }}
+          STATUS: ${{ needs.duel.outputs.status }}
         run: |
-          [ -f "$RUNNER_TEMP/duel.md" ] || exit 0
-          marker="<!-- <%= marker %> -->"
-          { echo "$marker"; cat "$RUNNER_TEMP/duel.md"; } > "$RUNNER_TEMP/comment.md"
-          ids=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
-            --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | startswith(\"$marker\"))) | .id")
-          if [ -n "$ids" ]; then
-            gh api --method PATCH "repos/$GITHUB_REPOSITORY/issues/comments/${ids%%$'\n'*}" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
-          else
+          marker="<!-- <%= marker %>"
+          # The first line of the last comment Duel posted here: its marker,
+          # with its status (none in Duel 0.1.0's, which counts as another).
+          last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
+            --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\") or . == \"$marker -->\")" | tail -n 1)
+          if [ "$COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$STATUS -->" ]; }; then
+            { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
             gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
           fi

data/lib/duel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Duel
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/sig/duel/baseline.rbs

@@ -16,9 +16,15 @@ module Duel
     # The commit, or nil for "last-release" with no release yet.
     def ref: () -> String?
 
-    # Whether nothing Config#watch names changed since the baseline.
+    # Whether nothing #watched changed since the baseline.
     def unchanged?: () -> bool
 
+    # What a change must touch to be compared: the code (Config#watch),
+    # and what decides how it's measured (the benchmarks, the
+    # configuration's file, and with each version on its own Ruby, its
+    # version files).
+    def watched: () -> Array[String]
+
     # The baseline's tree, checked out and built if it's a commit.
     def root: () -> String
 
@@ -43,6 +49,15 @@ module Duel
 
     private
 
+    # The benchmarks' directory, or for benchmarks at the root, their glob.
+    def benchmarks: () -> String
+
+    # The configuration's file, from the root.
+    def config_file: () -> String
+
+    # The version files at the root.
+    def version_files: () -> Array[String]
+
     # Where HEAD left the main branch: their merge base, or a failure that
     # says why there's none.
     def merge_base: () -> String

data/sig/duel/cli.rbs

@@ -19,6 +19,15 @@ module Duel
     # Where GitHub Actions has a step add to its job's summary.
     STEP_SUMMARY: String
 
+    # Where GitHub Actions has a step set its outputs.
+    STEP_OUTPUT: String
+
+    # The statuses the workflow comments on, by when it does.
+    COMMENTED: Hash[Config::comment, Array[String]]
+
+    # A run's status as the comment's marker has it.
+    MARKED: Hash[String, String]
+
     # The variables that set options, to their options.
     ENV_OPTIONS: Hash[String, String]
 
@@ -33,6 +42,7 @@ module Duel
     @markdown: String?
     @json: String?
     @settings: Settings?
+    @config: Config?
 
     def initialize: (Array[String] argv, ?env: _Env, ?out: _Output, ?err: _Output) -> void
 
@@ -44,6 +54,13 @@ module Duel
     # +source+ as a Regexp, or an option's invalid argument.
     def self.regexp: (String source) -> Regexp
 
+    # Whether the workflow comments on a pull request: "post", "change"
+    # or "none".
+    def self.comment: (Config::comment mode, String status) -> String
+
+    # The mode --comment names, or an invalid argument.
+    def self.comment_mode: (String name) -> Config::comment
+
     def parse: () -> Settings
 
     private
@@ -52,14 +69,18 @@ module Duel
     def compare: (Config config, Settings settings) -> Integer
 
     # Says there's nothing to compare, and why, and passes.
-    def nothing: (String why) -> Integer
+    def nothing: (String title, String why) -> Integer
+
+    # Reports a run that didn't compare, and why, and returns +exit+.
+    def unfinished: (String mark, String title, String status, String why, Integer exit) -> Integer
 
-    # Reports a run that didn't compare, and returns +exit+.
-    def unfinished: (String title, String status, String message, Integer exit) -> Integer
+    # What the workflow does about its comment on a pull request, for a
+    # run of +status+.
+    def commenting: (String status) -> String
 
     # Writes the reports where they're asked for, each made only if it's
-    # written.
-    def publish: (^() -> String markdown, ^() -> JSONReport::report json) -> void
+    # written, and on GitHub Actions, the step's outputs.
+    def publish: (String status, ^() -> String markdown, ^(String comment) -> JSONReport::report json) -> void
 
     # Writes +text+ to +path+, in a directory made for it.
     def write: (String path, String text) -> void

data/sig/duel/config.rbs

@@ -10,6 +10,9 @@ module Duel
     # version file's, a path, or what a block makes of the version's tree.
     type ruby = :version_file | String | ^(String root) -> String | nil
 
+    # When the workflow comments on a pull request (see #comment).
+    type comment = :always | :results | :failures | :never
+
     @root: String
     @benchmarks: String
     @watch: Array[String]
@@ -19,6 +22,7 @@ module Duel
     @release_tags: String
     @prepares: Hash[Symbol, Array[prepare]]
     @ruby: ruby
+    @comment: comment
     @metrics: Array[singleton(Metric)]
     @in_workers: Array[^(Stops stops) -> void]
     @hooks: Hash[Symbol, Array[hook]]
@@ -32,7 +36,8 @@ module Duel
     # A glob, from the root, of the files defining benchmarks.
     attr_accessor benchmarks: String
 
-    # Paths, from the root, whose changes a comparison is about.
+    # Paths, from the root, of the code whose changes a comparison is
+    # about (with what decides how it's measured).
     attr_accessor watch: Array[String]
 
     # The library to require from each version, or nil for none.
@@ -52,6 +57,16 @@ module Duel
     # given the version's tree.
     attr_accessor ruby: ruby
 
+    # When the workflow comments on a pull request: :always, :results,
+    # :failures (the default) or :never.
+    attr_reader comment: comment
+
+    # The values #comment takes.
+    COMMENTS: Array[comment]
+
+    # Sets #comment, or fails for a value it doesn't take.
+    def comment=: (untyped mode) -> untyped
+
     # What #prepare was given, by scope.
     # @api private
     attr_reader prepares: Hash[Symbol, Array[prepare]]