hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/git_landing.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "git_worktrees"
+require_relative "git_main_pull"
 require_relative "git_landing/merger"
+require_relative "git_landing/tidy"
+require_relative "git_landing/rivals"
+require_relative "git_landing/finisher"
+require_relative "git_landing/lineup"
+require_relative "../../indifferent_key"
 
 module Hecks
   module Adapters
@@ -12,17 +18,24 @@ module Hecks
     # that holds uncommitted work or a branch with commits `main` lacks, so no unpushed work goes.
     class GitLanding
       include GitWorktrees
+      include GitMainPull
 
-      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      # Accepts the arguments every driven adapter is built with; only the registry and the
+      # overrides are kept.
       #
       # @param aggregate [Object, nil] unused
       # @param settings [Hash] unused
       # @param root [String, nil] unused
-      def initialize(aggregate: nil, settings: {}, root: nil)
+      # @param registry [Runtime::Registry, nil] where the started Work rows are read
+      # @param tune [Hash] overrides of the line's limits and collaborators (see `Lineup`)
+      def initialize(aggregate: nil, settings: {}, root: nil, registry: nil, **tune)
         @git = Git.new
+        @registry = registry
+        @tune = tune
       end
 
-      # Lands a worktree's branch onto another branch (local `main` by default).
+      # Lands a worktree's branch onto another branch (local `main` by default), then removes the
+      # linked worktree and branch it landed from when they hold nothing main lacks.
       #
       # @param held [Hash] the `Landing` record: `checkout` (a directory inside the worktree; the
       #   current directory when absent), `branch` (its checked-out branch when absent), `onto`
@@ -34,8 +47,45 @@ module Hecks
         onto = plain(held[:onto]) || "main"
         raise ConsoleCapture::Failure, "#{branch} is the branch to land onto" if branch == onto
 
-        refuse_unsaved(branch)
-        Merger.new(@git, @checkout, branch: branch, onto: onto).land
+        lineup.stand(branch, onto: onto, checkout: @checkout) { |note| land_alone(branch, onto, note) }
+      end
+
+      # Takes the front place in the line and lands every branch whose landing is waiting behind
+      # it, in ticket order, without giving the place up: each is rebased onto the moving `onto`,
+      # run through the quick gate and landed. One that conflicts, fails the gate or overlaps
+      # another started row's area is skipped with its reason, and its own waiting `land!` is told.
+      #
+      # @param held [Hash] the `Landing` record: `checkout` (any directory in the repository) and
+      #   `onto`
+      # @return [Hash{Symbol => Hash}] `outcome:` (`trained`), `checkout:`, `branch:` and `report:`
+      # @raise [ConsoleCapture::Failure] when the checkout is not a repository or the wait runs out
+      def convene(**held)
+        settle(held)
+        onto = plain(held[:onto]) || "main"
+        land = ->(checkout, branch, target) { land_for(checkout, branch, target) }
+        said = lineup.convoy(@git, @checkout, onto: onto, land: land)
+        { outcome: { value: "trained" }, checkout: { value: primary.path }, branch: { value: "train" }, report: { value: said } }
+      end
+
+      # Finishes a branch in one step: refuses unsaved work, rebases it onto `onto`, runs the quick
+      # gate in its worktree, lands it through the queue and tidies the worktree.
+      #
+      # @param held [Hash] the `Landing` record, as for {#merge}; `gate:` (a callable) replaces the
+      #   gate run, for a spec
+      # @return [Hash{Symbol => Hash}] the answer {#merge} gives
+      # @raise [ConsoleCapture::Failure] at the first step that fails, naming it: unsaved work,
+      #   conflict, gate red, or the queue busy
+      def finish_branch(**held)
+        settle(held)
+        branch = plain(held[:branch]) || current_branch
+        onto = plain(held[:onto]) || "main"
+        raise ConsoleCapture::Failure, "#{branch} is the branch to land onto" if branch == onto
+
+        Finisher.new(@git, @checkout, branch: branch, onto: onto, gate: held[:gate]).prepare
+        @retiring = true
+        merge(**held)
+      ensure
+        @retiring = false
       end
 
       # Removes a linked worktree and deletes its branch, once the branch is on `onto`.
@@ -43,19 +93,19 @@ module Hecks
       # @param held [Hash] the `Landing` record: `checkout` (the worktree to remove), `branch`
       #   (its checked-out branch when absent), `onto`
       # @return [Hash{Symbol => Hash}] `outcome:` (`retired`), `checkout:`, `branch:`, `report:`
-      # @raise [ConsoleCapture::Failure] when it is the primary worktree, holds uncommitted work,
-      #   or its branch has commits `onto` lacks
+      # @raise [ConsoleCapture::Failure] when anything makes keeping it the safe answer: the primary
+      #   worktree, one the process stands in, any file not tracked and clean (ignored included), a
+      #   branch with commits `onto` lacks or a protected branch, or git refusing the removal
       def remove(**held)
         settle(held)
         branch = plain(held[:branch]) || current_branch
         onto = plain(held[:onto]) || "main"
         gone = @checkout
-        home = primary.path
-        refuse_unretirable(branch, onto)
-        read("worktree", "remove", gone, dir: home)
-        read("branch", "-D", ref(branch), dir: home)
+        kept, said = Tidy.new(@git, @checkout, branch: branch, onto: onto, retiring: true).retire
+        raise ConsoleCapture::Failure, "#{gone} is kept: #{said}" if kept
+
         { outcome: { value: "retired" }, checkout: { value: gone }, branch: { value: branch },
-          report: { value: "removed #{gone} and deleted #{branch}, which is on #{onto}" } }
+          report: { value: said } }
       end
 
       # The branches whose commits are not on a branch, or that hold uncommitted work.
@@ -74,20 +124,56 @@ module Hecks
 
       private
 
+      # One landing from another worktree, as the train makes it for a waiting branch.
+      def land_for(checkout, branch, onto)
+        mine = @checkout
+        @checkout = checkout
+        land_alone(branch, onto, nil)
+      ensure
+        @checkout = mine
+      end
+
+      def land_alone(branch, onto, note)
+        refuse_unsaved(branch)
+        refuse_stale_base(branch) if onto == "main"
+        refuse_rival(branch, onto)
+        said = tidy(Merger.new(@git, @checkout, branch: branch, onto: onto).land, branch, onto)
+        note ? said.merge(report: { value: "#{said[:report][:value]}; #{note}" }) : said
+      end
+
+      def common_git_dir = read("rev-parse", "--path-format=absolute", "--git-common-dir")
+
+      # The line of this repository, with the limits of the world's `landing "Queue"` setting.
+      def lineup
+        setting = (@registry&.world("Hecks")&.settings || {})["landing"]
+        Lineup.new(common_git_dir, setting: setting, **@tune)
+      end
+
+      def refuse_rival(branch, onto)
+        clash = Rivals.new(@git, @checkout, @registry).refusal(branch, onto)
+        raise ConsoleCapture::Failure, clash if clash
+      end
+
+      def tidy(landed, branch, onto)
+        said = @retiring ? retire_from_primary(branch, onto) : Tidy.new(@git, @checkout, branch: branch, onto: onto).call
+        landed.merge(report: { value: "#{landed[:report][:value]}; #{said}" })
+      end
+
+      # A finish runs inside the worktree it retires, so the process leaves it first; a worktree that
+      # holds ignored files is kept and said so.
+      def retire_from_primary(branch, onto)
+        Dir.chdir(primary.path) do
+          kept, said = Tidy.new(@git, @checkout, branch: branch, onto: onto, retiring: true).retire
+          kept ? "kept #{branch}: #{said}" : said
+        end
+      end
+
       def refuse_unsaved(branch)
         tree = worktree_on(branch)
         changed = tree ? dirty(tree.path) : []
         raise ConsoleCapture::Failure, "#{tree.path} holds uncommitted work: #{changed.join(", ")}" unless changed.empty?
       end
 
-      def refuse_unretirable(branch, onto)
-        raise ConsoleCapture::Failure, "#{@checkout} is the primary worktree" if @checkout == primary.path
-
-        refuse_unsaved(branch)
-        behind = count("#{ref(onto)}..#{ref(branch)}")
-        raise ConsoleCapture::Failure, "#{branch} has #{behind} commit(s) not on #{onto}" if behind.positive?
-      end
-
       def branches = read("for-each-ref", "--format=%(refname:short)", "refs/heads").split("\n")
 
       def unlanded_line(name, onto)

data/lib/hecks/hecks/adapters/git_main_pull.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "git_worktrees"
+
+module Hecks
+  module Adapters
+    # Bringing local `main` up to date with `origin/main`: the one operation `LinkedTree.PullMain`
+    # is, and that `LinkedTree.Add`, `Landing.Land` and `Landing.Finish` lean on, so a branch is
+    # never cut or landed from a stale base.
+    #
+    # One fetch, then a fast-forward when local `main` is behind, or a rebase of its unpushed
+    # commits (merge commits kept) when both moved. It never forces, never pushes, never discards
+    # a commit and never merges onto `main`. A repository without an `origin` (or with no
+    # `origin/main`) has nothing to be behind, and the answer says so.
+    #
+    # An includer has the `GitWorktrees` helpers and sets `@git`.
+    module GitMainPull
+      REMOTE_MAIN = "origin/main"
+
+      # The files git keeps while a rebase or merge is unfinished, and what each is called.
+      MIDWAY = { "rebase-merge" => "rebase", "rebase-apply" => "rebase", "MERGE_HEAD" => "merge" }.freeze
+
+      private
+
+      # @return [String] what was done, one line
+      # @raise [ConsoleCapture::Failure] naming `cannot pull main` and why
+      def pull_main
+        return "no origin/main to pull" unless fetched_origin_main?
+
+        behind = count("main..#{REMOTE_MAIN}")
+        return "main is up to date with #{REMOTE_MAIN}" if behind.zero?
+
+        host = worktree_on("main")
+        refuse_unready(host)
+        ahead = count("#{REMOTE_MAIN}..main")
+        return fast_forward(host, behind) if ahead.zero?
+
+        rebase_main(host, ahead, behind)
+      end
+
+      # Fetches `origin` once; false when there is no origin or no `origin/main` to compare with.
+      def fetched_origin_main?
+        return false unless @git.capture("remote", "get-url", "origin", chdir: @checkout).ok?
+
+        fetched = @git.capture("fetch", "--quiet", "origin", chdir: @checkout)
+        raise ConsoleCapture::Failure, "cannot pull main: git fetch origin failed: #{fetched.err.strip}" unless fetched.ok?
+
+        @git.capture("rev-parse", "--verify", "--quiet", "refs/remotes/#{REMOTE_MAIN}", chdir: @checkout).ok?
+      end
+
+      # Refuses a `main` checkout that is dirty or in the middle of a rebase or merge.
+      def refuse_unready(host)
+        return unless host
+
+        midway = MIDWAY.find { |name, _| File.exist?(git_path(host.path, name)) }
+        raise ConsoleCapture::Failure, "cannot pull main: the checkout is in the middle of a #{midway.last}" if midway
+
+        changed = read("status", "--porcelain", "--untracked-files=no", dir: host.path)
+        raise ConsoleCapture::Failure, "cannot pull main: the checkout has uncommitted changes" unless changed.empty?
+      end
+
+      def git_path(dir, name) = read("rev-parse", "--path-format=absolute", "--git-path", name, dir: dir)
+
+      def fast_forward(host, behind)
+        if host
+          read("merge", "--ff-only", REMOTE_MAIN, dir: host.path)
+        else
+          read("fetch", "--quiet", "origin", "main:main")
+        end
+        "main fast-forwarded #{behind} commit#{"s" unless behind == 1} to #{short(read("rev-parse", "main"))}"
+      end
+
+      def rebase_main(host, ahead, behind)
+        raise ConsoleCapture::Failure, "cannot pull main: main is diverged and is checked out nowhere to rebase it in" unless host
+
+        result = @git.capture("rebase", "--rebase-merges", REMOTE_MAIN, chdir: host.path)
+        unless result.ok?
+          conflicts = @git.capture("diff", "--name-only", "--diff-filter=U", chdir: host.path).out.split
+          @git.capture("rebase", "--abort", chdir: host.path)
+          raise ConsoleCapture::Failure,
+                "cannot pull main: rebasing main's #{ahead} unpushed commits onto #{REMOTE_MAIN} conflicts in " \
+                "#{conflicts.join(", ")}; nothing changed"
+        end
+        "main rebased #{ahead} unpushed commits onto #{REMOTE_MAIN} (#{behind} new) at #{short(read("rev-parse", "main"))}"
+      end
+
+      # Refuses landing a branch onto `main` while it lacks what `origin/main` has.
+      def refuse_stale_base(branch)
+        return unless fetched_origin_main?
+
+        lacking = count("#{branch_tip(branch)}..#{REMOTE_MAIN}")
+        return if lacking.zero? || ancestor?(branch_tip(branch), branch_tip("main"))
+
+        raise ConsoleCapture::Failure, "main is behind origin/main by #{lacking} commit#{"s" unless lacking == 1}: " \
+                                       "pull main first (LinkedTree.pull_main!) and rebase the branch"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_rehearsal/bench.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require_relative "reading"
+
+module Hecks
+  module Adapters
+    class GitRehearsal
+      # A detached copy of a commit a rehearsal runs in, removed once it ends, so the stages check
+      # the very commit a push would carry and not whatever a checkout holds.
+      class Bench
+        include Reading
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param scope [String] a scope sweeps and names only its own benches, so a quick rehearsal
+        #   never removes the live bench of a deep one
+        def initialize(git, checkout, scope: "quick")
+          @git = git
+          @checkout = checkout
+          @scope = scope
+        end
+
+        # The prefix of the scratch directory every bench is made in, which tells a bench of this
+        # adapter from any other worktree.
+        PREFIX = "hecks-push-rehearsal"
+
+        # The prefix of a `quick` rehearsal's bench.
+        QUICK = "#{PREFIX}-quick".freeze
+
+        # A worktree's line in `git worktree list --porcelain`.
+        LISTED = /\Aworktree /
+
+        # Removes benches an earlier rehearsal left registered (it was killed before it cleaned up):
+        # only worktrees named `<tmp>/hecks-push-rehearsal*/bench`, so no other worktree is touched.
+        # Call it only while no rehearsal runs, which the caller's lock ensures.
+        #
+        # @return [Integer] how many stale benches were removed
+        def sweep
+          stale = benches
+          stale.each do |directory|
+            @git.capture("worktree", "remove", "--force", directory, chdir: @checkout)
+            FileUtils.rm_rf(File.dirname(directory))
+          end
+          @git.capture("worktree", "prune", chdir: @checkout) unless stale.empty?
+          stale.size
+        end
+
+        # @param commit [String] the commit to check out
+        # @yieldparam directory [String] the copy
+        # @return [Object] what the block returned
+        def rehearse(commit)
+          Dir.mktmpdir(@scope == "quick" ? QUICK : PREFIX) do |scratch|
+            directory = File.join(scratch, "bench")
+            read("worktree", "add", "--quiet", "--detach", directory, commit)
+            begin
+              yield directory
+            ensure
+              @git.capture("worktree", "remove", "--force", directory, chdir: @checkout)
+            end
+          end
+        end
+
+        private
+
+        # The registered worktrees that are benches of this adapter.
+        def benches
+          listed = read("worktree", "list", "--porcelain").lines.grep(LISTED)
+          listed.map { |line| line.delete_prefix("worktree ").strip }.select { |directory| bench?(directory) }
+        end
+
+        def bench?(directory)
+          return false unless File.basename(directory) == "bench"
+
+          name = File.basename(File.dirname(directory))
+          @scope == "quick" ? name.start_with?(QUICK) : (name.start_with?(PREFIX) && !name.start_with?(QUICK))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_rehearsal/due.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "../push_size"
+require "hecks/runtime/asking"
+require_relative "reading"
+require_relative "record"
+
+module Hecks
+  module Adapters
+    class GitRehearsal
+      # Whether a push is due, read from refs git already holds: how many commits local `main` is
+      # ahead of `origin/main`, how old the oldest of them is, and how the last quick rehearsal
+      # ended.
+      class Due
+        include Reading
+
+        # Seconds in an hour.
+        HOUR = 3600.0
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param place [Hash] `branch:` the local branch ("main"), `remote:` it is pushed to
+        # @param limits [Hash, nil] the push size thresholds; the booted world's when nil
+        # @param clock [#now] where the age of the oldest commit is read from
+        def initialize(git, checkout, limits: nil, clock: Time, **place)
+          @limits = limits || PushSize.thresholds(Runtime::Asking.registry)
+          @clock = clock
+          @git = git
+          @checkout = checkout
+          @branch = place.fetch(:branch, "main")
+          @tracking = "#{place.fetch(:remote, "origin")}/#{@branch}"
+        end
+
+        # @return [String] one line:
+        #   whether a push is due, the count, the age, the last rehearsal
+        # @raise [ConsoleCapture::Failure] when there is no such branch or remote-tracking branch
+        def report
+          ahead = read("rev-list", "--count", "#{@tracking}..#{@branch}").to_i
+          return "push due: no; #{@branch} is level with #{@tracking}; #{last_rehearsal}" if ahead.zero?
+
+          "push due: yes; #{ahead} commit(s) ahead of #{@tracking}; oldest unpushed #{age} hours old; " \
+            "#{size(ahead)}#{last_rehearsal}#{gate_note}"
+        end
+
+        private
+
+        # The size sentence and its separator once past the threshold, else nothing.
+        def size(ahead)
+          sentence = PushSize.sentence(ahead, @limits)
+          sentence.empty? ? "" : "#{sentence}; "
+        end
+
+        def age
+          oldest = read("log", "--reverse", "--format=%ct", "#{@tracking}..#{@branch}").lines.first.to_i
+          format("%.1f", (@clock.now.to_i - oldest) / HOUR)
+        end
+
+        def last_rehearsal = last_of("quick")
+
+        # The train's quick gate is the push gate; say so when no green rehearsal of it is current.
+        def gate_note
+          entry = Record.new(@git, @checkout).last("quick")
+          return "" if entry && entry.verdict == "green" && current?(entry)
+
+          "; the train's quick gate is the push gate and runs at the push: push_rehearsal.rehearse! " \
+            "runs it ahead (scope.value=deep also runs the impacted specs; opt-in)"
+        end
+
+        def last_of(scope)
+          entry = Record.new(@git, @checkout).last(scope)
+          return "last #{scope}: none yet" unless entry
+
+          "last #{scope}: #{entry.verdict}#{failed(entry)} on #{short(entry.commit)} (#{currency(entry)})"
+        end
+
+        def failed(entry) = entry.failed.empty? ? "" : " (#{entry.failed.tr(",", ", ")})"
+
+        def currency(entry) = current?(entry) ? "the current #{@branch}" : "#{@branch} has moved since"
+
+        def current?(entry) = read("rev-parse", "--verify", "refs/heads/#{@branch}^{commit}") == entry.commit
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_rehearsal/impacted/skips.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class GitRehearsal
+      class Impacted
+        # Which specs a rehearsal cannot run here: those that need `cargo`, `gh` or the network, and
+        # those tagged `:io` when no scratch Postgres answers.
+        class Skips
+          NEEDS = {
+            "cargo"   => /\bcargo (?:build|test|run|check)|["']cargo["']/,
+            "gh"      => /["'`]gh["'`]|`gh |\bgh (?:pr|run|api|workflow|issue)\b/,
+            "network" => /Net::HTTP|URI\.open|open-uri|\bcurl\b/
+          }.freeze
+          TAGGED_IO = /\bio: true\b|,\s*:io\b/
+          NO_POSTGRES = "no scratch Postgres"
+
+          # @param root [String] the tree the specs are read from
+          # @param scratch [#call] says whether a scratch Postgres is reachable
+          def initialize(root, scratch:)
+            @root = root
+            @scratch = scratch
+          end
+
+          # @param spec [String] a spec file relative to the root
+          # @return [String, nil] why it cannot run here, or nil
+          def call(spec)
+            text = File.read(File.join(@root, spec)).scrub
+            found = NEEDS.find { |_need, pattern| pattern.match?(text) }
+            return "needs #{found.first}" if found
+
+            NO_POSTGRES if tagged_io?(text) && !reachable?
+          end
+
+          # @return [Boolean] whether the spec has `:io` examples
+          def io?(spec) = tagged_io?(File.read(File.join(@root, spec)).scrub)
+
+          private
+
+          def tagged_io?(text) = TAGGED_IO.match?(text)
+
+          def reachable? = @reachable.nil? ? (@reachable = @scratch.call) : @reachable
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_rehearsal/impacted/spec_run.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Adapters
+    class GitRehearsal
+      class Impacted
+        # Runs one spec file through the launcher and reads how it ended.
+        class SpecRun
+          # How one spec file ended.
+          #
+          # @!attribute [r] spec
+          #   @return [String] the spec file
+          # @!attribute [r] passed
+          #   @return [Boolean] whether every example passed
+          # @!attribute [r] failures
+          #   @return [Array<String>] the failing examples, `./spec/a_spec.rb:12 # description`
+          Outcome = Struct.new(:spec, :passed, :failures) do
+            # @return [String] the spec and its first failing example, for the report
+            def line = "failing spec: #{failures.first || spec}"
+          end
+
+          LAUNCHER = %w[exe/hecks test_suite_run.run_spec_example!].freeze
+          GREEN = /\b[1-9]\d* examples?, 0 failures\b(?!, \d+ errors? occurred outside)/
+          JSON_FROM = /^\{.*\z/m
+          FAILED = %r{^rspec (\./\S+)(?: # (.*))?$}
+
+          # @param capture [#call] given a command and `env:`, runs it in a directory and returns a
+          #   `Shell::Result`; the directory is the first argument
+          def initialize(capture)
+            @capture = capture
+          end
+
+          # @param directory [String] the copy to run in
+          # @param spec [String] the spec file, relative to it
+          # @param io [Boolean] whether the file's `:io` examples are to run
+          # @return [Outcome]
+          def call(directory, spec, io: false)
+            env = io ? { "CI" => "true" } : {}
+            result = @capture.call(directory, *LAUNCHER, "file.value=#{spec}", "example.value= ", "--wait", env: env)
+            answer = answer(result)
+            report = said(answer)
+            Outcome.new(spec, settled?(result, answer) && GREEN.match?(report), failures(report, result))
+          end
+
+          private
+
+          def answer(result)
+            json = result.out[JSON_FROM]
+            json ? JSON.parse(json) : {}
+          rescue JSON::ParserError
+            {}
+          end
+
+          # The launcher exits non-zero when reactions the spec's own domains refused or crashed
+          # surface in its run, though every example passed; a run it recorded as completed counts.
+          def settled?(result, answer) = result.ok? || answer.dig("state", "status") == "completed"
+
+          # A red run is refused, with the output in the refusal and none in the report.
+          def said(answer) = (answer.dig("state", "report") || answer.dig("state", "refusal")).to_s
+
+          def failures(report, result)
+            listed = report.scan(FAILED).map { |where, what| [where, what].compact.join(" # ") }
+            return listed unless listed.empty?
+
+            report.empty? ? ["exit #{result.exit_code}: #{printed(result.err).last}"] : []
+          end
+
+          def printed(text) = text.lines.map(&:strip).reject(&:empty?)
+        end
+      end
+    end
+  end
+end