fun_ci 1.2.1 → 2.0.0

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

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
-require "tmpdir"
 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
@@ -10,27 +13,31 @@ module FunCi
       "console" => :run_console,
       "init" => :run_init,
       "install-hooks" => :run_install_hooks,
-      "check" => :run_check
+      "check" => :run_check,
+      "prune" => :run_prune,
+      "extract" => :run_extract
     }.freeze
+    AGENT_COMMANDS = %w[status runs wait events why].freeze
 
-    def self.run(args, stdout: $stdout, stderr: $stderr, handlers: {})
-      new(stdout: stdout, stderr: stderr, handlers: handlers).run(args)
+    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(stdout:, stderr:, handlers:)
-      @stdout = stdout
-      @stderr = stderr
+    def initialize(io:, handlers:, db_dir:)
+      @io = io
+      @db_dir = db_dir
       @handlers = handlers
     end
 
     def run(args)
       subcommand = args.first
-      return help(0) if %w[-h --help].include?(subcommand)
-      return version if subcommand == "--version"
-      unless ROUTES.key?(subcommand)
-        print_error(subcommand)
-        return 1
-      end
+      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
 
@@ -38,6 +45,8 @@ module FunCi
 
     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
 
@@ -46,105 +55,74 @@ module FunCi
       require_relative "persistence/pipeline_recorder"
       db = setup_db
       recorder = Persistence::DbRecorder.new(db)
-      Pipeline::Trigger.run_from_args(args, stdout: @stdout, stderr: @stderr, recorder: recorder)
+      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 "tui/admin_tui"
-      require_relative "tui/animation_renderer"
-      require "io/console"
+      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
-      tui = Tui::AdminTui.new(
-        db: db,
-        width_provider: -> { IO.console&.winsize&.dig(1) || 80 },
-        height_provider: -> { IO.console&.winsize&.dig(0) },
-        animation_renderer: Tui::AnimationRenderer.new
-      )
-      tui.run
-      0
+      Console::Launcher.run(renderer: renderer, db: db, project_dir: Dir.pwd, stderr: @io.stderr)
+    ensure
+      db&.close
     end
 
-    def run_init(args)
-      require_relative "setup/installer"
-      code = Setup::Installer.run(project_root: Dir.pwd, stdout: @stdout)
-      return code if code != 0 || !args.include?("--everything")
-      code = run_install_hooks([])
-      return code unless code == 0
-      run_check([])
+    # 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 run_install_hooks(args)
-      require_relative "setup/hook_writer"
-      types = args.any? ? [args.first] : %w[pre-commit pre-push]
-      types.each do |type|
-        code = Setup::HookWriter.run(project_root: Dir.pwd, hook_type: type, stdout: @stdout)
-        return code unless code == 0
-      end
-      0
+    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_check(_args)
-      require_relative "setup/setup_checker"
-      Setup::SetupChecker.run(project_root: Dir.pwd, stdout: @stdout, stderr: @stderr)
+    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
-      db_dir = File.join(Dir.tmpdir, "fun-ci")
-      Dir.mkdir(db_dir) unless Dir.exist?(db_dir)
-      db_path = File.join(db_dir, "db.sqlite3")
+      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
 
-    HELP_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 pre-commit and pre-push git hooks
-        check          Verify project setup
-
-      Options:
-        -h, --help     Show this help message
-        --version      Show version
-
-      Trigger options:
-        --no-validate  Fork pipeline to background and return immediately
-
-      Init options:
-        --everything   Run init + install-hooks + check in one step
-
-      Examples:
-        fun-ci init --everything
-        fun-ci trigger abc1234 main
-        fun-ci trigger --no-validate abc1234 main
-        fun-ci console
-    HELP
-
-    def help(exit_code)
-      @stdout.puts HELP_TEXT
-      exit_code
-    end
-
-    def version
-      @stdout.puts "fun-ci #{FunCi::VERSION}"
-      0
-    end
-
-    def print_error(subcommand)
-      if subcommand
-        @stderr.puts "fun-ci: unknown command '#{subcommand}'"
-        @stderr.puts ""
-      end
-      @stderr.puts "Usage: fun-ci <command> [options]"
-      @stderr.puts ""
-      @stderr.puts "Run 'fun-ci --help' for available commands."
+    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