fun_ci 1.2.0 → 2.0.0

data/lib/fun_ci/cli_help.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FunCi
+  # What `fun-ci --help` and `fun-ci --version` print; each answers the exit code.
+  module CliHelp
+    def self.help(out)
+      out.puts TEXT
+      0
+    end
+
+    def self.version(out)
+      out.puts "fun-ci #{FunCi::VERSION}"
+      0
+    end
+
+    TEXT = <<~HELP
+      fun-ci - Opinionated, local-first CI for your projects
+
+      Usage:
+        fun-ci <command> [options]
+
+      Commands:
+        trigger        Run CI pipeline for a commit
+        console        Launch the admin TUI dashboard
+        init           Initialize .fun-ci/ with template scripts
+        install-hooks  Install post-commit and pre-push git hooks
+        check          Verify project setup
+        prune          Remove fun-ci's worktrees when no pipeline is running
+        status         Say where a commit's run stands, as an exit code an agent can act on
+        runs           List this project's recent runs, newest first
+        wait           Wait for a commit's verdict, then exit with it as status does
+        events         Print this project's runs' events as JSON lines
+        why            Print everything kept about why a commit's stage failed
+        extract        Try a stage's evidence extractors on a saved output
+
+      Options:
+        -h, --help     Show this help message
+        --version      Show version
+
+      Trigger options:
+        --background   Run the pipeline in the background and return at once
+
+      Agent options:
+        --need LEVEL   (status, wait, why) What must pass: build, fast (default) or all
+        --within TIME  (wait) Give up undecided after 30, 30s or 5m
+        --follow-branch  (wait) Move on to the newer commit that superseded the run
+        -n N           (runs) How many runs to list (default 10)
+        --branch NAME  (runs) Only runs on this branch
+        --follow       (events) Keep printing events as they happen, until stopped
+        --only failures  (events) Print only failed stages and superseded runs
+        --json         Print JSON instead of text (events always print JSON lines)
+        Exit codes: 0 passed, 1 failed, 2 over budget, 3 undecided,
+        4 superseded, 5 no run, 64 usage error
+
+      Init options:
+        --everything   Run init + install-hooks + check in one step
+
+      Examples:
+        fun-ci init --everything
+        fun-ci trigger abc1234 main
+        fun-ci trigger --background abc1234 main
+        fun-ci console
+    HELP
+  end
+end

data/lib/fun_ci/console/board_data.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../persistence/pipeline_run"
+require_relative "../persistence/stage_job"
+require_relative "../persistence/active_runs"
+require_relative "../pipeline/run_canceller"
+require_relative "streak_counter"
+
+module FunCi
+  module Console
+    class BoardData
+      def initialize(db, limit: 15, page_size: nil, run_canceller: Pipeline::RunCanceller.new)
+        @db = db
+        @page_size = page_size || limit
+        @limit = @page_size
+        @run_canceller = run_canceller
+      end
+
+      def load_more
+        @limit += @page_size
+      end
+
+      # Pages by `page_size` from now on, loading at least one such page.
+      def resize(page_size)
+        @page_size = page_size
+        @limit = [@limit, page_size].max
+      end
+
+      # Whether the store holds runs beyond those `runs` loads.
+      def more?
+        Persistence::PipelineRun.recent(@db, limit: @limit + 1).size > @limit
+      end
+
+      # Records failed each slow suite whose process died (acceptance-tests.md, AT-8.3).
+      def record_dead_slow_suites = @run_canceller.record_dead(@db)
+
+      def runs
+        pipeline_runs = Persistence::PipelineRun.recent(@db, limit: @limit)
+        pipeline_runs.map { |run| enrich_with_stages(run) }
+      end
+
+      def streak
+        pipeline_runs = Persistence::PipelineRun.recent(@db, limit: @limit)
+        StreakCounter.count(pipeline_runs)
+      end
+
+      # Stops the run's processes, then records it cancelled. A run that has
+      # finished meanwhile is left as it is.
+      def cancel_run(run_id)
+        Persistence::ActiveRuns.with_id(@db, run_id).each { |run| @run_canceller.cancel(@db, run) }
+      end
+
+      private
+
+      def enrich_with_stages(run)
+        run.merge(stages: Persistence::StageJob.for_run(@db, run[:id]).map { |job| stage(job) })
+      end
+
+      def stage(job)
+        { stage: job[:stage], status: job[:status], duration: Persistence::StageJob.elapsed_duration(job),
+          started_at: job[:started_at], finished_order: job[:finished_order] }
+      end
+    end
+  end
+end

data/lib/fun_ci/console/board_heartbeat.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    # The port to the renderer, noting in the console log every EVERY seconds
+    # how many boards went out and the newest run on the last, so a console
+    # that stops showing new runs leaves a record of what Ruby was sending.
+    class BoardHeartbeat
+      EVERY = 600
+
+      # `clock` answers seconds; only differences between its answers count.
+      def initialize(port, log:, clock:)
+        @port = port
+        @log = log
+        @clock = clock
+        @beat = { since: clock.call, boards: 0 }
+      end
+
+      def write(message)
+        @port.write(message)
+        note(message) if message[:t] == "board"
+      end
+
+      private
+
+      def note(board)
+        now = @clock.call
+        @beat = { since: @beat[:since], boards: @beat[:boards] + 1 }
+        tell(now, board) if now - @beat[:since] >= EVERY
+      end
+
+      def tell(now, board)
+        @log.write("#{@beat[:boards]} boards in the last #{(now - @beat[:since]).round} s; #{newest(board[:runs])}")
+        @beat = { since: now, boards: 0 }
+      end
+
+      def newest(runs) = runs.empty? ? "the last showed no runs" : "the newest run on the last: #{runs.first[:id]}"
+    end
+  end
+end

data/lib/fun_ci/console/console_events.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "stage_events"
+require_relative "milestone_events"
+
+module FunCi
+  module Console
+    # Every protocol `event` since the last poll of the runs: the stages that
+    # changed (for the effects on a stage's column), then the milestones the
+    # runs reached (for the header).
+    class ConsoleEvents
+      def initialize
+        @stages = StageEvents.new
+        @milestones = MilestoneEvents.new
+      end
+
+      def since_last(runs) = @stages.since_last(runs) + @milestones.since_last(runs)
+    end
+  end
+end

data/lib/fun_ci/console/console_log.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+
+module FunCi
+  module Console
+    # The project's .fun-ci/console.log, where the console notes what the
+    # renderer got wrong: the terminal is the renderer's, so stderr would
+    # draw over it.
+    class ConsoleLog
+      attr_reader :path
+
+      def initialize(project_dir:, clock:)
+        @path = File.join(project_dir, ".fun-ci", "console.log")
+        @clock = clock
+      end
+
+      # Appends `text` as one line, stamped with the clock's time in UTC.
+      def write(text)
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, "a") { |file| file.puts("#{@clock.call.utc.iso8601} #{text}") }
+      end
+    end
+  end
+end

data/lib/fun_ci/console/console_loop.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "renderer_process"
+
+module FunCi
+  module Console
+    # The console's conversation with its renderer: each line the renderer
+    # writes goes to the session, and whenever the renderer has been quiet for
+    # POLL_SECONDS the session polls the runs, so what the database holds
+    # reaches the screen without waiting for a key.
+    class ConsoleLoop
+      POLL_SECONDS = 1
+
+      def initialize(session:, renderer:)
+        @session = session
+        @renderer = renderer
+      end
+
+      # :quit once the session has quit, :ended if the renderer went away first.
+      def run
+        @session.start
+        loop do
+          return :quit if @session.finished?
+          return :ended unless step
+        end
+      end
+
+      private
+
+      # False once the renderer has closed its output.
+      def step
+        line = @renderer.next_line(patience: POLL_SECONDS)
+        @session.receive(line) if line
+        !line.nil?
+      rescue RendererProcess::Silent
+        @session.refresh
+        true
+      end
+    end
+  end
+end

data/lib/fun_ci/console/console_session.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "console_state"
+require_relative "view"
+require_relative "key_handler"
+require_relative "board_heartbeat"
+
+module FunCi
+  module Console
+    # The console's half of the renderer conversation (renderer-protocol.md):
+    # it reads the renderer's lines and writes protocol messages to the port.
+    # Ruby decides what is true here; drawing it is the renderer's job.
+    class ConsoleSession
+      VERSION = 1
+      HANDLERS = { "ready" => :ready, "resize" => :resize, "key" => :key, "error" => :renderer_error }.freeze
+
+      # `log` takes what the renderer got wrong (ConsoleLog), and every ten
+      # minutes what the session sent it (BoardHeartbeat).
+      def self.build(board_data:, port:, clock:, log:)
+        view = View.new(key_handler: KeyHandler.new(board_data: board_data))
+        new(state: ConsoleState.new(board_data: board_data, view: view, clock: clock),
+            port: BoardHeartbeat.new(port, log: log, clock: clock), log: log)
+      end
+
+      def initialize(state:, port:, log:)
+        @state = state
+        @port = port
+        @log = log
+        @phase = :starting
+      end
+
+      def start = @port.write(t: "hello", v: VERSION)
+
+      # A line the renderer wrote. One it got wrong is logged, never raised.
+      def receive(line)
+        message = JSON.parse(line)
+        message.is_a?(Hash) ? handle(message) : @log.write("the renderer sent a line that is not a message: #{line}")
+      rescue JSON::ParserError
+        @log.write("the renderer sent a line that is not JSON: #{line.inspect}")
+      end
+
+      # Sends what the runs look like now, as each poll does; nothing before
+      # the renderer is ready, since its size decides the page.
+      def refresh = @phase == :running && send_updates
+
+      def finished? = @phase == :finished
+
+      private
+
+      def handle(message)
+        handler = HANDLERS[message["t"]]
+        return @log.write("the renderer sent a message of unknown type #{message["t"].inspect}") unless handler
+
+        send(handler, message)
+      end
+
+      def ready(message)
+        @phase = :running
+        resize(message)
+      end
+
+      def resize(message)
+        @state.resize(message["rows"])
+        send_updates
+      end
+
+      def key(message)
+        return send_updates unless @state.press(message["key"]) == :quit
+
+        @phase = :finished
+        @port.write(t: "quit")
+      end
+
+      def renderer_error(message)
+        @log.write("the renderer reported a #{message["code"]} error: #{message["detail"]}")
+      end
+
+      def send_updates = @state.updates.each { |update| @port.write(update) }
+    end
+  end
+end

data/lib/fun_ci/console/console_state.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "run_message"
+require_relative "console_events"
+
+module FunCi
+  module Console
+    # What the console shows: the page of runs BoardData reads that the View
+    # puts on screen, and the clock's time, as a protocol `board` message,
+    # after the `event`s for what changed since the last one.
+    class ConsoleState
+      KEYS = { "up" => :up, "down" => :down, "esc" => :escape, "ctrl_c" => "q", "enter" => :enter }.freeze
+
+      def initialize(board_data:, view:, clock:)
+        @board_data = board_data
+        @view = view
+        @clock = clock
+        @events = ConsoleEvents.new
+      end
+
+      # :quit when the key ends the session.
+      def press(key) = @view.press(KEYS.fetch(key, key))
+
+      # Pages for a terminal of `rows`.
+      def resize(rows) = @board_data.resize(@view.resize(rows))
+
+      def updates
+        @board_data.record_dead_slow_suites
+        runs = @board_data.runs
+        [*@events.since_last(runs), board(runs)]
+      end
+
+      private
+
+      def board(runs)
+        page = @view.page(runs, more: @board_data.more?)
+        { t: "board", now: @clock.call.to_i, streak: @board_data.streak, **page,
+          runs: page[:runs].map { |run| RunMessage.from(run) } }
+      end
+    end
+  end
+end

data/lib/fun_ci/console/key_handler.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    # What a key means for the runs BoardData loads: moving the cursor,
+    # quitting, and cancelling the run under the cursor (a running one after
+    # the user confirms with `y`).
+    class KeyHandler
+      CONFIRMATION_ANSWERS = ["y", "n", :escape].freeze
+
+      attr_reader :cursor_index
+
+      def initialize(board_data:)
+        @board_data = board_data
+        @confirm_cancel = nil
+      end
+
+      # :quit when the key ends the session.
+      def handle_key(key)
+        return confirm(key) if @confirm_cancel
+        return :quit if key == "q"
+
+        act(key)
+      end
+
+      def confirming?
+        !@confirm_cancel.nil?
+      end
+
+      def confirmation_run
+        @confirm_cancel
+      end
+
+      private
+
+      def act(key)
+        case key
+        when "j", :down then move_cursor_down
+        when "k", :up then move_cursor_up
+        when "c" then initiate_cancel
+        end
+      end
+
+      # Onto the last run loaded, which loads the next page.
+      def move_cursor_down
+        last = @board_data.runs.length - 1
+        return if last.negative?
+        return @cursor_index = 0 if @cursor_index.nil?
+        return unless @cursor_index < last
+
+        @cursor_index += 1
+        @board_data.load_more if @cursor_index == last
+      end
+
+      def move_cursor_up
+        @cursor_index -= 1 if @cursor_index&.positive?
+      end
+
+      def initiate_cancel
+        run = @cursor_index && @board_data.runs[@cursor_index]
+        return unless run
+
+        @board_data.cancel_run(run[:id]) if run[:status] == "scheduled"
+        @confirm_cancel = run if run[:status] == "running"
+      end
+
+      def confirm(key)
+        @board_data.cancel_run(@confirm_cancel[:id]) if key == "y"
+        @confirm_cancel = nil if CONFIRMATION_ANSWERS.include?(key)
+      end
+    end
+  end
+end

data/lib/fun_ci/console/launcher.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "board_data"
+require_relative "console_log"
+require_relative "console_loop"
+require_relative "console_session"
+require_relative "renderer_process"
+require_relative "stop_report"
+
+module FunCi
+  module Console
+    # `fun-ci console`: starts the renderer, which draws on the terminal, and
+    # talks to it about the runs in `db` until the user quits. The renderer's
+    # stderr, what it gets wrong, and when and why the console started and
+    # stopped go to the project's .fun-ci/console.log.
+    module Launcher
+      PATIENCE = 5
+
+      # The exit status: 0 once the user has quit, 1 if the renderer stopped
+      # or the console failed.
+      def self.run(renderer:, db:, project_dir:, stderr:)
+        log = ConsoleLog.new(project_dir: project_dir, clock: -> { Time.now })
+        FileUtils.mkdir_p(File.dirname(log.path))
+        process = RendererProcess.start([renderer], err: [log.path, "a"])
+        log.write("console started; the renderer is pid #{process.pid}")
+        outcome = converse(process, BoardData.new(db), log)
+        StopReport.new(outcome, process.finish(patience: PATIENCE)).tell(log, stderr)
+      end
+
+      # :quit, :ended, or the error that ended the conversation.
+      def self.converse(process, board_data, log)
+        session = ConsoleSession.build(board_data: board_data, port: process, clock: -> { Time.now }, log: log)
+        ConsoleLoop.new(session: session, renderer: process).run
+      rescue Errno::EPIPE
+        :ended
+      rescue StandardError => e
+        e
+      end
+      private_class_method :converse
+    end
+  end
+end

data/lib/fun_ci/console/milestone_events.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "milestones"
+
+module FunCi
+  module Console
+    # The protocol `event` for each milestone a run reached since the last
+    # poll (acceptance-tests.md, AT-7.2). None on the first poll, which has
+    # nothing to compare with; none for a cancelled run; and none once a run
+    # has failed, so a run fails once however many of its stages fail; and
+    # none for an older run that paging brings onto the board.
+    class MilestoneEvents
+      def initialize
+        @previous = nil
+      end
+
+      def since_last(runs)
+        events = @previous ? runs.flat_map { |run| new_milestones(run) } : []
+        @previous = runs.to_h { |run| [run[:id], Milestones.of(run)] }
+        events
+      end
+
+      private
+
+      def new_milestones(run)
+        return [] unless news?(run)
+
+        before = @previous.fetch(run[:id], [])
+        return [] if before.include?("run_failed") || run[:status] == "cancelled"
+
+        (Milestones.of(run) - before).map { |name| { t: "event", name: name, run_id: run[:id] } }
+      end
+
+      # A run the last poll saw, or one newer than all it saw; run ids only grow.
+      def news?(run) = @previous.key?(run[:id]) || run[:id] > @previous.keys.max.to_i
+    end
+  end
+end

data/lib/fun_ci/console/milestones.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    # The milestones a run has reached, in the order it reached them
+    # (design.md, A run's states): its stages in the order they finished (a
+    # stage recorded before that order was kept counts as unordered, and lint,
+    # build, fast is the fallback), then the run passing or failing.
+    module Milestones
+      STAGES = %w[lint build fast].freeze
+      OUTCOMES = { "completed" => ["run_passed"], "failed" => ["run_failed"] }.freeze
+
+      def self.of(run)
+        passed = run[:stages].select { |stage| stage[:status] == "completed" && STAGES.include?(stage[:stage]) }
+        passed.sort_by { |stage| order(stage) }.map { |stage| "#{stage[:stage]}_passed" } +
+          OUTCOMES.fetch(run[:status], [])
+      end
+
+      def self.order(stage)
+        [stage[:finished_order].to_i, STAGES.index(stage[:stage])]
+      end
+      private_class_method :order
+    end
+  end
+end

data/lib/fun_ci/console/renderer_lookup.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    # Where the renderer binary is (architecture.md, Distribution): the one
+    # FUN_CI_RENDERER names, else the one a platform gem bundles in libexec/,
+    # else the first on PATH.
+    class RendererLookup
+      class Missing < StandardError; end
+
+      NAME = "fun-ci-renderer"
+      HOW_TO_GET_ONE = "fun-ci console needs its renderer, #{NAME}, and this installation has none. " \
+                       "Install it with `cargo install #{NAME}`, or set FUN_CI_RENDERER to its path.".freeze
+
+      # The installed gem's libexec/, where a platform gem puts the renderer.
+      LIBEXEC = File.expand_path("../../../libexec", __dir__)
+
+      def self.default = new(env: ENV, libexec: LIBEXEC, executable: method(:runnable?))
+
+      # Whether `path` is a file this user may run.
+      def self.runnable?(path) = File.file?(path) && File.executable?(path)
+
+      def initialize(env:, libexec:, executable:)
+        @env = env
+        @libexec = libexec
+        @executable = executable
+      end
+
+      # The renderer's path. Raises Missing, saying how to get one, if none is found.
+      def path
+        named = @env["FUN_CI_RENDERER"].to_s
+        return runnable(named) unless named.empty?
+
+        candidates.find { |candidate| @executable.call(candidate) } || raise(Missing, HOW_TO_GET_ONE)
+      end
+
+      private
+
+      def runnable(named)
+        return named if @executable.call(named)
+
+        raise Missing, "FUN_CI_RENDERER names #{named}, which is not a program fun-ci can run."
+      end
+
+      def candidates
+        on_path = @env.fetch("PATH", "").split(File::PATH_SEPARATOR).reject(&:empty?)
+        [@libexec, *on_path].map { |dir| File.join(dir, NAME) }
+      end
+    end
+  end
+end

data/lib/fun_ci/console/renderer_process.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FunCi
+  module Console
+    # The renderer as a child process (renderer-protocol.md): messages go to
+    # its stdin as JSON lines and its lines come from its stdout. No wait on
+    # it is endless, and one that will not exit is stopped.
+    class RendererProcess
+      class Silent < StandardError; end
+
+      # `err` takes the renderer's stderr, which is for diagnostics only.
+      def self.start(command, err: File::NULL)
+        input, to_renderer = IO.pipe
+        from_renderer, output = IO.pipe
+        pid = Process.spawn(*command, in: input, out: output, err: err)
+        [input, output].each(&:close)
+        new(waiter: Process.detach(pid), input: to_renderer, output: from_renderer)
+      end
+
+      def initialize(waiter:, input:, output:)
+        @waiter = waiter
+        @input = input
+        @output = output
+      end
+
+      def pid = @waiter.pid
+
+      def write(message) = @input.puts(JSON.generate(message))
+
+      # The renderer's next line, or nil once it has closed its output.
+      # Raises Silent when nothing comes within `patience` seconds.
+      def next_line(patience:)
+        raise Silent, "no word from the renderer in #{patience} s" unless @output.wait_readable(patience)
+
+        @output.gets&.chomp
+      end
+
+      # Closes the renderer's input, which it takes as `quit`, and answers how
+      # it exited; one still running after `patience` seconds is stopped.
+      def finish(patience:)
+        @input.close unless @input.closed?
+        stop(patience) unless @waiter.join(patience)
+        @output.close
+        @waiter.value
+      end
+
+      private
+
+      # SIGTERM first, on which the renderer restores the terminal.
+      def stop(patience)
+        Process.kill("TERM", @waiter.pid)
+        Process.kill("KILL", @waiter.pid) unless @waiter.join(patience)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end