keela 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3448ca0297d2fb01cbe430bf8d1686ae28871bfa36666815120241664ed95821
-  data.tar.gz: 05a96216af6eea62b31ee0e6d6ceb8e82326946ff8eecd35f3eeb07637d220d8
+  metadata.gz: 1b1c9fad8b959b91c3af1518da72d36f9f82bd649b4c21a6a0cf261246cbbcdb
+  data.tar.gz: 24c7b946587cb844ae9c08c921ffecacfb8b262404b2c177f0368d803cc52861
 SHA512:
-  metadata.gz: fc7d5f1e2f1844dc9f67d51e96de17b23e3d040ce767b51529d23c1619f96ae86ea1bf82a028e2e09cea4d074fcba001dab20b1a29725f54f71c366b68a2de17
-  data.tar.gz: 177309a39a1fa56d97d6a3693ff674cd94b92cb81e00ea50a6b889823e4d68fd2fdf0601c7d7157e10f48d50f66f940bb92a695808b424d30f4b5ee14bd22623
+  metadata.gz: e0fcd131e331240b852f7d657113aa0e9610aa4a7dd465b78576478c11abdeca5cd4140c9037cbbd378f53e23e4137d6a255eeb8d28950f0f82f6ad0eeabc7fd
+  data.tar.gz: 7d71ea4b1a2c601f0aba8901fbe31f95ba055eb784614213afa386321e096bb2364ecd832b60356f08c8cc42ed2e07e9bdcfc4c3a794fe218931834ac7df7c39

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-08-21
+
+### Fixed
+
+- Constants used as hash keys (`CONST => value`) or in rescue splats (`rescue *ERRORS => e`) are now correctly detected as used ([#63](https://github.com/kerrizor/keela/pull/63))
+- Methods referenced as literal symbols (`:method_name`) are now detected as used, including Rails callbacks, `send(:method)`, `validate :method`, etc. ([#64](https://github.com/kerrizor/keela/issues/64))
+- I18n pluralization keys (`one`, `other`, `zero`, etc.) are now detected as used when the parent key is called with `t('key', count: n)` ([#69](https://github.com/kerrizor/keela/pull/69))
+- I18n lazy lookup (`t('.title')` in views) now correctly resolves to the full key based on the view path ([#17](https://github.com/kerrizor/keela/issues/17))
+
 ## [0.4.0] - 2026-08-14
 
 ### Added

data/README.md

@@ -199,13 +199,67 @@ Run all strategies (default) or target specific ones with `--type`.
 
 The `i18n_keys` strategy is **beta** and may produce false positives. It cannot detect:
 
-- **Lazy lookup** - `t('.title')` in views resolves based on the view path
 - **Dynamic keys** - `t("users.#{action}.title")` with interpolated segments
 - **Model translations** - `User.human_attribute_name(:email)` and `User.model_name.human`
-- **Pluralization siblings** - If `one:` is used, `other:` may appear unused
+
+The following patterns ARE now supported:
+- **Lazy lookup** - `t('.title')` in views resolves based on the view path
+- **Pluralization siblings** - `t('key', count: n)` marks all plural forms as used
 
 Review results carefully and use the exclusion file for known false positives.
 
+## Limitations
+
+Keela uses static analysis — it reads your code without executing it. This means some patterns are **fundamentally undetectable**.
+
+### What Keela CAN Detect
+
+Keela detects **literal references** to methods, constants, etc.:
+
+```ruby
+# ✅ Direct calls
+user.save
+User.find(1)
+
+# ✅ Literal symbol references
+before_save :ensure_token
+validate :check_valid
+send(:process_data)
+respond_to?(:optional_method)
+```
+
+### What Keela CANNOT Detect
+
+**Dynamic dispatch** with interpolation or variables cannot be analyzed statically:
+
+```ruby
+# ❌ Interpolated symbols — what method does this call?
+public_send(:"add_#{role}", user)
+
+# ❌ Variable method names — could be anything
+send(method_name)
+
+# ❌ Computed method names
+define_method(compute_name) { }
+```
+
+To detect these, Keela would need to trace all possible runtime values — essentially becoming a Ruby interpreter. This is not a bug; it's a fundamental limitation of static analysis.
+
+### Handling False Positives
+
+When Keela reports a method as unused but it's actually called dynamically, add it to your exclusion file:
+
+```yaml
+# .keela/excluded.yml
+methods:
+  app/models/project_team.rb:
+    - add_owner: "Called via public_send(:\"add_\#{role}\")"
+    - add_maintainer: "Called via public_send(:\"add_\#{role}\")"
+    - add_developer: "Called via public_send(:\"add_\#{role}\")"
+```
+
+**Tip:** If you see `send`, `public_send`, or `define_method` with interpolation in a file, expect some false positives for methods in that file.
+
 ## Configuration File
 
 Create a `keela.yml` or `.keela.yml` in your project root:

data/lib/keela/scanner.rb

@@ -210,9 +210,16 @@ module Keela
     def find_unused(definitions, show_progress: false)
       source_code = source_files.values.flatten.join
 
+      # Get additional used names from strategy-specific detection
+      # (e.g., I18n lazy lookup)
+      additional_used = strategy.additional_used_names(source_files)
+
       progress_label = show_progress ? "Checking #{strategy.name}" : nil
 
       unused = Parallel.flat_map(definitions, progress: progress_label) do |definition|
+        # Check if marked as used by additional detection
+        next [] if additional_used.include?(definition[:name])
+
         regex = strategy.usage_regex(definition[:name])
         regex.match?(source_code) ? [] : definition
       end

data/lib/keela/strategies/constants.rb

@@ -41,8 +41,12 @@ module Keela
         # uppercase letters/digits/underscores (partial match)
         # Uses negative lookahead to avoid:
         #   - partial matches (followed by uppercase letters/digits/underscores)
-        #   - definitions (followed by optional whitespace then =, but not ==)
-        /(?<![A-Z0-9_])#{Regexp.quote(name)}(?![A-Z0-9_])(?!\s*=(?!=))/
+        #   - definitions (followed by optional whitespace then =, but not == or =>)
+        #
+        # The pattern (?!\s*=(?![=>])) means:
+        #   - Don't match if followed by optional whitespace, then =
+        #   - UNLESS that = is followed by = (comparison) or > (hash rocket)
+        /(?<![A-Z0-9_])#{Regexp.quote(name)}(?![A-Z0-9_])(?!\s*=(?![=>]))/
       end
 
       def skip_comments?

data/lib/keela/strategies/i18n_keys.rb

@@ -15,9 +15,16 @@ module Keela
     #   - t(:key)
     #   - .human_attribute_name(:attr)
     #
-    # Note: Lazy lookup (t('.title') in views) is not yet supported.
+    # Pluralization keys (zero, one, two, few, many, other) are grouped:
+    # if t("items.count", count: n) is called, all siblings are considered used.
+    #
+    # Lazy lookup is supported: t('.title') in app/views/users/show.html.erb
+    # resolves to 'users.show.title'.
     #
     class I18nKeys < Strategy
+      PLURAL_SUFFIXES = %w[zero one two few many other].freeze
+      VIEW_PATH_REGEX = %r{(?:ee/)?app/views/(.+)\.html\.(?:erb|haml|slim)$}.freeze
+      LAZY_LOOKUP_REGEX = /(?:I18n\.)?t\s*\(\s*['"](\.[^'"]+)['"]/
       def name
         "i18n_keys"
       end
@@ -32,10 +39,19 @@ module Keela
         return [] unless File.exist?(filepath)
 
         content = YAML.load_file(filepath, permitted_classes: [Symbol]) || {}
-        flatten_keys(content).map do |key|
+        keys = flatten_keys(content).map do |key|
           # Remove the locale prefix (e.g., "en.users.show" -> "users.show")
-          key_without_locale = key.sub(/^[a-z]{2}(-[A-Z]{2})?\./, "")
-          { name: key_without_locale, file: filepath }
+          key.sub(/^[a-z]{2}(-[A-Z]{2})?\./, "")
+        end
+
+        # For pluralization keys, also add the parent key so that
+        # t("items.count", count: n) marks all siblings as used
+        parent_keys = keys.filter_map do |key|
+          parent_key_for_pluralization(key)
+        end.uniq
+
+        (keys + parent_keys).uniq.map do |key|
+          { name: key, file: filepath }
         end
       rescue Psych::SyntaxError => e
         warn "Warning: Could not parse #{filepath}: #{e.message}"
@@ -55,20 +71,86 @@ module Keela
         #   t('users.show.title')
         #   t(:users_show_title) - symbol form (underscored)
         #
-        # Also match partial keys for lazy lookup support:
-        #   t(".title") in a view could match "users.show.title"
+        # For pluralization keys, also match the parent key:
+        #   t("items.count", count: n) should match items.count.one, items.count.other, etc.
         quoted_name = Regexp.quote(name)
 
-        # Build pattern that matches the key in quotes or as a symbol
-        /(?:I18n\.)?t\s*\(\s*["':]+#{quoted_name}["']?\s*[,)]/
+        # Check if this is a pluralization key and build alternate pattern
+        parent_key = parent_key_for_pluralization(name)
+        if parent_key
+          quoted_parent = Regexp.quote(parent_key)
+          # Match either the exact key OR the parent key
+          /(?:I18n\.)?t\s*\(\s*["':]+(?:#{quoted_name}|#{quoted_parent})["']?\s*[,)]/
+        else
+          # Build pattern that matches the key in quotes or as a symbol
+          /(?:I18n\.)?t\s*\(\s*["':]+#{quoted_name}["']?\s*[,)]/
+        end
       end
 
       def skip_comments?
         true
       end
 
+      # Convert a view file path to its I18n prefix
+      # "app/views/users/show.html.erb" -> "users.show"
+      # "app/views/users/_form.html.erb" -> "users.form"
+      # "ee/app/views/users/show.html.erb" -> "users.show"
+      def view_path_to_prefix(path)
+        return nil unless path =~ VIEW_PATH_REGEX
+
+        view_path = Regexp.last_match(1)
+
+        # Split into parts and process
+        parts = view_path.split("/")
+
+        # Handle partials: _form -> form
+        parts[-1] = parts[-1].sub(/^_/, "")
+
+        parts.join(".")
+      end
+
+      # Extract lazy lookup keys from view content
+      # Returns array of keys like [".title", ".description"]
+      def extract_lazy_keys(content)
+        content.scan(LAZY_LOOKUP_REGEX).flatten
+      end
+
+      # Build a set of expanded lazy lookup keys from view files
+      # Called by the scanner to detect usage via lazy lookup
+      def additional_used_names(source_files)
+        expanded = Set.new
+
+        source_files.each do |filepath, lines|
+          prefix = view_path_to_prefix(filepath)
+          next unless prefix
+
+          content = lines.join("\n")
+          lazy_keys = extract_lazy_keys(content)
+
+          lazy_keys.each do |lazy_key|
+            # .title -> users.show.title
+            full_key = "#{prefix}#{lazy_key}"
+            expanded << full_key
+          end
+        end
+
+        expanded
+      end
+
       private
 
+      # Returns the parent key if this is a pluralization key, nil otherwise
+      # "items.count.one" -> "items.count"
+      # "users.show.title" -> nil
+      def parent_key_for_pluralization(key)
+        PLURAL_SUFFIXES.each do |suffix|
+          if key.end_with?(".#{suffix}")
+            return key.sub(/\.#{suffix}$/, "")
+          end
+        end
+        nil
+      end
+
       # Flatten nested hash to dot-notation keys
       # { "en" => { "users" => { "title" => "..." } } }
       # becomes ["en.users.title"]

data/lib/keela/strategies/methods.rb

@@ -24,9 +24,14 @@ module Keela
           # Setter method: match assignment usage
           /(?<!def |def self\.)#{method_name.chomp("=")}\W=*/
         else
-          # Regular method: match calls
-          # Exclude both "def foo" and "def self.foo" definitions
-          /(?<!def |def self\.)#{method_name}\W/
+          # Regular method: match calls and symbol references
+          # Matches:
+          #   - Direct calls: foo(arg), obj.foo
+          #   - Symbol references: :foo, :foo! (callbacks, send, etc.)
+          # Excludes:
+          #   - Definitions: def foo, def self.foo
+          #   - Partial matches: :foobar, before_foo (via word boundary lookbehind)
+          /(?<!def |def self\.)(?<![A-Za-z0-9_]):?#{method_name}(?:\W|$)/
         end
       end
 

data/lib/keela/strategy.rb

@@ -55,6 +55,14 @@ module Keela
       nil
     end
 
+    # Override this method for strategies that need to detect usage through
+    # patterns that can't be expressed as a simple regex (e.g., I18n lazy lookup).
+    # Returns a Set of definition names that are considered "used".
+    # Called with the source_files hash { filepath => [lines] }.
+    def additional_used_names(_source_files)
+      Set.new
+    end
+
     private
 
     def configured_pattern

data/lib/keela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Keela
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keela
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Kerri Miller