openlanes 3.0.1 → 3.1.0

data/lib/openlanes/cli.rb

@@ -7,6 +7,7 @@ require "tty-screen"
 # the shared flags and plumbing, so it loads first; the rest only meet each
 # other here, at registration.
 require_relative "cli/base"
+require_relative "cli/coverage/coverage"
 require_relative "cli/create/create"
 require_relative "cli/index/index"
 require_relative "cli/init/init"
@@ -19,6 +20,7 @@ require_relative "cli/linear/subcommands/import"
 require_relative "cli/docs/docs"
 require_relative "cli/eval/eval"
 require_relative "cli/run/run"
+require_relative "cli/setup/setup"
 require_relative "cli/start/start"
 require_relative "cli/unblock/unblock"
 require_relative "cli/version/version"
@@ -30,10 +32,19 @@ require_relative "cli/worktree/worktree"
 require_relative "cli/mail/mail"
 require_relative "cli/mail/subcommands/send"
 require_relative "cli/mail/subcommands/read"
+require_relative "cli/mail/subcommands/ack"
+require_relative "cli/mail/subcommands/render"
 require_relative "cli/state/state"
 require_relative "cli/state/subcommands/sign"
 require_relative "cli/state/subcommands/show"
+require_relative "cli/state/subcommands/resume"
 require_relative "cli/skills/subcommands/install"
+require_relative "cli/api/api"
+require_relative "cli/api/subcommands/docs"
+require_relative "cli/app/app"
+require_relative "cli/app/subcommands/start"
+require_relative "cli/app/subcommands/status"
+require_relative "cli/app/subcommands/stop"
 
 module OpenLanes
   # The command line. Every command is a thin shell over one library class:
@@ -85,7 +96,7 @@ module OpenLanes
       width [90, TTY::Screen.width - 2].min
 
       # Most used first: what a person types every day, then what scripts do.
-      group "OpenLanes Default Web Operation", "init", "start", "web"
+      group "OpenLanes Default Web Operation", "setup", "init", "start", "web"
       group "Headless Operation",
         "create",
         "run",
@@ -93,15 +104,19 @@ module OpenLanes
         "index",
         "resync",
         "unblock",
+        "review",
         "worktree",
+        "coverage",
+        "app",
         "agents",
         "describe",
         "mail",
         "state",
         "eval"
-      group "Reference", "docs", "states", "linear", "skills", "completion", "version"
+      group "Reference", "docs", "api", "states", "linear", "skills", "completion", "version"
     end
 
+    register "setup", Setup
     register "init", Init
     register "create", Create, aliases: %w[new c]
     # Renamed from `status`, which read as "is the tool OK?" rather than "what
@@ -112,8 +127,13 @@ module OpenLanes
     register "start", Start
     register "web", Web
     register "unblock", Unblock
+    register "review", Review
     register "eval", Eval
     register "worktree", Worktree
+    # Beside the command, not instead of it: dry-cli runs `worktree 002` as
+    # before, since "002" names no subcommand.
+    register "worktree prune", WorktreePrune
+    register "coverage", Coverage
     register "docs", Docs
     register "states", States, aliases: %w[diagram]
     register "index", Index, aliases: %w[idx]
@@ -143,6 +163,8 @@ module OpenLanes
     register "mail" do |prefix|
       prefix.register "send", Mail::Send
       prefix.register "read", Mail::Read
+      prefix.register "ack", Mail::Ack
+      prefix.register "render", Mail::Render
     end
 
     # What every agent shells out to at the start and end of its round. See
@@ -150,6 +172,7 @@ module OpenLanes
     register "state" do |prefix|
       prefix.register "sign", State::Sign
       prefix.register "show", State::Show
+      prefix.register "resume", State::Resume
     end
 
     # Copies the skills bundled with the gem; see {OpenLanes::Skills}.
@@ -157,6 +180,18 @@ module OpenLanes
       prefix.register "install", Skills::Install
     end
 
+    # Lists and checks the OpenAPI contracts plans carry; see {OpenLanes::Presentation::ApiDocs}.
+    register "api" do |prefix|
+      prefix.register "docs", API::Docs
+    end
+
+    # The app a plan builds, for the Preview tab; see {OpenLanes::Apps}.
+    register "app" do |prefix|
+      prefix.register "start", App::Start
+      prefix.register "status", App::Status
+      prefix.register "stop", App::Stop
+    end
+
     register "completion", ::Dry::CLI::Autocomplete::Command[::OpenLanes::CLI]
   end
 end

data/lib/openlanes/coverage/cobertura.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Coverage
+    # Cobertura XML. Only the root `<coverage>` element is read:
+    # `lines-covered` and `lines-valid` when both are there (gcovr writes
+    # them), else `line-rate`, a 0–1 decimal that some producers round.
+    #
+    # The root tag is matched rather than parsed with an XML library, because
+    # its attributes are the whole of what is needed and the gem has no XML
+    # dependency to spend on it.
+    module Cobertura
+      ROOT = /<coverage\b([^>]*)>/m
+
+      module_function
+
+      # @param text [String]
+      # @return [Array(Numeric, Numeric)] covered, relevant
+      # @raise [OpenLanes::Coverage::Malformed]
+      def parse(text)
+        root = text[ROOT, 1] or raise Malformed, "no <coverage> element"
+        attributes = root.scan(/([\w-]+)\s*=\s*["']([^"']*)["']/).to_h
+
+        covered, valid = attributes.values_at("lines-covered", "lines-valid")
+        return [whole(covered), whole(valid)] if covered && valid
+
+        rate = attributes["line-rate"] or raise Malformed, "<coverage> has neither lines-valid nor line-rate"
+        [rational(rate), 1]
+      end
+
+      # @return [Integer]
+      def whole(text)
+        Integer(text, 10)
+      rescue ArgumentError
+        raise Malformed, "#{text.inspect} is not a line count"
+      end
+
+      # @return [Rational]
+      def rational(text)
+        value = Rational(text)
+        raise Malformed, "line-rate #{text.inspect} is outside 0 to 1" unless value.between?(0, 1)
+
+        value
+      rescue ArgumentError, ZeroDivisionError
+        raise Malformed, "line-rate #{text.inspect} is not a number"
+      end
+    end
+  end
+end

data/lib/openlanes/coverage/config.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Coverage
+    # The `coverage:` section of a project's `.openlanes.yml` (M15, amended
+    # 2026-10-17). One of two shapes, never both:
+    #
+    #   coverage:                 # the figure, printed by a command
+    #     command: bundle exec rspec
+    #     report_command: jq '.total.lines.percent' coverage/coverage.json
+    #     minimum: 95
+    #
+    #   coverage:                 # a report file, read by a parser here
+    #     command: npm test -- --coverage
+    #     report:  coverage/lcov.info
+    #     format:  lcov           # lcov | cobertura | istanbul | simplecov
+    #     minimum: 95
+    #
+    # `command` and `minimum` are required in both. A key the gate ignored
+    # would be a promise nobody checks, which is the failure this section
+    # exists to end; so, as everywhere in `.openlanes.yml`, anything
+    # unexpected is an error naming the file and the section. A
+    # `report_command` beside a `format` is refused rather than read as one
+    # of them: which of the two the author meant is exactly what is unknown.
+    #
+    # It lives in the file a project already has rather than in a second one
+    # beside it (the first M15 had `.openlanes.coverage.yml`): one project's
+    # settings in two files is two places to look, and one gets forgotten.
+    #
+    # @!attribute [r] path
+    #   @return [String] the `.openlanes.yml` it was read from
+    # @!attribute [r] command
+    #   @return [String] run through `sh -c` in the checkout
+    # @!attribute [r] report
+    #   @return [String, nil] relative to the checkout, as written; nil with
+    #     a {#report_command}
+    # @!attribute [r] format
+    #   @return [Symbol, nil] one of {FORMATS}; nil with a {#report_command}
+    # @!attribute [r] report_command
+    #   @return [String, nil] run through `sh -c` in the checkout after
+    #     {#command}; its STDOUT is the line percentage
+    # @!attribute [r] minimum
+    #   @return [Float] the lowest line percentage that passes, 0 to 100
+    Config = Data.define(:path, :command, :report, :format, :report_command, :minimum) do
+      def initialize(report: nil, format: nil, report_command: nil, **rest) = super
+
+      # @param root [String] the checkout the report path is relative to
+      # @return [String, nil] absolute; nil with a {#report_command}
+      def report_path(root) = report && File.expand_path(report, root)
+
+      # @return [Boolean] whether the figure comes from {#report_command}
+      def report_command? = !report_command.nil?
+
+      # Where the figure comes from, as a verdict names it.
+      #
+      # @return [String]
+      def source = report_command? ? "report_command: `#{report_command}`" : "#{format}: #{report}"
+
+      # The section as `.openlanes.yml` holds it.
+      #
+      # @return [Hash{String => Object}]
+      def to_h
+        { "command" => command, "report" => report, "format" => format&.to_s,
+          "report_command" => report_command, "minimum" => minimum }.compact
+      end
+    end
+
+    class Config
+      # The section's key at the top of `.openlanes.yml`.
+      SECTION = "coverage"
+
+      # Report formats with a parser. Each reports lines (plan decision 1).
+      FORMATS = %i[lcov cobertura istanbul simplecov].freeze
+
+      # Every key the section may hold.
+      KEYS = %w[command report format report_command minimum].freeze
+
+      # Keys both shapes require.
+      REQUIRED = %w[command minimum].freeze
+
+      # The two shapes, as every error and the setup note spell them.
+      SHAPES = "report_command alone, or report with format"
+
+      # Where the first M15 kept this section. Never read: only the
+      # `coverage:` section counts. But a project that still has it would
+      # otherwise turn unconfigured without a word and be sent back for
+      # setup, so its presence is said once, as a warning.
+      LEGACY = ".openlanes.coverage.yml"
+
+      class << self
+        # @param root [String] a checkout
+        # @return [OpenLanes::Coverage::Config, nil] nil when its
+        #   `.openlanes.yml` has no `coverage:` section, or there is no file
+        # @raise [OpenLanes::Coverage::Invalid] when the section, or the file
+        #   around it, cannot be used
+        def load(root)
+          warn_legacy(root)
+          OpenLanes::Config.load(root).coverage
+        rescue Invalid
+          raise
+        rescue OpenLanes::Error => e
+          raise Invalid, e.message
+        end
+
+        # @param value [Object] what YAML gave for `coverage:`
+        # @param path [String] the `.openlanes.yml`, named in every error
+        # @return [OpenLanes::Coverage::Config]
+        # @raise [OpenLanes::Coverage::Invalid]
+        def parse(value, path:)
+          fail_with(path, ": must be a mapping with command, minimum, and #{SHAPES}") unless value.is_a?(Hash)
+
+          settings = value.transform_keys(&:to_s)
+          unknown = settings.keys - KEYS
+          fail_with(path, ": unknown key #{unknown.join(", ")}; known: #{KEYS.join(", ")}") unless unknown.empty?
+          missing = REQUIRED - settings.keys
+          fail_with(path, ": missing key #{missing.join(", ")}") unless missing.empty?
+          shape!(settings, path)
+
+          new(path:,
+            command: text_of(settings, "command", path),
+            minimum: minimum_of(settings["minimum"], path),
+            **source_of(settings, path))
+        end
+
+        private
+
+        # Once per file and process: the gate asks on every poll.
+        #
+        # @return [void]
+        def warn_legacy(root)
+          path = File.join(root, LEGACY)
+          @warned ||= Set.new
+          return unless File.exist?(path) && @warned.add?(path)
+
+          UI.log("#{path} is no longer read; move its settings under #{SECTION}: in .openlanes.yml", level: :warn)
+        end
+
+        # @param message [String] after the section's name: ": …" for the
+        #   section, ".key: …" for one key, as the rest of `.openlanes.yml` reads
+        # @return [void] never returns
+        def fail_with(path, message) = raise(Invalid, "#{path}: #{SECTION}#{message}")
+
+        # Exactly one shape, said whole.
+        #
+        # @return [void]
+        def shape!(settings, path)
+          given = %w[report format report_command].select { settings.key?(it) }
+          return if [%w[report_command], %w[report format]].include?(given)
+
+          problem =
+            if given.empty? then "says nowhere to read the figure"
+            elsif given.include?("report_command") then "report_command replaces #{(given - %w[report_command]).join(" and ")}"
+            else "#{given.first} without #{(%w[report format] - given).first}"
+            end
+          fail_with(path, ": #{problem}; give #{SHAPES}")
+        end
+
+        # @return [Hash{Symbol => Object}]
+        def source_of(settings, path)
+          return { report_command: text_of(settings, "report_command", path) } if settings.key?("report_command")
+
+          { report: text_of(settings, "report", path), format: format_of(settings["format"], path) }
+        end
+
+        # @return [String]
+        def text_of(settings, key, path)
+          value = settings[key]
+          return value.strip if value.is_a?(String) && !value.strip.empty?
+
+          fail_with(path, ".#{key}: must be a non-empty string, not #{value.inspect}")
+        end
+
+        # @return [Symbol]
+        def format_of(value, path)
+          format = value.to_s.strip.downcase.to_sym
+          return format if FORMATS.include?(format)
+
+          fail_with(path, ".format: #{value.inspect} is not one of #{FORMATS.join(", ")}")
+        end
+
+        # A quoted `"95"` is refused rather than converted: YAML that types a
+        # number as a string was written by hand, and the hand may have meant
+        # something else.
+        #
+        # @return [Float]
+        def minimum_of(value, path)
+          return value.to_f if value.is_a?(Numeric) && value.between?(0, 100)
+
+          fail_with(path, ".minimum: #{value.inspect} is not a number from 0 to 100")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/coverage/istanbul.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Coverage
+    # Istanbul's `coverage-summary.json` (the `json-summary` reporter):
+    # `total.lines.covered` over `total.lines.total`.
+    #
+    # `pct` is never read. It is floored to two decimals, and istanbul writes
+    # 100 for a total of zero and `"Unknown"` for a blank summary, neither of
+    # which is a figure the gate can stand behind.
+    module Istanbul
+      module_function
+
+      # @param text [String]
+      # @return [Array(Integer, Integer)] covered, relevant
+      # @raise [OpenLanes::Coverage::Malformed]
+      # @raise [JSON::ParserError]
+      def parse(text)
+        lines = JSON.parse(text).dig("total", "lines") if text.strip.start_with?("{")
+        raise Malformed, "no total.lines" unless lines.is_a?(Hash)
+
+        covered, total = lines.values_at("covered", "total")
+        raise Malformed, "total.lines needs whole-number covered and total" unless [covered, total].all?(Integer)
+
+        [covered, total]
+      end
+    end
+  end
+end

data/lib/openlanes/coverage/lcov.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  module Coverage
+    # `lcov.info`: one `SF:` … `end_of_record` block per source file, each
+    # carrying `LF:` (instrumented lines) and `LH:` (lines hit).
+    #
+    # There is no total record, and the per-file percentages must not be
+    # averaged: a ten-line file at 0% and a thousand-line file at 100% are
+    # 99%, not 50%. The counts are summed instead. A block without `LF`/`LH`
+    # is counted from its `DA:` lines, which is what those two summarise.
+    module Lcov
+      module_function
+
+      # @param text [String]
+      # @return [Array(Integer, Integer)] covered, relevant
+      # @raise [OpenLanes::Coverage::Malformed] when text is present but holds
+      #   no `SF:` record
+      def parse(text)
+        records = text.split(/^end_of_record\s*$/).grep(/^SF:/)
+        raise Malformed, "no SF: records" if records.empty? && !text.strip.empty?
+
+        records.map { tally(it) }.transpose.map(&:sum).then { it.empty? ? [0, 0] : it }
+      end
+
+      # @param record [String] one file's block
+      # @return [Array(Integer, Integer)]
+      def tally(record)
+        found = record[/^LF:(\d+)/, 1]
+        hit = record[/^LH:(\d+)/, 1]
+        return [Integer(hit), Integer(found)] if found && hit
+
+        hits = record.scan(/^DA:\d+,(-?\d+)/).flatten.map { Integer(it) }
+        [hits.count(&:positive?), hits.size]
+      end
+    end
+  end
+end

data/lib/openlanes/coverage/report.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Coverage
+    # One coverage report, reduced to the two counts the gate compares.
+    #
+    # Every way a report can fail to say anything (missing, unreadable,
+    # malformed, or present with nothing instrumented) is the same answer: 0%,
+    # with the reason kept in {#problem}. A gate that passed on "could not
+    # tell" would pass a project whose test command stopped writing its
+    # report, which is the easiest way to stop being measured.
+    #
+    # @!attribute [r] covered
+    #   @return [Numeric] lines hit at least once
+    # @!attribute [r] relevant
+    #   @return [Numeric] instrumented lines
+    # @!attribute [r] problem
+    #   @return [String, nil] why the report counts as 0%, nil when it was read
+    Report = Data.define(:covered, :relevant, :problem) do
+      def initialize(covered: 0, relevant: 0, problem: nil) = super
+
+      # Computed from the counts, never from a figure a tool rounded: simplecov
+      # truncates to two decimals and istanbul floors, so 94.995 would read as
+      # a pass at 95.
+      #
+      # @return [Float] 0.0 to 100.0
+      def percent = ratio.to_f
+
+      # The percentage as the counts state it. A Float cannot hold most
+      # two-decimal figures (10.03 is 10.0299…), so anything that floors or
+      # compares reads this instead of {#percent}.
+      #
+      # @return [Rational] 0 to 100
+      def ratio
+        return 0r if problem || !relevant.positive?
+
+        covered * 100r / relevant
+      end
+
+      # @return [Boolean] whether the report said anything at all
+      def read? = problem.nil?
+    end
+
+    class Report
+      # The parser for each format. Each answers `parse(text)` with
+      # `[covered, relevant]`, or raises {Malformed}.
+      PARSERS = { lcov: "Lcov", cobertura: "Cobertura", istanbul: "Istanbul", simplecov: "Simplecov" }.freeze
+
+      class << self
+        # @param format [Symbol] one of {Config::FORMATS}
+        # @param path [String]
+        # @return [OpenLanes::Coverage::Report]
+        def read(format:, path:)
+          parser = Coverage.const_get(PARSERS.fetch(format.to_sym))
+          return new(problem: "#{path} is missing") unless File.exist?(path)
+
+          covered, relevant = parser.parse(File.read(path))
+          return new(covered:, relevant:, problem: "#{path} has no instrumented lines") unless relevant.positive?
+
+          new(covered:, relevant:)
+        rescue SystemCallError, IOError => e
+          new(problem: "#{path} cannot be read (#{e.message})")
+        rescue Malformed, JSON::ParserError => e
+          new(problem: "#{path} is not a #{format} report (#{e.message.lines.first.to_s.strip})")
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/coverage/simplecov.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenLanes
+  module Coverage
+    # SimpleCov's `coverage/.resultset.json`: per command (RSpec, and any
+    # suite merged in), per file, one hit count per source line, `nil` where a
+    # line is not code.
+    #
+    # Not `.last_run.json`: that one truncates to two decimals and is written
+    # only after a fully successful run (plan decision 3). The resultset is
+    # already filtered by the project's SimpleCov filters, so every file in it
+    # counts. It does not record `:nocov:` blocks, so this figure can come out
+    # lower than SimpleCov's own, never higher.
+    #
+    # {.lines_by_file} is public so `bin/coverage-changed` (PR #27), which
+    # judges each changed file, merges runs the same way the gate does.
+    module Simplecov
+      module_function
+
+      # @param text [String]
+      # @return [Array(Integer, Integer)] covered, relevant
+      # @raise [OpenLanes::Coverage::Malformed]
+      # @raise [JSON::ParserError]
+      def parse(text)
+        relevant = lines_by_file(text).values.flatten.compact
+        [relevant.count(&:positive?), relevant.size]
+      end
+
+      # Every command's counts merged line by line: a line hit by any run is
+      # covered, and a line is relevant when any run says it is code.
+      #
+      # @param text [String] the resultset
+      # @return [Hash{String => Array<Integer, nil>}] by the path as recorded
+      # @raise [OpenLanes::Coverage::Malformed]
+      # @raise [JSON::ParserError]
+      def lines_by_file(text)
+        runs = JSON.parse(text)
+        raise Malformed, "expected a mapping of command name to its run" unless runs.is_a?(Hash)
+
+        runs.each_with_object({}) do |(command, run), merged|
+          files = run.is_a?(Hash) && run["coverage"]
+          raise Malformed, "#{command} has no coverage mapping" unless files.is_a?(Hash)
+
+          files.each { |path, entry| merged[path] = merge(merged[path] || [], counts(path, entry)) }
+        end
+      end
+
+      # SimpleCov 0.18+ writes `{"lines": [...]}`; older versions the bare
+      # array. A non-integer count (`"ignored"`) is not code.
+      #
+      # @return [Array<Integer, nil>]
+      def counts(path, entry)
+        lines = entry.is_a?(Hash) ? entry["lines"] : entry
+        raise Malformed, "#{path} has no line counts" unless lines.is_a?(Array)
+
+        lines.map { it.is_a?(Integer) ? it : nil }
+      end
+
+      # @return [Array<Integer, nil>]
+      def merge(into, counts)
+        Array.new([into.size, counts.size].max) do |index|
+          a, b = into[index], counts[index]
+          a.nil? && b.nil? ? nil : a.to_i + b.to_i
+        end
+      end
+    end
+  end
+end

data/lib/openlanes/coverage.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenLanes
+  # A project's declared test coverage (decision M15), the `coverage:`
+  # section of its `.openlanes.yml`: which command runs the suite, where the
+  # line figure comes from, and the lowest one that may merge.
+  #
+  # Pure, like {Plans}: it reads files and does arithmetic, and starts no
+  # process. Running either command belongs to {Engine::CoverageGate}, which
+  # is the only caller that turns a figure into a verdict.
+  module Coverage
+    # A `coverage:` section, or the `.openlanes.yml` around it, that cannot be
+    # honoured as written.
+    class Invalid < OpenLanes::Error; end
+
+    # A report present on disk that a parser cannot read.
+    class Malformed < OpenLanes::Error; end
+
+    module_function
+
+    # @param root [String] the checkout whose declaration is read
+    # @return [OpenLanes::Coverage::Config, nil] nil when its `.openlanes.yml`
+    #   has no `coverage:` section
+    # @raise [OpenLanes::Coverage::Invalid]
+    def config(root) = Config.load(root)
+
+    # @param format [Symbol] one of {Config::FORMATS}
+    # @param path [String] the report
+    # @return [OpenLanes::Coverage::Report] never raises; a report that cannot
+    #   be read is a {Report} at 0% with its problem named
+    def read(format:, path:) = Report.read(format:, path:)
+  end
+end