hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/git_commit.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_commit"
+
+Hecks.adapter "GitCommit" do
+  port "Committing"
+end

data/lib/hecks/hecks/adapters/git_commit.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "git_worktrees"
+
+module Hecks
+  module Adapters
+    # The `Committing` port's adapter for `Commit`: stages the named paths, then commits what is
+    # staged under the message, on the branch the checkout is on.
+    #
+    # It never pushes, never amends, never forces, and never commits onto `main`: that goes through
+    # `Landing`, and a push goes through `PushTrain`. A commit with nothing staged is declined.
+    class GitCommit
+      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
+
+      # Commits what is staged in a checkout, after staging the named paths when there are some.
+      #
+      # @param held [Hash] the `Commit` record: `checkout` (a directory inside the worktree; the
+      #   current directory when absent), `message`, and `paths` (whitespace-separated, optional)
+      # @return [Hash{Symbol => Hash}] `sha:` the commit made, `report:` what it says
+      # @raise [ConsoleCapture::Failure] on an empty message, a commit onto `main`, nothing staged,
+      #   or a directory outside a repository
+      def commit(**held)
+        settle(held)
+        message = plain(held[:message]).to_s.strip
+        raise ConsoleCapture::Failure, "a commit needs a message" if message.empty?
+
+        branch = current_branch
+        raise ConsoleCapture::Failure, "a commit onto main goes through Landing" if branch == "main"
+
+        stage(plain(held[:paths]))
+        refuse_nothing_staged
+        read("commit", "-m", message)
+        sha = read("rev-parse", "--short", "HEAD")
+        { sha: { value: sha }, report: { value: "committed #{sha} on #{branch}" } }
+      end
+
+      private
+
+      # Stages each named path; `--` keeps a path from being read as an option.
+      def stage(paths)
+        names = paths.to_s.split
+        read("add", "--", *names) unless names.empty?
+      end
+
+      def refuse_nothing_staged
+        return unless read("diff", "--cached", "--name-only").empty?
+
+        raise ConsoleCapture::Failure, "nothing is staged to commit"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../git_worktrees"
+require_relative "../git_main_pull"
+require_relative "../shell"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # The steps before a landing that an agent used to run by hand: refuse unsaved work, rebase the
+      # branch onto local `main`, and run the quick gate in the branch's worktree.
+      #
+      # Each step refuses by name at the first failure, with the reason, and leaves the branch as it
+      # was: a rebase that conflicts is aborted. The landing itself and the tidy after it are
+      # {GitLanding#merge}'s.
+      class Finisher
+        include GitWorktrees
+        include GitMainPull
+
+        # The command that runs the seconds-long checks in a worktree.
+        GATE = %w[exe/hecks gate_run.gate! stage=quick --wait].freeze
+
+        # What a completed gate run prints.
+        COMPLETED = /"status":\s*"completed"/
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the worktree the branch is checked out in
+        # @param branch [String] the branch to finish
+        # @param onto [String] the branch to rebase onto
+        # @param gate [#call] answers the {Shell::Result} of the quick gate run in a directory
+        def initialize(git, checkout, branch:, onto:, gate: nil)
+          @git = git
+          @checkout = checkout
+          @branch = ref(branch)
+          @onto = ref(onto)
+          @gate = gate || ->(dir) { Shell.new.capture(*GATE, chdir: dir) }
+        end
+
+        # Refuses unsaved work, pulls `main` when it is the target, rebases and runs the gate.
+        #
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] naming the step that failed: unsaved work, conflict or
+        #   gate red
+        def prepare
+          refuse_unsaved
+          pull_main if @onto == "main"
+          rebase
+          run_gate
+        end
+
+        private
+
+        def refuse_unsaved
+          changed = dirty(@checkout)
+          raise ConsoleCapture::Failure, "unsaved work: #{@checkout} holds #{changed.join(", ")}" unless changed.empty?
+        end
+
+        def rebase
+          result = @git.capture("rebase", @onto, chdir: @checkout)
+          return if result.ok?
+
+          conflicts = @git.capture("diff", "--name-only", "--diff-filter=U", chdir: @checkout).out.split
+          @git.capture("rebase", "--abort", chdir: @checkout)
+          raise ConsoleCapture::Failure,
+                "conflict: rebasing #{@branch} onto #{@onto} conflicts in #{conflicts.join(", ")}; nothing changed"
+        end
+
+        def run_gate
+          result = @gate.call(@checkout)
+          return if result.ok? && result.out.match?(COMPLETED)
+
+          raise ConsoleCapture::Failure, "gate red: the quick gate failed in #{@checkout}: #{tail(result)}"
+        end
+
+        def tail(result)
+          lines = result.out.lines.last(5)
+          lines.join.strip
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # A landing in flight that holds no ticket: the shell lock directory old briefs make with
+      # `mkdir`, and the claim file landers of an older build write.
+      #
+      # The head of the line waits for either to go. A directory has no wake-up event, so this is
+      # the
+      # one place a wait looks again on a timer. A shell lock that one of the caller's own ancestor
+      # processes names on its command line is the caller's, so it never blocks the call that
+      # holds it.
+      class ForeignHold
+        # Seconds between looks at the lock.
+        LOOK = 2
+
+        # The shell lock directories that guard landings in a repository: the one the world names,
+        # and
+        # the job's own `land.lock`, which guards only the repository this code runs from.
+        #
+        # @param git_dir [String] the main checkout's git directory of the repository being landed
+        #   in
+        # @param named [String, nil] the world's `shell_lock`
+        # @return [Array<String>] the directories to honour
+        def self.locks(git_dir, named)
+          job = ENV.fetch("CLAUDE_JOB_DIR", "")
+          own = File.join(job, "tmp", "land.lock") if !job.empty? && home?(git_dir)
+          [named, own].compact
+        end
+
+        # @return [Boolean] whether a git directory is the repository this code is checked out from
+        def self.home?(git_dir)
+          out, status = Open3.capture2("git", "rev-parse", "--path-format=absolute", "--git-common-dir", chdir: __dir__)
+          status.success? && File.realpath(out.strip) == File.realpath(git_dir)
+        rescue SystemCallError
+          false
+        end
+
+        # @param legacy [String] the claim file the front ticket feeds
+        # @param locks [Array<String>] shell lock directories
+        # @param stale [Numeric] seconds after which either is taken to be abandoned
+        # @param mine [#call] answers whether a lock path is the caller's own
+        def initialize(legacy, locks:, stale:, mine: method(:ancestor_names?))
+          @legacy = legacy
+          @locks = locks
+          @stale = stale
+          @mine = mine
+        end
+
+        # @param token [String] the name of the caller's own ticket, whose claim file it fed itself
+        # @return [String, nil] a sentence naming what holds the landing, nil when nothing does
+        def holder(token)
+          lock = @locks.find { |path| fresh?(path) && !@mine.call(path) }
+          return "the shell lock #{lock}" if lock
+
+          claim = fresh_claim(token)
+          "#{claim["branch"]}, landing by an older build" if claim
+        end
+
+        # Looks every few seconds until nothing holds the landing, or the budget runs out.
+        #
+        # @param token [String] the caller's ticket
+        # @param budget [#call] seconds the caller may still wait
+        # @param say [#call] told what is being waited for, once
+        # @return [Boolean] false when the budget ran out first
+        def clears_within?(token, budget, say)
+          said = nil
+          while (held = holder(token))
+            return false if budget.call <= 0
+
+            say.call("waiting for #{held}") unless said == held
+            said = held
+            sleep([LOOK, budget.call].min)
+          end
+          true
+        end
+
+        private
+
+        def fresh?(path) = File.exist?(path) && Time.now - File.mtime(path) < @stale
+
+        def fresh_claim(token)
+          return unless fresh?(@legacy)
+
+          claim = JSON.parse(File.read(@legacy))
+          claim unless claim["token"] == token
+        rescue JSON::ParserError
+          nil
+        end
+
+        # Whether a process above this one has the path on its command line.
+        def ancestor_names?(path)
+          pid = Process.ppid
+          40.times do
+            out, = Open3.capture2("ps", "-o", "ppid=,command=", "-p", pid.to_s)
+            parent, command = out.strip.split(" ", 2)
+            return true if command.to_s.include?(path)
+            return false if parent.to_i <= 1
+
+            pid = parent.to_i
+          end
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require_relative "ticket"
+require_relative "numbering"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # The landing line of one repository: ticket files in `queue/` under the main checkout's git
+      # directory, numbered by a counter that only grows, so first come is first served across
+      # processes. The ticket at the front holds the one place to land.
+      #
+      # Every read or change of the line happens inside an `flock` on a guard file. The front
+      # ticket
+      # feeds the legacy claim file, which landers that still read it keep honouring.
+      class Line
+        # What a look at the line finds ahead of a ticket.
+        #
+        # @!attribute [r] ahead
+        #   @return [Array<Ticket>] the live tickets in front, in order
+        # @!attribute [r] notes
+        #   @return [Array<String>] the abandoned tickets removed on the way
+        Standing = Struct.new(:ahead, :notes)
+
+        # The minutes without a heartbeat after which a ticket is abandoned, when no setting names
+        # another.
+        DEFAULT_STALE_MINUTES = 30
+
+        # @param git_dir [String] the main checkout's git directory
+        # @param stale_minutes [Numeric, nil] the heartbeat window; the default when nil
+        # @param clock [#call] answers the current Time
+        # @param heartbeat [Numeric] seconds between a holder's heartbeats
+        def initialize(git_dir, stale_minutes: nil, clock: -> { Time.now }, heartbeat: 15)
+          @git_dir = git_dir
+          @root = File.join(git_dir, "hecks-landing")
+          @dir = File.join(@root, "queue")
+          @stale = (stale_minutes || DEFAULT_STALE_MINUTES).to_f * 60
+          @clock = clock
+          @heartbeat = heartbeat
+          @numbers = Numbering.new(@dir, @root)
+        end
+
+        # Takes the next place in the line.
+        #
+        # @param branch [String] the branch the ticket stands for
+        # @param jump [Boolean] take the place right behind the front ticket, ahead of those
+        #   waiting
+        # @param details [Hash] more for the ticket to record: `checkout`, `onto`, `ready`
+        # @return [Ticket] the ticket, locked and beating
+        def join(branch, jump: false, **details)
+          guarded do
+            record = details.merge(branch: branch, pid: Process.pid, at: now.to_f)
+            ticket = Ticket.create(@numbers.path(tickets, branch, jump, now), record)
+            ticket.beat(now)
+            ticket.beat_every(@heartbeat, @clock)
+            ticket
+          end
+        end
+
+        # Looks at the tickets in front of one, removing any that were abandoned: its process is
+        # gone,
+        # or it holds the lock but has not beaten for the stale window.
+        #
+        # @param ticket [Ticket] the ticket asking
+        # @return [Standing] the live tickets ahead and the sentences about the abandoned ones
+        def standing(ticket)
+          guarded do
+            ahead = tickets.select { |other| other.sequence < ticket.sequence }.map { |other| [other, lapse(other)] }
+            notes = ahead.filter_map { |other, why| supersede(other, why) if why }
+            Standing.new(ahead.reject { |_, why| why }.map(&:first), notes)
+          end
+        end
+
+        # Makes a ticket the holder: stamps the time it began and feeds the legacy claim.
+        #
+        # @param ticket [Ticket] the ticket at the front
+        # @return [void]
+        def promote(ticket)
+          guarded do
+            ticket.update(turn_at: now.to_f)
+            File.write(legacy, JSON.generate(token: ticket.name, branch: ticket.data[:branch], pid: Process.pid, at: now.to_f))
+          end
+        end
+
+        # Gives a ticket up: closes it, deletes its files, and clears the legacy claim when it fed
+        # it.
+        #
+        # @param ticket [Ticket] the ticket
+        # @return [void]
+        def leave(ticket)
+          guarded do
+            File.delete(legacy) if fed_by?(ticket)
+            ticket.close
+            ticket.remove
+          end
+        end
+
+        # The next ticket behind one that declared itself ready and has not been settled yet.
+        #
+        # @param ticket [Ticket] the holder
+        # @return [Ticket, nil] the first such ticket
+        def next_ready(ticket)
+          guarded do
+            tickets.find { |other| other.sequence > ticket.sequence && waiting_ready?(other) }
+          end
+        end
+
+        # @param data [Hash] a ticket's record
+        # @return [String] its branch and how long it has been at the front
+        def wording(data)
+          minutes = ((now.to_f - data.fetch(:turn_at) { data[:at] }.to_f) / 60).floor
+          "#{data[:branch]} (landing for #{minutes} minute#{"s" unless minutes == 1})"
+        end
+
+        # @return [Float] seconds until the soonest of some tickets would go stale, at least a
+        #   second
+        def stale_in(tickets)
+          [tickets.map { |held| @stale - held.silence(now) }.min.to_f, 1].max
+        end
+
+        # @return [String] the legacy claim file
+        def legacy = File.join(@git_dir, "hecks-landing.claim")
+
+        private
+
+        def now = @clock.call
+
+        def fed_by?(ticket)
+          File.exist?(legacy) && JSON.parse(File.read(legacy))["token"] == ticket.name
+        rescue JSON::ParserError
+          false
+        end
+
+        # Why a ticket is abandoned, or nil while it is alive and beating.
+        def lapse(ticket)
+          return "its process is gone" unless ticket.held?
+
+          quiet = ticket.silence(now)
+          "no heartbeat for #{(quiet / 60).floor} minutes" if quiet > @stale
+        end
+
+        def supersede(ticket, why)
+          sentence = "superseded the abandoned landing of #{wording(ticket.data)} (#{why})"
+          File.delete(legacy) if fed_by?(ticket)
+          ticket.remove
+          sentence
+        end
+
+        def tickets
+          names = Dir.children(@dir).grep(/#{Ticket::SUFFIX}\z/o)
+          names.sort.map { |name| Ticket.new(File.join(@dir, name)) }
+        end
+
+        def waiting_ready?(ticket)
+          held = ticket.data
+          held[:ready] && !held[:handled] && ticket.held?
+        end
+
+        def guarded
+          FileUtils.mkdir_p(@dir)
+          File.open(File.join(@root, "guard"), File::RDWR | File::CREAT) do |file|
+            file.flock(File::LOCK_EX)
+            yield
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "line"
+require_relative "waiting"
+require_relative "foreign_hold"
+require_relative "train"
+require_relative "../console_capture"
+require_relative "../../../indifferent_key"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # A landing's way through the line: a ticket in order, a wait for the front, the landing
+      # itself,
+      # then the ticket given back; or a train that settles the tickets behind it.
+      #
+      # The limits come from the world's `landing "Queue", stale_minutes: n, wait_minutes: n`; the
+      # `tune` hash overrides any of them (`stale_minutes`, `wait_minutes`, `heartbeat`, `clock`,
+      # `say`,
+      # `locks`, `mine`, `gate`).
+      class Lineup
+        # The minutes a landing waits for its turn, when no setting names another.
+        DEFAULT_WAIT_MINUTES = 40
+
+        # @param git_dir [String] the main checkout's git directory
+        # @param setting [Hash, nil] the world's `landing` setting
+        # @param tune [Hash] overrides of the limits and the collaborators
+        def initialize(git_dir, setting: nil, **tune)
+          @tune = { stale_minutes: read(setting, :stale_minutes), wait_minutes: read(setting, :wait_minutes),
+                    locks: ForeignHold.locks(git_dir, read(setting, :shell_lock)) }.compact.merge(tune)
+          @line = Line.new(git_dir, stale_minutes: @tune[:stale_minutes], clock: @tune.fetch(:clock) { -> { Time.now } },
+                                    heartbeat: @tune.fetch(:heartbeat, 15))
+        end
+
+        # Takes a place, waits for the front, and runs the block there; or, when a train settled
+        # the
+        # branch while it waited, answers what the train answered and runs nothing.
+        #
+        # @param branch [String] the branch to land
+        # @param onto [String] the branch it lands on
+        # @param checkout [String] the worktree it lands from
+        # @yieldparam note [String, nil] what the wait was: the place, the holder, what was
+        #   superseded
+        # @return [Hash] the landing answer
+        # @raise [ConsoleCapture::Failure] when the wait runs out, or the train refused the branch
+        def stand(branch, onto:, checkout:)
+          ticket = @line.join(branch, checkout: checkout, onto: onto, ready: true)
+          turn = waiting(ticket).run
+          turn.verdict ? carried(turn) : yield(turn.note)
+        rescue Waiting::Expired => e
+          raise ConsoleCapture::Failure, "queue busy: #{branch} is not landed: #{e.message}; land again when the line clears"
+        ensure
+          @line.leave(ticket) if ticket
+        end
+
+        # Takes the front place and lands every ready branch behind it.
+        #
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param onto [String] the branch the train lands on
+        # @param land [#call] `(checkout, branch, onto)` lands one branch
+        # @return [String] the train's report, opened by what the wait was
+        def convoy(git, checkout, onto:, land:)
+          ticket = @line.join("train", jump: true, checkout: checkout, onto: onto, ready: false)
+          turn = waiting(ticket).run
+          crew = Train::Crew.new(@line, ticket, land, @tune.fetch(:gate, Train::QUICK_GATE))
+          [Train.new(git, checkout, crew, onto: onto).run, turn.note].compact.join("; ")
+        ensure
+          @line.leave(ticket) if ticket
+        end
+
+        private
+
+        def waiting(ticket)
+          Waiting.new(@line, ticket, patience: @tune.fetch(:wait_minutes, DEFAULT_WAIT_MINUTES).to_f * 60,
+                                     say: @tune.fetch(:say) { ->(text) { warn(text) } }, foreign: foreign)
+        end
+
+        def foreign
+          stale = (@tune[:stale_minutes] || Line::DEFAULT_STALE_MINUTES).to_f * 60
+          options = { locks: @tune.fetch(:locks, []), stale: stale }
+          options[:mine] = @tune[:mine] if @tune[:mine]
+          ForeignHold.new(@line.legacy, **options)
+        end
+
+        def carried(turn)
+          verdict = turn.verdict
+          raise ConsoleCapture::Failure, verdict[:refused] if verdict[:refused]
+
+          said = verdict[:landed][:report][:value]
+          verdict[:landed].merge(report: { value: "#{said}; landed by the train, #{turn.note}" })
+        end
+
+        def read(setting, key) = setting && IndifferentKey.read(setting, key)
+      end
+    end
+  end
+end

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

@@ -76,7 +76,7 @@ module Hecks
         end
 
         def answer(outcome, landed, report)
-          { outcome: { value: outcome }, checkout: { value: @checkout }, branch: { value: @branch },
+          { outcome: { value: outcome }, checkout: { value: primary.path }, branch: { value: @branch },
             landed: { value: landed }, report: { value: report } }
         end
       end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "ticket"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # The numbers the line's tickets are named by: a counter kept in a file that only grows, so a
+      # ticket never gets a number an earlier one had, even after the line empties.
+      #
+      # Ordinary numbers are a thousand apart, so a train can take the place right behind the
+      # front.
+      class Numbering
+        # The distance between two ordinary ticket numbers.
+        GAP = 1000
+
+        # What a branch name loses before it goes into a file name.
+        UNSAFE = /[^A-Za-z0-9._-]/
+
+        # @param dir [String] the directory the tickets live in
+        # @param root [String] the directory the counter lives in
+        def initialize(dir, root)
+          @dir = dir
+          @counter = File.join(root, "sequence")
+        end
+
+        # @param tickets [Array<Ticket>] the tickets in the line, in order
+        # @param branch [String] the branch the new ticket stands for
+        # @param jump [Boolean] take the place right behind the front ticket
+        # @param now [Time] the current time
+        # @return [String] the path of the new ticket's file
+        def path(tickets, branch, jump, now)
+          number = jump && tickets.first ? behind(tickets) : bump
+          name = "#{number.to_s.rjust(10, "0")}-#{branch.gsub(UNSAFE, "_")}-#{Process.pid}-#{now.to_i}#{Ticket::SUFFIX}"
+          File.join(@dir, name)
+        end
+
+        private
+
+        def behind(tickets)
+          taken = tickets.map(&:sequence)
+          first = tickets.first.sequence + 1
+          (first..).find { |number| !taken.include?(number) }
+        end
+
+        def bump
+          count = (File.exist?(@counter) ? File.read(@counter).to_i : 0) + GAP
+          File.write(@counter, count.to_s)
+          count
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../git_worktrees"
+require_relative "../area_overlap"
+require_relative "../started_work"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # The started Work rows that hold ground a branch changes. A branch is landed for its own Work
+      # row, the one keyed by the branch name, so that row is never a rival; a landing with no row
+      # has none to clash with.
+      class Rivals
+        include GitWorktrees
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param registry [Runtime::Registry, nil] where the Work rows are read from
+        def initialize(git, checkout, registry)
+          @git = git
+          @checkout = checkout
+          @registry = registry
+        end
+
+        # @param branch [String] the branch to land
+        # @param onto [String] the branch it lands on
+        # @return [String, nil] the refusal naming the row and the files, nil when none clash
+        def refusal(branch, onto)
+          files = changed(branch, onto)
+          StartedWork.rows(@registry).each do |row|
+            next if row[:key] == branch
+
+            clash = files.select { |file| claims?(row, file) }
+            return wording(branch, row, clash) unless clash.empty?
+          end
+          nil
+        end
+
+        private
+
+        def claims?(row, file)
+          row[:area].any? { |area| AreaOverlap.overlap?(area, file, root: @checkout, file: true) }
+        end
+
+        def wording(branch, row, clash)
+          "#{branch} changes #{clash.join(", ")}, in the area of #{row[:key]} (#{row[:area].join(", ")})"
+        end
+
+        def changed(branch, onto)
+          result = @git.capture("diff", "--no-renames", "--name-only", "-z", "#{ref(onto)}...#{ref(branch)}",
+                                chdir: @checkout)
+          raise ConsoleCapture::Failure, "git diff failed in #{@checkout}: #{result.err.strip}" unless result.ok?
+
+          result.out.split("\0").reject(&:empty?)
+        end
+      end
+    end
+  end
+end