kettle-family 1.3.7 → 1.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec4f59e4397fe55738de3f0e3e482a2053d3c771716e9d94de40478f76ba80ae
-  data.tar.gz: 7ea569f07fa6cc8cc46cf5351cf93441ece85870c80ab51aed2458e0ce66346a
+  metadata.gz: 2768f1b7d61be1a362ef37070da39c0b5f0a6b6ea4137fa4c157e3eeaf3631ca
+  data.tar.gz: 43142009ed7af74c25116bef27ae083059c0d3afb8dbcc820180cdc47b9b13fd
 SHA512:
-  metadata.gz: 9dac940565396b2209bd67e957af7f2e015318d70572c05cca684e8de26c43d75755a142727d994baa5fbd646ce674fa7ab6c84bdb913ca9c6685824fd3beca6
-  data.tar.gz: 53c75a31e0896365a67c7b0ec46a45830d1e71abe37843dc715ee7f086f39166fbf39c36620efc0760d00848a6ce11238da0ee81cf84cfa6ced5e192e13178e4
+  metadata.gz: 3f5866f4a83b7783ee2607b64e208c6b10d7686dbc7121178b8d578e5d7f928c36e50e5a608634d11b8d879eb45317a10101372a82573e7a7d7d46c65d76c12b
+  data.tar.gz: 0f71c5f7b0c8705741a69870a937cfa994f6524bb4dc4922fcd6b69f4a84206b6093f4ec4ff949ad21e3854903bd45fb968cd30be994fcd3de617f37e86332e9

checksums.yaml.gz.sig

@@ -1,2 +1 @@
-O�PCn��
-�颍FH?=�IՈA���ًq$���C0D�qϱ�V�Od�{�q�n?g��z���A�0�	��f�H�
3�0Eϓ�=5N�8��̺Z�Cz�|T\������&t��P�B�fKU�v�'��Qoۮ;�Y�԰^hՏN�p��O���Iݑ���#�g��N|/�$��G��f���1CQG�[/s{&�N�WьE�r�3a{���q��%���;� �kZHI��1�!	�����2�*6�֦�jO��I?���e�ɻ�����O9��L�Je8;kQ����5�xzRM���0���-���|%#�:/�ꁞ!re��%�L�v��Vߒ����@<�ʧ�Rld+�U*s>�����C��
Ak
++�"��#ә��=���*@巨����d�M`�NEю4�'e��0����ׅ^��t��A�Z��P1�(%�	��J&]��;KçeJ���"E��$P��
�[/���=�u���7Ё=4��fa����:�k�a��{b%��E4�i)�Q��x��|�+�/-Ȫ+CR��y��L��`Ƽp�S@n��8���2�H�ul���q44��f�+af���/�⪾a��������x��U^�����~�M�pG@E6�Z�O��.�Q�+�o����V�R����S���o�������b�����	�"">�#�h;~�L
���y�t8�D;y4 ��JUQ�򒠜�L�4���~-�R�$�����W5���p�{d&P�F

data/CHANGELOG.md

@@ -30,6 +30,52 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.3.10] - 2026-10-11
+
+- TAG: [v1.3.10][1.3.10t]
+- COVERAGE: 93.42% -- 7072/7570 lines in 43 files
+- BRANCH COVERAGE: 77.96% -- 2837/3639 branches in 43 files
+- 35.42% documented
+
+### Fixed
+
+- Family release now tapes every child and aggregate event
+
+- the release command creates a ReleaseStateEventTape in execute mode and relays command_step, github_release, secret_provider and ci_monitor child events plus aggregate github_release events into it with the member attached; the tape preserves origin event type instead of rewriting it to release_state
+
+## [1.3.9] - 2026-10-10
+
+- TAG: [v1.3.9][1.3.9t]
+- COVERAGE: 93.43% -- 7068/7565 lines in 43 files
+- BRANCH COVERAGE: 77.95% -- 2832/3633 branches in 43 files
+- 35.42% documented
+
+### Added
+
+- New `clean-blockers` command uninstalls locally installed gems, from any family, whose unreleased versions are pinned by members’ lockfiles. Unlike `clean-unreleased`, which can only remove a family sibling newer than its latest release, it removes cross-family offenders: a kettle-dev member blocked by unreleased StructuredMerge gems, or vice versa.
+
+- Add clean-installed: the deterministic inverse of install. Uninstalls each selected member's current source version (plus configured install local_dependencies, which install also covers) when that version is unreleased, including cached .gem files. The other two cleanups cannot see this pollution class: clean-unreleased derives candidates from release state and can miss versions it judges released, and clean-blockers only sees lockfile pins, so an installed-but-unpinned gem (observed: commonmarker-merge 7.1.10) survives and then breaks gem activation with a dangling exact pin once the rest of its series is removed. Release state comes from the same ReleaseStateCheck clean-unreleased uses; members at a released source version are left alone. Also extracts MemberLoader from LocalInstall so install and clean-installed construct members identically.
+
+- Add a release-mode pre-clean to bup, bupb, and update-bundler: before a registry-only re-resolution, installed gems whose versions no registry publishes are removed, including cross-family gems named in member lockfiles. Previously the release-mode update only detected such pins after the fact (PublishedVersionCheck) and its advice to re-run the update was circular, because bundler resolves against the local gem dir and >= floors always re-pin the installed unreleased version. Removal up front turns that opaque post-update failure into a resolved-before-it-mattered cleanup. Fails open when the registry is unreachable: a network blip never removes gems. Also adds the standalone clean-installed command, the deterministic inverse of install, which uninstalls each member's unreleased source version (plus install local_dependencies) including cached .gem files.
+
+### Changed
+
+- [kc] kettle-jem/prepare: updated 2 project files:
+  - dependencies (2)
+
+- [kc] kettle-jem/template: updated 3 project files:
+  - code and tests (1)
+  - documentation (1)
+  - other (1)
+
+### Fixed
+
+- Add a structured CommandResult#diagnostics channel carrying complete, machine-readable findings. stdout is a human summary truncated to its last 20 lines, so a JSON consumer parsing it to decide what to act on silently acted on an incomplete set: a real cross-family release reported 28 unpublished lockfile pins and the JSON carried only 20, losing 8 gems. PublishedVersionCheck now emits each pin as gem, version, remote, member, and lockfile data alongside its message.
+
+- clean-blockers (and clean-unreleased, sharing GemUninstallSupport): two uninstall bugs fixed. The batched gem uninstall now retries once with --ignore-dependencies when RubyGems aborts on a dependent outside the batch (Gem::DependencyRemovalException), re-batching only what survived the abort; the dependency refusal previously left a partial cleanup reported as failure. And the cleanup now removes the cached .gem files as well as the installed specifications -- gem uninstall leaves cache/<name>-<version>.gem behind, and the next bundle install was reinstalling the same unreleased versions from that cache without touching the network, so the cleanup did not hold.
+
+- release: stop handing member kettle-release children the family-root dev bundle via BUNDLE_GEMFILE in release mode. That bundle resolves the family's own members, which are unreleased while any member is being released, so the child's kettle-release died booting (observed: "Could not find kettle-family-1.3.9 ... in locally installed gems" for every member). In release mode the child now resolves kettle-release from its own released dependency; local release tooling (KETTLE_DEV_DEV set) still pins the local kettle-dev bundle.
+
 ## [1.3.7] - 2026-10-09
 
 - TAG: [v1.3.7][1.3.7t]
@@ -2931,7 +2977,11 @@ Please file a bug if you notice a violation of semantic versioning.
 - Fixed CI load failures on engines without compatible `pty` support by falling back to Open3 for interactive release commands.
 - Fixed Ruby 3.2 version-bump support by loading Prism lazily and wiring the Prism gem only for MRI versions that need it.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.7...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.10...HEAD
+[1.3.10]: https://github.com/kettle-dev/kettle-family/compare/v1.3.9...v1.3.10
+[1.3.10t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.10
+[1.3.9]: https://github.com/kettle-dev/kettle-family/compare/v1.3.7...v1.3.9
+[1.3.9t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.9
 [1.3.7]: https://github.com/kettle-dev/kettle-family/compare/v1.3.6...v1.3.7
 [1.3.7t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.7
 [1.3.6]: https://github.com/kettle-dev/kettle-family/compare/v1.3.5...v1.3.6

data/README.md

@@ -501,6 +501,8 @@ The command names below are available from `kettle-family --help`:
 | `metadata` | Print member version, Ruby floor, license, and author metadata. |
 | `check` | Run internal read-only readiness checks. |
 | `clean-unreleased` | Uninstall locally installed family versions newer than released versions. |
+| `clean-blockers` | Uninstall unreleased gems, from any family, pinned by members' lockfiles — removes cross-family blockers such as an unreleased StructuredMerge gem pinned by a kettle-dev member. |
+| `clean-installed` | The deterministic inverse of `install`: uninstall each selected member's current source version (plus configured install local dependencies) when that version is unreleased, including cached `.gem` files. Sees installed-but-unpinned pollution the other two cleanups miss. |
 | `reconcile-releases` | Create verified missing GitHub Releases for published tags. |
 | `reset` | Reset a managed family artifact, such as release lockfiles. |
 | `test` | Run the configured test workflow for each selected member. |
@@ -751,6 +753,22 @@ The cleanup command compares installed local gem versions with each member's
 latest released version and uninstalls only versions newer than the release
 state reports.
 
+Two companion cleanups cover what `clean-unreleased` cannot see:
+
+```console
+kettle-family clean-blockers --execute
+kettle-family clean-installed --execute
+```
+
+`clean-blockers` targets cross-family pollution: unreleased gems from any
+family whose versions are pinned by members' lockfiles (e.g. an unreleased
+StructuredMerge gem pinned by a kettle-dev member). `clean-installed` is the
+deterministic inverse of `install` — it uninstalls a selected member's own
+current source version, and the local dependencies `install` covers, whenever
+that version is unreleased, including cached `.gem` files. Use it when an
+installed-but-unpinned version survives both other cleanups and breaks gem
+activation with a dangling exact pin.
+
 If a member lockfile has captured local sibling paths or checksum-less gem
 versions from local development, reset the selected members' `Gemfile.lock`
 files:
@@ -1192,7 +1210,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-7.231-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-7.570-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-family/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/kettle/family/blocker_cleanup.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "kettle/dev/lockfile_reset"
+
+module Kettle
+  module Family
+    # Removes locally installed gem versions that block a command, including gems
+    # belonging to OTHER families.
+    #
+    # Why this exists alongside +UnreleasedGemCleanup+ (`clean-unreleased`): that
+    # command derives candidates from family members' release state, so it can
+    # only ever remove a member of its own family whose installed version exceeds
+    # the latest release. The gems that actually block a release are usually
+    # cross-family, and each family is blocked by the other's legitimately
+    # installed development versions. Measured live:
+    #
+    #   kettle-dev        28 pins   ast-crispr 7.1.10, ast-merge, tree_haver, ...
+    #   kettle-drift      22 pins   (all structuredmerge gems)
+    #   kettle-family     28 pins   (all structuredmerge gems)
+    #   kettle-changelog   2 pins   nomono 1.1.7, token-resolver 2.0.13
+    #   kettle-jem         3 pins   kettle-test 2.0.24, nomono, token-resolver
+    #   smorg-rb           3 pins   (all kettle-dev gems)
+    #
+    # Neither family's `clean-unreleased` can see the other's offenders, which is
+    # what forced the kettle-dev 3.1.9 and kettle-family 1.3.7 releases to be
+    # finished manually after `gem push`: the tag, checksum and GitHub Release
+    # steps all run through a release-mode dependency update, and that cannot
+    # resolve while cross-family unreleased pins are present.
+    #
+    # The blocker set comes from calling PublishedVersionCheck directly on each
+    # selected member and reading its structured diagnostics, NOT from running the
+    # blocked command and parsing its report. A dry-run release cannot surface
+    # them: workflow.rb:2522-2526 replaces the member result with a synthetic
+    # "release readiness requires lockfile normalization" entry before
+    # append_release_internal_checks runs, so published_version_check never
+    # appears and every diagnostics array is empty. The findings are computed
+    # inside release_lockfile_readiness_would_fail? (workflow.rb:5785-5794) and
+    # then discarded in favour of a boolean. Running with --execute to obtain them
+    # would run the release, which is what we are trying to unblock.
+    #
+    # PublishedVersionCheck is read-only, so this is safe to run without
+    # --execute; only the uninstall itself is gated.
+    class BlockerCleanup
+      PHASE = "clean_blockers"
+      BLOCKER_KIND = "unpublished_lockfile_pin"
+      NO_BLOCKERS_MESSAGE = "no unpublished lockfile pins found"
+      # A member in local-gem mode resolves its family siblings through PATH
+      # remotes, so its lockfile has no GEM-section specs to check. Reporting
+      # "no blockers" for it would claim a clean bill of health that was never
+      # established, so it is reported separately.
+      NOT_INSPECTABLE_MESSAGE = "lockfile has no registry-resolved pins; nothing inspectable"
+      NOT_REMOVABLE_PREFIX = "blockers pinned but not installed in a gem home (source checkout, not removable): "
+
+      include GemUninstallSupport
+
+      def initialize(members:, execute: false, runner: nil)
+        @members = members
+        @execute = execute
+        @runner = runner || CommandRunner.new(execute: execute)
+      end
+
+      # @return [Array<CommandResult>]
+      def results
+        findings = members.map { |member| member_blockers(member) }
+        removable = removable_candidates(findings)
+        annotated = annotate_contributors(findings, removable)
+        informational = informational_results(annotated)
+        return informational if removable.empty?
+
+        informational + batched_cleanup_results(annotated, removable)
+      end
+
+      private
+
+      attr_reader :members, :execute, :runner
+
+      def uninstall_phase
+        PHASE
+      end
+
+      # One member's blockers, from the check's structured diagnostics.
+      #
+      # @return [Hash] member, blockers (deduped [name, version, remote]),
+      #   inspectable (whether the lockfile had registry pins at all)
+      def member_blockers(member)
+        lockfile = File.join(member.root, "Gemfile.lock")
+        return {member: member, blockers: [], inspectable: false} unless File.file?(lockfile)
+
+        pins = registry_pins(lockfile)
+        result = PublishedVersionCheck.call(member: member)
+        blockers = result.diagnostics
+          .select { |diagnostic| diagnostic["kind"] == BLOCKER_KIND }
+          .map { |diagnostic| [diagnostic["gem"], diagnostic["version"], diagnostic["remote"]] }
+          .uniq
+
+        {member: member, blockers: blockers, inspectable: !pins.empty?}
+      end
+
+      def registry_pins(lockfile)
+        Kettle::Dev::LockfileReset.registry_gem_specs_from_source(File.read(lockfile))
+      rescue
+        []
+      end
+
+      # Blockers that are actually installed in a gem home and can therefore be
+      # removed, deduplicated across members by [name, version].
+      #
+      # A blocker that is not installed in a gem home is a PATH or git source
+      # checkout: `gem uninstall` cannot remove it, and including one would abort
+      # the whole batch. Those are reported rather than attempted.
+      #
+      # The version is normalized by stripping any platform suffix, because a
+      # lockfile pins `nokogiri (1.19.4-x86_64-linux-gnu)` while gem homes store
+      # the spec as `nokogiri-1.19.4-x86_64-linux-gnu.gemspec` and
+      # #installed_versions records it as 1.19.4.
+      def removable_candidates(findings)
+        findings.flat_map { |finding| normalized_blockers(finding) }
+          .uniq
+          .select { |name, version| installed_versions(name).include?(version) }
+      end
+
+      # A finding's blockers as [name, Gem::Version] pairs, minus any whose version
+      # cannot be parsed. Shared by #removable_candidates and #annotate_contributors
+      # so both see identical pairs and cannot drift apart.
+      def normalized_blockers(finding)
+        finding.fetch(:blockers).filter_map do |name, version, _remote|
+          normalized = normalize_version(version)
+          [name, normalized] unless normalized.nil?
+        end
+      end
+
+      # Strips any platform suffix and parses, rejecting blanks.
+      #
+      # The blank guard matters: `Gem::Version.new("")` returns version "0" rather
+      # than raising, so an empty version from a malformed diagnostic would become
+      # a bogus `name:0` uninstall argument instead of being skipped.
+      #
+      # @return [Gem::Version, nil]
+      def normalize_version(version)
+        text = version.to_s.split("-", 2).first.to_s.strip
+        return nil if text.empty?
+
+        parse_gem_version(text)
+      end
+
+      # Adds `:own` — the subset of the global removable set this member pinned.
+      #
+      # Computed once here rather than on demand: three call sites need it
+      # (host selection, contributing filter, per-member reporting), and each
+      # would otherwise re-run the same normalization and membership test.
+      def annotate_contributors(findings, removable)
+        findings.map do |finding|
+          own = normalized_blockers(finding).select { |candidate| removable.include?(candidate) }.uniq
+          finding.merge(own: own)
+        end
+      end
+
+      # Per-member reporting. Members that contributed removable blockers get the
+      # shared batch outcome; the rest get a plain informational result.
+      def informational_results(annotated)
+        annotated.filter_map do |finding|
+          next if finding.fetch(:own).any?
+
+          member = finding.fetch(:member)
+          message = if finding.fetch(:blockers).any?
+            unremovable_blockers_message(finding)
+          elsif finding.fetch(:inspectable)
+            NO_BLOCKERS_MESSAGE
+          else
+            NOT_INSPECTABLE_MESSAGE
+          end
+          informational_result(member: member, message: message)
+        end
+      end
+
+      def contributors(annotated)
+        annotated.select { |finding| finding.fetch(:own).any? }
+      end
+
+      # Names the blockers this member pinned that cannot be removed here, and
+      # why, so a cross-family offender is attributable rather than mysterious.
+      def unremovable_blockers_message(finding)
+        names = finding.fetch(:blockers).map { |name, version, _remote| "#{name} #{version}" }
+        "#{NOT_REMOVABLE_PREFIX}#{names.join(", ")}"
+      end
+
+      # Runs the batch once, then reports that one outcome against every member
+      # that contributed to it. See the class comment for why a single batched
+      # invocation is required rather than one per gem.
+      def batched_cleanup_results(annotated, removable)
+        contributing = contributors(annotated)
+        # Defensive: `removable` is derived from findings' own blockers, so a
+        # non-empty set always has at least one contributor. Guarded anyway
+        # because a nil host would raise NoMethodError inside the uninstall.
+        host = contributing.first&.fetch(:member)
+        return [] if host.nil?
+
+        command = batched_uninstall_command(removable)
+        # gem uninstall does not depend on the working directory, so the first
+        # contributing member provides a real directory to execute in.
+        outcome = if execute
+          verified_uninstall_outcome(candidates: removable, host: host, command: command)
+        else
+          dry_run_uninstall_outcome(command: command)
+        end
+
+        contributing.map { |finding| member_result(finding, outcome) }
+      end
+
+      # One member's view of the shared batch outcome, naming the gems that member
+      # pinned so a failure is attributable rather than mysterious.
+      #
+      # The member's own contribution comes from the annotated finding:
+      # PublishedVersionCheck hits the registry, so re-invoking it during
+      # reporting would add a network round-trip per member.
+      def member_result(finding, outcome)
+        member = finding.fetch(:member)
+        own = finding.fetch(:own)
+        own_reason = describe_gem_versions(own)
+        reason = if outcome.ok? || own.empty?
+          outcome.reason
+        else
+          "batched gem uninstall including #{own_reason} failed"
+        end
+        outcome.dup.tap do |copy|
+          copy.member_name = member.name
+          copy.workdir = member.root
+          copy.stdout = outcome.skipped ? "would uninstall #{own_reason}" : outcome.stdout
+          copy.reason = reason
+        end
+      end
+
+      def informational_result(member:, message:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: 0,
+          success: true,
+          stdout: message,
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: nil
+        )
+      end
+    end
+  end
+end

data/lib/kettle/family/clean_installed.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Kettle
+  module Family
+    # Uninstalls exactly what `install` installs: each selected member's current
+    # source version, plus the cached .gem files.
+    #
+    # This is the deterministic inverse of `install`, and it exists because the
+    # other two cleanups cannot see this class of pollution:
+    #
+    # - +UnreleasedGemCleanup+ (`clean-unreleased`) removes installed versions
+    #   newer than the latest release, but it derives candidates per member from
+    #   release state and can miss versions it judges released.
+    # - +BlockerCleanup+ (`clean-blockers`) removes what members' lockfiles pin,
+    #   so an installed-but-unpinned gem is invisible to it. Observed live:
+    #   commonmarker-merge 7.1.10 survived a blocker cleanup (no release
+    #   lockfile pinned it), then broke gem activation family-wide with its
+    #   dangling exact pin on markdown-merge = 7.1.10 once the rest of the
+    #   series was removed.
+    #
+    # Candidates are the members `install` would act on -- the selected members
+    # plus any configured install local_dependencies -- restricted to those whose
+    # source version is unreleased (a member already at its released version has
+    # nothing to remove; uninstalling it would only churn the bundles that
+    # resolve it). Release state comes from the same ReleaseStateCheck
+    # +UnreleasedGemCleanup+ uses.
+    #
+    # The uninstall itself is the shared GemUninstallSupport batch: one
+    # invocation, a documented --ignore-dependencies retry when an out-of-batch
+    # dependent aborts it, cache removal, and post-uninstall re-enumeration.
+    #
+    # Note for the family running it: when this command is executed from an
+    # installed kettle-family, the batch includes kettle-family itself. The
+    # uninstall runs in a subprocess, so self-removal mid-run is safe; the
+    # executable falls back to the latest released install afterwards.
+    class CleanInstalled
+      PHASE = "clean_installed"
+      RELEASED_MESSAGE = "source version is released; nothing to uninstall"
+      NOT_INSTALLED_MESSAGE = "source version is not installed"
+      UNKNOWN_VERSION_MESSAGE = "source version is unknown; nothing to uninstall"
+      UNKNOWN_RELEASED_MESSAGE = "latest released version is unknown; no cleanup attempted"
+
+      include GemUninstallSupport
+      include MemberLoader
+
+      def initialize(config:, members:, execute: false, runner: nil)
+        @config = config
+        @members = members
+        @execute = execute
+        @runner = runner || CommandRunner.new(execute: execute)
+      end
+
+      # @return [Array<CommandResult>]
+      def results
+        findings = member_findings
+        removable = findings.filter_map { |finding| finding[:candidate] }.uniq
+        annotated = findings.map do |finding|
+          candidate = finding[:candidate]
+          own = (candidate && removable.include?(candidate)) ? [candidate] : []
+          finding.merge(own: own)
+        end
+        informational = annotated.filter_map { |finding| informational_for(finding) }
+        return informational if removable.empty?
+
+        informational + batched_cleanup_results(annotated.select { |finding| finding[:own].any? }, removable)
+      end
+
+      private
+
+      attr_reader :config, :members, :execute, :runner
+
+      def uninstall_phase
+        PHASE
+      end
+
+      # The members `install` would act on: selected members plus configured
+      # install local_dependencies, deduplicated by name.
+      def candidate_members
+        local = config.install_local_dependencies.map { |path| member_from_path(path) }
+        seen = {}
+        (local + members).each_with_object([]) do |member, memo|
+          next if seen.key?(member.name)
+
+          seen[member.name] = true
+          memo << member
+        end
+      end
+
+      def release_state_by_member
+        ReleaseStateCheck.new(config: config, members: candidate_members).results.each_with_object({}) do |result, memo|
+          memo[result.member_name] = result
+        end
+      end
+
+      # One member's candidate: its source version, when that version is
+      # unreleased and installed. [name, Gem::Version] or nil, plus the reason
+      # there is nothing to do.
+      def member_findings
+        states = release_state_by_member
+        candidate_members.map do |member|
+          state = states[member.name]
+          candidate, message = candidate_for(member, state)
+          {member: member, candidate: candidate, message: message, state: state}
+        end
+      end
+
+      def candidate_for(member, state)
+        return [nil, nil] unless state&.ok?
+
+        latest = latest_released_version(state.state)
+        return [nil, nil] unless latest
+
+        source = parse_gem_version(member.version.to_s)
+        return [nil, UNKNOWN_VERSION_MESSAGE] unless source
+        return [nil, RELEASED_MESSAGE] unless source > latest
+        return [[member.name, source], nil] if installed_versions(member.name).include?(source)
+
+        [nil, NOT_INSTALLED_MESSAGE]
+      end
+
+      def latest_released_version(state)
+        value = state.fetch("latest_released", nil).to_s
+        return nil if value.empty? || value == "unknown"
+
+        Gem::Version.new(value.delete_prefix("v"))
+      rescue ArgumentError
+        nil
+      end
+
+      # Per-member outcomes that are not part of the batch: unreadable release
+      # state (a failure naming its member), or nothing to do (informational).
+      def informational_for(finding)
+        member = finding.fetch(:member)
+        state = finding[:state]
+        return release_state_failure(member: member, release_state: state) unless state&.ok?
+
+        message = finding[:message]
+        return nil if message.nil? && finding[:own].any?
+        return informational_result(member: member, message: UNKNOWN_RELEASED_MESSAGE) if message.nil?
+
+        informational_result(member: member, message: message)
+      end
+
+      # Runs the batch once, then reports that one outcome against every member
+      # whose gem was in it, mirroring UnreleasedGemCleanup: the command and
+      # exit state are shared, but each member reports only its own gem so a
+      # failure stays attributable.
+      def batched_cleanup_results(contributors, removable)
+        host = contributors.first.fetch(:member)
+        command = batched_uninstall_command(removable)
+        outcome = if execute
+          verified_uninstall_outcome(candidates: removable, host: host, command: command)
+        else
+          dry_run_uninstall_outcome(command: command)
+        end
+
+        contributors.map do |finding|
+          member_result(finding.fetch(:member), outcome, finding.fetch(:own))
+        end
+      end
+
+      def member_result(member, outcome, own_candidates)
+        own = describe_gem_versions(own_candidates)
+        reason = if outcome.ok? || own_candidates.empty?
+          outcome.reason
+        else
+          "batched gem uninstall including #{own} failed"
+        end
+        outcome.dup.tap do |copy|
+          copy.member_name = member.name
+          copy.workdir = member.root
+          copy.stdout = outcome.skipped ? "would uninstall #{own}" : outcome.stdout
+          copy.reason = reason
+        end
+      end
+
+      def informational_result(member:, message:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: 0,
+          success: true,
+          stdout: message,
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: nil
+        )
+      end
+
+      def release_state_failure(member:, release_state:)
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: release_state&.status || 1,
+          success: false,
+          stdout: "",
+          stderr: release_state&.stderr.to_s,
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: "release state unavailable"
+        )
+      end
+    end
+  end
+end