Allow Definition#lock to be passed a lockfile:

- Ref #8917
- ### Problem

  In 6a0c03c, we introduced a
  deprecation that would disallow calling `lock("NewGemfile.lock")`.
  The intention was that the lockfile target should be passed when
  constructing a Definition object.

  With this deprecation, it is no longer possible to create a
  Definition from an existing lockfile, make changes to the
  definition, and dump its content into a new lockfile.
  This behaviour is used as public API but also internally with
  the `bundle lock` command (currently broken, a fix will follow up
  thanks to this commit).

  ### Solution

  Remove the deprecation and introduce a new one related to the
  position of the passed arguments. The method's signature is now:

  `lock(preserve_unknown_section = false, target_lock = lockfile)`

Author: Edouard-chin

bundler/lib/bundler/definition.rb

@@ -351,23 +351,24 @@ def groups
       dependencies.flat_map(&:groups).uniq
     end
 
-    def lock(file_or_preserve_unknown_sections = false, preserve_unknown_sections_or_unused = false)
+    def lock(file_or_preserve_unknown_sections = false, file_or_preserve_unknown_sections2 = lockfile)
       if [true, false, nil].include?(file_or_preserve_unknown_sections)
-        target_lockfile = lockfile
+        target_lockfile = file_or_preserve_unknown_sections2
         preserve_unknown_sections = file_or_preserve_unknown_sections
       else
         target_lockfile = file_or_preserve_unknown_sections
-        preserve_unknown_sections = preserve_unknown_sections_or_unused
-
-        suggestion = if target_lockfile == lockfile
-          "To fix this warning, remove it from the `Definition#lock` call."
+        if lockfile == file_or_preserve_unknown_sections2
+          preserve_unknown_sections = false
         else
-          "Instead, instantiate a new definition passing `#{target_lockfile}`, and call `lock` without a file argument on that definition"
+          preserve_unknown_sections = file_or_preserve_unknown_sections2
         end
 
-        msg = "`Definition#lock` was passed a target file argument. #{suggestion}"
+        Bundler::SharedHelpers.major_deprecation 2, <<~MSG
+          The lockfile target needs to be passed as second argument to the `Definition#lock` method.
+          To fix this warning, please modify the caller to:
 
-        Bundler::SharedHelpers.major_deprecation 2, msg
+          `lock(#{preserve_unknown_sections}, "#{file_or_preserve_unknown_sections}")`
+        MSG
       end
 
       write_lock(target_lockfile, preserve_unknown_sections)

bundler/spec/bundler/definition_spec.rb

@@ -38,6 +38,46 @@
         expect(bundled_app_lock).not_to be_file
       end
     end
+    context "method signature" do
+      before { Bundler::Definition.no_lock = true }
+      after { Bundler::Definition.no_lock = false }
+
+      it "does not print a deprecation when method is called with no arguments" do
+        allow(Bundler).to receive(:ui) { double("UI", info: "", debug: "") }
+
+        subject.lock
+      end
+
+      it "does not print a deprecation when +preserve_unknown_section+ is given as 1st arg" do
+        allow(Bundler).to receive(:ui) { double("UI", info: "", debug: "") }
+
+        subject.lock(true)
+      end
+
+      it "prints a deprecation when target lockfile is given as first argument" do
+        expected = <<~MSG
+          [DEPRECATED] The lockfile target needs to be passed as second argument to the `Definition#lock` method.
+          To fix this warning, please modify the caller to:
+
+          `lock(false, "Gemfile.lock")`
+        MSG
+        allow(Bundler).to receive(:ui) { double("UI", info: "", debug: "", warn: expected) }
+
+        subject.lock("Gemfile.lock")
+      end
+
+      it "prints a deprecation when target lockfile is given as 1st arg and unknown section as 2nd" do
+        expected = <<~MSG
+          [DEPRECATED] The lockfile target needs to be passed as second argument to the `Definition#lock` method.
+          To fix this warning, please modify the caller to:
+
+          `lock(true, "Gemfile.lock")`
+        MSG
+        allow(Bundler).to receive(:ui) { double("UI", info: "", debug: "", warn: expected) }
+
+        subject.lock("Gemfile.lock", true)
+      end
+    end
   end
 
   describe "detects changes" do