proctolog 0.1.0

data/app/models/proctolog/check.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A description checked as the desk reads it, before it is published or
+  # after: faults, which keep the desk from reading it well, and warnings,
+  # which only advise, each on its line. It reads with the desk's own parser
+  # and the desk's own picture names, so the check and the desk agree.
+  class Check
+    # What was found, on which line of the description; `fault` is false for
+    # a warning.
+    Finding = Data.define(:row, :said, :fault)
+
+    # More blocking decisions than this ask too much of one owner at once.
+    MOST_BLOCKING = 5
+
+    # `rendering` is GitHub's HTML of the same Markdown.
+    def initialize(markdown, rendering:, themes: Theme.all)
+      @markdown = markdown.to_s.gsub("\r\n", "\n")
+      @description = Description.new(@markdown)
+      @themes = themes
+      @pictures = Rendering.new(rendering).sections.flat_map(&:figures).map { it["data-picture"] }.tally
+    end
+
+    def findings
+      @findings ||= if @description.rows(Description::DECISIONS).empty?
+        [fault(nil, "There is no “## #{Description::DECISIONS}” section.")]
+      else
+        [*decisions.flat_map { of(it) }, *runs_on, *repeated_keys, *halves, *too_many].sort_by { it.row.to_i }
+      end
+    end
+
+    def faults = findings.select(&:fault)
+
+    def warnings = findings.reject(&:fault)
+
+    def passed? = faults.empty?
+
+    def to_s
+      blocking = decisions.count(&:blocking?)
+      [("#{count(decisions.size, "decision")}: #{blocking} blocking, #{decisions.size - blocking} non-blocking." if decisions.any?),
+        *findings.map { [("line #{it.row}" if it.row), (it.fault ? "fault" : "warning"), it.said].compact.join(": ") },
+        how_to_name_a_theme, "#{count(faults.size, "fault")}, #{count(warnings.size, "warning")}."].compact.join("\n")
+    end
+
+    private
+
+    def decisions = @description.decisions
+
+    def fault(row, said) = Finding.new(row:, said:, fault: true)
+
+    def warning(row, said) = Finding.new(row:, said:, fault: false)
+
+    def count(number, noun) = "#{number} #{noun.pluralize(number)}"
+
+    # What one decision lacks: a bold lead, its alternative, a theme the
+    # project lists, and pictures that its links name once each.
+    def of(decision)
+      row = decision.row
+      [(fault(row, "It has no bold lead: open it with what was built, in **bold**.") unless decision.bare_text.match?(/\A\*\*.+?\*\*/)),
+        (fault(row, "It names no alternative: end it with “Alternative: …”, before its theme.") unless decision.alternative),
+        theme_of(decision), *pictures_of(decision)].compact
+    end
+
+    def theme_of(decision)
+      return fault(decision.row, "It names no theme.") unless decision.theme_name
+
+      fault(decision.row, "It names the theme “#{decision.theme_name}”, which the project does not list.") if Theme.named(decision.theme_name, @themes).other?
+    end
+
+    # Said once under the findings, when any of them is about a theme.
+    def how_to_name_a_theme
+      "A decision names its theme at its end, <!-- proctolog:theme NAME -->, NAME one of #{@themes.map(&:name).join(", ")}: `proctolog themes` says what each means." if findings.any? { it.said.include?("theme") }
+    end
+
+    # A link names a picture by its alt text, which must be one picture's
+    # alone, or a pair's: NAME-before beside NAME-after.
+    def pictures_of(decision)
+      decision.text.scan(Description::LINK).flatten.uniq.filter_map do |name|
+        shown = @pictures.fetch(name, 0) + (paired?(name) ? 1 : 0)
+        if shown.zero? then fault(decision.row, "It links the picture “#{name}”, which no picture of the description has as its alt text.")
+        elsif shown > 1 then fault(decision.row, "It links the picture “#{name}”, which #{shown} pictures' alt texts name: give each picture an alt text of its own.")
+        end
+      end
+    end
+
+    def paired?(name) = @pictures.key?("#{name}-before") && @pictures.key?("#{name}-after")
+
+    # A decision is one line: what is indented under it runs onto the next.
+    def runs_on
+      @description.rows(Description::DECISIONS).each_cons(2).filter_map do |(line, row), (following, _)|
+        fault(row, "It runs onto the next line: keep a decision to one line.") if line.match?(Description::BOX) && following.match?(/\A\s+\S/)
+      end
+    end
+
+    # A reference kept twice, or two decisions in the same words, would make
+    # a choice on one stand for the other.
+    def repeated_keys
+      decisions.group_by(&:key).values.select(&:many?).flat_map do |same|
+        same.drop(1).map { fault(it.row, "It has the same reference as the decision on line #{same.first.row}: give it one of its own, or drop the copy.") }
+      end
+    end
+
+    # One half of a pair with no other half: a picture named NAME-before
+    # with no NAME-after, or the other way round.
+    def halves
+      @pictures.keys.filter_map do |name|
+        stem, half = name.match(/\A(.+)-(before|after)\z/)&.captures
+        other = (half == "before") ? "after" : "before"
+        fault(row_of_picture(name), "The picture “#{name}” has no “#{stem}-#{other}” to pair with.") if stem && !@pictures.key?("#{stem}-#{other}")
+      end
+    end
+
+    def row_of_picture(name) = @markdown.lines.index { it.include?(%(alt="#{name}")) }&.succ
+
+    def too_many
+      blocking = decisions.select(&:blocking?)
+      return [] if blocking.size <= MOST_BLOCKING
+
+      [warning(blocking[MOST_BLOCKING].row, "#{blocking.size} decisions are blocking: more than #{MOST_BLOCKING} ask a lot of one owner. Grade the ones a default can settle non-blocking.")]
+    end
+  end
+end

data/app/models/proctolog/choices.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # The owner's choices on the decisions of a burst, with the drafts, batches
+  # and responses that go with them: one JSON document beside the marks, which
+  # the pages' script writes whole and an agent can read. The script numbers
+  # each writing, so a page that was left open cannot write over a newer one.
+  class Choices
+    # A writing older than the one kept: another page moved on since.
+    Stale = Class.new(StandardError)
+
+    # How far one pull request's decisions are: a decision is reviewed once
+    # the owner chose on its present words, or it is ticked on GitHub. Its
+    # blocking decisions are counted apart: those left of them are what
+    # deciding goes through, while every decision counts toward its standing.
+    Progress = Data.define(:total, :chosen, :ticked, :drafts, :blocking, :blocking_left) do
+      def initialize(total:, chosen:, ticked:, drafts:, blocking: total, blocking_left: total - chosen - ticked) = super
+
+      # Out of each decision and whether it is reviewed.
+      def self.of(reviewed, drafts: 0)
+        blocking = reviewed.select { |decision, _| decision.blocking? }
+        new(total: reviewed.size, ticked: reviewed.count { |decision, _| decision.ticked }, chosen: reviewed.count { |decision, done| done && !decision.ticked },
+          drafts:, blocking: blocking.size, blocking_left: blocking.count { |_, done| !done })
+      end
+
+      def reviewed = chosen + ticked
+      def left = total - reviewed
+      def done? = left.zero?
+      def any? = total.positive?
+
+      def non_blocking = total - blocking
+      def non_blocking_left = left - blocking_left
+
+      def +(other) = with(**members.to_h { [it, public_send(it) + other.public_send(it)] })
+    end
+
+    NONE = Progress.new(total: 0, chosen: 0, ticked: 0, drafts: 0)
+
+    def self.of(burst) = new(Marks.directory_of(burst).join("choices.json"))
+
+    def initialize(path) = @path = path
+
+    # Nil until a page has written one.
+    def document
+      @document ||= JSON.parse(@path.read) if @path.exist?
+    rescue JSON::ParserError => e
+      raise Failure, "The choices file #{@path} is not JSON (#{e.message.lines.first&.strip}). The desk left it as it is: mend it, or move it aside to start the choices again."
+    end
+
+    def revision = document&.fetch("revision", 0).to_i
+
+    # Keeps a newer writing, beside the file and moved over it, so a reader
+    # never meets half a file.
+    def keep(incoming)
+      incoming.fetch("revision", 0).to_i > revision or raise Stale, "These choices were saved from another page since this one read them."
+
+      @path.dirname.mkpath
+      draft = @path.sub_ext(".json.part")
+      draft.write(JSON.pretty_generate(incoming))
+      draft.rename(@path)
+      @document = incoming
+    end
+
+    def progress(number, decisions)
+      chosen = entries("choices").select { it.dig("decision", "pr") == number }
+      Progress.of(decisions.index_with { |decision| decision.ticked || chosen.any? { stands?(it, decision) } },
+        drafts: entries("pending").count { it.dig("decision", "pr") == number && it["text"].to_s.strip.present? })
+    end
+
+    # A choice still stands while its decision reads as it did and rests on
+    # the pictures it was made on. The page's script, reopened() in
+    # review-drafts.js, follows the same rules.
+    def stands?(entry, decision) = reads_as_it_did?(entry, decision) && !pictures_changed?(entry, decision)
+
+    private
+
+    def entries(field) = Array(document&.dig(field))
+
+    # Its words, theme markers aside. One the owner made by itself that kept
+    # its reference through a rewrite stands when nothing was asked of the
+    # agent, or when the owner confirmed what came back. One made by leaving
+    # every non-blocking decision at once was made on less attention: it
+    # stands only while its words are the same and its decision is still
+    # non-blocking.
+    def reads_as_it_did?(entry, decision)
+      was = entry.fetch("decision", {})
+      same = [was["lead"], Theme.unmarked(was["text"])] == [decision.lead, decision.bare_text]
+      return same && !promoted?(entry, decision) if left_in_bulk?(entry)
+      return true if same
+
+      was["key"].present? && was["key"] == decision.key && (entry["kind"] == "leave" || confirmed?(entry))
+    end
+
+    # A bulk leave records the grade each decision had.
+    def left_in_bulk?(entry) = entry["batch"].present? && entry["grade"].present?
+
+    def promoted?(entry, decision) = entry["grade"] == "non_blocking" && decision.blocking?
+
+    def confirmed?(entry) = document.dig("feedback", entry["requestId"], "resolution") == "confirmed"
+
+    # Its pictures, matched by name: one added or taken away, or one whose
+    # pixels are no longer those recorded. A picture whose pixels are not
+    # known, then or now, changes nothing: the page says it is unverified. A
+    # choice made before pictures were recorded has none to hold it to.
+    def pictures_changed?(entry, decision)
+      was = entry.dig("decision", "pictures") or return false
+      seen = was.to_h { [it["name"], it["signature"]] }
+      now = decision.pictures.to_h { [it.name, Picture.signature(it.asset)] }
+      seen.keys.to_set != now.keys.to_set || now.any? { |name, signature| signature && seen[name] && signature != seen[name] }
+    end
+  end
+end

data/app/models/proctolog/code_review.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "open3"
+
+module Proctolog
+  class CodeReview
+    BASE = "refs/heads/proctolog-base"
+    HEAD = "refs/heads/proctolog-head"
+
+    # What Diffle holds of the pull request at a glance: the comments nobody
+    # resolved, which join the next handover, and how many of the files of
+    # the code last opened are marked viewed. `files` is nil until it opens.
+    Tally = Data.define(:open, :viewed, :files)
+
+    def initialize(burst, number)
+      @burst, @number = burst, PullRequest.number(number) || raise(ArgumentError, "#{number.inspect} is no pull request's number")
+    end
+
+    def folder = Marks.directory_of(@burst).join("code", @number.to_s)
+    def checkout = folder.join("checkout")
+
+    def snapshot
+      file = folder.join("snapshot.json")
+      file.file? ? JSON.parse(file.read) : nil
+    rescue JSON::ParserError => e
+      raise Failure, "The code-review snapshot #{file} could not be read: #{e.message}"
+    end
+
+    def threads
+      file = checkout.join(".git/diffle/comments.json")
+      return [] unless file.file?
+
+      data = JSON.parse(file.read)
+      raise Failure, "Diffle's comments in #{file} use an unsupported format." unless data["version"] == 3 && data["sets"].is_a?(Hash)
+
+      data["sets"].flat_map { |key, set| Array(set["threads"]).map { it.merge("mode" => key) } }.uniq { it.fetch("id") }
+    rescue JSON::ParserError, KeyError, NoMethodError => e
+      raise Failure, "Diffle's comments in #{file} could not be read: #{e.message}"
+    end
+
+    def requests
+      captured = snapshot
+      return [] unless captured
+
+      readings = captured.fetch("readings", {})
+      threads.reject { it["resolved"] }.map do |thread|
+        focused = thread.fetch("mode")[/\Acommit:(\h{40})\z/, 1]
+        reading = readings.find { |asked, kept| set_of(kept, asked) == thread.fetch("mode") }&.last || captured
+        {id: "code:#{@number}:#{thread.fetch("id")}", pr: @number, kind: "remark",
+         text: thread.fetch("messages").map { it.fetch("body") }.join("\n\n"),
+         source: {kind: "code", head: focused || reading.fetch("head"), base: focused ? "#{focused}^" : reading.fetch("oldSha"),
+                  anchor: thread.fetch("anchor"), mode: thread.fetch("mode"), stale: thread.fetch("stale"),
+                  updatedAt: thread.fetch("messages").map { it.fetch("updatedAt") }.max}}
+      end
+    end
+
+    def viewed
+      file = checkout.join(".git/diffle/comments.json")
+      captured = snapshot
+      return [] unless file.file? && captured
+
+      Array(JSON.parse(file.read).dig("sets", set_of(captured), "viewed"))
+    end
+
+    # The files of the code last opened that are marked viewed as they are
+    # there: a mark on another version of a file does not count.
+    def files_viewed
+      marked = viewed.select { it["viewed"] }
+      Array(snapshot&.fetch("files")).count { |file| marked.any? { it.values_at("path", "blob") == file.values_at("path", "blob") } }
+    end
+
+    def tally = Tally.new(open: threads.count { !it["resolved"] }, viewed: files_viewed, files: snapshot&.fetch("files")&.size)
+
+    def start(stop, head: nil, base: nil)
+      folder.mkpath
+      File.open(folder.join("start.lock"), "a") do |lock|
+        lock.flock(File::LOCK_EX)
+        pair = revisions(stop).dup
+        pair["prHead"] = pair.fetch("headRefOid")
+        if head
+          raise Failure, "The returned head must be a full available commit hash." unless held?(head)
+          pair["headRefOid"] = head
+        end
+        if base == "main"
+          pair["baseRefOid"] = main_head
+        elsif base
+          raise Failure, "The reviewed base must be a full available commit hash, or main." unless held?(base)
+          pair["baseRefOid"] = base
+        end
+        pair["comparison"] = if base == "main"
+          "main"
+        elsif base
+          "changes"
+        else
+          "layer"
+        end
+        separator = (base && base != "main") ? ".." : "..."
+        pair["range"] = "#{pair.fetch("baseRefOid")}#{separator}#{pair.fetch("headRefOid")}"
+        captured = snapshot
+        return captured.fetch("url") if captured && captured["mode"] == "range:#{pair.fetch("range")}" && live?(captured)
+
+        stop_server if captured
+        prepare(pair)
+        launch(pair)
+      end
+    end
+
+    def live?(captured = snapshot)
+      return false unless captured
+
+      answer = get(captured.fetch("url"), "/api/snapshot")
+      answer["root"] == checkout.realpath.to_s
+    rescue Failure, KeyError
+      false
+    end
+
+    def stop_server
+      captured = snapshot
+      return unless live?(captured)
+
+      Process.kill("TERM", captured.fetch("pid"))
+    rescue Errno::ESRCH
+      nil
+    end
+
+    private
+
+    # The comparison a snapshot opened, as the desk asked for it. The first
+    # snapshots compared the pinned refs and did not say so.
+    def mode_of(captured) = captured.fetch("mode", "range:#{BASE}...#{HEAD}")
+
+    # The set Diffle keeps a comparison's comments and viewed marks in. Diffle
+    # names it for what it compares: for three dots, the merge base, not the
+    # base it was given. It says the name as it opens, and the desk keeps it;
+    # a reading kept before then has the name made again from its revisions.
+    def set_of(reading, asked = mode_of(reading)) = reading["set"] || asked.sub(/\Arange:\h{40}/) { "range:#{reading.fetch("oldSha")}" }
+
+    def held?(hash)
+      hash.is_a?(String) && hash.match?(/\A[a-f0-9]{40}\z/) && [Project.current.root, checkout].any? do |root|
+        root.directory? && Open3.capture2e("git", "-C", root.to_s, "cat-file", "-e", "#{hash}^{commit}").last.success?
+      end
+    end
+
+    def main_head
+      output, status = Open3.capture2e("gh", "api", "repos/#{@burst.repository}/commits/main", "--jq", ".sha")
+      hash = output.strip
+      raise Failure, "GitHub could not name main's revision: #{output.strip}" unless status.success? && hash.match?(/\A[a-f0-9]{40}\z/)
+      hash
+    end
+
+    def revisions(stop) = revisions_now.tap { read_again_for(it.fetch("headRefOid")) unless it["headRefOid"] == stop.head_oid }
+
+    # Its base and head as GitHub names them this moment, or as this Mac
+    # holds them while nobody has opened it.
+    def revisions_now
+      return Unopened.find(@number)&.heads || raise(Failure, "##{@number} is no longer waiting unopened.") if PullRequest.unopened?(@number)
+
+      output, status = Open3.capture2e("gh", "pr", "view", @number.to_s, "--repo", @burst.repository, "--json", "baseRefOid,headRefOid")
+      raise Failure, "GitHub could not name this PR's revisions: #{output.strip}" unless status.success?
+
+      JSON.parse(output).tap do |pair|
+        raise Failure, "GitHub returned invalid revision hashes." unless %w[baseRefOid headRefOid].all? { pair[it].to_s.match?(/\A\h{40}\z/) }
+      end
+    end
+
+    # A head that moved since the desk read GitHub has the desk read it
+    # again, as `r` would, so the pull request's page and Diffle show the
+    # same code. GitHub moving once more in those seconds is said.
+    def read_again_for(head)
+      now = @burst.route(fresh: true).at(@number) or raise Failure, "##{@number} is no longer part of #{@burst.name}."
+      now.head_oid == head or raise Failure, "##{@number} moved on GitHub while the desk read it again. Open its code once more."
+    end
+
+    def prepare(pair)
+      git!("clone", "--quiet", "--local", "--no-checkout", Project.current.root.to_s, checkout.to_s) unless checkout.join(".git").directory?
+      hashes = pair.values_at("baseRefOid", "headRefOid")
+      absent = hashes.reject { Open3.capture2e("git", "-C", checkout.to_s, "cat-file", "-e", "#{it}^{commit}").last.success? }
+      local = absent.select { Open3.capture2e("git", "-C", Project.current.root.to_s, "cat-file", "-e", "#{it}^{commit}").last.success? }
+      git!("-C", checkout.to_s, "fetch", "--quiet", "--no-tags", Project.current.root.to_s, *local) if local.any?
+      absent -= local
+      unless absent.empty?
+        raise Failure, "Invalid GitHub repository name." unless @burst.repository.match?(%r{\A[\w.-]+/[\w.-]+\z})
+        git!("-C", checkout.to_s, "fetch", "--quiet", "--no-tags", "https://github.com/#{@burst.repository}.git", *absent)
+      end
+      git!("-C", checkout.to_s, "update-ref", BASE, hashes.first)
+      git!("-C", checkout.to_s, "update-ref", HEAD, hashes.last)
+    end
+
+    def launch(pair)
+      log = folder.join("server.log")
+      output = folder.join("export.md")
+      command = ENV.fetch("PROCTOLOG_DIFFLE", "diffle")
+      arguments = [command, "-C", checkout.to_s, pair.fetch("range"), "--no-open", "--no-lsp", "--no-watch", "--keep-alive", "--host", "127.0.0.1", "--port", "0"]
+      pid = Outside.run do |environment|
+        Process.spawn(environment.merge("NO_COLOR" => "1"), *arguments, out: output.to_s, err: log.to_s)
+      end
+      process = Process.detach(pid)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 30
+      loop do
+        url = log.file? && log.read[%r{http://127\.0\.0\.1:\d+/}]
+        if url
+          answer = get(url, "/api/snapshot")
+          raise Failure, "Diffle opened a different checkout or head." unless answer["root"] == checkout.realpath.to_s && answer["newSha"] == pair["headRefOid"]
+
+          previous = snapshot
+          readings = previous&.fetch("readings", {}) || {}
+          readings[mode_of(previous)] ||= previous.slice("head", "base", "oldSha", "set") if previous
+          mode = "range:#{pair.fetch("range")}"
+          set = answer.dig("mode", "commentKey")
+          readings[mode] = {"head" => pair.fetch("headRefOid"), "base" => pair.fetch("baseRefOid"), "oldSha" => answer.fetch("oldSha"), "set" => set}.compact
+          captured = {"pid" => pid, "url" => url, "mode" => mode, "set" => set, "readings" => readings, "comparison" => pair.fetch("comparison"), "head" => pair.fetch("headRefOid"), "prHead" => pair.fetch("prHead"), "base" => pair.fetch("baseRefOid"),
+                      "oldSha" => answer.fetch("oldSha"), "files" => answer.fetch("changed"), "openedAt" => Time.current.iso8601}.compact
+          file = folder.join("snapshot.json")
+          file.sub_ext(".part").write(JSON.pretty_generate(captured))
+          file.sub_ext(".part").rename(file)
+          return url
+        end
+        raise Failure, "Diffle did not start. See #{log}.\n#{log.file? ? log.read.last(2000) : "No log was written."}" if !process.alive? || Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        sleep 0.1
+      end
+    rescue Errno::ENOENT
+      raise Failure, "Diffle is not on PATH. Install it or set PROCTOLOG_DIFFLE to its executable."
+    rescue Failure
+      begin
+        Process.kill("TERM", pid) if pid
+      rescue Errno::ESRCH
+        nil
+      end
+      raise
+    end
+
+    def get(url, path)
+      origin = URI.parse(url)
+      raise Failure, "The saved Diffle address is not a loopback address." unless origin.scheme == "http" && origin.host == "127.0.0.1" && origin.port.positive?
+
+      response = Net::HTTP.start(origin.host, origin.port, nil, open_timeout: 2, read_timeout: 15) { it.get(path) }
+      raise Failure, "Diffle did not answer (#{response.code})." unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    rescue IOError, SystemCallError, Timeout::Error, JSON::ParserError, URI::InvalidURIError => e
+      raise Failure, "Diffle could not be reached: #{e.message}"
+    end
+
+    def git!(*arguments)
+      output, status = Open3.capture2e("git", *arguments)
+      raise Failure, "The private code-review checkout could not be prepared: #{output.strip}" unless status.success?
+      output
+    end
+  end
+end

data/app/models/proctolog/decision_record.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Proctolog
+  # A decision record of the repository, under docs/adr/: where a decision is
+  # recorded once it is more than a ticked box. Read from disk, never copied.
+  class DecisionRecord < Data.define(:file, :title)
+    def self.all(directory = nil) = Array(directory || Project.current.decision_records).flat_map { it.glob("*.md") }.sort.map { from(it) }
+
+    # Its first heading names it; a file with none is named by its file.
+    def self.from(path) = new(file: path.basename.to_s, title: path.each_line.find { it.start_with?("# ") }&.delete_prefix("# ")&.strip || path.basename(".md").to_s)
+  end
+end