kettle-family 1.3.5 → 1.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e18a444e22f9d52b19ef8396ce75bc80b85bb579fb353889fecb8547ddc8bec
-  data.tar.gz: b91bb8aa9018297be574e1eda7ddc26c6b8f314692cd4c4881c95fa4fe52062a
+  metadata.gz: ec4f59e4397fe55738de3f0e3e482a2053d3c771716e9d94de40478f76ba80ae
+  data.tar.gz: 7ea569f07fa6cc8cc46cf5351cf93441ece85870c80ab51aed2458e0ce66346a
 SHA512:
-  metadata.gz: 50d83077bd30c1c673772be79765f02d263cf499b382355f8b647889255abb9608155e8a0434d6c98d549ddad5188186f50e56b9608537e47b1cb5f2c1cfec5a
-  data.tar.gz: e81978953b9a9d94d2c518d770cd72e6b6efbcd5a3fd2c010da97f72cb9107d71624bd126cdf1799c1e17276f3546adaca3246089e151b6bccc7edc04db4cef2
+  metadata.gz: 9dac940565396b2209bd67e957af7f2e015318d70572c05cca684e8de26c43d75755a142727d994baa5fbd646ce674fa7ab6c84bdb913ca9c6685824fd3beca6
+  data.tar.gz: 53c75a31e0896365a67c7b0ec46a45830d1e71abe37843dc715ee7f086f39166fbf39c36620efc0760d00848a6ce11238da0ee81cf84cfa6ced5e192e13178e4

data/CHANGELOG.md

@@ -30,6 +30,53 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.3.7] - 2026-10-09
+
+- TAG: [v1.3.7][1.3.7t]
+- COVERAGE: 93.30% -- 6778/7265 lines in 38 files
+- BRANCH COVERAGE: 77.95% -- 2757/3537 branches in 38 files
+- 34.47% documented
+
+### Changed
+
+- Reject --start-at for template and test instead of silently dropping members. Those commands dispatch in dependency waves and a concurrent queue, so the set of members that still need work is not a suffix of the configured order and no positional value can select it. The flag now exits 1 with a message pointing at the equivalent --only selection. release is deliberately left accepting --start-at: it uses MEMBER@BRANCH to select a branch lane via release_target_branches, and its own resume hints already use --only rather than --start-at. Sequentially dispatched commands (lint, bup, check, docs, install, sync, push, pull, bump) keep positional --start-at, which is correct because they abort at the first failure so pending genuinely is a suffix.
+
+- [kc] kettle-jem/prepare: updated 5 project files:
+  - dependencies (5)
+
+- [kc] kettle-jem/template: updated 2 project files:
+  - code and tests (1)
+  - other (1)
+
+### Fixed
+
+- Fix clean-unreleased missing locally installed unreleased versions. Under `bundle exec`, every RubyGems enumeration API (find_all_by_name, stubs_for, Specification.all) reports only the versions the active bundle resolves, not everything installed in the gem home. An unreleased version that was built and installed but is not pinned by the lockfile was therefore invisible, so cleanup reported "no unreleased installed versions found" with outcome success while leaving the offender installed -- blind in exactly the state it exists to correct, since re-resolving the lockfile to released versions is what hides the offender. Installed versions are now read by scanning the specification directories under each Gem.path root, which sees every installed version regardless of bundle activation and still excludes PATH/git source checkouts. Verified against the kettle-dev family: the fix now surfaces 10 unreleased members (kettle-rb 0.1.16, kettle-test 2.0.24, token-resolver 2.0.13, and others) that the previous implementation reported as none, while correctly leaving the two released members (kettle-dev 3.1.8, kettle-family 1.3.6) alone.
+
+- Fix clean-unreleased --execute reporting success when gem uninstall removes nothing. RubyGems exits 0 and prints "Gem 'name' is not installed" when the target is absent from GEM_HOME, so an exit-status check could not distinguish a completed cleanup from one that silently did nothing -- the same silent-success failure mode as the enumeration bug. The batch outcome is now verified by re-enumerating installed versions afterwards, and any survivor turns the result into a failure that names it. Investigated and deliberately not implemented: `gem uninstall -i <root>` is not a workaround for a gem home other than GEM_HOME, because it fails with the same "not installed in GEM_HOME" error even when the path equals GEM_HOME. That case already fails loudly with a non-zero exit rather than being reported as success.
+
+- Fix the resume hint for template and test silently dropping members that never ran. Those commands do not dispatch positionally: template groups members into dependency waves derived from gemspec dependencies, test uses a concurrent work queue, and in both a failure only sets a stop flag that prevents threads from popping further work -- members already in flight finish while later waves never run. The pending set is therefore interleaved through the configured order rather than being a suffix of it, so the emitted positional `--start-at <failed member>` dropped every pending member ordered ahead of the failure. Measured on the kettle-dev family: nomono failed in template wave 1 and left kettle-dev, kettle-changelog, kettle-family and kettle-soup-cover pending at ordered positions 6, 8, 9 and 11 while kettle-drift at 7 and kettle-wash at 10 had succeeded, so `--start-at nomono` resumed only nomono and token-resolver and reported outcome success having never templated the other four. Resume hints for these commands are now set-based, mirroring release: one `--only` hint per failure plus a combined `--only` hint naming every member that never ran. Sequentially dispatched commands keep positional `--start-at`, which remains correct because they abort at the first failure. A failed family-root phase still restarts the whole command, since it aborts before member dispatch. Note that template and test ignore the configured `release.waves`, which only affect release ordering.
+
+## [1.3.6] - 2026-10-07
+
+- TAG: [v1.3.6][1.3.6t]
+- COVERAGE: 93.25% -- 6743/7231 lines in 38 files
+- BRANCH COVERAGE: 77.82% -- 2740/3521 branches in 38 files
+- 34.02% documented
+
+### Added
+
+- [kc] published-version-check: `Kettle::Family::PublishedVersionCheck` detects lockfile pins that no registry serves — the signature of a locally built and installed gem leaking into a lockfile. Bundler resolves against the local gem dir, so an ordinary `bundle install` can pin such a version, and the entry it writes is a normal GEM-section line carrying a valid checksum taken from the installed spec, so nothing in the lockfile text distinguishes it and there is no offline marker either (installed specs look the same as fetched ones, and `Gem::Specification` has no `#remote`). Only asking the registry can tell. A pinned native gem is compared after splitting off its platform suffix, because a lockfile pins `nokogiri (1.19.4-x86_64-linux-gnu)` while the registry lists bare `1.19.4` once per platform; comparing the pinned string directly reported every native gem as unpublished, adding 10 false positives to one real lockfile. Prerelease versions are unaffected because they are dot-separated (`1.0.0.rc1`) and RubyGems version strings cannot contain a hyphen, so the first hyphen is always the version/platform boundary. Runs in `bup`/`bupb`/`update-bundler` before committing a lockfile update, and in release preflight, where a bad pin previously surfaced much later as an opaque bundler error during lockfile reset.
+
+- [kc] published-version-memo: The published-version check fails open: when a registry cannot be consulted the version counts as unverifiable rather than unpublished, so a registry outage cannot turn every family member into a false failure. Registry answers are memoized per process keyed by gem, remote and version, so members sharing toolchain and sibling dependencies query the registry once for the whole run rather than once each. The memo is subordinate to the on-disk release marker that `kettle-release` writes after confirming a gem is available: a gem published during the current run is always re-queried rather than answered from a pre-publish memo entry, which would otherwise report the just-published version as unpublished and block a legitimate release.
+
+- [kc] dependency-floor-published-version-gate: `kettle-family release` now gates the "Reconcile family dependencies" commit on the lockfile it is about to record. The preceding `bundle install` resolves against the local gem dir, so it can pin a locally built and installed version, and committing that produces a lockfile no isolated environment can resolve. The failure previously surfaced much later as an opaque bundler error during release lockfile reset ("Your bundle is locked to kettle-jem (7.1.29) ... but that version can no longer be found") rather than at the moment the bad pin was introduced; observed live, a release run's own reconcile commit flipped kettle-jem 7.1.28 to 7.1.29 in the tracked `Gemfile.lock` and then aborted at step 0. The existing floor diagnostics do not catch this, because they validate checksums only for released family members, while the pins that break resolution are typically toolchain dependencies that are not members at all and carry a valid checksum. Gems published during the same run are not blocked, since the check consults the on-disk release marker ahead of its process memo.
+
+### Fixed
+
+- [kc] clean-unreleased-batch: `kettle-family clean-unreleased` now removes every unreleased installed version across the family in a single `gem uninstall` invocation instead of one invocation per gem. This is not merely fewer processes: RubyGems' `uninstall_specific` builds a `Gem::DependencyList` from every requested gem and removes them via `strongly_connected_components.flatten.reverse`, a topological sort of the whole set that removes dependents before their dependencies. A per-gem invocation sees only one gem and cannot sort, so it raises `Gem::DependencyRemovalException` ("Uninstallation aborted due to dependent gem(s)") whenever another installed gem still depends on it. Because family members are interdependent and the release order is dependency order, per-gem removal failed on the foundations: observed live, removing tree_haver first failed while ast-merge still required it, and four repeated passes still left two gems installed. One batched invocation removed both. Versions are passed as `name:version` arguments since RubyGems rejects `--version` alongside multiple gems, and `--all` is deliberately omitted because with gem arguments it is redundant while with none it means `uninstall_all`, which would remove every gem in the gem home.
+
+- [kc] clean-unreleased-source-checkouts: `kettle-family clean-unreleased` no longer reports source checkouts as unreleased installed gems. Under `bundle exec`, bundler adds PATH and git sources to the load path, so `Gem::Specification.find_all_by_name` also returns specs whose `full_gem_path` points at a working copy rather than a gem home — for example tree_haver 7.1.10 resolving to `gems/tree_haver`. Those are not installed gems and `gem uninstall` cannot remove them, so the command reported work that could never succeed; after uninstalling all 31 genuinely installed unreleased gems in the structuredmerge family, it still listed all 31. Candidates are now filtered to specs under `Gem.path`.
+
 ## [1.3.5] - 2026-10-05
 
 - TAG: [v1.3.5][1.3.5t]
@@ -2884,7 +2931,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.5...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.7...HEAD
+[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
+[1.3.6t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.6
 [1.3.5]: https://github.com/kettle-dev/kettle-family/compare/v1.3.4...v1.3.5
 [1.3.5t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.5
 [1.3.4]: https://github.com/kettle-dev/kettle-family/compare/v1.3.3...v1.3.4

data/README.md

@@ -1192,7 +1192,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.123-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-7.231-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/cli.rb

@@ -715,6 +715,7 @@ module Kettle
       def build_report(command, options)
         config = Config.load(root: options[:root], path: options[:config])
         start_at = parse_start_at(options[:start_at])
+        Selection.validate_positional_start_at!(command, start_at.member)
         effective_only = default_only_filter(command: command, only: options[:only])
         discovery = Discovery.new(
           config: config,

data/lib/kettle/family/published_version_check.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "kettle/dev/lockfile_reset"
+require "kettle/dev/ruby_gems_versions"
+
+module Kettle
+  module Family
+    # Detects versions pinned in a release lockfile that no registry actually
+    # serves — the signature of a locally built and installed gem leaking into
+    # a lockfile.
+    #
+    # Why this is needed at all: bundler resolves against the local gem dir, so
+    # an ordinary `bundle install` will happily pin a locally installed version.
+    # The resulting entry is a normal GEM-section line carrying a valid checksum
+    # taken from the installed spec, so it is indistinguishable from a published
+    # gem by inspection. There is also no offline marker for a local build —
+    # installed specs look the same as fetched ones, and Gem::Specification has
+    # no #remote — so the only reliable signal is asking the registry.
+    #
+    # Deliberately NOT applied to templating. Templating injects its own
+    # (often unreleased) version into a destination so it can run itself, and
+    # local templating from unreleased source is a routine workflow; gating that
+    # would break it. So this runs only where a lockfile is about to be
+    # committed or published, and templating's transient local pins get cleaned
+    # up later by a release-mode dependency update.
+    #
+    # Fails open: when the registry cannot be consulted the version counts as
+    # unverifiable rather than unpublished, so offline runs are never blocked by
+    # network conditions.
+    class PublishedVersionCheck
+      PHASE = "published_version_check"
+
+      # Process-local memo of registry answers, keyed by [gem name, remote].
+      #
+      # Two reasons this is safe and desirable:
+      #
+      #   * Family members share almost all their toolchain and sibling
+      #     dependencies, so one member's lookups serve every later member.
+      #     Without this, a 30-member release re-queries the same gems 30
+      #     times.
+      #   * A single command invocation should see one consistent snapshot of
+      #     the registry. Re-querying per member could otherwise report a gem
+      #     as unpublished for early members and published for later ones if it
+      #     lands mid-run.
+      #
+      # The memo is subordinate to the on-disk release marker, never above it.
+      # kettle-release writes ~/.local/state/kettle-dev/rubygems-cache-bust.json
+      # after publishing, so the filesystem is the authority on what this
+      # machine just released. A gem published *during* the current run — say
+      # kettle-dev 3.1.8, released before its dependents' floors are raised to
+      # it — would otherwise be answered from a pre-publish memo entry and
+      # falsely reported unpublished, blocking a legitimate release. So
+      # #published_versions always consults the marker first and skips the memo
+      # when it says that exact gem+version was just released. Verified: a
+      # pre-publish memo entry yields 0 live queries without the marker check
+      # and reports the new version missing.
+      #
+      # nil is memoized too, so an unreachable registry is asked once rather
+      # than once per pin. Lifetime is one process; nothing persists.
+      REGISTRY_MEMO = {}
+
+      def self.call(member:)
+        new(member: member).call
+      end
+
+      def initialize(member:)
+        @member = member
+      end
+
+      def call
+        result(diagnostics)
+      end
+
+      private
+
+      attr_reader :member
+
+      def diagnostics
+        lockfile = File.join(member.root, "Gemfile.lock")
+        return [] unless File.file?(lockfile)
+
+        registry_lockfile_specs(lockfile).filter_map { |spec| diagnostic_for(spec) }
+      end
+
+      def registry_lockfile_specs(lockfile)
+        Kettle::Dev::LockfileReset.registry_gem_specs_from_source(File.read(lockfile))
+      end
+
+      # A message for an unpublished pin, or nil when the version is published
+      # or the registry could not be consulted.
+      def diagnostic_for(spec)
+        return nil unless unpublished?(spec)
+
+        "release lockfile pins #{spec.fetch(:name)} #{spec.fetch(:version)}, " \
+          "which is not published on #{spec.fetch(:remote)} " \
+          "(locally installed but unreleased; run a release-mode dependency update to re-resolve)"
+      end
+
+      def unpublished?(spec)
+        remote = spec.fetch(:remote).to_s
+        return false if remote.empty?
+
+        pinned = version_without_platform(spec.fetch(:version))
+        versions = published_versions(spec.fetch(:name), remote, pinned)
+        return false if versions.nil?
+
+        !versions.include?(pinned)
+      end
+
+      # A lockfile pins a native gem as "1.19.4-x86_64-linux-gnu" while the
+      # registry lists its versions as bare "1.19.4", one entry per platform.
+      # Comparing the pinned string directly would report every native gem as
+      # unpublished, so split off the platform first.
+      #
+      # Splitting on the first "-" matches Bundler::LockfileParser. It is safe
+      # because RubyGems version strings cannot themselves contain a hyphen
+      # (prerelease segments are dot-separated, e.g. "1.0.0.rc1"), so the first
+      # hyphen is always the version/platform boundary.
+      def version_without_platform(pinned)
+        pinned.to_s.split("-", 2).first
+      end
+
+      # nil when the registry could not be consulted. Memoized per process,
+      # except for gems the on-disk release marker says were just published —
+      # see REGISTRY_MEMO for why bypassing the memo there is required.
+      def published_versions(name, remote, version)
+        key = [name, remote, version]
+        unless just_released?(name, version)
+          return REGISTRY_MEMO[key] if REGISTRY_MEMO.key?(key)
+        end
+
+        REGISTRY_MEMO[key] = Kettle::Dev::RubyGemsVersions.published_version_numbers(
+          name,
+          source: remote,
+          version: version
+        )
+      end
+
+      def just_released?(name, version)
+        return false if version.to_s.empty?
+
+        Kettle::Dev::RubyGemsVersions.recently_released?(name, version)
+      rescue
+        false
+      end
+
+      def result(found)
+        clean = found.empty?
+        CommandResult.new(
+          member_name: member.name,
+          phase: PHASE,
+          command: ["internal", PHASE],
+          workdir: member.root,
+          status: clean ? 0 : 1,
+          success: clean,
+          stdout: found.join("\n"),
+          stderr: "",
+          elapsed_seconds: 0.0,
+          skipped: false,
+          reason: clean ? nil : "lockfile pins versions no registry serves"
+        )
+      end
+    end
+  end
+end

data/lib/kettle/family/report.rb

@@ -711,11 +711,42 @@ module Kettle
         release_resume_hints
       end
 
+      # Commands whose member dispatch is not positional are defined once, on
+      # Selection, because that is also where --start-at is rejected for them.
+      # Report needs the same classification to emit a set-based resume hint
+      # instead of a positional one. See the documentation on
+      # Selection::NON_POSITIONAL_DISPATCH_COMMANDS for the measured evidence.
+      def non_positional_dispatch?
+        Selection.non_positional_dispatch?(command)
+      end
+
       def non_release_resume_hints
+        return non_positional_resume_hints if non_positional_dispatch?
+
         failed = results.find { |result| !result.ok? }
         failed ? [resume_hint_for(failed)] : []
       end
 
+      # Mirrors release_resume_hints: one hint per failure, plus a single set-based
+      # hint naming every member that never ran. --only selects by name rather
+      # than position, so it resumes exactly the unfinished members regardless of
+      # how dispatch ordered them, and the wave grouping is re-derived from the
+      # selected subset.
+      #
+      # A family-root failure takes precedence and suppresses the set-based hint:
+      # that phase aborts the entire run before member dispatch, so every member
+      # needs the whole command re-run rather than a subset resumed by name.
+      def non_positional_resume_hints
+        root_failure = results.find { |result| !result.ok? && family_root_phase?(result.phase) }
+        return [resume_hint_for(root_failure)] if root_failure
+
+        failed_hints = visible_results.reject(&:ok?).filter_map { |result| resume_hint_for(result) }.uniq
+        pending_names = summary_pending.map { |entry| entry.fetch("member") }
+        return failed_hints if pending_names.empty?
+
+        [*failed_hints, "kettle-family #{command} --only #{pending_names.join(",")}"]
+      end
+
       def release_resume_hints
         failed_hints = visible_results.reject(&:ok?).filter_map { |result| resume_hint_for(result) }.uniq
         pending_names = summary_pending.map { |entry| entry.fetch("member") }
@@ -726,11 +757,18 @@ module Kettle
 
       def resume_hint_for(result)
         return release_resume_hint(result) if command == "release"
-        return "kettle-family #{command}" if result.phase.start_with?("family_root_") || result.phase == "commit_family_root_bundle_update"
+        return "kettle-family #{command}" if family_root_phase?(result.phase)
+        # A positional --start-at would silently drop pending members that are
+        # ordered ahead of this one, so wave-dispatched commands resume by name.
+        return "kettle-family #{command} --only #{result.member_name}" if non_positional_dispatch?
 
         "kettle-family #{command} --start-at #{result.member_name}"
       end
 
+      def family_root_phase?(phase)
+        phase.to_s.start_with?("family_root_") || phase == "commit_family_root_bundle_update"
+      end
+
       def release_resume_hint(result)
         return result.resume_command if result.respond_to?(:resume_command) && !result.resume_command.to_s.empty?
         return nil if result.phase == "aggregate_github_release"

data/lib/kettle/family/selection.rb

@@ -13,6 +13,43 @@ module Kettle
         "bump" => "bump_release_pending"
       }.freeze
 
+      # Commands whose member dispatch is not positional, so `--start-at` cannot
+      # express "the members that still need work" for them.
+      #
+      # template groups members into dependency waves derived from gemspec
+      # dependencies and test uses a concurrent work queue. In both, a failure only
+      # sets a stop flag that prevents threads from popping further work: members
+      # already in flight finish while later waves never run. The pending set is
+      # therefore interleaved through the configured order rather than being a
+      # suffix of it, so no --start-at value selects exactly that set.
+      #
+      # Measured on the kettle-dev family: nomono failed in template wave 1 and
+      # left kettle-dev, kettle-changelog, kettle-family and kettle-soup-cover
+      # pending at ordered positions 6, 8, 9 and 11, while kettle-drift at 7 and
+      # kettle-wash at 10 had already succeeded. The pending positions were
+      # [5, 7, 8, 10] against a required suffix of [9, 10, 11, 12].
+      #
+      # These commands ignore the configured `release.waves`, which only feed
+      # display_members_for and so only affect release ordering.
+      NON_POSITIONAL_DISPATCH_COMMANDS = %w[template test].freeze
+
+      def self.non_positional_dispatch?(command)
+        NON_POSITIONAL_DISPATCH_COMMANDS.include?(command)
+      end
+
+      # Rejects `--start-at` for commands whose dispatch is not positional, rather
+      # than letting it silently drop members. Mirrors the class-method validation
+      # convention used by validate_release_state_only_filter! so callers in the CLI
+      # do not have to know which commands are affected.
+      def self.validate_positional_start_at!(command, start_at)
+        return if start_at.nil? || start_at.to_s.empty?
+        return unless non_positional_dispatch?(command)
+
+        raise Error, "--start-at is not supported for #{command}: members are dispatched in dependency " \
+                     "waves, so a positional resume would silently skip members that never ran. " \
+                     "Use --only #{start_at} (or the resume hint from the previous report) instead."
+      end
+
       def self.status_tokens
         STATUS_TOKEN_KEYS.keys
       end

data/lib/kettle/family/unreleased_gem_cleanup.rb

@@ -2,8 +2,49 @@
 
 module Kettle
   module Family
+    # Removes locally installed gem versions that no registry has published.
+    #
+    # Why this exists: bundler resolves against the local gem dir and picks the
+    # highest version satisfying a constraint, so a locally built unreleased
+    # version always wins over the published one. Floor constraints are `>=`, so
+    # there is no ceiling that stops it, and every `bundle install` or
+    # `bundle lock` re-pins the offender. Detection cannot fix resolution — the
+    # offenders have to be removed. Left in place they produce lockfiles that no
+    # isolated environment can resolve, which surfaces much later as an opaque
+    # bundler error ("locked to kettle-jem (7.1.29) ... can no longer be
+    # found").
+    #
+    # All candidates across the whole family are removed in ONE `gem uninstall`
+    # invocation rather than one invocation per gem. That is not merely fewer
+    # processes: RubyGems' `uninstall_specific` builds a Gem::DependencyList from
+    # every requested gem and removes them via
+    # `strongly_connected_components.flatten.reverse`, a topological sort of the
+    # whole set that removes dependents before their dependencies. A per-gem
+    # invocation sees only one gem and cannot sort, so it raises
+    # Gem::DependencyRemovalException ("Uninstallation aborted due to dependent
+    # gem(s)") whenever another installed gem still depends on it. Family
+    # members are heavily interdependent, so per-gem removal fails on the
+    # foundations: observed live, removing tree_haver first failed because
+    # ast-merge still required it, and four iterative passes still left two gems
+    # installed. One batched invocation removed both.
+    #
+    # The single run is still reported per member. Report keys results by member
+    # name for commands in MEMBER_RESULT_COMMANDS, and treats a member with no
+    # result as pending, which fails the whole summary. So attributing the batch
+    # to one synthetic family-level name left every member pending and reported
+    # `outcome: failure` with `failed: none`. Each contributing member instead
+    # receives the shared outcome of the one run.
+    #
+    # `--all` is deliberately not passed. With gem arguments present it is
+    # redundant (RubyGems routes to `uninstall_specific` either way), and with no
+    # arguments it means `uninstall_all`, which removes every gem in the gem
+    # home. Omitting it makes an empty argument list a plain usage error instead
+    # of a wipe. `--version` cannot be used either, because RubyGems rejects it
+    # alongside multiple gems; versions are given as `name:version` arguments,
+    # the form its own error message prescribes.
     class UnreleasedGemCleanup
       PHASE = "clean_unreleased"
+      UNKNOWN_RELEASED_MESSAGE = "latest released version is unknown; no cleanup attempted"
 
       def initialize(config:, members:, execute: false, runner: nil)
         @config = config
@@ -14,9 +55,24 @@ module Kettle
 
       def results
         release_states = release_state_by_member
-        members.flat_map do |member|
-          cleanup_results_for(member: member, release_state: release_states[member.name])
+        # Resolved once per member: candidates and the member's non-uninstall
+        # diagnostics both derive from the same release state and installed spec
+        # scan, so pairing them in one pass keeps installed specs enumerated a
+        # single time and avoids re-reading release_states per member.
+        planned = members.map do |member|
+          release_state = release_states[member.name]
+          candidates = unreleased_candidates(member: member, release_state: release_state)
+          {
+            member: member,
+            candidates: candidates,
+            diagnostics: member_diagnostics(member: member, release_state: release_state, candidates: candidates)
+          }
         end
+        diagnostics = planned.flat_map { |entry| entry.fetch(:diagnostics) }
+        contributors = planned.reject { |entry| entry.fetch(:candidates).empty? }
+        return diagnostics if contributors.empty?
+
+        diagnostics + batched_cleanup_results(contributors)
       end
 
       private
@@ -29,16 +85,41 @@ module Kettle
         end
       end
 
-      def cleanup_results_for(member:, release_state:)
+      # Per-member outcomes that are not an uninstall: a release state that could
+      # not be read, a version that cannot be compared, or nothing to do. These
+      # stay per member so a failure names the member it came from. Members that
+      # do have candidates are reported by the batch result instead.
+      def member_diagnostics(member:, release_state:, candidates:)
         return [release_state_failure(member: member, release_state: release_state)] unless release_state&.ok?
 
         latest_released = latest_released_version(release_state.state)
-        return [informational_result(member: member, message: "latest released version is unknown; no cleanup attempted")] unless latest_released
+        return [informational_result(member: member, message: UNKNOWN_RELEASED_MESSAGE)] unless latest_released
+        return [] unless candidates.empty?
+
+        [informational_result(member: member, message: "no unreleased installed versions found")]
+      end
 
-        candidates = installed_versions(member.name).select { |version| version > latest_released }
-        return [informational_result(member: member, message: "no unreleased installed versions found")] if candidates.empty?
+      # Installed versions newer than anything published, as [name, version] pairs.
+      #
+      # Only genuinely installed gems count. Under `bundle exec`, bundler adds
+      # PATH and git sources to the load path, so a source checkout can appear as
+      # a spec — e.g. tree_haver 7.1.10 resolving to gems/tree_haver rather than a
+      # gem home. That is not an installed gem and `gem uninstall` cannot remove
+      # it, so treating it as a candidate would report work that can never
+      # succeed, and once batched one such candidate would abort the whole
+      # removal. installed_versions therefore scans only specification
+      # directories under a Gem.path root, which excludes source checkouts by
+      # construction.
+      def unreleased_candidates(member:, release_state:)
+        return [] unless release_state&.ok?
+
+        latest_released = latest_released_version(release_state.state)
+        return [] unless latest_released
 
-        candidates.map { |version| cleanup_result(member: member, version: version) }
+        name = member.name
+        installed_versions(name).filter_map do |version|
+          [name, version] if version > latest_released
+        end
       end
 
       def latest_released_version(state)
@@ -50,22 +131,112 @@ module Kettle
         nil
       end
 
+      # Versions present in a gem home, oldest first.
+      #
+      # This scans the filesystem rather than asking RubyGems, because every
+      # RubyGems enumeration API is bundle-scoped: under `bundle exec`,
+      # find_all_by_name, stubs_for and Specification.all all report only the
+      # versions the active bundle resolves. An unreleased version installed in
+      # the gem home but not pinned by the lockfile is therefore invisible, which
+      # makes cleanup blind in exactly the state it exists to correct — once the
+      # lockfile re-resolves to released versions, the offenders it should remove
+      # stop being enumerated and the run reports "no unreleased installed
+      # versions found" with outcome success while leaving them installed.
+      # Observed live with kettle-rb: `gem list` showed 0.1.14, 0.1.15 and
+      # 0.1.16, while find_all_by_name under bundle exec returned only 0.1.15.
       def installed_versions(name)
-        Gem::Specification.find_all_by_name(name).map(&:version).uniq.sort
+        gem_home_specification_dirs.flat_map { |dir| installed_spec_versions_in(dir, name) }.uniq.sort
+      end
+
+      # Only specification directories under a Gem.path root are scanned. A PATH
+      # or git source checkout that bundler put on the load path is not in a gem
+      # home, so it stays excluded: `gem uninstall` cannot remove one, and one
+      # bogus candidate would abort the whole batch.
+      def gem_home_specification_dirs
+        Gem::Specification.dirs.select do |dir|
+          path = dir.to_s
+          !path.empty? && Gem.path.any? { |root| path.start_with?("#{root}#{File::SEPARATOR}") }
+        end
+      end
+
+      # Specifications are stored as `name-VERSION.gemspec`, or
+      # `name-VERSION-PLATFORM.gemspec` for a native gem. The version is the part
+      # before the first hyphen, which matches Gem::Specification#version and so
+      # excludes the platform exactly as the previous implementation did. A
+      # filename whose version part does not parse is skipped rather than guessed
+      # at, so a similarly named gem (name-extra) cannot become a candidate.
+      def installed_spec_versions_in(dir, name)
+        prefix = "#{name}-"
+        Dir.glob(File.join(dir, "#{prefix}*.gemspec")).filter_map do |file|
+          version_text = File.basename(file, ".gemspec").delete_prefix(prefix).split("-", 2).first.to_s
+          version = parse_version(version_text)
+          version unless version.nil?
+        end
+      end
+
+      def parse_version(text)
+        Gem::Version.new(text)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Runs the batch once, then reports that one outcome against every member
+      # whose gems were in it. See the class comment for why per-member results
+      # are required even though only one command runs.
+      def batched_cleanup_results(contributors)
+        candidates = contributors.flat_map { |entry| entry.fetch(:candidates) }
+        # Versions are given as `name:version` arguments rather than `--version`,
+        # which RubyGems rejects alongside multiple gems. See the class comment
+        # for why `--all` is omitted.
+        command = ["gem", "uninstall", *candidates.map { |name, version| "#{name}:#{version}" }, "--executables"]
+        # gem uninstall does not depend on the working directory, so the first
+        # contributing member provides a real directory to execute in.
+        host = contributors.first.fetch(:member)
+        outcome = execute ? verified_outcome(candidates, host, command) : dry_run_outcome(command)
+
+        contributors.map do |entry|
+          member_result(entry.fetch(:member), outcome, entry.fetch(:candidates))
+        end
       end
 
-      def cleanup_result(member:, version:)
-        command = ["gem", "uninstall", member.name, "--version", version.to_s, "--executables", "--all"]
-        return runner.call(member: member, phase: PHASE, command: command) if execute
+      # `gem uninstall` exits 0 and prints "Gem 'name' is not installed" when it
+      # removes nothing, so the exit status alone cannot distinguish a completed
+      # cleanup from one that found the wrong gem home and silently did nothing.
+      # Reporting ok in that case is the same failure mode as the enumeration bug
+      # this class exists to prevent: a success verdict over work that never
+      # happened. The candidates are therefore re-enumerated after the batch, and
+      # any version still present turns the outcome into a failure that names it.
+      def verified_outcome(candidates, host, command)
+        outcome = runner.call(member: host, phase: PHASE, command: command)
+        return outcome unless outcome.success && !outcome.skipped
+
+        remaining = candidates.select { |name, version| installed_versions(name).include?(version) }
+        return outcome if remaining.empty?
 
         CommandResult.new(
-          member_name: member.name,
+          member_name: nil,
           phase: PHASE,
           command: command,
-          workdir: member.root,
+          workdir: host.root,
+          status: outcome.status,
+          success: false,
+          stdout: outcome.stdout.to_s,
+          stderr: "#{outcome.stderr}still installed after gem uninstall: #{describe(remaining)}".strip,
+          elapsed_seconds: outcome.elapsed_seconds,
+          skipped: false,
+          reason: "gem uninstall reported success but #{describe(remaining)} remains installed"
+        )
+      end
+
+      def dry_run_outcome(command)
+        CommandResult.new(
+          member_name: nil,
+          phase: PHASE,
+          command: command,
+          workdir: nil,
           status: nil,
           success: true,
-          stdout: "would uninstall #{member.name} #{version}",
+          stdout: nil,
           stderr: "",
           elapsed_seconds: 0.0,
           skipped: true,
@@ -73,6 +244,32 @@ module Kettle
         )
       end
 
+      # One member's view of the shared batch outcome. The command and exit state
+      # are common to the whole batch, but each member reports only its own gems,
+      # so the per-member report stays readable and a failure names every gem
+      # that member contributed.
+      def member_result(member, outcome, own_candidates)
+        own = describe(own_candidates)
+        outcome_reason = outcome.reason
+        # Equivalent to `ok? ? reason : (own.empty? ? reason : batch message)`,
+        # with outcome.reason read once instead of twice.
+        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 describe(candidates)
+        candidates.map { |name, version| "#{name} #{version}" }.join(", ")
+      end
+
       def informational_result(member:, message:)
         CommandResult.new(
           member_name: member.name,

data/lib/kettle/family/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "1.3.5"
+      VERSION = "1.3.7"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/family/workflow.rb

@@ -2343,9 +2343,9 @@ module Kettle
             return memo
           end
 
-          append_release_internal_checks(member: member, memo: memo)
-          memo.last(2).each { |result| emit_member_result_progress(original_member, result, progress: progress) }
-          return memo unless memo.last(2).all?(&:ok?)
+          internal_check_results = append_release_internal_checks(member: member, memo: memo)
+          internal_check_results.each { |result| emit_member_result_progress(original_member, result, progress: progress) }
+          return memo unless internal_check_results.all?(&:ok?)
 
           release_event_state = {}
           result = release_command_runner.call(
@@ -2526,9 +2526,9 @@ module Kettle
             end
           end
 
-          append_release_internal_checks(member: member, memo: memo)
-          memo.last(2).each { |result| emit_member_result_progress(member, result, progress: progress) }
-          return memo unless memo.last(2).all?(&:ok?)
+          internal_check_results = append_release_internal_checks(member: member, memo: memo)
+          internal_check_results.each { |result| emit_member_result_progress(member, result, progress: progress) }
+          return memo unless internal_check_results.all?(&:ok?)
 
           release_event_state = {}
           release_result = runner.call(
@@ -2744,7 +2744,38 @@ module Kettle
         end
 
         reconciled_members = (floor_results.map(&:member_name) + lockfile_refresh_members.map { |member, _released_members| member.name }).uniq
-        commit_dependency_floor_changes(dependent_members: reconciled_members, runner: runner, memo: memo) if reconciled_members.any? && execute && commit
+        return unless reconciled_members.any? && execute && commit
+
+        return unless validate_dependency_floor_published_versions(member_names: reconciled_members, memo: memo)
+
+        commit_dependency_floor_changes(dependent_members: reconciled_members, runner: runner, memo: memo)
+      end
+
+      # Gates the "Reconcile family dependencies" commit on the lockfile it is
+      # about to record.
+      #
+      # The preceding bundle install resolves against the local gem dir, so it
+      # happily pins a locally built and installed version. Committing that
+      # produces a lockfile no isolated environment can resolve, and the failure
+      # surfaces much later as an opaque bundler error during release lockfile
+      # reset ("locked to kettle-jem (7.1.29) ... can no longer be found")
+      # rather than at the moment the bad pin was introduced. Observed live: a
+      # release run's own reconcile commit flipped kettle-jem 7.1.28 -> 7.1.29
+      # in the tracked Gemfile.lock and then aborted at step 0.
+      #
+      # Gems published during this very run are not a false positive, because
+      # PublishedVersionCheck consults kettle-release's on-disk release marker
+      # ahead of its process memo, and that marker is written only after the gem
+      # is confirmed available on the registry.
+      def validate_dependency_floor_published_versions(member_names:, memo:)
+        by_name = members.to_h { |member| [member.name, member] }
+        results = member_names.filter_map do |member_name|
+          member = by_name[member_name]
+          next unless member
+
+          PublishedVersionCheck.call(member: member).tap { |result| memo << result }
+        end
+        results.all?(&:ok?)
       end
 
       def dependent_members_depending_on(released_members:, dependent_members:)
@@ -3275,13 +3306,34 @@ module Kettle
         results.each { |result| result.branch = branch if result.respond_to?(:branch=) }
       end
 
+      # Runs the internal pre-release checks for one member, appending each
+      # result to +memo+. Returns the results appended by this call so callers
+      # can inspect exactly them instead of relying on a positional
+      # `memo.last(N)` window.
+      #
+      # Short-circuits on the first failure: a member with a broken lockfile
+      # should not spend a release on its changelog, and the returned array
+      # then holds only the failing result.
       def append_release_internal_checks(member:, memo:)
-        memo << ReadinessCheck.call(
+        appended = []
+        readiness = ReadinessCheck.call(
           member: member,
           config: config,
           allowed_local_path_roots: release_readiness_allowed_local_path_roots(member)
         )
-        memo << ChangelogCheck.call(member: member, config: config) if memo.last.ok?
+        memo << readiness
+        appended << readiness
+        return appended unless readiness.ok?
+
+        published_versions = PublishedVersionCheck.call(member: member)
+        memo << published_versions
+        appended << published_versions
+        return appended unless published_versions.ok?
+
+        changelog = ChangelogCheck.call(member: member, config: config)
+        memo << changelog
+        appended << changelog
+        appended
       end
 
       def release_readiness_allowed_local_path_roots(member)
@@ -4597,8 +4649,16 @@ module Kettle
         total
       end
 
+      # Progress denominator for one member's release. The base four are
+      # check, published_version_check, release_changelog and release_build.
+      #
+      # This must stay in step with what append_release_internal_checks emits:
+      # Progress#increment_member_count clamps the count to the total, so a
+      # total that is too low silently saturates the progress display instead
+      # of failing. Adding a release-internal phase without raising this base
+      # would leave every member showing its final count early.
       def release_phase_total(member = nil)
-        total = 3
+        total = 4
         if member
           normalize = normalize_release_lockfiles?(member)
           total += 2 if normalize
@@ -5723,8 +5783,14 @@ module Kettle
       end
 
       def release_lockfile_readiness_would_fail?(member)
-        result = ReadinessCheck.call(member: member, config: config, allowed_local_path_roots: release_allowed_local_path_roots)
-        result.stdout.lines.any? { |line| line.start_with?("release lockfile has local path remote at ") }
+        readiness = ReadinessCheck.call(
+          member: member,
+          config: config,
+          allowed_local_path_roots: release_allowed_local_path_roots
+        )
+        return true if readiness.stdout.lines.any? { |line| line.start_with?("release lockfile has local path remote at ") }
+
+        !PublishedVersionCheck.call(member: member).ok?
       end
 
       def release_lockfile_has_local_path_remote?(member)
@@ -5975,11 +6041,14 @@ module Kettle
       end
 
       def bundle_update_lockfile_diagnostics(member)
-        ReadinessCheck.call(
+        readiness = ReadinessCheck.call(
           member: member,
           config: config,
           allowed_local_path_roots: bundle_update_allowed_local_path_roots
-        ).stdout.lines.grep(/^release lockfile has local path remote at /).map do |line|
+        ).stdout.lines.grep(/^release lockfile has local path remote at /)
+        unpublished = PublishedVersionCheck.call(member: member).stdout.lines
+
+        (readiness + unpublished).map do |line|
           line.sub("release lockfile", "bundle update lockfile").chomp
         end
       end

data/lib/kettle/family.rb

@@ -5,6 +5,7 @@ require_relative "family/command_result"
 require_relative "family/release_state_result"
 require_relative "family/command_runner"
 require_relative "family/readiness_check"
+require_relative "family/published_version_check"
 require_relative "family/changelog_check"
 require_relative "family/git_status"
 require_relative "family/branch_lane_audit"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-family
 version: !ruby/object:Gem::Version
-  version: 1.3.5
+  version: 1.3.7
 platform: ruby
 authors:
 - Peter H. Boling
@@ -94,7 +94,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.7
+        version: 3.1.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -104,7 +104,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.7
+        version: 3.1.8
 - !ruby/object:Gem::Dependency
   name: kettle-gha-pins
   requirement: !ruby/object:Gem::Requirement
@@ -324,7 +324,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 3.2.14
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -334,7 +334,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.13
+        version: 3.2.14
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -389,6 +389,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.0.15
+- !ruby/object:Gem::Dependency
+  name: gem_mine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
 - !ruby/object:Gem::Dependency
   name: webrick
   requirement: !ruby/object:Gem::Requirement
@@ -436,6 +456,7 @@ files:
 - lib/kettle/family/nomono_bootstrap.rb
 - lib/kettle/family/orderer.rb
 - lib/kettle/family/paths.rb
+- lib/kettle/family/published_version_check.rb
 - lib/kettle/family/readiness_check.rb
 - lib/kettle/family/release_graph.rb
 - lib/kettle/family/release_reconciler.rb
@@ -459,10 +480,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-family.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.3.5
-  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.3.5/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.3.7
+  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.3.7/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-family/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.3.5
+  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.3.7
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-family/wiki
   news_uri: https://www.railsbling.com/tags/kettle-family