fun_ci 2.0.0-arm64-darwin

data/lib/fun_ci/agent/snapshots.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../persistence/project_runs"
+require_relative "../persistence/stage_job"
+require_relative "run_report"
+require_relative "events"
+
+module FunCi
+  module Agent
+    # Looks at the newest runs of the project git names, as `events` compares
+    # them: { run id => Events::RunState }.
+    class Snapshots
+      def initialize(db, git)
+        @db = db
+        @runs = Persistence::ProjectRuns.new(db, git.toplevel)
+      end
+
+      def take(limit:)
+        @runs.recent(limit: limit, branch: nil).to_h { |run| [run[:id], state_of(run)] }
+      end
+
+      private
+
+      def state_of(run)
+        superseded_by = run[:status] == "cancelled" ? @runs.superseded_by(run) : nil
+        Events::RunState.new(id: run[:id], sha: run[:commit_hash], branch: run[:branch], status: run[:status],
+                             finished: finished(run), superseded_by: superseded_by)
+      end
+
+      def finished(run)
+        jobs = Persistence::StageJob.for_run(@db, run[:id]).select { |job| job[:finished_order] }
+        stages = RunReport.stages(jobs).to_h { |stage| [stage.name, stage] }
+        jobs.sort_by { |job| job[:finished_order] }.map { |job| facts(stages.fetch(job[:stage])) }
+      end
+
+      def facts(stage) = { stage: stage.name, state: stage.state, seconds: stage.seconds }
+    end
+  end
+end

data/lib/fun_ci/agent/stage_summary.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # One line saying how a stage ended: its state, its exit status or the
+    # signal that ended it, how long it took and its budget, as far as known.
+    module StageSummary
+      WORDS = { "over_budget" => "ran over budget" }.freeze
+
+      def self.line(stage)
+        "#{stage.name} #{WORDS.fetch(stage.state, stage.state)}#{ending(stage)}#{took(stage)}"
+      end
+
+      def self.ending(stage)
+        return " (exit #{stage.exit_status})" if stage.exit_status
+        return " (killed by SIG#{stage.signal})" if stage.signal
+
+        ""
+      end
+
+      def self.took(stage)
+        return "" unless stage.seconds
+
+        budget = stage.budget ? ", budget #{stage.budget}s" : ""
+        " after #{stage.seconds}s#{budget}"
+      end
+      private_class_method :ending, :took
+    end
+  end
+end

data/lib/fun_ci/agent/status_command.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "command_support"
+require_relative "output"
+
+module FunCi
+  module Agent
+    # `fun-ci status [REV] [--need LEVEL] [--json]` (acceptance-tests.md, AT-9.2).
+    class StatusCommand
+      include CommandSupport
+
+      NAME = "status"
+
+      def initialize(context)
+        @context = context
+      end
+
+      def run(args)
+        options = Options.parse(args, takes: %i[need json])
+        sha = resolve(options.rev)
+        answer(sha, reports.for(sha, options.need), Output.new(@context.io.stdout, json: options.json))
+      rescue Options::Invalid => e
+        usage(e.message)
+      end
+
+      private
+
+      def answer(sha, report, output)
+        return output.unknown(sha) unless report
+
+        output.report(report)
+        ExitCode::FOR.fetch(report.verdict)
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/status_json.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "run_report"
+
+module FunCi
+  module Agent
+    # A run report as the JSON document of acceptance-tests.md, AT-9.3.
+    # Fields once published keep their names; a change bumps SCHEMA.
+    module StatusJson
+      SCHEMA = 1
+
+      def self.document(report)
+        { schema: SCHEMA, commit: { sha: report.sha, branch: report.branch, subject: report.subject },
+          need: report.need, verdict: report.verdict.to_s, stages: report.stages.map { |stage| stage(stage) },
+          superseded_by: report.superseded_by }
+      end
+
+      def self.unknown(sha) = { schema: SCHEMA, commit: { sha: sha }, verdict: "unknown" }
+
+      def self.stage(stage)
+        facts = { name: stage.name, state: stage.state, seconds: stage.seconds }
+        stage.failures.any? ? facts.merge(failures: stage.failures) : facts
+      end
+      private_class_method :stage
+    end
+  end
+end

data/lib/fun_ci/agent/status_text.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "run_report"
+require_relative "verdict"
+require_relative "digest"
+
+module FunCi
+  module Agent
+    # A run report as text: the commit, a line per stage with what went wrong
+    # in capitals, then the evidence of each needed stage that failed.
+    module StatusText
+      WORDS = { "failed" => "FAILED", "over_budget" => "OVER BUDGET" }.freeze
+
+      def self.lines(report)
+        needed = Verdict::LEVELS.fetch(report.need)
+        [header(report), *report.stages.map { |stage| stage_line(stage, needed) }, *Digest.lines(report.stages, needed),
+         *footer(report)]
+      end
+
+      def self.header(report) = %(fun-ci: #{report.sha[0, 7]} "#{report.subject}" on #{report.branch})
+
+      def self.stage_line(stage, needed)
+        seconds = stage.seconds ? format("%6.1fs", stage.seconds) : " " * 7
+        note = needed.include?(stage.name) ? "" : " (not needed)"
+        "  #{stage.name.ljust(6)} #{WORDS.fetch(stage.state, stage.state).ljust(12)}#{seconds}#{note}".rstrip
+      end
+
+      def self.footer(report)
+        return ["fun-ci why #{report.sha[0, 7]} #{report.deciding}"] if report.deciding
+        return [] unless report.verdict == :superseded && report.superseded_by
+
+        ["Superseded by #{report.superseded_by[0, 7]}."]
+      end
+      private_class_method :stage_line, :footer
+    end
+  end
+end

data/lib/fun_ci/agent/system_clock.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # The real time, for commands that wait.
+    class SystemClock
+      def now = Time.now
+      def pause(seconds) = sleep(seconds)
+    end
+  end
+end

data/lib/fun_ci/agent/verdict.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # What a run means for the level an agent needs (acceptance-tests.md,
+    # §9): the stages it needs decide, in the order they finished, and a
+    # cancelled run is superseded only while they haven't.
+    module Verdict
+      LEVELS = { "build" => %w[lint build], "fast" => %w[lint build fast], "all" => %w[lint build fast slow] }.freeze
+      FINISHED_BADLY = { "failed" => :failed, "timed_out" => :over_budget }.freeze
+
+      def self.decide(run_status:, stages:, need:)
+        needed = needed(stages, need)
+        first_bad = first_finished_badly(needed)
+        return FINISHED_BADLY.fetch(first_bad[:status]) if first_bad
+        return :passed if needed.count { |stage| stage[:status] == "completed" } == LEVELS.fetch(need).size
+
+        run_status == "cancelled" ? :superseded : :undecided
+      end
+
+      # The name of the stage whose failure or overrun decided the verdict, or nil.
+      def self.deciding_stage(stages:, need:) = first_finished_badly(needed(stages, need))&.fetch(:stage)
+
+      def self.needed(stages, need) = stages.select { |stage| LEVELS.fetch(need).include?(stage[:stage]) }
+
+      def self.first_finished_badly(stages)
+        stages.select { |stage| FINISHED_BADLY.key?(stage[:status]) }.min_by { |stage| stage[:finished_order] }
+      end
+      private_class_method :needed, :first_finished_badly
+    end
+  end
+end

data/lib/fun_ci/agent/wait_command.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "command_support"
+require_relative "output"
+require_relative "waiting"
+
+module FunCi
+  module Agent
+    # `fun-ci wait [REV] [--need LEVEL] [--within DURATION] [--follow-branch] [--json]`
+    # (acceptance-tests.md, AT-9.9 to AT-9.12).
+    class WaitCommand
+      include CommandSupport
+
+      NAME = "wait"
+      # How long a commit may go without a run before `wait` starts one; the
+      # post-commit hook's run for a commit just made turns up well within it.
+      GRACE_SECONDS = 5
+      # The answer when no run turned up and the project can't start one.
+      NOT_SET_UP = Data.define(:verdict).new(verdict: :unknown)
+
+      def initialize(context)
+        @context = context
+      end
+
+      def run(args)
+        options = Options.parse(args, takes: %i[need json within follow_branch])
+        sha = resolve(options.rev)
+        output = Output.new(@context.io.stdout, json: options.json)
+        answer(sha, wait_for(sha, options, deadline(options), output), output)
+      rescue Options::Invalid => e
+        usage(e.message)
+      end
+
+      private
+
+      def deadline(options) = options.within && (@context.clock.now + options.within)
+
+      # Follows a superseded run on to the commit that superseded it, when asked to.
+      def wait_for(sha, options, deadline, output)
+        report = Waiting.new(@context.clock, deadline: deadline) { poll(sha, options.need) }.until_decided
+        return report unless options.follow_branch && report&.superseded_by
+
+        output.following(sha, report)
+        wait_for(report.superseded_by, options, deadline, output)
+      end
+
+      def answer(sha, report, output)
+        return output.no_run_yet(sha) unless report
+        return output.not_set_up(sha) if report.equal?(NOT_SET_UP)
+
+        output.report(report)
+        ExitCode::FOR.fetch(report.verdict)
+      end
+
+      def poll(sha, need)
+        @context.pipeline.watch(@context.db)
+        reports.mark_waited(sha, @context.clock.now)
+        reports.for(sha, need) || start_after_grace(sha)
+      end
+
+      # Nil while waiting for a run; NOT_SET_UP once one can't be started.
+      def start_after_grace(sha)
+        @missing_since ||= @context.clock.now
+        return if @started || @context.clock.now - @missing_since < GRACE_SECONDS
+
+        @started = true
+        @context.pipeline.start(sha, @context.git.branch) ? nil : NOT_SET_UP
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/waiting.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Agent
+    # Polls until the answer is decided, or the deadline (a Time; nil for none) has passed
+    # (acceptance-tests.md, AT-9.9, AT-9.10). An answer is decided once its
+    # verdict is anything but undecided; nil (no run yet) is undecided.
+    class Waiting
+      POLL_SECONDS = 1
+
+      def initialize(clock, deadline:, &poll)
+        @clock = clock
+        @deadline = deadline
+        @poll = poll
+      end
+
+      def until_decided
+        loop do
+          answer = @poll.call
+          return answer if decided?(answer) || out_of_time?
+
+          @clock.pause(POLL_SECONDS)
+        end
+      end
+
+      private
+
+      def decided?(answer) = answer && answer.verdict != :undecided
+      def out_of_time? = @deadline && @clock.now >= @deadline
+    end
+  end
+end

data/lib/fun_ci/agent/why_command.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "command_support"
+require_relative "output"
+
+module FunCi
+  module Agent
+    # `fun-ci why [REV] [STAGE] [--need LEVEL] [--json] [--raw]`
+    # (acceptance-tests.md, AT-10.1, AT-10.6): everything kept about the stage
+    # named, or else about the stage that decided the verdict; with --raw, the
+    # raw output it kept, and nothing else.
+    class WhyCommand
+      include CommandSupport
+
+      NAME = "why"
+
+      def initialize(context)
+        @context = context
+      end
+
+      def run(args)
+        options = Options.parse(args, takes: %i[need json stage raw])
+        sha = resolve(options.rev)
+        answer(sha, reports.for(sha, options.need), options)
+      rescue Options::Invalid => e
+        usage(e.message)
+      end
+
+      private
+
+      def answer(sha, report, options)
+        output = Output.new(@context.io.stdout, json: options.json)
+        return output.unknown(sha) unless report
+
+        stage_name = options.stage || report.deciding
+        options.raw ? raw(report, stage_name) : output.why(report, stage_name)
+        ExitCode::FOR.fetch(report.verdict)
+      end
+
+      def raw(report, stage_name)
+        stage = report.stages.find { |candidate| candidate.name == stage_name }
+        text = stage && reports.raw_output(stage)
+        return @context.io.stdout.write(text) if text
+
+        @context.io.stderr.puts "fun-ci why: no raw output is kept for #{stage_name || "any stage"} of #{report.sha[0,
+                                                                                                                    7]}"
+      end
+    end
+  end
+end

data/lib/fun_ci/agent/why_json.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "run_report"
+
+module FunCi
+  module Agent
+    # `fun-ci why --json` (acceptance-tests.md, AT-10.2): the stage and how it
+    # ended, its evidence, or else why there is none. Fields once published
+    # keep their names; a change bumps SCHEMA.
+    module WhyJson
+      SCHEMA = 1
+      FAILED = %w[failed over_budget].freeze
+
+      def self.document(report, stage)
+        reason = no_evidence(report, stage)
+        { schema: SCHEMA, commit: { sha: report.sha, branch: report.branch, subject: report.subject },
+          **ending(stage), evidence: reason ? nil : stage.evidence.to_h, no_evidence: reason,
+          raw_output: { kept: !stage&.raw_bytes.nil?, bytes: stage&.raw_bytes || 0 } }
+      end
+
+      def self.ending(stage)
+        { stage: stage&.name, state: stage&.state, exit_status: stage&.exit_status, signal: stage&.signal,
+          seconds: stage&.seconds, budget: stage&.budget }
+      end
+
+      def self.no_evidence(report, stage)
+        return report.verdict == :passed ? "passed" : "running" unless stage
+        return stage.state unless FAILED.include?(stage.state)
+
+        stage.pruned? ? "pruned" : nil
+      end
+      private_class_method :ending, :no_evidence
+    end
+  end
+end

data/lib/fun_ci/agent/why_text.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "status_text"
+require_relative "stage_summary"
+require_relative "evidence_text"
+require_relative "../persistence/pipeline_recorder"
+
+module FunCi
+  module Agent
+    # What `fun-ci why` prints about one stage (acceptance-tests.md, AT-10.1):
+    # the commit, how the stage ended, then everything kept about it.
+    module WhyText
+      PASSED = "Nothing is kept about a stage that passed."
+      PRUNED = "Its evidence is no longer kept: fun-ci keeps it for a project's " \
+               "#{Persistence::DbRecorder::KEPT_RUNS} newest runs.".freeze
+
+      ONLY_TAIL = "Only the output's last lines were kept; extractors under `evidence:` in .fun-ci/config keep more."
+
+      def self.lines(report, stage)
+        [StatusText.header(report), StageSummary.line(stage), *body(stage), *raw(report, stage), *only_tail(stage)]
+      end
+
+      # So an agent that reads it knows it can write the extractor itself.
+      def self.only_tail(stage)
+        evidence = stage.evidence
+        kept_more = evidence.failures.any? || evidence.excerpts.any? { |excerpt| excerpt[:extractor] != "output-tail" }
+        kept_more || evidence.excerpts.empty? ? [] : ["", ONLY_TAIL]
+      end
+
+      def self.raw(report, stage)
+        stage.raw_bytes ? ["", "The whole output: fun-ci why #{report.sha[0, 7]} #{stage.name} --raw"] : []
+      end
+
+      def self.body(stage)
+        return [PASSED] if stage.state == "passed"
+        return [PRUNED] if stage.pruned?
+
+        EvidenceText.lines(stage.evidence)
+      end
+      private_class_method :body, :raw, :only_tail
+    end
+  end
+end

data/lib/fun_ci/cli.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "../fun_ci"
+require_relative "cli_help"
+require_relative "pipeline/trigger_params"
+require_relative "persistence/state_dir"
+require_relative "setup/commands"
+
+module FunCi
+  class Cli
+    ROUTES = {
+      "trigger" => :run_trigger,
+      "console" => :run_console,
+      "init" => :run_init,
+      "install-hooks" => :run_install_hooks,
+      "check" => :run_check,
+      "prune" => :run_prune,
+      "extract" => :run_extract
+    }.freeze
+    AGENT_COMMANDS = %w[status runs wait events why].freeze
+
+    def self.default_db_dir = Persistence::StateDir.path(ENV)
+
+    def self.run(args, io: Pipeline::Io.new, handlers: {}, db_dir: default_db_dir)
+      new(io: io, handlers: handlers, db_dir: db_dir).run(args)
+    end
+
+    def initialize(io:, handlers:, db_dir:)
+      @io = io
+      @db_dir = db_dir
+      @handlers = handlers
+    end
+
+    def run(args)
+      subcommand = args.first
+      return CliHelp.help(@io.stdout) if %w[-h --help].include?(subcommand)
+      return CliHelp.version(@io.stdout) if subcommand == "--version"
+
+      return unknown_command(subcommand) unless ROUTES.key?(subcommand) || AGENT_COMMANDS.include?(subcommand)
+
+      dispatch(subcommand, args.drop(1))
+    end
+
+    private
+
+    def dispatch(subcommand, args)
+      return @handlers[subcommand].call(args) if @handlers.key?(subcommand)
+      return run_agent(subcommand, args) if AGENT_COMMANDS.include?(subcommand)
+
+      send(ROUTES[subcommand], args)
+    end
+
+    def run_trigger(args)
+      require_relative "pipeline/trigger"
+      require_relative "persistence/pipeline_recorder"
+      db = setup_db
+      recorder = Persistence::DbRecorder.new(db)
+      Pipeline::Trigger.run_from_args(args, io: @io, recorder: recorder)
+    end
+
+    # Only `console` needs the renderer, so only it fails without one.
+    def run_console(_args)
+      require_relative "console/launcher"
+      require_relative "console/renderer_lookup"
+      launch_console(Console::RendererLookup.default.path)
+    rescue Console::RendererLookup::Missing => e
+      @io.stderr.puts e.message
+      1
+    end
+
+    def launch_console(renderer)
+      db = setup_db
+      Console::Launcher.run(renderer: renderer, db: db, project_dir: Dir.pwd, stderr: @io.stderr)
+    ensure
+      db&.close
+    end
+
+    # The mutation lane loads all of lib/ before it mutates, so it can't see
+    # a lazy require go missing (here and in run_prune); the process tests
+    # that run these commands load the files unmutated.
+    def run_agent(name, args)
+      require_relative "agent/commands" # mutineer:disable-line statement_removal
+      db = setup_db
+      Agent::Commands.run(name, args, agent_context(db))
+    ensure
+      db&.close
+    end
+
+    def agent_context(db)
+      Agent::Context.new(db: db, git: Agent::Git.new(Dir.pwd), io: @io, clock: Agent::SystemClock.new,
+                         pipeline: Agent::LivePipeline.new(Dir.pwd))
+    end
+
+    def run_init(args) = setup_commands.init(args)
+    def run_install_hooks(args) = setup_commands.install_hooks(args)
+    def run_check(args) = setup_commands.check(args)
+    def setup_commands = Setup::Commands.new(Dir.pwd, @io.stdout)
+
+    def run_extract(args)
+      require_relative "evidence/extract_command"
+      Evidence::ExtractCommand.new(Dir.pwd, @io).run(args)
+    end
+
+    def run_prune(_args)
+      require_relative "pipeline/worktree_prune" # mutineer:disable-line statement_removal
+      removed = Pipeline::WorktreePrune.new(Pipeline::Worktrees.new(Dir.pwd)).run
+      @io.stdout.puts "Removed #{removed} fun-ci worktree#{"s" unless removed == 1}."
+      0
+    rescue Pipeline::WorktreePrune::Busy, Pipeline::Worktrees::GitError => e
+      @io.stderr.puts "fun-ci prune: #{e.message}"
+      1
+    end
+
+    def setup_db
+      Persistence::StateDir.prepare(@db_dir)
+      db_path = File.join(@db_dir, "db.sqlite3")
+      db = Persistence::Database.connection(db_path)
+      Persistence::Database.migrate!(db)
+      db
+    end
+
+    def unknown_command(subcommand)
+      @io.stderr.puts "fun-ci: unknown command '#{subcommand}'", "" if subcommand
+      @io.stderr.puts "Usage: fun-ci <command> [options]", "", "Run 'fun-ci --help' for available commands."
+      1
+    end
+  end
+end

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