proctolog 0.1.0

data/app/models/proctolog/membership.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # What the owner last saw of a burst's membership, in one YAML file beside
+  # its marks: its pull requests, each listed stack's members from the bottom
+  # up, its pull requests as the last handover found them, and those opened
+  # on GitHub since they waited unopened, each with the number it had.
+  #
+  # A reading alone never moves it: the owner does, by dismissing what joined
+  # or left, or by writing a handover. Nor does a reading that could not say
+  # where GitHub's stacks stand, which says nothing of who joined or left.
+  class Membership
+    attr_reader :pull_requests, :stacks, :handed_over, :opened
+
+    def self.of(burst) = new(Marks.directory_of(burst).join("membership.yml"))
+
+    # A file that is not as the desk reads it is left for the owner to mend,
+    # as a marks file is.
+    def initialize(path)
+      @path = path
+      stored = (path.exist? && YAML.safe_load_file(path)) || {}
+      @pull_requests = stored.fetch("pull_requests", []).map { number(it) }
+      @stacks = stored.fetch("stacks", {}).to_h { |stack, members| [Integer(stack), members.map { number(it) }] }
+      @handed_over = stored.fetch("handed_over", @pull_requests).map { number(it) }
+      @opened = stored.fetch("opened", {}).to_h { |now, was| [number(now), was.to_s] }
+    rescue Psych::Exception, ArgumentError, TypeError, NoMethodError => e
+      raise Failure, "The membership file #{path} is not as the desk reads it (#{e.message.lines.first&.strip}). The desk left it as it is: mend it, or move it aside to start the membership again."
+    end
+
+    def kept? = @path.exist?
+
+    # The pull requests that joined the burst, and those that left it, since
+    # the owner last looked.
+    def joined(route) = counting?(route) ? numbers(route) - pull_requests : []
+
+    def left(route) = counting?(route) ? pull_requests - numbers(route) : []
+
+    # Those that left since the last handover: their choices are not yet handed over.
+    def departed(route) = kept? ? handed_over - numbers(route) : []
+
+    # The first reading of a burst names nothing: it is where joining and
+    # leaving count from.
+    def start(route) = (keep(route, members: numbers(route), handed_over: numbers(route)) if !kept? && route.stacks_known?)
+
+    # The owner has seen that this pull request joined, that it left, or
+    # that it was opened.
+    def acknowledge(number, route)
+      return seen_opened(number) if opened.key?(number)
+      return unless route.stacks_known?
+
+      keep(route, members: numbers(route).include?(number) ? pull_requests | [number] : pull_requests - [number], handed_over:)
+    end
+
+    # It waited unopened as `was`, and is open as `number` now: said until
+    # the owner has seen it.
+    def note_opened(number, was:)
+      @opened[number] = was
+      write
+    end
+
+    # A handover takes in what the burst holds now.
+    def hand_over(route) = (keep(route, members: numbers(route), handed_over: numbers(route)) if route.stacks_known?)
+
+    private
+
+    def number(written) = PullRequest.number(written) || raise(ArgumentError, "#{written.inspect} is no pull request's number")
+
+    def seen_opened(number)
+      @opened.delete(number)
+      write
+    end
+
+    def counting?(route) = kept? && route.stacks_known?
+
+    def numbers(route) = route.map(&:number)
+
+    def keep(route, members:, handed_over:)
+      @pull_requests, @handed_over = members, handed_over
+      @stacks = route.parts.select(&:stack?).to_h { [it.id, route.stops_of(it).map(&:number)] }
+      write
+    end
+
+    # Written beside the file and moved over it, so a reader never meets half a file.
+    def write
+      @path.dirname.mkpath
+      draft = @path.sub_ext(".yml.part")
+      draft.write({"pull_requests" => pull_requests, "stacks" => stacks, "handed_over" => handed_over, "opened" => opened.presence}.compact.to_yaml(line_width: -1))
+      draft.rename(@path)
+    end
+  end
+end

data/app/models/proctolog/mentions.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The pull requests a # in the owner's words can name: every one of the
+  # repository, open, merged or closed. GitHub is read in full once and the
+  # answer kept for the next start of the desk; after that it is asked only
+  # for what changed since the last change kept, and no more than once a
+  # minute.
+  class Mentions
+    # A pull request, as a # names it.
+    Mention = Data.define(:number, :title, :state, :url) do
+      def self.from(node) = new(number: node.fetch("number"), title: node.fetch("title"), state: node.fetch("state").downcase, url: node.fetch("url"))
+
+      def digits = number.to_s
+
+      def open? = state == "open"
+    end
+
+    # A # in the owner's words: one that begins a word, and its digits end one.
+    WRITTEN = /(?<![\w&#])#\d+(?!\w)/
+
+    # How many a # offers at once.
+    OFFERED = 8
+
+    # How long what GitHub said is taken for what it says now.
+    GOOD_FOR = 1.minute
+
+    # A desk serves several pages at once: one asks GitHub, the others wait
+    # for its answer instead of asking again.
+    ASKING = Mutex.new
+
+    # Those of the checkout's own repository; none for a checkout that has
+    # no repository on GitHub.
+    def self.here = Project.current.github_repository&.then { new(Github.new(it)) }
+
+    def initialize(github) = @github = github
+
+    # A repository the desk has never read is read behind the owner's back
+    # (ReadMentionsAheadJob).
+    def read_ahead
+      ReadMentionsAheadJob.perform_later(@github.repository) unless Rails.cache.exist?(cached) || kept&.file?
+    end
+
+    # Those a # with these digits may mean: the pull request with that very
+    # number first, then those whose number begins so, the newest first.
+    def matching(digits)
+      begun = every.select { it.digits.start_with?(digits) }
+      exact, longer = begun.partition { it.digits == digits }
+      [*exact, *longer.max_by(OFFERED, &:number)].first(OFFERED)
+    end
+
+    # The pull request a number names, of those already kept: a page that
+    # shows the owner's words asks GitHub nothing.
+    def [](number) = in_hand&.dig(:nodes, number)&.then { Mention.from(it) }
+
+    # What GitHub holds, asked again no more than once a minute. What is in
+    # hand is read again once the way is clear: the page that asked meanwhile
+    # may have brought it up to date.
+    def up_to_date
+      ASKING.synchronize do
+        @in_hand = nil
+        fresh? ? in_hand : brought_up_to_date
+      end
+    end
+
+    private
+
+    def every = up_to_date.fetch(:nodes).values.map { Mention.from(it) }
+
+    def in_hand = @in_hand ||= Rails.cache.read(cached) || from_disk
+
+    def fresh? = in_hand&.fetch(:checked)&.after?(GOOD_FOR.ago)
+
+    # The first reading asks for every pull request; the next only for those
+    # that changed at the last change it kept, or since. When GitHub cannot
+    # be asked, what is kept is good enough.
+    def brought_up_to_date
+      nodes = in_hand&.fetch(:nodes) || {}
+      since = nodes.values.pluck("updatedAt").max&.then { Time.iso8601(it) }
+      changed = @github.pull_requests_changed(since:).index_by { it.fetch("number") }
+      keep(checked: Time.current, nodes: nodes.merge(changed))
+    rescue Github::Unreachable
+      in_hand or raise
+    end
+
+    def keep(reading)
+      Rails.cache.write(cached, reading)
+      to_disk(reading)
+      @in_hand = reading
+    end
+
+    def cached = [:mentions, @github.repository]
+
+    # Where the reading waits for the next start of the desk. A desk that is
+    # only being tried out keeps none.
+    def kept = (Project.current.cache.join("mentions", "#{@github.repository.tr("/", "-")}.json") if Desk.config.x.keeps_readings)
+
+    # A file that cannot be read is as good as none: GitHub is asked again.
+    def from_disk
+      return unless kept&.file?
+
+      JSON.parse(kept.read).then { |read| {checked: Time.iso8601(read.fetch("checked")), nodes: read.fetch("nodes").index_by { it.fetch("number") }} }
+    rescue JSON::ParserError, KeyError, ArgumentError
+      nil
+    end
+
+    # Written beside the file and moved over it, so a start never meets half a reading.
+    def to_disk(reading)
+      return unless kept
+
+      kept.dirname.mkpath
+      draft = kept.sub_ext(".json.part")
+      draft.write(JSON.generate(checked: reading.fetch(:checked).iso8601(6), nodes: reading.fetch(:nodes).values))
+      draft.rename(kept)
+    end
+  end
+end

data/app/models/proctolog/note.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Something the owner wrote about a pull request, pinned to the place it is
+  # about: words of the description, a region of a picture, a moment of a
+  # recording, a scenario. A note with no place is about the whole pull request.
+  class Note < Data.define(:id, :kind, :state, :text, :written_at, :place, :reply)
+    KINDS = %w[change question remark].freeze
+    STATES = %w[open addressed confirmed withdrawn].freeze
+
+    # How far around a quote its surroundings are compared, in characters.
+    NEAR = 64
+
+    # How many characters of what stood around a quote must still stand there
+    # for a place to be its place: a word's worth, or all of it when less was kept.
+    CONFIRMING = 8
+
+    # Words this long are their own evidence and are followed wherever they
+    # moved: about seven words do not turn up by chance in a place they were not
+    # written. Shorter ones ("Expected: 0 failures.") recur through a description.
+    DISTINCTIVE = 40
+
+    # Words of a description, kept with a little of what stands before and
+    # after them, so they are found again wherever an edit moves them.
+    Quote = Data.define(:exact, :before, :after, :section) do
+      # A form sends a line break as two characters and a description has one,
+      # so the words are kept as the description has them.
+      def initialize(exact:, before:, after:, section:) = super(exact: exact.delete("\r"), before: before&.delete("\r"), after: after&.delete("\r"), section:)
+
+      # Where the words stand in a text now, as a range of it; nil when they
+      # are no longer there. Of several places, the one whose surroundings fit,
+      # and that one only while enough of its surroundings do or the words are
+      # distinctive: a phrase standing somewhere it was not written is not the note's.
+      def locate(text)
+        spot = spots(text).max_by { fit(text, it) } or return
+        spot if distinctive? || fit(text, spot) >= [CONFIRMING, before.to_s.length + after.to_s.length].min
+      end
+
+      # How many characters of the surroundings stand round the words where
+      # they stand best in a text; nil when the words are not in it.
+      def fit_in(text) = spots(text).map { fit(text, it) }.max
+
+      def distinctive? = exact.squish.length >= DISTINCTIVE
+
+      private
+
+      def spots(text) = text.enum_for(:scan, pattern).map { Regexp.last_match.begin(0)...Regexp.last_match.end(0) }
+
+      # The words, with any run of white space standing for any other.
+      def pattern = Regexp.new(exact.split.map { Regexp.escape(it) }.join('\s+'))
+
+      def fit(text, spot)
+        shared(text[[spot.begin - NEAR, 0].max...spot.begin].reverse, before.to_s.reverse) + shared(text[spot.end, NEAR], after.to_s)
+      end
+
+      def shared(one, other) = one.each_char.zip(other.each_char).take_while { |a, b| a == b }.size
+    end
+
+    # A rectangle of a picture: `box` is x, y, width and height as fractions of
+    # the picture, so it holds at any size. `picture` is the alt text, `asset`
+    # the uploaded file it was drawn on.
+    Region = Data.define(:picture, :asset, :box)
+
+    # A moment of a recording: seconds from its start, the step it falls in,
+    # that frame saved as a picture, and a rectangle on it when one was drawn.
+    Moment = Data.define(:recording, :time, :step, :frame, :box)
+
+    Scenario = Data.define(:name)
+
+    PLACES = {"quote" => Quote, "picture" => Region, "recording" => Moment, "scenario" => Scenario}.freeze
+
+    STATES.each { |state| define_method(:"#{state}?") { self.state == state } }
+    KINDS.each { |kind| define_method(:"#{kind}?") { self.kind == kind } }
+
+    def self.restored(stored)
+      name, place = PLACES.find { |key, _| stored.key?(key) }
+      new(**%w[id kind state text reply].index_with { stored[it] }.symbolize_keys,
+        written_at: Time.iso8601(stored.fetch("written_at")),
+        place: place&.new(**place.members.index_with { stored[name][it.to_s] }))
+    end
+
+    # Still needs someone: the agent while it is open, the owner once addressed.
+    def live? = open? || addressed?
+
+    # The decision of a description that this note answers otherwise: a change
+    # asked for on words of a box. A question or a remark leaves the box open.
+    def answers_in(description) = (description.decision_quoted_by(place) if change? && (place in Quote[section: Description::DECISIONS]))
+
+    def stored
+      {"id" => id, "kind" => kind, "state" => state, "text" => text, "written_at" => written_at.iso8601,
+       PLACES.key(place.class) => place&.to_h&.stringify_keys&.compact, "reply" => reply}.compact
+    end
+  end
+end

data/app/models/proctolog/outside.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The environment a program that is not the desk's runs in when the desk
+  # starts it: the reviewed app's commands, Diffle. Whatever put the desk on
+  # its own Ruby and gems stays with the desk, so that the app finds its own:
+  #
+  # - from a checkout, Bundler's variables;
+  # - as an rv tool, the gem home rv made for it, the variables that name its
+  #   Ruby, and the folders rv put first on the PATH;
+  # - and a version manager's Ruby of the desk's (asdf, for one), which leaves
+  #   the PATH while another ruby is still on it.
+  module Outside
+    # rv sets these for the tool it runs; the shell it was run from had none.
+    RV = %w[GEM_HOME GEM_PATH RUBY_ROOT RUBY_ENGINE RUBY_VERSION].freeze
+
+    # Yields what to hand Process.spawn, with Bundler's variables gone from
+    # ENV while the block runs.
+    def self.run(&) = defined?(Bundler) ? Bundler.with_unbundled_env { yield environment } : yield(environment)
+
+    def self.environment(env = ENV, installation: Installation.here, desks: RbConfig::CONFIG["bindir"])
+      path = env.fetch("PATH", "")
+      return {"BUNDLE_GEMFILE" => nil, "PATH" => path_for_the_app(path, desks:)} unless installation.rv_tool?
+
+      RV.index_with(nil).merge("BUNDLE_GEMFILE" => nil, "PATH" => path_for_the_app(before_rv(path, env), desks:))
+    end
+
+    # The PATH as the shell had it: rv puts its Ruby's folders, and its gems',
+    # in front.
+    def self.before_rv(path, env)
+      own = [env["RUBY_ROOT"], env["GEM_HOME"], *env.fetch("GEM_PATH", "").split(File::PATH_SEPARATOR)].compact_blank
+      path.split(File::PATH_SEPARATOR).drop_while { |entry| own.any? { entry.start_with?("#{it}/") } }.join(File::PATH_SEPARATOR)
+    end
+
+    # The app's bin/ scripts would run under the desk's own Ruby, put first on
+    # the PATH by a version manager, rather than the Ruby the app names. It is
+    # left out whenever another ruby is still on the PATH.
+    def self.path_for_the_app(path, desks: RbConfig::CONFIG["bindir"])
+      entries = path.split(File::PATH_SEPARATOR)
+      rest = entries - [desks]
+      another = rest.any? { File.executable?(File.join(it, "ruby")) }
+      (another ? rest : entries).join(File::PATH_SEPARATOR)
+    end
+  end
+end

data/app/models/proctolog/overlay/brief.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class Overlay
+    # What the desk tells Grouse of a scenario when it opens its overlay: the
+    # strip's label, who narrates, what to expect and the steps, and the way
+    # back to the desk. Grouse checks every field as the session opens, so the
+    # brief keeps within its limits; the rest of `metadata` is the desk's own,
+    # and no page shows it.
+    class Brief < Data.define(:label, :reviewer_label, :external_ref, :metadata)
+      SOURCE = "proctolog"
+      LABEL = 200
+      EXPECT = 1_000
+      STEP = 500
+      STEPS = 50
+      METADATA = 16_000
+
+      # "grouse-rails #7 · Send a note", or "sartoria · Step 2 · Sign in" for a
+      # step of the sitting. `steps` are the scenario's, one line each.
+      def self.for(scenario, burst:, steps:, head:, desk_url:)
+        label = [[Project.current.name, ("##{scenario.pr}" if scenario.pr)].compact.join(" "), ("Step #{scenario.sitting}" if scenario.sitting), scenario.name]
+        new(label: line(label.compact.join(" · "), LABEL), reviewer_label: "#{Owner.current.first_name} (PRoctolog)",
+          external_ref: line("#{SOURCE}:#{burst.slug}/#{scenario.to_param}#{"@#{head}" if head}", LABEL),
+          metadata: {expect: scenario.expect&.truncate(EXPECT), steps: steps.map { line(plain(it), STEP) }.compact_blank.first(STEPS), desk_url:,
+                     burst: burst.slug, pr: scenario.pr, scenario: scenario.to_param, recipe: scenario.recipe, head:}.compact).fitted
+      end
+
+      # A step as GitHub sets it, read as words: no code ticks, bold or links.
+      def self.plain(text) = text.gsub(/\[([^\]]+)\]\([^)\s]+\)/, '\1').delete("`").gsub("**", "")
+
+      def self.line(text, most) = text.squish.truncate(most)
+
+      # The member's email never reaches the strip: wherever the label, what to
+      # expect or a step names it, it says "the member".
+      def without(email)
+        return self if email.blank?
+
+        unnamed = ->(text) { text&.gsub(email, "the member") }
+        with(label: unnamed.call(label), metadata: metadata.merge({expect: unnamed.call(metadata[:expect]), steps: metadata[:steps]&.map(&unnamed)}.compact))
+      end
+
+      # Within Grouse's limit for all of `metadata`, losing steps from the end.
+      def fitted
+        return self if metadata.to_json.bytesize <= METADATA || metadata[:steps].blank?
+
+        with(metadata: metadata.merge(steps: metadata[:steps][...-1])).fitted
+      end
+
+      def as_json(*) = {source: SOURCE, label:, reviewer_label:, external_ref:, metadata:}
+    end
+  end
+end

data/app/models/proctolog/overlay/written.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class Overlay
+    # A note the owner wrote in the overlay, as its app's `notes` printed it
+    # (Grouse's export at its standard detail), and as the desk pins it on the
+    # scenario: their words, then where Grouse keeps the note.
+    class Written < Data.define(:id, :intent, :body, :transcript, :transcription, :url, :route, :templates, :created_at)
+      # Grouse's intents as the desk's kinds of note; approving, or saying
+      # nothing of what is wanted, is a remark.
+      KINDS = {"fix" => "change", "change" => "change", "question" => "question"}.freeze
+      TEMPLATES = 3
+
+      def self.from(note, app: nil)
+        new(id: note.fetch("public_id"), intent: note["intent"], body: note["body"], transcript: note["transcript"],
+          transcription: note["transcription_state"], url: (app && note["url"]&.start_with?("/")) ? URI.join(app, note["url"]).to_s : note["url"], route: note["route"],
+          templates: Array(note["templates"]), created_at: note["created_at"].to_s)
+      end
+
+      # A voice note waits for its words while they are being written out;
+      # once done, failed or not to be, it is pinned as it stands.
+      def ready? = transcription != "pending"
+
+      def kind = KINDS.fetch(intent.to_s, "remark")
+
+      def text
+        words = [body, transcript].map { it.to_s.strip }.compact_blank
+        words = ["A voice note with no words (#{transcription.to_s.tr("_", " ")})."] if words.empty?
+        [*words, [url, route, *templates.first(TEMPLATES)].compact_blank.join(" · ")].join("\n\n")
+      end
+    end
+  end
+end

data/app/models/proctolog/overlay.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Grouse's overlay in the app under review, labelled with a scenario: a
+  # review session of the app's, which one press of the scenario's button
+  # opened through app.yml's `overlay` (docs/manual/app.md). It is kept in the
+  # marks beside its scenario, with the ids of the Grouse notes pinned from it,
+  # so that a pull pins each note once. A second press opens a second one.
+  class Overlay < Data.define(:session, :opened, :head, :pinned)
+    # The session a press opened, and the cookie that shows the overlay to the
+    # browser it opens, a whole Set-Cookie line as the app printed it.
+    Opened = Data.define(:session, :cookie) do
+      def missing = nil
+    end
+
+    # Why a press opened the app without the overlay, in words that follow
+    # "Grouse's overlay did not open: ".
+    Refused = Data.define(:reason) do
+      def cookie = nil
+
+      def session = nil
+
+      def missing = "Grouse's overlay did not open: #{reason}"
+    end
+
+    # Opens a session for the brief. A refusal is said, and never stops the
+    # entering: the member is signed in all the same.
+    def self.open(server, brief)
+      case server.open_overlay(brief).symbolize_keys
+      in {public_id: String => session, cookie: String => cookie} then Opened.new(session:, cookie:)
+      in {problem: problem, **said} then Refused.new(reason: refusal(problem, said[:errors]))
+      else Refused.new(reason: "the app printed no session.")
+      end
+    rescue Server::Error => e
+      Refused.new(reason: e.message)
+    end
+
+    # "the app said invalid (metadata.steps: too_long)." Grouse names the
+    # fields of a refusal, never their values.
+    def self.refusal(problem, errors)
+      fields = errors.to_h.map { |field, codes| "#{field}: #{Array(codes).join(", ")}" }
+      "the app said #{problem}#{" (#{fields.join("; ")})" if fields.any?}."
+    end
+
+    # What a pull brought: notes pinned, and notes still waiting on their words.
+    Pulled = Data.define(:pinned, :waiting) do
+      def sentence
+        found = pinned.zero? ? "No new notes in Grouse's overlay." : "Pinned #{pinned} #{"note".pluralize(pinned)} from Grouse's overlay."
+        later = " #{waiting} #{(waiting == 1) ? "waits" : "wait"} for #{(waiting == 1) ? "its" : "their"} words: pull again in a moment." if waiting.positive?
+        "#{found}#{later}"
+      end
+    end
+
+    # Pins on a scenario every note written in its overlays that is not pinned
+    # yet. Each overlay's `notes` boots the app, so it is run when asked for.
+    def self.pull(server, marks, scenario)
+      counts = marks.overlays_of(scenario).map do |overlay|
+        answer = server.overlay_notes(overlay.session)
+        fresh = overlay.unpinned(answer, app: server.address).each { marks.pin_written(scenario, overlay:, written: it) }
+        [fresh.size, overlay.waiting(answer)]
+      end
+      pinned, waiting = counts.transpose.map(&:sum)
+      Pulled.new(pinned: pinned.to_i, waiting: waiting.to_i)
+    end
+
+    def self.restored(stored) = new(session: stored.fetch("session"), opened: stored["opened"], head: stored["head"], pinned: stored.fetch("pinned", []))
+
+    def self.opening(session, head:) = new(session:, opened: Time.current.iso8601, head:, pinned: [])
+
+    # The notes of what its app's `notes` printed that are ready to pin and are
+    # not pinned yet, the oldest first.
+    # A link Grouse printed as a path, as a runner has no host to give it, is
+    # made whole on `app`, the address the sitting serves the app on.
+    def unpinned(answer, app: nil) = written(answer, app:).select(&:ready?).reject { pinned.include?(it.id) }
+
+    # The notes still waiting on their words.
+    def waiting(answer) = written(answer).count { !it.ready? }
+
+    def pinning(id) = with(pinned: pinned | [id])
+
+    def stored = {"session" => session, "opened" => opened, "head" => head, "pinned" => pinned.presence}.compact
+
+    private
+
+    def written(answer, app: nil) = answer.fetch("notes", []).map { Written.from(it, app:) }.sort_by(&:created_at)
+  end
+end

data/app/models/proctolog/owner.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Proctolog
+  # Whom the desk serves: one person, on this Mac, named as Git names them
+  # (`user.name`), else by their login. Grouse's notes on the desk are theirs,
+  # and so are those written in the overlay of a scenario they opened.
+  class Owner < Data.define(:name)
+    def self.current = @current ||= new(name: git_name.presence || ENV.fetch("USER", "the owner"))
+
+    def self.git_name = Open3.capture2("git", "config", "--get", "user.name").first.strip
+
+    def first_name = name.split.first
+  end
+end

data/app/models/proctolog/pick.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The repository's open pull requests as a reviewer picks a burst from them:
+  # GitHub's stacks whole, from the bottom up, then the rest, the reviewer's
+  # own first, then those written for PRoctolog, then the newest.
+  class Pick
+    Stack = Data.define(:number, :pull_requests) do
+      def top = pull_requests.last
+    end
+
+    attr_reader :viewer, :unopened
+
+    # `unopened` are the pull requests nobody has opened yet, in the order of
+    # their numbers.
+    def initialize(pull_requests, viewer:, unopened: [])
+      @pull_requests, @viewer, @unopened = pull_requests, viewer, unopened
+    end
+
+    def stacks
+      @pull_requests.select(&:stack).group_by(&:stack).sort.map do |number, layers|
+        Stack.new(number:, pull_requests: layers.sort_by(&:position))
+      end
+    end
+
+    def loose = @pull_requests.reject(&:stack).sort_by { [yours?(it) ? 0 : 1, written?(it) ? 0 : 1, -it.number] }
+
+    def yours?(pull_request) = viewer.present? && pull_request.author == viewer
+
+    # Whether its description asks the reviewer anything the way PRoctolog reads it.
+    def written?(pull_request) = pull_request.description.decisions.any?
+
+    def empty? = @pull_requests.empty? && unopened.empty?
+
+    # Whether a pull request nobody has opened yet sits on another pull
+    # request's branch, so that it tops a chain.
+    def chained?(pull_request) = [*@pull_requests, *unopened].any? { it.head == pull_request.base }
+
+    # A name for a burst of these pull requests, from the branch of the first:
+    # what `burst new` would be told, and free among the bursts there are.
+    def self.slug_for(pull_requests)
+      base = pull_requests.first&.head.to_s.parameterize.first(40).delete_suffix("-").presence || "burst"
+      taken = Burst.files.map { it.basename(".yml").to_s }
+      (1..).lazy.map { (it == 1) ? base : "#{base}-#{it}" }.find { !taken.include?(it) }
+    end
+  end
+end