hecks 3.4.2 → 3.6.0

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

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