fun_ci 1.2.0 → 2.0.0

data/lib/fun_ci/console/run_message.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "time"
+
+module FunCi
+  module Console
+    # A run as BoardData reads it from SQLite, as the protocol's `board`
+    # message carries it: protocol status names, epoch seconds and
+    # milliseconds. Formatting them is the renderer's job.
+    module RunMessage
+      STATUS = { "scheduled" => "pending", "completed" => "passed", "timed_out" => "timeout" }.freeze
+
+      def self.from(run)
+        { id: run[:id], sha: run[:commit_hash], branch: run[:branch], project: run[:project_path],
+          status: status(run[:status]), started_at: epoch(run[:created_at]), updated_at: epoch(run[:updated_at]),
+          stages: run[:stages].map { |stage| stage(stage) } }.compact
+      end
+
+      def self.stage(stage)
+        { stage: stage[:stage], status: status(stage[:status]),
+          duration_ms: stage[:duration] && (stage[:duration] * 1000).round,
+          started_at: (epoch(stage[:started_at]) if stage[:status] == "running") }.compact
+      end
+      private_class_method :stage
+
+      def self.status(name) = STATUS.fetch(name, name)
+      private_class_method :status
+
+      def self.epoch(iso) = iso && Time.parse(iso).to_i
+      private_class_method :epoch
+    end
+  end
+end

data/lib/fun_ci/console/stage_change_detector.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    # The stages whose status differs between two polls of the runs, for the
+    # runs both polls saw; none when there was no earlier poll.
+    module StageChangeDetector
+      Change = Data.define(:run_id, :stage, :from, :to)
+
+      def self.detect(previous_runs, current_runs)
+        current_by_id = current_runs.to_h { |run| [run[:id], run] }
+        previous_runs.select { |run| current_by_id.key?(run[:id]) }
+                     .flat_map { |run| compare_stages(run, current_by_id.fetch(run[:id])) }
+      end
+
+      def self.compare_stages(previous_run, current_run)
+        before = statuses(previous_run[:stages])
+        current_run[:stages].reject { |stage| before[stage[:stage]] == stage[:status] }
+                            .map { |stage| change(current_run[:id], stage, before[stage[:stage]]) }
+      end
+      private_class_method :compare_stages
+
+      def self.change(run_id, stage, from)
+        Change.new(run_id: run_id, stage: stage[:stage], from: from, to: stage[:status])
+      end
+      private_class_method :change
+
+      def self.statuses(stages) = (stages || []).to_h { |stage| [stage[:stage], stage[:status]] }
+      private_class_method :statuses
+    end
+  end
+end

data/lib/fun_ci/console/stage_events.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "stage_change_detector"
+
+module FunCi
+  module Console
+    # The protocol `event` messages for the stages that changed since the
+    # last poll of the runs: one that failed or timed out, or one that
+    # passed. The renderer chooses the animation (renderer-protocol.md).
+    class StageEvents
+      NAMES = { "failed" => "stage_failed", "timed_out" => "stage_failed", "completed" => "stage_passed" }.freeze
+
+      def initialize
+        @previous = []
+      end
+
+      # None on the first poll, which has nothing to compare with.
+      def since_last(runs)
+        changes = StageChangeDetector.detect(@previous, runs)
+        @previous = runs
+        changes.select { |change| NAMES.key?(change.to) }.map { |change| event(change) }
+      end
+
+      private
+
+      def event(change)
+        { t: "event", name: NAMES.fetch(change.to), run_id: change.run_id, stage: change.stage }
+      end
+    end
+  end
+end

data/lib/fun_ci/console/stop_report.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    # Why the console stopped, in the console log and, unless the user quit
+    # and the renderer exited cleanly, on stderr: the terminal is the
+    # renderer's until it exits, so an error is only told once it has.
+    class StopReport
+      CAUSES = { quit: "the user quit", ended: "the renderer went away" }.freeze
+
+      # `outcome`: :quit, :ended, or the error that stopped the console.
+      def initialize(outcome, status)
+        @outcome = outcome
+        @status = status
+      end
+
+      # The exit status: 0 once the user has quit, 1 otherwise.
+      def tell(log, stderr)
+        log.write("console stopped: #{cause}; the renderer exited (#{@status})")
+        return 0 if @outcome == :quit && @status.success?
+
+        stderr.puts "#{failure}; see .fun-ci/console.log"
+        1
+      end
+
+      private
+
+      def failed? = @outcome.is_a?(Exception)
+
+      def cause = failed? ? "it failed: #{error}\n#{trace}" : CAUSES.fetch(@outcome)
+
+      def error = "#{@outcome.class}: #{@outcome.message}"
+
+      def trace = @outcome.backtrace.map { |line| "  #{line}" }.join("\n")
+
+      def failure = failed? ? "fun-ci console failed (#{error})" : "fun-ci console: the renderer stopped (#{@status})"
+    end
+  end
+end

data/lib/fun_ci/console/streak_counter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    module StreakCounter
+      PASS_STATUS = "completed"
+      ACTIVE_STATUSES = %w[running scheduled].freeze
+
+      # Passed runs since the latest finished run that did not pass; nil
+      # while no run has finished.
+      def self.count(runs)
+        finished = runs.reject { |run| ACTIVE_STATUSES.include?(run[:status]) }
+        return nil if finished.empty?
+
+        finished.take_while { |run| run[:status] == PASS_STATUS }.size
+      end
+    end
+  end
+end

data/lib/fun_ci/console/view.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Console
+    # What the user sees of the runs and does with them: KeyHandler's cursor
+    # and cancel confirmation, and one page of runs, as many as the terminal
+    # fits, scrolled so the run under the cursor is on it (renderer-protocol.md,
+    # `board`).
+    class View
+      # The renderer's 14-row header, a blank line and the footer.
+      CHROME_ROWS = 16
+      ROWS_PER_RUN = 2
+
+      def initialize(key_handler:)
+        @key_handler = key_handler
+        @page_size = 0
+      end
+
+      # The number of runs a terminal of `rows` fits.
+      def resize(rows)
+        @page_size = [(rows - CHROME_ROWS) / ROWS_PER_RUN, 0].max
+      end
+
+      # :quit when the key ends the session.
+      def press(key) = @key_handler.handle_key(key)
+
+      # `more`: whether the store holds runs beyond `runs`.
+      def page(runs, more:)
+        first = first_shown
+        { cursor: cursor_on_page(first), confirming: @key_handler.confirming?,
+          has_more: more || first + @page_size < runs.size, runs: runs[first, @page_size] || [] }
+      end
+
+      private
+
+      def first_shown
+        cursor = @key_handler.cursor_index
+        cursor ? [cursor - @page_size + 1, 0].max : 0
+      end
+
+      def cursor_on_page(first)
+        cursor = @key_handler.cursor_index
+        cursor - first if cursor && @page_size.positive?
+      end
+    end
+  end
+end

data/lib/fun_ci/evidence/about.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Evidence
+    # What is known about a failed stage when its evidence is collected, as a
+    # project's command is told it: how it ended, its budget, the stages
+    # alongside it, the commit, where it ran, when it started, and where its
+    # output is.
+    About = Data.define(:stage, :state, :exit_status, :signal, :seconds, :budget, :alongside, :commit, :worktree,
+                        :started_at, :output)
+  end
+end

data/lib/fun_ci/evidence/about_stage.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "about"
+
+module FunCi
+  module Evidence
+    # What is known About a stage, from what was known when it started and
+    # how it ended. Its output is written to its directory for a project's
+    # command to read.
+    module AboutStage
+      def self.of(sources, outcome, output)
+        About.new(**outcome.to_h.except(:overrun), **started(sources), **where(sources, output),
+                  stage: sources.stage, budget: sources.budget, commit: sources.commit)
+      end
+
+      def self.where(sources, output)
+        { worktree: sources.worktree, output: sources.stage_dir.output_file(output) }
+      end
+
+      def self.started(sources)
+        return { seconds: nil, started_at: nil } unless sources.started
+
+        { seconds: (Time.now - sources.started).round(1), started_at: sources.started.utc.iso8601(3) }
+      end
+      private_class_method :started, :where
+    end
+  end
+end

data/lib/fun_ci/evidence/caps.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FunCi
+  module Evidence
+    # How much evidence fun-ci keeps (architecture.md, "Evidence of a failed stage"): at
+    # most `failures` failures, the rest counted in a fact; then, over
+    # `bytes` of JSON, excerpts cut from the last backwards, then messages
+    # to their first `message_lines`, each cut marked `truncated`. Facts and
+    # problems are small and never cut.
+    class Caps
+      Limits = Data.define(:bytes, :failures, :message_lines)
+      REAL = Limits.new(bytes: 262_144, failures: 100, message_lines: 50)
+      # What a line costs in JSON besides its own bytes: quotes and a comma.
+      LINE_COST = 3
+
+      def initialize(limits = REAL)
+        @limits = limits
+      end
+
+      def apply(document)
+        document = shorter(few_failures(document))
+        over(document).positive? ? shorter_messages(document) : document
+      end
+
+      private
+
+      # Each pass cuts at least a line, so there are never more passes than lines.
+      def shorter(document)
+        document.excerpts.sum { |excerpt| excerpt[:lines].size }.times do
+          break unless over(document).positive?
+
+          document = shorter_excerpts(document)
+        end
+        document
+      end
+
+      def over(document) = JSON.generate(document.to_h).bytesize - @limits.bytes
+
+      def few_failures(document)
+        left_out = document.failures.size - @limits.failures
+        return document unless left_out.positive?
+
+        count = { name: "failures not kept", value: left_out.to_s, extractor: "fun-ci" }
+        document.with(failures: document.failures.first(@limits.failures), facts: document.facts + [count])
+      end
+
+      def shorter_excerpts(document)
+        excess = over(document)
+        excerpts = document.excerpts.reverse.map do |excerpt|
+          cut, excess = cut_lines(excerpt, excess)
+          cut
+        end
+        document.with(excerpts: excerpts.reverse)
+      end
+
+      # The excerpt without as many of its last lines as cover `excess` bytes, and what is left of `excess`.
+      def cut_lines(excerpt, excess)
+        lines = excerpt[:lines].dup
+        excess -= lines.pop.bytesize + LINE_COST while excess.positive? && lines.any?
+        [lines.size == excerpt[:lines].size ? excerpt : excerpt.merge(lines: lines, truncated: true), excess]
+      end
+
+      def shorter_messages(document)
+        document.with(failures: document.failures.map { |failure| short_message(failure) })
+      end
+
+      def short_message(failure)
+        lines = failure[:message].to_s.lines
+        return failure if lines.size <= @limits.message_lines
+
+        failure.merge(message: lines.first(@limits.message_lines).join.chomp, truncated: true)
+      end
+    end
+  end
+end

data/lib/fun_ci/evidence/catalog.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "option_check"
+require_relative "presets"
+require_relative "extractors/grep"
+require_relative "extractors/section"
+require_relative "extractors/log_file"
+require_relative "extractors/json_log"
+require_relative "extractors/junit_files"
+require_relative "extractors/command"
+require_relative "extractors/process_tree"
+
+module FunCi
+  module Evidence
+    # The built-in extractors by name, and how an entry of .fun-ci/config
+    # becomes one to run (architecture.md, "Evidence of a failed stage"). An entry that can't is
+    # Refused, with what is wrong with it.
+    module Catalog
+      class Refused < StandardError; end
+
+      # name: what the evidence credits (`grep`, `section:rspec`); on: nil, or "overrun".
+      Entry = Data.define(:name, :extractor, :on)
+
+      BUILT_INS = { "grep" => Extractors::Grep, "section" => Extractors::Section,
+                    "log-file" => Extractors::LogFile, "json-log" => Extractors::JsonLog,
+                    "junit-files" => Extractors::JunitFiles, "process-tree" => Extractors::ProcessTree }.freeze
+      SHARED = %w[use on preset].freeze
+
+      def self.entry(raw)
+        raise Refused, "an entry must be a mapping with use: or run:, not #{raw.inspect}" unless raw.is_a?(Hash)
+
+        raw.key?("run") ? command(raw) : built_in(raw)
+      end
+
+      def self.built_in(raw)
+        built_in = BUILT_INS[raw["use"]] || raise(Refused, "unknown extractor '#{raw["use"]}'")
+        Entry.new(name: [raw["use"], raw["preset"]].compact.join(":"),
+                  extractor: built_in.new(checked_options(raw, built_in)), on: raw["on"])
+      end
+
+      def self.checked_options(raw, built_in)
+        options = preset_options(raw).merge(raw.except(*SHARED))
+        mistake = OptionCheck.mistake(raw["use"], built_in, options) || on_mistake(raw)
+        raise Refused, mistake if mistake
+
+        options
+      end
+
+      # A project's own extractor. Whatever the entry says besides run:,
+      # format:, watch: and on: is passed on to it.
+      def self.command(raw)
+        mistake = command_mistake(raw) || on_mistake(raw)
+        raise Refused, mistake if mistake
+
+        Entry.new(name: "run:#{raw["run"]}", extractor: Extractors::Command.new(raw.except("on")), on: raw["on"])
+      end
+
+      def self.command_mistake(raw)
+        unless raw["run"].is_a?(String) && !raw["run"].empty?
+          return "run: must name a command, not #{raw["run"].inspect}"
+        end
+        return nil if [nil, "text", "json"].include?(raw["format"])
+
+        "run:#{raw["run"]}: 'format' must be text or json, not #{raw["format"].inspect}"
+      end
+
+      # The options of the preset an entry names, which its own replace.
+      def self.preset_options(raw)
+        return {} unless raw.key?("preset")
+
+        preset = Presets.find(raw["use"], raw["preset"])
+        preset ? preset.options : raise(Refused, "#{raw["use"]} has no preset '#{raw["preset"]}'")
+      end
+
+      def self.on_mistake(raw)
+        return nil if [nil, "overrun"].include?(raw["on"])
+
+        "#{raw["use"] || "run:#{raw["run"]}"}: 'on' must be overrun, not #{raw["on"].inspect}"
+      end
+      private_class_method :built_in, :command, :command_mistake, :checked_options, :preset_options, :on_mistake
+    end
+  end
+end

data/lib/fun_ci/evidence/collector.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "sources"
+require_relative "document"
+require_relative "masking"
+require_relative "settings"
+require_relative "extraction"
+require_relative "findings"
+require_relative "outcome"
+require_relative "stage_context"
+require_relative "detection"
+require_relative "source"
+require_relative "caps"
+require_relative "../persistence/output_tail"
+
+module FunCi
+  module Evidence
+    # Picks out what fun-ci keeps about a stage that failed (architecture.md,
+    # "Evidence of a failed stage"): for an overrun, what process-tree and the
+    # entries for an overrun found before the kill; the entries configured for
+    # the stage and the presets detected, within the budget; then the output's
+    # last lines; all masked.
+    class Collector
+      MONOTONIC = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      FAILED = Outcome.new(state: "failed")
+      # How long past its budget a stage runs while its overrun is looked at.
+      GRACE = 2
+      NOTHING = Extraction::Result.new(parts: [], problems: [], chosen: [])
+
+      # commands: runs a project's own extractors (a CommandRunner).
+      def initialize(sources, settings: Settings.new(nil), clock: MONOTONIC, commands: nil)
+        @sources = sources
+        @settings = settings
+        @contexts = StageContext.new(sources, clock, commands)
+      end
+
+      def collect(output, outcome = FAILED)
+        result = extracted(output, outcome)
+        overrun = outcome.overrun || NOTHING
+        parts = [["fun-ci", own_facts(outcome.alongside)], *overrun.parts, *result.parts, ["output-tail", tail(output)]]
+        Caps.new.apply(masking.document(assemble(parts, [overrun, result])))
+      end
+
+      # What a stage over budget was doing, looked at before the kill.
+      def before_kill(pgid)
+        Extraction.new(@contexts.before_kill(pgid, GRACE), GRACE)
+                  .run([[{ "use" => "process-tree" }, "overrun"], *entries("overrun")])
+      end
+
+      # The raw output, masked as the evidence is.
+      def masked(output) = masking.mask(output)
+
+      private
+
+      # The configured entries, then the detected presets, within the budget.
+      def extracted(output, outcome)
+        context = @contexts.after(output, outcome, @settings.budget)
+        Extraction.new(context, @settings.budget).run(entries(nil) + detected(output, context.deadline))
+      end
+
+      # The candidates' presets whose signatures the output matched, or that have none.
+      def detected(output, deadline)
+        Detection.chosen(output, @sources.candidates, deadline).map do |found|
+          [{ "use" => found.preset.use, "preset" => found.preset.name }, found.because]
+        end
+      end
+
+      def assemble(parts, results)
+        Document.assemble(parts, problems: results.flat_map(&:problems), chosen: results.flat_map(&:chosen))
+      end
+
+      # The stage's entries that run on `on`: nil, when it fails, or "overrun".
+      def entries(on)
+        @settings.entries(@sources.stage).select { |raw| on_of(raw) == on }.map { |raw| [raw, "configured"] }
+      end
+
+      def on_of(raw) = raw.is_a?(Hash) ? raw["on"] : nil
+
+      def own_facts(alongside)
+        Findings.new(facts: alongside.empty? ? [] : [{ name: "alongside", value: alongside.join(", ") }])
+      end
+
+      def tail(output)
+        text = Persistence::OutputTail.of(output, mask: masking.method(:mask))
+        Findings.new(excerpts: [{ title: Document::TAIL_TITLE, location: "output", lines: text.lines(chomp: true) }])
+      end
+
+      def masking
+        return Masking.none unless @settings.masking?
+
+        Masking.new(@sources.environment, patterns: @settings.mask_patterns)
+      end
+    end
+  end
+end

data/lib/fun_ci/evidence/command_output.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "findings"
+require_relative "problem"
+
+module FunCi
+  module Evidence
+    # What a project's command printed, as findings: with `format: text`,
+    # one excerpt; with `format: json`, the document of `contract/evidence/`, whose fields
+    # fun-ci doesn't know are ignored.
+    module CommandOutput
+      SCHEMA = 1
+      FIELDS = { facts: %i[name value], failures: %i[test file line message output],
+                 excerpts: %i[title location lines] }.freeze
+
+      def self.text(title, stdout)
+        Findings.new(excerpts: [{ title: title, location: "stdout", lines: stdout.lines(chomp: true) }])
+      end
+
+      def self.json(stdout)
+        document = parse(stdout)
+        schema = document.fetch("schema", SCHEMA)
+        raise Problem, "printed schema #{schema}, and this fun-ci reads schema #{SCHEMA}" if schema.to_i > SCHEMA
+
+        Findings.new(**FIELDS.to_h { |list, keys| [list, items(document, list, keys)] })
+      end
+
+      def self.parse(stdout)
+        document = JSON.parse(stdout)
+        document.is_a?(Hash) ? document : raise(Problem, "printed JSON that isn't an object")
+      rescue JSON::ParserError => e
+        raise Problem, "printed JSON that doesn't parse: #{e.message.lines.first.to_s.strip}"
+      end
+
+      def self.items(document, list, keys)
+        given = document.fetch(list.to_s, [])
+        raise Problem, "printed '#{list}' that isn't a list of objects" unless given.is_a?(Array) && given.all?(Hash)
+
+        given.map { |item| keys.to_h { |key| [key, item[key.to_s]] }.compact }
+      end
+      private_class_method :parse, :items
+    end
+  end
+end

data/lib/fun_ci/evidence/command_reading.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FunCi
+  module Evidence
+    # Reads a command's stdout in a thread, up to `limit` bytes; past that it
+    # calls `stop`, which kills the command.
+    class CommandReading
+      def self.start(reader, limit, stop) = new(reader, limit, stop).tap(&:begin)
+
+      def initialize(reader, limit, stop)
+        @reader = reader
+        @limit = limit
+        @stop = stop
+      end
+
+      def begin = @thread = Thread.new { read(+"".b) }
+
+      # All that was read, once reading ends or the drain is over.
+      def finish(drain)
+        @thread.join(drain)
+        @reader.close
+        @thread.value
+      end
+
+      private
+
+      def read(buffer)
+        loop do
+          buffer << @reader.readpartial(65_536)
+          break @stop.call if buffer.bytesize > @limit
+        end
+        buffer
+      rescue IOError
+        buffer
+      end
+    end
+  end
+end

data/lib/fun_ci/evidence/command_runner.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../pipeline/git_environment"
+require_relative "command_reading"
+
+module FunCi
+  module Evidence
+    # Runs a project's extractor command as stage scripts are run: in the
+    # worktree, with the clean git environment, in a process group of its
+    # own, killed with everything it started when `seconds` run out or when it
+    # prints more than `limit` bytes. Its stdin is a file in `scratch`, and
+    # its stderr another. A process that leaves the group (setsid) can't be
+    # killed with it, so reading stops once the time and the drain are over.
+    class CommandRunner
+      Ran = Data.define(:stdout, :stderr, :exit_status, :killed)
+      # bytes: the most of stdout kept; drain: seconds to read on after the command ends.
+      Limits = Data.define(:bytes, :drain)
+      LIMITS = Limits.new(bytes: 262_144, drain: 1)
+
+      def initialize(dir:, scratch:, limits: LIMITS)
+        @dir = dir
+        @scratch = scratch
+        @limit = limits.bytes
+        @drain = limits.drain
+      end
+
+      # env: added to the command's environment for this run.
+      def call(command, stdin:, seconds:, env: {})
+        File.write(path("context.json"), stdin)
+        reader, writer = IO.pipe
+        pid = spawn(command, writer, env)
+        writer.close
+        finish(pid, CommandReading.start(reader, @limit, -> { kill(pid) }), seconds)
+      end
+
+      private
+
+      def path(name) = File.join(@scratch, name)
+
+      def spawn(command, writer, env)
+        Process.spawn(Pipeline::GitEnvironment::CLEAN.merge(env), command,
+                      in: path("context.json"), out: writer, err: path("stderr"), pgroup: true, chdir: @dir)
+      end
+
+      def finish(pid, reading, seconds)
+        waiter = Process.detach(pid)
+        out_of_time = waiter.join(seconds).nil?
+        kill(pid) if out_of_time
+        status = waiter.value
+        stdout = reading.finish(@drain)
+        Ran.new(stdout: text(stdout.byteslice(0, @limit)), stderr: text(File.binread(path("stderr"))),
+                exit_status: status.exitstatus, killed: killed(out_of_time, stdout))
+      end
+
+      def killed(out_of_time, stdout)
+        return :budget if out_of_time
+
+        stdout.bytesize > @limit ? :overflow : nil
+      end
+
+      # Kills the command and all it started in its group.
+      def kill(pid)
+        %w[TERM KILL].each { |signal| ignoring_gone { Process.kill(signal, -pid) } }
+      end
+
+      def ignoring_gone
+        yield
+      rescue Errno::ESRCH, Errno::EPERM
+        # The group has gone, or what is left of it is no longer ours.
+      end
+
+      def text(bytes) = bytes.force_encoding(Encoding::UTF_8).scrub("?")
+    end
+  end
+end