openlanes 3.0.1 → 3.1.0

data/lib/openlanes/engine/pr_outcomes.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # What a {PrWatch::Outcome} does to the plan folder (M4): the side
+    # effects the watch itself refuses to have.
+    #
+    # A person's verdict arrives on GitHub, not in a ledger, so this is where
+    # it is written down: the pull request's row in `pull-requests.md`, the
+    # folder's state, and for a rejection the comments, mailed to the agents
+    # who fix it. Each step is asked of the folder as it stands, so applying
+    # the same outcome twice changes nothing the second time; that is what
+    # lets the watch ask GitHub again every 15 seconds without remembering
+    # what it already did.
+    class PrOutcomes
+      # What changed, for the log.
+      #
+      # @!attribute [r] plan
+      #   @return [String] ordinal
+      # @!attribute [r] pr
+      #   @return [Integer]
+      # @!attribute [r] to
+      #   @return [Symbol, nil] the state the folder moved to, nil when it stayed
+      # @!attribute [r] note
+      #   @return [String]
+      Applied = Data.define(:plan, :pr, :to, :note)
+
+      # Who signs a mail carrying a person's review comments.
+      SENDER = "github"
+
+      # @param tree_dir [String] the `.plans` directory, reread after each rename
+      # @param agents [Agents::Registry] who handles 🔴, and so gets the comments
+      # @param clock [#call] the time a merge is recorded at
+      def initialize(tree_dir:, agents:, clock: -> { Clock::System.now })
+        @tree_dir = tree_dir
+        @agents = agents
+        @clock = clock
+      end
+
+      # @param outcome [PrWatch::Outcome]
+      # @return [Applied, nil] nil when the folder already said so
+      def apply(outcome)
+        case outcome.kind
+        when :rejected then reject(outcome)
+        when :merged then merged(outcome)
+        when :closed then closed(outcome)
+        end
+      end
+
+      private
+
+      # `review-rejected` with comments: 🔴, and the comments to the builders.
+      # A plan already at 🔴 has been told; one at 🟢 passes through 👀, the
+      # only state the machine rejects from.
+      def reject(outcome)
+        subject = find(outcome.plan) or return nil
+        return nil if subject.status.key == :rejected
+
+        moved = walk(subject, :rejected) or return nil
+        # A person overruled the approval: the board must stop showing it
+        # as finished.
+        Plans::PlanState.for(moved.feature.path).unfinish!
+        mailed = mail(moved, outcome)
+        Applied.new(plan: outcome.plan,
+          pr: outcome.pr,
+          to: :rejected,
+          note: "PR ##{outcome.pr} labelled #{Plans::ReviewLabel::REJECTED.name}; mailed #{mailed.join(", ")}")
+      end
+
+      # Merged on GitHub: the row says so, `state.json` says when (the
+      # watch learns of it on the poll after, which is as close as a
+      # local clock gets), and once no pull request is left open the plan is
+      # ✅, by the person who merged it.
+      def merged(outcome)
+        subject = find(outcome.plan) or return nil
+        record(subject, outcome.pr, "merged")
+        Plans::PlanState.for(subject.feature.path).finish!("merged", at: @clock.call)
+        subject = find(outcome.plan)
+        return applied(outcome, nil, "merged") if subject.pull_requests.any?(&:open?)
+
+        to = walk(subject, :approved) ? :approved : nil
+        applied(outcome, to, "merged")
+      end
+
+      # Closed unmerged: the row says so, and a plan with nothing merged and
+      # nothing open is ❌, with `discarded.md` saying who closed what.
+      def closed(outcome)
+        subject = find(outcome.plan) or return nil
+        record(subject, outcome.pr, "closed")
+        subject = find(outcome.plan)
+        prs = subject.pull_requests
+        return applied(outcome, nil, "closed unmerged") if prs.any? { it.open? || it.merged? }
+
+        return applied(outcome, nil, "closed unmerged") if subject.status.key == :discarded
+
+        note = File.join(subject.feature.path, "discarded.md")
+        written = !File.exist?(note) && File.write(note, <<~MARKDOWN)
+          # Discarded
+
+          Every pull request was closed on GitHub without merging: #{prs.map { "##{it.number}" }.join(", ")}.
+        MARKDOWN
+        to = walk(subject, :discarded) ? :discarded : nil
+        # ❌ requires the note, so it is written before the move; a refused
+        # move takes it back, or the folder would carry a discarded note
+        # while claiming some other state.
+        File.delete(note) if written && to.nil?
+        applied(outcome, to, "closed unmerged")
+      end
+
+      # @return [Applied]
+      def applied(outcome, to, what) = Applied.new(plan: outcome.plan, pr: outcome.pr, to:, note: "PR ##{outcome.pr} #{what}")
+
+      # Rewrite one row's state in `pull-requests.md`, worded as
+      # {Plans::PullRequests::STATES} words it, leaving every other row and
+      # every line around the table alone.
+      def record(subject, number, word)
+        pair = Plans::PullRequests::STATES.find { |pattern, _| pattern.match?(word) } or
+          raise(Error, "no pull request state matches #{word.inspect}; Plans::PullRequests::STATES must word it")
+        state = pair.last
+        rows = subject.pull_requests.map do |pr|
+          mine = pr.number.to_s.delete("#").to_i == number
+          { number: pr.number, title: pr.title, url: pr.url, state: mine ? state : pr.state }
+        end
+        Plans::PullRequests.upsert(File.join(subject.feature.path, Plans::PullRequests::FILENAME), rows)
+      end
+
+      # Move to +to+, through 👀 when the plan is still at 🟢: a person who
+      # ruled on GitHub before hansolo did has reviewed it all the same.
+      #
+      # @return [Plans::Subject, nil] the plan after the move, nil when the
+      #   machine refused it
+      def walk(subject, to)
+        subject.machine.promote!(:in_review) if subject.status.key == :ready_for_review && !subject.machine.may?(to)
+        subject = find(subject.feature.ordinal.to_s)
+        return nil unless subject.machine.may?(to)
+
+        subject.machine.promote!(to)
+        find(subject.feature.ordinal.to_s)
+      rescue Plans::StateMachine::Refused
+        nil
+      end
+
+      # @return [Array<String>] who was mailed
+      def mail(subject, outcome)
+        body = ["PR ##{outcome.pr} was labelled #{Plans::ReviewLabel::REJECTED.name} on GitHub.", *comments(outcome)].join("\n\n")
+        status = Plans::STATUS_BY_KEY.fetch(:rejected)
+        @agents.all.select { it.handles?(status) }.map(&:name).each do |name|
+          Plans::Mailbox.new(dir: subject.feature.path).append(from: SENDER, to: name, body:)
+        end
+      end
+
+      def comments(outcome)
+        return ["No comment was left; read the review on GitHub."] if outcome.comments.empty?
+
+        outcome.comments.map { |c| "#{c[:author]} (#{c[:url]}):\n\n#{c[:body].strip}" }
+      end
+
+      def find(ordinal) = Plans::Tree.new(dir: @tree_dir).find(ordinal)
+    end
+  end
+end

data/lib/openlanes/engine/pr_watch.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # Human mode (M4): while a person reviews and merges, the engine watches
+    # each plan's open pull request and says what happened to it.
+    #
+    # Paced by elapsed time rather than by ticks, so a faster tick loop does
+    # not become a faster stream of `gh` calls. It only reads; the dispatcher
+    # fires the events and sends the mail.
+    class PrWatch
+      # What one pull request turned out to be.
+      #   :rejected — carries `review-rejected`; `comments` are what to fix
+      #   :merged, :closed — no longer open, merged or not
+      #   :waiting — still open, waiting on a person
+      Outcome = Data.define(:plan, :pr, :kind, :comments) do
+        def initialize(comments: [], **rest) = super
+      end
+
+      # @param github [Vcs::GitHub]
+      # @param clock [#call] monotonic seconds
+      # @param interval [Numeric] seconds between polls
+      def initialize(github:, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, interval: 15)
+        @github = github
+        @clock = clock
+        @interval = interval
+        @last = nil
+      end
+
+      # @return [Boolean] whether a poll is due; the first one waits a full interval
+      def due?
+        now = @clock.call
+        @last ||= now
+        now - @last >= @interval
+      end
+
+      # One `gh pr list` for every watched plan, and one `gh pr view` for each
+      # watched pull request that list left out.
+      #
+      # @param subjects [Array<Plans::Subject>]
+      # @return [Array<Outcome>] one per open pull request a plan records
+      def poll(subjects)
+        @last = @clock.call
+        watched = subjects.flat_map { |s| s.pull_requests.select(&:open?).map { |pr| [s, pr.number.to_s.delete("#").to_i] } }
+        return [] if watched.empty?
+
+        by_number = @github.pulls(state: "all").to_h { |row| [row[:number], row] }
+        watched.filter_map do |subject, number|
+          row = by_number[number] || lookup(number) or next
+          outcome(subject, number, row)
+        end
+      end
+
+      private
+
+      # `gh pr list` returns only the newest pull requests, up to its limit,
+      # so a plan whose pull request is older than that would drop out of
+      # every poll and its merge or rejection would never be applied. Asked
+      # by number instead. One that cannot be read is skipped this poll and
+      # asked again on the next, rather than stopping the watch for all.
+      #
+      # @return [Hash, nil] a row shaped like {Vcs::GitHub#pulls}
+      def lookup(number)
+        @github.pull_request(number.to_s)
+      rescue Error
+        nil
+      end
+
+      def outcome(subject, number, row)
+        plan = subject.feature.ordinal.to_s
+        if row[:open]
+          return Outcome.new(plan:, pr: number, kind: :waiting) unless rejected?(row)
+
+          Outcome.new(plan:, pr: number, kind: :rejected, comments: @github.review_comments(number:))
+        else
+          Outcome.new(plan:, pr: number, kind: row[:state].to_s.start_with?("Merged") ? :merged : :closed)
+        end
+      end
+
+      def rejected?(row) = Array(row[:labels]).include?(Plans::ReviewLabel::REJECTED.name)
+    end
+  end
+end

data/lib/openlanes/engine/progress_log.rb

@@ -5,133 +5,46 @@ require "tmpdir"
 
 module OpenLanes
   module Engine
-    # One line of `run --log FILE`, laid out as fixed-width columns.
+    # What is left of the run's own column-format log now that every event
+    # goes through {Log}: the clock and the status cell the terminal's lines
+    # are drawn with, and where a spawned server's raw output is kept.
     #
-    # The log file is the only record of a headless run, and it is shared: two
-    # `openlanes run` invocations pointed at the same `--log` both append to
-    # it, interleaved, and so does every round within one run. That is what the
-    # process id column is for. Without it a reader cannot tell one run's agents
-    # from another's, and "started 003.00" twice looks like a bug rather than two
-    # machines doing the same work.
-    #
-    # Fixed columns are what make the file readable by eye and by `awk` alike. A
-    # value wider than its column is cut rather than allowed to push the columns
-    # out, and a value that is missing still occupies its width, so a round header
-    # with no plan or agent of its own lines up with the lines underneath it.
-    #
-    # @example
-    #   ProgressLog.render("editing spec.md", plan: "003.00", status: "⭐️ Planned",
-    #     agent: "yoda-writer", seconds: 42, round: "01", pid: 91_234)
-    #   #=> "[16:22:14 | 003.00 | ⭐️  Planned            | yoda-writer          | 01 |   91234 |    42s] editing spec.md"
+    # The fixed-column file it used to write is gone. Two files saying the
+    # same thing in two formats is the duplication this codebase keeps
+    # paying for; `log/development.log` is now the one record of a run.
     module ProgressLog
-      # Wall clock only. A log line answers "when", and the date is the file's.
+      # Wall clock only. A terminal line answers "when", and the date is the day's.
       TIME_FORMAT = "%H:%M:%S"
 
-      # Width of {TIME_FORMAT}'s output.
-      TIME_WIDTH = 8
-
-      # "003.00".
-      PLAN_WIDTH = 6
-
       # Cells given to the emoji, and the gap after it. Many terminal fonts draw
       # a colour emoji wider than its two cells, and with one space it overlapped
       # the label's first letter ("🔴Changes").
       EMOJI_WIDTH = 2
       EMOJI_GAP = "  "
 
-      # Derived from the widest state as {.status_cell} renders it, so a state
-      # added to {STATUSES} with a longer label cannot silently knock the columns
-      # after it out of line. Untrimmed: cut to fit, "Changes Requested" and
-      # "Ready for Planning" read as "Changes Reque" and "Ready for Pla".
-      STATUS_WIDTH = Plans::STATUSES.map { |status| EMOJI_WIDTH + EMOJI_GAP.length + UI.display_width(status.label) }.max
-
-      # The longest specialist name in `agents/` is `palpatine-planner` at 17,
-      # and the names are hyphenated words rather than a bounded vocabulary, so
-      # this leaves room for one more without a reflow.
-      AGENT_WIDTH = 20
-
-      # Enough for a 32-bit process id, right justified.
-      PID_WIDTH = 7
-
-      # "01". Rounds cap at two digits; a run that reaches a third has bigger
-      # problems than this column.
-      ROUND_WIDTH = 2
-
-      # "  907s". Anything longer than four digits of seconds is an agent nobody
-      # is still waiting on.
-      SECONDS_WIDTH = 6
-
-      # The keywords {.render} takes besides the message. {UI.log} hands its
-      # taps more than these, and the file only these.
-      FIELDS = %i[plan status agent seconds round pid at].freeze
-
-      # Between columns, inside the brackets.
-      SEPARATOR = " | "
-
-      # Cells from the opening bracket to the closing one, separators included.
-      # The message starts one space after this on every line, whatever fields
-      # that line happens to be missing, so a reader indenting a wrapped message
-      # has a number to indent by.
-      COLUMN_WIDTHS = [TIME_WIDTH, PLAN_WIDTH, STATUS_WIDTH, AGENT_WIDTH, ROUND_WIDTH, PID_WIDTH,
-                       SECONDS_WIDTH].freeze
-
-      # @see COLUMN_WIDTHS
-      LINE_WIDTH = COLUMN_WIDTHS.sum + (SEPARATOR.length * (COLUMN_WIDTHS.size - 1)) + 2
-
-      # Hex digits of the checkout's path in a default log's name.
+      # Hex digits of the checkout's path in a default file's name.
       CHECKOUT_DIGITS = 6
 
       class << self
-        # Where a run's log goes when `--log` names nowhere: the temp
+        # Where a spawned process's raw STDOUT and STDERR go: the temp
         # directory, under the checkout's directory name and a short digest
         # of its full path. The name alone collided: `~/a/minesweeper` and
         # `~/b/minesweeper` both appended to `openlanes-minesweeper.log`, and
         # two runs' lines read as one.
         #
         # @param root [String] the checkout
-        # @param kind [String, nil] which process logs, e.g. "web"
-        # @return [String] e.g. "/tmp/openlanes-minesweeper-3f9a1c.log"
+        # @param kind [String, nil] which process writes it, e.g. "web"
+        # @return [String] e.g. "/tmp/openlanes-web-minesweeper-3f9a1c.log"
         def default_path(root, kind: nil)
           root = File.expand_path(root)
           digest = Digest::SHA256.hexdigest(root)[0, CHECKOUT_DIGITS]
           File.join(Dir.tmpdir, "#{["openlanes", kind, File.basename(root), digest].compact.join("-")}.log")
         end
 
-        # Render one log line: bracketed fixed-width columns, then the message.
-        #
-        # No colour. The line goes to a file, where an escape sequence is neither
-        # readable nor the width it claims to be.
-        #
-        # @param message [String] the free-form tail, the only variable-width part
-        # @param plan [String, nil] the plan's ordinal, e.g. "003.00"
-        # @param status [String, nil] emoji and label, e.g. "⭐️ Planned"
-        # @param agent [String, nil] the specialist's name, e.g. "yoda-writer"
-        # @param seconds [Numeric, nil] how long this agent has been alive
-        # @param round [String, nil] which pass over the tree, e.g. "01"
-        # @param pid [Integer, nil] which run wrote the line
-        # @param at [Time] injectable, so a caller can render a fixed clock
-        # @return [String] one line, with no trailing newline
-        def render(message, plan: nil, status: nil, agent: nil, seconds: nil,
-          round: nil, pid: Process.pid, at: Time.now)
-          columns = [
-            left(at.strftime(TIME_FORMAT), TIME_WIDTH),
-            left(plan, PLAN_WIDTH),
-            left(status_cell(status), STATUS_WIDTH),
-            left(agent, AGENT_WIDTH),
-            right(round, ROUND_WIDTH),
-            right(pid, PID_WIDTH),
-            right(duration(seconds), SECONDS_WIDTH)
-          ]
-
-          text = message.to_s
-          prefix = "[#{columns.join(SEPARATOR)}]"
-          text.empty? ? prefix : "#{prefix} #{text}"
-        end
-
         # The emoji fitted to {EMOJI_WIDTH} and followed by {EMOJI_GAP}, then the
         # label. A value with no label (or none at all) passes through.
         #
-        # @param status [String, nil] emoji and label, e.g. "⭐️ Planned"
+        # @param status [String, nil] emoji and label, e.g. "⭐ Planned"
         # @return [String, nil]
         def status_cell(status)
           emoji, label = status.to_s.split(" ", 2)
@@ -139,27 +52,6 @@ module OpenLanes
 
           "#{UI.fit(emoji, EMOJI_WIDTH)}#{EMOJI_GAP}#{label}"
         end
-
-        # @param seconds [Numeric, nil]
-        # @return [String] whole seconds with a trailing "s", or blank for nil
-        def duration(seconds) = seconds.nil? ? "" : "#{seconds.round}s"
-
-        # @param value [Object, nil]
-        # @param width [Integer] terminal cells
-        # @return [String] padded on the right to exactly +width+ cells
-        def left(value, width) = UI.fit(value, width)
-
-        # {UI.fit} pads on the right, which is the wrong end for a number. Fit
-        # first so an over-long value is still truncated to the column, then move
-        # the padding to the front.
-        #
-        # @param value [Object, nil]
-        # @param width [Integer] terminal cells
-        # @return [String] padded on the left to exactly +width+ cells
-        def right(value, width)
-          text = UI.fit(value, width).rstrip
-          UI.fit("", width - UI.display_width(text)) + text
-        end
       end
     end
   end

data/lib/openlanes/engine/quality_question.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Engine
+    # R4's question, `desired_codebase_quality`, put to a person once per
+    # project: on the first pull request labelled `review-ok-not-perfect`
+    # while `.openlanes.yml` has no key. It hangs on the plan whose pull
+    # request raised it, kept in that plan's `state.json` so it survives a
+    # restart, and every other plan waiting on the same answer stays 👀
+    # without asking again. The answer is written into `.openlanes.yml`,
+    # after which nothing asks.
+    module QualityQuestion
+      # The question's name on its plan, as `X<n>` is an extension's.
+      NAME = "Q1"
+
+      # R4's wording, verbatim where it fits a card.
+      HEADING = "Please indicate the desired quality of the codebase"
+
+      # @return [String]
+      BODY = "This affects the severity of items found during review that will require rework. " \
+             "Critical blocking issues or security issues identified during review will be addressed regardless."
+
+      # One choice, the letter the page sends back and the key it writes.
+      #
+      # @!attribute [r] letter
+      #   @return [String]
+      # @!attribute [r] quality
+      #   @return [Symbol] one of {Config::QUALITIES}
+      # @!attribute [r] label
+      #   @return [String]
+      Choice = Data.define(:letter, :quality, :label)
+
+      # @return [Array<Choice>]
+      CHOICES = [
+        Choice.new(letter: "a",
+          quality: :high,
+          label: "High quality, but slower and more expensive. A PR review labelled \"review-ok-not-perfect\" " \
+                 "returns to developers for fixes."),
+        Choice.new(letter: "b",
+          quality: :mvp,
+          label: "Good enough, but faster and cheaper, think MVP (\"review-ok-not-perfect\" is accepted, " \
+                 "as it contains no blocking issues).")
+      ].freeze
+
+      module_function
+
+      # Ask, unless some plan in the same tree already has the question open.
+      #
+      # @param plan_dir [String] the asking plan's folder
+      # @param at [Time]
+      # @return [Boolean] whether this plan holds the open question
+      def ask!(plan_dir, at: Clock::System.now)
+        holder = open_in(File.dirname(plan_dir))
+        return holder == plan_dir if holder
+
+        Plans::PlanState.for(plan_dir).ask_quality!(at:)
+        true
+      end
+
+      # @param plans_dir [String]
+      # @return [String, nil] the folder of the plan whose question is open
+      def open_in(plans_dir)
+        Dir.glob(File.join(plans_dir, "*", Plans::PlanState::FILENAME)).map { File.dirname(it) }.find do |dir|
+          ask = Plans::PlanState.for(dir).quality_ask
+          ask && !ask.key?("settled_at")
+        end
+      end
+
+      # The open question on this plan, as the page's `Question`s.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param plan [OpenLanes::Plans::PlanState]
+      # @return [Array<Hash>] empty unless this plan holds it, unanswered
+      def questions(subject, plan)
+        ask = plan.quality_ask
+        return [] if ask.nil? || ask.key?("settled_at")
+
+        [{ id:       "#{subject.feature.ordinal}/#{NAME}",
+           number:   1,
+           kind:     "quality",
+           heading:  HEADING,
+           body:     BODY,
+           agent:    nil,
+           owner:    "product",
+           options:  CHOICES.map do |choice|
+             { letter: choice.letter, label: choice.label, recommended: choice.quality == Config::QUALITIES.first,
+               answer: "#{choice.letter}) #{choice.label}" }
+           end,
+           held:     false,
+           asked_at: ask["asked_at"] }]
+      end
+
+      # Settle the question and write the key, unless the file has one by now.
+      #
+      # @param plan_dir [String]
+      # @param letter [String] "a" or "b"
+      # @param by [String]
+      # @param root [String] the project root, where `.openlanes.yml` lives
+      # @param at [Time]
+      # @return [Symbol, nil] the quality chosen; nil when the question was not open
+      # @raise [ArgumentError] on a letter that is not one of {CHOICES}
+      def answer!(plan_dir, letter, by:, root:, at: Clock::System.now)
+        choice = CHOICES.find { it.letter == letter.to_s.downcase } or
+          raise ArgumentError, "#{letter} is not one of #{CHOICES.map { "#{it.letter})" }.join(", ")}"
+        Plans::PlanState.for(plan_dir).settle_quality_ask!(answer: choice.quality, by:, at:) or return nil
+
+        write_key(root, choice.quality)
+        choice.quality
+      end
+
+      # Appended rather than rewritten through {Config#to_yaml}, which
+      # would drop the comments a person keeps in the file.
+      #
+      # @return [void]
+      def write_key(root, quality)
+        path = File.join(root, Config::FILE)
+        return unless Config.load(root).quality_unset?
+
+        text = File.file?(path) ? File.read(path, encoding: "UTF-8") : ""
+        text += "\n" unless text.empty? || text.end_with?("\n")
+        File.write(path, "#{text}desired_codebase_quality: #{quality}\n")
+      end
+    end
+  end
+end