hecks 3.5.0 → 3.7.0

data/lib/hecks/hecks/adapters/codebase/promotion/move.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../../git"
+
+module Hecks
+  module Adapters
+    module Codebase
+      module Promotion
+        # One accepted promotion carried out: a fast-forward of the lane onto the commit and, when
+        # the `Lane` row says the lane `feeds` a tag, a forward-only move of that tag.
+        #
+        # Unconfirmed it names the move and makes none. A lane that already holds the commit is not
+        # moved, but a confirmed run still brings the tag it feeds up to the lane's head, so a tag
+        # left behind by a half-finished promotion is repaired by the next one.
+        class Move
+          # @param held [Hash] the `PromotionRun` record: `lane`, `commit`, `head`, `confirm`
+          # @param tree [Tree] the checkout, already known to be one
+          def initialize(held, tree)
+            @args = held.transform_values { |value| Promotion.plain(value) }
+            @lane = Promotion.row(@args[:lane])
+            @commit = @args.fetch(:commit)
+            @root = tree.root
+            @repo = Promotion.git || Git.new
+          end
+
+          # @return [Hash{Symbol => Hash}] `report:` what was, or would be, moved, and `promoted:`
+          #   whether the remote was changed
+          # @raise [ConsoleCapture::Failure] when the remote refuses the move
+          def carry_out
+            return already_held if held?
+            return Promotion.outcome("rehearsal: would fast-forward #{span} (add --confirm to move it)", false) unless confirmed?
+
+            @repo.fast_forward(@commit, name, chdir: @root)
+            Promotion.outcome("fast-forwarded #{span}#{feed_note(@commit)}", true)
+          end
+
+          private
+
+          # A lane that holds the commit is not moved, but the tag it feeds is still brought up
+          # to the lane: a promotion that moved the lane and then failed on the tag is finished
+          # by the next run, whichever commit that run is about, not left behind for good.
+          def already_held
+            said = "#{name} already holds #{short(@commit)}"
+            return Promotion.outcome(said, false) unless confirmed? && feeds?
+
+            moved = @repo.move_tag(feed, @args[:head], chdir: @root)
+            Promotion.outcome("#{said}, #{feed} #{moved}", moved != :current)
+          end
+
+          def feed = @lane["feeds"].to_s
+
+          def feeds? = !feed.empty?
+
+          def name = @lane["name"]
+
+          def confirmed? = @args[:confirm]
+
+          def span = "#{name} #{short(@args[:head])}..#{short(@commit)}"
+
+          def short(commit) = commit.to_s[0, 7]
+
+          def held? = @args[:head] != "none" && @repo.ancestor?(@commit, @args[:head], chdir: @root)
+
+          # @param onto [String] the commit the fed tag should name
+          def feed_note(onto) = feeds? ? ", #{feed} #{@repo.move_tag(feed, onto, chdir: @root)}" : ""
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/promotion/standing.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "candidates"
+require_relative "../../git"
+
+module Hecks
+  module Adapters
+    module Codebase
+      module Promotion
+        # Where a lane, the lane it follows and a commit stand: the facts a promotion is judged by.
+        #
+        # It reads the remote and the checks and answers them as value objects. It does not judge
+        # them; `PromotionRun.Accept` holds the rules. Without a named commit it offers the newest
+        # commit of the followed lane that passed every check, so the answer does not depend
+        # on which commit's CI run happened to start the promotion.
+        class Standing
+          # @param held [Hash] the `PromotionRun` record: `lane`, and `commit` when one was named
+          # @param tree [Tree] the checkout, already known to be one
+          def initialize(held, tree)
+            @lane_name = Promotion.plain(held[:lane])
+            @lane = Promotion.row(@lane_name)
+            @named = Promotion.plain(held[:commit])
+            @where = tree.root
+            @repo = Promotion.git || Git.new
+          end
+
+          # @return [Hash{Symbol => Hash}] `lane_known`, `green`, `descends`, `commit`, `head` and
+          #   the `reason` they were not all true
+          def facts
+            return Promotion.unknown(@lane_name) unless follower?
+            return Promotion.unknown(@lane["name"], "#{source} has no head on origin") unless source_head
+
+            fetch
+            answer
+          end
+
+          private
+
+          def follower? = @lane && !@lane["follows"].to_s.empty?
+
+          def source = @lane["follows"]
+
+          # The commit named, else the newest one of the followed lane that every required check
+          # passed on, else its head, so that a refusal says what the head is waiting on.
+          def commit = @commit ||= @named || candidates.newest_certified || source_head
+
+          def candidates = @candidates ||= Candidates.new(@repo, @where, source_head, head)
+
+          def head = remember(:@head) { remote("refs/heads/#{@lane["name"]}") }
+
+          def source_head = remember(:@source_head) { remote("refs/heads/#{source}") }
+
+          # Memoizes a value that may be nil: an absent lane is asked about once, not on each use.
+          def remember(name)
+            return instance_variable_get(name) if instance_variable_defined?(name)
+
+            instance_variable_set(name, yield)
+          end
+
+          def remote(ref) = @repo.remote_head(ref, chdir: @where)
+
+          def ancestor?(older, newer) = @repo.ancestor?(older, newer, chdir: @where)
+
+          # The history a fast-forward test needs, which a shallow clone lacks.
+          def fetch
+            @repo.capture("fetch", "origin", source, chdir: @where)
+            @repo.capture("fetch", "origin", @lane["name"], chdir: @where) if head
+          end
+
+          # A commit is on the lane a promotion draws from when that lane's head contains it.
+          def on_source? = !source_head.nil? && ancestor?(commit, source_head)
+
+          # A commit the lane already holds needs no move, and a commit that contains the lane's
+          # head is a fast-forward; only one that is neither would rewind or fork the lane.
+          def forward_or_held? = head.nil? || ancestor?(head, commit) || ancestor?(commit, head)
+
+          def answer
+            gate = candidates.gate(commit)
+            descends = on_source? && forward_or_held?
+            Promotion.answer(commit, head, gate.green?, descends, [gate.why, descends ? nil : not_forward].compact)
+          end
+
+          def not_forward = "the commit is not a fast-forward of the lane, or not on #{source}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/promotion/watch.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "candidates"
+require_relative "../../git"
+
+module Hecks
+  module Adapters
+    module Codebase
+      module Promotion
+        # How long a lane has stood behind the lane it follows, against what its `Lane` row allows.
+        #
+        # It reads the remote and the clock and answers hours as value objects. It does not judge
+        # them: the policies of `PromotionRun` fault a lane that is late, and the fault files a
+        # finding. A lane whose row allows no lag is never late.
+        class Watch
+          SECONDS_PER_HOUR = 3600
+
+          # @param held [Hash] the `PromotionRun` record: `lane`
+          # @param tree [Tree] the checkout, already known to be one
+          def initialize(held, tree)
+            @lane_name = Promotion.plain(held[:lane])
+            @lane = Promotion.row(@lane_name)
+            @where = tree.root
+            @repo = Promotion.git || Git.new
+          end
+
+          # @return [Hash{Symbol => Hash}] `lane_known`, `behind_hours`, `limit_hours`, `promoted`
+          #   and the `reason`, as value objects
+          def facts
+            return Promotion.unknown(@lane_name) unless @lane && !source.empty?
+
+            fetch
+            Promotion.watched(behind, limit, late? ? lateness : "#{name} is on time: #{behind}h behind, #{limit}h allowed")
+          end
+
+          private
+
+          def name = @lane["name"]
+
+          def source = @lane["follows"].to_s
+
+          def limit = @lane["alert_after"].to_i
+
+          def late? = behind > limit
+
+          def fetch
+            @repo.capture("fetch", "origin", source, chdir: @where)
+            @repo.capture("fetch", "origin", name, chdir: @where)
+          end
+
+          # Whole hours since the oldest commit the followed lane has and this lane lacks.
+          def behind
+            @behind ||= limit.zero? ? 0 : hours_since(oldest_unpromoted)
+          end
+
+          def oldest_unpromoted
+            held = @repo.remote_head("refs/heads/#{name}", chdir: @where)
+            @repo.oldest_commit_time(held && "origin/#{name}", "origin/#{source}", chdir: @where)
+          end
+
+          def hours_since(time) = time ? (Promotion.now.to_i - time) / SECONDS_PER_HOUR : 0
+
+          def lateness
+            "#{name} has stood #{behind}h behind #{source} (its Lane row allows #{limit}h): #{checks_on_source}"
+          end
+
+          # Tells a lane that is merely waiting on CI from one whose promotion is stuck: a certified
+          # commit the lane has not reached means the promotion should have run, whatever the
+          # head of the followed lane is doing.
+          def checks_on_source
+            head = @repo.remote_head("refs/heads/#{source}", chdir: @where)
+            candidates = Candidates.new(@repo, @where, head, @repo.remote_head("refs/heads/#{name}", chdir: @where))
+            certified = candidates.newest_certified
+            return "every required check passed on #{certified[0, 7]}, so a promotion should have run" if certified
+
+            why = candidates.gate(head).why
+            why.empty? ? "#{head[0, 7]} passed every required check but is not a fast-forward of #{name}" : why
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/promotion.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+require_relative "tree"
+require_relative "promotion/standing"
+require_relative "promotion/move"
+require_relative "promotion/watch"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `PromotionRun` asks of the working tree and the remote: the facts a
+      # promotion is judged by, and the move itself once it is accepted.
+      #
+      # The rules are not here. `Standing` only reports where things stand (which lane, where its
+      # head is, where each `RequiredCheck` stands against the commit) and the givens of
+      # `PromotionRun.Accept` decide. `Move` carries it out: a fast-forward of the lane and, when
+      # the `Lane` row says the lane `feeds` a tag, a forward-only move of that tag. Unconfirmed it
+      # names the move and makes none.
+      module Promotion
+        # Every operation this family carries out.
+        OPERATIONS = %w[promote watch].freeze
+
+        class << self
+          # @return [Git, nil] reads and moves refs; a `Git` when nil. A spec replaces it.
+          attr_accessor :git
+
+          # @return [#states, nil] reports where each check stands against a commit; `GithubChecks`
+          #   when nil. A spec replaces it, so nothing asks GitHub.
+          attr_accessor :checks
+
+          # @return [#call, nil] answers the time now; the system clock when nil. A spec sets it.
+          attr_accessor :clock
+
+          # @return [Time] the time now
+          def now = (clock || -> { Time.now }).call
+        end
+
+        module_function
+
+        # The facts of a promotion or of a watch, answered without judging them.
+        #
+        # @param held [Hash] the `PromotionRun` record: `operation`, `lane`, and `commit` when named
+        # @param tree [Tree] the checkout, already known to be one
+        # @return [Hash{Symbol => Hash}] for a promotion: `lane_known`, `green`, `descends`,
+        #   `commit`, `head` and the `reason` they were not all true; for a watch: `lane_known`,
+        #   `behind_hours`, `limit_hours` and the `reason`; all as value objects
+        def facts(held, tree)
+          watching = plain(held[:operation]) == "watch"
+          (watching ? Watch : Standing).new(held, tree).facts
+        end
+
+        # The facts of a tree that is not a checkout: placeholders that satisfy the value objects,
+        # so the checkout rule is the one that refuses.
+        #
+        # @return [Hash{Symbol => Hash}] every fact a promotion is judged by, none of them true
+        def no_facts = unknown("none", "needs a hecks checkout: hecks.gemspec stands beside lib/")
+
+        # Carries out an accepted promotion.
+        #
+        # @param operation [String] `promote`
+        # @param held [Hash] the `PromotionRun` record's fields: `lane`, `commit`, `head`, `confirm`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused; the move goes through the `Git` adapter
+        # @return [Hash{Symbol => Hash}] `report:` what was, or would be, moved, and `promoted:`
+        #   whether the remote was changed
+        # @raise [ConsoleCapture::Failure] when the remote refuses the move
+        def call(operation, held, tree, shell: nil)
+          _ = [operation, shell]
+          Move.new(held, tree).carry_out
+        end
+
+        # @param name [String] a lane's name
+        # @return [Hash{String => String}, nil] the `Lane` row of that name
+        def row(name) = Hecks::Vocabulary.rows("Lane").find { |lane| lane["name"] == name }
+
+        # @param commit [String] the commit to move onto
+        # @param head [String, nil] where the lane stands, nil when it does not exist yet
+        # @param green [Boolean] whether every required check passed
+        # @param descends [Boolean] whether the move is a fast-forward from the followed lane
+        # @param reasons [Array<String>] why the facts are not all true
+        # @return [Hash{Symbol => Hash}] the facts, as value objects
+        def answer(commit, head, green, descends, reasons)
+          { lane_known: { value: true }, green: { value: green }, descends: { value: descends },
+            commit: { value: commit }, head: { value: head || "none" },
+            reason: { value: reasons.reject { |why| why.to_s.empty? }.join("; ") } }
+        end
+
+        # @param behind [Integer] whole hours the lane has stood behind the lane it follows
+        # @param limit [Integer] whole hours its `Lane` row allows
+        # @param reason [String] what the watch found
+        # @return [Hash{Symbol => Hash}] the facts of a watch, as value objects
+        def watched(behind, limit, reason)
+          { lane_known: { value: true }, behind_hours: { value: behind }, limit_hours: { value: limit },
+            promoted: { value: false }, reason: { value: reason } }
+        end
+
+        # @param lane [String] the lane that was asked for
+        # @param why [String, nil] what to say instead of the default
+        # @return [Hash{Symbol => Hash}] facts none of which is true
+        def unknown(lane, why = nil)
+          { lane_known: { value: false }, green: { value: false }, descends: { value: false },
+            commit: { value: "none" }, head: { value: "none" }, behind_hours: { value: 0 },
+            limit_hours: { value: 0 }, promoted: { value: false },
+            reason: { value: why || "#{lane.inspect} is not a Lane row that follows another lane" } }
+        end
+
+        # @return [Hash{Symbol => Hash}] what a finished move reports
+        def outcome(text, promoted) = { report: { value: text }, promoted: { value: promoted } }
+
+        def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/publishing.rb

@@ -45,7 +45,7 @@ module Hecks
         def no_facts(operation)
           none = { value: "none" }
           { operation: { value: operation }, version: { value: "0.0.0" }, client_version: { value: "0.0.0" },
-            ir_version: { value: "0.0.0" }, ships_from: { path: "none" }, branch: none, head: none,
+            ir_version: { value: "0.0.0" }, ships_from: { path: "none" }, branch: none, head: none, release_lane: none,
             tag_state: none, on_origin: { value: false }, clean: { value: false }, changelog: { value: false } }
         end
 
@@ -80,19 +80,26 @@ module Hecks
           err = StringIO.new
           runner = release(args, tree, commands, out, err)
           status = runner.call
-          text = [out.string, err.string].map(&:strip).reject(&:empty?).join("\n")
+          text = transcript(out, err)
           raise ConsoleCapture::Failure, text if !status.zero? && runner.steps.empty?
 
-          outcome(text, args, tagged: runner.steps.include?(:tagged), published: runner.steps.include?(:gem),
-                              verified: runner.verified, succeeded: status.zero?)
+          outcome(text, args, **steps_taken(runner, status))
+        end
+
+        # @return [String] what the release printed to either stream, trimmed
+        def transcript(out, err)
+          [out, err].map { |stream| stream.string.strip }.reject(&:empty?).join("\n")
+        end
+
+        # @return [Hash] which steps the release really carried out, and whether it ended well
+        def steps_taken(runner, status)
+          { tagged: runner.steps.include?(:tagged), published: runner.steps.include?(:gem),
+            verified: runner.verified, succeeded: status.zero? }
         end
 
         # @return [Hecks::Release::Runner] the release, over the facts the run was cleared by
         def release(args, tree, commands, out, err)
-          flag = ->(name) { args[name] == true }
-          options = Release::Runner::Options.new(dry_run: args[:confirm] != true, gem_only: flag.call(:gem_only),
-                                                 npm_only: flag.call(:npm_only), npm_local: flag.call(:npm_local),
-                                                 no_wait: flag.call(:no_wait), yes: true)
+          options = runner_options(args)
           facts = Release::Runner::Preflight::Facts.new(version: args[:version], sha: args[:head])
           Release::Runner.new(root: tree.root, options: options, commands: commands, input: StringIO.new, out: out,
                               err: err, facts: facts, **(Publishing.release_options || {}))
@@ -100,6 +107,15 @@ module Hecks
           raise ConsoleCapture::Failure, e.message
         end
 
+        # @return [Hecks::Release::Runner::Options] the release's switches: a dry run unless
+        #   confirmed
+        def runner_options(args)
+          flag = ->(name) { args[name] == true }
+          Release::Runner::Options.new(dry_run: args[:confirm] != true, gem_only: flag.call(:gem_only),
+                                       npm_only: flag.call(:npm_only), npm_local: flag.call(:npm_local),
+                                       no_wait: flag.call(:no_wait), yes: true)
+        end
+
         # Pushes the gem alone, or builds it and deletes it again when unconfirmed.
         #
         # @param args [Hash] the record's plain fields
@@ -130,11 +146,14 @@ module Hecks
           raise ConsoleCapture::Failure, e.message
         end
 
+        # @param steps [Hash] `tagged`, `published` and `verified`, and `succeeded` (true when
+        #   absent)
         # @return [Hash] the answer the journal records: a report, what was done, and the release
-        def outcome(text, args, tagged:, published:, verified:, succeeded: true)
-          { report: { value: text }, tagged: { value: tagged }, published: { value: published },
-            verified: { value: verified }, succeeded: { value: succeeded }, version: { value: args[:version] },
-            ir_version: { value: args[:ir_version] }, ships_from: args[:ships_from] }
+        def outcome(text, args, **steps)
+          { report: { value: text }, tagged: { value: steps[:tagged] }, published: { value: steps[:published] },
+            verified: { value: steps[:verified] }, succeeded: { value: steps.fetch(:succeeded, true) },
+            version: { value: args[:version] }, ir_version: { value: args[:ir_version] },
+            ships_from: args[:ships_from] }
         end
       end
     end

data/lib/hecks/hecks/adapters/codebase/regeneration.rb

@@ -16,7 +16,7 @@ module Hecks
       # files reports drift and writes only when it is confirmed.
       module Regeneration
         # Every operation this family carries out.
-        OPERATIONS = %w[regenerate_corpus project_ci_gates project_tools_doc decide_ci_gate].freeze
+        OPERATIONS = %w[regenerate_corpus project_ci_gates project_lanes project_tools_doc decide_ci_gate].freeze
 
         # How many lines of a script's output a refusal keeps.
         KEPT_LINES = 60
@@ -33,13 +33,35 @@ module Hecks
         # @raise [ConsoleCapture::Failure] with the difference, when a check finds drift, or with
         #   what the script printed when it ends badly
         def call(operation, held, tree, shell: nil)
-          flag = ->(name) { (held[name].is_a?(Hash) ? held[name][:value] : held[name]) == true }
-          check = flag.call(:check) || !flag.call(:confirm)
+          check = check_only?(held)
           child = RubyChild.new(tree)
-          return project_ci_gates(child, check) if operation == "project_ci_gates"
-          return project_tools_doc(child, check) if operation == "project_tools_doc"
-          return decide_ci_gate(child, held) if operation == "decide_ci_gate"
+          case operation
+          when "project_ci_gates" then project_ci_gates(child, check)
+          when "project_lanes" then project_lanes(child, check, set?(held, :live), set?(held, :confirm))
+          when "project_tools_doc" then project_tools_doc(child, check)
+          when "decide_ci_gate" then decide_ci_gate(child, held)
+          else regenerate(child, check)
+          end
+        end
+
+        # @param held [Hash] the record's fields: `check`, `confirm`
+        # @return [Boolean] whether the run only compares: asked for, or not confirmed
+        def check_only?(held)
+          set?(held, :check) || !set?(held, :confirm)
+        end
 
+        # @param held [Hash] the record's fields
+        # @param name [Symbol] a switch of the record
+        # @return [Boolean] whether the switch was given as true
+        def set?(held, name)
+          (held[name].is_a?(Hash) ? held[name][:value] : held[name]) == true
+        end
+
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare
+        # @return [String] how many domains were checked or regenerated
+        # @raise [ConsoleCapture::Failure] with the difference, or with what the script printed
+        def regenerate(child, check)
           result = child.capture("regen_codegen_domains", *("--check" if check))
           raise ConsoleCapture::Failure, refusal(result) unless result.ok?
 
@@ -54,6 +76,21 @@ module Hecks
           child.answer("project_ci_gates", *("--check" if check))
         end
 
+        # Projects the `Lane` rows, or with `live` compares GitHub's rulesets with them. Only a live
+        # run that is confirmed changes GitHub, so without `confirm` a live run is a comparison.
+        #
+        # @param child [RubyChild] the checkout's tool runner
+        # @param check [Boolean] whether to only compare the files
+        # @param live [Boolean] whether to compare, or with `confirm` update, GitHub's rulesets
+        # @param confirm [Boolean] whether a live run may change GitHub
+        # @return [String] what the tool printed
+        # @raise [ConsoleCapture::Failure] with the stale files or differing rulesets
+        def project_lanes(child, check, live, confirm)
+          return child.answer("project_lanes", "--live", *("--confirm" if confirm)) if live
+
+          child.answer("project_lanes", *("--check" if check))
+        end
+
         # @param child [RubyChild] the checkout's tool runner
         # @param check [Boolean] whether to only compare
         # @return [String] what the tool printed

data/lib/hecks/hecks/adapters/codebase/release_facts.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "hecks/release/runner"
+require "hecks/release/lane"
 require_relative "tree"
 require_relative "../console_capture"
 
@@ -11,7 +12,8 @@ module Hecks
       # The facts a release is judged by, read from git and the checkout's files and judged by
       # nothing here: the rules are the givens of the `Clear` command of `PublishingRun`.
       #
-      # It reads the branch, whether `HEAD` is `origin/main` (after a fetch), whether the tree is
+      # It reads the branch, the lane a release is cut from (the `Lane` row that feeds a tag),
+      # whether `HEAD` is that lane's `origin/` branch (after a fetch), whether the tree is
       # clean, the gem's version and the client package's, whether the changelog has a heading for
       # the version, and where a tag for the version already points. Nothing is changed but the
       # remote-tracking refs a fetch updates.
@@ -49,13 +51,22 @@ module Hecks
         private
 
         def git_facts(version)
+          fetch_origin!
+          head = read("rev-parse", "HEAD")
+          lane_facts(head).merge(clean:     flag(read("status", "--porcelain").empty?),
+                                 tag_state: word(tag_state("v#{version}", head)))
+        end
+
+        def fetch_origin!
           fetch = @git.capture("fetch", "origin")
           raise ConsoleCapture::Failure, "git fetch origin failed (#{fetch.stderr.strip})" unless fetch.success?
+        end
 
-          head = read("rev-parse", "HEAD")
-          { branch: word(read("rev-parse", "--abbrev-ref", "HEAD")), head: word(head),
-            on_origin: flag(head == read("rev-parse", "origin/main")),
-            clean: flag(read("status", "--porcelain").empty?), tag_state: word(tag_state("v#{version}", head)) }
+        # Where the checkout stands against the lane a release is cut from.
+        def lane_facts(head)
+          lane = Release::Lane.release
+          { branch: word(read("rev-parse", "--abbrev-ref", "HEAD")), head: word(head), release_lane: word(lane),
+            on_origin: flag(head == read("rev-parse", "origin/#{lane}")) }
         end
 
         def tag_state(tag, head)

data/lib/hecks/hecks/adapters/codebase/source_tree.rb

@@ -11,6 +11,7 @@ require_relative "codemods"
 require_relative "test_suite"
 require_relative "corpus_tasks"
 require_relative "publishing"
+require_relative "promotion"
 require_relative "../git"
 
 module Hecks
@@ -47,6 +48,7 @@ module Hecks
       def examine(**held)
         answer = { checkout: { value: tree.checkout? } }
         operation = plain(held[:operation])
+        return answer.merge(promotion_facts(held)) if Codebase::Promotion::OPERATIONS.include?(operation)
         return answer unless Codebase::Publishing::OPERATIONS.include?(operation)
 
         facts = tree.checkout? ? Git.new.survey(**held) : Codebase::Publishing.no_facts(operation)
@@ -180,9 +182,15 @@ module Hecks
       # The task families, each carrying out the operations it lists.
       FAMILIES = [Codebase::Language, Codebase::KernelTables, Codebase::Conformance, Codebase::Regeneration,
                   Codebase::Gate, Codebase::Style, Codebase::Codemods, Codebase::TestSuite,
-                  Codebase::CorpusTasks, Codebase::Publishing].freeze
+                  Codebase::CorpusTasks, Codebase::Publishing, Codebase::Promotion].freeze
       private_constant :FAMILIES
 
+      # The facts of a promotion or a watch, naming the operation so policies can tell them apart.
+      def promotion_facts(held)
+        facts = tree.checkout? ? Codebase::Promotion.facts(held, tree) : Codebase::Promotion.no_facts
+        { operation: held[:operation], alert_key: held[:alert_key] }.compact.merge(facts)
+      end
+
       def tree = Codebase::Tree.new
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument

data/lib/hecks/hecks/adapters/codebase/sqlite_fixture.rb

@@ -40,7 +40,7 @@ module Hecks
         def regenerate(confirm:)
           return rewrite if confirm
 
-          "dry run, would rewrite #{DIRECTORY}/ for #{STORES.join(', ')} through the real adapters " \
+          "dry run, would rewrite #{DIRECTORY}/ for #{STORES.join(", ")} through the real adapters " \
             "(#{installed}; add --confirm)"
         end
 

data/lib/hecks/hecks/adapters/codebase/style.rb

@@ -161,7 +161,7 @@ module Hecks
         # @raise [ConsoleCapture::Failure] when a path begins with `-`
         def after_separator(paths)
           flagged = paths.select { |path| path.start_with?("-") }
-          raise ConsoleCapture::Failure, "paths may not begin with '-': #{flagged.join(', ')}" if flagged.any?
+          raise ConsoleCapture::Failure, "paths may not begin with '-': #{flagged.join(", ")}" if flagged.any?
 
           ["--", *paths]
         end

data/lib/hecks/hecks/adapters/codebase/test_runner.rb

@@ -34,17 +34,23 @@ module Hecks
           path = File.expand_path(file, @tree.root)
           raise ConsoleCapture::Failure, "no such spec file #{file}" unless File.file?(path)
 
+          report = run_example(path, example)
+          raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
+
+          report
+        end
+
+        private
+
+        # What the runner printed for the example, when it passed.
+        def run_example(path, example)
           out = StringIO.new
           status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
           raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
-          out.string.strip.tap do |report|
-            raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
-          end
+          out.string.strip
         end
 
-        private
-
         def runner
           return self.class.runner if self.class.runner