openlanes 3.0.0 → 3.1.0

data/lib/openlanes/lifecycle/unblock_workflow.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Lifecycle
+    # `openlanes unblock NNN…` without the command: resolve the plans named,
+    # refuse the ones that cannot be drained, say what each is waiting on,
+    # hand the rest to the draining agent, and report what moved.
+    #
+    # Deliberately not part of `run`. ⭕ and 🛑 are {Plans::StateMachine::SETTLED},
+    # so the loop never offers a blocked plan to anybody, and that is the
+    # property that makes the state mean anything: the plan waits for a human,
+    # and no agent quietly decides otherwise. Answers arriving is not a fact
+    # the tool can observe, so a human typing the command *is* the signal.
+    class UnblockWorkflow
+      include UI
+      include Dry::Monads[:result]
+
+      # The agent that knows the shape of `blocked.md`.
+      DEFAULT_AGENT = "lando-broker"
+
+      # What each token turned out to be, for whoever has to fix it.
+      PROBLEMS = {
+        missing:     "no plan of that number",
+        not_blocked: "no blocked.md, so there is nothing to drain"
+      }.freeze
+
+      # @param tree [OpenLanes::Plans::Tree]
+      # @param agent [String] the name of the agent that drains
+      # @param root [String, nil] repository root (default: the .plans parent)
+      # @param dry_run [Boolean] invoke no agent, change nothing
+      # @param quiet [Boolean] draw nothing on STDERR
+      def initialize(tree:, agent: DEFAULT_AGENT, root: nil, dry_run: false, quiet: false)
+        @tree = tree
+        @agent = agent
+        @root = root
+        @dry_run = dry_run
+        @quiet = quiet
+      end
+
+      # The deliverable rows go to STDOUT and the progress to STDERR as the
+      # work happens; the answer is the exit status the command ends with.
+      #
+      # @param tokens [Array<String>] the plans named: NNN or NNN.MM
+      # @return [Dry::Monads::Result] Success(Integer) the exit status, or
+      #   Failure({Refusal}) when no agent has the name given
+      def call(tokens)
+        agent = OpenLanes::Agents.registry.find(@agent) or return Failure(unknown_agent)
+
+        unblocker = Lifecycle.unblocker(tree: @tree,
+          agent:,
+          root: @root,
+          commit: !@dry_run,
+          executor: Execution.executor(root: @root || File.dirname(@tree.dir), dry_run: @dry_run))
+        targets = unblocker.resolve(tokens)
+        refused(targets)
+        subjects = targets.select(&:drainable?).map(&:subject)
+        return Success(worst(targets, [])) if subjects.empty?
+
+        credentials unless @dry_run || @quiet
+        preflight(subjects)
+
+        outcomes = Execution.on_interrupt { unblocker.call(subjects) }
+        outcomes.each { |outcome| report(outcome) }
+        footer(outcomes) unless @quiet
+        Success(worst(targets, outcomes))
+      end
+
+      private
+
+      # @return [OpenLanes::Refusal]
+      def unknown_agent
+        known = OpenLanes::Agents.registry.all.map(&:name).join(", ")
+        Refusal.new(message: "No agent called #{@agent}.\n\nKnown: #{known}", status: 65)
+      end
+
+      # @return [void]
+      def credentials
+        notice = Execution.credentials_notice
+        warn(notice) if notice
+      end
+
+      # A number that names no folder, or a folder that was never stopped, is
+      # refused rather than skipped. Whoever typed this believes an answer has
+      # arrived; running against a folder nobody blocked and saying nothing is
+      # how you come back later to a plan nobody touched and no record of why.
+      #
+      # Every bad token is reported, not just the first, because stopping at
+      # the first one hides the rest of the answer.
+      #
+      # @param targets [Array<OpenLanes::Lifecycle::Unblocker::Target>]
+      # @return [void]
+      def refused(targets)
+        problems = targets.reject(&:drainable?)
+        return if problems.empty?
+
+        problems.each do |target|
+          state = target.subject ? target.subject.status.key : "unknown"
+          puts "#{target.token}\t#{state}\t0 open\t#{PROBLEMS.fetch(target.problem)}"
+        end
+        return if @quiet
+
+        error("#{problems.size} of the plans named cannot be drained:\n\n" +
+              problems.map { |t| "  #{t.token} — #{PROBLEMS.fetch(t.problem)}" }.join("\n") +
+              "\n\nThe tree holds: #{@tree.ordinals.join(", ")}")
+      end
+
+      # What each folder is waiting on, said BEFORE the agent is invoked.
+      #
+      # A real run hands the folder to an agent that can take a quarter of an
+      # hour, and until it came back the terminal used to show nothing at
+      # all: a run that had found nothing to do and a run still working
+      # looked exactly alike.
+      #
+      # @param subjects [Array<OpenLanes::Plans::Subject>]
+      # @return [void]
+      def preflight(subjects)
+        return if @quiet
+
+        subjects.each do |subject|
+          questions = Unblocker.questions(subject)
+          answered = questions.count(&:answered)
+          say("#{paint(subject.feature.ordinal.to_s, :bright_black)} #{subject.status.emoji} " \
+              "#{subject.feature.title} — #{summary(questions.size, answered)}")
+          detail(subject, questions)
+        end
+      end
+
+      # @param open [Integer]
+      # @param answered [Integer]
+      # @return [String]
+      def summary(open, answered)
+        return "nothing open" if open.zero?
+
+        "#{open} open, #{answered.zero? ? "none answered yet" : "#{answered} with an answer waiting"}"
+      end
+
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param questions [Array<OpenLanes::Lifecycle::Unblocker::Question>]
+      # @return [void]
+      def detail(subject, questions)
+        if subject.unreadable_block?
+          say("  #{paint("blocked.md names no `## B<n>` question, so nothing here can be drained", :red)}",
+            bullet: " ")
+          say("  #{paint("Number each open question `## B1`, `## B2`, and each answer `## A1`, `## A2`.", :yellow)}",
+            bullet: " ")
+        elsif questions.empty?
+          say("  #{paint("nothing left open", :green)}", bullet: " ")
+        else
+          questions.each { |question| say("  #{paint(question.to_s, :yellow)}", bullet: " ") }
+        end
+      end
+
+      # One plan, after the fact: the deliverable line on STDOUT, and what
+      # changed on STDERR.
+      #
+      # @param outcome [OpenLanes::Lifecycle::Unblocker::Outcome]
+      # @return [void]
+      def report(outcome)
+        moved = movement(outcome)
+        puts "#{outcome.ordinal}\t#{outcome.ok ? outcome.subject.status.key : "failed"}\t" \
+             "#{outcome.after.size} open\t#{moved}\t#{outcome.note}"
+        # A dry run changed nothing, so the preflight above it is still the
+        # whole truth. Printing the same lines again reads as a second pass
+        # that found the same thing, which is not what happened.
+        return if @quiet || @dry_run
+
+        say("#{paint(outcome.ordinal.to_s, :bright_black)} #{outcome.subject.status.emoji} " \
+            "#{outcome.subject.feature.title} — #{paint(moved, outcome.ok ? :green : :red)}")
+        detail(outcome.subject, outcome.after)
+      end
+
+      # What the file says happened, rather than what the agent claims. The
+      # questions are counted off disk on both sides of the run.
+      #
+      # @param outcome [OpenLanes::Lifecycle::Unblocker::Outcome]
+      # @return [String]
+      def movement(outcome)
+        return "failed" unless outcome.ok
+        return "not attempted" if @dry_run
+        return "blocked.md retired" if outcome.cleared?
+        return "nothing folded" if outcome.folded.empty?
+
+        "folded #{outcome.folded.map { |n| "B#{n}" }.join(", ")}"
+      end
+
+      # @param outcomes [Array<OpenLanes::Lifecycle::Unblocker::Outcome>]
+      # @return [void]
+      def footer(outcomes)
+        if @dry_run
+          warn("Dry run: no agent was invoked, and #{outcomes.size} " \
+               "plan#{"s" unless outcomes.size == 1} #{outcomes.size == 1 ? "is" : "are"} unchanged.\n" \
+               "Re-run without --dry-run to fold in whatever has been answered.")
+          return
+        end
+
+        failed = outcomes.reject(&:ok)
+        return error(failed.map { |o| "#{o.ordinal}: #{o.note}" }.join("\n")) unless failed.empty?
+
+        success(tally(outcomes))
+      end
+
+      # @param outcomes [Array<OpenLanes::Lifecycle::Unblocker::Outcome>]
+      # @return [String]
+      def tally(outcomes)
+        cleared = outcomes.count(&:cleared?)
+        folded = outcomes.sum { |o| o.folded.size }
+        waiting = outcomes.sum { |o| o.after.size }
+        text = "#{folded} question#{"s" unless folded == 1} folded in · " \
+               "#{cleared} plan#{"s" unless cleared == 1} out of the block · " \
+               "#{waiting} still waiting on a human."
+        return text unless folded.zero?
+
+        "#{text}\n\nNothing moved. An answer has to be written into blocked.md as its own " \
+          "`## A<n>` section, answering the `## B<n>` of the same number, before " \
+          "there is anything to fold."
+      end
+
+      # The most serious thing that happened, as an exit status. A tree that
+      # was partly drained still exits non-zero when part of it could not be.
+      #
+      # @param targets [Array<OpenLanes::Lifecycle::Unblocker::Target>]
+      # @param outcomes [Array<OpenLanes::Lifecycle::Unblocker::Outcome>]
+      # @return [Integer]
+      def worst(targets, outcomes)
+        problems = targets.map(&:problem)
+        return 66 if problems.include?(:missing)
+        return 65 if problems.include?(:not_blocked)
+        return 1 unless outcomes.all?(&:ok)
+
+        0
+      end
+    end
+  end
+end

data/lib/openlanes/lifecycle/unblocker.rb

@@ -118,7 +118,7 @@ module OpenLanes
       # is as much a thing the user needs told about as a folder that drained, and
       # stopping at the first bad one hides the rest of the report.
       #
-      # The gate is `blocked.md` itself, not the folder's emoji. ⭕️ is *derived*
+      # The gate is `blocked.md` itself, not the folder's emoji. ⭕ is *derived*
       # from the file, so gating on the emoji made the tool circular: a
       # `blocked.md` whose questions are not numbered `## B<n>` never earns the
       # emoji, so `unblock` refused it, so the file could never drain and the
@@ -187,11 +187,85 @@ module OpenLanes
       # @param progress [OpenLanes::UI::Line]
       # @return [Array(Boolean, String)]
       def invoke(subject, progress)
-        @executor.call(agent, subject, root:, &progress)
+        journal_answers(subject)
+        forward = progress.to_proc
+        kept = { written: 0, number: nil }
+        @executor.call(agent, subject, root:) do |update|
+          record_journal(subject, update, kept)
+          forward.call(update)
+        end
       rescue StandardError => e
         [false, "#{e.class}: #{e.message.lines.first.to_s.strip}"]
       end
 
+      # The broker's own journal lines (M2), written as they arrive, the way
+      # {Engine::Dispatcher} writes every other agent's: its prompt asks it to
+      # keep one like any agent's, and neither the run loop nor `openlanes
+      # unblock` hands its progress to the dispatcher. As they arrive, so a
+      # broker that fails or is killed keeps what it said.
+      #
+      # A journal that cannot be written costs the record, never the drain;
+      # the lines stay unwritten for the next update to try again.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @param update [Object] whatever the executor reports
+      # @param kept [Hash] how many lines are written, and the journal round
+      # @return [void]
+      def record_journal(subject, update, kept)
+        lines = update.respond_to?(:journal) ? Array(update.journal) : []
+        return if !applying? || lines.size <= kept[:written]
+
+        entries, rejected = lines[kept[:written]..].partition { it.is_a?(Plans::Journal::Entry) }
+        unless entries.empty?
+          kept[:number], refused = Plans::PlanState.for(subject.feature.path)
+                                                   .journal!(agent: agent.name,
+                                                     entries:,
+                                                     number: kept[:number],
+                                                     state: subject.feature.status)
+          rejected += refused
+        end
+        kept[:written] = lines.size
+        rejected.each { UI.log("journal line ignored, #{it.reason}: #{it.line[0, 160]}", level: :warn, **log_fields(subject)) }
+      rescue SystemCallError, OpenLanes::Error => e
+        UI.log("journal not written yet: #{e.message}", level: :warn, **log_fields(subject))
+      end
+
+      # Every answered question goes into the journal of the agent that asked
+      # it (M3), B1 with A1, before the broker folds it in and deletes it:
+      # afterwards the words are gone from `blocked.md`, and the asker's next
+      # round would know only that the plan was unblocked, not what it was
+      # told. Here, rather than where the page writes an answer, because an
+      # answer typed into the file by hand is drained the same way.
+      #
+      # A journal that cannot be written costs the record, never the drain.
+      #
+      # @param subject [OpenLanes::Plans::Subject]
+      # @return [void]
+      def journal_answers(subject)
+        return unless applying?
+
+        state = Plans::PlanState.for(subject.feature.path)
+        asker = state.blocked_by or return
+        text = subject.read("blocked.md").to_s
+        bodies = Plans::BlockedFile.bodies(text)
+        answers = Plans::BlockedFile.answers(text).transform_values { plain(it) }
+        self.class.questions(subject).each do |question|
+          answer = answers[question.number]
+          next if answer.nil? || answer.empty?
+
+          state.answer!(agent: asker,
+            ref: "B#{question.number}",
+            question: plain("#{question.heading} #{bodies[question.number]}"),
+            answer:)
+        end
+      rescue SystemCallError, OpenLanes::Error => e
+        UI.log("journal not written: #{e.message}", level: :warn, **log_fields(subject))
+      end
+
+      # @param text [String] a block's body
+      # @return [String] one line, without the page's command markers
+      def plain(text) = Plans::Journal.clip(text.gsub(/<!--.*?-->/m, "").split.join(" "))
+
       # The same pass the run loop makes after every round, for the same reason:
       # a drained folder is only *named* differently once something reads the
       # file the agent just deleted.

data/lib/openlanes/lifecycle.rb

@@ -3,7 +3,8 @@
 module OpenLanes
   # Operations that change which plans exist or what they are called:
   # minting a folder, drafting its brief, adopting an orphan pull request,
-  # reconciling names with contents, and draining answered questions.
+  # reconciling names with contents, draining answered questions, and
+  # aging the ones nobody answers.
   module Lifecycle
     module_function
 
@@ -12,6 +13,10 @@ module OpenLanes
     # @return [Dry::Monads::Result] Success(path) or Failure(message)
     def create(dir:, **) = Creator.new(dir:).create(**)
 
+    # @param options [Hash] passed to {CreateWorkflow#initialize}
+    # @return [OpenLanes::Lifecycle::CreateWorkflow] `openlanes create`, without the command
+    def create_plan(**) = CreateWorkflow.new(**)
+
     # @param tree [OpenLanes::Plans::Tree]
     # @return [OpenLanes::Lifecycle::Resync::Dirs]
     def resync_dirs(tree:, **) = Resync::Dirs.new(tree:, **)
@@ -19,10 +24,41 @@ module OpenLanes
     # @return [OpenLanes::Lifecycle::Resync::Prs]
     def resync_prs(**) = Resync::Prs.new(**)
 
+    # `resync prs` as one step: retitle (and adopt) on GitHub, or say why not.
+    #
+    # @param commit [Boolean] false previews and changes nothing
+    # @param options [Hash] passed to {Resync::Prs#initialize}
+    # @return [Dry::Monads::Result] Success(Array<Resync::Prs::Change>), or
+    #   Failure({Refusal}) with status 69 when GitHub refused, or 73 when an
+    #   orphan would be adopted in a linked worktree, where no plan is minted
+    def retitle_prs(commit:, **)
+      Dry::Monads::Result::Success.new(Resync::Prs.new(**).call(commit:))
+    rescue Allocator::Refused => e
+      Dry::Monads::Result::Failure.new(Refusal.new(message: e.message, status: 73))
+    rescue OpenLanes::Error => e
+      Dry::Monads::Result::Failure.new(Refusal.new(message: e.message, status: 69))
+    end
+
     # @return [OpenLanes::Lifecycle::Brief]
     def brief(**) = Brief.new(**)
 
+    # @param options [Hash] passed to {UnblockWorkflow#initialize}
+    # @return [OpenLanes::Lifecycle::UnblockWorkflow] `openlanes unblock`, without the command
+    def unblock(**) = UnblockWorkflow.new(**)
+
     # @return [OpenLanes::Lifecycle::Unblocker]
     def unblocker(**) = Unblocker.new(**)
+
+    # Bomb or defer the blocked plans past their limits (plan 009).
+    #
+    # @param tree [OpenLanes::Plans::Tree]
+    # @param subjects [Array<OpenLanes::Plans::Subject>, nil] nil for every plan
+    # @param since [Date, nil] `plans.aging_since`
+    # @param now [Time]
+    # @param commit [Boolean] false reports and changes nothing
+    # @return [OpenLanes::Lifecycle::Aging::Result]
+    def age(tree:, subjects: nil, since: nil, now: Time.now, commit: true)
+      Aging.new(tree:, since:, now:).call(subjects:, commit:)
+    end
   end
 end

data/lib/openlanes/linear/mapping.rb

@@ -12,7 +12,7 @@ module OpenLanes
     # contract, and the name we would prefer if the team happens to have one.
     # {Push} resolves the name first and falls back to the type.
     #
-    # Several states have no Linear equivalent at all — ⭕️ Technical Block is
+    # Several states have no Linear equivalent at all — ⭕ Technical Block is
     # a reason, not a position in a workflow — so they map to the nearest
     # position and carry a label saying which reason.
     #
@@ -50,11 +50,14 @@ module OpenLanes
       building_ui:        Placement.new(type: "started", name: "In Progress", labels: %w[frontend]),
       ready_for_review:   Placement.new(type: "started", name: "In Review", labels: []),
       in_review:          Placement.new(type: "started", name: "In Review", labels: []),
+      verifying:          Placement.new(type: "started", name: "In Review", labels: []),
+      completed:          Placement.new(type: "started", name: "In Review", labels: %w[ready-to-merge]),
       rejected:           Placement.new(type: "started", name: "In Review", labels: %w[changes-requested]),
       approved:           Placement.new(type: "completed", name: "Done", labels: []),
       deployed:           Placement.new(type: "completed", name: "Done", labels: %w[deployed]),
       blocked:            Placement.new(type: "unstarted", name: "Todo", labels: %w[blocked]),
       product_blocked:    Placement.new(type: "unstarted", name: "Todo", labels: %w[blocked-on-product]),
+      bomb:               Placement.new(type: "unstarted", name: "Todo", labels: %w[blocked bomb]),
       deferred:           Placement.new(type: "backlog", name: "Backlog", labels: %w[deferred]),
       retroactive:        Placement.new(type: "completed", name: "Done", labels: %w[retroactive]),
       discarded:          Placement.new(type: "canceled", name: "Canceled", labels: [])

data/lib/openlanes/linear/unit.rb

@@ -55,7 +55,7 @@ module OpenLanes
       # the moment the work moves.
       GLYPH_NOTE = /\s*\((?:[^\w\s(][^)]*)\)\s*\z/
 
-      # The same thing without the brackets: `… over the law plane ☢️ deferred`.
+      # The same thing without the brackets: `… over the law plane 💤 deferred`.
       TRAILING_GLYPH = /\s*[\u{2190}-\u{2BFF}\u{1F000}-\u{1FAFF}][^\n]*\z/
 
       # A plan number the author typed into the heading as well. The issue for