kettle-family 1.2.100 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b8d7a476e1af0096eca0bc0870cd9a8623b2ad2ccdcfa5080ec184b5b561096
-  data.tar.gz: df5707cdac3c7838df5cbbc83731ffb7741dfe818e440a83d917792a1f4290b3
+  metadata.gz: c2e7e86419a5d960e83f3e8f7cb5aa1348f5acbe217b02b43e27ca479b9dafd9
+  data.tar.gz: cb5de478d104da8759b0746db6a58f415afb768aae9cd6622e3b4d2a42cdbd09
 SHA512:
-  metadata.gz: 1cc3290cedbd5e35c1c77f4810b6fba3e562297e66a8f1c0d5a0f575110c231771cb460ae67617d289dcf845cde1f0ef4ed09aa996ca5774631fbe1f0c8a4556
-  data.tar.gz: f6e8a65bfd5e7dd3c544a6b47443383a7a9d4cfc7597a52e509bbc9cf765cf1835624f8b4022db1b80b45b2cb0e40c3a5de77acb08f0cfd953c44913d6611454
+  metadata.gz: a60488bf1fc40699a0317e52d6b62318bf0eb243cc42f6950b39b1f7e2e785e7be4de6163a436057d2fcef5a602446dd1acbce249f6ecad7912ccfbc947d7526
+  data.tar.gz: 7c35f5fb09c6edbd5dc63235c0e3a97b69e9aa21a2dffff7c453fa557ab54f9383b7d1d69a9d08972bd1a7f078352dff5cc32991e203d588765570eaecc3ed18

data/CHANGELOG.md

@@ -30,6 +30,17 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [1.3.0] - 2026-09-10
+
+- TAG: [v1.3.0][1.3.0t]
+- COVERAGE: 93.47% -- 6322/6764 lines in 36 files
+- BRANCH COVERAGE: 77.95% -- 2559/3283 branches in 36 files
+- 33.49% documented
+
+### Fixed
+
+- Serialize explicit release dependency graph contracts so CI-resident monorepo paths are preserved while sibling and branch-target releases reject ambient local paths.
+
 ## [1.2.100] - 2026-09-09
 
 - TAG: [v1.2.100][1.2.100t]
@@ -2720,7 +2731,9 @@ 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.2.100...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-family/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/kettle-dev/kettle-family/compare/v1.2.100...v1.3.0
+[1.3.0t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.3.0
 [1.2.100]: https://github.com/kettle-dev/kettle-family/compare/v1.2.99...v1.2.100
 [1.2.100t]: https://github.com/kettle-dev/kettle-family/releases/tag/v1.2.100
 [1.2.99]: https://github.com/kettle-dev/kettle-family/compare/v1.2.98...v1.2.99

data/README.md

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

@@ -284,6 +284,23 @@ module Kettle
         fetch_path("release", "local_path_strategy").to_s
       end
 
+      def release_graph_contract
+        configured = fetch_path("release", "graph_contract").to_s.strip
+        return configured unless configured.empty?
+
+        return "monorepo_ci_local" if ci_resident_local_release_graph?
+        return "wave_transition" if release_local_path_strategy == "waves"
+
+        "registry_only"
+      end
+
+      def release_branch_target_graph_contract
+        configured = fetch_path("release", "branch_target_graph_contract").to_s.strip
+        return configured unless configured.empty?
+
+        "branch_terminal"
+      end
+
       def release_allowed_local_path_roots
         inferred = ci_resident_monorepo_local_path_graph? ? [family_local_path_root] : []
         configured = Array(fetch_path("release", "allowed_local_path_roots"))
@@ -306,6 +323,8 @@ module Kettle
         path_within_root?(family_local_path_root)
       end
 
+      alias_method :ci_resident_local_release_graph?, :ci_resident_monorepo_local_path_graph?
+
       # This remains the repository-topology predicate used by release
       # scheduling. CI-safe local path inference is deliberately narrower.
       def configured_monorepo_release?

data/lib/kettle/family/execution_profile.rb

@@ -68,8 +68,8 @@ module Kettle
           host_platform_policy: :active_platform_must_resolve,
           allowed_mutations: %i[canonical_release_lockfiles configured_wave_paths]
         ),
-        release_recovery: Definition.new(
-          name: :release_recovery,
+        release_wave_transition: Definition.new(
+          name: :release_wave_transition,
           path_gem_policy: :configured_release_wave,
           lockfile_role: :canonical,
           install_location: :disposable,

data/lib/kettle/family/release_graph.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kettle
+  module Family
+    # Immutable release dependency graph selected for one member or branch
+    # target. It is passed to kettle-dev as data, never reconstructed from
+    # whichever *_DEV variables happened to launch the family command.
+    class ReleaseGraph
+      ENV_KEY = "KETTLE_RELEASE_GRAPH_CONTRACT_JSON"
+      NAMES = %w[registry_only wave_transition monorepo_ci_local branch_terminal].freeze
+
+      attr_reader :name, :ci_root, :local_path_roots, :selector_env
+
+      def initialize(name:, ci_root: nil, local_path_roots: [], selector_env: {})
+        @name = name.to_s
+        @ci_root = canonical_path(ci_root) if ci_root
+        @local_path_roots = Array(local_path_roots).map { |path| canonical_path(path) }.uniq.freeze
+        @selector_env = selector_env.to_h.transform_keys(&:to_s).transform_values(&:to_s).freeze
+        validate!
+        freeze
+      end
+
+      def registry_only?
+        name == "registry_only" || name == "branch_terminal"
+      end
+
+      def local_paths?
+        !local_path_roots.empty?
+      end
+
+      def environment
+        selector_env.merge(ENV_KEY => JSON.generate(to_h))
+      end
+
+      def to_h
+        {
+          "name" => name,
+          "ci_root" => ci_root,
+          "local_path_roots" => local_path_roots,
+          "selector_env" => selector_env
+        }
+      end
+
+      private
+
+      def validate!
+        raise Error, "unknown release graph contract #{name.inspect}" unless NAMES.include?(name)
+
+        if registry_only? && (local_paths? || !selector_env.empty?)
+          raise Error, "#{name} release graph cannot declare local paths or selectors"
+        end
+        return unless %w[wave_transition monorepo_ci_local].include?(name)
+
+        raise Error, "#{name} release graph requires at least one local path root" unless local_paths?
+        raise Error, "#{name} release graph requires a local path selector" if selector_env.empty?
+
+        selector_env.each_value do |value|
+          next if local_path_roots.any? { |root| value == root || value.start_with?("#{root}/") }
+
+          raise Error, "#{name} selector #{value.inspect} is outside its declared local path roots"
+        end
+
+        return unless name == "monorepo_ci_local"
+
+        raise Error, "monorepo_ci_local release graph requires a CI root" if ci_root.to_s.empty?
+        local_path_roots.each do |path|
+          next if path == ci_root || path.start_with?("#{ci_root}/")
+
+          raise Error, "monorepo_ci_local path #{path.inspect} is outside CI root #{ci_root.inspect}"
+        end
+      end
+
+      def canonical_path(path)
+        expanded = File.expand_path(path)
+        File.realpath(expanded)
+      rescue Errno::ENOENT
+        expanded
+      end
+    end
+  end
+end

data/lib/kettle/family/version.rb

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

data/lib/kettle/family/workflow.rb

@@ -3668,16 +3668,16 @@ module Kettle
       # changelog may live at the family root. Pass the shared paths to the
       # member release phase as well as to the separate family phase.
       def release_env_for_member(member, family_root: config.root, wave_jobs: 1)
+        graph = release_graph_for(member, family_root: family_root)
         env = execution_profile(release_bootstrap_execution_profile, release_env)
-        env.merge!(release_wave_local_path_env_for(member, family_root: family_root))
-        env.merge!(release_local_path_policy_env(family_root: family_root))
+        env.merge!(release_lockfile_local_path_env_overrides(member, graph: graph))
+        env.merge!(graph.environment)
         # A resumed child kettle-release starts in the member's mise
         # environment after the release candidate was already prepared.
         # Disable sibling paths so mise cannot reactivate them before the
         # resumed release validates that immutable lockfile. A new release
         # retains the staged local-graph policy until kettle-release reaches
         # its own release-lockfile boundary.
-        env.merge!(release_lockfile_local_path_env_overrides(member)) if release_step_resume?
         # Family release performs one live pin review before member releases.
         # Child kettle-release must consume that reviewed cache instead of
         # repeating the GitHub API lookup for every member.
@@ -3755,37 +3755,6 @@ module Kettle
         family_gemfile if File.file?(family_gemfile)
       end
 
-      # A release task may start with local sibling paths so a member can
-      # consume a selected dependency that has not been published yet. Once
-      # that dependency is complete in an earlier wave, use its registry
-      # release for the next member. Dependencies outside the selected set are
-      # already treated as registry dependencies; this is what makes resume
-      # runs work after an earlier wave has been published.
-      def release_wave_local_path_env_for(member, family_root: config.root)
-        # Monorepo members and their sibling dependencies share the same CI
-        # checkout, so their canonical development lockfile may keep those
-        # paths throughout every release wave.
-        if config.configured_monorepo_release?
-          env_name = config.family_local_path_env_name
-          return env_name ? {env_name => family_local_path_root_for(family_root)} : {}
-        end
-
-        return {} unless config.release_local_path_strategy == "waves"
-
-        env_name = config.family_local_path_env_name
-        return {} if env_name.to_s.empty?
-
-        local_value = release_env[env_name]
-        return {} unless local_path_env_value?(local_value)
-
-        selected_names = members.map(&:name)
-        completed_names = Array(@release_completed_member_names)
-        unresolved_selected_dependency = release_dependency_names(member).any? do |dependency|
-          selected_names.include?(dependency) && !completed_names.include?(dependency)
-        end
-        {env_name => unresolved_selected_dependency ? local_value : "false"}
-      end
-
       # simplecov:disable Covered by monorepo release integration, not sibling-repository suite.
       def aggregate_monorepo_github_release(members)
         version = members.map { |member| member.version.to_s }.uniq
@@ -5417,14 +5386,61 @@ module Kettle
       end
 
       def release_lockfile_execution_profile
-        return ExecutionProfile.fetch(:release_recovery) if release_recovery?
-        return ExecutionProfile.fetch(:release_monorepo) if preserve_monorepo_template_context?
+        release_graph_execution_profile(release_graph_for(family_member))
+      end
 
-        ExecutionProfile.fetch(:release_registry)
+      def release_graph_execution_profile(graph)
+        case graph.name
+        when "monorepo_ci_local"
+          ExecutionProfile.fetch(:release_monorepo)
+        when "wave_transition"
+          ExecutionProfile.fetch(:release_wave_transition)
+        when "branch_terminal", "registry_only"
+          ExecutionProfile.fetch(:release_registry)
+        else
+          raise Error, "unknown release graph contract #{graph.name.inspect}"
+        end
       end
 
-      def release_recovery?
-        !start_step.nil? || !skip_steps.to_s.empty? || fast_recovery || skip_ci
+      def release_graph_for(member, family_root: config.root)
+        name = if config.release_target_branches.any?
+          config.release_branch_target_graph_contract
+        else
+          config.release_graph_contract
+        end
+
+        case name
+        when "registry_only", "branch_terminal"
+          ReleaseGraph.new(name: name, ci_root: family_root)
+        when "monorepo_ci_local"
+          unless config.ci_resident_local_release_graph?
+            raise Error, "monorepo_ci_local requires family.local_path_root to be contained by the family repository"
+          end
+
+          env_name = config.family_local_path_env_name
+          raise Error, "monorepo_ci_local requires family.local_path_env" if env_name.to_s.empty?
+
+          root = family_local_path_root_for(family_root)
+          ReleaseGraph.new(name: name, ci_root: family_root, local_path_roots: [root], selector_env: {env_name => root})
+        when "wave_transition"
+          env_name = config.family_local_path_env_name
+          raise Error, "wave_transition requires family.local_path_env" if env_name.to_s.empty?
+
+          local_value = release_local_path_env_sources[env_name]
+          return ReleaseGraph.new(name: "registry_only", ci_root: family_root) unless local_path_env_value?(local_value)
+
+          selected_names = members.map(&:name)
+          completed_names = Array(@release_completed_member_names)
+          unresolved_selected_dependency = release_dependency_names(member).any? do |dependency|
+            selected_names.include?(dependency) && !completed_names.include?(dependency)
+          end
+          return ReleaseGraph.new(name: "registry_only", ci_root: family_root) unless unresolved_selected_dependency
+
+          root = File.expand_path(local_value)
+          ReleaseGraph.new(name: name, ci_root: family_root, local_path_roots: [root], selector_env: {env_name => root})
+        else
+          raise Error, "unknown release graph contract #{name.inspect}"
+        end
       end
 
       def release_step_resume?
@@ -5438,7 +5454,7 @@ module Kettle
         when :template_local
           env["K_JEM_TEMPLATING"] = "true"
           env["BUNDLE_DISABLE_CHECKSUM_VALIDATION"] = "true"
-        when :release_bootstrap, :release_registry, :release_monorepo, :release_recovery
+        when :release_bootstrap, :release_registry, :release_monorepo, :release_wave_transition
           # Release profiles deliberately leave Bundler mutation decisions to
           # kettle-dev. The profile selection controls which local-path
           # overrides this workflow contributes below.
@@ -5492,12 +5508,14 @@ module Kettle
       end
 
       def release_lockfile_env(member = nil)
+        graph = release_graph_for(member || family_member)
         execution_profile(
-          release_lockfile_execution_profile,
+          release_graph_execution_profile(graph),
           base_release_env
           .merge(release_lockfile_bundler_env_resets)
           .merge(env_overrides)
-          .merge(release_lockfile_local_path_env_overrides(member))
+          .merge(release_lockfile_local_path_env_overrides(member, graph: graph))
+          .merge(graph.environment)
         )
       end
 
@@ -5508,8 +5526,8 @@ module Kettle
         }
       end
 
-      def release_allowed_local_path_roots
-        config.release_allowed_local_path_roots
+      def release_allowed_local_path_roots(member = family_member)
+        release_graph_for(member).local_path_roots
       end
 
       def family_local_path_root_for(family_root)
@@ -5519,38 +5537,13 @@ module Kettle
         File.expand_path(relative, family_root)
       end
 
-      def release_allowed_local_path_env_names
-        names = config.release_allowed_local_path_env_names
-        names << "K_JEM_TEMPLATING" if preserve_monorepo_template_context?
-        names.uniq
-      end
-
-      def release_local_path_policy_env(family_root: config.root)
-        roots = release_allowed_local_path_roots.map do |root|
-          if File.expand_path(family_root) == File.expand_path(config.root)
-            root
-          else
-            relative = Pathname.new(root).relative_path_from(Pathname.new(config.root))
-            File.expand_path(relative, family_root)
-          end
-        end
-        env_names = release_allowed_local_path_env_names
-        return {} if roots.empty? && env_names.empty?
-
-        {
-          "KETTLE_RELEASE_ALLOWED_LOCAL_PATH_ROOTS" => roots.join(File::PATH_SEPARATOR),
-          "KETTLE_RELEASE_ALLOWED_LOCAL_PATH_ENVS" => env_names.join(",")
-        }
-      end
-
-      def release_lockfile_local_path_env_overrides(member = nil)
+      def release_lockfile_local_path_env_overrides(member = nil, graph: release_graph_for(member || family_member))
         explicit = config.release_disable_local_path_env.to_h { |key| [key.to_s, "false"] }
-        explicit.delete("K_JEM_TEMPLATING") if preserve_monorepo_template_context?
         derived = release_local_path_env_detection_sources.each_with_object({}) do |(key, value), memo|
           key = key.to_s
           next unless key.end_with?("_LOCAL", "_DEV")
           next unless local_path_env_value?(value)
-          next if release_allowed_local_path_env_names.include?(key)
+          next if graph.selector_env.key?(key)
 
           memo[key] = "false"
         end
@@ -5558,24 +5551,7 @@ module Kettle
         explicit
           .merge(derived)
           .merge(inferred)
-          .merge(release_member_local_path_env(member))
-          .merge(preserve_monorepo_template_context? ? {"K_JEM_TEMPLATING" => "true"} : {})
-      end
-
-      # K_JEM_TEMPLATING activates the generated monorepo dependency closure;
-      # it is not an unrelated local checkout switch. Preserve it only when
-      # the caller explicitly enabled it for a configured monorepo release.
-      def preserve_monorepo_template_context?
-        return false unless config.configured_monorepo_release?
-
-        value = release_local_path_env_sources["K_JEM_TEMPLATING"].to_s.strip.downcase
-        %w[true yes 1 on].include?(value)
-      end
-
-      def release_member_local_path_env(member)
-        return {} unless config.configured_monorepo_release?
-
-        release_wave_local_path_env_for(member)
+          .merge(graph.selector_env)
       end
 
       def release_lockfile_inferred_local_path_env(member)

data/lib/kettle/family.rb

@@ -22,6 +22,7 @@ require_relative "family/nomono_bootstrap"
 require_relative "family/debugger_bootstrap"
 require_relative "family/appraisal_bootstrap"
 require_relative "family/release_waves"
+require_relative "family/release_graph"
 require_relative "family/execution_profile"
 require_relative "family/workflow"
 require_relative "family/discovery"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-family
 version: !ruby/object:Gem::Version
-  version: 1.2.100
+  version: 1.3.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -94,7 +94,7 @@ dependencies:
         version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.34
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -104,7 +104,7 @@ dependencies:
         version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.34
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: kettle-gha-pins
   requirement: !ruby/object:Gem::Requirement
@@ -422,6 +422,7 @@ files:
 - lib/kettle/family/nomono_bootstrap.rb
 - lib/kettle/family/orderer.rb
 - lib/kettle/family/readiness_check.rb
+- lib/kettle/family/release_graph.rb
 - lib/kettle/family/release_reconciler.rb
 - lib/kettle/family/release_state_check.rb
 - lib/kettle/family/release_state_event_tape.rb
@@ -443,10 +444,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.2.100
-  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.2.100/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-family/tree/v1.3.0
+  changelog_uri: https://github.com/kettle-dev/kettle-family/blob/v1.3.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-family/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.2.100
+  documentation_uri: https://www.rubydoc.info/gems/kettle-family/1.3.0
   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