openlanes 3.0.0 → 3.1.0

data/lib/openlanes/support/log.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "semantic_logger"
+
+module OpenLanes
+  # The one place a process sets SemanticLogger up, so the engine and the
+  # control room's server write the same file the same way.
+  #
+  # `openlanes run` and `openlanes start` log as `engine`; the server they
+  # spawn, and `openlanes web` alone, log as `web`. Both append to
+  # `<project root>/log/development.log` unless told otherwise, and the
+  # engine hands its server the file, level and format through {Settings#env},
+  # so a `--log` typed on `run` moves both processes rather than one.
+  #
+  # Two processes share one file safely because each opens it in append mode
+  # and writes a whole line per call: the kernel puts every O_APPEND write at
+  # the end, so lines from the two interleave but never tear. Each line carries
+  # its process id, which is how a reader tells them apart.
+  #
+  # Logging is synchronous. SemanticLogger's default background thread keeps
+  # its queue in memory, and a CLI that exits, is killed by its own run, or is
+  # TERMed by {Web::Launcher#stop} would take the last lines with it.
+  #
+  # @example
+  #   Log.setup(Log::Settings.from(options, root:), name: "engine")
+  #   Log.logger.info("started", plan: "003.00")
+  module Log
+    # Where both processes log unless `--log` says otherwise, relative to the
+    # project root.
+    DEFAULT_FILE = File.join("log", "development.log")
+
+    # `--log -`: the log goes to STDOUT instead of a file.
+    STDOUT_FILE = "-"
+
+    # Lowest first. Anything below the chosen level is not written.
+    LEVELS = %w[debug info warn error fatal].freeze
+
+    # The level a run logs at when nothing says otherwise.
+    DEFAULT_LEVEL = "info"
+
+    # SemanticLogger's colour formatter kept to one line per entry, as
+    # `standard` is: the stock one writes an exception's backtrace over many
+    # lines, which `tail -F` in the mprocs `logs` pane would scatter between
+    # the other process's lines.
+    class OneLineColor < SemanticLogger::Formatters::Color
+      # @return [String, nil]
+      def message = ("-- #{log.message.delete("\n")}" if log.message)
+
+      # @return [String, nil]
+      def exception
+        return unless log.exception
+
+        "-- Exception: #{color}#{log.exception.class}: #{log.exception.message.delete("\n")}#{color_map.clear}"
+      end
+    end
+
+    # `--log-format` to SemanticLogger's formatter. `standard` is the one-line
+    # formatter rather than the default one, which writes a stack trace over
+    # many lines and breaks "one line per entry"; `color` is the same line in
+    # colour, by level, for a person reading the file with `tail -F` or `less -R`.
+    FORMATS = { "color" => OneLineColor, "standard" => :one_line, "json" => :json }.freeze
+
+    # The format a run logs in when nothing says otherwise. Plain, so a log
+    # written in CI or by any project using the gem greps without first
+    # stripping escape codes; `just start` asks for `--log-format color`.
+    DEFAULT_FORMAT = "standard"
+
+    # How the engine tells the server it spawns where to log. The environment
+    # rather than argv, for the same reason as the Redis URL: the server's
+    # command line stays the same whatever the run was told.
+    ENV_FILE = "OPENLANES_LOG"
+    ENV_LEVEL = "OPENLANES_LOG_LEVEL"
+    ENV_FORMAT = "OPENLANES_LOG_FORMAT"
+
+    # The password in a URL's userinfo, wherever the URL sits in a line: a
+    # git or Redis error, or an agent's failure reason, can quote a remote
+    # with its credentials, and the log outlives the run. The same rule as
+    # {Live.mask}, which only looks at a string that is one URL.
+    CREDENTIALS = %r{([a-z][a-z0-9+.-]*://[^:@/\s]*):[^@/\s]+@}i
+
+    # The logger a process uses when {.setup} was never told its name.
+    DEFAULT_NAME = "openlanes"
+
+    # A level or format nobody knows. Raised before anything is opened, so a
+    # typo is a refusal rather than a run that silently logs at the default.
+    class Invalid < ArgumentError; end
+
+    # Where a process logs, at what level, in which format.
+    #
+    # @!attribute [r] file
+    #   @return [String] an absolute path, or {STDOUT_FILE}
+    # @!attribute [r] level
+    #   @return [String] one of {LEVELS}
+    # @!attribute [r] format
+    #   @return [String] one of the keys of {FORMATS}
+    Settings = Data.define(:file, :level, :format) do
+      # Flags first, then the environment the engine handed its server, then
+      # the defaults. A relative file is taken from the project root, not the
+      # directory the command was typed in, so `log/development.log` is the
+      # same file for a run typed three directories down.
+      #
+      # @param options [Hash] the command's options: `:log`, `:log_level`, `:log_format`
+      # @param root [String] the project root
+      # @param env [Hash]
+      # @return [Settings]
+      # @raise [Invalid] for a level or format that is not one of the known ones
+      def self.from(options = {}, root:, env: ENV)
+        pick = ->(key, name) { [options[key], env[name]].map { it.to_s.strip }.find { !it.empty? } }
+        file = pick.call(:log, ENV_FILE) || DEFAULT_FILE
+        level = (pick.call(:log_level, ENV_LEVEL) || DEFAULT_LEVEL).downcase
+        format = (pick.call(:log_format, ENV_FORMAT) || DEFAULT_FORMAT).downcase
+        raise Invalid, "--log-level #{level}: use one of #{LEVELS.join(", ")}" unless LEVELS.include?(level)
+        raise Invalid, "--log-format #{format}: use one of #{FORMATS.keys.join(", ")}" unless FORMATS.key?(format)
+
+        file = File.expand_path(file, root) unless file == STDOUT_FILE
+        new(file:, level:, format:)
+      end
+
+      # @return [Boolean] whether the log goes to STDOUT rather than a file
+      def stdout? = file == STDOUT_FILE
+
+      # @return [Hash{String => String}] for a child process's environment
+      def env = { ENV_FILE => file, ENV_LEVEL => level, ENV_FORMAT => format }
+    end
+
+    class << self
+      # The settings {.setup} was last given, nil before then.
+      #
+      # @return [Settings, nil]
+      attr_reader :settings
+
+      # Point SemanticLogger at the one file (or STDOUT), replacing whatever
+      # it wrote to before, so calling this twice in one process (the suite
+      # does) never leaves two appenders writing every line twice.
+      #
+      # @param settings [Settings]
+      # @param name [String] what this process's lines are signed with,
+      #   `engine` or `web`
+      # @return [Settings]
+      def setup(settings, name: DEFAULT_NAME)
+        SemanticLogger.sync!
+        SemanticLogger.clear_appenders!
+        SemanticLogger.application = "openlanes"
+        SemanticLogger.default_level = settings.level.to_sym
+        formatter = FORMATS.fetch(settings.format)
+        formatter = formatter.new if formatter.is_a?(Class)
+        if settings.stdout?
+          SemanticLogger.add_appender(io: $stdout, formatter:)
+        else
+          FileUtils.mkdir_p(File.dirname(settings.file))
+          SemanticLogger.add_appender(file_name: settings.file, formatter:)
+        end
+        @name = name
+        @settings = settings
+      end
+
+      # @return [Boolean] whether {.setup} has run in this process
+      def configured? = !@settings.nil?
+
+      # The file lines go to, or nil when they go nowhere or to STDOUT.
+      #
+      # @return [String, nil]
+      def path = settings&.then { it.stdout? ? nil : it.file }
+
+      # @param name [String, nil] another name than this process's own
+      # @return [SemanticLogger::Logger]
+      def logger(name = nil) = SemanticLogger[name || @name || DEFAULT_NAME]
+
+      # One {UI.log} line, at +level+, with its fields as the payload. A
+      # no-op until {.setup} has run: commands that never log (`list-plans`,
+      # `docs`) still call code that reports through {UI.log}.
+      #
+      # @param message [String]
+      # @param level [Symbol] one of {LEVELS}
+      # @param fields [Hash] plan, status, agent, round, seconds and the like
+      # @return [void]
+      def event(message, level: :info, **fields)
+        return unless configured?
+
+        payload = fields.compact.transform_values do |value|
+          case value
+          when Float then value.round(1)
+          when String then redact(value)
+          else value
+          end
+        end
+        logger.public_send(level, redact(message.to_s), payload.empty? ? nil : payload)
+      end
+
+      # @param text [String]
+      # @return [String] +text+ with every URL password replaced by `***`
+      def redact(text) = text.gsub(CREDENTIALS, '\1:***@')
+
+      # Forget the setup and stop writing. For the suite, which sets logging
+      # up in a temp directory and must not leave an appender writing there.
+      #
+      # @return [void]
+      def reset!
+        SemanticLogger.clear_appenders!
+        @settings = nil
+        @name = nil
+      end
+    end
+  end
+end

data/lib/openlanes/support/refusal.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # Why a workflow would not do what it was asked, and the exit status that
+  # says so. Every command workflow fails with one of these inside a
+  # `Dry::Monads::Failure`, so the command that called it refuses the same
+  # way whichever workflow said no. The statuses follow sysexits, as
+  # {CLI::Base#refuse} documents.
+  #
+  # @!attribute [r] message
+  #   @return [String] what the person reads in the error box
+  # @!attribute [r] status
+  #   @return [Integer] the exit status
+  Refusal = Data.define(:message, :status)
+end

data/lib/openlanes/support/runtime.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+
+module OpenLanes
+  # Where a project's runtime files live: outside `.plans/`, under the XDG
+  # state directory. A lock or a run record inside `.plans/` sat beside
+  # committed documents, so every `git status` and every PR snapshot had to
+  # learn to ignore it, and a rename of a locked folder moved the lock with it.
+  #
+  # Keyed by the project root (the directory that holds `.plans/`), so two
+  # checkouts never share a state directory, and the harness and an agent
+  # handed the same `--dir` address the same one.
+  module Runtime
+    module_function
+
+    # @param env [Hash] the environment to read
+    # @return [String] absolute `XDG_STATE_HOME`, else `~/.local/state`. An
+    #   empty or relative value is ignored, as the XDG spec says.
+    def state_home(env = ENV)
+      value = env["XDG_STATE_HOME"].to_s
+      return value if !value.empty? && value.start_with?("/")
+
+      File.join(Dir.home, ".local", "state")
+    end
+
+    # @param root [String] the directory that holds `.plans/`
+    # @return [String] `<state_home>/openlanes/<basename>-<6 hex>`, created on demand
+    def dir(root:)
+      real = begin
+        File.realpath(root)
+      rescue Errno::ENOENT
+        File.expand_path(root)
+      end
+      path = File.join(state_home, "openlanes", "#{File.basename(real)}-#{Digest::SHA256.hexdigest(real)[0, 6]}")
+      FileUtils.mkdir_p(path)
+      path
+    end
+
+    # @param root [String]
+    # @return [String] the directory plan locks are written to
+    def locks_dir(root:)
+      path = File.join(dir(root:), "locks")
+      FileUtils.mkdir_p(path)
+      path
+    end
+
+    # @param root [String]
+    # @return [String] the directory each run's {Engine::EventJournal} is appended to
+    def journal_dir(root:)
+      path = File.join(dir(root:), "journal")
+      FileUtils.mkdir_p(path)
+      path
+    end
+
+    # @param root [String]
+    # @return [String] the run's {Engine::StateFile}
+    def state_file(root:) = File.join(dir(root:), "openlanes-state.json")
+  end
+end

data/lib/openlanes/support/spawner.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # The one place a child process is started, so a spec can start none.
+  #
+  # Named `Spawner`, not `Process`: Zeitwerk would resolve an
+  # `OpenLanes::Process` ahead of `::Process` at every bare `Process.kill`
+  # and `Process.wait` under `lib/openlanes`.
+  module Spawner
+    # Starts real processes.
+    module System
+      module_function
+
+      # @param env [Hash{String => String}]
+      # @param argv [Array<String>]
+      # @param options [Hash] as `Process.spawn` takes them
+      # @return [Integer] the pid
+      def spawn(env, *argv, **) = ::Process.spawn(env, *argv, **)
+    end
+
+    # Records what would have been started and hands back scripted pids.
+    class Fake
+      # One recorded call.
+      Call = Data.define(:env, :argv, :options)
+
+      # @return [Array<Call>]
+      def calls = @mutex.synchronize { @calls.dup }
+
+      # @param pids [Array<Integer>] handed out in order; a counter from
+      #   `first_pid` once they run out
+      # @param first_pid [Integer]
+      def initialize(pids: [], first_pid: 90_000)
+        @pids = pids.dup
+        @next = first_pid
+        @calls = []
+        @mutex = Mutex.new
+      end
+
+      # @param env [Hash{String => String}]
+      # @param argv [Array<String>]
+      # @param options [Hash]
+      # @return [Integer]
+      def spawn(env, *argv, **options)
+        @mutex.synchronize do
+          @calls << Call.new(env:, argv:, options:)
+          @pids.shift || (@next += 1)
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/support/ui.rb

@@ -2,7 +2,6 @@
 
 require "concurrent/hash"
 require "etc"
-require "fileutils"
 require "dry/cli/ui"
 require "pastel"
 require "stringio"
@@ -97,8 +96,9 @@ module OpenLanes
       def alive = "#{seconds.round}s"
 
       # @param message [String]
+      # @param level [Symbol] the entry's level in the log
       # @return [void]
-      def note(message) = UI.log(message, **@fields, seconds:)
+      def note(message, level: :info) = UI.log(message, level:, **@fields, seconds:)
 
       # @return [void]
       def start
@@ -182,7 +182,7 @@ module OpenLanes
       def failed(reason)
         stop_ticker
         @handle&.fail(reason)
-        note("failed after #{alive}: #{reason}")
+        note("failed after #{alive}: #{reason}", level: :warn)
       end
 
       # @param update [OpenLanes::Execution::Transcript::Progress]
@@ -219,6 +219,10 @@ module OpenLanes
       end
     end
 
+    # Serialises {.report_line} across worker threads. Created here, once:
+    # a lazy `||=` let two threads that arrived together each make their own.
+    @print_mutex = Mutex.new
+
     class << self
       # Set by the CLI's --quiet. Silences spinners and bars along with
       # everything else, so a quiet run really is quiet.
@@ -240,16 +244,16 @@ module OpenLanes
       def reset!
         remove_instance_variable(:@pastel) if instance_variable_defined?(:@pastel)
         self.quiet = false
-        self.log_path = nil
       end
 
-      # Where {.log} appends to, if anywhere. nil (the default) means nowhere;
-      # `openlanes run` sets this before the loop starts, so a round
-      # started under a tool that discards STDERR — an agent's own Bash call,
-      # for instance — still leaves something to `tail -f`.
+      # Where {.log} writes, if anywhere: the file {Log.setup} was given
+      # (`-` for STDOUT), nil before then. `openlanes run` sets logging up
+      # before the loop starts, so a round started under a tool that discards
+      # STDERR (an agent's own Bash call, for instance) still leaves
+      # something to `tail -f`.
       #
       # @return [String, nil]
-      attr_accessor :log_path
+      def log_path = Log.settings&.file
 
       # Something else that hears every {.log} line, as it is logged: the
       # live board keeps the latest few for the page. Taps are called on the
@@ -271,20 +275,18 @@ module OpenLanes
       # @return [Array<#call>]
       def log_taps = @log_taps || []
 
-      # Append one timestamped line to {.log_path}. A no-op with nothing set.
-      # Safe to call from several threads at once.
+      # Tell every tap, then write one entry to the log {Log.setup} opened,
+      # with the fields as its payload. The file is in addition to what the
+      # taps draw, never instead of it. Safe to call from several threads at once.
       #
       # @param message [String]
+      # @param level [Symbol] the entry's level in the log; taps hear every
+      #   level alike, since the terminal has no levels to filter by
+      # @param fields [Hash] plan, status, agent, round, seconds, to
       # @return [void]
-      def log(message, **fields)
+      def log(message, level: :info, **fields)
         log_taps.each { |tap| tap.call(message, fields) }
-        path = log_path or return
-
-        line = Engine::ProgressLog.render(message, **fields)
-        (@log_mutex ||= Mutex.new).synchronize do
-          FileUtils.mkdir_p(File.dirname(path))
-          File.open(path, "a") { |f| f.puts(line) }
-        end
+        Log.event(message, level:, **fields)
       end
 
       # Cells the meter takes on a spinner line, per direction.
@@ -549,7 +551,7 @@ module OpenLanes
       def report_line(text, bullet: "·")
         return if quiet
 
-        (@print_mutex ||= Mutex.new).synchronize { line(text, bullet:) }
+        @print_mutex.synchronize { line(text, bullet:) }
       end
 
       # A sensible worker count: agents are mostly waiting on a model rather
@@ -573,9 +575,25 @@ module OpenLanes
       # @return [String] decorated when colour is on, bare otherwise
       def paint(text, *styles) = color? ? pastel.decorate(text.to_s, *styles) : text.to_s
 
+      # The emoji variation selector U+FE0F, or a zero-width joiner U+200D.
+      EMOJI_SEQUENCE = /[\u{FE0F}\u{200D}]/
+
+      # `unicode-display_width` counts 🅱️, ☢️ and 🕰️ as one cell, while
+      # terminals with Unicode 9 widths draw them two, and every padded column
+      # came out one cell short (decision N2). A character the text explicitly
+      # asks to see as an emoji is two cells here, whatever the gem says.
+      # Measured per grapheme, so a ZWJ sequence such as 🏳️‍🌈, which the gem
+      # counts as three and which carries its selector mid-sequence, is the
+      # two cells a terminal draws, not four.
+      #
       # @param text [String]
       # @return [Integer] how many terminal cells the text occupies
-      def display_width(text) = ::Unicode::DisplayWidth.of(text.to_s)
+      def display_width(text)
+        text = text.to_s
+        return ::Unicode::DisplayWidth.of(text) unless text.match?(EMOJI_SEQUENCE)
+
+        text.each_grapheme_cluster.sum { it.match?(EMOJI_SEQUENCE) ? 2 : ::Unicode::DisplayWidth.of(it) }
+      end
 
       # Pad or truncate to an exact number of terminal *cells*.
       #
@@ -612,6 +630,77 @@ module OpenLanes
       # @return [void]
       def box(kind, message) = console.public_send(kind, message.to_s)
 
+      # Labelled lines for a box, the labels padded to one width:
+      #
+      #   Progress:     /var/folders/…/openlanes-minesweeper.log
+      #   Live board:   redis://host:6379 as kig@host
+      #                 (c016…:734c…)
+      #
+      # A value given as several parts is joined with spaces while it fits
+      # the box, and each part that does not starts a continuation line
+      # under the values, so a long id breaks where it was meant to rather
+      # than wherever the box's own wrap runs out of room.
+      #
+      # @param rows [Array<Array(String, String | Array<String>)>] label and value
+      # @param room [Integer] text columns inside the box
+      # @return [String]
+      def labelled(rows, room: box_room)
+        pad = rows.map { |label, _| display_width("#{label}:") }.max.to_i + 1
+        free = [room - pad, 1].max
+        rows.flat_map { |label, parts|
+          lines = Array(parts).map(&:to_s).each_with_object([]) do |part, acc|
+            if acc.any? && display_width("#{acc.last} #{part}") <= free
+              acc[-1] = "#{acc.last} #{part}"
+            else
+              acc.concat(broken(part, free))
+            end
+          end
+          lines.each_with_index.map { |text, i| (i.zero? ? fit("#{label}:", pad) : " " * pad) + text }
+        }.join("\n")
+      end
+
+      # A value wider than its column, cut into pieces that fit: after a
+      # `/` where it can be, so a path breaks between directories, and
+      # anywhere when one name is wider than the column on its own. Left
+      # to the box, a path wider than the room after its label wrapped
+      # onto the next line whole, under the label rather than beside it,
+      # and was then cut mid-name with no indent.
+      #
+      # @param text [String]
+      # @param free [Integer] columns
+      # @return [Array<String>] the pieces, each at most +free+ wide
+      def broken(text, free)
+        return [text] if display_width(text) <= free
+
+        text.split(%r{(?<=/)}).flat_map { cells(it, free) }.each_with_object([+""]) do |piece, acc|
+          acc.last.empty? || display_width(acc.last + piece) <= free ? acc.last << piece : acc << piece.dup
+        end
+      end
+
+      # A piece cut by terminal cells rather than characters, one grapheme
+      # cluster at a time, so a wide name such as `界界界` is never cut into
+      # a chunk wider than +free+ (nor a combining mark off its letter).
+      #
+      # @param text [String]
+      # @param free [Integer] columns
+      # @return [Array<String>]
+      def cells(text, free)
+        text.each_grapheme_cluster.with_object([+""]) do |grapheme, acc|
+          acc << +"" unless acc.last.empty? || display_width(acc.last + grapheme) <= free
+          acc.last << grapheme
+        end
+      end
+
+      # Text columns inside a box, as dry-cli-ui works them out: the box is
+      # {.width} or the terminal less two, whichever is narrower, and a
+      # border and two columns of padding go on either side.
+      #
+      # @return [Integer]
+      def box_room
+        terminal = tty? ? TTY::Screen.width : Dry::CLI::UI::Terminal::DEFAULT_WIDTH
+        [width, terminal - 2].min - 6
+      end
+
       # A framed panel centered on the screen, for the keyboard help. Unlike
       # {.box} it positions itself absolutely, so it overlays whatever the
       # spinners are drawing rather than scrolling in below them — the next

data/lib/openlanes/vcs/ci_gate.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Vcs
+    # One word for a pull request's CI, from `gh pr checks` buckets (M3).
+    module CiGate
+      # Buckets that say nothing about the code: a skipped job is not a verdict.
+      NEUTRAL = %w[pass skipping].freeze
+
+      module_function
+
+      # An unknown bucket counts as red (open question 5): a state `gh` grows
+      # later must not wave a passing label through.
+      #
+      # @param checks [Array<Hash>] `{name:, bucket:}`, as {GitHub#checks} returns
+      # @return [Symbol] `:green`, `:red`, `:pending`, or `:none` when no
+      #   check ran
+      def verdict(checks)
+        buckets = checks.map { |c| c[:bucket].to_s }
+        # Every job skipped means CI did not run (a spent Actions budget can
+        # report it this way), which is the same as no checks, not a pass.
+        return :none if buckets.all?("skipping")
+
+        return :red if buckets.any? { |b| b != "pending" && !NEUTRAL.include?(b) }
+        return :pending if buckets.include?("pending")
+
+        :green
+      end
+    end
+  end
+end