agentilda 2.0.1 → 2.0.4

data/lib/agentilda/publisher.rb

@@ -1,175 +0,0 @@
-# frozen_string_literal: true
-
-require "tempfile"
-require "tty/command"
-
-module Agentilda
-  # Turns a finished worktree into a pushed branch and a pull request.
-  #
-  # This is the one place the harness reaches off the machine, so it requires
-  # `--commit`, is skipped with `--no-git-push`, and refuses anything
-  # it is not certain about. Everything it does is reported before it does it.
-  #
-  # Titles follow the convention the whole system joins on:
-  #
-  #     [002.00](A) Tenancy Households       — a plan's first pull request
-  #     [002.00](B) Tenancy Households       — its second
-  #
-  # The slug is title-cased from the folder name, so the title reads as a
-  # sentence rather than as a path fragment.
-  class Publisher
-    # A published, or publishable, pull request.
-    #
-    # @!attribute [r] ordinal
-    #   @return [Agentilda::Ordinal]
-    # @!attribute [r] branch
-    #   @return [String]
-    # @!attribute [r] title
-    #   @return [String]
-    # @!attribute [r] url
-    #   @return [String, nil] nil on a dry run or a refusal
-    # @!attribute [r] refusal
-    #   @return [String, nil]
-    Publication = Data.define(:ordinal, :branch, :title, :url, :refusal) do
-      # @return [Boolean]
-      def published? = !url.nil?
-    end
-
-    # A..Z, which is more parts than any feature should be split into.
-    LETTERS = ("A".."Z").to_a.freeze
-
-    # @param root [String] repository the worktree belongs to
-    # @param command [TTY::Command]
-    # @param base [String] the branch pull requests target
-    # @param dry_run [Boolean]
-    def initialize(root:, command: TTY::Command.new(printer: :null), base: "main", dry_run: true)
-      @root = root
-      @command = command
-      @base = base
-      @dry_run = dry_run
-    end
-
-    # Push one plan's branch and open its pull request.
-    #
-    # @param checkout [Agentilda::Worktree::Checkout]
-    # @param subject [Agentilda::Subject]
-    # @param letter [String, nil] force a part letter; nil auto-assigns
-    # @return [Agentilda::Publisher::Publication]
-    def publish(checkout:, subject:, letter: nil)
-      title = title_for(subject, letter)
-
-      unless checkout.dirty?
-        return refuse(subject, checkout, title, "nothing to publish — the worktree is unchanged")
-      end
-
-      return Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: nil) if @dry_run
-
-      commit(checkout, title)
-      push(checkout)
-      url = create_pull_request(checkout, subject, title)
-
-      Publication.new(**base_fields(subject, checkout, title), url:, refusal: nil)
-    rescue TTY::Command::ExitError => e
-      refuse(subject, checkout, title, git_complaint(e))
-    end
-
-    # git and gh put the useful sentence in stderr, several lines below the
-    # command they echo. Reporting only the first line reports "it failed".
-    #
-    # @param error [TTY::Command::ExitError]
-    # @return [String]
-    def git_complaint(error)
-      lines = error.message.lines.map(&:strip).reject(&:empty?)
-      stderr = lines.find { |l| l.start_with?("stderr:") }
-      complaint = stderr&.delete_prefix("stderr:")&.strip
-
-      complaint.to_s.empty? || complaint == "Nothing written" ? lines.first.to_s : complaint
-    end
-
-    # The title a plan's next pull request should carry.
-    #
-    # @param subject [Agentilda::Subject]
-    # @param letter [String, nil]
-    # @return [String]
-    def title_for(subject, letter = nil)
-      "[#{subject.feature.ordinal}](#{letter || auto_letter(subject)}) #{subject.feature.title}"
-    end
-
-    # Which part this is. Always a letter, starting at A: a plan that turns out
-    # to need only one pull request still reads consistently with every other,
-    # and nothing has to be renamed when a second arrives.
-    #
-    # @param subject [Agentilda::Subject]
-    # @return [String]
-    def auto_letter(subject) = LETTERS.fetch(subject.pull_requests.size, LETTERS.last)
-
-    private
-
-    # @return [Hash]
-    def base_fields(subject, checkout, title)
-      { ordinal: subject.feature.ordinal, branch: checkout.branch, title: }
-    end
-
-    # @return [Agentilda::Publisher::Publication]
-    def refuse(subject, checkout, title, why)
-      Publication.new(**base_fields(subject, checkout, title), url: nil, refusal: why)
-    end
-
-    # @param checkout [Agentilda::Worktree::Checkout]
-    # @param title [String]
-    # @return [void]
-    def commit(checkout, title)
-      run(checkout, "git", "add", "-A")
-      # The subject line drops the bracketed prefix: it belongs in the pull
-      # request title, where things join on it, not in every commit message.
-      run(checkout, "git", "commit", "-m", title.sub(/\A\[[^\]]+\](?:\([A-Z]\))?\s*/, ""))
-    end
-
-    # @param checkout [Agentilda::Worktree::Checkout]
-    # @return [void]
-    def push(checkout) = run(checkout, "git", "push", "-u", "origin", checkout.branch)
-
-    # @return [String, nil] the pull request URL
-    def create_pull_request(checkout, subject, title)
-      Tempfile.create(["pr", ".md"]) do |file|
-        file.write(description(subject, title))
-        file.flush
-        result = run(checkout, "gh", "pr", "create", "-a", "@me", "-B", @base, "-t", title, "-F", file.path)
-        return result.out.to_s[%r{https://\S+}]
-      end
-    end
-
-    # The body `/create-pr` would have written: a title line, a summary lifted
-    # from the specification, and a link back to the plan folder so a reviewer
-    # can find the rest.
-    #
-    # @return [String]
-    def description(subject, title)
-      <<~MARKDOWN
-        # #{title}
-
-        ## Summary
-
-        #{summary_text(subject)}
-
-        ## Plan
-
-        Implements `#{subject.feature.dirname}`. The specification and the plan
-        for this work live in that folder.
-      MARKDOWN
-    end
-
-    # The specification's own Goal section, verbatim. A pull request body that
-    # paraphrases the spec is a second copy that drifts; quoting it is not.
-    #
-    # @param subject [Agentilda::Subject]
-    # @return [String]
-    def summary_text(subject)
-      text = subject.goal.join("\n\n")
-      text.empty? ? "See `#{subject.feature.dirname}/spec.md`." : text
-    end
-
-    # @return [TTY::Command::Result]
-    def run(checkout, *argv) = @command.run(*argv, chdir: checkout.path)
-  end
-end

data/lib/agentilda/pull_request.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Agentilda
-  # 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

data/lib/agentilda/pull_requests.rb

@@ -1,230 +0,0 @@
-# frozen_string_literal: true
-
-require "agentilda/markdown"
-require "agentilda/pull_request"
-
-module Agentilda
-  # 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<Agentilda::PullRequest>] possibly empty
-    def all = @all ||= parse
-
-    private
-
-    # @return [String]
-    attr_reader :dir
-
-    # @return [Array<Agentilda::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 [Agentilda::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<Agentilda::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

data/lib/agentilda/reporter.rb

@@ -1,181 +0,0 @@
-# frozen_string_literal: true
-
-require "agentilda/status"
-
-module Agentilda
-  # `/spec-status` — every plan, its state in icon and words, and its pull
-  # requests as clickable links.
-  #
-  # {#render} returns a string and prints nothing. Whoever calls it decides
-  # where it goes, which keeps the table pipeable.
-  class Reporter
-    # Columns, so the header and the rows cannot drift apart.
-    HEADINGS = ["Plan", "⬇", "Status", "Feature", "Pull Requests"].freeze
-
-    # Cells given to the plan number: "018.01" with room to grow.
-    ORDINAL_WIDTH = 7
-
-    # Cells given to a status icon. Emoji vary in both character count and
-    # display width, so the cell is padded to this by {UI.fit} rather than
-    # trusted to be any particular size — see the note there.
-    EMOJI_WIDTH = 2
-
-    # Cells given to a pull request's state, so the URLs line up beneath each
-    # other whichever states the tree happens to contain.
-    STATE_WIDTH = PullRequests::STATES.map { |_, label| UI.display_width(label) }.max
-
-    # @param tree [Agentilda::Tree]
-    def initialize(tree:)
-      @tree = tree
-    end
-
-    # @return [Agentilda::Tree]
-    attr_reader :tree
-
-    # @return [String] the whole table, newline-terminated
-    def render
-      return "No plans found in #{tree.dir}\n" if tree.subjects.empty?
-
-      [header, *tree.subjects.flat_map { |s| rows_for(s) }, "", footer].join("\n") + "\n"
-    end
-
-    # @return [Hash{Symbol => Integer}] how many plans sit in each state
-    def totals
-      tree.subjects.each_with_object(Hash.new(0)) { |s, h| h[s.status.key] += 1 }
-    end
-
-    # Plans whose folder name their contents do not justify.
-    #
-    # @return [Array<Agentilda::Subject>]
-    def inconsistent = tree.subjects.reject(&:consistent?)
-
-    private
-
-    # @return [Integer] widest status label, so the column lines up
-    def label_width = @label_width ||= tree.subjects.map { |s| UI.display_width(s.status.label) }.max.to_i + 4
-
-    # @return [Integer] widest feature name
-    def title_width = @title_width ||= tree.subjects.map { |s| UI.display_width(s.feature.title) }.max.to_i + 2
-
-    # The one place the table's shape is written down. The heading, the plan
-    # rows, the continuation lines and the violations all come through here, so
-    # a column cannot widen in one of them and stay put in the others.
-    #
-    # Cells arrive already fitted and already painted, in that order, because
-    # the order matters: escape codes count toward a string's length, so
-    # padding a coloured string pads it to a width of which several characters
-    # are invisible, and the column collapses by exactly that much.
-    #
-    # @return [String]
-    def row(flag, ordinal, emoji, label, title, tail)
-      format("%s %s  %s %s  %s %s", flag, ordinal, emoji, label, title, tail)
-    end
-
-    # Cell at which the pull requests start, so a plan's second and third pull
-    # requests sit under its first. Measured by running blanks through {#row}
-    # rather than counted by hand, so the indent cannot drift when the layout
-    # changes.
-    #
-    # @return [Integer]
-    def pr_column
-      @pr_column ||= row(" ",
-        " " * ORDINAL_WIDTH,
-        " " * EMOJI_WIDTH,
-        " " * label_width,
-        " " * title_width,
-        "").length
-    end
-
-    # @return [Integer] cell at which the feature name starts
-    def title_column = pr_column - title_width - 1
-
-    # @return [String]
-    def header
-      text = row(" ",
-        UI.fit(HEADINGS[0], ORDINAL_WIDTH),
-        UI.fit(HEADINGS[1], EMOJI_WIDTH),
-        UI.fit(HEADINGS[2], label_width),
-        UI.fit(HEADINGS[3], title_width),
-        HEADINGS[4])
-
-      rule = "  " + ("─" * (UI.display_width(text) - 2))
-
-      [UI.paint(text, :bold), UI.paint(rule, :bright_yellow)].join("\n")
-    end
-
-    # One line per plan, plus a continuation line for each extra pull request
-    # so that every URL is visible and clickable rather than truncated.
-    #
-    # @param subject [Agentilda::Subject]
-    # @return [Array<String>]
-    def rows_for(subject)
-      feature = subject.feature
-      prs = subject.pull_requests
-
-      first = row(
-        subject.consistent? ? " " : UI.paint("!", :red),
-        UI.paint(UI.fit(feature.ordinal.to_s, ORDINAL_WIDTH), :bold),
-        UI.fit(feature.status.emoji, EMOJI_WIDTH),
-        UI.paint(UI.fit(feature.status.label, label_width), :yellow),
-        UI.paint(UI.fit(feature.title, title_width), :blue, :bold),
-        prs.empty? ? UI.paint("[none yet]", :bright_red) : link(prs.first)
-      )
-
-      rest = prs.drop(1).map { |pr| (" " * pr_column) + link(pr) }
-
-      [first, *rest, *violation_line(subject)]
-    end
-
-    # The URL is left bare rather than wrapped in an OSC 8 hyperlink: the table
-    # is as likely to be piped into a file as read in a terminal, and every
-    # terminal worth the name linkifies a bare URL anyway.
-    #
-    # @param pr [Agentilda::PullRequest]
-    # @return [String]
-    def link(pr)
-      colour = state_colour(pr)
-
-      format("#%4s %s %s",
-        pr.number,
-        UI.paint(UI.fit(pr.state, STATE_WIDTH), colour),
-        UI.paint(pr.url.to_s, colour))
-    end
-
-    # @param pr [Agentilda::PullRequest]
-    # @return [Symbol] a pastel style name
-    def state_colour(pr)
-      if pr.merged?
-        :magenta
-      elsif pr.open?
-        :yellow
-      else
-        :blue
-      end
-    end
-
-    # @param subject [Agentilda::Subject]
-    # @return [Array<String>]
-    def violation_line(subject)
-      return [] if subject.consistent?
-
-      [(" " * title_column) + UI.paint("↳ #{subject.violation}", :red)]
-    end
-
-    # @return [String]
-    def footer
-      counts = totals.map { |key, n| "#{STATUS_BY_KEY.fetch(key).emoji} #{n}" }.join("   ")
-      lines = ["  #{tree.subjects.size} #{tree.subjects.size == 1 ? "plan" : "plans"}   #{counts}"]
-
-      unless inconsistent.empty?
-        lines << "  #{UI.paint("#{inconsistent.size} with a status their contents do not justify", :red)}"
-      end
-
-      tree.duplicates.each do |ordinal, dirnames|
-        lines << "  #{UI.paint("#{ordinal} is claimed by #{dirnames.size} folders — a number is an identity:", :red)}"
-        dirnames.each { |d| lines << "    #{UI.paint(d, :bright_black)}" }
-      end
-
-      lines.join("\n")
-    end
-  end
-end