hecks 3.5.0 → 3.7.0

data/lib/hecks/grammar.rb

@@ -3,6 +3,7 @@ require "json"
 # Loads the whole framework on purpose; nothing the entry point loads
 # requires this file back, so the require is acyclic.
 require_relative "../hecks"
+require_relative "grammar/operators"
 
 module Hecks
   # The sublanguage grammar domains (grammar/*.bluebook) and the one boot path
@@ -14,6 +15,14 @@ module Hecks
     DIR    = File.expand_path("grammar", __dir__)
     LEDGER = File.join(DIR, "expression_operators.json")
 
+    # The ports and adapters a chapter needs loaded before its own bluebook, relative to the
+    # repository root.
+    CHAPTER_PREREQUISITES = %w[lib/hecks/ports/persistence.port lib/hecks/ports/extraction.port
+                               lib/hecks/adapters/driven/memory.adapter
+                               lib/hecks/adapters/driven/prism.adapter].freeze
+
+    extend Operators
+
     module_function
 
     # Boots the expression chapter and replays the admission ledger through
@@ -25,27 +34,36 @@ module Hecks
     #   own domain rules
     def expression
       registry = Runtime::Registry.new
-      root = File.expand_path("../..", __dir__)
-      Hecks.with_registry(registry) do
-        Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
-        Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
-        Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
-        Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
-        Kernel.load(File.join(DIR, "expression.bluebook"))
-      end
+      load_chapter(registry, File.join(DIR, "expression.bluebook"))
       dispatcher = Runtime::Dispatcher.new(registry)
+      JSON.parse(File.read(LEDGER)).fetch("steps").each { |step| replay_step(dispatcher, step) }
+      dispatcher
+    end
 
-      JSON.parse(File.read(LEDGER)).fetch("steps").each do |step|
-        args = symbolize(step.fetch("args"))
-        begin
-          dispatcher.dispatch_flat(step.fetch("verb"), args)
-        rescue *Runtime::DOMAIN_REFUSALS => e
-          raise Runtime::WiringError,
-                "the admission ledger refused at #{step['verb']} #{step['args']} — #{e.message}"
-        end
+    # Loads a chapter's bluebook into a registry, after the ports and adapters it needs.
+    #
+    # @param registry [Runtime::Registry] the registry the chapter loads into
+    # @param chapter [String] the path of the chapter's `.bluebook`
+    # @return [void]
+    def load_chapter(registry, chapter)
+      root = File.expand_path("../..", __dir__)
+      Hecks.with_registry(registry) do
+        CHAPTER_PREREQUISITES.each { |file| Kernel.load(File.join(root, file)) }
+        Kernel.load(chapter)
       end
+    end
 
-      dispatcher
+    # Dispatches one admission-ledger step.
+    #
+    # @param dispatcher [Runtime::Dispatcher] the dispatcher bound to the expression chapter
+    # @param step [Hash] a ledger step, with `"verb"` and `"args"`
+    # @return [void]
+    # @raise [Runtime::WiringError] if the chapter's own domain rules refuse the step
+    def replay_step(dispatcher, step)
+      dispatcher.dispatch_flat(step.fetch("verb"), symbolize(step.fetch("args")))
+    rescue *Runtime::DOMAIN_REFUSALS => e
+      raise Runtime::WiringError,
+            "the admission ledger refused at #{step["verb"]} #{step["args"]} — #{e.message}"
     end
 
     # Reads every admitted operator from the ledger's replayed chapter.
@@ -56,11 +74,15 @@ module Hecks
     #   `:category`, `:precedence`, `:arity`, and `:renderings` (an Array of
     #   `{target:, form:}` Hashes)
     def admitted_operators(dispatcher = expression)
-      records(dispatcher, "Operator").select { |op| op[:status] == "admitted" }.map do |op|
-        { symbol: op[:symbol].value, category: op[:category].value,
-          precedence: op[:precedence].value, arity: op[:arity].value,
-          renderings: Array(op[:renderings]).map { |r| { target: r[:target], form: r[:form] } } }
-      end
+      records(dispatcher, "Operator").select { |op| op[:status] == "admitted" }.map { |op| operator_row(op) }
+    end
+
+    # @param operator [Runtime::Instance] an admitted `Operator` record
+    # @return [Hash] its symbol, category, precedence, arity and renderings
+    def operator_row(operator)
+      { symbol: operator[:symbol].value, category: operator[:category].value,
+        precedence: operator[:precedence].value, arity: operator[:arity].value,
+        renderings: Array(operator[:renderings]).map { |r| { target: r[:target], form: r[:form] } } }
     end
 
     # Reads every admitted normalisation rule from the ledger's replayed
@@ -74,11 +96,15 @@ module Hecks
       records(dispatcher, "Normalisation")
         .select { |rule| rule[:status] == "admitted" }
         .sort_by { |rule| rule[:position].value }
-        .map do |rule|
-          { strategy: rule[:strategy].value, source_token: rule[:source_token].value,
-            replacement: rule[:replacement].value, boundary: rule[:boundary].value,
-            position: rule[:position].value }
-        end
+        .map { |rule| normalisation_row(rule) }
+    end
+
+    # @param rule [Runtime::Instance] an admitted `Normalisation` record
+    # @return [Hash] its strategy, source token, replacement, boundary and position
+    def normalisation_row(rule)
+      { strategy: rule[:strategy].value, source_token: rule[:source_token].value,
+        replacement: rule[:replacement].value, boundary: rule[:boundary].value,
+        position: rule[:position].value }
     end
 
     # Reads every record of one aggregate from the expression chapter's own
@@ -95,105 +121,6 @@ module Hecks
       registry.repository("Expression", aggregate).all
     end
 
-    # The operators the language's own guards and invariants (Bluebook, World and
-    # the grammar chapters) evaluate through. Retiring one would leave the
-    # language unable to read its own rules, so callers refuse it by name.
-    #
-    # @return [Hash{String => Array<String>}] each self-bearing operator symbol
-    #   mapped to the `"Chapter Aggregate.command"`/`"Chapter Aggregate::ValueObject"`
-    #   sites that use it
-    def self_bearing_operators
-      sites = Hash.new { |h, k| h[k] = [] }
-
-      chapters = Bluebook::MetaValidator.grammar_registry
-                                        .then { |reg| %w[Bluebook World].map { |name| reg.bluebook(name) } }
-      chapters += grammar_chapters
-
-      chapters.compact.each do |chapter|
-        chapter.aggregates.each do |aggregate|
-          aggregate.commands.each do |command|
-            command.givens.each do |given|
-              operators_in(given.canonical).each do |symbol|
-                sites[symbol] << "#{chapter.name} #{aggregate.name}.#{command.hecks_name}"
-              end
-            end
-          end
-          aggregate.value_objects.each do |value_object|
-            value_object.invariants.each do |invariant|
-              operators_in(invariant.canonical).each do |symbol|
-                sites[symbol] << "#{chapter.name} #{aggregate.name}::#{value_object.hecks_name}"
-              end
-            end
-          end
-        end
-      end
-
-      sites.transform_values(&:uniq)
-    end
-
-    # Every grammar/*.bluebook chapter, each booted alone in a scratch registry.
-    #
-    # @return [Array<Class>] each grammar chapter, booted alone in its own scratch
-    #   registry
-    def grammar_chapters
-      Dir[File.join(DIR, "*.bluebook")].map do |chapter|
-        registry = Runtime::Registry.new
-        root = File.expand_path("../..", __dir__)
-        Hecks.with_registry(registry) do
-          Kernel.load(File.join(root, "lib/hecks/ports/persistence.port"))
-          Kernel.load(File.join(root, "lib/hecks/ports/extraction.port"))
-          Kernel.load(File.join(root, "lib/hecks/adapters/driven/memory.adapter"))
-          Kernel.load(File.join(root, "lib/hecks/adapters/driven/prism.adapter"))
-          Kernel.load(chapter)
-        end
-        registry.bluebooks.values.first
-      end
-    end
-
-    # Which admitted operators one canonical text evaluates through, found by
-    # walking the evaluator's own parse.
-    #
-    # @param canonical [String] canonical expression text to parse
-    # @return [Array<String>] operator symbols the expression evaluates through, or
-    #   `[]` when `canonical` fails to parse
-    def operators_in(canonical)
-      evaluator = Bluebook::Expression::Evaluator
-      begin
-        node = evaluator.parse(canonical)
-      rescue StandardError
-        return []
-      end
-      walk_operators(node, evaluator).uniq
-    end
-
-    # One case over the closed set of AST node types, kept together so the whole
-    # operator vocabulary reads in one place.
-    # @param node [Object] an evaluator/resolver AST node, or a Struct fallback
-    # @param evaluator [Module] `Bluebook::Expression::Evaluator`, passed through
-    #   so nested calls don't re-resolve the constant
-    # @return [Array<String>] operator symbols found in `node` and its children
-    # rubocop:disable-next Metrics/AbcSize
-    def walk_operators(node, evaluator)
-      resolver = Bluebook::Expression::Resolver
-      case node
-      when evaluator::Or  then ["||"] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
-      when evaluator::And then ["&&"] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
-      when evaluator::Not then ["!"] + walk_operators(node.node, evaluator)
-      when evaluator::Compare
-        [node.operator.symbol] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
-      when evaluator::Include
-        [".include?"] + walk_operators(node.haystack, evaluator) + walk_operators(node.needle, evaluator)
-      when evaluator::Resolve then walk_operators(node.expr, evaluator)
-      when resolver::Addition then ["+"] + walk_operators(node.left, evaluator) + walk_operators(node.right, evaluator)
-      when resolver::Modulo   then [".modulo"] + walk_operators(node.receiver,
-                                                                evaluator) + walk_operators(node.divisor, evaluator)
-      when Struct
-        node.members.flat_map { |member| walk_operators(node[member], evaluator) }
-      else
-        []
-      end
-    end
-
     # Deep-symbolizes a JSON-decoded value's Hash keys.
     #
     # @param value [Object] a Hash, Array, or scalar decoded from JSON

data/lib/hecks/hecks/adapters/bluebook_report.rb

@@ -50,21 +50,21 @@ module Hecks
       end
 
       def row(name, old, new)
-        return mark(name, "ADDED #{new['version']}") if old.nil?
-        return mark(name, "REMOVED (was #{old['version']})") if new.nil?
+        return mark(name, "ADDED #{new["version"]}") if old.nil?
+        return mark(name, "REMOVED (was #{old["version"]})") if new.nil?
         return reversioned(name, old, new) if old["version"] != new["version"]
         return same_version_changed(name, old, new) if old["digest"] != new["digest"]
 
-        format(ROW, name, "#{new['version']}   unchanged")
+        format(ROW, name, "#{new["version"]}   unchanged")
       end
 
       def same_version_changed(name, old, new)
-        mark(name, "#{new['version']}   SAME VERSION, DIFFERENT CONTENT (digest #{old['digest'][0, 8]} -> " \
-                   "#{new['digest'][0, 8]}); a vendored copy was edited or re-tagged")
+        mark(name, "#{new["version"]}   SAME VERSION, DIFFERENT CONTENT (digest #{old["digest"][0, 8]} -> " \
+                   "#{new["digest"][0, 8]}); a vendored copy was edited or re-tagged")
       end
 
       def reversioned(name, old, new)
-        line = "#{old['version']} -> #{new['version']}"
+        line = "#{old["version"]} -> #{new["version"]}"
         if old["shape"] != new["shape"]
           line += "   shape #{shape(old)} -> #{shape(new)}   NEW ERA (its translation edge must already be in " \
                   "bluebook/translations/)"

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

@@ -37,7 +37,7 @@ module Hecks
           child = RubyChild.new(tree)
           return child.answer(SCRIPTS.fetch(operation)) if confirm == true
 
-          "dry run, nothing kept (add --confirm to rewrite):\n#{child.answer(SCRIPTS.fetch(operation), '--dry-run')}"
+          "dry run, nothing kept (add --confirm to rewrite):\n#{child.answer(SCRIPTS.fetch(operation), "--dry-run")}"
         end
       end
     end

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

@@ -131,8 +131,7 @@ module Hecks
         def coverage(tree)
           modules = Corpus.generated_modules(root: tree.root)
           pending = Corpus::RUST_COVERAGE_PENDING
-          unknown = pending.keys - modules
-          raise ConsoleCapture::Failure, "pending names #{unknown.join(', ')}, with no generated module" if unknown.any?
+          refuse_unknown_pending(pending.keys - modules)
 
           lines, problems = judge(modules, pending, coverage_results(modules, tree))
           raise ConsoleCapture::Failure, [*lines, "", *problems].join("\n") if problems.any?
@@ -140,6 +139,12 @@ module Hecks
           [*lines, "#{modules.size} generated modules checked"].join("\n")
         end
 
+        # @param unknown [Array<String>] the pending names that match no generated module
+        # @raise [ConsoleCapture::Failure] when there are any
+        def refuse_unknown_pending(unknown)
+          raise ConsoleCapture::Failure, "pending names #{unknown.join(", ")}, with no generated module" if unknown.any?
+        end
+
         # @param modules [Array<String>] the generated modules
         # @param pending [Hash{String => String}] the modules known to fail, and why
         # @param results [Hash{String => Array}] each module's `[passed, output]`
@@ -148,17 +153,26 @@ module Hecks
           problems = []
           lines = modules.map do |name|
             passed, output = results.fetch(name)
-            if pending.key?(name)
-              problems << "#{name} passes now - delete it from Hecks::Corpus::RUST_COVERAGE_PENDING" if passed
-              "#{name}: pending (#{passed ? 'NOW PASSES' : 'still fails'}) - #{pending[name]}"
-            else
-              problems << "#{name} failed:\n#{output}" unless passed
-              "#{name}: #{passed ? 'ok' : 'FAILED'}"
-            end
+            problem, line = pending.key?(name) ? pending_verdict(name, passed, pending[name]) : verdict(name, passed, output)
+            problems << problem if problem
+            line
           end
           [lines, problems]
         end
 
+        # @return [Array(String, String)] the problem (nil when none) and the line for a module
+        #   known to fail
+        def pending_verdict(name, passed, why)
+          [("#{name} passes now - delete it from Hecks::Corpus::RUST_COVERAGE_PENDING" if passed),
+           "#{name}: pending (#{passed ? "NOW PASSES" : "still fails"}) - #{why}"]
+        end
+
+        # @return [Array(String, String)] the problem (nil when none) and the line for a module
+        #   that must pass
+        def verdict(name, passed, output)
+          [("#{name} failed:\n#{output}" unless passed), "#{name}: #{passed ? "ok" : "FAILED"}"]
+        end
+
         # @param modules [Array<String>] the generated modules
         # @param tree [Tree] the checkout
         # @return [Hash{String => Array}] each module's `[passed, output]`

data/lib/hecks/hecks/adapters/codebase/language/edits.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Codebase
+      module Language
+        # The edits a word or argument operation makes to the syntax tables, through
+        # {Grammar::Evolve}.
+        module Edits
+          module_function
+
+          # Makes one edit to the syntax tables.
+          #
+          # @param operation [String] a word or argument operation
+          # @param args [Hash] the record's plain fields
+          # @return [void]
+          # @raise [Grammar::Evolve::Refusal] when the tables refuse the edit
+          def edit(operation, args)
+            case operation
+            when "propose" then propose(args)
+            when "rename" then rename(args)
+            when "propose_argument" then propose_argument(args)
+            when "admit", "deprecate", "retire" then set_status(operation, args)
+            else set_argument_status(operation, args)
+            end
+          end
+
+          # @param args [Hash] the record's plain fields
+          # @return [void]
+          def propose(args)
+            Grammar::Evolve.propose(word: args[:word], context: args[:context], body: args[:body] || "none",
+                                    inner: args[:inner] || "", opens: args[:opens] || "", fills: args[:fills] || "")
+          end
+
+          # @param args [Hash] the record's plain fields
+          # @return [void]
+          # @raise [Grammar::Evolve::Refusal] when no new name was given
+          def rename(args)
+            to = args[:new_name] or refuse("a rename goes somewhere: new_name=")
+            Grammar::Evolve.rename(word: args[:word], context: args[:context], to: to)
+          end
+
+          # @param args [Hash] the record's plain fields
+          # @return [void]
+          def propose_argument(args)
+            Grammar::Evolve.propose_argument(keyword: args[:word], context: args[:context], kind: args[:kind],
+                                             required: args[:required] || "false", at: args[:at] || "",
+                                             named: args[:named] || "", fills: args[:fills] || "",
+                                             pairs_shape: args[:pairs_shape])
+          end
+
+          # @param operation [String] `admit`, `deprecate` or `retire`
+          # @param args [Hash] the record's plain fields
+          # @return [void]
+          def set_status(operation, args)
+            Grammar::Evolve.set_status(word: args[:word], context: args[:context], to: STATUSES.fetch(operation))
+          end
+
+          # @param operation [String] the argument form of `admit`, `deprecate` or `retire`
+          # @param args [Hash] the record's plain fields
+          # @return [void]
+          def set_argument_status(operation, args)
+            Grammar::Evolve.set_argument_status(keyword: args[:word], context: args[:context],
+                                                to: STATUSES.fetch(operation), at: args[:at] || "",
+                                                named: args[:named] || "")
+          end
+
+          # @param message [String] why the edit cannot be made
+          # @raise [Grammar::Evolve::Refusal] always
+          def refuse(message) = raise(Grammar::Evolve::Refusal, message)
+        end
+      end
+    end
+  end
+end

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

@@ -83,12 +83,21 @@ module Hecks
           rows = Grammar::Evolve.keyword_rows
           moving = rows.reject { |row| row[:status] == "admitted" }
           renamed = rows.reject { |row| row[:was].to_s.empty? }
-          lines = ["#{rows.size} keyword rows; #{moving.size} not simply admitted; #{renamed.size} renamed"]
-          lines += moving.map { |row| "  #{row[:status].ljust(10)} #{row[:context]}.#{row[:word]}" }
-          lines += renamed.map { |row| "  renamed    #{row[:context]}.#{row[:word]} (was #{row[:was]})" }
-          lines.join("\n")
+          [summary_line(rows, moving, renamed),
+           *moving.map { |row| moving_line(row) }, *renamed.map { |row| renamed_line(row) }].join("\n")
         end
 
+        # The count line that heads the report.
+        def summary_line(rows, moving, renamed)
+          "#{rows.size} keyword rows; #{moving.size} not simply admitted; #{renamed.size} renamed"
+        end
+
+        # The line for a row that is not simply admitted.
+        def moving_line(row) = "  #{row[:status].ljust(10)} #{row[:context]}.#{row[:word]}"
+
+        # The line for a row that carries a former name.
+        def renamed_line(row) = "  renamed    #{row[:context]}.#{row[:word]} (was #{row[:was]})"
+
         # @param operation [String] a projection's operation
         # @param args [Hash] the record's plain fields
         # @param tree [Tree] the checkout
@@ -110,7 +119,7 @@ module Hecks
         # @return [String] the rehearsed edit, or the confirmed edit's outcome
         # @raise [ConsoleCapture::Failure] when the language or a gate refuses
         def evolve(operation, args, tree, shell)
-          change = -> { edit(operation, args) }
+          change = -> { Edits.edit(operation, args) }
           return rehearse(change, tree) unless args[:confirm] == true
 
           guarded(operation, args, tree, shell, change)
@@ -147,17 +156,25 @@ module Hecks
           snapshots = paths.to_h { |path| [path, File.read(path)] }
           Grammar::Evolve.restore_on_raise(paths, &edit)
           regenerate(tree, shell)
-          gates = shell.capture("bundle", "exec", "rspec", *GATES, chdir: tree.root)
-          unless gates.ok?
-            snapshots.each { |path, text| File.write(path, text) }
-            raise ConsoleCapture::Failure,
-                  "RESTORED — the gates refused, and the failures are the checklist. Nothing was " \
-                  "changed.\n#{[gates.out, gates.err].join.strip}"
-          end
+          hold_gates(tree, shell, snapshots)
           ["#{args[:context]}.#{args[:word]} — the gates hold. Regenerated projections and the golden " \
            "are in the tree.", follow_up(operation, args)].compact.join("\n")
         end
 
+        # Runs the gates, and puts every file back from `snapshots` when one refuses.
+        #
+        # @param snapshots [Hash{String => String}] each file's text before the edit
+        # @raise [ConsoleCapture::Failure] when a gate refuses; nothing was changed
+        def hold_gates(tree, shell, snapshots)
+          gates = shell.capture("bundle", "exec", "rspec", *GATES, chdir: tree.root)
+          return if gates.ok?
+
+          snapshots.each { |path, text| File.write(path, text) }
+          raise ConsoleCapture::Failure,
+                "RESTORED — the gates refused, and the failures are the checklist. Nothing was " \
+                "changed.\n#{[gates.out, gates.err].join.strip}"
+        end
+
         # @param tree [Tree] the checkout
         # @param shell [#capture] starts the child process
         # @return [void]
@@ -174,67 +191,8 @@ module Hecks
 
           format(text, context: args[:context], new_name: args[:new_name], word: args[:word])
         end
-
-        # Makes one edit to the syntax tables.
-        #
-        # @param operation [String] a word or argument operation
-        # @param args [Hash] the record's plain fields
-        # @return [void]
-        # @raise [Grammar::Evolve::Refusal] when the tables refuse the edit
-        def edit(operation, args)
-          case operation
-          when "propose" then propose(args)
-          when "rename" then rename(args)
-          when "propose_argument" then propose_argument(args)
-          when "admit", "deprecate", "retire" then set_status(operation, args)
-          else set_argument_status(operation, args)
-          end
-        end
-
-        # @param args [Hash] the record's plain fields
-        # @return [void]
-        def propose(args)
-          Grammar::Evolve.propose(word: args[:word], context: args[:context], body: args[:body] || "none",
-                                  inner: args[:inner] || "", opens: args[:opens] || "", fills: args[:fills] || "")
-        end
-
-        # @param args [Hash] the record's plain fields
-        # @return [void]
-        # @raise [Grammar::Evolve::Refusal] when no new name was given
-        def rename(args)
-          to = args[:new_name] or refuse("a rename goes somewhere: new_name=")
-          Grammar::Evolve.rename(word: args[:word], context: args[:context], to: to)
-        end
-
-        # @param args [Hash] the record's plain fields
-        # @return [void]
-        def propose_argument(args)
-          Grammar::Evolve.propose_argument(keyword: args[:word], context: args[:context], kind: args[:kind],
-                                           required: args[:required] || "false", at: args[:at] || "",
-                                           named: args[:named] || "", fills: args[:fills] || "",
-                                           pairs_shape: args[:pairs_shape])
-        end
-
-        # @param operation [String] `admit`, `deprecate` or `retire`
-        # @param args [Hash] the record's plain fields
-        # @return [void]
-        def set_status(operation, args)
-          Grammar::Evolve.set_status(word: args[:word], context: args[:context], to: STATUSES.fetch(operation))
-        end
-
-        # @param operation [String] the argument form of `admit`, `deprecate` or `retire`
-        # @param args [Hash] the record's plain fields
-        # @return [void]
-        def set_argument_status(operation, args)
-          Grammar::Evolve.set_argument_status(keyword: args[:word], context: args[:context],
-                                              to: STATUSES.fetch(operation), at: args[:at] || "",
-                                              named: args[:named] || "")
-        end
-
-        # @param message [String] why the edit cannot be made
-        # @raise [Grammar::Evolve::Refusal] always
-        def refuse(message) = raise(Grammar::Evolve::Refusal, message)
       end
     end
   end
 end
+require_relative "language/edits"

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "gate"
+
+module Hecks
+  module Adapters
+    module Codebase
+      module Promotion
+        # The commits a lane could move onto, and which of them have been certified.
+        #
+        # A commit is certified when every `RequiredCheck` passed against that exact commit; the
+        # checks of its neighbours say nothing about it. Promotion is therefore a question about the
+        # whole stretch of the followed lane the promoted lane has not reached, not about whichever
+        # commit happened to finish last: when the newest commit is red or still running, an older
+        # one that passed is still worth promoting, and a promotion run that was dropped or
+        # beaten to the lane costs nothing, because the next one finds the same answer.
+        class Candidates
+          # How far back from the followed lane's head to look for a certified commit.
+          LIMIT = 25
+
+          # @param repo [#recent_commits, #ancestor?] the `Git` adapter
+          # @param where [String] a directory inside the repository
+          # @param source_head [String] where the followed lane stands
+          # @param head [String, nil] where the promoted lane stands, nil when it does not exist yet
+          def initialize(repo, where, source_head, head)
+            @repo = repo
+            @where = where
+            @source_head = source_head
+            @head = head
+          end
+
+          # @return [Array<String>] the commits the promoted lane lacks, newest first, each one a
+          #   fast-forward of the lane
+          def commits
+            @commits ||= @repo.recent_commits(@source_head, older: @head, limit: LIMIT, chdir: @where)
+                              .select { |commit| forward?(commit) }
+          end
+
+          # @return [String, nil] the newest commit every required check passed on, nil when none
+          #   did
+          def newest_certified = commits.find { |commit| gate(commit).green? }
+
+          # @param commit [String] a commit
+          # @return [Gate] where the required checks stand against it; asked once per commit
+          def gate(commit) = (@gates ||= {})[commit] ||= Gate.new(commit)
+
+          private
+
+          def forward?(commit) = @head.nil? || @repo.ancestor?(@head, commit, chdir: @where)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "hecks/vocabulary"
+require_relative "../../../../quality_control/adapters/github_checks"
+
+module Hecks
+  module Adapters
+    module Codebase
+      module Promotion
+        # Where every `RequiredCheck` of the Vocabulary chapter stands against one commit.
+        #
+        # It reports and does not decide: `Accept` holds the rule that a promotion needs every check
+        # green. A check that has not finished (or has not started) is told apart from one that
+        # failed, so the refusal can say whether to wait or to fix.
+        class Gate
+          # @param commit [String] the commit to read the checks of
+          def initialize(commit)
+            @commit = commit
+          end
+
+          # @return [Boolean] whether every required check passed
+          def green?
+            failed.empty? && waiting.empty?
+          end
+
+          # @return [String] what keeps the commit from being green: the checks that failed, then
+          #   those still to finish; empty when it is green
+          def why
+            [("failed: #{failed.join(", ")}" unless failed.empty?),
+             ("waiting on: #{waiting.join(", ")}" unless waiting.empty?)].compact.join("; ")
+          end
+
+          private
+
+          def failed = named(%i[failed])
+
+          def waiting = named(%i[pending missing])
+
+          def named(kinds) = states.select { |_, state| kinds.include?(state) }.keys
+
+          def states
+            @states ||= (Promotion.checks || GithubChecks.new).states(commit: @commit, names: names)
+          end
+
+          def names = Hecks::Vocabulary.rows("RequiredCheck").map { |check| check["name"] }
+        end
+      end
+    end
+  end
+end