hecks 5.0.0 → 6.0.0

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "git_worktrees"
+require_relative "git_landing/merger"
+
+module Hecks
+  module Adapters
+    # The `Worktrees` port's adapter for `Landing`: merges a worktree's branch onto local `main`,
+    # retires a worktree and its branch once they are merged, and lists what is not on `main`.
+    #
+    # It never pushes, never forces, and never resolves a conflict. Retiring refuses a worktree
+    # that holds uncommitted work or a branch with commits `main` lacks, so no unpushed work goes.
+    class GitLanding
+      include GitWorktrees
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @git = Git.new
+      end
+
+      # Lands a worktree's branch onto another branch (local `main` by default).
+      #
+      # @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`
+      # @return [Hash{Symbol => Hash}] the answer `Merger#land` describes
+      # @raise [ConsoleCapture::Failure] on a conflict, uncommitted work, or no such branch
+      def merge(**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
+
+        refuse_unsaved(branch)
+        Merger.new(@git, @checkout, branch: branch, onto: onto).land
+      end
+
+      # Removes a linked worktree and deletes its branch, once the branch is on `onto`.
+      #
+      # @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
+      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)
+        { outcome: { value: "retired" }, checkout: { value: gone }, branch: { value: branch },
+          report: { value: "removed #{gone} and deleted #{branch}, which is on #{onto}" } }
+      end
+
+      # The branches whose commits are not on a branch, or that hold uncommitted work.
+      #
+      # @param held [Hash] `checkout` (any directory in the repository), `onto` (default `main`)
+      # @return [Hash{Symbol => String}] `text:` one tab-separated line per branch
+      # @raise [Runtime::NotFound] when the checkout is not a repository
+      def unlanded(**held)
+        settle(held)
+        onto = ref(plain(held[:onto]) || "main")
+        lines = branches.reject { |name| name == onto }.filter_map { |name| unlanded_line(name, onto) }
+        { text: lines.empty? ? "everything is on #{onto}\n" : "#{lines.join("\n")}\n" }
+      rescue ConsoleCapture::Failure => e
+        raise Runtime::NotFound, e.message
+      end
+
+      private
+
+      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)
+        ahead = count("#{onto}..#{name}")
+        tree = worktree_on(name)
+        changed = tree ? dirty(tree.path).size : 0
+        return nil if ahead.zero? && changed.zero?
+
+        [name, "#{ahead} commit(s) not on #{onto}", tree&.path || "no worktree", "#{changed} uncommitted"].join("\t")
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_launcher.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/git_launcher"
+
+Hecks.adapter "GitLauncher" do
+  port "Launcher"
+end

data/lib/hecks/hecks/adapters/git_launcher.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require_relative "git"
+
+module Hecks
+  module Adapters
+    # The `Launcher` port's adapter: keeps the copy of Hecks that runs the push train on the branch
+    # it just pushed, so the next boarding (and the records it keeps) runs the code that landed.
+    #
+    # It moves only a copy that is a detached, clean checkout of the same repository the push went
+    # to; any other copy (an installed gem, a checkout on a branch, one with edits, another
+    # repository) is left as it is and the answer says why. Moving it is a fetch and a detached
+    # checkout of the pushed commit, never a reset of a branch.
+    class GitLauncher
+      # The directory this copy of Hecks runs from.
+      ROOT = File.expand_path("../../../..", __dir__)
+
+      # Accepts the arguments every driven adapter is built with; `root` names the copy to keep
+      # current, for a test, and defaults to the running one.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] the copy of Hecks to move
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @git = Git.new
+        @root = root || ROOT
+      end
+
+      # Moves the running copy of Hecks to the commit a boarding pushed, when it is a detached,
+      # clean checkout of the same repository.
+      #
+      # @param held [Hash] the `PushTrain` record: `checkout`, `remote` and `pushed`
+      # @return [Hash{Symbol => Hash}] `report:` where the copy now stands, or why it was left
+      # @raise [ConsoleCapture::Failure] when the copy should move and git refuses
+      def refresh(**held)
+        reason = left_as_is(held)
+        return { report: { value: "launcher left at #{head}: #{reason}" } } if reason
+
+        before = head
+        move_to(plain(held[:remote]), plain(held[:pushed]))
+        { report: { value: "launcher #{before} -> #{head}" } }
+      end
+
+      private
+
+      def left_as_is(held)
+        return "not a git checkout" unless git("rev-parse", "--git-dir").ok?
+        return "on a branch, not detached" if git("symbolic-ref", "-q", "HEAD").ok?
+        return "has local edits (#{first_edit})" if first_edit
+        return "a checkout of another repository" unless same_repository?(held)
+
+        nil
+      end
+
+      # The first changed or untracked path, as `git status --porcelain` writes it, so the report
+      # says which file keeps the copy from moving.
+      def first_edit = status_lines.first&.strip
+
+      def status_lines = git("status", "--porcelain").out.lines
+
+      def same_repository?(held)
+        pushed_to = @git.capture("remote", "get-url", plain(held[:remote]), chdir: plain(held[:checkout]))
+        mine = git("remote", "get-url", plain(held[:remote]))
+        pushed_to.ok? && mine.ok? && pushed_to.out.strip == mine.out.strip
+      end
+
+      def move_to(remote, commit)
+        [["fetch", "-q", remote], ["checkout", "-q", "--detach", commit]].each do |args|
+          done = git(*args)
+          raise ConsoleCapture::Failure, "git #{args.first} in #{@root}: #{done.err.strip}" unless done.ok?
+        end
+      end
+
+      def head = git("rev-parse", "--short", "HEAD").out.strip
+
+      def git(*) = @git.capture(*, chdir: @root)
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_refs.rb

@@ -27,7 +27,8 @@ module Hecks
         listed = capture("ls-remote", remote, name, chdir: chdir)
         refuse("git ls-remote #{remote} #{name} failed", listed) unless listed.ok?
 
-        listed.out.lines.map { |line| line.split.first }.first
+        printed = listed.out
+        printed.lines.map { |line| line.split.first }.first
       end
 
       # Whether one commit is an ancestor of another, so that moving a ref from the first to the
@@ -41,7 +42,8 @@ module Hecks
       def ancestor?(ancestor, descendant, chdir: nil)
         result = capture("merge-base", "--is-ancestor", checked_ref(ancestor), checked_ref(descendant), chdir: chdir)
         return true if result.ok?
-        return false if result.status.exitstatus == 1
+
+        return false if result.exit_code == 1
 
         refuse("git merge-base failed", result)
       end
@@ -63,7 +65,8 @@ module Hecks
         listed = capture("log", "--first-parent", "--reverse", "--format=%ct", range, chdir: chdir)
         refuse("git log #{range} failed", listed) unless listed.ok?
 
-        listed.out.lines.first&.to_i
+        printed = listed.out
+        printed.lines.first&.to_i
       end
 
       # The commits a lane may be moved onto, newest first: the first-parent chain of `newer` that
@@ -80,7 +83,8 @@ module Hecks
         listed = capture("rev-list", "--first-parent", "-n", Integer(limit).to_s, range, chdir: chdir)
         refuse("git rev-list #{range} failed", listed) unless listed.ok?
 
-        listed.out.split
+        printed = listed.out
+        printed.split
       end
 
       # Moves a remote branch to a commit, and only forward: the push is refused by the remote when

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require_relative "reading"
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # A detached worktree a push is made from, removed once it ends. The local branch is checked
+      # out there and merged with the remote's when the two have parted, so the repository's
+      # pre-push hook checks the very commit that goes out, not whatever a checkout holds.
+      class Bench
+        include Reading
+
+        # What git says when the remote's branch moved after the fetch.
+        MOVED = /\[rejected\]|non-fast-forward|fetch first|cannot lock ref|stale info/
+
+        # How many lines of a refused push's output a refusal keeps.
+        KEPT_LINES = 40
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param branch [String] the branch to push
+        # @param remote [String] the remote to push it to
+        # @param config [Array<String>] `-c name=value` words placed before `push`, which the
+        #   repository's pre-push hook reads with `git config`
+        def initialize(git, checkout, branch:, remote:, config: [])
+          @git = git
+          @checkout = checkout
+          @branch = branch
+          @remote = remote
+          @config = config
+        end
+
+        # Pushes the local branch, merged with the remote's when they have parted.
+        #
+        # @param local [String] the commit the local branch names
+        # @param tracking [String] the remote-tracking branch, just fetched
+        # @return [String, Symbol] the commit pushed, or `:moved` when the remote's branch moved
+        # @raise [ConsoleCapture::Failure] when the two conflict, or the push is refused
+        def push(local, tracking)
+          Dir.mktmpdir("hecks-push-train") do |scratch|
+            bench = File.join(scratch, "bench")
+            read("worktree", "add", "--quiet", "--detach", bench, local)
+            push_from(bench, local, tracking)
+          ensure
+            @git.capture("worktree", "remove", "--force", bench, chdir: @checkout) if bench
+          end
+        end
+
+        private
+
+        def push_from(bench, local, tracking)
+          merge(bench, tracking) unless ancestor?(tracking, local)
+          pushed = @git.capture(*@config, "push", @remote, "HEAD:refs/heads/#{@branch}", chdir: bench)
+          return read("rev-parse", "HEAD", dir: bench) if pushed.ok?
+          return :moved if pushed.err.match?(MOVED)
+
+          raise ConsoleCapture::Failure, "the push of #{@branch} was refused:\n#{tail(pushed)}"
+        end
+
+        def merge(bench, tracking)
+          return if @git.capture("merge", "--no-edit", tracking, chdir: bench).ok?
+
+          conflicted = read("diff", "--name-only", "--diff-filter=U", dir: bench).split.join(", ")
+          @git.capture("merge", "--abort", chdir: bench)
+          raise ConsoleCapture::Failure,
+                "#{@branch} and #{tracking} conflict in #{conflicted}: merge them by hand, then board again"
+        end
+
+        def tail(result) = "#{result.out}#{result.err}".lines.last(KEPT_LINES).join
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train/carriage.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "reading"
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # One boarding's work once it holds the line: fetch the remote's branch, then either find
+      # the local branch already level with it or push the local branch, and ride again while
+      # commits landed during the push are still ahead.
+      #
+      # A push the remote turns away because its branch moved meanwhile (a push from another
+      # machine, which the line does not hold back) is fetched again and retried.
+      class Carriage
+        include Reading
+
+        # How many times a push the remote turned away for having moved is tried.
+        ATTEMPTS = 3
+
+        # How many pushes one boarding makes while the local branch keeps getting ahead.
+        RIDES = 3
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param branch [String] the branch to push
+        # @param remote [String] the remote to push it to
+        # @param config [Array<String>] `-c name=value` words for the push, read by the hook
+        def initialize(git, checkout, branch:, remote:, config: [])
+          @git = git
+          @checkout = checkout
+          @branch = branch
+          @remote = remote
+          @config = config
+        end
+
+        # @return [String] the commit the local branch names now
+        # @raise [ConsoleCapture::Failure] when there is no such branch
+        def local_head = read("rev-parse", "--verify", "refs/heads/#{@branch}^{commit}")
+
+        # Carries the local branch: finds it already on the remote, or pushes it and pushes again
+        # while commits that landed meanwhile are still ahead (at most `RIDES` pushes).
+        #
+        # @param boarded [String] the commit the local branch named at boarding
+        # @return [Hash{Symbol => Hash}] the answer `GitTrain#carry` describes
+        # @raise [ConsoleCapture::Failure] when the branches conflict or the push is refused
+        def carry(boarded)
+          fetch
+          return carried(boarded) if level?
+
+          ride(boarded)
+        end
+
+        private
+
+        # Whether everything the local branch holds is on the remote.
+        def level? = ancestor?(local_head, tracking)
+
+        def ride(boarded, reports = [])
+          answer = push(boarded)
+          reports << answer.dig(:report, :value)
+          fetch
+          return finish(answer, reports) if level? || reports.size >= RIDES
+
+          ride(boarded, reports)
+        end
+
+        def finish(answer, reports)
+          answer.merge(report: { value: (reports + leftover).join("; ") })
+        end
+
+        # What the local branch still holds that the remote lacks, named so nobody has to look.
+        def leftover
+          return [] if level?
+
+          waiting = read("log", "--format=%h %s", "#{tracking}..#{@branch}").lines.map(&:strip)
+          ["#{waiting.size} commit(s) still ahead of #{tracking}: #{waiting.first(5).join(" | ")}"]
+        end
+
+        def push(boarded, attempt = 1)
+          before = read("rev-parse", tracking)
+          pushed = Bench.new(@git, @checkout, branch: @branch, remote: @remote, config: @config)
+                        .push(local_head, tracking)
+          return retry_push(boarded, attempt) if pushed == :moved
+
+          answer("pushed", boarded, pushed, pushed_report(before, pushed))
+        end
+
+        def retry_push(boarded, attempt)
+          raise ConsoleCapture::Failure, "#{tracking} kept moving: #{ATTEMPTS} pushes were turned away" if attempt >= ATTEMPTS
+
+          fetch
+          push(boarded, attempt + 1)
+        end
+
+        def pushed_report(before, pushed)
+          count = read("rev-list", "--count", "#{before}..#{pushed}")
+          local = LocalBranch.new(@git, @checkout, @branch).catch_up(pushed)
+          "pushed #{short(pushed)} to #{tracking}, #{count} commit(s) new there; #{local}"
+        end
+
+        def carried(boarded)
+          answer("carried", boarded, nil, "#{short(boarded)} is already on #{tracking}: an earlier push carried it")
+        end
+
+        def answer(outcome, boarded, pushed, report)
+          { outcome: { value: outcome }, checkout: { value: @checkout }, boarded: { value: boarded },
+            pushed: pushed && { value: pushed }, report: { value: report } }.compact
+        end
+
+        def fetch = read("fetch", "--quiet", @remote, "+refs/heads/#{@branch}:refs/remotes/#{tracking}")
+
+        def tracking = "#{@remote}/#{@branch}"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train/local_branch.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "reading"
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # The local branch after a push: brought forward to the pushed commit when nothing would be
+      # lost by it, so the next merge into it starts from what the remote holds.
+      #
+      # A branch checked out in a worktree with uncommitted changes, or one that took new commits
+      # while the push ran, is left where it is: the next boarding carries those commits.
+      class LocalBranch
+        include Reading
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param branch [String] the local branch
+        def initialize(git, checkout, branch)
+          @git = git
+          @checkout = checkout
+          @branch = branch
+        end
+
+        # Brings the branch forward to the pushed commit where that is safe.
+        #
+        # @param pushed [String] the commit the push took to the remote
+        # @return [String] what became of the local branch, as a clause of the report
+        def catch_up(pushed)
+          local = read("rev-parse", "refs/heads/#{@branch}")
+          return "local #{@branch} is there too" if local == pushed
+          return "local #{@branch} took new commits meanwhile; the next boarding carries them" unless ancestor?(local, pushed)
+
+          forward(pushed, local, checked_out_in)
+        end
+
+        private
+
+        def forward(pushed, local, worktree)
+          return update(pushed, local) unless worktree
+          return "local #{@branch} has uncommitted changes in #{worktree}; it is left behind" unless clean?(worktree)
+
+          read("merge", "--quiet", "--ff-only", pushed, dir: worktree)
+          "local #{@branch} moved forward in #{worktree}"
+        end
+
+        def update(pushed, local)
+          read("update-ref", "refs/heads/#{@branch}", pushed, local)
+          "local #{@branch} moved forward"
+        end
+
+        def clean?(worktree) = read("status", "--porcelain", "--untracked-files=no", dir: worktree).empty?
+
+        # The worktree that has the branch checked out, if any.
+        def checked_out_in
+          blocks = read("worktree", "list", "--porcelain").split("\n\n")
+          held = blocks.find { |block| block.lines.map(&:chomp).include?("branch refs/heads/#{@branch}") }
+          held && worktree_path(held)
+        end
+
+        # The path a `git worktree list --porcelain` block opens with.
+        def worktree_path(block)
+          first = block.lines.first
+          first.delete_prefix("worktree ").strip
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train/reading.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # The git reads every part of a boarding makes, in the checkout it was boarded from: each
+      # answers what git printed or refuses with what git said.
+      #
+      # An includer sets `@git` (the `Git` adapter) and `@checkout` (the repository's top level).
+      module Reading
+        private
+
+        def read(*args, dir: @checkout)
+          result = @git.capture(*args, chdir: dir)
+          raise ConsoleCapture::Failure, "git #{args.first} failed in #{dir}: #{result.err.strip}" unless result.ok?
+
+          result.out.strip
+        end
+
+        def ancestor?(ancestor, descendant) = @git.ancestor?(ancestor, descendant, chdir: @checkout)
+
+        def short(commit) = commit[0, 9]
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train/survey.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # What a survey finds: every git checkout directly under a directory whose default branch
+      # holds commits its remote does not, with how far ahead and behind it stands and its newest
+      # unpushed commit. Each checkout is fetched first, so the counts are against the remote as it
+      # is now. A checkout without the remote has nowhere to push and is passed over; one whose
+      # fetch fails is named as unreadable.
+      class Survey
+        # @param git [Git] the adapter every git call goes through
+        # @param root [String] the directory whose children are surveyed
+        # @param remote [String] the remote each checkout is compared with
+        def initialize(git, root, remote:)
+          @git = git
+          @root = root
+          @remote = remote
+        end
+
+        # @return [String] one line per checkout with unpushed commits, else a line saying none has
+        def report
+          lines = checkouts.filter_map { |dir| line_for(dir) }
+          lines.empty? ? "nothing to push under #{@root}" : lines.join("\n")
+        end
+
+        private
+
+        # The git checkouts directly under the root that have the remote, in name order.
+        def checkouts = children.select { |dir| File.exist?(File.join(dir, ".git")) && remote?(dir) }
+
+        def children = Dir.children(@root).sort.map { |name| File.join(@root, name) }
+
+        def line_for(dir)
+          return "#{File.basename(dir)}: unreadable (fetching #{@remote} failed)" unless fetched?(dir)
+
+          branch = default_branch(dir)
+          ahead = count(dir, "#{@remote}/#{branch}..#{branch}")
+          return if ahead.to_i.zero?
+
+          "#{File.basename(dir)} (#{branch}): #{ahead} ahead, #{count(dir, "#{branch}..#{@remote}/#{branch}")} behind " \
+            "— newest #{git(dir, "log", "-1", "--format=%h %cr %an: %s", branch)}"
+        end
+
+        def remote?(dir) = @git.capture("remote", "get-url", @remote, chdir: dir).ok?
+
+        def fetched?(dir) = @git.capture("fetch", "-q", @remote, chdir: dir).ok?
+
+        def default_branch(dir)
+          head = git(dir, "symbolic-ref", "--short", "refs/remotes/#{@remote}/HEAD")
+          head.empty? ? "main" : head.delete_prefix("#{@remote}/")
+        end
+
+        def count(dir, range) = git(dir, "rev-list", "--count", range)
+
+        def git(dir, *) = @git.capture(*, chdir: dir).out.strip
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/git_train"
+
+Hecks.adapter "GitTrain" do
+  port "Train"
+end