fun_ci 2.0.2-aarch64-linux → 2.1.1-aarch64-linux

data/lib/fun_ci/pipeline/trunk_run.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../trunk/check"
+require_relative "../trunk/checker"
+
+module FunCi
+  module Pipeline
+    # A run's check against the trunk (architecture.md, Checking against the
+    # trunk). It begins before the stages, where the database may be used
+    # (claiming a fetch, recording its process, reading the other branches'
+    # heads); finishes in a thread beside them, which touches no database,
+    # since the slow suite's fork closes the recorder, checking the other
+    # heads too when the trunk has moved; and is recorded once the stages are
+    # done, through whichever recorder the run holds then. Whatever goes wrong
+    # is recorded as an unknown check rather than raised into the run.
+    class TrunkRun
+      Result = Trunk::Checker::Result
+      # What the thread found: the run's own result, and the other heads' checks.
+      Found = Data.define(:result, :rechecks)
+
+      # For a project that checks no trunk.
+      class Skipped
+        def finish(_recorder) = nil
+        def notice = nil
+      end
+
+      # trunk: begins a check (#start(sha, fetches), nil for none), finishes it
+      # (#finish(pending)) and checks other heads against a tip (#recheck(heads, tip)).
+      def self.start(trunk, sha, recorder)
+        pending = trunk.start(sha, recorder.trunk_fetches) { |pid| recorder.trunk_fetch_process(pid) }
+        return Skipped.new unless pending
+
+        recorder.trunk_check_started
+        heads = recorder.trunk_heads(except: sha)
+        new(Thread.new { found(trunk, pending, sha, heads) }, trunk.notice(pending))
+      rescue StandardError => e
+        new(Thread.new { Found.new(result: failed(sha, e), rechecks: []) })
+      end
+
+      def self.found(trunk, pending, sha, heads)
+        rechecked(trunk, heads, Found.new(result: finished(trunk, pending, sha), rechecks: []))
+      end
+
+      def self.finished(trunk, pending, sha)
+        trunk.finish(pending)
+      rescue StandardError => e
+        failed(sha, e)
+      end
+
+      # A recheck that goes wrong costs the other heads a fresher check, never the run its own.
+      def self.rechecked(trunk, heads, found)
+        tip = found.result.check&.tip
+        tip ? found.with(rechecks: trunk.recheck(heads, tip)) : found
+      rescue StandardError
+        found
+      end
+
+      def self.failed(sha, error)
+        check = Trunk::Check.new(commit: sha, tip: nil,
+                                 merge: Trunk::Merge.unknown("the check failed: #{error.message}"))
+        Result.new(check: check, fetched: nil)
+      end
+      private_class_method :found, :finished, :rechecked, :failed
+
+      attr_reader :notice
+
+      # notice: what to tell the developer of a first fetch, or nil.
+      def initialize(thread, notice = nil)
+        @thread = thread
+        @notice = notice
+      end
+
+      def finish(recorder)
+        found = @thread.value
+        result = found.result
+        recorder.trunk_fetched(result.fetched, result.check&.tip) if result.fetched
+        [result.check, *found.rechecks].compact.each { |check| recorder.trunk_checked(check) }
+      end
+    end
+  end
+end

data/lib/fun_ci/setup/agent_instructions.rb

@@ -15,6 +15,9 @@ module FunCi
         `fun-ci wait` command it prints, in the background, and act on its exit
         code: 0 passed, 1 failed, 2 over budget, 3 undecided, 4 superseded.
         `fun-ci wait --need all` must exit 0 before the work is called done.
+        Before calling work done, run `fun-ci wait --need all --trunk`; 6 means
+        the commit conflicts with the trunk, which has to be integrated first,
+        as it prints.
         `fun-ci runs` lists recent runs, and `fun-ci status` says where one stands.
       MD
 

data/lib/fun_ci/setup/project_config.rb

@@ -38,6 +38,8 @@ module FunCi
       def any_project_presets = preset_candidates.reject(&:because).map { |found| found.preset.name }
 
       def worktree_slots = settings.worktree_slots
+      def trunk = settings.trunk
+      def trunk_fetch = settings.trunk_fetch
 
       def script_path(stage)
         File.join(@fun_ci_dir, "#{stage}.sh")
@@ -49,7 +51,7 @@ module FunCi
 
       private
 
-      def settings = Settings.new(File.join(@fun_ci_dir, "config"))
+      def settings = Settings.at(File.join(@fun_ci_dir, "config"))
 
       def preset_candidates
         evidence = Evidence::Settings.load(File.join(@fun_ci_dir, "config"))

data/lib/fun_ci/setup/settings.rb

@@ -9,13 +9,34 @@ module FunCi
     # as are all of them when the file isn't YAML.
     class Settings
       DEFAULTS = { "worktree_slots" => 2 }.freeze
+      FETCH_EVERY = 300
+      UNITS = { "" => 1, "s" => 1, "m" => 60, "h" => 3600 }.freeze
 
-      def initialize(path)
-        @path = path
+      # The settings in the file at `path`, which may not exist.
+      def self.at(path) = new(File.exist?(path) ? File.read(path) : nil)
+
+      # text: the YAML, or nil for none.
+      def initialize(text)
+        @text = text
       end
 
       def worktree_slots = errors.empty? ? values.fetch("worktree_slots") : DEFAULTS.fetch("worktree_slots")
 
+      # The trunk's name, or nil when none is given or it is no name. A mistake
+      # in the trunk settings never stops a pipeline, so none is among `errors`.
+      def trunk
+        given = setting("trunk")
+        given.is_a?(String) ? given : nil
+      end
+
+      # Seconds between fetches of the trunk, or nil when fun-ci doesn't fetch it.
+      def trunk_fetch
+        given = setting("trunk_fetch")
+        return nil if given == false
+
+        seconds(given) || FETCH_EVERY
+      end
+
       def errors
         return [".fun-ci/config must be a mapping such as `worktree_slots: 2`"] unless raw.is_a?(Hash)
 
@@ -29,7 +50,18 @@ module FunCi
 
       private
 
-      def raw = File.exist?(@path) ? YAML.safe_load_file(@path) || {} : {}
+      def setting(key)
+        raw.is_a?(Hash) ? raw[key] : nil
+      rescue Psych::SyntaxError
+        nil
+      end
+
+      def seconds(given)
+        match = /\A(\d+)([smh]?)\z/.match(given.to_s)
+        match && (match[1].to_i * UNITS.fetch(match[2]))
+      end
+
+      def raw = (@text && YAML.safe_load(@text)) || {}
       def values = DEFAULTS.merge(raw)
     end
   end

data/lib/fun_ci/setup/setup_checker.rb

@@ -2,24 +2,29 @@
 
 require_relative "project_config"
 require_relative "legacy_hooks"
+require_relative "trunk_report"
 
 module FunCi
   module Setup
     class SetupChecker
       def self.run(project_root:, stdout: $stdout)
-        new(config: ProjectConfig.new(project_root), hooks: LegacyHooks.new(project_root), stdout: stdout).run
+        new(config: ProjectConfig.new(project_root), hooks: LegacyHooks.new(project_root), stdout: stdout,
+            trunk: TrunkReport.new(project_root)).run
       end
 
-      def initialize(config:, hooks:, stdout:)
+      # trunk: describes the project's trunk (#lines).
+      def initialize(config:, hooks:, stdout:, trunk:)
         @config = config
         @hooks = hooks
         @stdout = stdout
+        @trunk = trunk
       end
 
       # Warnings are printed but don't fail the check.
       def run
         errors = @config.validate + @config.evidence_errors
         @stdout.puts(errors.empty? ? "All OK. The project is configured." : errors)
+        @stdout.puts(@trunk.lines)
         list_presets
         @hooks.warnings.each { |warning| @stdout.puts "Warning: #{warning}" }
         errors.empty? ? 0 : 1

data/lib/fun_ci/setup/trunk_report.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "project_config"
+require_relative "../trunk/description"
+require_relative "../trunk/git"
+
+module FunCi
+  module Setup
+    # The project's trunk as `fun-ci check` describes it. Git is asked only
+    # inside a repository: outside one there is no trunk to find.
+    class TrunkReport
+      NO_REFS = Trunk::Refs.new(remotes: [], branches: [], heads: {})
+
+      def initialize(project_root)
+        @project_root = project_root
+      end
+
+      def lines
+        config = ProjectConfig.new(@project_root)
+        Trunk::Description.lines(setting: config.trunk, interval: config.trunk_fetch, refs: refs)
+      end
+
+      private
+
+      def refs = File.exist?(File.join(@project_root, ".git")) ? Trunk::Git.new(@project_root).refs : NO_REFS
+    end
+  end
+end

data/lib/fun_ci/trunk/check.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Trunk
+    # Seconds a run's fetch of the trunk may take, and then its merge.
+    FETCH_DEADLINE = 20
+    CHECK_BUDGET = 5
+
+    # The trunk as fun-ci saw it: its branch, on a remote or (remote nil)
+    # local, the SHA at its tip, and when fun-ci first saw that SHA.
+    Tip = Data.define(:remote, :branch, :sha, :seen_at)
+
+    class Tip
+      def ref = remote ? "#{remote}/#{branch}" : branch
+    end
+
+    # What merging a commit with a trunk tip would do: ahead and behind count
+    # the commits each has that the other lacks, and outcome is "clean",
+    # "conflicts" (in `files`) or "unknown" (for `reason`).
+    Merge = Data.define(:outcome, :ahead, :behind, :files, :reason)
+
+    class Merge
+      def self.clean(ahead:, behind:) = new(outcome: "clean", ahead: ahead, behind: behind, files: [], reason: nil)
+
+      def self.conflicts(files, ahead:, behind:)
+        new(outcome: "conflicts", ahead: ahead, behind: behind, files: files, reason: nil)
+      end
+
+      def self.unknown(reason) = new(outcome: "unknown", ahead: nil, behind: nil, files: [], reason: reason)
+    end
+
+    # The last fetch of a project's trunk fun-ci tried: when one last
+    # succeeded (nil if none has), and why the last one failed, if it did.
+    LastFetch = Data.define(:fetched_at, :error)
+
+    # A conflict with the trunk explained: git's messages about the merge, and
+    # each conflicted file as the merge leaves it, by path.
+    Explained = Data.define(:messages, :files)
+
+    # What merge-tree prints: the merged tree's SHA, the conflicted paths, and
+    # after a blank line git's messages.
+    MergeOutput = Data.define(:tree, :paths, :messages)
+
+    class MergeOutput
+      def self.parse(out)
+        lines = out.lines(chomp: true)
+        paths = lines.drop(1).take_while { |line| !line.empty? }
+        new(tree: lines.first, paths: paths, messages: lines.drop(paths.size + 2).reject(&:empty?))
+      end
+    end
+
+    # One check of a commit against one trunk tip (architecture.md, Checking against the trunk);
+    # the tip is nil when there was none to check against.
+    Check = Data.define(:commit, :tip, :merge)
+  end
+end

data/lib/fun_ci/trunk/checker.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../setup/project_config"
+require_relative "check"
+require_relative "fetch"
+require_relative "git"
+require_relative "merge_check"
+require_relative "resolver"
+require_relative "tip_reader"
+require_relative "description"
+
+module FunCi
+  module Trunk
+    # Checks a commit against the project's trunk (architecture.md, Checking against the trunk):
+    # the ref `trunk:` names in .fun-ci/config, or the one the repository
+    # has; none at all when it says `none`. A check starts where the database
+    # may be used (resolving the trunk, claiming a fetch, recording its pid)
+    # and finishes where it may not (waiting for the fetch, merging).
+    class Checker
+      SET_IT = "set trunk: in .fun-ci/config"
+
+      # What a check found, or nil for none, and how its fetch went, or nil when it made none.
+      Result = Data.define(:check, :fetched)
+      # A check begun: the trunk it found (nil for none), its fetch if started, and the fetch before it.
+      Pending = Data.define(:sha, :ref, :started, :last)
+
+      def self.for(project, env: ENV.to_h)
+        new(Git.new(project), Setup::ProjectConfig.new(project), Fetch.new(project, env: env), -> { Time.now })
+      end
+
+      # config: answers #trunk and #trunk_fetch; fetch: starts and finishes a Fetch; clock: answers the time.
+      def initialize(git, config, fetch, clock)
+        @git = git
+        @config = config
+        @fetch = fetch
+        @clock = clock
+      end
+
+      # fetches: claims a fetch and knows the last (Persistence::TrunkFetches). Yields a fetch's pid.
+      # Nil when the project checks no trunk.
+      def start(sha, fetches, &)
+        setting = @config.trunk
+        return nil if setting == "none"
+
+        ref = Resolver.pick(setting, @git.refs)
+        started = fetch?(ref, fetches) ? @fetch.start(ref, &) : nil
+        Pending.new(sha: sha, ref: ref, started: started, last: fetches.last)
+      end
+
+      # What to tell the developer of a project's first fetch, so it never comes as a surprise; else nil.
+      def notice(pending)
+        return nil unless pending&.started && pending.last.nil?
+
+        Description.first_fetch(pending.ref, @config.trunk_fetch)
+      end
+
+      def finish(pending)
+        return Result.new(check: unknown(pending.sha, "no trunk found; #{SET_IT}"), fetched: nil) unless pending.ref
+
+        fetched = pending.started && @fetch.finish(pending.started, deadline: FETCH_DEADLINE)
+        Result.new(check: against(pending, fetched), fetched: fetched)
+      end
+
+      # heads: { commit => trunk SHA it was last checked against }. Each checked
+      # against another SHA is checked against `tip`, which it hasn't met yet.
+      def recheck(heads, tip)
+        heads.reject { |_, sha| sha == tip.sha }.keys.map do |commit|
+          Check.new(commit: commit, tip: tip, merge: MergeCheck.new(@git).merge(commit, tip.sha, tip.ref))
+        end
+      end
+
+      private
+
+      def fetch?(ref, fetches)
+        interval = @config.trunk_fetch
+        ref&.remote && interval && fetches.claim(now: @clock.call, interval: interval)
+      end
+
+      def against(pending, fetched)
+        ref = pending.ref
+        tip = TipReader.new(@git, @clock).tip(ref, fetching: !@config.trunk_fetch.nil?, fetched: fetched,
+                                                   last: pending.last)
+        return unknown(pending.sha, "#{ref} doesn't exist; #{SET_IT}") unless tip
+
+        Check.new(commit: pending.sha, tip: tip, merge: MergeCheck.new(@git).merge(pending.sha, tip.sha, ref.to_s))
+      end
+
+      def unknown(sha, reason) = Check.new(commit: sha, tip: nil, merge: Merge.unknown(reason))
+    end
+  end
+end

data/lib/fun_ci/trunk/description.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "resolver"
+
+module FunCi
+  module Trunk
+    # What `fun-ci check` says about the trunk (design.md, The
+    # trunk): which ref it is, why that one, and how fun-ci keeps it fresh,
+    # so the network access never comes as a surprise; or a warning, which
+    # never fails the check, when there is none.
+    module Description
+      WHY = { configured: "trunk: in .fun-ci/config", default: "%s's default branch",
+              usual: "the first usual trunk name on %s", local: "a local branch" }.freeze
+      NONE = "Trunk: none (trunk: none in .fun-ci/config), so runs check none."
+      NOT_FOUND = "Warning: no trunk found, so runs check none; set trunk: in .fun-ci/config"
+      UNITS = [[3600, "hour"], [60, "minute"], [1, "second"]].freeze
+
+      # interval: seconds between fetches, nil when fun-ci doesn't fetch.
+      def self.lines(setting:, interval:, refs:)
+        return [NONE] if setting == "none"
+
+        ref = Resolver.pick(setting, refs)
+        return [NOT_FOUND] unless ref
+
+        ["Trunk: #{ref} (#{WHY.fetch(Resolver.why(setting, refs)).sub("%s",
+                                                                      ref.remote.to_s)}).#{fetching(ref, interval)}"]
+      end
+
+      # What a project's first fetch says, so it never comes as a surprise.
+      def self.first_fetch(ref, interval)
+        "fun-ci: fetching #{ref} into refs/fun-ci/ now and at most every #{every(interval)}, " \
+          "touching none of your refs; set trunk_fetch: false in .fun-ci/config to stop."
+      end
+
+      def self.fetching(ref, interval)
+        return "" unless ref.remote
+        return " fun-ci doesn't fetch it (trunk_fetch: false)." unless interval
+
+        " fun-ci fetches it in the background, at most every #{every(interval)}; " \
+          "set trunk_fetch: false in .fun-ci/config to stop."
+      end
+
+      # "5 minutes", "1 hour".
+      def self.every(seconds)
+        size, unit = UNITS.find { |unit_seconds, _| (seconds % unit_seconds).zero? }
+        count = seconds / size
+        "#{count} #{unit}#{"s" unless count == 1}"
+      end
+      private_class_method :fetching
+    end
+  end
+end

data/lib/fun_ci/trunk/fetch.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "../pipeline/process_runner"
+require_relative "resolver"
+
+module FunCi
+  module Trunk
+    # How a fetch of the trunk went: nil error when it fetched.
+    Fetched = Data.define(:error)
+
+    # Fetches the trunk into a ref of fun-ci's own (architecture.md, Checking against the trunk,
+    # Keeping the trunk fresh). An empty refmap keeps git from moving the
+    # developer's remote-tracking ref too, and nothing may ask them anything:
+    # ssh runs in batch mode unless they have an ssh command of their own.
+    # Started in one thread, so its pid can be recorded, and finished in
+    # another, killed with its process group at the deadline.
+    class Fetch
+      QUIET = { "GIT_TERMINAL_PROMPT" => "0", "SSH_ASKPASS_REQUIRE" => "never", "GCM_INTERACTIVE" => "never" }.freeze
+      NO_PROMPT_SSH = 'if [ -z "$GIT_SSH_COMMAND" ] && ! git config --get core.sshCommand >/dev/null; then ' \
+                      'export GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=10"; fi; '
+      OPTIONS = %w[--quiet --no-tags --no-write-fetch-head --no-recurse-submodules --no-auto-maintenance
+                   --refmap=].freeze
+
+      def self.ref_for(ref) = "refs/fun-ci/trunk/#{ref.remote}/#{ref.branch}"
+
+      # Why a fetch failed, from what git printed: its fatal line, else its first, else that it failed.
+      def self.reason(output)
+        lines = output.lines.map(&:strip).reject(&:empty?)
+        (lines.find { |line| line.start_with?("fatal:") } || lines.first || "git fetch failed").to_s
+      end
+
+      # env: what the fetch finds in its environment besides fun-ci's own.
+      def initialize(dir, env:)
+        @launch = Pipeline::ProcessRunner::Launch.new(chdir: dir, env: QUIET.merge(env))
+        @runner = Object.new.extend(Pipeline::ProcessRunner)
+      end
+
+      # Yields the fetch's pid before it runs.
+      def start(ref, &) = @runner.start_process(command(ref), @launch, &)
+
+      def finish(started, deadline:, timer: Pipeline::ProcessRunner::BUDGET)
+        output, status, over = @runner.await_process(started, deadline, launch: @launch, timer: timer)
+        return Fetched.new(error: "no answer within #{deadline} s") if over
+
+        Fetched.new(error: status.success? ? nil : self.class.reason(output))
+      end
+
+      private
+
+      def command(ref)
+        refspec = "+refs/heads/#{ref.branch}:#{self.class.ref_for(ref)}"
+        fetch = Shellwords.join(["git", "fetch", *OPTIONS, ref.remote, refspec])
+        "sh -c #{Shellwords.escape("#{NO_PROMPT_SSH}exec #{fetch}")}"
+      end
+    end
+  end
+end

data/lib/fun_ci/trunk/first_fetch.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../setup/project_config"
+require_relative "../persistence/trunk_fetches"
+require_relative "description"
+require_relative "git"
+require_relative "resolver"
+
+module FunCi
+  module Trunk
+    # What to say before a project's first fetch of its trunk, where the
+    # developer sees it (architecture.md, Checking against the trunk):
+    # the post-commit hook's run is in the background, and what it prints is not.
+    module FirstFetch
+      # Nil unless the project fetches a remote trunk and never has yet; git lists
+      # the project's refs.
+      def self.notice(project, db, git: Git.new(project))
+        config = Setup::ProjectConfig.new(project)
+        interval = config.trunk_fetch
+        return nil if interval.nil? || config.trunk == "none" || Persistence::TrunkFetches.new(db, project).last
+
+        ref = Resolver.pick(config.trunk, git.refs)
+        ref&.remote ? Description.first_fetch(ref, interval) : nil
+      end
+    end
+  end
+end

data/lib/fun_ci/trunk/git.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require_relative "../pipeline/process_runner"
+require "tmpdir"
+require_relative "../pipeline/git_environment"
+require_relative "merge_check"
+require_relative "resolver"
+
+module FunCi
+  module Trunk
+    # The git the trunk check asks, in the project's repository. A merge
+    # writes its tree and conflicted blobs into a scratch object directory
+    # that borrows the repository's objects, so the repository keeps nothing.
+    class Git
+      REF_PREFIXES = %w[refs/heads/ refs/remotes/].freeze
+
+      # timer: whether a merge finished within its budget (ProcessRunner's timer), for tests to decide.
+      def initialize(dir, timer: Pipeline::ProcessRunner::BUDGET)
+        @dir = dir
+        @timer = timer
+      end
+
+      def counts(commit, trunk) = run("rev-list", "--left-right", "--count", "#{commit}...#{trunk}")
+
+      def merge_tree(commit, trunk) = scratch { |env| merged(commit, trunk, env) }
+
+      # The merge's messages and each conflicted file as the merge leaves it.
+      def explain(commit, trunk)
+        scratch do |env|
+          output = MergeOutput.parse(merged(commit, trunk, env).out)
+          files = output.paths.to_h { |path| [path, run("cat-file", "-p", "#{output.tree}:#{path}", env: env).out] }
+          Explained.new(messages: output.messages, files: files)
+        end
+      end
+
+      # The repository's top directory, or nil outside one.
+      def toplevel
+        answer = run("rev-parse", "--show-toplevel")
+        answer.status.zero? ? answer.out.strip : nil
+      end
+
+      def version = run("--version").out[/\d+(?:\.\d+)+/]
+
+      def refs
+        remotes = run("remote").out.split
+        Refs.new(remotes: remotes, branches: branches, heads: remotes.to_h { |remote| [remote, head(remote)] }.compact)
+      end
+
+      # The commit a ref names, or nil when there is no such ref.
+      def rev(ref)
+        answer = run("rev-parse", "--verify", "--quiet", "#{ref}^{commit}")
+        answer.status.zero? ? answer.out.strip : nil
+      end
+
+      # When the ref last moved, from its reflog, or else when its commit was made.
+      def moved_at(ref)
+        moved = run("reflog", "-1", "--date=unix", "--format=%gd", ref).out[/@\{(\d+)\}/, 1]
+        Time.at(Integer(moved || run("log", "-1", "--format=%ct", ref).out.strip))
+      end
+
+      private
+
+      def branches
+        names = run("for-each-ref", "--format=%(refname)", *REF_PREFIXES).out.split("\n")
+        names.reject { |name| name.end_with?("/HEAD") }.map { |name| strip_prefix(name) }
+      end
+
+      def strip_prefix(name) = REF_PREFIXES.reduce(name) { |short, prefix| short.delete_prefix(prefix) }
+
+      def head(remote)
+        answer = run("symbolic-ref", "--quiet", "refs/remotes/#{remote}/HEAD")
+        answer.status.zero? ? answer.out.strip.delete_prefix("refs/remotes/#{remote}/") : nil
+      end
+
+      # Within the check's budget, killed with its process group past it; what it
+      # prints to stderr comes with what it prints, which is all git says when it fails.
+      def merged(commit, trunk, env)
+        command = Shellwords.join(["git", "merge-tree", "--write-tree", "--name-only", "--messages", commit, trunk])
+        launch = Pipeline::ProcessRunner::Launch.new(chdir: @dir, env: env)
+        output, status, over = Object.new.extend(Pipeline::ProcessRunner)
+                                     .run_process_with_timeout(command, CHECK_BUDGET, launch: launch, timer: @timer)
+        over ? MergeCheck::OVER_BUDGET : MergeCheck::Answer.new(status: status.exitstatus, out: output, err: output)
+      end
+
+      # Yields an environment whose new objects go to a scratch directory that is gone afterwards.
+      def scratch
+        Dir.mktmpdir("fun-ci-merge") do |dir|
+          yield({ "GIT_OBJECT_DIRECTORY" => dir, "GIT_ALTERNATE_OBJECT_DIRECTORIES" => objects })
+        end
+      end
+
+      def objects = File.expand_path(File.join(run("rev-parse", "--git-common-dir").out.strip, "objects"), @dir)
+
+      def run(*, env: {})
+        out, err, status = Open3.capture3(Pipeline::GitEnvironment::CLEAN.merge(env), "git", *, chdir: @dir)
+        MergeCheck::Answer.new(status: status.exitstatus, out: out, err: err)
+      end
+    end
+  end
+end

data/lib/fun_ci/trunk/local.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../setup/project_config"
+require_relative "checker"
+require_relative "git"
+require_relative "tip_reader"
+
+module FunCi
+  module Trunk
+    # The trunk as the project's git has it now, for the agent commands
+    # (architecture.md, Checking against the trunk): where
+    # its ref points, read the way a check reads it, and a check against it
+    # that never fetches, since a command an agent runs must not wait on the network.
+    class Local
+      # Lets no fetch go, and knows the last one.
+      NoFetch = Data.define(:fetches)
+
+      # Reopened rather than given as a block to Data.define, so tools that
+      # read the source (mutineer) see these as NoFetch's methods.
+      class NoFetch
+        def claim(**) = nil
+        def last = fetches.last
+      end
+
+      # dir: the project's directory, or one inside it.
+      def initialize(dir)
+        @dir = dir
+      end
+
+      # The SHA the tip's trunk points at now, or nil when it is gone.
+      def now_at(tip)
+        ref = Ref.new(remote: tip.remote, branch: tip.branch)
+        TipReader.new(git, -> { Time.now }).tip(ref, fetching: !config.trunk_fetch.nil?)&.sha
+      end
+
+      # fetches: the project's (Persistence::TrunkFetches), for when the last fetch was.
+      def check(sha, fetches)
+        checker = Checker.for(root)
+        pending = checker.start(sha, NoFetch.new(fetches: fetches))
+        pending && checker.finish(pending).check
+      end
+
+      # The conflict between the commit and the tip it was checked against, merged
+      # again; nil when either is gone from the repository (a force push, then gc).
+      def explain(sha, tip)
+        return nil unless git.rev(sha) && git.rev(tip.sha)
+
+        git.explain(sha, tip.sha)
+      end
+
+      private
+
+      def root = @root ||= Git.new(@dir).toplevel || @dir
+      def git = Git.new(root)
+      def config = Setup::ProjectConfig.new(root)
+    end
+  end
+end