add module for deprecation handling

.simplecov

@@ -21,6 +21,7 @@ SimpleCov.start do
     "lib/lunchmoney.rb",
     "lib/lunchmoney/api.rb",
     "lib/lunchmoney/configuration.rb",
+    "lib/lunchmoney/deprecate.rb",
     "lib/lunchmoney/errors.rb",
     "lib/lunchmoney/exceptions.rb",
     "lib/lunchmoney/validators.rb",

lib/lunchmoney/api.rb

@@ -3,6 +3,7 @@
 
 require_relative "exceptions"
 require_relative "configuration"
+require_relative "deprecate"
 
 require_relative "calls/base"
 require_relative "objects/object"

lib/lunchmoney/deprecate.rb

@@ -0,0 +1,35 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  module Deprecate
+    cattr_accessor :endpoint_deprecation_warnings, default: true
+
+    sig { params(replacement: T.nilable(String)).void }
+    def deprecate_endpoint(replacement = nil)
+      return unless endpoint_deprecation_warnings
+
+      replacement = if replacement.nil?
+        "There is currently no replacement for this endpoint"
+      else
+        "Please use #{replacement} instead"
+      end
+
+      message = "#{deprecated_endpoint} is deprecated and may be removed from LunchMoney | #{replacement}"
+      Kernel.warn(message)
+    end
+
+    private
+
+    sig { returns(String) }
+    def deprecated_endpoint
+      endpoint_call = Kernel.caller_locations.find { |call| call.to_s.include?("lunchmoney/calls") }
+
+      if endpoint_call.nil?
+        ""
+      else
+        "LunchMoney::Api##{endpoint_call.label}"
+      end
+    end
+  end
+end

test/helpers/deprecation_helper.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module LunchMoney
+  module Calls
+    class DeprecateTestCalls
+      include LunchMoney::Deprecate
+
+      sig { returns(String) }
+      def old_endpoint_no_replacement
+        deprecate_endpoint
+
+        "This is the old endpoint"
+      end
+
+      sig { returns(String) }
+      def old_endpoint_with_replacement
+        deprecate_endpoint("#new_endpoint")
+
+        "This is the old endpoint"
+      end
+    end
+  end
+end

test/lunchmoney/deprecate_test.rb

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "test_helper"
+
+class DeprecateTest < ActiveSupport::TestCase
+  setup do
+    @deprecate_test_klass = T.let(
+      LunchMoney::Calls::DeprecateTestCalls,
+      T.class_of(LunchMoney::Calls::DeprecateTestCalls),
+    )
+  end
+
+  test "deprecate_endpoint does not warn when endpoint_deprecation_warnings is false" do
+    @deprecate_test_klass.any_instance.expects(:endpoint_deprecation_warnings).returns(false)
+
+    Kernel.expects(:warn).never
+
+    @deprecate_test_klass.new.old_endpoint_no_replacement
+  end
+
+  test "deprecate_endpoint warns when endpoint_deprecation_warnings is true" do
+    @deprecate_test_klass.any_instance.expects(:endpoint_deprecation_warnings).returns(true)
+
+    Kernel.expects(:warn).with(regexp_matches(/is deprecated and may be removed from LunchMoney/))
+
+    @deprecate_test_klass.new.old_endpoint_no_replacement
+  end
+
+  test "deprecate_endpoint warns with replacement message when replacement is provided" do
+    @deprecate_test_klass.any_instance.expects(:endpoint_deprecation_warnings).returns(true)
+
+    call_locations = [mock(label: "old_endpoint_with_replacement", to_s: "lunchmoney/calls/deprecate_test_calls.rb:10")]
+    Kernel.expects(:caller_locations).returns(call_locations)
+
+    Kernel.expects(:warn).with(regexp_matches(/old_endpoint_with_replacement is deprecated .+Please use #new_endpoint/))
+
+    @deprecate_test_klass.new.old_endpoint_with_replacement
+  end
+
+  test "deprecate_endpoint warns with no replacement message when replacement is not provided" do
+    @deprecate_test_klass.any_instance.expects(:endpoint_deprecation_warnings).returns(true)
+
+    Kernel.expects(:warn).with(regexp_matches(/There is currently no replacement for this endpoint/))
+
+    @deprecate_test_klass.new.old_endpoint_no_replacement
+  end
+end

test/test_helper.rb

@@ -16,6 +16,9 @@
 require "vcr"
 
 require_relative "helpers/configuration_helper"
+require_relative "helpers/deprecation_helper"
 require_relative "helpers/mocha_typed"
 require_relative "helpers/mock_response_helper"
 require_relative "helpers/vcr_helper"
+
+LunchMoney::Deprecate.endpoint_deprecation_warnings = false