fun_ci 2.0.1 → 2.1.0

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/gradle_linter_detector.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Setup
+    # The source linter a Gradle build applies, whose task lint.sh runs. Lint
+    # runs beside the build on the source alone (design.md, Stages side by
+    # side), so only linters that compile nothing are named here.
+    class GradleLinterDetector
+      LINTERS = [
+        { plugin: "org.jlleitschuh.gradle.ktlint", command: "./gradlew ktlintCheck" },
+        { plugin: "com.diffplug.spotless", command: "./gradlew spotlessCheck" },
+        { plugin: "io.gitlab.arturbosch.detekt", command: "./gradlew detekt" }
+      ].freeze
+
+      def initialize(build_file)
+        @build_file = build_file
+      end
+
+      # The linter's command, or nil for a build that applies none.
+      def lint_command = LINTERS.find { |linter| @build_file.include?(linter[:plugin]) }&.fetch(:command)
+    end
+  end
+end

data/lib/fun_ci/setup/installer.rb

@@ -2,12 +2,18 @@
 
 require_relative "project_detector"
 require_relative "template_writer"
-require_relative "maven_linter_detector"
+require_relative "lint_detection"
 require_relative "agent_instructions"
 
 module FunCi
   module Setup
     class Installer
+      # Which stages run side by side, and so what each may touch (design.md,
+      # Stages side by side).
+      SIDE_BY_SIDE = ["lint.sh runs beside build.sh, so it reads the source alone.",
+                      "Then fast.sh runs beside slow.sh, both on what build.sh built: have build.sh " \
+                      "compile everything they need, test code included."].freeze
+
       def self.run(project_root:, stdout: $stdout)
         new(project_root: project_root, stdout: stdout).run
       end
@@ -51,21 +57,15 @@ module FunCi
 
       def write_templates(detected)
         @stdout.puts "Detected: #{detected.to_s.tr("_", " ")}"
-        TemplateWriter.new(detected, @project_root, lint_override: detect_maven_linter(detected)).write
-        report("Created .fun-ci/ with template scripts.", 0)
+        TemplateWriter.new(detected, @project_root, lint_override: LintDetection.command(detected, @project_root)).write
+        @stdout.puts "Created .fun-ci/ with template scripts.", *SIDE_BY_SIDE
+        0
       end
 
       def report(message, exit_code)
         @stdout.puts message
         exit_code
       end
-
-      def detect_maven_linter(detected)
-        return nil unless detected == :jvm_maven
-
-        command = MavenLinterDetector.new(File.read(File.join(@project_root, "pom.xml"))).lint_command
-        command == MavenLinterDetector::DEFAULT_COMMAND ? nil : command
-      end
     end
   end
 end

data/lib/fun_ci/setup/lint_detection.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "maven_linter_detector"
+require_relative "gradle_linter_detector"
+
+module FunCi
+  module Setup
+    # The lint command init writes in place of the template's, from the source
+    # linter the project's build configures; nil keeps the template's.
+    module LintDetection
+      GRADLE_FILES = %w[build.gradle.kts build.gradle].freeze
+
+      def self.command(detected, project_root)
+        case detected
+        when :jvm_maven then maven(project_root)
+        when :jvm_gradle_kotlin, :jvm_gradle_groovy then gradle(project_root)
+        end
+      end
+
+      def self.maven(project_root)
+        command = MavenLinterDetector.new(File.read(File.join(project_root, "pom.xml"))).lint_command
+        command == MavenLinterDetector::DEFAULT_COMMAND ? nil : command
+      end
+
+      def self.gradle(project_root)
+        file = GRADLE_FILES.map { File.join(project_root, _1) }.find { File.exist?(_1) }
+        file && GradleLinterDetector.new(File.read(file)).lint_command
+      end
+      private_class_method :maven, :gradle
+    end
+  end
+end

data/lib/fun_ci/setup/maven_linter_detector.rb

@@ -2,16 +2,18 @@
 
 module FunCi
   module Setup
+    # The linter a POM configures, whose goal lint.sh runs. Lint runs beside the
+    # build on the source alone (design.md, Stages side by side), so linters that
+    # read compiled classes, such as spotbugs, are left to build.sh or fast.sh.
     class MavenLinterDetector
       LINTERS = [
         { artifact_id: "detekt-maven-plugin", command: "mvn detekt:check" },
         { artifact_id: "ktlint-maven-plugin", command: "mvn ktlint:check" },
         { artifact_id: "maven-checkstyle-plugin", command: "mvn checkstyle:check" },
-        { artifact_id: "spotbugs-maven-plugin", command: "mvn spotbugs:check" },
         { artifact_id: "maven-pmd-plugin", command: "mvn pmd:check" }
       ].freeze
 
-      DEFAULT_COMMAND = "mvn verify -DskipTests"
+      DEFAULT_COMMAND = "mvn validate"
 
       def initialize(pom_content)
         @pom_content = pom_content

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/stage_templates/managed.rb

@@ -6,18 +6,23 @@ module FunCi
   module Setup
     # Stacks that run on a virtual machine: the JVM, .NET, the BEAM and Dart's.
     module StageTemplates
-      GRADLE = stages("./gradlew check -x test", "./gradlew assemble", "./gradlew test", "./gradlew integrationTest")
-               .freeze
+      NO_GRADLE_LINTER = 'echo "No source linter in the build: put ktlint, spotless or detekt in .fun-ci/lint.sh"'
+
+      GRADLE = stages(NO_GRADLE_LINTER, "./gradlew assemble testClasses",
+                      "./gradlew test", "./gradlew integrationTest").freeze
 
       MANAGED = {
         jvm_gradle_kotlin: GRADLE,
         jvm_gradle_groovy: GRADLE,
-        jvm_maven: stages("mvn verify -DskipTests", "mvn compile", "mvn test", "mvn verify"),
-        dotnet: stages("dotnet format --verify-no-changes", "dotnet build",
-                       'dotnet test --filter "Category!=Slow"', 'dotnet test --filter "Category=Slow"'),
-        elixir_mix: stages("mix format --check-formatted", "mix deps.get && mix compile",
+        jvm_maven: stages("mvn validate", "mvn test-compile", "mvn surefire:test",
+                          "mvn failsafe:integration-test failsafe:verify"),
+        dotnet: stages("dotnet format whitespace --folder --verify-no-changes", "dotnet build",
+                       'dotnet test --no-build --filter "Category!=Slow"',
+                       'dotnet test --no-build --filter "Category=Slow"'),
+        elixir_mix: stages("mix format --check-formatted", "mix deps.get && MIX_ENV=test mix compile",
                            "mix test --exclude slow", "mix test --only slow"),
-        dart: stages("dart analyze", "dart pub get", "dart test --exclude-tags slow", "dart test --tags slow")
+        dart: stages("dart analyze", "dart pub get --precompile", "dart test --exclude-tags slow",
+                     "dart test --compiler source --tags slow")
       }.freeze
     end
   end

data/lib/fun_ci/setup/stage_templates/native.rb

@@ -15,7 +15,7 @@ module FunCi
                            "cargo test", "cargo test -- --ignored"),
         go: stages("go vet ./...", "go build ./...", "go test -short ./...", "go test ./..."),
         swift: stages("swift format lint --recursive --strict .", "swift build --build-tests",
-                      "swift test --skip Slow", "swift test --filter Slow"),
+                      "swift test --skip-build --skip Slow", "swift test --skip-build --filter Slow"),
         cmake: stages(CLANG_FORMAT, "cmake -S . -B build && cmake --build build",
                       "#{CTEST} -LE slow", "#{CTEST} -L slow"),
         make: stages("make lint", "make", "make test", "make test-slow")

data/lib/fun_ci/setup/stage_templates/shell.rb

@@ -4,11 +4,20 @@ module FunCi
   module Setup
     # What every stack's stage scripts are made of.
     module StageTemplates
-      def self.script(body) = "#!/bin/sh\n#{body}\n"
+      # What each stage runs beside, said where its script is edited (design.md,
+      # Stages side by side).
+      SIDE_BY_SIDE = {
+        "lint.sh" => "Runs beside build.sh, so it reads the source alone.",
+        "build.sh" => "Runs beside lint.sh; then fast.sh and slow.sh run side by side on what it builds.",
+        "fast.sh" => "Runs beside slow.sh, on what build.sh built.",
+        "slow.sh" => "Runs beside fast.sh, on what build.sh built."
+      }.freeze
+
+      def self.script(name, body) = "#!/bin/sh\n# #{SIDE_BY_SIDE.fetch(name)}\n#{body}\n"
 
       def self.stages(lint, build, fast, slow)
-        { "lint.sh" => lint, "build.sh" => build, "fast.sh" => fast, "slow.sh" => slow }.transform_values do |body|
-          script(body)
+        { "lint.sh" => lint, "build.sh" => build, "fast.sh" => fast, "slow.sh" => slow }.to_h do |name, body|
+          [name, script(name, body)]
         end
       end
     end

data/lib/fun_ci/setup/stage_templates.rb

@@ -18,7 +18,7 @@ module FunCi
       # { "lint.sh" => script, ... }; +lint_override+ replaces the lint command.
       def self.scripts(template_id, lint_override: nil)
         scripts = TEMPLATES.fetch(template_id)
-        lint_override ? scripts.merge("lint.sh" => script(lint_override)) : scripts
+        lint_override ? scripts.merge("lint.sh" => script("lint.sh", lint_override)) : scripts
       end
     end
   end

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