openlanes 3.0.0 → 3.1.0

data/lib/openlanes/vcs/github.rb

@@ -12,12 +12,23 @@ module OpenLanes
     # repository.
     class GitHub
       # Fields asked of `gh pr list`.
-      FIELDS = %w[number title url headRefName files state isDraft mergedAt].freeze
+      FIELDS = %w[number title url headRefName files state isDraft mergedAt labels].freeze
+
+      # A runner that runs every command in one directory. `gh` with no `-R`
+      # asks the checkout it runs in which repository it means, and the
+      # engine's working directory is the plans project, which `--root` can
+      # point away from: label sync then wrote to the wrong repository.
+      Rooted = Data.define(:command, :chdir) do
+        def run(*argv, **) = command.run(*argv, chdir:, **)
+        def run!(*argv, **) = command.run!(*argv, chdir:, **)
+      end
 
       # @param command [TTY::Command] runner, injectable for tests
       # @param limit [Integer] how many pull requests to fetch
-      def initialize(command: TTY::Command.new(printer: :null), limit: 200)
-        @command = command
+      # @param chdir [String, nil] the checkout `gh` runs in; nil means the
+      #   current directory
+      def initialize(command: TTY::Command.new(printer: :null), limit: 200, chdir: nil)
+        @command = chdir ? Rooted.new(command:, chdir:) : command
         @limit = limit
       end
 
@@ -53,7 +64,8 @@ module OpenLanes
             branch: pr["headRefName"].to_s,
             files:  Array(pr["files"]).map { |f| f["path"] }.compact,
             state:  self.class.state_label(pr),
-            open:   pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN"
+            open:   pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN",
+            labels: Array(pr["labels"]).map { |l| l["name"] }
           }
         end
       rescue TTY::Command::ExitError, JSON::ParserError => e
@@ -79,7 +91,10 @@ module OpenLanes
 
       # Fields asked of `gh pr view`, which unlike `pr list` can be told about
       # one pull request in another repository.
-      VIEW_FIELDS = %w[number title url headRefName state isDraft mergedAt body].freeze
+      VIEW_FIELDS = %w[
+        number title url headRefName headRefOid baseRefName mergeCommit state isDraft mergedAt body labels
+        mergeStateStatus
+      ].freeze
 
       # A reference to one pull request: a bare number, a `#`-prefixed number,
       # or a full URL to a GitHub pull request or a GitLab merge request.
@@ -107,7 +122,8 @@ module OpenLanes
       # One pull request, by number or URL.
       #
       # @param ref [String] "12", "#12" or "https://github.com/o/r/pull/12"
-      # @return [Hash] `{number:, title:, url:, branch:, state:, body:}`
+      # @return [Hash] `{number:, title:, url:, branch:, head:, state:, open:, labels:, body:, merge_state:}`,
+      #   the keys {#pulls} gives a row plus the body and GitHub's `mergeStateStatus`
       # @raise [OpenLanes::Error]
       def pull_request(ref)
         out = @command.run("gh", "pr", "view", ref.to_s, "--json", VIEW_FIELDS.join(",")).out
@@ -115,12 +131,18 @@ module OpenLanes
 
         pr = JSON.parse(out)
         {
-          number: pr["number"],
-          title:  pr["title"].to_s,
-          url:    pr["url"].to_s,
-          branch: pr["headRefName"].to_s,
-          state:  self.class.state_label(pr),
-          body:   pr["body"].to_s
+          number:       pr["number"],
+          title:        pr["title"].to_s,
+          url:          pr["url"].to_s,
+          branch:       pr["headRefName"].to_s,
+          head:         pr["headRefOid"].to_s,
+          state:        self.class.state_label(pr),
+          open:         pr["mergedAt"].nil? && pr["state"].to_s.upcase == "OPEN",
+          labels:       Array(pr["labels"]).map { |l| l["name"] },
+          body:         pr["body"].to_s,
+          merge_state:  pr["mergeStateStatus"].to_s,
+          base:         pr["baseRefName"].to_s,
+          merge_commit: pr.dig("mergeCommit", "oid").to_s
         }
       rescue TTY::Command::ExitError, JSON::ParserError => e
         raise Error, "could not read pull request #{ref}: #{e.message.lines.first.to_s.strip}"
@@ -135,6 +157,30 @@ module OpenLanes
         refs.map { |ref| pull_request(ref) }
       end
 
+      # The pull request a branch merged through, newest first, for
+      # `worktree prune` to ask whether a checkout's work landed.
+      #
+      # @param branch [String]
+      # @return [Hash, nil] `{number:, base:, merge_commit:}`; nil when none merged
+      def merged_pull_for(branch)
+        out = @command.run("gh",
+          "pr",
+          "list",
+          "--state",
+          "merged",
+          "--head",
+          branch,
+          "--limit",
+          "1",
+          "--json",
+          "number,baseRefName,mergeCommit").out
+        pr = JSON.parse(out.to_s.strip.empty? ? "[]" : out).first or return nil
+
+        { number: pr["number"], base: pr["baseRefName"].to_s, merge_commit: pr.dig("mergeCommit", "oid").to_s }
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not list the pull requests of #{branch}: #{e.message.lines.first.to_s.strip}"
+      end
+
       # `gh` speaks in enums; `pull-requests.md` speaks in the words the state
       # machine parses. Translate once, here, rather than at each call site.
       #
@@ -162,10 +208,314 @@ module OpenLanes
         raise Error, "could not retitle ##{number}: #{e.message.lines.first.to_s.strip}"
       end
 
+      # Create a review label when the repository lacks it. Never `--force`:
+      # this runs before every label swap, and recolouring is {LabelSync}'s
+      # job, done once per run where the change is announced, not as a side
+      # effect of labelling one pull request.
+      #
+      # @param label [Plans::ReviewLabel]
+      # @param repo [String, nil] "owner/repo"; nil means the current checkout's
+      # @return [void]
+      # @raise [OpenLanes::Error]
+      def ensure_label(label, repo: nil)
+        @command.run("gh",
+          "label",
+          "create",
+          label.name,
+          "--color",
+          label.colour,
+          "--description",
+          label.meaning,
+          *repo_flag(repo))
+      rescue TTY::Command::ExitError, SystemCallError => e
+        return if e.message.match?(/already exists/i)
+
+        raise Error, "could not create label #{label.name}: #{first_line(e)}"
+      end
+
+      # Every label the repository has, and its colour.
+      #
+      # @param repo [String, nil]
+      # @return [Hash{String => String}] name to colour, lower-case hex without `#`
+      # @raise [OpenLanes::Error]
+      def label_colours(repo: nil)
+        out = @command.run("gh", "label", "list", "--limit", "1000", "--json", "name,color", *repo_flag(repo)).out
+        JSON.parse(out).to_h { [it["name"].to_s, it["color"].to_s.downcase] }
+      # A machine without `gh` (a CI image, say) is a reason to skip the sync,
+      # not to stop the run: {LabelSync}'s caller warns on Error.
+      rescue TTY::Command::ExitError, JSON::ParserError, SystemCallError => e
+        raise Error, "could not list labels: #{first_line(e)}"
+      end
+
+      # The open pull requests that carry one label, asked of GitHub rather
+      # than of `pull-requests.md`, which only knows the plans' own.
+      #
+      # Every one of them, through the issues API with `--paginate`: `gh pr
+      # list` stops at its `--limit`, and a migration that saw only the first
+      # thousand would mark itself done with the rest still carrying the label.
+      # The issues API lists pull requests among the issues; `pull_request` is
+      # what tells them apart.
+      #
+      # @param name [String] the label
+      # @param repo [String, nil]
+      # @return [Hash{Integer => Array<String>}] each one's number, and every
+      #   label it carries
+      # @raise [OpenLanes::Error]
+      def open_pulls_labelled(name, repo: nil)
+        out = @command.run("gh",
+          "api",
+          "--paginate",
+          "-X",
+          "GET",
+          "repos/#{repo || "{owner}/{repo}"}/issues",
+          "-f",
+          "state=open",
+          "-f",
+          "labels=#{name}",
+          "-f",
+          "per_page=100",
+          "--jq",
+          ".[] | select(.pull_request) | {number, labels: [.labels[].name]}").out
+        out.each_line.reject { it.strip.empty? }.to_h do |line|
+          pull = JSON.parse(line)
+          [pull["number"], Array(pull["labels"])]
+        end
+      rescue TTY::Command::ExitError, JSON::ParserError, SystemCallError => e
+        raise Error, "could not list pull requests labelled #{name}: #{first_line(e)}"
+      end
+
+      # Give an existing label its colour and description back (R3). Only
+      # {LabelSync} calls this, and only for the labels openlanes owns.
+      #
+      # @param label [Plans::ReviewLabel]
+      # @param repo [String, nil]
+      # @return [void]
+      # @raise [OpenLanes::Error]
+      def recolour_label(label, repo: nil)
+        @command.run("gh",
+          "label",
+          "edit",
+          label.name,
+          "--color",
+          label.colour,
+          "--description",
+          label.meaning,
+          *repo_flag(repo))
+      rescue TTY::Command::ExitError, SystemCallError => e
+        raise Error, "could not recolour label #{label.name}: #{first_line(e)}"
+      end
+
+      # Put one label on a pull request and take others off, in one edit.
+      #
+      # @param number [Integer]
+      # @param repo [String, nil]
+      # @param add [Plans::ReviewLabel]
+      # @param remove [Array<String>] label names to take off
+      # @param create_missing [Boolean] create +add+ on the repository first;
+      #   false when the caller already has, once, for many pull requests
+      # @return [Array<String>] the labels the pull request is left with
+      # @raise [OpenLanes::Error]
+      def swap_label(number:, add:, repo: nil, remove: [], create_missing: true)
+        ensure_label(add, repo:) if create_missing
+        removing = remove.map(&:to_s) - [add.name]
+        begin
+          edit_labels(number, add, removing, repo)
+        rescue Error
+          raise if removing.empty?
+
+          # Removing a label the pull request does not carry fails the whole
+          # edit (open question 6). Adding alone would leave any of `removing`
+          # it does carry beside the new one, two verdicts at once, so ask what
+          # is still there and take exactly that off. A second failure is real.
+          edit_labels(number, add, labels(number:, repo:) & removing, repo)
+        end
+        labels(number:, repo:)
+      end
+
+      # @param number [Integer]
+      # @param repo [String, nil]
+      # @return [Array<String>] label names on the pull request
+      def labels(number:, repo: nil)
+        out = @command.run("gh", "pr", "view", number.to_s, "--json", "labels", *repo_flag(repo)).out
+        Array(JSON.parse(out)["labels"]).map { |l| l["name"] }
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not read labels of ##{number}: #{first_line(e)}"
+      end
+
+      # Post one conversation comment. The engine, not chewie, says why a
+      # verification failed: only the engine has the SHA the screenshot link
+      # needs, because only the engine pushes.
+      #
+      # @param number [Integer]
+      # @param body [String]
+      # @param repo [String, nil]
+      # @return [void]
+      def comment(number:, body:, repo: nil)
+        @command.run("gh", "pr", "comment", number.to_s, "--body", body, *repo_flag(repo))
+      rescue TTY::Command::ExitError => e
+        raise Error, "could not comment on ##{number}: #{first_line(e)}"
+      end
+
+      # @param number [Integer]
+      # @param repo [String, nil]
+      # @return [Array<Hash>] `{name:, bucket:}`, bucket as `gh` reports it
+      def checks(number:, repo: nil)
+        # `gh pr checks` exits non-zero when a check failed or is pending, and
+        # the JSON it printed is still the answer, so its status is no verdict.
+        result = @command.run!("gh", "pr", "checks", number.to_s, "--json", "name,state,bucket", *repo_flag(repo))
+        out = result.out.to_s
+        if out.strip.empty?
+          return [] if result.success? || result.err.to_s.match?(/no checks reported/i)
+
+          raise Error, "could not read checks of ##{number}: #{result.err.to_s.lines.first.to_s.strip}"
+        end
+
+        JSON.parse(out).map { |c| { name: c["name"].to_s, bucket: c["bucket"].to_s } }
+      rescue JSON::ParserError => e
+        raise Error, "could not read checks of ##{number}: #{e.message.lines.first.to_s.strip}"
+      end
+
+      # CI on a branch's tip, `main` above all (R5): a pull request green on
+      # its own head still lands on whatever `main` is, so a red `main` holds
+      # every merge. Check runs and commit statuses both, mapped onto the
+      # buckets `gh pr checks` uses, so {CiGate.verdict} reads them alike.
+      # CircleCI reports statuses only: reading check runs alone saw no CI on
+      # `main` and held every merge, and missed a red status beside a green run.
+      #
+      # @param branch [String]
+      # @param repo [String, nil]
+      # @return [Array<Hash>] `{name:, bucket:}`
+      # @raise [OpenLanes::Error] when GitHub cannot be read
+      def branch_checks(branch:, repo: nil)
+        commit = "repos/#{repo || "{owner}/{repo}"}/commits/#{branch}"
+        runs = JSON.parse(@command.run("gh", "api", "#{commit}/check-runs").out)["check_runs"]
+        statuses = JSON.parse(@command.run("gh", "api", "#{commit}/status").out)["statuses"]
+        Array(runs).map { |c| { name: c["name"].to_s, bucket: bucket_of(c) } } +
+          Array(statuses).map { |s| { name: s["context"].to_s, bucket: status_bucket(s) } }
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not read checks of #{branch}: #{first_line(e)}"
+      end
+
+      # Merge one pull request, as the engine does on palpatine's `auto`
+      # (P4). A merge commit, which is how this repository's history reads;
+      # the branch is left alone, since the plan's worktree still has it
+      # checked out. Agents never reach this: `gh pr merge` is ungrantable.
+      #
+      # @param number [Integer]
+      # @param head [String] the head commit CI was read for; GitHub refuses
+      #   the merge once the branch has moved past it
+      # @param repo [String, nil]
+      # @return [void]
+      # @raise [OpenLanes::Error] when GitHub refuses, a conflict among the reasons
+      def merge(number:, head:, repo: nil)
+        @command.run("gh", "pr", "merge", number.to_s, "--merge", "--match-head-commit", head, *repo_flag(repo))
+      rescue TTY::Command::ExitError => e
+        raise Error, "could not merge ##{number}: #{first_line(e)}"
+      end
+
+      # Rebase a pull request's branch onto its base on GitHub's side (P5),
+      # for a sibling built from a branch no worktree of this run holds.
+      #
+      # @param number [Integer]
+      # @param repo [String, nil]
+      # @return [void]
+      # @raise [OpenLanes::Error] when the rebase conflicts or GitHub refuses
+      def update_branch(number:, repo: nil)
+        @command.run("gh", "pr", "update-branch", number.to_s, "--rebase", *repo_flag(repo))
+      rescue TTY::Command::ExitError => e
+        raise Error, "could not rebase ##{number} onto its base: #{first_line(e)}"
+      end
+
+      # @param number [Integer]
+      # @param repo [String, nil]
+      # @return [Array<Hash>] `{author:, body:, url:}`, conversation comments then reviews
+      def review_comments(number:, repo: nil)
+        out = @command.run("gh", "pr", "view", number.to_s, "--json", "comments,reviews", *repo_flag(repo)).out
+        data = JSON.parse(out)
+        (Array(data["comments"]) + Array(data["reviews"])).filter_map do |c|
+          next if c["body"].to_s.strip.empty?
+
+          { author: c.dig("author", "login").to_s, body: c["body"].to_s, url: c["url"].to_s }
+        end
+      rescue TTY::Command::ExitError, JSON::ParserError => e
+        raise Error, "could not read comments of ##{number}: #{first_line(e)}"
+      end
+
+      # @param url [String] a pull request URL
+      # @return [String, nil] "owner/repo", or nil when the URL is not GitHub's
+      def self.repo_of(url) = url.to_s[%r{github\.com/([^/]+/[^/]+)/pull/}, 1]
+
+      # The number a pull request reference names: the `/pull/N` segment of a
+      # URL, or a bare or `#`-prefixed number. Never "the trailing digits",
+      # which read `…/pull/7#issuecomment-1234` as #1234 and relabel a
+      # different pull request.
+      #
+      # @param ref [String, Integer] "12", "#12" or a pull request URL
+      # @return [Integer]
+      # @raise [OpenLanes::Error] when `ref` names no pull request
+      def self.number_of(ref)
+        text = ref.to_s.strip
+        found = text[%r{\Ahttps?://\S+?/(?:pull|merge_requests)/(\d+)(?:[/?#]\S*)?\z}, 1] || text[/\A#?(\d+)\z/, 1]
+        raise Error, "not a pull request number or URL: #{ref}" unless found
+
+        found.to_i
+      end
+
       # @return [Boolean] whether `gh` is installed and authenticated
       def available?
         @command.run!("gh", "auth", "status").success?
       end
+
+      private
+
+      def repo_flag(repo) = repo ? ["-R", repo] : []
+
+      # A check run as a `gh pr checks` bucket. An unlisted conclusion is a
+      # failure, as {CiGate} treats an unknown bucket.
+      #
+      # @param run [Hash] one entry of `check_runs`
+      # @return [String]
+      def bucket_of(run)
+        return "pending" unless run["status"].to_s == "completed"
+
+        case run["conclusion"].to_s
+        when "success", "neutral" then "pass"
+        when "skipped" then "skipping"
+        else "fail"
+        end
+      end
+
+      # A commit status as a `gh pr checks` bucket. `error`, and any state
+      # GitHub adds later, is a failure.
+      #
+      # @param status [Hash] one entry of `statuses`
+      # @return [String]
+      def status_bucket(status)
+        case status["state"].to_s
+        when "success" then "pass"
+        when "pending" then "pending"
+        else "fail"
+        end
+      end
+
+      # The first line `gh` wrote to stderr, which is the one naming the problem.
+      def first_line(error)
+        stderr = error.message[/stderr: (.*)/, 1].to_s.strip
+        stderr.empty? ? error.message.lines.first.to_s.strip : stderr
+      end
+
+      def edit_labels(number, add, removing, repo)
+        @command.run("gh",
+          "pr",
+          "edit",
+          number.to_s,
+          "--add-label",
+          add.name,
+          *removing.flat_map { |r| ["--remove-label", r] },
+          *repo_flag(repo))
+      rescue TTY::Command::ExitError => e
+        raise Error, "could not label ##{number}: #{first_line(e)}"
+      end
     end
   end
 end

data/lib/openlanes/vcs/label_migration.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Vcs
+    # Moves the open pull requests that still carry M3's review labels onto
+    # R3's, once per repository, before anything reads a label in R3's sense.
+    #
+    # Under M3 `ready-to-merge` was a review verdict, "passed with nothing
+    # open"; under R3 it is chewie-verifier's, and the merge gate reads it as
+    # "verified". Left on a pull request no verifier ever saw, it would be
+    # read as a verification that never happened. So it goes back to
+    # `review-approved`, and a pull request chewie did verify earns it again
+    # from the coverage gate: an ambiguous label is re-checked, never trusted.
+    # M3's two other names map straight across ({Plans::ReviewLabel::RENAMED}).
+    #
+    # The steps run in order, and a pull request that carries `ok-to-merge`
+    # is left out of the first two: the third puts `ready-to-merge` on it and
+    # leaves `ok-to-merge` where it is, so a run interrupted after the third
+    # step cannot read the `ready-to-merge` it just put there as M3's and take
+    # it off again. `ok-to-merge` comes off once the migration is marked done.
+    #
+    # Done is a label on the repository, {Plans::ReviewLabel::MIGRATED},
+    # created after the last step and never touched by {LabelSync}. Not the
+    # colour of `ready-to-merge`: an earlier release recoloured that without
+    # moving a pull request, which made the old meaning look migrated on
+    # every repository it had run on. Nothing is kept on this machine, so a
+    # second machine starting on the same repository agrees.
+    class LabelMigration
+      # Every open pull request carrying +from+ moves to +to+.
+      Step = Data.define(:from, :to) do
+        # @return [String]
+        def to_s = "#{from} → #{to}"
+      end
+
+      # M3's chewie verification, kept beside `ready-to-merge` until the end.
+      VERIFIED = "ok-to-merge"
+
+      STEPS = [
+        Step.new(from: Plans::ReviewLabel::READY_TO_MERGE.name, to: Plans::ReviewLabel::APPROVED),
+        *Plans::ReviewLabel::RENAMED.map { |from, to| Step.new(from:, to:) }
+      ].freeze
+
+      # What the migration did, or under a dry run would do.
+      #
+      # @!attribute [r] pending
+      #   @return [Boolean] whether the repository was not yet migrated
+      # @!attribute [r] moves
+      #   @return [Hash{Step => Array<Integer>}] each step's pull request numbers
+      Outcome = Data.define(:pending, :moves) do
+        alias_method :pending?, :pending
+
+        # @return [Array<Integer>] every pull request relabelled, in step order
+        def relabelled = moves.values.flatten
+
+        # @return [String, nil] one line for the startup notice; nil when nothing moved
+        def to_s
+          return if relabelled.empty?
+
+          "relabel #{moves.map { |step, numbers| "#{step} on #{numbered(numbers)}" }.join("; ")}"
+        end
+
+        private
+
+        # @param numbers [Array<Integer>]
+        # @return [String] "#7, #9"
+        def numbered(numbers) = numbers.map { "##{it}" }.join(", ")
+      end
+
+      # @param github [GitHub]
+      def initialize(github: GitHub.new)
+        @github = github
+      end
+
+      # @param repo [String, nil] "owner/repo"; nil means the current checkout's
+      # @param dry_run [Boolean] read the pull requests, relabel none, mark nothing
+      # @return [Outcome]
+      # @raise [OpenLanes::Error] when `gh` cannot list or relabel; the
+      #   repository stays unmarked, so the next start tries again
+      def call(repo: nil, dry_run: false)
+        return Outcome.new(pending: false, moves: {}) if done?(repo)
+
+        moves = STEPS.to_h { [it, move(it, repo:, dry_run:)] }.reject { |_, numbers| numbers.empty? }
+        finish(repo) unless dry_run
+        Outcome.new(pending: true, moves:)
+      end
+
+      private
+
+      # @return [Boolean]
+      def done?(repo) = @github.label_colours(repo:).key?(Plans::ReviewLabel::MIGRATED.name)
+
+      # @param step [Step]
+      # @return [Array<Integer>] the pull requests moved, or under a dry run to be
+      def move(step, repo:, dry_run:)
+        numbers = @github.open_pulls_labelled(step.from, repo:).reject { |_, labels| held?(step, labels) }.keys
+        return numbers if dry_run || numbers.empty?
+
+        @github.ensure_label(step.to, repo:)
+        remove = Plans::ReviewLabel.displaced_by(step.to) - [VERIFIED]
+        numbers.each { @github.swap_label(number: it, add: step.to, remove:, repo:, create_missing: false) }
+        numbers
+      end
+
+      # Whether a pull request waits for the `ok-to-merge` step instead.
+      #
+      # @param step [Step]
+      # @param labels [Array<String>]
+      # @return [Boolean]
+      def held?(step, labels) = step.from != VERIFIED && labels.include?(VERIFIED)
+
+      # Mark the repository done, then take `ok-to-merge` off. The mark first:
+      # once `ok-to-merge` is gone a `ready-to-merge` beside it is no longer
+      # told apart from M3's. Taking it off is tidying, so it may fail: the
+      # next verdict on that pull request takes it off anyway.
+      #
+      # @return [void]
+      def finish(repo)
+        @github.ensure_label(Plans::ReviewLabel::MIGRATED, repo:)
+        tidy(repo)
+      end
+
+      # @return [void]
+      def tidy(repo)
+        @github.open_pulls_labelled(VERIFIED, repo:).each_key do |number|
+          @github.swap_label(number:, add: Plans::ReviewLabel::READY_TO_MERGE, remove: [VERIFIED], repo:, create_missing: false)
+        end
+      rescue Error => e
+        UI.log("#{VERIFIED} left on open pull requests: #{e.message}", level: :warn)
+      end
+    end
+  end
+end

data/lib/openlanes/vcs/label_sync.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Vcs
+    # Makes the repository's review labels match {Plans::ReviewLabel::ALL}
+    # (R3): creates the missing, recolours the mismatched, leaves the rest.
+    #
+    # Run once when the engine starts on a project. Labelling a pull request
+    # still creates a missing label on first use, but never recolours one, so
+    # without this a repository labelled under M3 would keep `review-rejected`
+    # in M3's red forever and a person reading the board would see two reds
+    # meaning one thing. One `gh label list`, and a write only per label that
+    # is wrong, so a second run asks once and changes nothing.
+    class LabelSync
+      # What was done to one label, or under a dry run what would have been.
+      #
+      # @!attribute [r] action
+      #   @return [Symbol] :create, :recolour or :keep
+      # @!attribute [r] was
+      #   @return [String, nil] the colour the repository had, for :recolour
+      Change = Data.define(:label, :action, :was) do
+        # @return [Boolean] whether this label needs a write
+        def write? = action != :keep
+
+        # @return [String] one line for the startup notice
+        def to_s
+          case action
+          when :create then "create #{label.name} (##{label.colour})"
+          when :recolour then "recolour #{label.name} ##{was} → ##{label.colour}"
+          else "keep #{label.name}"
+          end
+        end
+      end
+
+      # @param github [GitHub]
+      # @param labels [Array<Plans::ReviewLabel>]
+      def initialize(github: GitHub.new, labels: Plans::ReviewLabel::ALL)
+        @github = github
+        @labels = labels
+      end
+
+      # @param repo [String, nil] "owner/repo"; nil means the current checkout's
+      # @param dry_run [Boolean] read the repository's labels, write nothing
+      # @return [Array<Change>] one per label, in R3 order
+      # @raise [OpenLanes::Error] when `gh` cannot list or write a label
+      def call(repo: nil, dry_run: false)
+        have = @github.label_colours(repo:)
+        changes = @labels.map { change_for(it, have) }
+        return changes if dry_run
+
+        changes.each do |change|
+          case change.action
+          when :create then @github.ensure_label(change.label, repo:)
+          when :recolour then @github.recolour_label(change.label, repo:)
+          end
+        end
+        changes
+      end
+
+      private
+
+      # GitHub answers colours in lower case and R3 writes some in upper, so
+      # they are compared without case; otherwise every run would "fix" them.
+      #
+      # @return [Change]
+      def change_for(label, have)
+        colour = have[label.name]
+        return Change.new(label:, action: :create, was: nil) if colour.nil?
+        return Change.new(label:, action: :keep, was: colour) if colour.casecmp?(label.colour)
+
+        Change.new(label:, action: :recolour, was: colour)
+      end
+    end
+  end
+end