net-ssh 8.0.2 → 8.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96690db72c35721670d94d15faf150030ae24a696b2eecc9f9b174eadaa892a2
-  data.tar.gz: b5d55d232f256442dfdc344b6a18384872fdc1f7c2d7ced93f7e6dec1890f02c
+  metadata.gz: 110d479784d8cc56b52a5a3e9b14e5f23dbf556873b64a8e1563df31b1205911
+  data.tar.gz: e0f0d31f6476b896ddc6354906cc1b861f99687365a0783527b738e69f4d4e15
 SHA512:
-  metadata.gz: e6ebb241e5088fd5b25402bafca4c6152e56da239a3e6bb0124ab84b9944ba7bb91506c6aef17bcb84e021f92335440d8e08f1fce4726189179d65c61150098f
-  data.tar.gz: ff9a4c3de691cce2a5cf9e1bb6a647b98663351ab6f896198ee519c6f040e0b767382ad499b7d3907446e52afbc98f485df2a126612da78aaba2d76fc80e563f
+  metadata.gz: 985c71acd2df6c9e5a287c8e64c6e960cd80bd47c5d18837e1381a7c38f09ee2bbad51e3946f8d26d5f467c4999fca322e3ce4b48aa16115c2d434f675cf52cd
+  data.tar.gz: 81a1286e7e73a6c6b17a4a64e5c5004844a734bfa0118d39041ff291eb0e364c9fa4d3777cd7c745fb0ba038bd1aed2cef191b9c001cfb47937b7154a0506813

data/.github/workflows/changelog.yml

@@ -9,35 +9,10 @@ permissions:
 
 jobs:
   changelog:
-    if: ${{ github.event.pull_request.user.login != 'dependabot[bot]' }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
           # HEAD is the PR merged into the base branch; HEAD^1 is the base it was merged into.
           fetch-depth: 2
-      - name: Set up Ruby 3.1
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.1
-      - name: Validate fragments
-        run: rake changelog:check
-      - name: Require a fragment
-        if: ${{ !contains(github.event.pull_request.labels.*.name, 'skip-changelog') }}
-        env:
-          PR: ${{ github.event.number }}
-        run: |
-          changed=$(git diff --name-only HEAD^1 HEAD)
-          if echo "$changed" | grep -x 'CHANGES\.txt' > /dev/null; then
-            echo "::error::Don't edit CHANGES.txt, add a changelog.d/$PR.<type>.txt fragment instead, see CONTRIBUTING.md#changelog"
-            exit 1
-          fi
-          own=$(git diff --name-only --diff-filter=AMR HEAD^1 HEAD -- changelog.d/ | grep -E "^changelog\.d/$PR\.[a-z-]+(\.[0-9]+)?\.txt$" || true)
-          if [ -n "$own" ]; then
-            echo "Changelog fragments:"; echo "$own"
-          elif ! echo "$changed" | grep -v '^changelog\.d/' > /dev/null; then
-            echo "Only changelog.d/ changed, no fragment needed"
-          else
-            echo "::error::Add a changelog fragment named changelog.d/$PR.<type>.txt (use $PR.none.txt if nothing user-visible changed), see CONTRIBUTING.md#changelog"
-            exit 1
-          fi
+      - uses: net-ssh/changelogd@v1

data/CHANGES.txt

@@ -1,3 +1,11 @@
+=== 8.0.4
+
+  * Security: validate every ProxyJump hop, not only the first, as [user@]host[:port] (refusing a path, query, fragment or password) and shell-escape the hops passed to ssh -J; a hop such as `evil/x&$(cmd)` ran `cmd` through the shell [GHSA-g2r2-x3p2-5677]
+
+=== 8.0.3
+
+  * Add `preopen_channels` option: keep a spare session channel open so each command saves a round trip [#1071]
+
 === 8.0.2
 
   * Fixed `Session#close` raising `EOFError: cannot send data if channel has declared eof` when a forwarded connection still had unread data from its local client; data net-ssh had already read is still sent before the EOF and, as in OpenSSH, the rest is dropped; a regression in 8.0.0 [#1066, #1067]

data/CONTRIBUTING.md

@@ -6,7 +6,7 @@ Run the unit tests with `bundle exec rake test` and the linter with `bundle exec
 
 Don't edit `CHANGES.txt`. Instead, add a fragment file to `changelog.d/` in your PR; the release's version bump (`rake vbump:*`) moves all fragments into a new `=== <version>` section at the top of `CHANGES.txt` and deletes them.
 
-A fragment is named `<number>.<type>.txt`, where `<number>` is the PR number (so open the PR first, then add the fragment), and contains a single UTF-8 paragraph: the entry as it should read in `CHANGES.txt`, without the bullet or prefix. Lines are joined, so it can be wrapped. If it doesn't end with a reference list such as `[#985, #1056]`, `[GHSA-xxxx-xxxx-xxxx]` or `[CVE-2024-12345, #1060]`, ` [#<number>]` is appended; write the list yourself to reference issues or advisories too.
+A fragment is named `<number>.<type>.txt`, where `<number>` is the PR number (so open the PR first, then add the fragment), and contains a single UTF-8 paragraph: the entry as it should read in `CHANGES.txt`, without the bullet or prefix. Lines are joined, so it can be wrapped. If it doesn't end with a reference list such as `[#985, #1056]` or `[GHSA-xxxx-xxxx-xxxx]`, ` [#<number>]` is appended.
 
 | Type                | Written as                     | Use for                                                      |
 | ------------------- | ------------------------------ | ------------------------------------------------------------ |
@@ -24,12 +24,11 @@ rake "changelog:new[1058,change,Session#exec! now returns the exit status]"
 
 echo 'Removed the `:paranoid` option; use `:verify_host_key` [#1050]' > changelog.d/1050.breaking.txt
 echo 'Reject packet lengths above 256 KB, as OpenSSH does [GHSA-pfqh-p9vh-wx4p]' > changelog.d/1060.security.txt
-echo 'Custom verifiers must implement `verify_signature` [#1050]' > changelog.d/1050.breaking-security.txt
 touch changelog.d/1061.none.txt
 ```
 
 For several entries from one PR add a suffix: `1050.breaking.txt`, `1050.breaking.2.txt` (`changelog:new` picks the next free one).
 
-In a release section, entries are grouped as `BREAKING: Security:`, `BREAKING:`, `Security:`, then the rest; within a group fragments are ordered by number, newest first, followed by any hand-written entries from an `=== Unreleased` section in their written order. A final release with nothing to report still gets a `=== <version>` section saying `No changes since <previous version>.`
+`rake changelog:check` validates the fragments and `rake changelog:preview` prints the section the next release would add. CI fails a PR that edits `CHANGES.txt` or doesn't add or modify a `changelog.d/<PR number>.<type>.txt` fragment, unless it only touches `changelog.d/` or a maintainer adds the `skip-changelog` label; Dependabot PRs are skipped.
 
-`rake changelog:check` validates the fragments and the `=== Unreleased` section, and `rake changelog:preview` prints the section the next release would add. CI fails a PR that edits `CHANGES.txt` or doesn't add or modify a `changelog.d/<PR number>.<type>.txt` fragment, unless it only touches `changelog.d/` or a maintainer adds the `skip-changelog` label; Dependabot PRs are skipped.
+The full rules, including how a release orders the entries, are in the [changelogd README](https://github.com/net-ssh/changelogd#readme).

data/Gemfile

@@ -3,6 +3,8 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in mygem.gemspec
 gemspec
 
+gem "changelogd", git: "https://github.com/net-ssh/changelogd.git", tag: "v1", group: :development
+
 gem 'byebug', group: %i[development test] if !Gem.win_platform? && RUBY_ENGINE == "ruby"
 
 if ENV["CI"]

data/Rakefile

@@ -28,9 +28,18 @@ CLEAN.include ['pkg', 'rdoc']
 name = "net-ssh"
 
 require_relative "lib/net/ssh/version"
-require_relative "rakelib/changelog"
 version = Net::SSH::Version::CURRENT
 
+begin
+  require "changelogd/rake"
+rescue LoadError
+  # A git gem isn't on the load path under plain `rake`, as the release workflow runs it; bundler/setup could clash with the running rake.
+  require "bundler"
+  $LOAD_PATH.unshift(*Bundler.definition.specs["changelogd"].flat_map(&:full_require_paths))
+  require "changelogd/rake"
+end
+Changelogd::RakeTasks.new(version_file: "lib/net/ssh/version.rb")
+
 extra_files = %w[LICENSE.txt THANKS.txt CHANGES.txt]
 if defined?(RDoc::Task)
   RDoc::Task.new do |rdoc|
@@ -63,6 +72,7 @@ namespace :cert do
 end
 
 def change_version(&block)
+  Rake::Task["changelog:check"].invoke
   version_file = 'lib/net/ssh/version.rb'
   require_relative version_file
   pre = Net::SSH::Version::PRE
@@ -110,17 +120,9 @@ def change_version(&block)
     raise ArgumentError, "Cound not find line: TINY = \"#{tiny}\" in #{version_file}" unless found[:tiny] || new_tiny == tiny
   end
 
-  begin
-    heading = Changelog.heading(Net::SSH::Version::MAJOR, Net::SSH::Version::MINOR, new_tiny, new_pre)
-    section = Changelog.new(__dir__).release(heading)
-  rescue StandardError
-    FileUtils.rm_f "#{version_file}.new"
-    raise
-  end
-  puts section ? "Added to CHANGES.txt:\n#{section}" : "Nothing to release for a pre-release, CHANGES.txt unchanged"
-
   FileUtils.mv version_file, "#{version_file}.old"
   FileUtils.mv "#{version_file}.new", version_file
+  Rake::Task["changelog:release"].invoke
 end
 
 namespace :vbump do
@@ -158,44 +160,6 @@ namespace :vbump do
   end
 end
 
-namespace :changelog do
-  changelog = Changelog.new(__dir__)
-
-  desc "Validate the fragments in changelog.d/"
-  task :check do
-    count = changelog.check.size
-    puts "#{count} valid changelog fragment#{'s' unless count == 1}"
-  rescue Changelog::Error => e
-    abort e.message
-  end
-
-  desc "Print the CHANGES.txt section the next version bump would write"
-  task :preview, [:heading] do |_t, args|
-    puts changelog.section(args[:heading] || "Unreleased") || "Nothing to release"
-  rescue Changelog::Error => e
-    abort e.message
-  end
-
-  desc "Create a fragment: rake \"changelog:new[1234,change,Text of the entry]\""
-  task :new, [:number, :type] do |_t, args|
-    abort "Usage: rake \"changelog:new[<PR number>,<#{Changelog::TYPES.keys.join('|')}>,<text>]\"" unless args[:number] && args[:type]
-    # Rake splits arguments on commas and strips the spaces around them, so take the text from the raw task string.
-    raw = Rake.application.top_level_tasks.find { |t| t.start_with?("changelog:new[") }
-    text = raw&.[](/\A[^\[]*\[[^,]*,[^,]*,\s*(.*)\]\z/m, 1) || args.extras.join(", ")
-    puts "Created #{changelog.new_fragment(args[:number], args[:type], text)}"
-  rescue Changelog::Error => e
-    abort e.message
-  end
-
-  desc "Write the fragments to CHANGES.txt under a heading, e.g. rake \"changelog:release[7.3.4]\" (vbump does this)"
-  task :release, [:heading] do |_t, args|
-    abort "Usage: rake \"changelog:release[<version heading>]\"" unless args[:heading]
-    puts changelog.release(args[:heading]) || "Nothing to release"
-  rescue Changelog::Error => e
-    abort e.message
-  end
-end
-
 namespace :rdoc do
   desc "Update gh-pages branch"
   task :publish do

data/lib/net/ssh/connection/session.rb

@@ -53,6 +53,10 @@ module Net
         # The list of callbacks for pending requests. See #send_global_request.
         attr_reader :pending_requests # :nodoc:
 
+        # A "session" channel opened ahead of time by :preopen_channels, and
+        # the server's confirmation for it once that has arrived.
+        SpareChannel = Struct.new(:local_id, :remote_id, :window_size, :packet_size) # :nodoc:
+
         class NilChannel
           def initialize(session)
             @session = session
@@ -84,6 +88,11 @@ module Net
           @max_pkt_size = (options.key?(:max_pkt_size) ? options[:max_pkt_size] : 0x8000)
           @max_win_size = (options.key?(:max_win_size) ? options[:max_win_size] : Channel::DEFAULT_MAX_WIN_SIZE)
 
+          @preopen_channels = options.fetch(:preopen_channels, false)
+          @spare_channel = nil
+          @spare_wanted = false
+          @preopened = []
+
           @keepalive = Keepalive.new(self)
 
           @event_loop = options[:event_loop] || SingleSessionEventLoop.new
@@ -121,6 +130,7 @@ module Net
         # successfully closed, and then closes the underlying transport layer
         # connection.
         def close
+          stop_preopening
           info { "closing remaining channels (#{channels.length} open)" }
 
           channels.each do |id, channel|
@@ -143,6 +153,7 @@ module Net
         # when the connection needs to close but you don't know the status of the
         # underlying protocol's state).
         def shutdown!
+          stop_preopening
           transport.shutdown!
         end
 
@@ -258,8 +269,10 @@ module Net
         # Called by event loop to process available data before going to
         # event multiplexing
         def ev_preprocess(&block)
+          confirm_preopened_channels
           dispatch_incoming_packets(raise_disconnect_errors: false)
           each_channel { |id, channel| channel.process unless channel.local_closed? }
+          open_spare_channel
         end
 
         # Returns the file descriptors the event loop should wait for read/write events,
@@ -348,14 +361,20 @@ module Net
         #   end
         #
         #   channel.wait
+        #
+        # With the :preopen_channels option a plain "session" channel reuses
+        # the spare opened ahead of time, if there is one. Its callback still
+        # runs from the event loop, as if the server had just confirmed it.
         def open_channel(type = "session", *extra, &on_confirm)
-          local_id = get_next_channel_id
+          spare = take_spare_channel if type == "session" && extra.empty?
+          local_id = spare ? spare.local_id : get_next_channel_id
 
           channel = Channel.new(self, type, local_id, @max_pkt_size, @max_win_size, &on_confirm)
-          msg = Buffer.from(:byte, CHANNEL_OPEN, :string, type, :long, local_id,
-                            :long, channel.local_maximum_window_size,
-                            :long, channel.local_maximum_packet_size, *extra)
-          send_message(msg)
+          if spare
+            @preopened << [channel, spare] if spare.remote_id
+          else
+            send_channel_open(type, channel.local_id, channel.local_maximum_window_size, channel.local_maximum_packet_size, *extra)
+          end
 
           channels[local_id] = channel
         end
@@ -603,6 +622,8 @@ module Net
         end
 
         def force_channel_cleanup_on_close
+          stop_preopening
+          @preopened.clear
           channels.each do |id, channel|
             channel_closed(channel)
           end
@@ -694,18 +715,37 @@ module Net
 
         def channel_open_confirmation(packet)
           info { "channel_open_confirmation: #{packet[:local_id]} #{packet[:remote_id]} #{packet[:window_size]} #{packet[:packet_size]}" }
+          if (spare = spare_channel(packet))
+            spare.remote_id = packet[:remote_id]
+            spare.window_size = packet[:window_size]
+            spare.packet_size = packet[:packet_size]
+            return
+          end
+
           channel = channels[packet[:local_id]]
           channel.do_open_confirmation(packet[:remote_id], packet[:window_size], packet[:packet_size])
         end
 
         def channel_open_failure(packet)
           error { "channel_open_failed: #{packet[:local_id]} #{packet[:reason_code]} #{packet[:description]}" }
+          if spare_channel(packet)
+            info { "preopen_channels: server refused the spare channel, no longer pre-opening" }
+            stop_preopening
+            @spare_channel = nil
+            return
+          end
+
           channel = channels.delete(packet[:local_id])
           channel.do_open_failed(packet[:reason_code], packet[:description])
         end
 
         def channel_window_adjust(packet)
           info { "channel_window_adjust: #{packet[:local_id]} +#{packet[:extra_bytes]}" }
+          if (spare = spare_channel(packet))
+            spare.window_size += packet[:extra_bytes]
+            return
+          end
+
           channels[packet[:local_id]].do_window_adjust(packet[:extra_bytes])
         end
 
@@ -726,11 +766,20 @@ module Net
 
         def channel_eof(packet)
           info { "channel_eof: #{packet[:local_id]}" }
+          return if spare_channel(packet)
+
           channels[packet[:local_id]].do_eof
         end
 
         def channel_close(packet)
           info { "channel_close: #{packet[:local_id]}" }
+          if (spare = spare_channel(packet))
+            send_message(Buffer.from(:byte, CHANNEL_CLOSE, :long, spare.remote_id))
+            @spare_channel = nil
+            # Wait for the next plain open_channel before opening another, so a server closing spares can't make us loop.
+            @spare_wanted = false
+            return
+          end
 
           channel = channels[packet[:local_id]]
           channel_closed(channel)
@@ -746,6 +795,45 @@ module Net
           channels[packet[:local_id]].do_failure
         end
 
+        def send_channel_open(type, local_id, window_size, packet_size, *extra)
+          send_message(Buffer.from(:byte, CHANNEL_OPEN, :string, type, :long, local_id,
+                                   :long, window_size, :long, packet_size, *extra))
+        end
+
+        def take_spare_channel
+          return unless @preopen_channels
+
+          @spare_wanted = true
+          spare = @spare_channel
+          @spare_channel = nil
+          spare
+        end
+
+        def open_spare_channel
+          return unless @spare_wanted && @preopen_channels && @spare_channel.nil? && !closed?
+
+          @spare_channel = SpareChannel.new(get_next_channel_id)
+          info { "preopen_channels: opening spare channel #{@spare_channel.local_id}" }
+          send_channel_open("session", @spare_channel.local_id, @max_win_size, @max_pkt_size)
+        end
+
+        # An unused spare is never closed, as that would cost round trips just before the transport goes away;
+        # it stays in @spare_channel to absorb the server's late replies for it.
+        def stop_preopening
+          @preopen_channels = false
+        end
+
+        def confirm_preopened_channels
+          until @preopened.empty?
+            channel, spare = @preopened.shift
+            channel.do_open_confirmation(spare.remote_id, spare.window_size, spare.packet_size)
+          end
+        end
+
+        def spare_channel(packet)
+          @spare_channel if @spare_channel && @spare_channel.local_id == packet[:local_id]
+        end
+
         def io_select_wait(wait)
           [wait, max_select_wait_time].compact.min
         end

data/lib/net/ssh/proxy/jump.rb

@@ -54,20 +54,21 @@ module Net
         # We cannot build the ProxyCommand template until we know if the :config
         # option was specified during `Net::SSH.start`.
         def build_proxy_command_equivalent(connection_options = nil)
-          extra_jumps = jump_proxies.split(",", 2)[1]
+          raise ArgumentError, "no jump host given" if jump_proxies.empty?
+
           config = connection_options && connection_options[:config]
-          uri, = jump_proxies.split(",").map { |jump| validate_jump!(jump) }
+          uri, *extra_jumps = jump_proxies.split(",", -1).map { |jump| validate_jump!(jump) }
 
           template = "ssh".dup
-          template << " -l #{uri.user}"    if uri.user
-          template << " -p #{uri.port}"    if uri.port
-          template << " -J #{extra_jumps}" if extra_jumps
+          template << " -l #{escape(uri.user)}" if uri.user
+          template << " -p #{uri.port}" if uri.port
+          template << " -J #{escape(extra_jumps.map { |jump| jump_spec(jump) }.join(','))}" unless extra_jumps.empty?
           template << " -F #{escape(config)}" if config != true && config
           @options.each do |key, values|
             Array(values).each { |value| template << " -o #{escape(key)}=#{escape(value)}" }
           end
           template << " -W %h:%p "
-          template << uri.host
+          template << escape(uri.host)
 
           @command_line_template = template
         end
@@ -90,11 +91,25 @@ module Net
           Shellwords.escape(value).gsub("%", "%%")
         end
 
+        # Only [user@]host[:port] is checked, so anything else URI accepts (a path,
+        # query, fragment or password) must be refused before it reaches the shell.
         def validate_jump!(jump)
           uri = URI.parse("ssh://#{jump}")
+          raise URI::InvalidURIError if uri.host.to_s.empty? || jump_spec(uri) != jump
+
           validate_user_name!(uri.user) if uri.user
           validate_host_name!(uri.host)
+          validate_port!(uri.port) if uri.port
           uri
+        rescue URI::InvalidURIError
+          raise ArgumentError, "jump host is not [user@]host[:port]: #{jump.inspect}"
+        end
+
+        def jump_spec(uri)
+          spec = uri.host.dup
+          spec.prepend("#{uri.user}@") if uri.user
+          spec << ":#{uri.port}" if uri.port
+          spec
         end
       end
     end

data/lib/net/ssh/version.rb

@@ -52,7 +52,7 @@ module Net
       MINOR = 0
 
       # The tiny component of this version of the Net::SSH library
-      TINY  = 2
+      TINY  = 4
 
       # The prerelease component of this version of the Net::SSH library
       # nil allowed

data/lib/net/ssh.rb

@@ -71,7 +71,7 @@ module Net
       append_all_supported_algorithms non_interactive password_prompt
       agent_socket_factory minimum_dh_bits verify_host_key
       fingerprint_hash check_host_ip pubkey_algorithms no_delay
-      control_master control_path
+      control_master control_path preopen_channels
     ]
 
     # The standard means of starting a new SSH connection. When used with a
@@ -221,6 +221,12 @@ module Net
     #   is +nil+, for no passphrase)
     # * :password => the password to use to login
     # * :port => the port to use when connecting to the remote host
+    # * :preopen_channels => set to +true+ to keep one spare "session" channel
+    #   open, so that Net::SSH::Connection::Session#open_channel can hand it
+    #   out at once and a command that waits for the previous one to finish
+    #   costs one round trip instead of two. The spare counts against the
+    #   server's MaxSessions; if the server refuses it, pre-opening stops for
+    #   the session. Defaults to +false+.
     # * :properties => a hash of key/value pairs to add to the new connection's
     #   properties (see Net::SSH::Connection::Session#properties)
     # * :proxy => a proxy instance (see Proxy) to use when connecting

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-ssh
 version: !ruby/object:Gem::Version
-  version: 8.0.2
+  version: 8.0.4
 platform: ruby
 authors:
 - Jamis Buck
@@ -32,7 +32,7 @@ cert_chain:
   ufHf4AX2UIkJbh7zCPkiNCqIr7MSWLNFG/9lOlHYsEJM8XujT1ofPobYx6YSFx/C
   7HBrI7UX7awt6UvBZebhcHzyMHxg/B5PVQllPA==
   -----END CERTIFICATE-----
-date: 2026-10-22 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -324,7 +324,6 @@ files:
 - lib/net/ssh/version.rb
 - net-ssh-public_cert.pem
 - net-ssh.gemspec
-- rakelib/changelog.rb
 - support/ssh_tunnel_bug.rb
 homepage: https://github.com/net-ssh/net-ssh
 licenses:

data/rakelib/changelog.rb

@@ -1,229 +0,0 @@
-# frozen_string_literal: true
-
-require 'fileutils'
-require 'open3'
-
-# Builds CHANGES.txt sections from the fragment files in changelog.d/ (see CONTRIBUTING.md).
-class Changelog
-  class Error < StandardError; end
-
-  # Output order of the groups in a release section; `none` fragments are never emitted.
-  TYPES = {
-    'breaking-security' => 'BREAKING: Security: ',
-    'breaking' => 'BREAKING: ',
-    'security' => 'Security: ',
-    'change' => '',
-    'none' => nil
-  }.freeze
-
-  FILENAME = /\A(?<number>[1-9]\d*)\.(?<type>[a-z-]+)(?:\.(?<seq>[1-9]\d*))?\.txt\z/.freeze
-  REF = /#\d+|GHSA(?:-[a-z0-9]{4}){3}|CVE-\d{4}-\d+/i.freeze
-  REF_LIST = /\[(?:#{REF})(?:,\s*(?:#{REF}))*\]\z/.freeze
-  UNRELEASED = '=== Unreleased'
-  PLACEHOLDER = 'TODO: describe the change as it should read in CHANGES.txt'
-
-  Fragment = Struct.new(:path, :number, :type, :seq, :text) do
-    def entry
-      "#{TYPES.fetch(type)}#{text}"
-    end
-
-    def sort_key
-      [-number, seq]
-    end
-  end
-
-  attr_reader :dir, :changes_path
-
-  def initialize(root)
-    @root = root
-    @dir = File.join(root, 'changelog.d')
-    @changes_path = File.join(root, 'CHANGES.txt')
-  end
-
-  # Raises Error listing every invalid fragment; returns all fragments, including `none` ones.
-  def fragments
-    errors = []
-    fragments = []
-    entries_in_dir.each do |name|
-      result = parse_fragment(name)
-      result.is_a?(Fragment) ? fragments << result : errors << "changelog.d/#{name}: #{result}"
-    end
-    raise Error, "Invalid changelog fragments:\n  #{errors.join("\n  ")}" unless errors.empty?
-
-    fragments.sort_by(&:sort_key)
-  end
-
-  # Validates the fragments and the `=== Unreleased` section of CHANGES.txt; returns the fragments.
-  def check
-    all = fragments
-    split_changes(read_changes)
-    all
-  end
-
-  # The text of the section for +heading+, or nil for a pre-release with nothing to release.
-  def section(heading)
-    assemble(heading, fragments, split_changes(read_changes))
-  end
-
-  # Writes the section for +heading+ to the top of CHANGES.txt, folding in any `=== Unreleased`
-  # entries, and removes all fragments; returns the section, or nil when CHANGES.txt was left unchanged.
-  def release(heading)
-    all = fragments
-    content = read_changes
-    raise Error, "CHANGES.txt already has a '=== #{heading}' section" if content.lines.any? { |l| l.chomp == "=== #{heading}" }
-
-    parts = split_changes(content)
-    section = assemble(heading, all, parts)
-    if section
-      rest = parts[:rest].empty? ? '' : "\n#{parts[:rest]}"
-      File.write(changes_path, "#{parts[:preamble]}#{section}#{rest}")
-    end
-    remove(all.map(&:path))
-    section
-  end
-
-  # Creates a fragment for PR +number+ and returns its path; picks the next free `.N` suffix if needed.
-  def new_fragment(number, type, text = nil)
-    path = (1..).lazy.map { |seq| File.join(dir, fragment_name(number, type, seq)) }.find { |p| !File.exist?(p) }
-    error = validate_name(File.basename(path))
-    raise Error, error if error
-
-    FileUtils.mkdir_p(dir)
-    text = PLACEHOLDER if (text.nil? || text.strip.empty?) && type != 'none'
-    File.write(path, "#{text}\n")
-    path
-  end
-
-  def self.heading(major, minor, tiny, pre)
-    ["#{major}.#{minor}.#{tiny}", pre].compact.join(' ')
-  end
-
-  private
-
-  def entries_in_dir
-    return [] unless Dir.exist?(dir)
-
-    Dir.children(dir).sort.reject { |name| name == 'README.md' || name.start_with?('.') }
-  end
-
-  def fragment_name(number, type, seq)
-    seq == 1 ? "#{number}.#{type}.txt" : "#{number}.#{type}.#{seq}.txt"
-  end
-
-  def validate_name(name)
-    match = FILENAME.match(name)
-    return "file name must be <PR number>.<type>[.<n>].txt, types: #{TYPES.keys.join(', ')}" unless match
-    return "unknown type '#{match[:type]}', expected one of: #{TYPES.keys.join(', ')}" unless TYPES.key?(match[:type])
-
-    nil
-  end
-
-  # Returns a Fragment, or an error message.
-  def parse_fragment(name)
-    path = File.join(dir, name)
-    return 'is not a file' unless File.file?(path)
-
-    error = validate_name(name)
-    return error if error
-
-    match = FILENAME.match(name)
-    fragment = Fragment.new(path, match[:number].to_i, match[:type], (match[:seq] || 1).to_i, nil)
-    return fragment if fragment.type == 'none'
-
-    text = parse_text(read_utf8(path))
-    return text[:error] if text[:error]
-
-    fragment.text = text[:text]
-    fragment.text = "#{fragment.text} [##{fragment.number}]" unless fragment.text.match?(REF_LIST)
-    fragment
-  end
-
-  def parse_text(raw)
-    return { error: 'is not valid UTF-8' } unless raw.valid_encoding?
-
-    lines = raw.strip.lines.map(&:strip)
-    return { error: 'is empty' } if lines.empty?
-    return { error: 'must be a single paragraph (no blank lines)' } if lines.include?('')
-
-    text = lines.join(' ')
-    return { error: 'still contains the placeholder text' } if text == PLACEHOLDER
-    return { error: "should not start with a bullet, it's added when assembling" } if text.match?(/\A[*-] /)
-    return { error: 'should not start with BREAKING:/Security:, the type adds the prefix' } if text.match?(/\A(BREAKING|Security):/i)
-
-    { text: text }
-  end
-
-  def read_changes
-    File.exist?(changes_path) ? read_utf8(changes_path).gsub("\r\n", "\n") : ''
-  end
-
-  # Explicit so a non-UTF-8 locale (e.g. LANG=C) doesn't break on non-ASCII text.
-  def read_utf8(path)
-    File.read(path, mode: 'r:bom|utf-8')
-  end
-
-  # A final release (a heading without a pre-release suffix) always gets a section, so every published version has a heading.
-  def assemble(heading, fragments, parts)
-    entries = grouped_entries(fragments, parts[:unreleased])
-    if entries.empty?
-      return nil unless heading.match?(/\A\d+\.\d+\.\d+\z/)
-
-      previous = parts[:rest][/\A=== (.+)$/, 1]
-      entries = ["  * #{previous ? "No changes since #{previous}." : 'No changes.'}\n"]
-    end
-    "=== #{heading}\n\n#{entries.join}"
-  end
-
-  # Splits CHANGES.txt into the text before the first heading, the entries of a leading
-  # `=== Unreleased` section (as lists of raw lines) and everything from the first released heading on.
-  def split_changes(content)
-    lines = content.lines
-    first = lines.index { |l| l.start_with?('=== ') } || lines.size
-    preamble = lines[0...first].join
-    return { preamble: preamble, unreleased: [], rest: lines[first..].join } unless lines[first]&.chomp == UNRELEASED
-
-    body_end = lines.index.with_index { |l, i| i > first && l.start_with?('=== ') } || lines.size
-    { preamble: preamble, unreleased: unreleased_entries(lines[(first + 1)...body_end]), rest: lines[body_end..].join }
-  end
-
-  def unreleased_entries(lines)
-    lines.each_with_object([]) do |line, entries|
-      next if line.strip.empty?
-
-      if line.match?(/\A\s*\* /)
-        entries << [line]
-      elsif entries.empty?
-        raise Error, "Cannot parse the Unreleased section of CHANGES.txt near: #{line.strip}"
-      else
-        entries.last << line
-      end
-    end
-  end
-
-  # Fragments come before the hand-written Unreleased entries of the same group.
-  def grouped_entries(fragments, unreleased)
-    TYPES.keys.flat_map do |type|
-      from_fragments = fragments.select { |f| f.type == type && type != 'none' }.map { |f| "  * #{f.entry}\n" }
-      from_unreleased = unreleased.select { |lines| unreleased_type(lines.first) == type }.map do |lines|
-        lines.join.end_with?("\n") ? lines.join : "#{lines.join}\n"
-      end
-      from_fragments + from_unreleased
-    end
-  end
-
-  def unreleased_type(line)
-    text = line.sub(/\A\s*\* /, '')
-    TYPES.find { |_type, prefix| prefix && !prefix.empty? && text.start_with?(prefix) }&.first || 'change'
-  end
-
-  # `git rm` so the deletions are staged with the version bump; plain delete outside a git checkout.
-  def remove(paths)
-    return if paths.empty?
-
-    relative = paths.map { |p| p.delete_prefix("#{@root}/") }
-    _out, status = Open3.capture2e('git', '-C', @root, 'rm', '-q', '--', *relative)
-    FileUtils.rm_f(paths) unless status.success?
-  rescue SystemCallError
-    FileUtils.rm_f(paths)
-  end
-end