agentilda 1.0.3 → 2.0.1

data/lib/agentilda/resync.rb

@@ -15,15 +15,21 @@ module Agentilda
     #   folder whose status already holds is left alone, which is what stops
     #   ⭕️ Blocked and 🅱️ Product Blocked — deliberately identical invariants,
     #   distinguished only by the name — from collapsing into one.
-    # - **The number is not in `NNN.MM` form** — a folder written `018-⚪️--foo`
-    #   before the padding rule, or `18.1-⚪️--foo` by hand. These read fine and
-    #   sort wrong, which is the whole reason the rule exists: `018.09` <
-    #   `018.1` < `018.10` puts a single mixed-width folder in the middle of
-    #   the range. Both are renamed to `018.00-⚪️--foo` and `018.01-⚪️--foo`.
+    # - **The spelling is not canonical** — a folder written `018-⚪️--foo`
+    #   before the `NNN.MM` padding rule or the ` → ` separator, or
+    #   `18.1-⚪️--foo` by hand. Unpadded numbers read fine and sort wrong —
+    #   `018.09` < `018.1` < `018.10` puts a single mixed-width folder in the
+    #   middle of the range. Both are renamed, to `018.00-⚪️ → foo` and
+    #   `018.01-⚪️ → foo`.
     #
-    # The two cases collapse into one rule — **rename any folder that is not
-    # already named what it should be named** — which is why the emoji fix and
-    # the renumber cannot disagree about the target.
+    # The repairs are applied in that order reversed, as **up to two renames
+    # per folder**: first the spelling, under the status the folder already
+    # claims — which is how a `--`-era folder migrates to the ` → ` form —
+    # and only then the status its contents justify. Both renames aim at
+    # {Feature.plan_dirname}, so they cannot disagree about the final name;
+    # splitting them keeps each auditable on its own, instead of one report
+    # line where a spelling migration also appears to have opinions about
+    # the state of the work.
     class Dirs
       # A proposed rename.
       #
@@ -40,22 +46,41 @@ module Agentilda
       # @!attribute [r] reason
       #   @return [String] why the current name is wrong
       Change = Data.define(:dirname, :from, :to, :source, :target, :reason) do
-        # @return [String] a single auditable line
-        def to_s = "#{dirname} → #{File.basename(target)}  (#{reason})"
+        # @return [String] a single auditable line — `⇒` rather than `→`,
+        #   which the folder names themselves now contain
+        def to_s = "#{dirname} ⇒ #{File.basename(target)}  (#{reason})"
       end
 
+      # The state a folder's contents justify, or the one it claims when
+      # nothing fits. What a rename moves toward, and what the dispatcher
+      # reads on a dry run, which renames nothing, so the preview still
+      # names the agents a real run would start.
+      #
+      # @param subject [Agentilda::Subject]
+      # @return [Agentilda::Status]
+      def self.target(subject) = subject.best_fit || subject.status
+
       # @param tree [Agentilda::Tree]
-      def initialize(tree:)
+      # @param except [Array<String>] ordinals to leave alone however wrong
+      #   their names are: the dispatcher passes the plans an agent is
+      #   working in right now
+      def initialize(tree:, except: [])
         @tree = tree
+        @except = except.map(&:to_s)
       end
 
       # @return [Agentilda::Tree]
       attr_reader :tree
 
-      # What would change, without changing anything.
+      # What would change, without changing anything. A folder can appear
+      # twice: its spelling migration first, then its status correction.
       #
       # @return [Array<Agentilda::Resync::Dirs::Change>]
-      def plan = tree.subjects.filter_map { |subject| change_for(subject) }
+      def plan
+        tree.subjects.flat_map do |subject|
+          @except.include?(subject.feature.ordinal.to_s) ? [] : changes_for(subject)
+        end
+      end
 
       # @param commit [Boolean] actually rename
       # @return [Array<Agentilda::Resync::Dirs::Change>] what was proposed
@@ -71,48 +96,70 @@ module Agentilda
       private
 
       # A folder moves when the name it has is not the name it should have.
-      #
-      # `best_fit` answers "which state do these contents justify", and falls
-      # back to the state already claimed when nothing fits — so a folder with
-      # an unreadable set of contents still gets its number padded rather than
-      # being skipped for a reason that has nothing to do with its number.
-      #
-      # Invariants are minimum requirements, so a ⚪️ folder that has grown a
-      # `plan.md` still satisfies ⚪️ and is ⭐️ anyway.
+      # {target} says what that name is; this says how to get there, as up
+      # to two renames applied in order. The status rename starts from where
+      # the spelling rename left the folder, not from where it stands now,
+      # so committing the steps sequentially never renames a path that has
+      # already moved out from under it.
       #
       # @param subject [Agentilda::Subject]
-      # @return [Agentilda::Resync::Dirs::Change, nil]
-      def change_for(subject)
+      # @return [Array<Agentilda::Resync::Dirs::Change>] empty when the name
+      #   is already right
+      def changes_for(subject)
         feature = subject.feature
-        fit = subject.best_fit || subject.status
-        dirname = feature.dirname_as(fit)
-        return nil if dirname == feature.dirname
+        fit = self.class.target(subject)
+        steps = []
+
+        spelled = feature.dirname_as(subject.status)
+        if spelled != feature.dirname
+          steps << step(feature,
+            from:   subject.status,
+            to:     subject.status,
+            source: feature.path,
+            reason: spelling_reason(feature))
+        end
 
+        if fit.key != subject.status.key
+          source = steps.empty? ? feature.path : steps.last.target
+          steps << step(feature,
+            from:   subject.status,
+            to:     fit,
+            source:,
+            reason: subject.violation || "contents now justify #{fit.label}")
+        end
+
+        steps
+      end
+
+      # @param feature [Agentilda::Feature]
+      # @param from [Agentilda::Status]
+      # @param to [Agentilda::Status]
+      # @param source [String] absolute path the rename starts from
+      # @param reason [String]
+      # @return [Agentilda::Resync::Dirs::Change]
+      def step(feature, from:, to:, source:, reason:)
         Change.new(
-          dirname: feature.dirname,
-          from: subject.status.key,
-          to: fit.key,
-          source: feature.path,
-          target: File.join(File.dirname(feature.path), dirname),
-          reason: reason_for(subject, fit)
+          dirname: File.basename(source),
+          from:    from.key,
+          to:      to.key,
+          source:,
+          target:  File.join(File.dirname(feature.path), feature.dirname_as(to)),
+          reason:
         )
       end
 
-      # @param subject [Agentilda::Subject]
-      # @param fit [Agentilda::Status] the state the folder is moving to
-      # @return [String] why the current name is wrong
-      def reason_for(subject, fit)
-        feature = subject.feature
-        return subject.violation || "contents now justify #{fit.label}" unless fit.key == subject.status.key
+      # @param feature [Agentilda::Feature]
+      # @return [String] why the spelling is wrong, status aside
+      def spelling_reason(feature)
         return "#{feature.dirname_ordinal} is not padded to #{feature.ordinal}" unless feature.padded?
 
-        "name is not in canonical NNN.MM-<emoji>--<slug> form"
+        "name is not in canonical NNN.MM-<emoji> → <slug> form"
       end
 
       # A rename that finds its target occupied has not happened, and saying
       # nothing about it would leave the folder misnamed with a report
       # claiming otherwise. Two folders can want the same canonical name —
-      # `018-⚪️--foo` and `018.00-⚪️--foo` are the same plan written twice.
+      # `018-⚪️--foo` and `018.00-⚪️ → foo` are the same plan written twice.
       #
       # @param change [Agentilda::Resync::Dirs::Change]
       # @return [void]
@@ -236,10 +283,14 @@ module Agentilda
       # @param pull [Hash]
       # @return [Agentilda::Resync::Prs::Change]
       def restamped(pull)
-        Change.new(number: pull[:number], title: pull[:title], ordinal: nil, ambiguous: false,
+        Change.new(number: pull[:number],
+          title: pull[:title],
+          ordinal: nil,
+          ambiguous: false,
           new_title: pull[:title].sub(STALE, "[#{Agentilda::NO_PLAN_PREFIX}] "),
           reason: "the no-plan marker is now [#{Agentilda::NO_PLAN_PREFIX}]",
-          assumed: false, adopted: false)
+          assumed: false,
+          adopted: false)
       end
 
       # @param pulls [Array<Hash>]
@@ -261,7 +312,7 @@ module Agentilda
         adoptees = create ? adoption.call(pulls) : adoption.plan(pulls)
         by_number = adoptees.to_h { |a| [a.pull[:number], a] }
 
-        changes.map { |c| (c.ambiguous? && by_number[c.number]) ? adopted(c, by_number[c.number]) : c }
+        changes.map { |c| c.ambiguous? && by_number[c.number] ? adopted(c, by_number[c.number]) : c }
       end
 
       # @return [Hash{Integer => Hash}]
@@ -272,11 +323,11 @@ module Agentilda
       # @return [Agentilda::Resync::Prs::Change]
       def adopted(change, adoptee)
         change.with(
-          ordinal: adoptee.ordinal,
+          ordinal:   adoptee.ordinal,
           new_title: "#{adoptee.ordinal.to_prefix} #{change.title}",
-          reason: "#{change.reason} — adopted into #{adoptee.dirname}",
+          reason:    "#{change.reason} — adopted into #{adoptee.dirname}",
           ambiguous: false,
-          adopted: true
+          adopted:   true
         )
       end
 
@@ -331,8 +382,14 @@ module Agentilda
       # @param why [String]
       # @return [Agentilda::Resync::Prs::Change]
       def resolved(pull, ordinal, why)
-        Change.new(number: pull[:number], title: pull[:title], ordinal:, reason: why,
-          new_title: "#{ordinal.to_prefix} #{pull[:title]}", ambiguous: false, assumed: false, adopted: false)
+        Change.new(number: pull[:number],
+          title: pull[:title],
+          ordinal:,
+          reason: why,
+          new_title: "#{ordinal.to_prefix} #{pull[:title]}",
+          ambiguous: false,
+          assumed: false,
+          adopted: false)
       end
 
       # Nothing resolved, so this is developer work — but that is an assertion
@@ -341,17 +398,28 @@ module Agentilda
       # @param pull [Hash]
       # @return [Agentilda::Resync::Prs::Change]
       def no_plan(pull)
-        Change.new(number: pull[:number], title: pull[:title], ordinal: nil,
+        Change.new(number: pull[:number],
+          title: pull[:title],
+          ordinal: nil,
           new_title: "[#{Agentilda::NO_PLAN_PREFIX}] #{pull[:title]}",
-          reason: "no plan resolved from the branch or the diff", ambiguous: false, assumed: true, adopted: false)
+          reason: "no plan resolved from the branch or the diff",
+          ambiguous: false,
+          assumed: true,
+          adopted: false)
       end
 
       # @param pull [Hash]
       # @param why [String]
       # @return [Agentilda::Resync::Prs::Change]
       def flag(pull, why)
-        Change.new(number: pull[:number], title: pull[:title], new_title: nil, ordinal: nil,
-          reason: why, ambiguous: true, assumed: false, adopted: false)
+        Change.new(number: pull[:number],
+          title: pull[:title],
+          new_title: nil,
+          ordinal: nil,
+          reason: why,
+          ambiguous: true,
+          assumed: false,
+          adopted: false)
       end
     end
   end

data/lib/agentilda/roster.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "agentilda/status"
+require "agentilda/state_machine"
+
 module Agentilda
   # `agentilda agents` — who the specialists are and what each is offered
   # work from. Reading one in full is {Viewer}'s job: the definition file is
@@ -21,6 +24,11 @@ module Agentilda
     # `run` never offers it work.
     READ_ONLY = "read-only"
 
+    # What an agent that handles only {StateMachine::SETTLED} states advances
+    # to. `run` never starts it; a command does, and `resync` then names the
+    # folder by what its files justify.
+    BY_CONTENTS = "by contents"
+
     # @param agents [Agentilda::Agents]
     def initialize(agents: Agents.new)
       @agents = agents
@@ -29,26 +37,33 @@ module Agentilda
     # @return [Agentilda::Agents]
     attr_reader :agents
 
-    # One line per agent, in name order.
+    # One row per agent, in name order, framed by {UI.table}.
     #
     # @return [String] newline-terminated
     def list
       all = agents.all
       return "No agent definitions in #{agents.dir}\n" if all.empty?
 
-      [header(all), *all.map { |agent| row(agent, all) }].join("\n") + "\n"
+      UI.table(all.map { |agent| row(agent) }, header: HEADINGS)
     end
 
     private
 
-    # A state as the folder names write it, so what an agent handles reads the
-    # same here as it does in `status` and on disk.
+    # A state as its words alone, deliberately without the emoji that every
+    # other rendering of a state carries. The table widget pads a cell to a
+    # width it measures in characters, while the terminal draws a status emoji
+    # in two cells; the variation-selector ones (⭕️ 🅱️ ⚪️ ⭐️ 🕰️) are two
+    # characters drawn in two cells, so no single count is right for all of
+    # them. A row carrying one lands short or long and the frame stops lining
+    # up. The label says the same thing unambiguously, and is worth more than
+    # the emoji is. {Reporter} lays its own columns out with {UI.fit} and so
+    # keeps the emoji.
     #
     # @param key [Symbol]
     # @return [String]
     def state(key)
       status = STATUS_BY_KEY[key] or return key.to_s
-      "#{status.emoji} #{status.label}"
+      status.label
     end
 
     # @param agent [Agentilda::Agent]
@@ -57,54 +72,22 @@ module Agentilda
 
     # @param agent [Agentilda::Agent]
     # @return [String]
-    def advances(agent) = agent.advances_to ? state(agent.advances_to) : READ_ONLY
+    def advances(agent)
+      return state(agent.advances_to) if agent.advances_to
+      return BY_CONTENTS if agent.handles.any? && agent.handles.all? { |key| StateMachine::SETTLED.include?(key) }
 
-    # @param all [Array<Agentilda::Agent>]
-    # @return [Integer]
-    def name_width(all) = @name_width ||= all.map { |a| UI.display_width(a.name) }.max.to_i + 2
-
-    # @param all [Array<Agentilda::Agent>]
-    # @return [Integer]
-    def handles_width(all)
-      @handles_width ||= (all.map { |a| UI.display_width(handles(a)) } + [UI.display_width(HEADINGS[1])]).max.to_i + 2
+      READ_ONLY
     end
 
-    # @param all [Array<Agentilda::Agent>]
-    # @return [Integer]
-    def advances_width(all)
-      @advances_width ||= (all.map { |a| UI.display_width(advances(a)) } + [UI.display_width(HEADINGS[2])]).max.to_i + 2
-    end
-
-    # Cells arrive fitted and then painted, in that order: escape codes count
-    # toward a string's length, so padding a coloured string pads it to a width
-    # of which several characters are invisible. See {Reporter#row}.
+    # The widget measures and pads the cells, so they arrive painted only.
     #
-    # @return [String]
-    def line(name, handled, advances, model)
-      format("  %s %s %s %s", name, handled, advances, model).rstrip
-    end
-
-    # @param all [Array<Agentilda::Agent>]
-    # @return [String]
-    def header(all)
-      text = line(UI.fit(HEADINGS[0], name_width(all)),
-        UI.fit(HEADINGS[1], handles_width(all)),
-        UI.fit(HEADINGS[2], advances_width(all)),
-        HEADINGS[3])
-
-      rule = "  " + ("─" * (UI.display_width(text) - 2))
-
-      [UI.paint(text, :bold), UI.paint(rule, :bright_yellow)].join("\n")
-    end
-
     # @param agent [Agentilda::Agent]
-    # @param all [Array<Agentilda::Agent>]
-    # @return [String]
-    def row(agent, all)
-      line(UI.paint(UI.fit(agent.name, name_width(all)), :bright_cyan),
-        UI.fit(handles(agent), handles_width(all)),
-        UI.paint(UI.fit(advances(agent), advances_width(all)), agent.read_only? ? :bright_black : :green),
-        UI.paint(agent.model.to_s, :bright_black))
+    # @return [Array<String>] one cell per entry in {HEADINGS}
+    def row(agent)
+      [UI.paint(agent.name, :bright_cyan),
+       handles(agent),
+       UI.paint(advances(agent), agent.read_only? ? :bright_black : :green),
+       UI.paint(agent.model.to_s, :bright_black)]
     end
   end
 end