Warn when default cache key format is used with arguments

The default key format ignores method arguments, meaning
different arguments return the same cached value. This adds
a deprecation warning (once per method) when a cached method
is called with arguments but uses the default key format,
guiding users to provide a :key_format proc.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: agrberg

README.md

@@ -135,7 +135,7 @@ Fetching data from GitHub
 
 #### Default
 
-By default, Cacheable will construct a key in the format `[cache_key || class_name, method_name]` without using method arguments.
+By default, Cacheable will construct a key in the format `[cache_key || class_name, method_name]` without using method arguments. If a cached method is called with arguments while using the default key format, Cacheable will emit a warning to stderr since different arguments will return the same cached value. To silence the warning, provide a `:key_format` proc that includes the arguments in the cache key.
 
 If the object responds to `cache_key` its return value will be the first element in the array. `ActiveRecord` provides [`cache_key`](https://api.rubyonrails.org/classes/ActiveRecord/Integration.html#method-i-cache_key) but it can be added to any Ruby object or overwritten. If the object does not respond to it, the name of the class will be used instead. The second element will be the name of the method as a symbol.
 

lib/cacheable/method_generator.rb

@@ -53,8 +53,16 @@ def create_cacheable_methods(original_method_name, opts = {})
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def default_key_format
-      proc do |target, method_name, _method_args, **_kwargs|
-        # By default, we omit the _method_args from the cache key because there is no acceptable default behavior
+      warned = false
+
+      proc do |target, method_name, method_args, **kwargs|
+        if !warned && (!method_args.empty? || !kwargs.empty?)
+          warn "Cacheable WARNING: '#{method_name}' is using the default key format but was called with " \
+               'arguments. Arguments are NOT included in the cache key, so different arguments will return ' \
+               'the same cached value. Provide a :key_format proc to include arguments in the cache key.'
+          warned = true
+        end
+
         class_name = (target.is_a?(Module) ? target.name : target.class.name)
         cache_key = target.respond_to?(:cache_key) ? target.cache_key : class_name
         [cache_key, method_name].compact

spec/cacheable/cacheable_spec.rb

@@ -43,7 +43,7 @@
       arg = 'an argument'
       expect(cacheable_object).to receive(cacheable_method_inner).with(arg)
 
-      cacheable_object.send(cacheable_method, arg)
+      expect { cacheable_object.send(cacheable_method, arg) }.to output.to_stderr
     end
 
     it 'creates a method that can skip the cache' do
@@ -223,9 +223,28 @@
           .to change { described_class.cache_adapter.exist?(key) }.from(false).to(true)
       end
 
-      it 'does not use the arguments to the method to determine the cache key' do
-        args = [1]
-        expect(cacheable_object.cacheable_method_key_format(*args)).to eq([cacheable_method])
+      it 'does not use positional arguments in the cache key and warns' do
+        cache_key = nil
+        expect { cache_key = cacheable_object.cacheable_method_key_format(1) }
+          .to output(/default key format.*arguments are NOT included/i).to_stderr
+        expect(cache_key).to eq([cacheable_method])
+      end
+
+      it 'does not use keyword arguments in the cache key and warns' do
+        cache_key = nil
+        expect { cache_key = cacheable_object.cacheable_method_key_format(foo: 1) }
+          .to output(/default key format.*arguments are NOT included/i).to_stderr
+        expect(cache_key).to eq([cacheable_method])
+      end
+
+      it 'only warns once per method' do
+        expect { cacheable_object.cacheable_method_key_format(1) }
+          .to output(/default key format/i).to_stderr
+        expect { cacheable_object.cacheable_method_key_format(2) }.not_to output.to_stderr
+      end
+
+      it 'does not warn when called without arguments' do
+        expect { cacheable_object.cacheable_method_key_format }.not_to output.to_stderr
       end
 
       it 'uses different keys for different cached values' do
@@ -244,8 +263,10 @@
         expect(cacheable_object).to receive(inner_method).with(arg1).once.and_call_original
         expect(cacheable_object).to receive(inner_method).with(arg2).once.and_call_original
 
-        2.times { expect(cacheable_object.send(cacheable_method, arg1)).to include(arg1) }
-        2.times { expect(cacheable_object.send(another_cacheable_method, arg2)).to include(arg2) }
+        expect do
+          2.times { expect(cacheable_object.send(cacheable_method, arg1)).to include(arg1) }
+          2.times { expect(cacheable_object.send(another_cacheable_method, arg2)).to include(arg2) }
+        end.to output.to_stderr
       end
 
       it 'uses the value of `cache_key` if the method is defined instead of the class' do