openlanes 3.0.0

data/lib/openlanes/plans/ordinal.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # A plan's number, and therefore its identity. Set once when the folder is
+    # created and never changed: branch names, pull request titles and every
+    # `pull-requests.md` join on it, and renumbering breaks all of them silently.
+    #
+    # Always rendered `NNN.MM`. `002.00` is an ordinary plan, specified before it
+    # was built. `002.01` is retroactive — work that shipped between 002 and 003
+    # and was documented afterwards. The decimal marks a **sibling**, not
+    # containment: 002.01 is not part of 002.
+    #
+    # `000` is where the sequence starts, so the first plan of a project is
+    # `000.00`. It also absorbs the older meaning — work that predates the plan
+    # discipline — since either way it sorts first, which is where it belongs.
+    #
+    # @!attribute [r] major
+    #   @return [Integer] 0..999
+    # @!attribute [r] minor
+    #   @return [Integer] 0..99; zero for an ordinary plan
+    class Ordinal < Data.define(:major, :minor)
+      include Comparable
+
+      # The canonical form, plus the bare `NNN` that trees written before this
+      # rule still use and must remain readable.
+      PATTERN = /\A(\d{1,3})(?:\.(\d{1,2}))?\z/
+
+      # The most retroactive slots a single gap can hold.
+      MAX_MINOR = 99
+
+      # @param text [String, nil] e.g. "3", "003", "003.00", "018.01"
+      # @return [OpenLanes::Plans::Ordinal, nil] nil when it is not a plan number
+      def self.parse(text)
+        m = PATTERN.match(text.to_s.strip)
+        m && new(major: m[1].to_i, minor: m[2].to_i)
+      end
+
+      # Pull the number off the front of a folder name.
+      #
+      # @param dirname [String] e.g. "018.01-✅--verify-against-filed-returns"
+      # @return [OpenLanes::Plans::Ordinal, nil]
+      def self.from_dirname(dirname) = parse(dirname.to_s[/\A[\d.]+/])
+
+      # The next ordinary plan after everything in +existing+.
+      #
+      # The first plan in an empty tree is `000.00`, not `001.00`: the sequence
+      # counts from zero so that the very first specification — usually the
+      # project's own — sorts above everything and needs no gap reserved for it.
+      #
+      # @param existing [Array<OpenLanes::Plans::Ordinal>]
+      # @return [OpenLanes::Plans::Ordinal]
+      def self.next_major(existing)
+        return new(major: 0, minor: 0) if existing.empty?
+
+        new(major: existing.map(&:major).max + 1, minor: 0)
+      end
+
+      # The next retroactive slot in the gap after +major+.
+      #
+      # @param existing [Array<OpenLanes::Plans::Ordinal>]
+      # @param major [Integer] the plan the work landed after
+      # @return [OpenLanes::Plans::Ordinal]
+      # @raise [OpenLanes::Error] when the gap is full
+      def self.next_minor(existing, major:)
+        taken = existing.select { |o| o.major == major }.map(&:minor).max || 0
+        if taken >= MAX_MINOR
+          raise Error, "all #{MAX_MINOR} retroactive slots after #{format("%03d", major)} are taken"
+        end
+
+        new(major:, minor: taken + 1)
+      end
+
+      # @return [Boolean] whether this plan was documented after the fact
+      def retroactive? = minor.positive?
+
+      # @return [String] the canonical `NNN.MM`
+      def to_s = format("%03d.%02d", major, minor)
+
+      # @return [String] what a pull request title carries
+      def to_prefix = "[#{self}]"
+
+      # @param other [Object]
+      # @return [Integer, nil]
+      def <=>(other)
+        return nil unless other.is_a?(self.class)
+
+        [major, minor] <=> [other.major, other.minor]
+      end
+    end
+  end
+end

data/lib/openlanes/plans/plan_state.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "socket"
+require "time"
+require "tmpdir"
+
+module OpenLanes
+  module Plans
+    # `state.json` in a plan folder: what has happened to this plan, in a form
+    # a program can read without parsing prose.
+    #
+    # Three kinds of record live here, written by three kinds of writer:
+    #
+    #   stages      the harness: one per agent per round, Started when it is
+    #               dispatched and settled when it returns, with the adapter,
+    #               model, effort, tokens and seconds it ran on
+    #   signatures  the agents, through `openlanes state sign`: the ledger
+    #               lines they used to append to plan.md and spec.md
+    #   messages    the agents, through `openlanes mail send`: what a pair
+    #               says to each other, and the RESUME notes an interrupted
+    #               agent leaves for its successor
+    #
+    # A stage still Started whose harness process is gone is a crash, which is
+    # how a restarted run finds what it has to resume.
+    #
+    # The folder name stays the source of truth for the plan's state; `state`
+    # here is the last state the harness moved the folder to, kept so the file
+    # is readable on its own.
+    #
+    # Every write takes a lock, re-reads, changes, and renames a temporary file
+    # over the old one, so two agents signing in the same second cannot lose
+    # each other's line, and a reader never sees half a file. The lock lives in
+    # the system temp dir, keyed by the plan's number, because the folder it
+    # protects is renamed under it as the plan moves.
+    class PlanState
+      FILENAME = "state.json"
+
+      # Bumped when a field changes meaning. Readers accept older versions.
+      VERSION = 1
+
+      # Where the schema is published, so an editor can validate the file.
+      SCHEMA_ID = "https://github.com/kigster/openlanes/blob/main/schemas/plan-state.schema.json"
+
+      # The schema in this checkout.
+      SCHEMA_PATH = File.expand_path("../../../schemas/plan-state.schema.json", __dir__)
+
+      # @param dir [String] a plan folder
+      # @return [OpenLanes::Plans::PlanState]
+      def self.for(dir) = new(dir:)
+
+      # @param dir [String] a plan folder
+      def initialize(dir:)
+        @dir = dir
+      end
+
+      # @return [String]
+      attr_reader :dir
+
+      # @return [String]
+      def path = File.join(dir, FILENAME)
+
+      # @return [Boolean]
+      def exist? = File.file?(path)
+
+      # The whole document, or a fresh one when there is none yet.
+      #
+      # @return [Hash]
+      def read
+        return skeleton unless exist?
+
+        data = JSON.parse(File.read(path, encoding: "UTF-8"))
+        data.is_a?(Hash) ? skeleton.merge(data) : skeleton
+      rescue JSON::ParserError => e
+        raise Error, "#{path} is not valid JSON: #{e.message.lines.first.strip}"
+      end
+
+      # Change the document under the lock and write it back atomically.
+      #
+      # @yieldparam data [Hash] mutate in place
+      # @return [Hash] what was written
+      def update
+        locked do
+          data = read
+          yield data
+          data["plan"] = identity
+          data["updated_at"] = Time.now.iso8601
+          write(data)
+          data
+        end
+      end
+
+      # @return [Array<Hash>]
+      def stages = read["stages"]
+
+      # @return [Array<Hash>]
+      def signatures = read["signatures"]
+
+      # @return [Array<Hash>]
+      def messages = read["messages"]
+
+      # @return [String, nil]
+      def state = read["state"]
+
+      # ---- the harness --------------------------------------------------------
+
+      # Record or update one agent's round. A second call for the same agent
+      # and round updates the first, so a round is one record from dispatch
+      # to settlement.
+      #
+      # @param agent [String]
+      # @param round [Integer]
+      # @param fields [Hash] status, started_at, finished_at, adapter, model,
+      #   effort, up, down, seconds, note, to, run
+      # @return [Hash] the stage as written
+      def stage!(agent:, round:, **fields)
+        stage = nil
+        update do |data|
+          stage = data["stages"].find { |s| s["agent"] == agent && s["round"] == round }
+          unless stage
+            stage = { "agent" => agent, "round" => round }
+            data["stages"] << stage
+          end
+          stage.merge!(fields.transform_keys(&:to_s).compact)
+        end
+        stage
+      end
+
+      # @param key [Symbol, String] the state the folder was just moved to
+      # @return [void]
+      def state!(key)
+        update { |data| data["state"] = key.to_s }
+      end
+
+      # Stages a dead harness left Started. Nobody is working them, and nobody
+      # will finish them unless a run picks them up.
+      #
+      # @param alive [Proc] pid → Boolean
+      # @param pid [Integer] this run, which is never its own crash
+      # @return [Array<Hash>]
+      def stranded(alive: method(:alive?), pid: Process.pid)
+        stages.select do |s|
+          run = s["run"] || {}
+          s["status"] == "Started" && run["pid"] != pid && run["host"] == Socket.gethostname && !alive.call(run["pid"])
+        end
+      end
+
+      # ---- the agents -------------------------------------------------------
+
+      # One ledger line, in JSON. What `openlanes state sign` writes.
+      #
+      # @param agent [String]
+      # @param round [Integer]
+      # @param status [String] one of {Ledger::STATUSES}
+      # @param note [String, nil]
+      # @param next_agent [String, nil] only after Completed
+      # @param at [Time]
+      # @return [Hash] the signature as written
+      # @raise [OpenLanes::Error] for a status outside the ledger's vocabulary,
+      #   or a handoff after anything but Completed
+      def sign!(agent:, round:, status:, note: nil, next_agent: nil, at: Time.now)
+        raise Error, "status must be one of #{Ledger::STATUSES.join(", ")}" unless Ledger::STATUSES.include?(status)
+        raise Error, "only a Completed signature may name who is next" if next_agent && status != "Completed"
+        raise Error, "a signature needs an agent name" unless agent.to_s.match?(/\A[\w-]+\z/)
+
+        signature = { "at" => at.iso8601, "agent" => agent, "status" => status, "round" => Integer(round),
+                      "note" => note, "next" => next_agent }.compact
+        update { |data| data["signatures"] << signature }
+        signature
+      end
+
+      # Append one message and give it the next number.
+      #
+      # @param from [String]
+      # @param to [String]
+      # @param body [String]
+      # @param at [Time]
+      # @param after [Integer] numbers already taken elsewhere, so a plan
+      #   whose older messages are in mailbox.md keeps counting from there
+      # @param command [String, nil] the id of the page's command that sent
+      #   it. A command is applied at least once (W13), so a second append
+      #   under the same id, to the same reader, returns the first and adds
+      #   nothing: an engine that died between the append and recording the
+      #   reply does not say the same thing twice.
+      # @return [Hash]
+      def message!(from:, to:, body:, at: Time.now, after: 0, command: nil)
+        message = nil
+        update do |data|
+          message = command && data["messages"].find { |m| m["command"] == command && m["to"] == to }
+          next if message
+
+          number = [data["messages"].map { |m| m["number"] }.max.to_i, after].max + 1
+          message = { "number" => number, "at" => at.iso8601, "from" => from, "to" => to, "body" => body }
+          message["command"] = command if command
+          data["messages"] << message
+        end
+        message
+      end
+
+      # The signatures as ledger entries, so the dispatcher reads them exactly
+      # as it reads a line in plan.md. Each signature takes two line numbers,
+      # the entry and its handoff, so {Ledger.handoff_after} pairs them.
+      #
+      # @return [OpenLanes::Plans::Ledger::Reading]
+      def ledger
+        entries = []
+        handoffs = []
+        signatures.each_with_index do |sig, index|
+          at = parse_time(sig["at"])
+          line = (index * 2) + 1
+          entries << Ledger::Entry.new(at:,
+            agent: sig["agent"],
+            status: sig["status"],
+            round: sig["round"].to_i,
+            note: sig["note"],
+            file: FILENAME,
+            line:)
+          handoffs << Ledger::Handoff.new(at:, next: sig["next"], file: FILENAME, line: line + 1) if sig["next"]
+        end
+        Ledger::Reading.new(entries:, handoffs:, problems: [])
+      end
+
+      private
+
+      # @return [Hash]
+      def skeleton
+        { "$schema" => SCHEMA_ID, "version" => VERSION, "plan" => identity, "state" => nil,
+          "updated_at" => nil, "stages" => [], "signatures" => [], "messages" => [] }
+      end
+
+      # The plan's number and slug, from the folder name it has right now.
+      #
+      # @return [Hash]
+      def identity
+        feature = Feature.parse(dir)
+        feature ? { "ordinal" => feature.ordinal.to_s, "slug" => feature.slug } : { "ordinal" => nil, "slug" => File.basename(dir) }
+      end
+
+      # @param data [Hash]
+      # @return [void]
+      def write(data)
+        tmp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+        File.write(tmp, "#{JSON.pretty_generate(data)}\n")
+        File.rename(tmp, path)
+      ensure
+        FileUtils.rm_f(tmp) if tmp && File.exist?(tmp)
+      end
+
+      # @return [Object] the block's value
+      def locked
+        lock = File.join(Dir.tmpdir, "openlanes-plan-#{lock_key}.lock")
+        File.open(lock, File::RDWR | File::CREAT, 0o644) do |f|
+          f.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      # The plans directory and the plan's number: stable while the folder's
+      # name changes underneath.
+      #
+      # @return [String]
+      def lock_key
+        plans = File.expand_path(File.dirname(dir))
+        Digest::SHA256.hexdigest("#{plans}\0#{identity["ordinal"] || File.basename(dir)}")[0, 16]
+      end
+
+      # @param text [String, nil]
+      # @return [Time]
+      def parse_time(text)
+        Time.iso8601(text.to_s)
+      rescue ArgumentError
+        Time.at(0)
+      end
+
+      # @param pid [Integer, nil]
+      # @return [Boolean]
+      def alive?(pid)
+        return false unless pid.is_a?(Integer) && pid.positive?
+
+        Process.kill(0, pid)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+    end
+  end
+end

data/lib/openlanes/plans/pull_request.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # One row of a plan's `pull-requests.md`.
+    #
+    # @!attribute [r] number
+    #   @return [String, nil] as written, without the `#`
+    # @!attribute [r] title
+    #   @return [String]
+    # @!attribute [r] url
+    #   @return [String, nil]
+    # @!attribute [r] state
+    #   @return [String] normalised words plus emoji, e.g. "Open 🟡"
+    PullRequest = Data.define(:number, :title, :url, :state) do
+      # Still awaiting a decision. A closed-unmerged pull request is finished
+      # business, so it is neither open nor merged.
+      #
+      # @return [Boolean]
+      def open? = state.match?(/\b(?:open|wip|draft)\b/i)
+
+      # @return [Boolean]
+      def merged? = state.match?(/\bmerged\b/i) && !state.match?(/\bunmerged\b/i)
+
+      # @return [String] "#92 — Send mail through Resend"
+      def label = number ? "##{number} — #{title}" : title
+    end
+  end
+end

data/lib/openlanes/plans/pull_requests.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Plans
+    # Extracts the pull request roll-up from a plan folder.
+    class PullRequests
+      # A markdown link whose text may contain escaped brackets, because every
+      # title this tool writes now opens with `\[NNN.MM\]`. Matching `[^\]]+`
+      # stops at the escaped `]` and loses the URL with it.
+      LINK = /\[((?:\\.|[^\]\\])+)\]\((https?:[^)\s]+)\)/
+
+      # Canonical wording for the states we recognise, most specific first.
+      STATES = [
+        [/\bclosed\b|\bunmerged\b|\babandoned\b/i, "Closed 🔴"],
+        [/\bmerged\b/i, "Merged 🟣"],
+        [/\bdraft\b|\bwip\b/i, "WIP 🟡"],
+        [/\bopen\b/i, "Open 🟡"]
+      ].freeze
+
+      # Filenames that may hold the table.
+      CANDIDATES = %w[pull-requests.md pull_requests.md prs.md].freeze
+
+      # The file this class writes, and the first one it looks for.
+      FILENAME = CANDIDATES.first
+
+      # Render `pull-requests.md` for a set of pull requests fetched from GitHub.
+      #
+      # The table is what {#parse} reads back and what the state machine judges
+      # a folder by. The descriptions below it are for a reader — human or
+      # agent — synthesizing a specification from work that already shipped:
+      # the table says *which* pull requests, the bodies say *what they did*,
+      # and a retroactive `spec.md` cannot be written from numbers alone.
+      #
+      # Prose after the table is ignored by the parser, so the two can coexist
+      # in one file rather than needing a scratch file the folder rules forbid.
+      #
+      # @param prs [Array<Hash>] `{number:, title:, url:, state:, body:}`
+      # @return [String]
+      def self.render(prs)
+        rows = prs.map { |pr|
+          "| #{pr[:number]} | [#{escape(pr[:title])}](#{pr[:url]}) | #{pr[:state]} |"
+        }
+
+        <<~MARKDOWN
+          # Pull Requests
+
+          | Pull Request Number | Pull Request Name | Status |
+          | ------------------: | :---------------- | -----: |
+          #{rows.join("\n")}
+
+          ## What these pull requests did
+
+          #{prs.map { |pr| describe(pr) }.join("\n")}
+        MARKDOWN
+      end
+
+      # The table alone, for splicing into a file that already says other
+      # things: the ledger blocks luke and rey write before a pull request
+      # exists. Rewriting the whole file deleted their signatures.
+      #
+      # @param prs [Array<Hash>]
+      # @return [String] header, rule and rows, newline-terminated
+      def self.table(prs)
+        rows = prs.map { |pr| "| #{pr[:number]} | [#{escape(pr[:title])}](#{pr[:url]}) | #{pr[:state]} |" }
+        ["| Pull Request Number | Pull Request Name | Status |",
+         "| ------------------: | :---------------- | -----: |", *rows].join("\n") + "\n"
+      end
+
+      # Write the table into +path+ without touching anything else there.
+      #
+      # @param path [String]
+      # @param prs [Array<Hash>]
+      # @return [void]
+      def self.upsert(path, prs)
+        return File.write(path, render(prs)) unless File.file?(path)
+
+        lines = File.read(path, encoding: "UTF-8").lines
+        start = lines.index { |l| l.strip.start_with?("|") && lines[lines.index(l) + 1].to_s.strip.start_with?("|") }
+        if start
+          stop = start
+          stop += 1 while lines[stop + 1]&.strip&.start_with?("|")
+          lines[start..stop] = [table(prs)]
+        else
+          at = lines.index { |l| l.start_with?("# ") }
+          insertion = ["\n", table(prs)]
+          at ? lines.insert(at + 1, *insertion) : lines.unshift("# Pull Requests\n", *insertion, "\n")
+        end
+        File.write(path, lines.join)
+      end
+
+      # @param pr [Hash]
+      # @return [String]
+      def self.describe(pr)
+        body = pr[:body].to_s.strip
+        body = "_No description was written on the pull request._" if body.empty?
+
+        <<~MARKDOWN
+          ### ##{pr[:number]} — #{pr[:title]}
+
+          #{pr[:url]}
+
+          #{body}
+        MARKDOWN
+      end
+
+      # Three characters have to survive a round trip through a table cell.
+      #
+      # A `|` ends the cell, and a title containing one is not unusual —
+      # "fix: guard against a || b".
+      #
+      # `[` and `]` are newer and cost more. Every title this tool writes now
+      # opens with a plan number, so the row reads `[[013.00] Ship it](url)` —
+      # and a markdown link whose text starts with `[` does not parse. The
+      # title came back with the URL glued to it and `url` came back nil, which
+      # is not a cosmetic loss: it is every pull request link on the page, and
+      # the attachment on every Linear issue.
+      #
+      # @param text [String]
+      # @return [String]
+      def self.escape(text)
+        text.to_s.gsub(/([\[\]|])/) { "\\#{$1}" }.gsub(/\s+/, " ").strip
+      end
+
+      # @param dir [String] absolute path to the plan folder
+      def initialize(dir:)
+        @dir = dir
+      end
+
+      # @return [Array<OpenLanes::Plans::PullRequest>] possibly empty
+      def all = @all ||= parse
+
+      private
+
+      # @return [String]
+      attr_reader :dir
+
+      # @return [Array<OpenLanes::Plans::PullRequest>]
+      def parse
+        path = CANDIDATES.map { |f| File.join(dir, f) }.find { |p| File.file?(p) }
+        return [] unless path
+
+        text = File.read(path, encoding: "UTF-8")
+        table = pick_table(Markdown.tables(text))
+        return scrape(text) unless table
+
+        rows = table[:rows].filter_map { |cells| row_to_pr(cells, columns(table[:header])) }
+        rows.empty? ? scrape(text) : rows
+      end
+
+      # @param tables [Array<Hash>]
+      # @return [Hash, nil]
+      def pick_table(tables)
+        tables.find { |t|
+          t[:header].any? { |h| h.match?(/pull\s*request|\bpr\b|\A#\z|\Anumber\z/i) } &&
+            t[:rows].any? { |r| r.any? { |c| c.match?(%r{/(?:pull|merge_requests)/\d+}) } }
+        } || tables.find { |t| t[:rows].any? { |r| r.any? { |c| c.match?(%r{/pull/\d+}) } } }
+      end
+
+      # @param header [Array<String>]
+      # @return [Hash{Symbol => Integer, nil}]
+      def columns(header)
+        {
+          number: header.index { |h| h.match?(/number|\A#\z|\Apr\z|\Apr\s*#/i) },
+          title:  header.index { |h| h.match?(/name|title|summary|description|scope/i) },
+          state:  header.index { |h| h.match?(/status|state/i) }
+        }
+      end
+
+      # @param cells [Array<String>]
+      # @param idx [Hash{Symbol => Integer, nil}]
+      # @return [OpenLanes::Plans::PullRequest, nil]
+      def row_to_pr(cells, idx)
+        title_cell = cells[idx[:title] || 1].to_s
+
+        # The title comes from the title column and the URL from wherever it is.
+        # Scanning every cell for the first link and taking both from it reads
+        # `| [#24](...) | Split verified into signed_off |` as an issue called
+        # "#24", because the number column is a link too and comes first.
+        titled = title_cell.match(LINK)
+        link = titled || cells.filter_map { |c| c.match(LINK) }.first
+
+        url = link && link[2]
+        title = titled ? titled[1] : unformat(title_cell)
+        title = title.gsub(/\\([\[\]|\\])/, '\1') # undo the escaping {.render} applies
+        number = cells[idx[:number] || 0].to_s[/\d+/] || url&.[](%r{/(?:pull|merge_requests)/(\d+)}, 1)
+        return nil if title.empty? && url.nil?
+
+        PullRequest.new(number:,
+          url:,
+          title: title.empty? ? "Pull request" : title,
+          state: normalize(cells[idx[:state] || -1].to_s))
+      end
+
+      # When there is no parsable table, scrape bare links so a folder that
+      # plainly has pull requests does not report none.
+      #
+      # @param text [String]
+      # @return [Array<OpenLanes::Plans::PullRequest>]
+      def scrape(text)
+        text.scan(%r{https?://\S+?/(?:pull|merge_requests)/(\d+)}).flatten.uniq.map do |num|
+          PullRequest.new(number: num,
+            title: "Pull request ##{num}",
+            state: "Unknown",
+            url: text[%r{https?://\S+?/(?:pull|merge_requests)/#{num}\b}])
+        end
+      end
+
+      # Strip the markdown a title was wrapped in without eating the title.
+      #
+      # An underscore between letters is not emphasis, it is an identifier —
+      # `signed_off`, `as_of`, `pull_requests`. Removing every underscore turned
+      # "Split verified into signed_off" into "signedoff" on the way to Linear.
+      #
+      # @param cell [String]
+      # @return [String]
+      def unformat(cell)
+        cell.to_s.gsub(/[*`]/, "").sub(/\A_+/, "").sub(/_+\z/, "").strip
+      end
+
+      # @param cell [String]
+      # @return [String]
+      def normalize(cell)
+        STATES.each { |pattern, label| return label if cell.match?(pattern) }
+        stripped = cell.gsub(/[*_`]/, "").strip
+        stripped.empty? ? "Unknown" : stripped
+      end
+    end
+  end
+end