proctolog 0.1.0

data/app/models/proctolog/scenario.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A state of the app that one click opens, from the registry in
+  # scenarios/<burst>.yml. It is a step of the sitting (`sitting`), or a group
+  # of steps in a pull request's "How to test locally" (`pr`, with the bold
+  # heading over them as `steps`): those steps are read from the description
+  # each time and never copied here.
+  #
+  # `recipe` and `arguments` (`with` in the file) name the state the app's
+  # own `state` command makes; `opens` is the page, a path or the key of what
+  # it printed (`link`, `lands_on`). The member it printed is signed in on
+  # arrival, nobody is when `signed_out`, and with neither, whoever is signed
+  # in stays.
+  class Scenario < Data.define(:pr, :sitting, :group, :name, :expect, :steps, :recipe, :arguments, :opens, :size, :browser, :signed_out)
+    Incomplete = Class.new(StandardError)
+
+    FILES = -> { Project.current.scenario_folders }
+
+    STEPS_IN = "How to test locally"
+    # What the owner can say of a scenario, by the words on the buttons.
+    RESULTS = {"As expected" => "ok", "Not as expected" => "not_ok", "Skip" => "skipped"}.freeze
+
+    Step = Data.define(:number, :text)
+
+    def self.of(burst)
+      file = folders.map { it.join("#{burst.slug}.yml") }.find(&:exist?) or return []
+
+      YAML.safe_load_file(file, symbolize_names: true).map { from(it) }.tap { check_names(it) }
+    end
+
+    def self.folders = Array(FILES.respond_to?(:call) ? FILES.call : FILES)
+
+    # The scenarios a pull request's description offers on its own: each bold
+    # heading of its "How to test locally" with numbered steps under it, a
+    # label such as "**What is needed.**" being none, opening the app's home
+    # page as whoever is signed in. A section that numbers its steps under no
+    # such heading is one scenario. A file that names the pull request says
+    # more, and wins.
+    def self.described(stop)
+      section = stop.description.section(STEPS_IN)
+      headings = section.split(/^(?=\*\*[^*\n]+\*\*)/).filter_map { it[/\A\*\*([^*\n]+)\*\*/, 1] if it.match?(/^\d+\.\s/) }
+      headings = [STEPS_IN] if headings.empty? && section.match?(/^\d+\.\s/)
+      headings.map { new(pr: stop.number, steps: it, opens: "/") }
+    end
+
+    def self.from(entry)
+      new(**entry.transform_keys { (it == :with) ? :arguments : it }).tap do |scenario|
+        scenario.problems.any? and raise Incomplete, "The scenario #{scenario.name.inspect} #{scenario.problems.to_sentence}"
+      end
+    end
+
+    def self.check_names(scenarios)
+      twice = scenarios.map(&:to_param).tally.select { _2 > 1 }.keys
+      twice.none? or raise Incomplete, "Two scenarios are called #{twice.to_sentence}"
+    end
+
+    def initialize(pr: nil, sitting: nil, group: nil, steps: nil, name: steps&.chomp("."), expect: nil, recipe: nil, arguments: {},
+      opens: ("lands_on" if recipe), size: "desktop", browser: "clean", signed_out: false)
+      super(pr:, sitting:, group:, name:, expect:, steps:, recipe:, arguments:, opens:, size:, browser: Browser.named(browser), signed_out:)
+    end
+
+    # What is missing or wrong, in words that follow "The scenario “…” ".
+    def problems
+      [("has no name" unless name),
+        ("is neither a step of the sitting nor a pull request's" unless pr.nil? ^ sitting.nil?),
+        ("is a step of the sitting with no group" if sitting && !group),
+        ("is a step of the sitting with nothing to expect" if sitting && !expect),
+        ("names no bold heading over its steps" if pr && !steps),
+        ("opens no page" unless opens),
+        ("opens a key of what a recipe printed, and has no recipe" if opens && !opens.start_with?("/") && !recipe),
+        ("has a size that is neither a name nor a width and a height" unless Size.valid?(size))].compact
+    end
+
+    def to_param = sitting ? "step-#{sitting}" : "#{pr}-#{name.to_s.parameterize}"
+
+    # Whose marks keep what the owner saw of it.
+    def marked_on = pr || "sitting"
+
+    def window = Size.of(size)
+
+    # The notes of a marks file that are pinned to this scenario.
+    def noted_in(marks) = marks.notes.select { it.place in Note::Scenario[name: ^(name)] }
+
+    # Makes the state and works out where the browser goes, through the app's
+    # own sign-in or sign-out on the way, and what cookies it is given first.
+    # With an `overlay` brief, Grouse's overlay is opened once the member is
+    # known, and its cookie goes last, as the app printed it, to any browser.
+    # Raises a Server::Error when the app cannot be entered; a refused overlay
+    # does not stop it.
+    def visit(server, overlay: nil)
+      server.require_up
+      account = recipe ? server.enter(recipe, **arguments) : {}
+      opened = overlay && Overlay.open(server, overlay.without(account["email"]))
+      Visit.new(to: server.address(entrance(account, server.app)), overlay: opened,
+        cookies: [*(server.app.cookies.map { Visit.cookie(it) } if browser.clean?), *opened&.cookie])
+    end
+
+    # Its numbered steps as the description has them now: under the bold
+    # heading `steps` of "How to test locally", the first line of each. Code
+    # blocks and sub-bullets stay on GitHub. A description that numbers its
+    # steps under no bold heading has one scenario, whose `steps` is the name
+    # of the section itself.
+    def steps_in(description)
+      section = description.section(STEPS_IN)
+      group = (steps == STEPS_IN) ? section : section.split(/^(?=\*\*[^*\n]+\*\*)/).find { it[/\A\*\*([^*\n]+)\*\*/, 1].to_s.chomp(".") == steps.chomp(".") }
+      group.to_s.scan(/^(\d+)\.\s+(.+)$/).map { |number, text| Step.new(number: number.to_i, text:) }
+    end
+
+    private
+
+    def landing(account)
+      return opens if opens.start_with?("/")
+
+      account.fetch(opens) { raise Failure, "The recipe #{recipe} printed no #{opens.inspect} for the scenario #{name.inspect} to open. It printed #{account.keys.to_sentence.presence || "nothing"}." }
+    end
+
+    def entrance(account, app)
+      page = landing(account)
+      if signed_out then app.sign_out(to: page)
+      elsif (email = account["email"]) then app.sign_in(email, to: page)
+      else page
+      end
+    end
+  end
+end

data/app/models/proctolog/server.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require "socket"
+
+module Proctolog
+  # The app a scenario opens: a checkout of the sitting's branch, served on a
+  # port of its own. The desk starts and stops it, and makes the state a
+  # scenario needs, with the commands the app names for both (App).
+  class Server
+    Error = Class.new(StandardError)
+    Down = Class.new(Error)
+    NotStartedHere = Class.new(Error)
+    RecipeFailed = Class.new(Error)
+    TookTooLong = Class.new(Error)
+    Unanswered = Class.new(Error)
+    Unready = Class.new(Error)
+
+    # How long a recipe gets, in seconds. Booting the app is most of it.
+    PATIENCE = 90
+    # Where a burst that names no sitting serves its app.
+    PORT = 3100
+
+    attr_reader :checkout, :branch, :port, :slug, :app
+
+    # PROCTOLOG_SITTING, a YAML mapping such as `{port: 3400, slug: deskb}`,
+    # overrides what the burst file says, so a trial never touches the
+    # owner's server.
+    def self.from(settings) = new(**settings.merge(YAML.safe_load(ENV.fetch("PROCTOLOG_SITTING", "{}"), symbolize_names: true)))
+
+    # With no branch, the checkout is served as it is.
+    def initialize(checkout:, port:, slug:, branch: nil, app: App.current)
+      @checkout, @branch, @port, @slug, @app = Pathname(checkout).expand_path, branch, port, slug, app
+    end
+
+    # Every port the app listens on answers.
+    def up? = app.listens(port).all? { listening?(it) }
+
+    def state
+      return :up if up?
+
+      started_here? ? :starting : :down
+    end
+
+    def address(path = "/") = "http://localhost:#{port}#{path}"
+
+    def log = logs.join("#{slug}.log")
+
+    def head
+      output, status = git("rev-parse", "HEAD")
+      output.strip if status.success?
+    end
+
+    # When the commit the checkout stands on was made.
+    def head_at
+      output, found = git("log", "-1", "--format=%cI")
+      Time.iso8601(output.strip) if found.success?
+    end
+
+    # The first line of the commit the checkout stands on, which says what it is.
+    def head_subject
+      output, found = git("log", "-1", "--format=%s")
+      output.strip.presence if found.success?
+    end
+
+    # Where the checkout stands: the branch it is on, or the sitting's branch
+    # when it is detached at that branch's tip, or else the commit.
+    def serving
+      name, on_a_branch = git("symbolic-ref", "--quiet", "--short", "HEAD")
+      return name.strip if on_a_branch.success?
+
+      at = head or return
+      (branch && tip(branch) == at) ? branch : at.first(8)
+    end
+
+    # Whether a commit is in the history the checkout stands on, so that a
+    # pull request's scenario opened here opens that pull request's work.
+    def holds?(commit) = commit.present? && git("merge-base", "--is-ancestor", commit, "HEAD").last.success?
+
+    # Whether the checkout's files differ from the commit it is at.
+    def changed?
+      output, status = git("status", "--porcelain", "--untracked-files=no")
+      status.success? && output.present?
+    end
+
+    # Whether the checkout keeps an app.yml of its own. One that has none is
+    # older than the commands the desk runs the app by, which may not do there
+    # what they say: open the app's own development database, for one.
+    def runnable? = checkout.join(Project::CONFIGURATION, App::FILE).exist?
+
+    def require_runnable
+      runnable? or raise Unready, "#{checkout.to_s.sub(Dir.home, "~")} has no #{Project::CONFIGURATION}/#{App::FILE} of its own, so it is older than the commands that run the app here, and they may not do there what they say. Bring it up to date, or name another checkout as the sitting."
+    end
+
+    # Whether the desk started the server that runs now: only that one it can stop.
+    def started_here? = leader.present?
+
+    # A server the desk started that has stopped since, not by its Stop, with
+    # its log to read.
+    def crashed? = pidfile.exist? && !started_here? && !up?
+
+    # The end of its log as words, without the colours a terminal would draw.
+    def last_lines(count = 8) = log.exist? ? log.readlines.last(count).join.gsub(/\e\[[\d;]*m/, "") : ""
+
+    def serve_command = app.serve(slug:, port:)
+
+    # The app's `prepare` and then its `serve`, in one shell that becomes the
+    # server, so a slow first preparation happens in the log, not the page.
+    def start_command
+      prepare = app.prepare(slug:, port:) or return serve_command
+      ["sh", "-c", "#{Shellwords.join(prepare)} && exec #{Shellwords.join(serve_command)}"]
+    end
+
+    def checkout_command = ["git", "-C", checkout.to_s, "checkout", "--detach", branch]
+
+    def enter_command(recipe, **arguments) = app.state(recipe, arguments, slug:, port:)
+
+    # Starts the app detached, its output in a log, and says what it did about
+    # the branch. The checkout is moved onto the branch only when it is not
+    # there already and has no changes of its own.
+    def start
+      return "The server is up already." if up? || started_here?
+
+      sentence = align
+      require_runnable
+      logs.mkpath
+      spawn_detached(start_command)
+      sentence
+    rescue SystemCallError => e
+      raise Error, "The server could not be started: #{e.message}"
+    end
+
+    def stop
+      pid = leader or raise NotStartedHere, "The desk did not start this server, so it cannot stop it. Stop it where it runs."
+      signal_group("TERM", pid)
+      within(10) { !alive?(pid) } or signal_group("KILL", pid)
+      pidfile.delete
+    end
+
+    # Makes the state a recipe names and returns what it printed last: the
+    # member to sign in as, and the places a scenario may open.
+    def enter(recipe, **arguments)
+      require_up
+      require_runnable
+      output, status = run(enter_command(recipe, **arguments)) ||
+        raise(TookTooLong, "The recipe #{recipe} took longer than #{PATIENCE} seconds and was stopped.")
+      account = parse(output) if status.success?
+      account || raise(RecipeFailed, "The recipe #{recipe} failed. Its last lines, without the backtrace:\n#{output.lines.grep_v(/^\s+from /).last(4).join}")
+    end
+
+    # Opens a review session for Grouse's overlay and returns what the app
+    # printed last: the session and its cookie, or the problem it refused for.
+    def open_overlay(brief) = answer(app.overlay(brief, slug:, port:), "The overlay")
+
+    # The notes written in a review session, as the app printed them.
+    def overlay_notes(session) = answer(app.notes(session, slug:, port:), "Reading the overlay's notes")
+
+    def require_up
+      up? or raise Down, "The server is down: nothing answers on #{app.listens(port).map { ":#{it}" }.to_sentence}. Start it first."
+    end
+
+    # Puts the checkout on the branch, detached, when it can, and says what it
+    # did or why it did not.
+    def align
+      return "Serving the checkout as it is." unless branch
+
+      at = tip(branch) or return "There is no branch #{branch} here, so the checkout stays as it is."
+      return "The checkout is at #{branch} already." if at == head
+      return "The checkout is not at #{branch} and has changes of its own, so it was left as it is." unless clean?
+
+      output, status = Open3.capture2e(*checkout_command)
+      status.success? ? "Checked out #{branch}, detached." : "#{branch} could not be checked out: #{output.lines.first&.strip}"
+    end
+
+    private
+
+    def pidfile = logs.join("#{slug}.pid")
+
+    def logs = Project.current.cache.join("servers")
+
+    def listening?(port)
+      Socket.tcp("localhost", port, connect_timeout: 0.5) { true }
+    rescue SystemCallError
+      false
+    end
+
+    def git(*) = Open3.capture2e("git", "-C", checkout.to_s, *)
+
+    def tip(name)
+      output, found = git("rev-parse", "--verify", "--quiet", "#{name}^{commit}")
+      output.strip if found.success?
+    end
+
+    def clean? = git("status", "--porcelain", "--untracked-files=no").first.empty?
+
+    # The output and exit status of a command run in the checkout; nil when it
+    # was stopped for taking too long.
+    def run(command)
+      Outside.run do |environment|
+        Open3.popen2e(environment, *command, chdir: checkout.to_s) do |input, output, process|
+          input.close
+          reading = Thread.new { output.read }
+          if process.join(PATIENCE)
+            [reading.value, process.value]
+          else
+            Process.kill("TERM", process.pid)
+            reading.kill
+            nil
+          end
+        end
+      end
+    end
+
+    # The JSON a command of the app's printed last, whether it succeeded or
+    # refused in words; raises when it printed none, or took too long.
+    def answer(command, what)
+      require_runnable
+      output, = run(command) || raise(TookTooLong, "#{what} took longer than #{PATIENCE} seconds and was stopped.")
+      parse(output) || raise(Unanswered, "#{what} printed no JSON. Its last lines, without the backtrace:\n#{output.lines.grep_v(/^\s+from /).last(4).join}")
+    end
+
+    def parse(output)
+      account = JSON.parse(output.lines.last.to_s)
+      account if account.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # The log and the pidfile are found before the app's environment stands
+    # in for the desk's, which may not say where the cache is.
+    def spawn_detached(command)
+      output = log.to_s
+      pid = Outside.run { Process.spawn(it, *command, chdir: checkout.to_s, pgroup: true, in: File::NULL, out: [output, "w"], err: %i[child out]) }
+      Process.detach(pid)
+      pidfile.write("#{pid} #{started_at(pid)}")
+    end
+
+    # The process group the desk started, while it still runs. A pid alone may
+    # have been given to another process since, so it is kept with its start time.
+    def leader
+      return unless pidfile.exist?
+
+      pid, started = pidfile.read.split(" ", 2)
+      pid.to_i if started && started_at(pid) == started
+    end
+
+    def started_at(pid) = Open3.capture2("ps", "-o", "lstart=", "-p", pid.to_s).first.strip
+
+    def signal_group(name, pid)
+      Process.kill(name, -pid)
+    rescue Errno::ESRCH
+      nil
+    end
+
+    def alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def within(seconds)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+      until yield
+        return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+        sleep 0.2
+      end
+      true
+    end
+  end
+end

data/app/models/proctolog/since.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Proctolog
+  # What moved in a pull request since the owner's mark: its code, between the
+  # head then and the head now, and its description, between the revision that
+  # stood then and the text now. Each is worked out when asked, from the
+  # repository on this Mac and from GitHub's edit history; nothing is copied.
+  class Since
+    FileChange = Data.define(:path, :added, :removed) do
+      # The lines of each file as `git diff --numstat` counts them.
+      def self.parse(numstat)
+        numstat.each_line(chomp: true).map do |line|
+          line.split("\t", 3).then { |added, removed, path| new(path:, added: Integer(added, exception: false), removed: Integer(removed, exception: false)) }
+        end
+      end
+
+      # Git counts no lines in a binary file.
+      def binary? = added.nil?
+    end
+
+    # The files that differ between two heads, among those the pull request
+    # changed at either: `dropped` are those it changed at the first and no
+    # longer does. A commit or a base branch this Mac does not hold is named in
+    # `absent`, and no file is listed then.
+    Code = Data.define(:from, :to, :files, :absent, :dropped, :compare_url) do
+      def dropped?(file) = dropped.include?(file.path)
+    end
+
+    # What a description lost and gained, as paragraphs, since the revision
+    # that stood at `at`.
+    Paragraphs = Data.define(:at, :removed, :added) do
+      # A blank line inside a code fence splits it in two: the comparison does not read Markdown.
+      def self.between(before, after, at:)
+        [before, after].map { split(it) }.then { |was, is| new(at:, removed: was - is, added: is - was) }
+      end
+
+      def self.split(text) = text.gsub("\r\n", "\n").split(/\n[ \t]*\n/).map(&:strip).compact_blank
+
+      def unchanged? = removed.empty? && added.empty?
+    end
+
+    # The revision that stood at `at` is no longer in GitHub's history.
+    Forgotten = Data.define(:at)
+
+    # `history` answers `description_revisions(number)`, as Github does.
+    def initialize(stop:, mark:, repository:, history:, root: Rails.root)
+      @stop, @mark, @repository, @history, @root = stop, mark, repository, history, root
+    end
+
+    # Nothing while the head is the one marked.
+    def code
+      return if mark.head == stop.head_oid
+
+      absent = [mark.head, stop.head_oid, base].reject { held?(it) }
+      was, is = absent.empty? ? [mark.head, stop.head_oid].map { own_files(it) } : [[], []]
+      Code.new(from: mark.head, to: stop.head_oid, files: differing(was | is), absent:, dropped: was - is,
+        compare_url: ("https://github.com/#{@repository}/compare/#{mark.head}...#{stop.head_oid}" if stop.pull_request.opened?))
+    end
+
+    # Nothing while the description is the one marked. The revision that stood
+    # then is found in the history by the time of the edit the mark recorded.
+    def description
+      return if mark.description == stop.description.digest
+
+      at = Time.iso8601(mark.described_at.to_s)
+      revision = @history.description_revisions(stop.number).find { it.at == at }
+      revision ? Paragraphs.between(revision.text, stop.description.to_s, at:) : Forgotten.new(at:)
+    end
+
+    private
+
+    attr_reader :stop, :mark
+
+    # The branch the pull request sits on, as this Mac last fetched it; one
+    # nobody has opened yet sits on a branch of this Mac.
+    def base = stop.pull_request.opened? ? "origin/#{stop.base}" : stop.base
+
+    def held?(commit) = git("cat-file", "-e", "#{commit}^{commit}").last.success?
+
+    # The files a pull request changes at one head: those of its own commits.
+    # Its base may have been rebuilt since that head was pushed (a restack) and
+    # still holds the lower layers' commits as the same patches, which
+    # `--cherry-pick` leaves out; against the base's tip alone, the diff of an
+    # old head would count every file of every layer under it.
+    def own_files(head)
+      git!("log", "--cherry-pick", "--right-only", "--no-merges", "--no-renames", "--name-only", "--format=", "#{base}...#{head}").lines(chomp: true).compact_blank.uniq
+    end
+
+    # The files among these that differ between the two heads. `:(top,literal)`
+    # takes each path from the top of the repository as it is written, wherever
+    # the desk is run from.
+    # shortcut: a layer under this one that changed a shared file between the heads shows it as this pull request's; git cannot tell without the base the old head stood on, so upgrade when a mark keeps it.
+    def differing(paths)
+      return [] if paths.empty? # with no path, git would list the whole diff
+
+      FileChange.parse(git!("diff", "--no-renames", "--numstat", mark.head, stop.head_oid, "--", *paths.map { ":(top,literal)#{it}" }))
+    end
+
+    def git!(*args)
+      output, status = git(*args)
+      status.success? ? output : raise(Failure, "git could not compare the heads of ##{stop.number}: #{output.strip}")
+    end
+
+    def git(*) = Open3.capture2e("git", "-C", @root.to_s, *)
+  end
+end

data/app/models/proctolog/size.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # How big a window to open, and what it says it is: the desk's desktop or
+  # phone, a size the app names in its app.yml, or a width and a height.
+  class Size < Data.define(:name, :width, :height, :user_agent)
+    IPHONE = "Mozilla/5.0 (iPhone; CPU iPhone OS 18_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) " \
+             "Version/18.6 Mobile/15E148 Safari/604.1"
+
+    OWN = {
+      "desktop" => {width: 1440, height: 900, user_agent: nil},
+      "phone" => {width: 390, height: 844, user_agent: IPHONE}
+    }.freeze
+
+    # A name or a width and a height. Whether the app names that size is asked
+    # when the window opens, so a registry reads before its app.yml does.
+    def self.valid?(spec) = spec in String | [Integer, Integer]
+
+    def self.of(spec, app: App.current)
+      case spec
+      in [Integer => width, Integer => height] then new(name: "#{width}x#{height}", width:, height:, user_agent: nil)
+      in String
+        named = OWN[spec] || app.size(spec) || raise(App::Missing, "No size is named #{spec}: it is not the desk's desktop or phone, and app.yml's sizes do not name it.")
+        new(name: spec, user_agent: nil, **named)
+      end
+    end
+
+    def to_s = name
+  end
+end

data/app/models/proctolog/standing.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Where one pull request stands, worked out from facts: the owner's marks and
+  # what GitHub says now. Nothing is set by hand but "good to go" and "waiting
+  # on"; everything else follows.
+  class Standing
+    # Something that should hold before the pull request goes. `met` is nil for
+    # a condition only the owner can judge. `about` names the part of the page
+    # it is about, where the page can take the owner there.
+    Condition = Data.define(:name, :met, :detail, :about) do
+      def initialize(about: nil, **) = super
+    end
+
+    attr_reader :stop, :marks, :progress
+
+    # `under` is the standing of the layer this one sits on. `above` holds the
+    # layers over it: a suite run at the top of a stack vouches for what is
+    # under it. `scenarios` are the names of this pull request's scenarios, and
+    # `named` the preconditions the burst file names for it. `progress` is how
+    # far the owner's choices on its decisions are; without one, only the boxes
+    # ticked on GitHub count as reviewed.
+    def initialize(stop:, marks:, progress: nil, under: nil, above: [], scenarios: [], named: [])
+      @stop, @marks, @under, @above, @scenarios, @named = stop, marks, under, above, scenarios, named
+      @progress = progress || Choices::Progress.of(decisions.index_with(&:ticked))
+    end
+
+    # Whose move it is: :waiting on something outside, the :agent's, the
+    # :owner's, or nobody's because it is :settled.
+    def turn
+      if marks.waiting_on then :waiting
+      elsif for_the_agent.any? then :agent
+      elsif good_to_go? && !changed? && for_the_owner.empty? then :settled
+      else :owner
+      end
+    end
+
+    def settled? = turn == :settled
+
+    def good_to_go? = marks.good_to_go.present?
+
+    # What moved since "good to go" was given: the code, the description, both
+    # or neither.
+    def changed
+      return [] unless good_to_go?
+
+      [("code" if marks.good_to_go.head != stop.head_oid), ("description" if marks.good_to_go.description != stop.description.digest)].compact
+    end
+
+    def changed? = changed.any?
+
+    # What is open, in a few words each: the reasons behind the turn.
+    def open = [*("changed since your mark: #{changed.to_sentence}" if changed?), *otherwise_open]
+
+    # What is open besides a change since the mark, which the route says in a column of its own.
+    def otherwise_open = [*for_the_agent, *for_the_owner, *to_review, *("not yet marked" unless good_to_go?)]
+
+    # What is left of its decisions, as one of the reasons: "22 of 24 decisions
+    # to review". A page that shows the count beside them leaves it out.
+    def to_review
+      return [] if progress.done?
+
+      ["#{progress.reviewed.zero? ? progress.left : "#{progress.left} of #{progress.total}"} #{"decision".pluralize(progress.total)} to review"]
+    end
+
+    def conditions
+      [decisions_reviewed, notes_confirmed, verification_current, layers_under_settled,
+        *@named.map { Condition.new(name: it, met: nil, detail: "named in the burst file; yours to judge") }]
+    end
+
+    # The conditions that facts decide, which "2 of 4 met" counts.
+    def judged = conditions.reject { it.met.nil? }
+
+    # Whether its scenarios were tried on this head, when it has any. Said beside
+    # the conditions, never one of them: a pull request can go without them.
+    def scenarios_seen
+      return if @scenarios.empty?
+
+      seen = @scenarios.select { marks.scenarios.dig(it, "head") == stop.head_oid }
+      failed = seen.select { marks.scenarios.dig(it, "result") == "not_ok" }
+      Condition.new(name: "Its scenarios are tried on this head", met: seen.size == @scenarios.size && failed.empty?,
+        detail: ["#{seen.size - failed.size} of #{@scenarios.size}", ("#{failed.size} not as expected" if failed.any?)].compact.join(", "))
+    end
+
+    private
+
+    def decisions = stop.description.decisions
+
+    def for_the_agent
+      [*("#{count(notes(:open).size, "note")} open" if notes(:open).any?),
+        *("#{count(stop.open_threads, "review thread")} unresolved" if stop.open_threads.positive?)]
+    end
+
+    def for_the_owner = notes(:addressed).any? ? ["#{count(notes(:addressed).size, "note")} addressed, to confirm"] : []
+
+    def notes(state) = marks.notes.select { it.state == state.to_s }
+
+    def count(number, noun) = "#{number} #{noun.pluralize(number)}"
+
+    def decisions_reviewed
+      detail = ["#{progress.reviewed} of #{progress.total} reviewed", ("#{progress.ticked} ticked on GitHub" if progress.ticked.positive?)].compact.join(", ")
+      Condition.new(name: "Its decisions are reviewed", met: progress.done?, detail: progress.any? ? detail : "it has none", about: :decisions)
+    end
+
+    def notes_confirmed
+      live = marks.notes.select(&:live?)
+      Condition.new(name: "Your notes are confirmed", met: live.empty?,
+        detail: live.empty? ? "none waiting" : live.group_by(&:state).map { |state, notes| "#{notes.size} #{state}" }.to_sentence)
+    end
+
+    # A commit the Verification section names that is still the head of this
+    # pull request, or of a layer above it.
+    def verification_current
+      named = stop.description.section("Verification").scan(/`(\h{7,40})`/).flatten
+      vouching = [stop, *@above].find { |layer| named.any? { layer.head_oid.start_with?(it) } }
+      Condition.new(name: "Verification is of the present head", met: vouching.present?,
+        detail: vouching ? "it names `#{vouching.head_oid[0, 8]}`, the head of ##{vouching.number}" : "it names no commit that is a head now")
+    end
+
+    def layers_under_settled
+      Condition.new(name: "The layers under it are settled", met: @under.nil? || @under.settled_through?,
+        detail: @under.nil? ? "it sits on nothing in this burst" : (@under.unsettled_below || "all settled"))
+    end
+
+    protected
+
+    def settled_through? = settled? && (@under.nil? || @under.settled_through?)
+
+    # The highest layer at or below this one that is not settled, named.
+    def unsettled_below = settled? ? @under&.unsettled_below : "##{stop.number} is not settled"
+  end
+end