proctolog 0.1.0

data/app/models/proctolog/app.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "erb"
+require "open3"
+require "shellwords"
+
+module Proctolog
+  # How the checkout's own app is run for its scenarios, in the app's own
+  # words: the commands and paths of .proctolog/app.yml (docs/manual/app.md).
+  # Every part is optional; a scenario that needs a missing one says which.
+  class App
+    # A Server::Error, so the scenario pages say it where the press was made.
+    Missing = Class.new(Server::Error)
+
+    FILE = "app.yml"
+
+    # A commit, by its short hash and its first line.
+    Arrival = Data.define(:commit, :subject)
+
+    def self.current = new(Project.current.definitions.join(FILE))
+
+    attr_reader :file
+
+    def initialize(file)
+      @file = Pathname(file)
+      @settings = file.exist? ? YAML.safe_load_file(file) || {} : {}
+    end
+
+    def described? = file.exist?
+
+    # The commit that brought this file into its repository: a checkout without
+    # it is older than the commands the file names. Nil outside Git.
+    def arrival
+      return @arrival if defined?(@arrival)
+
+      output, found = Open3.capture2e("git", "-C", file.dirname.to_s, "log", "--diff-filter=A", "-1", "--format=%h%x00%s", "--", file.basename.to_s)
+      @arrival = (Arrival.new(*output.strip.split("\0", 2)) if found.success? && output.include?("\0"))
+    end
+
+    def parts = @settings.keys
+
+    def serve(slug:, port:) = command(:serve, slug:, port:)
+
+    # What makes the app ready to serve, such as its database; nil when it needs nothing.
+    def prepare(slug:, port:) = (command(:prepare, slug:, port:) if @settings.key?("prepare"))
+
+    # The words of the command that makes a state, its arguments one key=value
+    # word each where %{args} stands.
+    def state(name, arguments, slug:, port:) = command(:state, slug:, port:, name:, args: arguments.map { |key, value| "#{key}=#{value}" })
+
+    # Grouse's overlay, labelled with a scenario: `overlay` opens a review
+    # session from a brief of one JSON word, and `notes` prints what was
+    # written in one. A project that names no `overlay` opens none.
+    def overlay? = @settings.key?("overlay")
+
+    def overlay(brief, slug:, port:) = command(:overlay, slug:, port:, brief: brief.to_json)
+
+    def notes(session, slug:, port:) = command(:notes, slug:, port:, session:)
+
+    def sign_in(email, to:) = path(:sign_in, email:, to:)
+
+    def sign_out(to:) = path(:sign_out, to:)
+
+    # The ports that answer once the app is up, counted from the one it is given.
+    def listens(port) = @settings.fetch("listens", [0]).map { port + it }
+
+    # Cookies a clean browser starts with, as name=value.
+    def cookies = Array(@settings["cookies"])
+
+    def size(name) = @settings.dig("sizes", name)&.symbolize_keys
+
+    def sizes = @settings.fetch("sizes", {}).keys
+
+    # The programs its commands start, as the file names them: past an `env`
+    # and the variables it sets, which only say how the program runs.
+    def programs = %w[prepare serve state overlay notes].filter_map { @settings[it]&.then { program_of(it) } }.uniq
+
+    private
+
+    def program_of(template) = Shellwords.split(template).drop_while { it == "env" || it.match?(/\A\w+=/) }.first
+
+    def command(part, args: [], **values)
+      Shellwords.split(template(part)).flat_map { (it == "%{args}") ? args : format(it, **values) }
+    end
+
+    def path(part, **values) = format(template(part), **values.transform_values { ERB::Util.url_encode(it) })
+
+    def template(part)
+      @settings[part.to_s] or raise Missing, "#{Project.current.from_root(file)} names no #{part}, which this scenario needs. See docs/manual/app.md."
+    end
+  end
+end

data/app/models/proctolog/browser.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Where a scenario opens. `mine` is the browser that pressed the button, with
+  # its 1Password and its passkeys. `clean` is a Chrome of its own, started
+  # with a profile kept under cache/, so that it can be given a size and say it
+  # is a phone. `fresh` is that with a new, empty profile each time, for a step
+  # that wants the cookie banner up.
+  class Browser < Data.define(:name)
+    NAMES = %w[mine clean fresh].freeze
+    # Chrome will not make a window with tabs narrower than this. An app
+    # window will, which is also what an iPhone's web layer looks like.
+    NARROWEST_TABBED = 500
+
+    def self.named(name)
+      NAMES.include?(name) or raise ArgumentError, "a browser is #{NAMES.to_sentence(last_word_connector: " or ")}, not #{name.inspect}"
+      new(name:)
+    end
+
+    NAMES.each { |browser| define_method(:"#{browser}?") { name == browser } }
+
+    # Drops the profiles fresh browsers were given over a day ago, whose
+    # scenarios are long over (PruneFreshProfilesJob).
+    def self.prune_fresh_profiles = Project.current.browsers.glob("fresh-*").select { it.mtime < 1.day.ago }.each(&:rmtree)
+
+    def command(address, size:)
+      ["open", "-na", "Google Chrome", "--args", "--user-data-dir=#{profile(size)}", "--window-size=#{size.width},#{size.height}",
+        *("--user-agent=#{size.user_agent}" if size.user_agent), "--no-first-run", "--no-default-browser-check",
+        (size.width < NARROWEST_TABBED) ? "--app=#{address}" : address]
+    end
+
+    def launch(address, size:)
+      system(*command(address, size:)) or raise Failure, "Chrome could not be opened (is Google Chrome installed?)."
+    end
+
+    private
+
+    def profile(size) = profiles.join(fresh? ? "fresh-#{SecureRandom.hex(4)}" : "clean-#{size}")
+
+    def profiles = Project.current.browsers
+  end
+end

data/app/models/proctolog/burst.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A body of agent work the desk opens as one: the pull requests a file under
+  # bursts/ names, taken together because they came out of one effort.
+  class Burst
+    Missing = Class.new(StandardError)
+
+    # Where burst files are, the first to hold a slug winning: the reviewer's
+    # own, then the repository's; reviews/ is where they were kept before
+    # bursts had their name.
+    FOLDERS = -> { Project.current.burst_folders }
+
+    # `file` is where it was read from.
+    attr_reader :slug, :name, :repository, :stacks, :tops, :file
+
+    delegate :read_at, to: :github
+
+    def self.all = files.map { from(it) }
+
+    # One file for each slug, in the order of their slugs.
+    def self.files = folders.flat_map { it.glob("*.yml") }.uniq(&:basename).sort_by(&:basename)
+
+    def self.folders = Array(FOLDERS.respond_to?(:call) ? FOLDERS.call : FOLDERS)
+
+    # A burst file as the desk reads it. A mistake in it is named with the
+    # file and the reason, as Project#settings names one in its own files.
+    def self.from(file)
+      settings = YAML.safe_load_file(file, symbolize_names: true)
+      settings.is_a?(Hash) or raise Failure, "#{file} is not a burst file: it holds no settings."
+      numbered(settings, file)
+      new(file.basename(".yml").to_s, file:, **settings)
+    rescue Psych::Exception => e
+      raise Failure, "#{file} is not valid YAML (#{e.message.lines.first&.strip})."
+    rescue ArgumentError => e
+      raise Failure, "#{file} is not a burst file as the desk reads one (#{e.message})."
+    end
+
+    # Stacks and pull requests are named by their numbers, in lists; a pull
+    # request nobody has opened yet by its branch.
+    def self.numbered(settings, file)
+      %i[stacks tops pull_requests].each do |list|
+        named = settings.fetch(list, [])
+        named.is_a?(Array) or raise Failure, "#{file} names #{named.inspect} under `#{list}`, which is a list of numbers."
+        named.grep_v((list == :stacks) ? Integer : BRANCH_OR_NUMBER).first&.then { raise Failure, "#{file} names #{it.inspect} under `#{list}`: #{(list == :stacks) ? "a stack" : "a pull request"} is named by its number#{", or by its branch while it is not opened" unless list == :stacks}." }
+      end
+    end
+
+    # A number, or a branch as git would take one.
+    BRANCH_OR_NUMBER = ->(named) { named.is_a?(Integer) || (named.is_a?(String) && named.match?(%r{\A(?!-)[^\s~^:?*\[\\]+\z})) }
+    private_class_method :numbered
+
+    # Every burst, the one written last first: a burst an agent has just
+    # made is the work waiting, and one reviewed a while ago sinks.
+    def self.newest_first = all.sort_by { -it.file.mtime.to_f }
+
+    # The burst the desk opens on, and the commands take when none is named:
+    # the newest one not put away.
+    def self.latest = newest_first.find { !it.put_away? }
+
+    def self.find(slug) = all.find { it.slug == slug } || raise(Missing, "no burst is named #{slug}")
+
+    SLUG = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
+
+    # Writes a burst of the reviewer's own, beside their marks, and returns its
+    # file. It is named as addresses and the route name it, `login-fixes`.
+    def self.start(slug, name: nil, stacks: [], tops: [], pull_requests: [])
+      slug.match?(SLUG) or raise Failure, "#{slug.inspect} is no burst name: lowercase words joined by hyphens, as login-fixes."
+      [stacks, tops, pull_requests].any?(&:present?) or raise Failure, "A burst needs pull requests: name some with --pr, --top or --stack."
+      taken = folders.map { it.join("#{slug}.yml") }.find(&:exist?) and raise Failure, "#{Project.current.from_root(taken)} is a burst named #{slug} already."
+      repository = Project.current.github_repository or raise Failure, "#{Project.current.root} has no GitHub repository as its origin."
+
+      settings = {name: name || slug.tr("-", " ").capitalize, repository:, stacks:, tops:, pull_requests:}.compact_blank
+      Project.current.own_bursts.tap(&:mkpath).join("#{slug}.yml").tap do |file|
+        file.write(["# Yours alone, outside the repository. docs/manual/bursts.md says what else it can hold.",
+          *settings.map { |key, value| "#{key}: #{value.is_a?(Array) ? "[#{value.map(&:to_json).join(", ")}]" : value.to_json}" }].join("\n") + "\n")
+      end
+    end
+
+    # The burst of that name, or else one written as `start` writes it: what a
+    # press on a lone pull request or a stack opens, the second time as the first.
+    def self.find_or_start(slug, **picks) = all.find { it.slug == slug } || from(start(slug, **picks))
+
+    # Whether it is the reviewer's own, rather than one the repository shares.
+    def own? = file.to_s.start_with?("#{Project.current.own_bursts}/")
+
+    # `stacks` are GitHub's native stacks, by their numbers; `tops` the tops of
+    # chains the desk follows down by base branches; `pull_requests` those
+    # that stand alone. A top with nothing under it stands alone as well.
+    def initialize(slug, name:, repository:, file: nil, stacks: [], tops: [], pull_requests: [], hands_off: [], before_it_goes: {}, handover: {}, sitting: nil, waiting: [])
+      @slug, @name, @repository, @file = slug, name, repository, file
+      @stacks, @tops, @pull_requests = stacks, tops, pull_requests
+      @hands_off, @before_it_goes = hands_off, before_it_goes
+      @terms = Handover::Terms.from(handover)
+      @sitting = sitting
+      @waiting = waiting
+    end
+
+    def to_param = slug
+
+    def marks(number) = Marks.of(self, number)
+
+    def choices = Choices.of(self)
+
+    def rules = Rules.new(choices, handovers: Handover.kept(self))
+
+    # How far each pull request's decisions are, by its number.
+    def progress(route) = choices.then { |kept| route.to_h { [it.number, kept.progress(it.number, it.description.decisions)] } }
+
+    # Ticking these decisions of one pull request, to show and then carry out.
+    # A description the burst file lists under `hands_off` is another
+    # session's, and the desk does not edit it.
+    def acceptance(number, decisions)
+      raise Acceptance::Refused, refusal(number) if refusal(number)
+      Acceptance.new(home: home_of(number), number:, decisions:)
+    end
+
+    # Why the desk will not edit this description, when it will not.
+    def refusal(number) = ("The description of ##{number} is not the desk's to edit" if @hands_off.include?(number))
+
+    # Every decision box of the route, or of the part in focus, and what waits
+    # for the owner among them. `pages` maps a pull request's address on
+    # GitHub to the desk's page for it.
+    def decisions(pages: {}, focus: route) = Decisions.new(route: focus, marks: method(:marks), renderings: method(:rendering), named: @waiting, pages:)
+
+    # Where every stop of the route stands, in its order: each layer knows the
+    # standing of the one it sits on.
+    def standings(route)
+      progress, scenarios = progress(route), scenarios_on(route)
+      route.each_with_object({}) do |stop, standings|
+        standings[stop] = Standing.new(stop:, marks: marks(stop.number), progress: progress.fetch(stop.number), under: route.under(stop)&.then { standings[it] },
+          above: route.above(stop), scenarios: scenarios.select { it.pr == stop.number }.map(&:name), named: @before_it_goes.fetch(stop.number, []))
+      end
+    end
+
+    # What moved in a pull request since the owner's "good to go", to show
+    # when its standing says something did.
+    def since(stop) = Since.new(stop:, mark: marks(stop.number).good_to_go, repository:, history: home_of(stop.number), root: Project.current.root)
+
+    # The prompt for a fresh session, out of everything open on this route, or
+    # in the part in focus.
+    def handover(route, focus: Focus.new(route, nil), worklist: nil) = Handover.new(burst: self, route:, focus:, worklist:, terms: @terms, renderings: method(:rendering), pictures: method(:picture_file))
+
+    def reports = Reports.new(self)
+
+    # A description's picture as a file on this Mac, once the desk has shown it.
+    def picture_file(asset) = (Project.current.pictures.glob("#{asset}.*").first if Picture.asset?(asset.to_s))
+
+    # The server its scenarios open the app on: the burst file's `sitting`, or
+    # else the checkout under review as it is, on a database of the burst's own.
+    def server = @server ||= Server.from(@sitting || {checkout: Project.current.root, port: Server::PORT, slug:})
+
+    # A checkout the owner can make for one pull request's scenarios when the
+    # sitting cannot run them: where the burst keeps its worktrees, or else in
+    # the cache. Nil when the app's app.yml came with no commit to pick.
+    def fresh_sitting(stop)
+      arrival = server.app.arrival or return
+      path = @terms.worktree_of("try/#{stop.number}")&.then { Pathname(it).expand_path } || Project.current.cache.join("sittings", stop.number.to_s)
+      FreshSitting.new(repository: Project.current.root, path:, head: stop.head_oid.first(12), arrival: arrival.commit, port: server.port, slug: server.slug)
+    end
+
+    def scenarios = @scenarios ||= scenarios_on(route)
+
+    # The scenarios its file writes, and for each pull request of `route` the
+    # file names none of, those its description offers on its own.
+    def scenarios_on(route)
+      written = Scenario.of(self)
+      written + route.reject { |stop| written.any? { it.pr == stop.number } }.flat_map { Scenario.described(it) }
+    end
+
+    def scenario(id) = scenarios.find { it.to_param == id } || raise(Missing, "no scenario is called #{id}")
+
+    # A stack is placed from the membership kept beside the marks when GitHub
+    # cannot say where its pull requests stand. Built once for this burst's
+    # reading of a page, which asks for it from the page, its pane and its focus.
+    def route(fresh: false)
+      return @route if @route && !fresh
+
+      open = github.open_pull_requests(fresh:)
+      unopened = Unopened.waiting(open:).map(&:pull_request)
+      among = open + unopened
+      @route = Route.new(stacks: @stacks, tops: resolved(@tops, among), loose: resolved(@pull_requests, among), among:, kept: membership.stacks).tap do |route|
+        Picture.fetch_ahead(of: [read_at, route.map(&:number), *unopened.map { [it.number, it.head_oid, it.described_at] }]) { pictures_of(route) }
+        Mentions.here&.read_ahead
+      end
+    end
+
+    # A description as GitHub renders it, for an open pull request, or as
+    # this Mac keeps it, for one nobody has opened yet.
+    def rendering(number) = home_of(number).rendering(number)
+
+    # The pull requests it holds now.
+    def numbers = route.map(&:number)
+
+    # The pull requests it held that are no longer open, merged or closed,
+    # by their numbers: those its file names and those the owner saw in it.
+    def gone = @gone ||= github.gone(held - numbers)
+
+    # Those of them that went in, the latest first.
+    def merged = gone.values.select(&:merged?).sort_by { -it.merged_at.to_f }
+
+    # Nothing of it is open or waiting unopened, and some of it was merged:
+    # the work went in, and the desk puts the burst away. A burst GitHub
+    # cannot be asked about now is not taken for finished.
+    def finished?
+      route.none? && merged.any?
+    rescue Github::Unreachable
+      false
+    end
+
+    # Put away: finished, or put away by the owner while some of it is still
+    # open. The desk no longer opens on it, and lists it only when asked.
+    def put_away? = put_away_by_hand? || finished?
+
+    # The owner's word that they are done with it, kept beside its marks, not
+    # in its file: a burst the repository shares is put away for them alone.
+    def put_away_by_hand? = put_away_mark.exist?
+
+    def put_away! = put_away_mark.tap { it.dirname.mkpath }.write("#{Time.current.iso8601}\n")
+
+    def take_out! = FileUtils.rm_f(put_away_mark)
+
+    def membership = Membership.of(self)
+
+    # What joined it, what left, and where its file and GitHub disagree. The
+    # first time the desk reads a burst, the membership it counts from is kept.
+    def notices
+      @notices ||= route.then do |route|
+        membership.start(route)
+        BurstNotices.new(burst: self, route:, membership:, open: github.open_pull_requests, choices: choices.document, others:, merged: merged.map(&:number))
+      end
+    end
+
+    # The other bursts of the repository, which may hold the same pull requests.
+    def others = Burst.all.reject { it.slug == slug }.select { it.repository == repository }
+
+    # Which of its pull requests GitHub has moved on since the desk read them,
+    # and which it closed: their numbers. Others of the repository are not its concern.
+    def moved
+      mine = route.map(&:number)
+      github.moved.slice(:changed, :closed).transform_values { it & mine }
+    end
+
+    # Pieces of a description's markdown as GitHub draws them, for a page that has only the markdown.
+    def draw(pieces) = PiecesRendering.new(github).call(pieces)
+
+    private
+
+    # The pictures its descriptions show, each by its id and its kind, as GitHub's HTML addresses them.
+    def pictures_of(route) = route.flat_map { Rendering.pictures(rendering(it.number)) }
+
+    def github = @github ||= Github.new(@repository)
+
+    def put_away_mark = Marks.directory_of(self).join("put_away")
+
+    # Every pull request it was known to hold, by GitHub's number.
+    def held = [*@tops, *@pull_requests, *membership.pull_requests, *membership.handed_over].grep(Integer).uniq
+
+    # What holds a pull request's description, and answers for it: GitHub,
+    # or this Mac while nobody has opened it.
+    def home_of(number) = PullRequest.unopened?(number) ? Unopened : github
+
+    # A branch the file names stands for the pull request on it: the one
+    # open on GitHub, or else the one waiting unopened. A branch with
+    # neither stays as it is named, and is gone.
+    def resolved(named, among) = named.map { |name| (name.is_a?(String) && among.find { it.head == name }&.number) || name }
+  end
+end

data/app/models/proctolog/burst_notices.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # What the burst page says above its route. How the burst moved: the pull
+  # requests that joined or left it since the owner last looked, each until
+  # the owner dismisses it, and those that left with choices or drafts not
+  # yet handed over. And where the burst's file and GitHub disagree, each with
+  # its fix, for as long as it is true.
+  class BurstNotices
+    # A pull request that joined or left, by its number and its title, when
+    # the desk still knows it; or one opened on GitHub, with the number it
+    # waited unopened as.
+    Moved = Data.define(:number, :title, :was) do
+      def initialize(was: nil, **) = super
+    end
+
+    # A pull request that left with the owner's choices or drafts, drawn from
+    # what they kept of it: nothing of it is read again from GitHub.
+    Departed = Data.define(:number, :title, :entries)
+
+    # One of the owner's choices or drafts on a decision of it.
+    Entry = Data.define(:kind, :lead, :text, :draft)
+
+    # Something the file says that GitHub does not, in a sentence, with how
+    # to mend it. `cause` groups it with its kind: :off_the_burst,
+    # :empty_stack, :filed_twice or :held_elsewhere.
+    Disagreement = Data.define(:cause, :said, :fix)
+
+    # `open` is every open pull request of the repository, `others` the
+    # other bursts of the same repository, `choices` the owner's document,
+    # `merged` the numbers of those that left it by going in.
+    def initialize(burst:, route:, membership:, open:, choices:, others:, merged: [])
+      @burst, @route, @membership, @open, @choices, @others, @merged = burst, route, membership, open, choices, others, merged
+    end
+
+    def joined = @joined ||= @membership.joined(@route).map { moved(it) }
+
+    # One that left by going in is no notice: the route lists it as merged.
+    def left = @left ||= (@membership.left(@route) - @merged).map { moved(it) }
+
+    # Opened on GitHub since it waited unopened, and its review came with it.
+    def opened = @opened ||= @membership.opened.filter_map { |number, was| Moved.new(number:, title: title_of(number), was:) if @route.at(number) }
+
+    def departed
+      @departed ||= @membership.departed(@route).filter_map do |number|
+        entries = entries_of(number)
+        Departed.new(number:, title: title_of(number), entries:) if entries.any?
+      end
+    end
+
+    # A burst whose work all went in has nothing left to mend.
+    def disagreements = @disagreements ||= finished? ? [] : [*off_the_burst, *empty_stacks, *filed_twice, *held_elsewhere]
+
+    def count = [joined, left, opened, departed, disagreements].sum(&:size)
+
+    def any? = count.positive?
+
+    private
+
+    def moved(number) = Moved.new(number:, title: title_of(number))
+
+    def finished? = @route.none? && @merged.any?
+
+    # From GitHub while it is open, else from a choice made on it.
+    def title_of(number) = @open.find { it.number == number }&.title || on(number).first&.dig("decision", "title")
+
+    def on(number) = %w[choices pending].flat_map { Array(@choices&.dig(it)) }.select { it.dig("decision", "pr") == number }
+
+    def entries_of(number)
+      on(number).map do |entry|
+        Entry.new(kind: entry["kind"], lead: entry.dig("decision", "lead"), text: entry["text"].to_s, draft: Array(@choices&.dig("pending")).include?(entry))
+      end
+    end
+
+    def file = @burst.file ? shown(@burst.file) : "the burst file"
+
+    # Open pull requests that sit, one on another, on a member of the burst,
+    # and are neither in it nor in another burst of the repository. Each run
+    # is named at the member it sits on.
+    def off_the_burst
+      held = numbers(@route) | @others.flat_map(&:numbers)
+      @route.filter_map do |member|
+        run = sitting_on([member.pull_request], held)
+        off(member, run) if run.any?
+      end
+    end
+
+    # Every open pull request outside `held` that sits on one of `below`, or
+    # on one that does, and so on up.
+    def sitting_on(below, held)
+      above = @open.select { |pull| below.any? { pull.base == it.head } }.reject { held.include?(it.number) }
+      above.empty? ? [] : above + sitting_on(above, held + numbers(above))
+    end
+
+    def off(member, run)
+      tops = run.reject { |pull| run.any? { it.base == pull.head } }
+      fix = "List #{named(tops)} under `tops` in #{file}"
+      # GitHub appends to a stack only at its top.
+      if member.part.stack? && member.layer == member.of
+        fix += ", or link #{them(run)} to stack ##{member.part.id}: `gh stack link #{member.part.id} #{numbers(run).join(" ")}`"
+      end
+      Disagreement.new(cause: :off_the_burst, said: "#{named(run)} #{be(run)} on ##{member.number}'s branch, not in this burst.", fix: "#{fix}.")
+    end
+
+    def empty_stacks
+      return [] unless @route.stacks_known?
+
+      (@burst.stacks - @open.filter_map(&:stack)).map do |stack|
+        Disagreement.new(cause: :empty_stack, said: "Stack ##{stack} has no open pull requests.", fix: "Take it out of `stacks` in #{file}.")
+      end
+    end
+
+    # A slug both under bursts/ and under reviews/, where burst files were
+    # kept before bursts had their name: the desk opens the first.
+    def filed_twice
+      opened, *also = Burst.folders.map { it.join("#{@burst.slug}.yml") }.select(&:exist?)
+      also.map do |other|
+        Disagreement.new(cause: :filed_twice, said: "#{shown(other)} #{(other.realpath == opened.realpath) ? "points to" : "names the same burst as"} #{shown(opened)}, which the desk opens.",
+          fix: "Delete #{shown(other)} once no desk from before bursts had their name is left to read it.")
+      end
+    end
+
+    def held_elsewhere
+      @others.filter_map do |other|
+        shared = @route.select { other.numbers.include?(it.number) }
+        next if shared.empty?
+
+        Disagreement.new(cause: :held_elsewhere, said: "#{named(shared)} #{be(shared)} also in #{other.name}, in #{shown(other.file)}.",
+          fix: "Each burst keeps its own choices on #{them(shared)}: take #{them(shared)} out of one of the files if only one burst should hold #{them(shared)}.")
+      end
+    end
+
+    def shown(path) = Project.current.from_root(path)
+
+    def numbers(pull_requests) = pull_requests.map(&:number)
+
+    def named(pull_requests) = pull_requests.map { "##{it.number}" }.to_sentence
+
+    def be(pull_requests) = pull_requests.one? ? "is" : "are"
+
+    def them(pull_requests) = pull_requests.one? ? "it" : "them"
+  end
+end

data/app/models/proctolog/chapters.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Proctolog
+  # The steps of a recording and when each was on screen, as a WebVTT chapters
+  # file. The capture script writes it beside the video and the player reads
+  # it back, so the list beside the video is what the video says. Plain Ruby,
+  # with no Rails in it, because capture/film.rb loads it without the desk.
+  class Chapters
+    include Enumerable
+
+    Chapter = Data.define(:name, :from, :to)
+
+    CUE = /^(?<from>[\d:.]+) --> (?<to>[\d:.]+)[^\n]*\n(?<name>[^\n]+)/
+
+    def self.parse(text) = new(text.scan(CUE).map { |from, to, name| Chapter.new(name: CGI.unescapeHTML(name), from: seconds(from), to: seconds(to)) })
+
+    def self.read(file) = file.exist? ? parse(file.read) : new([])
+
+    def self.seconds(stamp) = stamp.split(":").map(&:to_f).reduce { |minutes, more| (minutes * 60) + more }
+
+    def initialize(chapters) = @chapters = chapters
+
+    def each(&) = @chapters.each(&)
+
+    # The step a time falls in: the last that began at or before it, so a
+    # pause between two steps belongs to the one before.
+    def at(time) = @chapters.rfind { it.from <= time }
+
+    def to_vtt = "WEBVTT\n\n#{map { cue(it) }.join("\n\n")}\n"
+
+    private
+
+    def cue(chapter) = "#{stamp(chapter.from)} --> #{stamp(chapter.to)}\n#{CGI.escapeHTML(chapter.name.split.join(" "))}"
+
+    def stamp(time)
+      ms = (time * 1000).round
+      format("%02d:%02d:%02d.%03d", ms / 3_600_000, ms / 60_000 % 60, ms / 1000 % 60, ms % 1000)
+    end
+  end
+end