bundler-conservative-update 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1a4ccaabd989d98fa9366f6d41905b4b0f343c2bf82aab17e73e3b561ab4db0
+  data.tar.gz: a50dc2157b5e28562b8a1af937e5408eb58c0f25021ac3999b663078a57c3b37
+SHA512:
+  metadata.gz: 7fcf8501218bd8f636e5b4e2174c20061f9e02f0030aaa4296e0b2f93157903a843b740bff1ad4d23fe0beac63b371ca697c8d8d75fbdbf31de5bafcfb8f7d46
+  data.tar.gz: 2ca8818cdd1524c7c4ad3399997e1e0d0ed381f0a2219fdb1a533f451ab80f1428838fc2d286db747a82b76c257786583ee7a2467bf3733e4477e6d9d9acb9a1

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 1.0.0 - 2026-08-05
+
+### Added
+
+- Initial release: `bundle update` invocations that name gems, or a group, are
+  re-executed with `--conservative`, so only those gems are unlocked and
+  transitive dependencies stay locked.
+- Invocations that name nothing to update are left to Bundler, since
+  `--conservative` without an explicit unlock widens the resolution to every
+  direct dependency: a bare `bundle update`, `--all`, `--bundler`, `--source`
+  and `--ruby`.
+- Explicit update strategies are respected: `--conservative`, `--patch`,
+  `--minor`, `--major` and `--strict` all suppress the injection.
+- Values of `--gemfile`, `--jobs`/`-j`, `--cooldown` and `--retry`/`-r` are not
+  mistaken for gem names.
+- `BUNDLER_CONSERVATIVE_UPDATE_DISABLE=1` (or `true`) opts a single run out.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Buk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# bundler-conservative-update
+
+[![CI](https://github.com/bukhr/bundler-conservative-update/actions/workflows/ci.yml/badge.svg)](https://github.com/bukhr/bundler-conservative-update/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/bundler-conservative-update)](https://rubygems.org/gems/bundler-conservative-update)
+
+A [Bundler plugin](https://bundler.io/guides/bundler_plugins.html) that makes
+[`bundle update`](https://bundler.io/man/bundle-update.1.html) conservative by
+default: only the gems you name get updated, and transitive dependencies stay
+locked.
+
+```console
+$ bundle update rails                 # behaves like `bundle update --conservative rails`
+$ bundle update --all                 # untouched: explicit "update everything"
+$ bundle update --minor rails         # untouched: explicit strategy
+```
+
+## The problem
+
+`bundle update rails` does not just update `rails`. Bundler also unlocks its
+dependencies and moves them to the newest versions the `Gemfile` allows, so a
+one-gem bump produces a `Gemfile.lock` diff nobody asked for or reviewed:
+
+```console
+bundle update rails && git diff --stat Gemfile.lock
+ Gemfile.lock | 74 +++++++++++++++++++++++-----------------------
+```
+
+[`--conservative`](https://bundler.io/man/bundle-update.1.html) avoids this, but
+it is opt-in per invocation: it only helps when every person and every script
+remembers to type it, and Bundler has no setting to make it the default
+(`prefer_patch` is related but different, see
+[Relationship to prefer_patch](#relationship-to-prefer_patch)).
+
+This plugin turns that behavior into the project's default. Because it is
+declared in the `Gemfile`, the policy covers every `bundle update` run on the
+project — yours, your teammates', and CI's — with no flag to remember.
+
+## Installation
+
+Add the plugin to your `Gemfile`:
+
+```ruby
+plugin "bundler-conservative-update"
+```
+
+The next `bundle install` installs the plugin.
+
+See [bundle-plugin](https://bundler.io/man/bundle-plugin.1.html).
+
+## Usage
+
+There is nothing to configure. Run `bundle update` as usual:
+
+```console
+bundle update rails
+bundler-conservative-update: re-running with --conservative (only requested gems are updated; set BUNDLER_CONSERVATIVE_UPDATE_DISABLE=1 to opt out)
+  Pass --patch, --minor, --major or --all to choose a different update strategy.
+```
+
+The plugin re-executes the command as `bundle update --conservative rails`. It
+injects only when the invocation **names something to update** and has not
+already stated its own update strategy:
+
+| Invocation | `--conservative` injected? | Why |
+|---|---|---|
+| `bundle update rails` | yes | names a gem |
+| `bundle update rails --local` | yes | flags that do not change resolution scope are preserved |
+| `bundle update --group dev` | yes | Bundler expands the group into the gems to unlock |
+| `bundle update` (no gems) | no | names nothing; see note below |
+| `bundle install`, `bundle exec`, `bundle lock`, … | no | not an update |
+| `bundle update --conservative rails` | no | already requested; also the recursion guard |
+| `bundle update --patch/--minor/--major/--strict rails` | no | explicit update strategy |
+| `bundle update --all` | no | explicit "update everything" |
+| `bundle update --bundler[=X]`, `--source[=X]`, `--ruby` | no | see note below |
+| any of the above with `BUNDLER_CONSERVATIVE_UPDATE_DISABLE=1` | no | [opt-out](#opting-out) |
+
+> All the "names nothing" cases share one reason. `--conservative` restricts the
+> resolution through the list of gems Bundler was explicitly asked to unlock;
+> when that list is empty, Bundler falls back to unlocking **every** direct
+> dependency of the `Gemfile` — the exact outcome this plugin exists to prevent.
+> A bare `bundle update` names no gem, and `--bundler`, `--source` and `--ruby`
+> change *what* is being resolved rather than naming gems, so injecting there
+> would not restrict anything. Those invocations are left to Bundler.
+
+The re-execution uses `Kernel.exec`, which replaces the current process: stdin
+and the TTY are inherited, and the exit code you get is the real
+`bundle update`'s.
+
+### Opting out
+
+To let a single update reach transitive dependencies on purpose, set
+`BUNDLER_CONSERVATIVE_UPDATE_DISABLE` to `1` or `true` (case-insensitive):
+
+```console
+BUNDLER_CONSERVATIVE_UPDATE_DISABLE=1 bundle update rails
+```
+
+There is no permanent, per-project opt-out by design: a project that wants
+unconstrained updates should not declare the plugin. For the periodic "update
+everything" chore no variable is needed — `--all` is already respected:
+
+```console
+bundle update --all
+```
+
+## Relationship to `prefer_patch`
+
+Bundler's [`prefer_patch`](https://bundler.io/man/bundle-config.1.html) setting
+(`BUNDLE_PREFER_PATCH`) makes `bundle update` behave like
+`bundle update --patch`. That controls the **level** of the updates (prefer
+patch releases over minor/major), not their **scope**: shared and transitive
+dependencies can still move.
+
+`--conservative` controls the scope: only the gems you named are unlocked,
+everything else stays exactly as locked. This plugin automates the scope part
+only.
+
+The two compose. The hook inspects `ARGV`, not Bundler's configuration, so
+`BUNDLE_PREFER_PATCH` does not suppress the injection: with both in place,
+`bundle update rails` updates only `rails` and prefers a patch release. Passing
+`--patch` explicitly on the command line does suppress it, because then the
+invocation already states its own strategy.
+
+## Limitations
+
+- **`bundle update` with no gems named is not protected.** The plugin steps
+  aside there, so the run behaves like a plain full update. Name the gems you
+  want, or pass `--all` to be explicit about it.
+- **`bundle lock --update` is not covered.** It resolves through a code path
+  that never fires plugin hooks, so the plugin cannot see the invocation, let
+  alone re-execute it. Prefer `bundle update`, and review the `Gemfile.lock`
+  diff by hand when you do reach for
+  [`bundle lock --update`](https://bundler.io/man/bundle-lock.1.html).
+- **`--bundler`, `--source` and `--ruby` are left unprotected**, for the reason
+  described in [Usage](#usage).
+- **Tools that resolve the lockfile without running `bundle update` locally**
+  (Dependabot, Renovate, and similar) are not covered.
+- **A fresh clone is unprotected until `bundle install` has run**, since that is
+  what installs the plugin.
+
+## How it works
+
+[`plugins.rb`](plugins.rb) registers a `before-install-all` hook, which also
+runs for `bundle update`. On that hook,
+[`BundlerConservativeUpdate::Hook`](lib/bundler_conservative_update.rb) inspects
+`ARGV`: it locates the subcommand (the first argument that is not an option,
+skipping the value of options like `--retry 3`), checks that the invocation
+names a gem or a group and carries no explicit strategy, and then re-executes
+`bundle` with `--conservative` inserted right after the subcommand.
+
+The decision tables live in
+[`lib/bundler_conservative_update.rb`](lib/bundler_conservative_update.rb) —
+`SKIP_FLAGS`, `SKIP_FLAG_PREFIXES`, `VALUE_FLAGS` and `UPDATE_VALUE_FLAGS`. That
+is the one place to touch when a flag needs to be added.
+
+No environment marker is involved. Recursion stops on its own because the
+re-executed command carries `--conservative` in its own `ARGV`, and that flag is
+one of the reasons the hook declines to inject.
+
+## Development
+
+```console
+bundle install
+bundle exec rake test
+```
+
+The suite includes an integration test that installs the plugin into a
+throwaway project and runs a real `bundle update` against it. To run only the
+unit tests, or a single file:
+
+```console
+SKIP_INTEGRATION=1 bundle exec rake test
+bundle exec ruby -Itest test/hook_test.rb
+```
+
+[CI](.github/workflows/ci.yml) runs the full suite on Ruby 3.0 through 3.4.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+[github.com/bukhr/bundler-conservative-update](https://github.com/bukhr/bundler-conservative-update/issues).
+Please include the Bundler version and the exact `bundle update` invocation in
+bug reports, and make sure `bundle exec rake test` passes on pull requests.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](LICENSE.txt).

data/lib/bundler_conservative_update/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BundlerConservativeUpdate
+  VERSION = "1.0.0"
+end

data/lib/bundler_conservative_update.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "bundler_conservative_update/version"
+
+module BundlerConservativeUpdate
+  # Flags that suppress the injection, matched exactly.
+  #
+  # --conservative is both the "the user already asked for it" case and the
+  # recursion guard: the re-executed command carries the flag, so the hook
+  # declines the second time around.
+  #
+  # --patch, --minor, --major and --strict are explicit update strategies, and
+  # --all is an explicit "update everything" request. In all of them the user
+  # has already stated how far the update may reach.
+  #
+  # --ruby changes what the resolution is about instead of naming gems to
+  # update. Combined with an injected --conservative, Bundler's conservative
+  # branch finds no explicit gem unlocks and falls back to unlocking every
+  # direct dependency, which is the exact outcome this plugin prevents.
+  SKIP_FLAGS = %w[--conservative --patch --minor --major --strict --all --ruby].freeze
+
+  # Flags suppressed by prefix, so `--source foo` and `--source=foo` are both
+  # covered. Same reasoning as --ruby: with an injected --conservative they
+  # would unlock all direct dependencies.
+  SKIP_FLAG_PREFIXES = %w[--bundler --source].freeze
+
+  # Global options that take a separate value argument. That value must not be
+  # mistaken for the subcommand, as in the `3` of `--retry 3`.
+  VALUE_FLAGS = %w[--retry -r].freeze
+
+  # Options of `bundle update` that take a separate value argument. That value
+  # must not be mistaken for a gem name, as in the `4` of `--jobs 4`.
+  UPDATE_VALUE_FLAGS = %w[--gemfile --jobs -j --cooldown --retry -r].freeze
+
+  # Escape hatch: set to "1" or "true" to run a genuinely unrestricted
+  # `bundle update` when transitive updates are intended.
+  DISABLE_ENV = "BUNDLER_CONSERVATIVE_UPDATE_DISABLE"
+
+  # Decides whether a `bundle update` invocation should be re-executed with
+  # --conservative. Instantiated with injected argv and env so it can be tested
+  # without a real Bundler run.
+  class Hook
+    def initialize(argv:, env:)
+      @argv = argv
+      @env  = env
+    end
+
+    # True when the current command is a `bundle update` that names a scope to
+    # update and has not already stated its own update strategy.
+    def should_inject?
+      index = update_index
+
+      return false if index.nil?
+      return false unless @argv[index] == "update"
+
+      args = @argv[(index + 1)..] || []
+
+      return false if skip_flag?(args)
+      return false unless scope?(args)
+      return false if disabled?
+
+      true
+    end
+
+    # The original argv with --conservative inserted right after the
+    # subcommand, leaving the receiver's argv untouched.
+    def conservative_argv
+      new_argv = @argv.dup
+      new_argv.insert(update_index + 1, "--conservative")
+      new_argv
+    end
+
+    private
+
+    # Index of the subcommand: the first argument that is not an option,
+    # skipping the value of the global options that take one.
+    def update_index
+      index = 0
+
+      while index < @argv.length
+        arg = @argv[index]
+
+        if VALUE_FLAGS.include?(arg)
+          index += 2
+          next
+        end
+
+        return index unless arg.start_with?("-")
+
+        index += 1
+      end
+
+      nil
+    end
+
+    # True when the invocation names something to update: gems, or a group
+    # whose direct dependencies Bundler expands into the gem list.
+    #
+    # A bare `bundle update` names nothing. Bundler treats that as a full
+    # update and, with a --conservative that carries no explicit unlocks,
+    # falls back to unlocking every direct dependency of the Gemfile. The
+    # injection would neither restrict the resolution nor match the message the
+    # plugin prints, so the invocation is left alone, same as --all.
+    def scope?(args)
+      gem_names?(args) || group_flag?(args)
+    end
+
+    def gem_names?(args)
+      index = 0
+
+      while index < args.length
+        arg = args[index]
+
+        if UPDATE_VALUE_FLAGS.include?(arg)
+          index += 2
+          next
+        end
+
+        return true unless arg.start_with?("-")
+
+        index += 1
+      end
+
+      false
+    end
+
+    # --group is matched by prefix so `--group foo` and `--group=foo` are both
+    # covered, plus the -g alias.
+    def group_flag?(args)
+      args.any? { |arg| arg == "-g" || arg.start_with?("--group") }
+    end
+
+    def skip_flag?(args)
+      args.any? do |arg|
+        SKIP_FLAGS.include?(arg) || SKIP_FLAG_PREFIXES.any? { |prefix| arg.start_with?(prefix) }
+      end
+    end
+
+    def disabled?
+      %w[1 true].include?(@env[DISABLE_ENV].to_s.downcase)
+    end
+  end
+end

data/plugins.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Bundler plugin entrypoint. When a `bundle update` without an explicit update
+# strategy is detected, the process is re-executed with --conservative so only
+# the requested gems are updated and transitive dependencies stay locked.
+
+require "bundler_conservative_update"
+
+Bundler::Plugin.add_hook("before-install-all") do |_dependencies|
+  hook = BundlerConservativeUpdate::Hook.new(argv: ARGV, env: ENV)
+
+  next unless hook.should_inject?
+
+  spec = Gem.loaded_specs["bundler"]
+
+  # Without a loaded bundler spec there is no reliable path to re-execute, so
+  # the plugin steps aside and lets the plain update run.
+  next if spec.nil?
+
+  # CLI::Update raises the ui level to warn before this hook runs, so info
+  # messages are invisible under --quiet. The headline goes through warn.
+  Bundler.ui.warn("bundler-conservative-update: re-running with --conservative (only requested gems are updated; set BUNDLER_CONSERVATIVE_UPDATE_DISABLE=1 to opt out)")
+  Bundler.ui.info("  Pass --patch, --minor, --major or --all to choose a different update strategy.")
+
+  Kernel.exec(Gem.ruby, spec.bin_file("bundle"), *hook.conservative_argv)
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: bundler-conservative-update
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Javier Omar Pacheco Moreno
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Re-executes `bundle update` with --conservative, so only the gems you
+  name are updated and transitive dependencies stay locked. Explicit strategies (--patch,
+  --minor, --major, --strict), explicit scopes (--all, --source, --bundler, --ruby)
+  and an opt-out are respected.
+email:
+- contacto@buk.cl
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/bundler_conservative_update.rb
+- lib/bundler_conservative_update/version.rb
+- plugins.rb
+homepage: https://github.com/bukhr/bundler-conservative-update
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/bukhr/bundler-conservative-update
+  documentation_uri: https://github.com/bukhr/bundler-conservative-update/blob/main/README.md
+  changelog_uri: https://github.com/bukhr/bundler-conservative-update/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/bukhr/bundler-conservative-update/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: A Bundler plugin that makes `bundle update` conservative by default
+test_files: []