hecks 5.0.0 → 7.0.0

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

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "verdict"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # One place in the landing line: a file named by its sequence number, its branch, its process
+      # and its start time.
+      #
+      # The owner holds an exclusive `flock` on the file for as long as the ticket lives, so a
+      # waiter
+      # blocks on the ticket ahead of it and the kernel wakes it the moment that ticket is
+      # released or
+      # its process dies. The owner also touches the file on a timer: its modification time is the
+      # heartbeat, and a ticket that stops beating while still locked belongs to a hung process.
+      class Ticket
+        # The suffix every ticket file carries.
+        SUFFIX = ".ticket"
+
+        # Makes a ticket and takes its lock.
+        #
+        # @param path [String] the new file
+        # @param data [Hash] what it records: branch, pid, start time, checkout, onto and whether
+        #   it is ready
+        # @return [Ticket] the ticket, locked by this process
+        def self.create(path, data)
+          io = File.new(path, File::RDWR | File::CREAT | File::EXCL)
+          io.flock(File::LOCK_EX)
+          io.write(JSON.generate(data))
+          io.flush
+          new(path, io, Verdict.create(wake_path(path)))
+        end
+
+        # @param path [String] a ticket file
+        # @return [String] the mailbox beside it
+        def self.wake_path(path) = path.sub(/#{SUFFIX}\z/o, ".verdict")
+
+        # @return [String] the ticket file
+        attr_reader :path
+
+        # @param path [String] the ticket file
+        # @param io [IO, nil] the owner's locked handle
+        # @param verdict [Verdict, nil] the owner's mailbox
+        def initialize(path, io = nil, verdict = nil)
+          @path = path
+          @io = io
+          @verdict = verdict
+        end
+
+        # @return [String] the file name
+        def name = File.basename(@path)
+
+        # @return [Integer] the place in the line this ticket was given
+        def sequence = name.to_i
+
+        # @return [Hash] what the ticket records; a branch of "another landing" when it cannot be
+        #   read
+        def data
+          JSON.parse(File.read(@path), symbolize_names: true)
+        rescue JSON::ParserError, SystemCallError
+          { branch: "another landing" }
+        end
+
+        # Rewrites the record in place, so the lock on the file is kept.
+        #
+        # @param changes [Hash] the keys to set
+        # @return [void]
+        def update(**changes)
+          File.write(@path, JSON.generate(data.merge(changes)))
+        end
+
+        # Touches the file; its modification time becomes the heartbeat.
+        #
+        # @param time [Time] the heartbeat
+        # @return [void]
+        def beat(time)
+          File.utime(time, time, @path)
+        rescue SystemCallError
+          nil
+        end
+
+        # Starts beating on a timer, until the ticket is closed.
+        #
+        # @param every [Numeric] seconds between beats
+        # @param clock [#call] answers the current Time
+        # @return [void]
+        def beat_every(every, clock)
+          @beater = Thread.new do
+            loop do
+              sleep(every)
+              beat(clock.call)
+            end
+          end
+        end
+
+        # @param now [Time] the current time
+        # @return [Float] seconds since the last heartbeat, infinite when the ticket is gone
+        def silence(now)
+          now.to_f - File.mtime(@path).to_f
+        rescue Errno::ENOENT
+          Float::INFINITY
+        end
+
+        # @return [Boolean] whether a live process holds the lock
+        def held?
+          File.open(@path, File::RDONLY) { |file| file.flock(File::LOCK_EX | File::LOCK_NB) == false }
+        rescue Errno::ENOENT
+          false
+        end
+
+        # Blocks until the owner releases the lock or dies.
+        #
+        # @return [void]
+        def wait_gone
+          File.open(@path, File::RDONLY) { |file| file.flock(File::LOCK_EX) }
+        rescue Errno::ENOENT
+          nil
+        end
+
+        # Blocks until the train delivers a verdict to this ticket's owner.
+        #
+        # @return [Hash, nil] the verdict
+        def verdict = @verdict&.read
+
+        # Tells the owner of this ticket how its branch fared.
+        #
+        # @param payload [Hash] `landed:` the answer, or `refused:` the reason
+        # @return [void]
+        def deliver(payload)
+          Verdict.deliver(self.class.wake_path(@path), payload)
+        end
+
+        # Stops beating and lets go of the lock and the mailbox.
+        #
+        # @return [void]
+        def close
+          @beater&.kill
+          @verdict&.close
+          @io&.close
+        end
+
+        # Deletes the files of a ticket.
+        #
+        # @return [void]
+        def remove
+          File.delete(@path)
+          Verdict.new(self.class.wake_path(@path), nil).remove
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "../git_worktrees"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # What a landing leaves behind: the linked worktree it landed from and that worktree's branch.
+      #
+      # When in doubt it keeps both. It removes them only when the worktree is a linked one that
+      # nobody stands in, holds no file that is not tracked and clean (ignored files and build
+      # output count, so a local `.env` is never lost), and its branch tip, verified once, is
+      # contained in local `onto`. The worktree goes without `--force`, and the branch goes only
+      # while it still names the verified tip, so a commit made in between is never dropped.
+      # `main`, `stable`, `edge`, the target and a branch another worktree holds are never deleted.
+      class Tidy
+        include GitWorktrees
+
+        # Branches no tidy deletes, whatever they contain.
+        PROTECTED = %w[main stable edge].freeze
+
+        # The most paths a refusal names.
+        NAMED = 5
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param branch [String] the landed branch
+        # @param onto [String] the branch it was landed on
+        # @param retiring [Boolean] whether `checkout` is the very worktree to retire
+        def initialize(git, checkout, branch:, onto:, retiring: false)
+          @git = git
+          @checkout = checkout
+          @from = checkout
+          @branch = ref(branch)
+          @onto = ref(onto)
+          @retiring = retiring
+        end
+
+        # @return [String] a sentence saying what was removed, or why nothing was
+        def call
+          kept, said = retire
+          kept ? "kept #{@branch}: #{said}" : said
+        end
+
+        # @return [Array(Boolean, String)] whether everything was kept, and the sentence saying so
+        #   or what was removed
+        def retire
+          @checkout = primary.path
+          tree = worktree_on(@branch)
+          tip = tree && branch_tip(@branch)
+          why = reason_to_keep(tree, tip)
+          why ? [true, why] : drop(tree.path, tip)
+        end
+
+        private
+
+        def reason_to_keep(tree, tip)
+          return "no linked worktree has it checked out" unless tree
+
+          refusal_for_tree(tree) || unsaved(tree.path) || unmerged(tip)
+        rescue SystemCallError, ConsoleCapture::Failure => e
+          "#{tree&.path || @branch} could not be checked (#{e.message}), so nothing was removed"
+        end
+
+        def refusal_for_tree(tree)
+          return "its worktree is the main checkout" if same?(tree.path, primary.path)
+          return "#{@branch} is protected" if protected_branch?
+          return "#{tree.path} is not the worktree named #{@from}" if @retiring && !same?(tree.path, @from)
+
+          "#{tree.path} is where this runs: run from the main checkout to retire it" if standing_in?(tree.path)
+        end
+
+        def protected_branch? = PROTECTED.include?(@branch) || @branch == @onto
+
+        def unsaved(path)
+          found = status_lines(path)
+          return if found.empty?
+
+          "#{path} holds uncommitted work or files that are not tracked and clean: #{named(found)}"
+        end
+
+        def status_lines(path)
+          out = read("status", "--porcelain", "--ignored", "--untracked-files=all", dir: path)
+          out.lines.map(&:rstrip).reject(&:empty?)
+        end
+
+        def named(lines)
+          shown = lines.first(NAMED).join(", ")
+          lines.size > NAMED ? "#{shown} and #{lines.size - NAMED} more" : shown
+        end
+
+        def unmerged(tip)
+          return "it has no commit to verify" unless tip
+
+          local = "refs/heads/#{@onto}"
+          behind = count("#{local}..#{tip}")
+          "it has #{behind} commit(s) not on #{@onto}" if behind.positive? || !ancestor?(tip, local)
+        end
+
+        def drop(path, tip)
+          return [true, "#{@branch} moved after it was checked"] unless branch_tip(@branch) == tip
+
+          read("worktree", "remove", path, dir: @checkout)
+          [false, delete_branch(path, tip)]
+        rescue ConsoleCapture::Failure => e
+          [true, "git would not remove #{path}: #{e.message}"]
+        end
+
+        def delete_branch(path, tip)
+          return "removed #{path}; kept #{@branch}, which another worktree holds" if worktree_on(@branch)
+
+          read("update-ref", "-d", "refs/heads/#{@branch}", tip, dir: @checkout)
+          "removed #{path} and deleted #{@branch}"
+        rescue ConsoleCapture::Failure
+          "removed #{path}; kept #{@branch}, which moved after it was verified"
+        end
+
+        def same?(one, other) = File.identical?(one, other)
+
+        # Whether the directory the process stands in, or the landing's checkout, is in the tree.
+        def standing_in?(path)
+          [here, (@from unless @retiring)].compact.any? { |dir| inside?(path, dir) }
+        end
+
+        def here
+          Dir.pwd
+        rescue SystemCallError
+          nil
+        end
+
+        def inside?(tree, dir)
+          current = File.realpath(dir)
+          loop do
+            return true if File.identical?(current, tree)
+
+            above = File.dirname(current)
+            return false if above == current
+
+            current = above
+          end
+        rescue SystemCallError
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../git_worktrees"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # A merge train: the holder of the front place lands every branch whose ticket declared it
+      # ready,
+      # in ticket order, without giving the place up between them.
+      #
+      # Each branch is rebased onto the moving `onto`, run through the quick gate, then landed by
+      # the
+      # same steps a single landing takes. A branch that conflicts, fails the gate or overlaps
+      # another
+      # started row's area is skipped with its reason; the verdict goes into its ticket, so the
+      # waiting
+      # `land!` of that branch returns the answer or the refusal, and the others go on.
+      class Train
+        include GitWorktrees
+
+        # What the train works with.
+        #
+        # @!attribute [r] line
+        #   @return [Line] the line
+        # @!attribute [r] ticket
+        #   @return [Ticket] the train's own ticket, at the front
+        # @!attribute [r] land
+        #   @return [#call] `(checkout, branch, onto)` lands one branch, answering the landing hash
+        # @!attribute [r] gate
+        #   @return [#call] `(directory)` answers nil when the quick gate is green, else why it is
+        # not
+        Crew = Struct.new(:line, :ticket, :land, :gate)
+
+        # The quick gate, run from the branch's own worktree.
+        QUICK_GATE = lambda do |dir|
+          out, status = Open3.capture2e("exe/hecks", "gate_run.gate!", "stage=quick", "--wait", chdir: dir)
+          "the quick gate failed: #{Train.tail(out, 3)}" unless status.success?
+        end
+
+        # @param text [String] some output
+        # @param count [Integer] how many lines
+        # @return [String] the last lines of it
+        def self.tail(text, count)
+          lines = text.lines.last(count)
+          lines.map(&:strip).join(" ")
+        end
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param crew [Crew] the line, the ticket and the steps
+        # @param onto [String] the branch the train lands on
+        def initialize(git, checkout, crew, onto:)
+          @git = git
+          @checkout = checkout
+          @crew = crew
+          @onto = ref(onto)
+        end
+
+        # @return [String] a sentence saying which branches landed and which were skipped, and why
+        def run
+          settled = []
+          while (ticket = @crew.line.next_ready(@crew.ticket))
+            settled << carry(ticket)
+          end
+          settled.empty? ? "no branch was waiting in the line" : settled.join("; ")
+        end
+
+        private
+
+        def carry(ticket)
+          held = ticket.data
+          ticket.update(handled: true)
+          answer = lands(held)
+          ticket.deliver(landed: answer)
+          "landed #{held[:branch]}"
+        rescue ConsoleCapture::Failure => e
+          ticket.deliver(refused: e.message)
+          "skipped #{held[:branch]}: #{e.message}"
+        end
+
+        def lands(held)
+          rebase(held[:branch])
+          why = @crew.gate.call(worktree_on(held[:branch])&.path || @checkout)
+          raise ConsoleCapture::Failure, why if why
+
+          @crew.land.call(held[:checkout], held[:branch], @onto)
+        end
+
+        def rebase(branch)
+          tree = worktree_on(branch)
+          return unless tree
+
+          result = @git.capture("rebase", @onto, chdir: tree.path)
+          return if result.ok?
+
+          @git.capture("rebase", "--abort", chdir: tree.path)
+          raise ConsoleCapture::Failure, "#{branch} does not rebase onto #{@onto}: #{Train.tail(result.out, 2)}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # The one-way mailbox a ticket owns: a named pipe the ticket's owner blocks on and the train
+      # writes to when it has settled that ticket's branch for it.
+      #
+      # The owner keeps the pipe open for reading and writing from the moment the ticket exists,
+      # so a
+      # verdict written before the owner starts to read is held by the pipe, never lost.
+      class Verdict
+        # @param path [String] where the pipe is made
+        # @return [Verdict] the mailbox, open and empty
+        def self.create(path)
+          File.mkfifo(path)
+          new(path, File.open(path, File::RDWR))
+        end
+
+        # Hands a verdict to the owner of the pipe at `path`, when the owner is still there.
+        #
+        # @param path [String] the pipe
+        # @param payload [Hash] what the owner is told
+        # @return [void]
+        def self.deliver(path, payload)
+          File.open(path, File::WRONLY | File::NONBLOCK) { |pipe| pipe.write("#{JSON.generate(payload)}\n") }
+        rescue Errno::ENXIO, Errno::ENOENT
+          nil
+        end
+
+        # @param path [String] the pipe
+        # @param io [IO, nil] the owner's open end
+        def initialize(path, io)
+          @path = path
+          @io = io
+        end
+
+        # Blocks until a verdict arrives; no polling.
+        #
+        # @return [Hash, nil] what the train delivered, nil when the pipe closed
+        def read
+          line = @io.gets
+          line && JSON.parse(line, symbolize_names: true)
+        rescue IOError
+          nil
+        end
+
+        # @return [void]
+        def close
+          @io&.close
+        end
+
+        # @return [void]
+        def remove
+          File.delete(@path)
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # A ticket's wait for the front of the line.
+      #
+      # It blocks on the lock of the ticket just ahead, so the kernel wakes it when that ticket is
+      # released or its process dies, and on the ticket's mailbox, so a train that settles the
+      # branch
+      # for it wakes it too. A timer wakes it only at the moment a silent ticket would go stale, or
+      # when its own wait runs out. Each change of place is said once, naming the holder.
+      class Waiting
+        # How a holder's wording reads in a position message.
+        LANDING_FOR = / \(landing for (.*)\)\z/
+
+        # Raised when the wait ran out before the ticket reached the front.
+        class Expired < RuntimeError; end
+
+        # What the wait ended with.
+        #
+        # @!attribute [r] verdict
+        #   @return [Hash, nil] the train's verdict, when it settled the branch instead
+        # @!attribute [r] note
+        #   @return [String, nil] a sentence for the report: the wait, the place and what was
+        # superseded
+        Turn = Struct.new(:verdict, :note)
+
+        # @param line [Line] the line
+        # @param ticket [Ticket] the ticket waiting
+        # @param patience [Numeric] seconds the wait may last
+        # @param say [#call] told each change of place
+        # @param foreign [ForeignHold] what else can hold the landing
+        def initialize(line, ticket, patience:, say:, foreign:)
+          @line = line
+          @ticket = ticket
+          @say = say
+          @foreign = foreign
+          @until = clock + patience
+          @started = clock
+          @notes = []
+        end
+
+        # @return [Turn] reached the front, or settled by a train
+        # @raise [Expired] when the wait ran out
+        def run
+          events = Thread::Queue.new
+          mailbox = Thread.new { events << [:verdict, @ticket.verdict] }
+          verdict = await(events)
+          verdict ? Turn.new(verdict, note) : front
+        ensure
+          mailbox&.kill
+        end
+
+        private
+
+        def front
+          budget = -> { @until - clock }
+          cleared = @foreign.clears_within?(@ticket.name, budget, @say)
+          raise Expired, "waited #{waited} for the shell lock or an older landing" unless cleared
+
+          @line.promote(@ticket)
+          Turn.new(nil, note)
+        end
+
+        def await(events)
+          loop do
+            standing = @line.standing(@ticket)
+            @notes.concat(standing.notes)
+            return nil if standing.ahead.empty?
+
+            announce(standing.ahead)
+            event = pause(standing, events)
+            return event.last if event&.first == :verdict
+          end
+        end
+
+        def pause(standing, events)
+          raise Expired, "waited #{waited} behind #{@last}" if @until <= clock
+
+          watcher = Thread.new do
+            standing.ahead.last.wait_gone
+            events << [:ahead]
+          end
+          events.pop(timeout: [@line.stale_in(standing.ahead), @until - clock].min)
+        ensure
+          watcher&.kill
+        end
+
+        def announce(ahead)
+          @last = @line.wording(ahead.first.data)
+          said = "#{ordinal(ahead.size + 1)} in line; holder #{@last.sub(LANDING_FOR, ' has landed for \\1')}"
+          return if @said == said
+
+          @said = said
+          @notes << said
+          @say.call("#{@ticket.data[:branch]} is #{said}")
+        end
+
+        def note
+          return nil if @notes.empty?
+
+          "#{@notes.join("; ")}; waited #{waited}"
+        end
+
+        def waited
+          seconds = (clock - @started).round
+          seconds < 120 ? "#{seconds}s" : "#{seconds / 60}m #{seconds % 60}s"
+        end
+
+        def ordinal(number)
+          suffix = number.between?(11, 13) ? "th" : { 1 => "st", 2 => "nd", 3 => "rd" }.fetch(number % 10, "th")
+          "#{number}#{suffix}"
+        end
+
+        def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_landing.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_landing"
+
+Hecks.adapter "GitLanding" do
+  port "Worktrees"
+end