proctolog 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 784717d224b472eba9ce15227d5ffb578dabce10741c802d6cd62e642f8aee96
+  data.tar.gz: 879591d6f7db0c4448563096e0e82ed566f68364c2c55e5b0ac03a739855a207
+SHA512:
+  metadata.gz: 0e7c19af833d9fe3099f47e221f7663cd9c43066dcdf08b7a96b48e04374af2ac4f4017158dc308f244a07abc827d78ba0563ae85e9d2f9a3c9bdcfb5bc175cc
+  data.tar.gz: 5da7be3fd3fcd54977e57f350b6f496ddda3d70b5c10982976116d8e1d814fc052a503526039195065f73ce1587415fb938fa251b93e8156313c4bb0b335f1dc

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+What changed in each version of the `proctolog` gem, newest first. Versions
+are semantic ([docs/manual/updates.md](docs/manual/updates.md)); a release
+that asks something of you says what under **You do**.
+
+## 0.1.0
+
+The first one published as a gem.
+
+- `rvx proctolog install`, or
+  `gem install proctolog` and `proctolog install`, in place of cloning the
+  repository. Under rv it runs on a Ruby 4 of its own, whatever Ruby the shell
+  has, and the apps it starts never inherit it.
+- `proctolog version`, and `proctolog update`, which takes a newer version
+  however yours was installed: rv, RubyGems, or a checkout it pulls forward.
+- The desk asks RubyGems once a day for the latest version, and the next page
+  says when it's newer than yours.
+
+**You do**, coming from a checkout: nothing, if you keep it: `proctolog
+update` pulls it from now on. To move to the gem, remove
+`~/.local/bin/proctolog`, the checkout's launcher, then install it one of the
+ways above.

data/README.md

@@ -0,0 +1,178 @@
+# PRoctolog
+
+A review desk for stacks of pull requests an agent wrote. It runs on your Mac,
+reads the PRs from GitHub, and walks you through every decision their
+descriptions ask of you. What you answered becomes a handover: a short brief and
+a file for each PR, for the agent to work through.
+
+![Deciding the first of a PR's decisions, with the pictures it links](docs/manual/desk.png)
+
+It's rough. It has also been through a stack of 21 PRs and 439 decisions, so
+it works.
+
+## The short version
+
+Install it with [rv](https://rv.dev), then run it from a checkout of the repo
+whose PRs you review:
+
+```sh
+rvx proctolog install
+cd path/to/your-repo
+proctolog doctor   # fix what it marks !!
+proctolog serve    # then open http://localhost:4040
+```
+
+Pick a PR, a stack, or a few ticked ones, and press `?` once you're in. When
+your agent opens PRs, tell it to "write these PRs for PRoctolog", so they come
+with decisions to review. Everything below is the long version.
+
+## Install
+
+You need `gh` signed in with access to the repository you review, and either
+[rv](https://rv.dev) or Ruby 4.0. Chrome, [Diffle](https://github.com/moritzwilksch/diffle),
+ImageMagick and ffmpeg each switch something on, and nothing here installs
+them; `doctor` says what each adds, and Homebrew has them all:
+
+```sh
+brew install --cask google-chrome
+brew install diffle imagemagick ffmpeg
+```
+
+With rv, whatever Ruby your shell or your repo runs:
+
+```sh
+rvx proctolog install
+proctolog doctor
+```
+
+rv gives PRoctolog a Ruby 4 and gems of its own, and `install` puts a
+`proctolog` in `~/.local/bin` that runs it through `rvx`. The apps you review
+keep their own Ruby: what the desk starts for them never sees PRoctolog's.
+rv installs from gem.coop, which mirrors RubyGems.
+
+With Ruby 4.0 already in your shell:
+
+```sh
+gem install proctolog
+proctolog install
+proctolog doctor
+```
+
+Either way `install` also links the zsh completion into `~/.zsh/completions`
+and the agent skills (below) into `~/.claude/skills` and `~/.agents/skills`. `doctor`
+says what's missing, a line each, with the fix: `!!` for what the desk can't do
+without, `--` for what only turns a feature off.
+
+When a newer PRoctolog is out, the desk says so, and `proctolog update` takes
+it ([versions and updates](docs/manual/updates.md)).
+
+Working on PRoctolog itself? Run it from a checkout instead: clone it, then
+`bundle install && ruby bin/install`, which also puts a `proctolog` that runs
+the checkout in `~/.local/bin`. Keep the checkout where it is, since
+everything links back to it. The desk tells a checkout of a newer release
+too, and `proctolog update` pulls it forward.
+
+## Your first review
+
+```sh
+cd path/to/your-repo
+proctolog serve
+```
+
+Open <http://localhost:4040>. It lists the repo's open PRs: GitHub's stacks
+whole, then the rest, yours first. Press "Review alone" on one, "Review the
+stack" on a stack, or tick a few and review them together. That's all the setup
+there is.
+
+On a PR, press `?` for the keys, `f` for the first decision waiting on you, and
+`e` for the handover. Give your agent its brief, or open the new session the
+page offers, which already has. Or skip the page: tell your agent to "check my
+PRoctolog comments", halfway through if you like, and it runs
+`proctolog handover` and takes what you decided so far. Either way it answers
+with a JSON file PRoctolog reads back, so you can confirm each change or push
+back.
+
+What you review together is a burst. The page writes one for each pick, kept
+under `~/.local/share/proctolog/` with your marks, never in the repo; "open
+PRs" at the top of any page goes back to the list. From the terminal it's
+`proctolog burst new login-fixes --top 1120 --pr 1131`, where `--top` brings
+the chain of PRs under it, `--pr` one alone and `--stack` a stack of GitHub's.
+
+Your review is saved as you go, on your Mac under `~/.local/share/proctolog/`.
+
+## PRs PRoctolog reads well
+
+PRoctolog finds decisions under a `## Decisions for the owner` heading, one
+checkbox line each. The `proctolog-pr-writing` skill teaches your agent the
+format, and `proctolog install` already put it where the agent looks. Tell it to
+"write these PRs for PRoctolog", or "rewrite this PR's description for
+PRoctolog" for one that's open. Check a description before publishing it:
+
+```sh
+proctolog check --file body.md
+proctolog check 1131
+```
+
+Not ready to open PRs? Tell your agent to write them for PRoctolog without
+opening them. The desk reviews each from a folder on your Mac as `#01`, `#02`,
+and when the branches are opened, the review moves to their real numbers
+([how](docs/manual/unopened.md)).
+
+## Scenarios
+
+A scenario button starts the app, signs the right member in and opens Chrome
+on the right page. The desk doesn't know your app; it runs the few commands
+the repo's `.proctolog/app.yml` names ([how](docs/manual/app.md)), on your
+own checkout and a scratch database the first Start makes. An app with
+Grouse in it can open Grouse's overlay there too, labelled with the scenario,
+and what you say or type in it comes back as notes on that scenario
+([how](docs/manual/app.md#grouses-overlay)). Each bold heading
+with numbered steps in a PR's "How to test locally" is a scenario already. A
+`scenarios/<burst>.yml` beside the burst only adds a starting state and page
+([how](docs/manual/bursts.md)). A repo without an `app.yml` still lists each
+scenario's steps, and you mark what you saw.
+
+Films and before/after pairs need a camera the desk doesn't have yet; it's
+next, on the same `app.yml`.
+
+## Notes on the desk itself
+
+Grouse is private, so the desk runs without it, and the gem never carries it.
+In a checkout of PRoctolog, once you can read
+[its repo](https://github.com/LemuelCushing/grouse-rails), turn it on:
+
+```sh
+bundle config set --local with grouse && bundle install
+```
+
+Then every page of the desk carries Grouse's overlay, at the bottom right: say or type what's wrong with the page you're
+on, and the note keeps the page, the templates that drew it, what you pointed
+at and, if you ask, a screenshot. Read them at <http://localhost:4040/grouse>.
+An agent working on the desk reads them through Grouse's export API;
+[AGENTS.md](AGENTS.md) tells it how. They're kept under
+`~/.local/share/proctolog/grouse_notes`, one store for every repo you review.
+
+A voice note is written out by ElevenLabs, and every note written up as an
+issue by Anthropic, with keys the desk reads from 1Password when it serves:
+`config/keys.yml` holds the references, never the keys, and `op` (1Password's
+CLI, signed in) reads them. Point them at your own items there if yours live
+elsewhere.
+
+Without a key a voice note arrives "audio only", with a recording that plays,
+and a note's page says "No structurer set up". `bin/rails grouse:doctor`, in the
+desk's checkout, says what Grouse is missing.
+
+## More
+
+- [Bursts, the route and where things live](docs/manual/bursts.md)
+- [How the desk runs your app](docs/manual/app.md)
+- [Reading a PR by keyboard](docs/manual/reading.md)
+- [Deciding](docs/manual/deciding.md)
+- [Handover and the next pass](docs/manual/handover.md)
+- [Writing a PR the desk reads](docs/manual/pr-format.md)
+- [Before anything is opened](docs/manual/unopened.md)
+- [Films](docs/manual/films.md)
+- [Versions and updates](docs/manual/updates.md)
+- [CONCEPTS.md](CONCEPTS.md) for the words, [ROADMAP.md](ROADMAP.md) for what's next
+
+Working on the desk itself? Start at [AGENTS.md](AGENTS.md).

data/app/controllers/proctolog/acceptances_controller.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Ticking boxes of one description, on GitHub or in the file of one nobody
+  # has opened yet. The first page shows which boxes and the command;
+  # nothing is ticked until the second press.
+  class AcceptancesController < ApplicationController
+    include WithDecisions
+
+    rescue_from(Acceptance::Refused, Github::Unreachable) { redirect_to decisions_path_for(number), alert: it.message }
+
+    def new
+      @boxes = decisions.to_accept(number, positions)
+      @stop = @boxes.first.stop
+      @acceptance = @burst.acceptance(number, @boxes.map(&:decision))
+    end
+
+    def create
+      boxes = decisions.to_accept(number, positions)
+      leads = @burst.acceptance(number, boxes.map(&:decision)).carry_out(seen: params.expect(:digest))
+      @burst.marks(number).accept(leads)
+      redirect_to decisions_path_for(number), notice: "Ticked #{leads.size} #{"box".pluralize(leads.size)} of ##{number} #{PullRequest.unopened?(number) ? "in its file" : "on GitHub"}."
+    end
+
+    private
+
+    def positions = params.expect(positions: []).map(&:to_i)
+  end
+end

data/app/controllers/proctolog/application_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class ApplicationController < ActionController::Base
+    rescue_from(Github::Unreachable) { render plain: "GitHub did not answer.\n\n#{it.message}", status: :service_unavailable }
+    rescue_from(ActionController::InvalidAuthenticityToken) do
+      redirect_back_or_to root_path, alert: "This page was older than the desk's last start, so nothing was saved. Do it once more."
+    end
+    rescue_from(Burst::Missing) { render plain: it.message, status: :not_found }
+    # A button's press comes back to the page it was pressed on, with the
+    # sentence. A page that cannot be shown says it in place: going back to
+    # it would only ask again.
+    rescue_from(Failure) do
+      request.get? ? render(plain: it.message, status: :internal_server_error) : redirect_back_or_to(root_path, alert: it.message.truncate(1200))
+    end
+
+    helper_method :focus
+
+    private
+
+    # The part of the burst the owner is taking on its own, from `part`. One
+    # the burst does not have leaves the whole burst in sight, and says so.
+    def focus
+      @focus ||= Focus.on(@burst.route, params[:part]).tap do |focus|
+        flash.now[:alert] = "This burst has no part #{params[:part]}, so the whole burst is shown." if params[:part].present? && focus.whole?
+      end
+    end
+
+    # Every address a page of a focused burst makes keeps the focus.
+    def default_url_options = (@burst && params[:part].present?) ? {part: focus.to_param}.compact : {}
+  end
+end

data/app/controllers/proctolog/bursts_controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class BurstsController < ApplicationController
+    # The burst written last, or the open pull requests to pick one from.
+    def index = redirect_to(Burst.latest&.then { burst_path(it) } || open_pull_requests_path)
+
+    # The route of a burst. `fresh` reads GitHub again, then comes back to an
+    # address that a reload can repeat without asking GitHub each time.
+    def show
+      @burst = Burst.find(params.expect(:id))
+      @route = @burst.route(fresh: params.key?(:fresh))
+      return redirect_to(burst_path(@burst)) if params.key?(:fresh)
+
+      @taken_in = @burst.reports.take_in
+      @standings = @burst.standings(@route)
+      @notices = @burst.notices
+      @rules = @burst.rules.select { it.within?(focus) }
+      @merged = @burst.merged
+      @merged_shown = params.key?(:merged) || @burst.finished?
+    end
+
+    # A burst of the pull requests ticked on the open pull requests, each the
+    # top of whatever chain is under it, named as the owner typed or else
+    # after the first one's branch.
+    def create
+      tops = params.fetch(:tops, []).map(&:to_i)
+      tops.any? or raise Failure, "Tick the pull requests to review together first."
+      picked = Github.new(Project.current.github_repository).open_pull_requests.select { tops.include?(it.number) }
+      slug = params[:slug].presence || Pick.slug_for(picked)
+      redirect_to burst_path(Burst.from(Burst.start(slug, name: params[:name].presence, tops:)).slug)
+    end
+  end
+end

data/app/controllers/proctolog/choices_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The choices of a burst as the pages' script keeps them: read whole, and
+  # written whole when the writing is newer than the one kept.
+  class ChoicesController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    rescue_from(Choices::Stale) { render json: {error: it.message, document: choices.document}, status: :conflict }
+    rescue_from(JSON::ParserError, KeyError) { render json: {error: "These are not the choices of #{@burst.name}."}, status: :unprocessable_content }
+
+    def show = render(json: {document: choices.document})
+
+    # A desk from before bursts had their name reads `review`, so both are
+    # written: one rolled back can still read what this one saved.
+    def update
+      incoming = JSON.parse(request.raw_post)
+      mine?(incoming) or raise KeyError
+      choices.keep(incoming.merge("burst" => @burst.slug, "review" => @burst.slug))
+      render json: {revision: choices.revision}
+    end
+
+    private
+
+    def choices = @choices ||= Choices.of(@burst)
+
+    # A page from before bursts had their name says whose they are as `review`.
+    def mine?(incoming) = incoming.is_a?(Hash) && incoming["repository"] == @burst.repository && incoming.fetch("burst") { incoming["review"] } == @burst.slug
+  end
+end

data/app/controllers/proctolog/code_reviews_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Proctolog
+  class CodeReviewsController < ApplicationController
+    include PullRequestScoped
+
+    # The code comments of a pull request; as JSON, the tally its page's
+    # outline asks for again whenever the owner comes back to that tab.
+    def show
+      @code = CodeReview.new(@burst, @stop.number)
+      respond_to do |format|
+        format.html { @snapshot, @threads = @code.snapshot, @code.threads }
+        format.json { render json: @code.tally.to_h }
+      end
+    end
+
+    def create
+      redirect_to CodeReview.new(@burst, @stop.number).start(@stop, head: params[:head], base: params[:base]), allow_other_host: true
+    end
+
+    def destroy
+      CodeReview.new(@burst, @stop.number).stop_server
+      redirect_to burst_pull_request_code_review_path(@burst, @stop.number)
+    end
+  end
+end

data/app/controllers/proctolog/decisions_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Every decision of the burst on one page, and the star that marks one as
+  # needing thought, which goes back to the page it was pressed on.
+  class DecisionsController < ApplicationController
+    include WithDecisions
+
+    # `fresh` reads GitHub again, then comes back to an address a reload can repeat.
+    def index
+      if params.key?(:fresh)
+        @burst.route(fresh: true)
+        return redirect_to(burst_decisions_path(@burst, show: params[:show]))
+      end
+
+      @burst.reports.take_in
+      # Listed and counted within the focus; the stars and ticks it sends are
+      # found among the whole burst's.
+      @decisions = @burst.decisions(pages:, focus:)
+      @filter = @decisions.filter_for(params[:show] || "open")
+      # By pull request, or by theme: one kind of question across the burst.
+      @by_theme = params[:by] == "theme"
+      @kept = params[:kept]
+      @records = DecisionRecord.all
+    end
+
+    def update
+      box = decisions.box(number, params.expect(:position).to_i, params.expect(:lead))
+      @burst.marks(number).star(box.lead, on: params.expect(:starred) == "1")
+      redirect_to url_from(params[:return].to_s) || burst_decisions_path(@burst, anchor: "box-#{box.to_param}")
+    end
+  end
+end

data/app/controllers/proctolog/entries_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The address a scenario's button hands a browser, good once: it sets the
+  # cookies that sign the browser in on the app and sends it there.
+  class EntriesController < ApplicationController
+    def show
+      visit = Visit.take(params.expect(:token)) or return render(plain: "This address was good once and has been used. Press the scenario's button again.", status: :gone)
+
+      response.headers["Set-Cookie"] = visit.cookies if visit.cookies.any?
+      redirect_to visit.to, allow_other_host: true
+    end
+  end
+end

data/app/controllers/proctolog/evidence_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The pictures an agent's answer rests on, shown where the answer is read.
+  class EvidenceController < ApplicationController
+    before_action { @evidence = Evidence.new(Burst.find(params.expect(:burst_id))) }
+
+    # Retaken under the same name as often as the agent works again, so never kept by the browser.
+    def show
+      file = @evidence.picture(params.expect(:path)) or return head(:not_found)
+
+      send_file file, type: Rack::Mime.mime_type(file.extname.downcase), disposition: :inline
+    end
+
+    # Where a before and its after differ, for the viewer to outline and go through.
+    def compare
+      files = params.expect(:before, :after).map { @evidence.picture(it) }
+      return head(:not_found) unless files.all?
+
+      render json: Difference.between(*files, cache: Project.current.cache).to_h.slice(:compared, :same, :sizes, :boxes)
+    end
+  end
+end

data/app/controllers/proctolog/freshness_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # How fresh the desk's reading of GitHub is. A page asks whether GitHub has
+  # moved on once it is shown, so that opening a page never waits on GitHub.
+  # With `again` the desk reads GitHub anew and goes back to the page that
+  # asked, as the pages' own "Read again" links do.
+  class FreshnessController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    def show
+      return again if params.key?(:again)
+
+      render json: {read_at: @burst.read_at.iso8601, **@burst.moved}
+    rescue Github::Unreachable
+      # A GitHub that does not answer says nothing has moved: the question is a courtesy.
+      render json: {changed: [], closed: []}
+    end
+
+    private
+
+    def again
+      @burst.route(fresh: true)
+      redirect_to url_from(params[:back].to_s) || burst_path(@burst)
+    end
+  end
+end

data/app/controllers/proctolog/good_to_go_controller.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The owner's "good to go" for the commit and the description a pull
+  # request has now, or the taking of it back.
+  class GoodToGoController < ApplicationController
+    include PullRequestScoped
+
+    # The mark is for what the owner was looking at: the page sends the commit
+    # and the description it showed, and GitHub is read again at this moment.
+    # A push or an edit in between means the mark is not given.
+    def create
+      now = @burst.route(fresh: true).at(@stop.number)
+
+      if now && [now.head_oid, now.description.digest] == [params[:head], params[:description]]
+        marks.settle(head: now.head_oid, described_at: now.described_at, description: now.description.digest)
+        back_to_the_page(anchor: "standing")
+      else
+        redirect_to burst_pull_request_path(@burst, @stop.number),
+          alert: "##{@stop.number} moved on GitHub since this page was read, so it was not marked. Look at it again as it is now."
+      end
+    end
+
+    def destroy
+      marks.unsettle
+      back_to_the_page(anchor: "standing")
+    end
+  end
+end

data/app/controllers/proctolog/memberships_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The owner moving a burst's kept membership on: by dismissing a notice
+  # that a pull request joined or left, or by handing the burst over.
+  class MembershipsController < ApplicationController
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    def update
+      @burst.membership.acknowledge(PullRequest.number(params.expect(:number)), @burst.route)
+      redirect_to burst_path(@burst, anchor: "notices")
+    end
+
+    # The pages' script says so once a handover is downloaded.
+    def handed_over
+      @burst.membership.hand_over(@burst.route)
+      head :no_content
+    end
+  end
+end

data/app/controllers/proctolog/mentions_controller.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The pull requests a # may mean, asked as the owner types one into any box
+  # of the desk: mentions.js offers them under it. A checkout with no GitHub
+  # repository, or digits that are not digits, mean none.
+  class MentionsController < ApplicationController
+    def index
+      mentions = Mentions.here
+      digits = params[:number].to_s[/\A\d{1,9}\z/]
+      return render(json: []) unless mentions && digits
+
+      render json: mentions.matching(digits).map(&:to_h)
+    end
+  end
+end

data/app/controllers/proctolog/moments_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A note pinned to a moment of a recording, and moving it along. Both go
+  # back to the player, which is where the owner was.
+  class MomentsController < ApplicationController
+    include NoteParams
+
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    def create
+      recording = Recording.find(@burst, params.expect(:recording)) or return head(:not_found)
+      time = Float(params.expect(:time), exception: false) or raise ActionController::BadRequest, "A moment is a time in seconds"
+      moment = recording.moment(time, box: params[:box].presence&.then { box_of(it) }, keep_in: Marks.directory_of(@burst).join("frames"))
+      note = @burst.marks(recording.folder).pin(kind: one_of(Note::KINDS, params.expect(:kind)), text: params.expect(:text).strip, place: moment)
+      redirect_to burst_recording_path(@burst, recording.to_param, anchor: "note-#{note.id}")
+    end
+
+    # A note's id begins with the folder of its recording: "sitting-3", "1085-2".
+    def update
+      id = params.expect(:id)
+      @burst.marks(id[/\A(sitting|\d+)-\d+\z/, 1].to_s).move(id, to: one_of(Note::STATES, params.expect(:state))) or return head(:not_found)
+      redirect_back_or_to burst_recordings_path(@burst)
+    end
+  end
+end

data/app/controllers/proctolog/note_params.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # What a controller that writes notes asks of its parameters.
+  module NoteParams
+    extend ActiveSupport::Concern
+
+    private
+
+    def one_of(choices, value) = choices.include?(value) ? value : raise(ActionController::BadRequest, "#{value.inspect} is none of #{choices.to_sentence}")
+
+    # A picture's id as the pictures route takes it, and nothing else, since
+    # it is kept in the note as it was sent.
+    def asset_of(id)
+      Picture.asset?(id) ? id : raise(Failure, "That is not the id of a picture, so no note was saved.")
+    end
+
+    # "x,y,width,height", each a fraction of the picture.
+    def box_of(text)
+      box = text.split(",").map { Float(it, exception: false) }
+      (box.size == 4 && box.all? { it&.between?(0, 1) }) ? box : raise(ActionController::BadRequest, "A box is four fractions of the picture, not #{text.inspect}")
+    end
+  end
+end

data/app/controllers/proctolog/notes_controller.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # Writing a note, and moving it along: both come back to the page that sent
+  # them when it said where (a note under a box is written on the decisions page
+  # or on the pull request's, and stays there), else to the pull request's page
+  # at the note.
+  class NotesController < ApplicationController
+    include NoteParams
+
+    before_action { @burst = Burst.find(params.expect(:burst_id)) }
+
+    # A note written in the picture viewer is saved without leaving it: the
+    # answer says where the page shows it, for once the viewer closes.
+    def create
+      note = marks.pin(kind: one_of(Note::KINDS, params.expect(:kind)), text: params.expect(:text).strip, place:)
+      respond_to do |format|
+        format.html { back_to note }
+        format.json { render json: {at: at(note), id: note.id}, status: :created }
+      end
+    end
+
+    # A state sent moves the note along; words sent without one are the note
+    # written again, as the picture viewer opens a note drawn on a picture.
+    def update
+      note = (params.key?(:state) ? moved : revised) or return head(:not_found)
+      respond_to do |format|
+        format.html { back_to note }
+        format.json { render json: {at: at(note), id: note.id} }
+      end
+    end
+
+    private
+
+    def marks = @marks ||= @burst.marks(PullRequest.number(params.expect(:pull_request_number)))
+
+    def moved = marks.move(params.expect(:id), to: one_of(Note::STATES, params.expect(:state)))
+
+    def revised = marks.revise(params.expect(:id), kind: one_of(Note::KINDS, params.expect(:kind)), text: params.expect(:text).strip)
+
+    def back_to(note) = redirect_to(url_from(params[:return].to_s) || at(note))
+
+    def at(note) = burst_pull_request_path(@burst, marks.number, anchor: "note-#{note.id}")
+
+    # Words of the description, a region of a picture, or neither: the whole pull request.
+    def place
+      if params.key?(:quote)
+        quote = params.expect(quote: %i[exact before after section])
+        Note::Quote.new(exact: quote.require(:exact), before: quote[:before].presence, after: quote[:after].presence, section: quote[:section].presence)
+      elsif params.key?(:picture)
+        picture = params.expect(picture: %i[picture asset box])
+        Note::Region.new(picture: picture.require(:picture), asset: asset_of(picture.require(:asset)), box: box_of(picture.require(:box)))
+      end
+    end
+  end
+end