kettle-dev 3.0.34 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf4388ae02268bbe6676ece5cee25b5548277a6e60432554c460f189ca02d2f0
-  data.tar.gz: 80841fd013dbd2868b22e36b185c18c0a7f90ed3698f5cb3a2d666c46a80b41b
+  metadata.gz: b7fdd37cea8287569cfe883f3b0830022afe7e90be2582adf2046cadcdd687c7
+  data.tar.gz: 327f6277c15a6e780001e321192b72e5a10afc56718171e3324e24445c0466b5
 SHA512:
-  metadata.gz: 713c1d308268ce8cde18124db06ad5efed08d53fc945af0c723843de08d840b6db23f946941de187b2adcf61e482e206e307fda8bbd52b562c3aaed1fd61ee91
-  data.tar.gz: 8e94e9a97e3ae52b955fd098db642ab23639fb6e0d67b2abed14fe8684248430c50618b8f8d6f3d0a57bb1934954e1f41fe7b17711fac151bdca9928b98a0795
+  metadata.gz: f7cb591d2c7e73f063f11362091eb7efc51ff3d9b6a5cd4242260e3dd45fe1ffce867a77e218f606880f7cfd7bf5fd1f071391714b8164721c89860d4b63c737
+  data.tar.gz: 99531967a52f754cbda4a1d868e216de15d1dac6e6d27d1b4028dad9dae87681b1a88761f91d0931425d050f9ae0a6a18344c19f48621dfccac346f9a539c9ec

data/CHANGELOG.md

@@ -30,6 +30,19 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.1.0] - 2026-09-10
+
+- TAG: [v3.1.0][3.1.0t]
+- COVERAGE: 91.86% -- 6141/6685 lines in 48 files
+- BRANCH COVERAGE: 76.10% -- 2337/3071 branches in 48 files
+- 51.02% documented
+
+### Fixed
+
+- [kc] release-graph-contracts: Honor the serialized release graph for lockfile normalization and child commands, retaining only declared CI-resident monorepo paths.
+
+- Validate serialized family release graph contracts in release lockfile normalization and child commands instead of reconstructing local-path policy from ambient environment.
+
 ## [3.0.34] - 2026-09-09
 
 - TAG: [v3.0.34][3.0.34t]
@@ -3847,7 +3860,9 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v3.0.34...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v3.1.0...HEAD
+[3.1.0]: https://github.com/kettle-dev/kettle-dev/compare/v3.0.34...v3.1.0
+[3.1.0t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v3.1.0
 [3.0.34]: https://github.com/kettle-dev/kettle-dev/compare/v3.0.33...v3.0.34
 [3.0.34t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v3.0.34
 [3.0.33]: https://github.com/kettle-dev/kettle-dev/compare/v3.0.32...v3.0.33

data/README.md

@@ -1066,7 +1066,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.635-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-6.685-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-dev/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/dev/lockfile_reset.rb

@@ -9,6 +9,7 @@ require "bundler"
 require "ripper"
 
 require_relative "bundler_env_guard"
+require_relative "release_graph_contract"
 
 module Kettle
   module Dev
@@ -22,8 +23,6 @@ module Kettle
         "GALTZO_FLOSS_DEV" => "false",
         "UR_BRAIN_DEV" => "false"
       }.freeze
-      ALLOWED_LOCAL_PATH_ROOTS_ENV = "KETTLE_RELEASE_ALLOWED_LOCAL_PATH_ROOTS"
-      ALLOWED_LOCAL_PATH_ENVS_ENV = "KETTLE_RELEASE_ALLOWED_LOCAL_PATH_ENVS"
       RELEASE_LOCKFILES_TARGET = "release-lockfiles"
       SUPPORTED_TARGETS = ["Gemfile.lock", "Appraisal.root.gemfile.lock", RELEASE_LOCKFILES_TARGET].freeze
       UNBUNDLED_ENV_KEYS = (BundlerEnvGuard::RESET_ENV_KEYS + %w[
@@ -113,28 +112,30 @@ module Kettle
         @root = root
         @command_runner = command_runner
         @release_platforms = {}
-        @allowed_local_path_roots = configured_allowed_local_path_roots
-        @allowed_local_path_env_names = configured_allowed_local_path_env_names
+        @release_graph_contract = ReleaseGraphContract.from_environment(root: root)
       end
 
       def reset(target, skip_changelog_dependency: false)
         BundlerEnvGuard.warn_unexpected_env!
         paths = lockfile_paths_for(target)
-        # A monorepo lockfile may deliberately use paths rooted in the
-        # repository's members directory. Keep that valid development graph;
-        # only rebuild when an unapproved path or other diagnostic remains.
-        force_full_update = release_lockfiles_target?(target) &&
-          (allowed_local_path_roots.empty? || paths.any? { |path| normalization_needed?(path) })
+        release_lockfiles = release_lockfiles_target?(target)
+        # The selected graph governs both tracked release locks and disposable
+        # release-task locks. Registry contracts reject every PATH source;
+        # CI-resident monorepo contracts retain only declared contained paths.
+        force_full_update = release_lockfiles && (
+          release_graph_contract.registry_only? || paths.any? { |path| normalization_needed?(path, strict: true) }
+        )
         platforms = release_platforms_for(paths) if force_full_update
         uninstall_unreleased_local_gems(paths) if force_full_update
         paths.each do |path|
-          if force_full_update || normalization_needed?(path)
+          if force_full_update || normalization_needed?(path, strict: release_lockfiles)
             reset_lockfile!(
               path,
               full_update: force_full_update,
               platforms: platforms&.fetch(path),
               skip_changelog_dependency: skip_changelog_dependency,
-              update_bundler: force_full_update
+              update_bundler: force_full_update,
+              strict: release_lockfiles
             )
           end
         end
@@ -145,17 +146,18 @@ module Kettle
               full_update: true,
               platforms: platforms.fetch(path),
               skip_changelog_dependency: skip_changelog_dependency,
-              update_bundler: true
+              update_bundler: true,
+              strict: release_lockfiles
             )
           end
         end
-        diagnostics = paths.flat_map { |path| diagnostics(path) }
+        diagnostics = paths.flat_map { |path| diagnostics(path, strict: release_lockfiles) }
         raise Error, validation_message(target, diagnostics) unless diagnostics.empty?
 
         paths
       end
 
-      def reset_lockfile!(path, full_update: false, platforms: nil, skip_changelog_dependency: false, update_bundler: false)
+      def reset_lockfile!(path, full_update: false, platforms: nil, skip_changelog_dependency: false, update_bundler: false, strict: false)
         gemfile = gemfile_for_lockfile(path)
         unless gemfile && File.file?(gemfile)
           warn("Cannot reset #{display_path(path)} because its Gemfile was not found.")
@@ -171,9 +173,10 @@ module Kettle
             platforms: platforms,
             skip_changelog_dependency: skip_changelog_dependency,
             update_bundler: update_bundler,
-            isolated_gem_home: gem_home
+            isolated_gem_home: gem_home,
+            strict: strict
           )
-          if full_update || has_local_path_remote?(path)
+          if full_update || has_local_path_remote?(path, strict: strict)
             rebuild_lockfile(path) { command_runner.call(command) }
           else
             command_runner.call(command)
@@ -181,11 +184,11 @@ module Kettle
         end
       end
 
-      def reset_command(path:, gemfile:, full_update: false, platforms: nil, skip_changelog_dependency: false, update_bundler: false, isolated_gem_home: nil, isolated_gem_path: nil)
-        update_gems = (full_update || has_local_path_remote?(path)) ? [] : reset_update_gems(path)
+      def reset_command(path:, gemfile:, full_update: false, platforms: nil, skip_changelog_dependency: false, update_bundler: false, isolated_gem_home: nil, isolated_gem_path: nil, strict: false)
+        update_gems = (full_update || has_local_path_remote?(path, strict: strict)) ? [] : reset_update_gems(path)
         platforms ||= reset_platforms(path)
         removed_platforms = full_update ? [] : lockfile_platforms(path) - platforms
-        env = normalization_env.merge(
+        env = (strict ? release_normalization_env : normalization_env).merge(
           "BUNDLE_GEMFILE" => gemfile,
           "BUNDLE_LOCKFILE" => path
         )
@@ -263,14 +266,14 @@ module Kettle
         ).uniq.sort
       end
 
-      def normalization_needed?(path)
-        has_local_path_remote?(path) ||
+      def normalization_needed?(path, strict: false)
+        has_local_path_remote?(path, strict: strict) ||
           !empty_registry_checksums(path).empty? ||
           !unreleased_workspace_registry_specs(path).empty? ||
           bundled_with_checksum_mismatch?(path)
       end
 
-      def diagnostics(path)
+      def diagnostics(path, strict: false)
         diagnostics = []
         disallowed_local_path_remote_lines(path).each do |line_number|
           diagnostics << "#{display_path(path)} has local path remote at line #{line_number}"
@@ -332,9 +335,17 @@ module Kettle
       end
 
       def normalization_env
-        DEFAULT_DISABLED_ENV
-          .reject { |name, _| allowed_local_path_env_names.include?(name) }
-          .merge(dynamic_local_path_env)
+        disabled_local_path_env
+      end
+
+      # The release graph, not ambient development ENV, decides which local
+      # selectors remain active while Bundler normalizes a release lockfile.
+      def release_normalization_env
+        disabled_local_path_env.merge(release_graph_contract.normalization_environment)
+      end
+
+      def disabled_local_path_env
+        DEFAULT_DISABLED_ENV.merge(dynamic_local_path_env)
       end
 
       # Appraisal generation normally uses the release-normalized environment.
@@ -354,7 +365,7 @@ module Kettle
         ENV.each_with_object({}) do |(key, value), env|
           next unless key.end_with?("_DEV", "_LOCAL")
           next unless local_path_env_value?(value)
-          next if allowed_local_path_env_names.include?(key)
+          next if release_graph_contract.selector_env.key?(key)
 
           env[key] = "false"
         end
@@ -376,15 +387,16 @@ module Kettle
         local_path_env_value?(ENV[name])
       end
 
-      def has_local_path_remote?(path)
-        !disallowed_local_path_remote_lines(path).empty?
+      def has_local_path_remote?(path, strict: false)
+        paths = disallowed_local_path_remote_lines(path)
+        !paths.empty?
       end
 
       def local_path_remote_lines(path)
         self.class.local_path_remote_lines_from_source(File.read(path))
       end
 
-      attr_reader :allowed_local_path_roots, :allowed_local_path_env_names
+      attr_reader :release_graph_contract
 
       def disallowed_local_path_remote_lines(path)
         local_path_remote_lines(path).reject do |line_number|
@@ -392,25 +404,12 @@ module Kettle
         end
       end
 
-      def configured_allowed_local_path_roots
-        ENV.fetch(ALLOWED_LOCAL_PATH_ROOTS_ENV, "").split(File::PATH_SEPARATOR).filter_map do |value|
-          next if value.strip.empty?
-
-          canonical_path(value)
-        end.uniq
-      end
-
-      def configured_allowed_local_path_env_names
-        ENV.fetch(ALLOWED_LOCAL_PATH_ENVS_ENV, "").split(",").map(&:strip).reject(&:empty?).uniq
-      end
-
       def local_path_remote_at(path, line_number)
         File.readlines(path)[line_number - 1].to_s.split("remote:", 2).last.to_s.strip
       end
 
       def allowed_local_path?(path)
-        remote = canonical_path(path)
-        allowed_local_path_roots.any? { |root| remote == root || remote.start_with?("#{root}/") }
+        release_graph_contract.allowed_path?(path)
       end
 
       def canonical_path(path)

data/lib/kettle/dev/release_cli.rb

@@ -888,11 +888,11 @@ module Kettle
       end
 
       def release_lockfile_normalization_needed?(path)
-        lockfile_reset.normalization_needed?(path)
+        lockfile_reset.normalization_needed?(path, strict: true)
       end
 
       def normalize_release_lockfile!(path)
-        lockfile_reset.reset_lockfile!(path)
+        lockfile_reset.reset_lockfile!(path, strict: true)
       end
 
       def release_gemfile_for_lockfile(path)
@@ -900,29 +900,32 @@ module Kettle
       end
 
       def release_lockfile_normalization_env
-        lockfile_reset.normalization_env
+        lockfile_reset.release_normalization_env
       end
 
       # The release process has three distinct lockfile roles:
       #
-      # - canonical: tracked project lockfiles, always registry-backed;
+      # - canonical: tracked project lockfiles, using the declared release
+      #   graph (normally registry-only, or contained CI-resident monorepo
+      #   paths when kettle-family supplied that contract);
       # - task: a disposable Gemfile.lock copy for build and publication; and
       # - tool: a tool-owned Gemfile, such as kettle-changelog's release bundle.
       #
-      # A family may use local sibling gems to launch this process, but no
-      # release child may inherit that graph. Git hooks are release children
-      # too: they commonly load project tooling and otherwise can silently
-      # rewrite the canonical lockfile with local PATH sources.
+      # A family may use local sibling gems to launch this process. Release
+      # children receive only the serialized release graph, never the ambient
+      # launcher graph. Git hooks are release children too: they commonly load
+      # project tooling and otherwise can silently rewrite a lockfile with an
+      # undeclared local PATH source.
       def release_git_hook_environment
         release_child_environment
       end
 
       def release_lockfile_diagnostics(path)
-        lockfile_reset.diagnostics(path)
+        lockfile_reset.diagnostics(path, strict: true)
       end
 
       def release_lockfile_has_local_path_remote?(path)
-        lockfile_reset.has_local_path_remote?(path)
+        lockfile_reset.has_local_path_remote?(path, strict: true)
       end
 
       def release_lockfile_local_path_remote_lines(path)
@@ -1123,9 +1126,9 @@ module Kettle
       end
 
       # Every release child runs outside the release tool's Bundler context and
-      # with local sibling switches disabled. The optional lockfile identifies
-      # a disposable task lockfile; omitting it deliberately selects the
-      # canonical tracked lockfile for setup, checks, docs, and checksums.
+      # with only the serialized release graph enabled. The optional lockfile
+      # identifies a disposable task lockfile; omitting it deliberately selects
+      # the canonical tracked lockfile for setup, checks, docs, and checksums.
       def release_child_command(command, environment: {}, lockfile: nil)
         command_body = command
         command = +"env"

data/lib/kettle/dev/release_graph_contract.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Kettle
+  module Dev
+    # Parsed contract supplied by kettle-family for a single release target.
+    # Direct kettle-release calls receive the safe registry-only default.
+    class ReleaseGraphContract
+      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 self.from_environment(root:)
+        raw = (ENV[ENV_KEY] || "").strip
+        return new(name: "registry_only", root: root, ci_root: root) if raw.empty?
+
+        data = JSON.parse(raw)
+        new(
+          name: data["name"],
+          ci_root: data["ci_root"] || root,
+          local_path_roots: data["local_path_roots"] || [],
+          selector_env: data["selector_env"] || {},
+          root: root
+        )
+      rescue JSON::ParserError, KeyError, TypeError => error
+        raise Error, "invalid #{ENV_KEY}: #{error.message}"
+      end
+
+      def initialize(name:, root:, ci_root:, local_path_roots: [], selector_env: {})
+        @name = String(name)
+        @root = File.realpath(root)
+        @ci_root = canonical_path(ci_root)
+        @local_path_roots = Array(local_path_roots).map { |path| canonical_path(path) }.uniq.freeze
+        @selector_env = selector_env.to_h.map { |key, value| [String(key), String(value)] }.to_h.freeze
+        validate!
+        freeze
+      end
+
+      def local_paths?
+        !local_path_roots.empty?
+      end
+
+      def registry_only?
+        name == "registry_only" || name == "branch_terminal"
+      end
+
+      def allowed_path?(path)
+        candidate = canonical_path(path)
+        local_path_roots.any? { |root| path_within_root?(candidate, root) }
+      end
+
+      def normalization_environment
+        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 local path roots" unless local_paths?
+        raise Error, "#{name} release graph requires local path selectors" if selector_env.empty?
+
+        selector_env.each_value do |value|
+          next if allowed_path?(value)
+
+          raise Error, "#{name} selector #{value.inspect} is outside its declared local path roots"
+        end
+        return unless name == "monorepo_ci_local"
+
+        unless path_within_root?(@root, ci_root)
+          raise Error, "monorepo_ci_local release root #{@root.inspect} is outside CI root #{ci_root.inspect}"
+        end
+        local_path_roots.each do |path|
+          next if path_within_root?(path, 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, @root)
+        File.realpath(expanded)
+      rescue Errno::ENOENT
+        expanded
+      end
+
+      def path_within_root?(path, root)
+        path == root || (path[0, root.length] == root && path[root.length] == "/")
+      end
+    end
+  end
+end

data/lib/kettle/dev/version.rb

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

data/lib/kettle/dev.rb

@@ -49,6 +49,7 @@ module Kettle
     autoload :OpenCollectiveConfig, "kettle/dev/open_collective_config"
     autoload :ReleaseNotifier, "kettle/dev/release_notifier"
     autoload :ReleaseCLI, "kettle/dev/release_cli"
+    autoload :ReleaseGraphContract, "kettle/dev/release_graph_contract"
     autoload :ReleaseSecrets, "kettle/dev/release_secrets"
     autoload :ReleaseSecretsDoctor, "kettle/dev/release_secrets_doctor"
     autoload :ResetCLI, "kettle/dev/reset_cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 3.0.34
+  version: 3.1.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -382,6 +382,7 @@ files:
 - lib/kettle/dev/rakelib/yard.rake
 - lib/kettle/dev/readme_backers.rb
 - lib/kettle/dev/release_cli.rb
+- lib/kettle/dev/release_graph_contract.rb
 - lib/kettle/dev/release_notifier.rb
 - lib/kettle/dev/release_secrets.rb
 - lib/kettle/dev/release_secrets_doctor.rb
@@ -400,10 +401,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v3.0.34
-  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v3.0.34/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v3.1.0
+  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v3.1.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/3.0.34
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/3.1.0
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev