brute 3.2.2 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd242366b30cf384cb0326b8fa006f43883f1cf117d410b830288164a4d13582
-  data.tar.gz: 3d4973d9a6fa69e6fd04d464343d8d2d85fb8455236e9d03f32df17888182e1f
+  metadata.gz: 428a37a7f0f2e0930d1b0c901fc75606686c25e07046b54c6dc4964fbbb88433
+  data.tar.gz: 33f0b4a2956004b7e4d26790f981718fea46d2ae7cf1f54deaea250a7951edaf
 SHA512:
-  metadata.gz: f0659b341410c0cb87db3cefe95e3c8c99bbf5ea9c88ba974d6b8f1adc5835919e256a577435748d652e1e229b30fb6cbaac321d297688fc9fac0812a028e369
-  data.tar.gz: 5f693c1c49b4bd74ce901e78bcd459f04c6316fe044bb871a04142b09154cb04767a1166dd64d02d2332fb9fac63572a6d13b28fbef40520c18737b1a11f98f4
+  metadata.gz: 7c382ae2d9229bdd7524cbdb87614f94b8c54e25ae2f76ee68892198bcf8d901d35398b3555f712b07253f17c3dddd1d8d66907c44ff9eaa28dd5adca3441582
+  data.tar.gz: 1c3816fff0d6664a25a9bfcb0c44df62c6833c2ba5066b3cbec0772fd24ea1ab4e078b7e1faca3f577297842fdd92c3aca59368f376993ba88956aaf3c02d500

data/lib/brute/changelog.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require "date"
+
+require_relative "deprecate"
+
+module Brute
+  # A parser and linter for CHANGELOG.md, which follows
+  # [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+  #
+  # The changelog is the one release artefact nothing else can regenerate, so
+  # it is the one most easily forgotten. Making it machine-checkable turns
+  # "did anyone write the changelog?" into a gate: `bin/lint-changelog`
+  # validates the format, and `bin/release-gem` refuses to push a version that
+  # has no section of its own.
+  #
+  #   changelog = Brute::Changelog.load
+  #   changelog.problems              # => [] when the format is clean
+  #   changelog.release_problems("4.1.0")
+  #
+  # The shape it expects:
+  #
+  #   # Changelog
+  #
+  #   ## [Unreleased]
+  #
+  #   ## [4.1.0] - 2026-08-20
+  #
+  #   ### Added
+  #
+  #   - Something that happened.
+  #
+  class Changelog
+    # Deprecated. This moved out to the gem_kit-release gem, where the rest of
+    # the release toolchain now lives — `gem kit changelog` is the CLI over it.
+    # The implementation stays here, working, until the deadline.
+    extend Brute::Deprecate
+    brute_deprecate_constant "GemKit::Release::Changelog", "5.0"
+
+    # The six change types Keep a Changelog defines. Anything else under a
+    # version is a typo or an invention, and both are worth catching.
+    SECTIONS = %w[Added Changed Deprecated Removed Fixed Security].freeze
+
+    UNRELEASED       = "Unreleased"
+    HEADING          = /\A##\s+\[([^\]]+)\](?:\s+-\s+(.*))?\s*\z/
+    SUBHEADING       = /\A###\s+(.*?)\s*\z/
+    BULLET           = /\A[-*]\s+\S/
+    DATE             = /\A\d{4}-\d{2}-\d{2}\z/
+
+    # One `## [...]` section of the file.
+    Release = Struct.new(:version, :date, :line, :subsections, keyword_init: true) do
+      def unreleased? = version == UNRELEASED
+      def empty? = subsections.empty? || subsections.values.all?(&:empty?)
+      def to_s = unreleased? ? "[#{version}]" : "[#{version}] - #{date}"
+    end
+
+    # Load the changelog sitting beside the gem (../../CHANGELOG.md).
+    def self.load(path = File.expand_path("../../CHANGELOG.md", __dir__))
+      new(File.exist?(path) ? File.read(path) : nil, path: path)
+    end
+
+    attr_reader :path, :releases
+
+    # @parameter text [String, nil] the file's contents; nil means "no file".
+    def initialize(text, path: "CHANGELOG.md")
+      @path     = path
+      @text     = text
+      @releases = text ? parse(text) : []
+    end
+
+    def missing? = @text.nil?
+
+    def unreleased = releases.find(&:unreleased?)
+
+    def released = releases.reject(&:unreleased?)
+
+    def find(version)
+      target = Gem::Version.new(version.to_s)
+      released.find { |release| Gem::Version.new(release.version) == target rescue false }
+    end
+
+    # Everything wrong with the file's *format*, as a list of human-readable
+    # problems. Empty means it lints clean.
+    def problems
+      return ["#{path} does not exist"] if missing?
+
+      [*header_problems, *heading_problems, *ordering_problems, *content_problems]
+    end
+
+    # Everything standing between this changelog and releasing `version`.
+    # Format problems count: a file nobody can parse is not documentation.
+    def release_problems(version)
+      return problems unless problems.empty?
+
+      release = find(version)
+      return ["#{path} has no section for #{version} — run bin/update-changelog"] if release.nil?
+      return ["#{path} section for #{version} is empty"] if release.empty?
+
+      newest = released.first
+      if newest && newest.version != release.version
+        return ["#{path} lists #{newest.version} above #{version}; the release being cut must come first"]
+      end
+
+      []
+    end
+
+    private
+
+      # Split the file into `## [...]` sections, recording each one's
+      # `### Type` subsections and their top-level bullets.
+      def parse(text)
+        found   = []
+        current = nil
+        heading = nil
+
+        text.each_line.with_index(1) do |line, number|
+          case line
+          when HEADING
+            heading = nil
+            current = Release.new(version: $1, date: $2&.strip, line: number, subsections: {})
+            found << current
+          when SUBHEADING
+            next unless current
+
+            heading = $1
+            (current.subsections[heading] ||= [])
+          when BULLET
+            current.subsections[heading] << line.strip if current && heading
+          end
+        end
+
+        found
+      end
+
+      def header_problems
+        first = @text.each_line.find { |line| !line.strip.empty? }
+        return [] if first&.strip == "# Changelog"
+
+        ["#{path}:1 must start with the title `# Changelog`"]
+      end
+
+      def heading_problems
+        problems = []
+
+        @text.each_line.with_index(1) do |line, number|
+          next unless line.start_with?("## ") && !line.start_with?("###")
+
+          unless line =~ HEADING
+            problems << "#{path}:#{number} malformed version heading: #{line.strip.inspect} " \
+                        "(expected `## [Unreleased]` or `## [1.2.3] - YYYY-MM-DD`)"
+            next
+          end
+
+          version, date = $1, $2&.strip
+          next if version == UNRELEASED
+
+          problems << "#{path}:#{number} #{version} has no date (expected `## [#{version}] - YYYY-MM-DD`)" if date.nil? || date.empty?
+          problems << "#{path}:#{number} #{version} has a malformed date: #{date.inspect}" if date && !date.empty? && date !~ DATE
+          problems << "#{path}:#{number} #{version} is not a valid version number" unless valid_version?(version)
+        end
+
+        problems + subheading_problems
+      end
+
+      def subheading_problems
+        @text.each_line.with_index(1).filter_map do |line, number|
+          next unless line.start_with?("### ")
+          next if line =~ SUBHEADING && SECTIONS.include?($1)
+
+          "#{path}:#{number} unknown section #{line.sub("###", "").strip.inspect} " \
+            "(expected one of: #{SECTIONS.join(", ")})"
+        end
+      end
+
+      def ordering_problems
+        problems = []
+
+        if unreleased && releases.first&.unreleased? == false
+          problems << "#{path}:#{unreleased.line} [Unreleased] must be the first section"
+        end
+
+        seen = {}
+        released.each do |release|
+          if (first = seen[release.version])
+            problems << "#{path}:#{release.line} duplicate section for #{release.version} (also at line #{first})"
+          end
+          seen[release.version] ||= release.line
+        end
+
+        versions = released.select { |release| valid_version?(release.version) }
+        versions.each_cons(2) do |newer, older|
+          next if Gem::Version.new(newer.version) > Gem::Version.new(older.version)
+
+          problems << "#{path}:#{older.line} #{older.version} is listed below #{newer.version}; " \
+                      "releases must run newest to oldest"
+        end
+
+        problems
+      end
+
+      def content_problems
+        released.flat_map do |release|
+          if release.subsections.empty?
+            ["#{path}:#{release.line} #{release} has no #{SECTIONS.join("/")} section"]
+          else
+            release.subsections.filter_map do |heading, bullets|
+              "#{path}:#{release.line} #{release} has an empty `### #{heading}` section" if bullets.empty?
+            end
+          end
+        end
+      end
+
+      def valid_version?(version)
+        Gem::Version.correct?(version)
+      end
+  end
+end
+
+__END__
+
+describe "brute/changelog" do
+  # These specs exercise a deprecated class on purpose; skip_during keeps the
+  # warning out of the suite's output (see DEPRECATIONS.md).
+  changelog = lambda do |body|
+    Gem::Deprecate.skip_during { Brute::Changelog.new("# Changelog\n\n#{body}") }
+  end
+
+  good = <<~MD
+    ## [Unreleased]
+
+    ## [4.1.0] - 2026-08-20
+
+    ### Added
+
+    - A thing.
+
+    ## [4.0.0] - 2026-08-01
+
+    ### Removed
+
+    - An older thing.
+  MD
+
+  it "parses sections, dates and bullets" do
+    log = changelog.call(good)
+
+    log.releases.map(&:version).should == ["Unreleased", "4.1.0", "4.0.0"]
+    log.unreleased.should.be.kind_of?(Brute::Changelog::Release)
+    log.released.first.date.should == "2026-08-20"
+    log.released.first.subsections["Added"].should == ["- A thing."]
+    log.find("4.0.0").subsections["Removed"].size.should == 1
+  end
+
+  it "lints a well-formed file clean and clears it for release" do
+    log = changelog.call(good)
+
+    log.problems.should == []
+    log.release_problems("4.1.0").should == []
+  end
+
+  it "requires the `# Changelog` title" do
+    Gem::Deprecate.skip_during do
+      Brute::Changelog.new("## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n")
+        .problems.first.should.match(/must start with the title/)
+    end
+  end
+
+  it "reports a missing file" do
+    log = Gem::Deprecate.skip_during { Brute::Changelog.new(nil, path: "nope.md") }
+    log.missing?.should.be.true
+    log.problems.first.should.match(/does not exist/)
+  end
+
+  it "rejects a malformed version heading" do
+    changelog.call("## 1.0.0\n").problems.first.should.match(/malformed version heading/)
+  end
+
+  it "rejects an undated or badly dated release" do
+    changelog.call("## [1.0.0]\n\n### Added\n\n- x\n").problems.first.should.match(/has no date/)
+    changelog.call("## [1.0.0] - 20260101\n\n### Added\n\n- x\n").problems.first.should.match(/malformed date/)
+  end
+
+  it "rejects an unknown section type" do
+    changelog.call("## [1.0.0] - 2026-01-01\n\n### Improved\n\n- x\n")
+      .problems.first.should.match(/unknown section "Improved"/)
+  end
+
+  it "rejects an empty release and an empty subsection" do
+    changelog.call("## [1.0.0] - 2026-01-01\n").problems.first.should.match(/has no Added/)
+    changelog.call("## [1.0.0] - 2026-01-01\n\n### Added\n\n## [0.9.0] - 2026-01-01\n\n### Added\n\n- x\n")
+      .problems.first.should.match(/empty `### Added` section/)
+  end
+
+  it "rejects duplicates and out-of-order releases" do
+    body = "## [1.0.0] - 2026-01-02\n\n### Added\n\n- x\n\n## [1.0.0] - 2026-01-01\n\n### Added\n\n- y\n"
+    changelog.call(body).problems.first.should.match(/duplicate section for 1\.0\.0/)
+
+    body = "## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n\n## [2.0.0] - 2026-01-02\n\n### Added\n\n- y\n"
+    changelog.call(body).problems.first.should.match(/must run newest to oldest/)
+  end
+
+  it "requires [Unreleased] to come first" do
+    body = "## [1.0.0] - 2026-01-01\n\n### Added\n\n- x\n\n## [Unreleased]\n"
+    changelog.call(body).problems.first.should.match(/\[Unreleased\] must be the first section/)
+  end
+
+  it "blocks a release with no section of its own" do
+    changelog.call(good).release_problems("9.9.9").first.should.match(/no section for 9\.9\.9/)
+  end
+
+  it "blocks a release that is not the newest section" do
+    changelog.call(good).release_problems("4.0.0").first.should.match(/lists 4\.1\.0 above 4\.0\.0/)
+  end
+
+  it "reports format problems ahead of release problems" do
+    changelog.call("## nonsense\n").release_problems("4.1.0").first.should.match(/malformed version heading/)
+  end
+
+  it "loads the repo's own CHANGELOG.md" do
+    Gem::Deprecate.skip_during { Brute::Changelog.load.missing?.should.be.false }
+  end
+end

data/lib/brute/completion/open_router.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Brute
+  # Completion middlewares — the terminal step of an agent turn. Each one is a
+  # ready-made replacement for the hand-written `run` proc: it takes
+  # env[:messages], calls one provider, and appends the reply back onto the log.
+  #
+  #   Brute.agent
+  #     .use(Brute::Middleware::SystemPrompt)
+  #     .run(Brute::Completion::OpenRouter.new(model: "anthropic/claude-sonnet-4"))
+  #
+  # Brute still owns no LLM library: each class here requires only the gem for
+  # its own provider, and only when you use it.
+  module Completion
+    class OpenRouter
+      # config:   keyword arguments for OpenRouter::Client.new
+      #           (access_token:, request_timeout:, uri_base:, extra_headers:).
+      #           Defaults to OpenRouter.configuration's global settings.
+      # options:  keyword arguments for OpenRouter::CompletionOptions.new
+      #           (model:, temperature:, tools:, ...).
+      def initialize(app, config: {}, **options)
+        @app = app
+        @config = config
+        @options = ::OpenRouter::CompletionOptions.new(**options)
+      end
+
+      def call(env)
+        env[:hooks]&.emit(:before_llm, env)
+
+        messages = Brute::MessageTransport::OpenRouter.dump_all(env[:messages])
+
+        ::OpenRouter::Client.new(**@config).then do |client|
+          client.complete(messages, @options).then do |response|
+
+            # Expose the provider's usage for downstream accounting
+            # middleware (goal budgets, autonomous limits, compaction
+            # thresholds, usage attribution) — additive metadata only.
+            if response.respond_to?(:usage) && response.usage
+              (env[:metadata] ||= {})[:last_llm_usage] = response.usage
+            end
+
+            # OpenRouter in fact only returns a single message...
+            # https://github.com/estiens/open_router_enhanced/blob/main/lib/open_router/response.rb
+            Brute::MessageTransport::OpenRouter.wrap_each(response) do |message|
+              env[:messages] << message
+            end
+          end
+        end
+
+        env[:hooks]&.emit(:after_llm, env)
+        env
+      end
+    end
+  end
+end
+
+__END__
+
+describe "brute/completion/open_router" do
+  require "brute/messages"
+
+  # The repo suite has no open_router gem; stub the two constants the
+  # middleware touches (the transport wraps duck-typed responses fine).
+  begin
+    require "open_router"
+  rescue LoadError
+    module OpenRouter
+      CompletionOptions = Class.new { def initialize(**_opts); end }
+      Client = Class.new
+    end
+  end
+
+  FakeUsageResponse = Struct.new(:usage) do
+    def choices
+      [{ "message" => { "role" => "assistant", "content" => "hello" } }]
+    end
+  end unless defined?(FakeUsageResponse)
+
+  # Run one turn against a stubbed OpenRouter::Client and hand back the env.
+  with_fake_client = lambda do |middleware, response|
+    fake_client = Object.new
+    fake_client.define_singleton_method(:complete) { |_messages, _options| response }
+    original = OpenRouter::Client.method(:new)
+    OpenRouter::Client.define_singleton_method(:new) { |**_config| fake_client }
+    begin
+      env = { messages: Brute.log }
+      env[:messages].user("hi")
+      middleware.call(env)
+      env
+    ensure
+      OpenRouter::Client.define_singleton_method(:new, original)
+    end
+  end
+
+  it "records the provider usage into env metadata and appends the message" do
+    response = FakeUsageResponse.new({ "prompt_tokens" => 10, "completion_tokens" => 5, "total_tokens" => 15 })
+    env = with_fake_client.call(Brute::Completion::OpenRouter.new(->(e) { e }), response)
+
+    env[:messages].last.role.should == :assistant
+    env[:metadata][:last_llm_usage]["total_tokens"].should == 15
+  end
+
+  it "leaves metadata alone when the response has no usage" do
+    env = with_fake_client.call(Brute::Completion::OpenRouter.new(->(e) { e }), FakeUsageResponse.new(nil))
+
+    env.key?(:metadata).should.be.false
+  end
+
+  it "still answers to the deprecated Middleware::OpenRouter::Completion name" do
+    deprecated = Brute::Middleware::OpenRouter::Completion.new(->(e) { e })
+    deprecated.should.be.kind_of?(Brute::Completion::OpenRouter)
+
+    env = with_fake_client.call(deprecated, FakeUsageResponse.new(nil))
+    env[:messages].last.content.should == "hello"
+  end
+end

data/lib/brute/contrib/log_file.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "file/tail"
+require "fileutils"
+
+module Brute
+  module Contrib
+    # A line-oriented, append-only log file that doubles as a work queue.
+    #
+    # Every entry is exactly one line — newlines in the input are folded to
+    # spaces on the way in — so a line is the unit of both storage and
+    # retrieval. Reads are destructive: `pop` takes the newest line off the
+    # end, `drain` yields every line oldest-first and empties the file.
+    #
+    #   log = Brute::Contrib::LogFile.new("tmp/queue.log")
+    #   log.append("something happened")
+    #   log.pop            # => "something happened"
+    #   log.drain { |line| handle(line) }
+    #
+    # Safe across both threads (a mutex) and processes (an exclusive flock),
+    # so several agents can share one file without losing lines.
+    class LogFile < File
+      include File::Tail
+
+      def initialize(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        super(path, File::RDWR | File::CREAT | File::APPEND)
+        @mutex = Mutex.new
+      end
+
+      # Append one line. Blank (or whitespace-only) input is a no-op and
+      # returns nil; otherwise returns the stripped line that was written.
+      def append(line)
+        strip_whitespace(line).then do |stripped_text|
+          unless stripped_text.empty?
+            locked do
+              puts(stripped_text)
+              flush
+              stripped_text
+            end
+          end
+        end
+      end
+
+      # Remove and return the newest line, or nil when the file is empty.
+      def pop
+        locked do
+          backward(1)
+          offset = tell
+          gets&.chomp.tap { truncate(offset) }
+        end
+      end
+
+      # Yield every line oldest-first, then empty the file. Requires a block —
+      # without one there is nowhere for the lines to go, so it raises rather
+      # than discarding them.
+      def drain
+        locked do
+          if block_given?
+            backward(line_count)
+            each_line { |x| yield x.chomp }
+            truncate(0)
+          else
+            raise "No block given..."
+          end
+        end
+      end
+
+      private
+
+        def line_count
+          rewind
+          each_line.count
+        end
+
+        def strip_whitespace(line)
+          line.to_s.gsub(/\r?\n/, " ").strip
+        end
+
+        def locked
+          @mutex.synchronize do
+            flock(File::LOCK_EX)
+            yield
+          ensure
+            flock(File::LOCK_UN)
+          end
+        end
+    end
+  end
+end
+
+__END__
+
+require "tmpdir"
+
+describe "brute/contrib/log_file" do
+  it "pops the last line, then nothing" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("first")
+      log.append("second")
+
+      log.pop.should == "second"
+      log.pop.should == "first"
+      log.pop.should.be.nil
+    end
+  end
+
+  it "keeps one entry on one line" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("two\nlines")
+      log.append("   ")
+
+      log.pop.should == "two lines"
+      log.pop.should.be.nil
+    end
+  end
+
+  it "loses no line to concurrent threads" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      4.times.map { |i| Thread.new { 50.times { |j| log.append("p#{i}-#{j}") } } }.each(&:join)
+
+      popped = []
+      4.times.map { Thread.new { while (line = log.pop) do popped << line end } }.each(&:join)
+
+      popped.uniq.size.should == 200
+      File.size(log.path).should == 0
+    end
+  end
+
+  it "drains every line, oldest first, and empties the file" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("first")
+      log.append("second")
+      log.append("third")
+
+      drained = []
+      log.drain { |line| drained << line }
+
+      drained.should == ["first", "second", "third"]
+      File.size(log.path).should == 0
+      log.pop.should.be.nil
+    end
+  end
+
+  it "refuses to drain without a block, leaving the lines alone" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("first")
+      log.append("second")
+
+      lambda { log.drain }.should.raise(RuntimeError)
+
+      File.read(log.path).should == "first\nsecond\n"
+      log.pop.should == "second"
+    end
+  end
+
+  it "keeps appending after a drain" do
+    Dir.mktmpdir do |dir|
+      log = Brute::Contrib::LogFile.new(File.join(dir, "log"))
+      log.append("before")
+      log.drain { |line| line }
+      log.append("after")
+
+      log.pop.should == "after"
+      log.pop.should.be.nil
+    end
+  end
+end