keela 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ac5a23ccbc726eeea66f99e4a6d9cb109360b987daa26e54c43c6d566c448b
-  data.tar.gz: 5c6b44f161613c7dea1aae79490918ce8233572345863febcf34a9417710bf60
+  metadata.gz: b149f85c049e9f0a669ccdef6c9f70f4bcd627d9bec77a543303fae76592cfde
+  data.tar.gz: 3ddae5519560492fbd7fc223065047f787f08bf9c8e99da35efdcbfec0e8e1c7
 SHA512:
-  metadata.gz: 69de532e979e8bb052281e2fc58f2c4c6b9039f6a157b88139badff12c4f48abc0df134c817a44f6a6b1dcad131c2fe86c7a667fd51e36d1314184d5444b620d
-  data.tar.gz: fc86b2efb01f42db61d20f2a65d029082802a09c480bc6aeda5a6739f4b13c4ebfbb5d061f98520bb0248d10d15b9f4237bd18b8a5a0925b384553915d5f6ed4
+  metadata.gz: c02762a44f0cab25a0c3711001bcc1891cd016c489318b55c837b4a6be87973551c7f073a29b3ef97691fadf5e6d5c2b040b873f3b2a37a0f1c58bdcf6fc78d7
+  data.tar.gz: 529a21fb0e9e8c1e603f48b6f3565a6b8f85c81a939a7120301476c444ce0478d2aac842eaa2f4689afc80803847f6f1f577e8010842f3517c8a4b20fa6fc8d6

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-30
+
+### Added
+
+- **Stale exclusions are now reported during a normal run, not just under `--test-exclusions`.** An entry in the excluded YAML whose definition no longer exists (removed, renamed, or its file deleted) was previously only caught by the separate `--test-exclusions` command, so the exclusions file silently rotted. A normal run now flags these inline, elevated to the same behavior as newly unused findings: in baseline mode it fails the run (exit 1), and structured output (`--format json|toon`) carries a `stale_exclusions` section and a `stale_total` summary count. Detection is scoped to the current strategy's section; legacy flat-format entries are skipped to avoid cross-strategy false positives ([#103](https://github.com/kerrizor/keela/issues/103))
+- **New `--normalize-exclusions` flag rewrites the exclusions file in sorted, normalized order.** An explicit write mode (modeled on `--update-baseline`) that deep-sorts the excluded YAML: strategy keys, then file keys within each strategy, then the `name: reason` entries by name. It is reorder-only and non-destructive, it never prunes stale entries, and it preserves every reason verbatim (reasons containing colons stay quoted). Both the strategy-aware and legacy flat formats are handled, output is idempotent, and the file is rewritten with a fixed header (freeform comments are not preserved) ([#93](https://github.com/kerrizor/keela/issues/93))
+
+### Changed
+
+- Relaxed the `parallel` dependency from `~> 1.20` to `>= 1.20, < 3`, so keela no longer forces a downgrade in projects already on parallel 2.x, while still supporting 1.x ([#101](https://github.com/kerrizor/keela/pull/101))
+
+### Fixed
+
+- **`has_scope :name` is no longer swallowed as a false positive by the `scopes` strategy.** The usage regex excluded any line ending in `scope :` to skip the `scope :name` definition, but `has_scope :name` (common in Rails controllers and ActiveAdmin) also ends in `scope :`, so real usages were rejected and the scope was wrongly reported unused. The lookbehind now requires a whitespace character before `scope`, so an indented definition is still excluded while `has_scope` (preceded by `_`) counts as usage ([#100](https://github.com/kerrizor/keela/issues/100))
+- **A method named only in a comment is no longer counted as used.** Usage detection matched its regex against the whole source, comments included, so a method whose name appeared in a comment was treated as called and genuinely dead code was never flagged. Whole-line Ruby comments (`.rb`, `.rake`, `.builder`) are now dropped from the usage corpus before matching. HAML is left alone (a leading `#` there is an element id), and `#{}` interpolation and trailing comments are kept, since telling a real `#` from one inside a string or regexp needs a tokenizer ([#104](https://github.com/kerrizor/keela/pull/104))
+- Run every selected strategy in baseline mode even when an earlier strategy fails, so text and structured reports include all unused code findings ([#102](https://github.com/kerrizor/keela/pull/102)).
+- **Lazy i18n lookups (`t(".key")`) in mailers, controllers, and `.text.` mailer templates are no longer reported as false-positive unused keys.** The `i18n_keys` strategy only expanded lazy lookups inside `.html.` view templates, so a lazy key used in a mailer/controller Ruby method or a `.text.erb` template was flagged unused. The view-path matcher now also covers `.text.` templates, and a pragmatic line scan of `app/mailers` and `app/controllers` (plus `ee/` variants) resolves each lazy `t(".x")` against its enclosing class and method scope, keeping `_mailer` for mailers and dropping `_controller` for controllers ([#73](https://github.com/kerrizor/keela/issues/73))
+- **Multi-line `delegate` declarations now detect every delegated method, not just the one on the first line.** The `delegations` strategy parsed files line by line, so a `delegate` wrapped across several lines only matched the methods on the opening line; the continuation lines did not match `delegate` and the opening line had no `to:` for target/prefix detection. The strategy now joins each `delegate` statement, across continuation lines while a line ends in a comma (after a trailing comment is stripped), into one logical statement before extracting, so target, `prefix:`, and every method resolve correctly. Single-line delegates and comment skipping are preserved ([#52](https://github.com/kerrizor/keela/issues/52))
+
 ## [0.5.1] - 2026-10-06
 
 ### Changed

data/README.md

@@ -63,6 +63,7 @@ If a `.keela_baseline.yml` file exists, Keela compares the current scan against
 | No changes from baseline | ✅ Pass (silent, exit 0) |
 | NEW unused code detected | ❌ Fail (shows new items) |
 | Code REMOVED from baseline | ❌ Fail (prompts to update baseline) |
+| STALE exclusion (its definition is gone) | ❌ Fail (shows stale entries to remove) |
 
 This lets you gradually pay down tech debt while preventing new dead code from sneaking in.
 
@@ -178,6 +179,9 @@ keela --source-location
 # Validate exclusion file entries (find stale exclusions)
 keela --test-exclusions
 
+# Rewrite the exclusion file in sorted, normalized order
+keela --normalize-exclusions
+
 # Show version
 keela --version
 ```
@@ -193,8 +197,8 @@ Keela detects several types of unused code:
 | **constants** | Unused constants | `UNUSED_CONSTANT = 'value'` |
 | **delegations** | Unused delegate declarations | `delegate :unused, to: :target` |
 | **attributes** | Unused attr_* declarations | `attr_accessor :unused_attr` |
-| **i18n_keys** | Unused translation keys | `en.users.unused_key` in locale YAML |
-| **partials** | Unused Rails view partials | `app/views/users/_unused.html.erb` |
+| **i18n_keys** _(beta)_ | Unused translation keys | `en.users.unused_key` in locale YAML |
+| **partials** _(beta)_ | Unused Rails view partials | `app/views/users/_unused.html.erb` |
 
 Run all strategies (default) or target specific ones with `--type`.
 
@@ -508,6 +512,18 @@ Or configure in `keela.yml`:
 excluded_path: ".keela/excluded.yml"
 ```
 
+### Normalizing the Exclusion File
+
+As the exclusion file grows, entries tend to land in whatever order they were added, which makes diffs noisy. Rewrite it in a sorted, canonical order with:
+
+```bash
+keela --normalize-exclusions
+```
+
+This sorts the strategy sections, the files within each section, and the entries within each file, then rewrites the file with a fixed header. It is reorder-only: no entry is removed, and every `name: reason` pair is preserved (use `--test-exclusions` to find stale entries). Running it twice produces identical output.
+
+Freeform comments are not preserved: the rewrite regenerates a fixed header, so any hand-written comments in the file are dropped.
+
 ## Ruby API
 
 ```ruby

data/exe/keela

@@ -94,6 +94,10 @@ OptionParser.new do |opts|
     options[:test_exclusions] = true
   end
 
+  opts.on("--normalize-exclusions", "Rewrite the exclusions file in sorted, normalized order") do
+    options[:normalize_exclusions] = true
+  end
+
   opts.on("-h", "--help", "Show this help") do
     puts opts
     exit
@@ -135,6 +139,21 @@ if options[:test_exclusions]
   exit(success ? 0 : 1)
 end
 
+# Handle --normalize-exclusions mode
+if options[:normalize_exclusions]
+  excluded_path = Keela.configuration.excluded_path ||
+                  Keela::Scanner::DEFAULT_EXCLUDED_PATHS.find { |p| File.exist?(p) }
+
+  unless excluded_path
+    warn "Error: No exclusion file found. Specify with --excluded PATH"
+    exit 1
+  end
+
+  normalizer = Keela::ExclusionNormalizer.new(excluded_path)
+  success = normalizer.normalize
+  exit(success ? 0 : 1)
+end
+
 STRATEGY_MAP = {
   methods: Keela::Strategies::Methods,
   scopes: Keela::Strategies::Scopes,
@@ -210,6 +229,7 @@ end
 
 success = true
 results = {}
+stale_exclusions = {}
 
 structured_output = Keela::Formatters.structured_format?(options[:format])
 silent_output = structured_output || options[:quiet]
@@ -220,14 +240,16 @@ strategies.each_with_index do |strategy, index|
   end
 
   scanner = Keela::Scanner.new(strategy: strategy, baseline: baseline, source_files: source_files)
-  success &&= scanner.run(
+  strategy_success = scanner.run(
     force_report: options[:force_report],
     update_baseline: options[:update_baseline],
     silent: silent_output
   )
+  success &&= strategy_success
 
   # Collect results for structured output formats
   results[strategy.name] = scanner.unused_collection.transform_values(&:to_a)
+  stale_exclusions[strategy.name] = scanner.stale_exclusions.transform_values(&:to_a)
 
   unless silent_output
     puts if strategies.size > 1 && index < strategies.size - 1
@@ -243,7 +265,7 @@ end
 # Output structured format if requested
 if structured_output
   formatter_class = Keela::Formatters.for(options[:format])
-  formatter = formatter_class.new(results: results, strategies: strategies)
+  formatter = formatter_class.new(results: results, strategies: strategies, stale_exclusions: stale_exclusions)
   puts formatter.format
 end
 

data/lib/keela/exclusion_normalizer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "rainbow"
+
+module Keela
+  # Rewrites an exclusion file in sorted, normalized order.
+  #
+  # Reorder-only and non-destructive: it never prunes stale entries, it only
+  # deep-sorts the existing data and re-dumps it with a fixed header. Freeform
+  # YAML comments are not preserved (Psych drops them on load).
+  #
+  class ExclusionNormalizer
+    STRATEGY_MAP = {
+      methods: Strategies::Methods,
+      scopes: Strategies::Scopes,
+      constants: Strategies::Constants,
+      delegations: Strategies::Delegations,
+      attributes: Strategies::Attributes,
+      i18n_keys: Strategies::I18nKeys
+    }.freeze
+
+    attr_reader :excluded_path
+
+    def initialize(excluded_path)
+      @excluded_path = excluded_path
+    end
+
+    def normalize
+      unless File.exist?(excluded_path)
+        puts Rainbow("Exclusion file not found: #{excluded_path}").red
+        return false
+      end
+
+      data = YAML.load_file(excluded_path, symbolize_names: true) || {}
+
+      sorted = strategy_aware_format?(data) ? deep_sort_strategy_aware(data) : deep_sort_flat(data)
+
+      File.write(excluded_path, serialize(sorted))
+      puts Rainbow("Normalized #{excluded_path}").green.bright
+      true
+    end
+
+    private
+
+    def strategy_aware_format?(data)
+      data.keys.any? { |k| STRATEGY_MAP.key?(k) }
+    end
+
+    def deep_sort_strategy_aware(data)
+      data.sort_by { |key, _| key.to_s }.to_h do |strategy_name, files|
+        [strategy_name.to_s, sort_files(files || {})]
+      end
+    end
+
+    def deep_sort_flat(data)
+      sort_files(data)
+    end
+
+    def sort_files(files)
+      files.sort_by { |key, _| key.to_s }.to_h do |file_path, entries|
+        [file_path.to_s, sort_entries(entries || [])]
+      end
+    end
+
+    # Sorts the name:reason entry array by name, converting the symbolized
+    # key back to a string so the dumped YAML uses string keys.
+    #
+    def sort_entries(entries)
+      entries
+        .map { |entry| { entry.keys.first.to_s => entry.values.first } }
+        .sort_by { |entry| entry.keys.first }
+    end
+
+    def serialize(data)
+      if data.empty? || data.values.all? { |v| v.respond_to?(:empty?) && v.empty? }
+        "#{header}---\n{}\n"
+      else
+        "#{header}#{format_yaml(data)}"
+      end
+    end
+
+    def header
+      <<~HEADER
+        # Excluded items that Keela should not flag as unused.
+        # These are known to be in use (e.g. called via metaprogramming).
+        #
+        # This file is normalized by `keela --normalize-exclusions`.
+        # Freeform comments are not preserved when it is rewritten.
+        #
+      HEADER
+    end
+
+    def format_yaml(hash)
+      indent_yaml_list_items(hash.to_yaml)
+    end
+
+    # Indents YAML list items that are not already indented, matching the
+    # style Baseline uses for its output.
+    #
+    def indent_yaml_list_items(yaml_string)
+      yaml_string.gsub(/\n-(\s+\S)/, "\n  -\\1")
+    end
+  end
+end

data/lib/keela/formatters/base.rb

@@ -3,11 +3,12 @@
 module Keela
   module Formatters
     class Base
-      attr_reader :results, :strategies
+      attr_reader :results, :strategies, :stale_exclusions
 
-      def initialize(results:, strategies:)
+      def initialize(results:, strategies:, stale_exclusions: {})
         @results = results
         @strategies = strategies
+        @stale_exclusions = stale_exclusions
       end
 
       def format
@@ -28,6 +29,14 @@ module Keela
       def non_empty_results
         results.reject { |_, v| v.empty? }
       end
+
+      def non_empty_stale_exclusions
+        stale_exclusions.reject { |_, v| v.empty? }
+      end
+
+      def stale_total
+        stale_exclusions.values.flat_map(&:values).flatten.size
+      end
     end
   end
 end

data/lib/keela/formatters/json.rb

@@ -9,9 +9,11 @@ module Keela
         output = {
           strategies: strategies.map(&:name),
           unused: non_empty_results,
+          stale_exclusions: non_empty_stale_exclusions,
           summary: {
             total: total_count,
-            by_strategy: by_strategy_counts
+            by_strategy: by_strategy_counts,
+            stale_total: stale_total
           }
         }
 

data/lib/keela/formatters/toon.rb

@@ -9,9 +9,11 @@ module Keela
         output = {
           "strategies" => strategies.map(&:name),
           "unused" => non_empty_results.transform_keys(&:to_s),
+          "stale_exclusions" => non_empty_stale_exclusions.transform_keys(&:to_s),
           "summary" => {
             "total" => total_count,
-            "by_strategy" => by_strategy_counts.transform_keys(&:to_s)
+            "by_strategy" => by_strategy_counts.transform_keys(&:to_s),
+            "stale_total" => stale_total
           }
         }
 

data/lib/keela/reporter.rb

@@ -36,6 +36,20 @@ module Keela
       print_removed(removed, baseline_path) unless removed.empty?
     end
 
+    def print_stale_exclusions(stale, excluded_path)
+      return if stale.empty?
+
+      count = stale.values.flatten.size
+      message = <<~MESSAGE
+        We have detected #{count} stale #{strategy_name} exclusion(s).
+
+        Their definitions no longer exist; remove them from #{excluded_path}.
+      MESSAGE
+
+      puts Rainbow(message).red.bright
+      puts Rainbow(format_yaml(stale)).red.bright
+    end
+
     def format_report(collection, source_locations = {})
       if source_locations.empty?
         format_yaml(collection)

data/lib/keela/scanner.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require "parallel"
+require "set"
 require "yaml"
 
 module Keela
   class Scanner
-    attr_reader :strategy, :configuration, :baseline, :source_files, :unused_collection, :source_locations, :new_unused, :removed
+    attr_reader :strategy, :configuration, :baseline, :source_files, :unused_collection, :source_locations, :new_unused, :removed, :stale_exclusions
 
     DEFAULT_EXCLUDED_PATHS = [".keela/excluded.yml", "keela_excluded.yml"].freeze
     DEFAULT_BASELINE_PATHS = [".keela/baseline.yml", "keela_baseline.yml"].freeze
@@ -51,6 +52,7 @@ module Keela
       @source_locations = {}  # { "file:name" => line_number }
       @new_unused = []
       @removed = []
+      @stale_exclusions = Hash.new { |hash, key| hash[key] = [] }
     end
 
     def run(force_report: false, update_baseline: false, silent: false)
@@ -71,7 +73,10 @@ module Keela
 
       if report_mode
         elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
-        reporter.print_full_report(unused_collection, elapsed, source_locations: source_locations) unless silent
+        unless silent
+          reporter.print_full_report(unused_collection, elapsed, source_locations: source_locations)
+          reporter.print_stale_exclusions(stale_exclusions, resolve_excluded_path) unless stale_exclusions.empty?
+        end
         if update_baseline
           baseline.set(strategy.name, unused_collection)
           # Note: caller is responsible for calling baseline.save after all strategies run
@@ -91,7 +96,9 @@ module Keela
         )
       end
 
-      new_unused.empty? && removed.empty?
+      reporter.print_stale_exclusions(stale_exclusions, resolve_excluded_path) unless silent || stale_exclusions.empty?
+
+      new_unused.empty? && removed.empty? && stale_exclusions.empty?
     end
 
     def file_globs
@@ -181,18 +188,37 @@ module Keela
       # Support both formats:
       # 1. Strategy-aware (new): { methods: { "file.rb": [{ name: "reason" }] } }
       # 2. Flat (legacy): { "file.rb": [{ name: "reason" }] }
-      excluded = if all_excluded.key?(strategy.name.to_sym)
+      strategy_aware = all_excluded.key?(strategy.name.to_sym)
+      excluded = if strategy_aware
                    all_excluded[strategy.name.to_sym] || {}
                  else
                    all_excluded # Legacy flat format
                  end
 
+      # Stale detection is only safe for the current strategy's section. A legacy
+      # flat entry may belong to another strategy, and keela runs one strategy per
+      # Scanner, so flagging it here would be a false positive. Skip flat format.
+      #
+      detect_stale_exclusions(excluded, definitions) if strategy_aware
+
       definitions.reject do |h|
         excluded_for_file = excluded[h[:file].to_sym]
         excluded_for_file&.flat_map(&:keys)&.include?(h[:name].to_sym)
       end
     end
 
+    def detect_stale_exclusions(excluded, definitions)
+      present = definitions.map { |h| [h[:file].to_sym, h[:name].to_sym] }.to_set
+
+      excluded.each do |file, entries|
+        Array(entries).flat_map(&:keys).each do |name|
+          next if present.include?([file, name])
+
+          @stale_exclusions[file.to_s] << name.to_s
+        end
+      end
+    end
+
     def resolve_excluded_path
       return configuration.excluded_path if configuration.excluded_path && File.exist?(configuration.excluded_path)
 

data/lib/keela/source.rb

@@ -14,6 +14,11 @@ module Keela
     # control characters the range ends in.
     ASCII_RANGE = [0x00, 0x7F].map { |code_point| code_point.chr(Encoding::UTF_8) }.join("-").freeze
 
+    # Extensions whose "#" begins a line comment. HAML is excluded on purpose:
+    # there "#id" is an element id, not a comment.
+    #
+    RUBY_EXTENSIONS = %w[.rb .rake .builder].freeze
+
     attr_reader :text
 
     def initialize(text)
@@ -29,8 +34,23 @@ module Keela
     # no single file (issue #83). Empty files contribute nothing.
     #
     def self.from_source_files(source_files)
-      new(source_files.values.map { |lines| terminate(lines.join) }.join)
+      new(source_files.map { |filename, lines| terminate(strip_comments(filename, lines).join) }.join)
+    end
+
+    # Drop whole-line Ruby comments from the usage corpus.
+    #
+    # A method name mentioned in a comment is not a call, but the usage regex
+    # matches it anyway and would hide genuinely dead code. Only whole-line
+    # comments are dropped: telling a real "#" from one inside a string, a
+    # regexp, or "#{" interpolation needs a tokenizer, not worth it for the
+    # trailing-comment case.
+    #
+    def self.strip_comments(filename, lines)
+      return lines unless RUBY_EXTENSIONS.include?(File.extname(filename))
+
+      lines.reject { |line| line.match?(/\A\s*#(?!\{)/) }
     end
+    private_class_method :strip_comments
 
     def self.terminate(text)
       return text if text.empty? || text.end_with?("\n")

data/lib/keela/strategies/delegations.rb

@@ -48,6 +48,62 @@ module Keela
         methods.length == 1 ? methods.first : methods
       end
 
+      # Own extraction for delegation files so multi-line delegate statements
+      # are detected in full. The scanner's default line-by-line path sees only
+      # the first line of a wrapped delegate, missing every continuation method.
+      # We join each statement into one logical line, then reuse
+      # #extract_definition on the result so target/prefix detection is unchanged.
+      #
+      # Because returning non-nil makes the scanner skip its default path, this
+      # must also replicate that path's comment-skipping and its line-gating on
+      # configuration.source_location.
+      #
+      def extract_definitions_from_file(filepath, lines)
+        track_lines = Keela.configuration.source_location
+        definitions = []
+        index = 0
+
+        while index < lines.length
+          line = lines[index]
+
+          if skip_comments? && line.strip.start_with?("#")
+            index += 1
+            next
+          end
+
+          unless line =~ /^\s*delegate\s+/
+            index += 1
+            next
+          end
+
+          start_index = index
+          statement = strip_comment(line)
+
+          # A delegate statement continues onto the next line while the current
+          # line, ignoring a trailing comment and trailing whitespace, ends in a
+          # comma. It stops at the first line that does not (the options line).
+          # Strip inline comments as we join so #extract_definition sees the same
+          # clean text the scanner's default (comment-skipping) path would.
+          #
+          while continuation?(lines[index])
+            index += 1
+            break if index >= lines.length
+
+            statement += strip_comment(lines[index])
+          end
+
+          index += 1
+
+          Array(extract_definition(statement)).compact.each do |name|
+            definition = { name: name, file: filepath }
+            definition[:line] = start_index + 1 if track_lines
+            definitions << definition
+          end
+        end
+
+        definitions
+      end
+
       def usage_regex(name)
         # Match usage of the delegated method, but not the delegate declaration
         # Uses negative lookbehind to avoid matching:
@@ -85,6 +141,25 @@ module Keela
 
       private
 
+      # Whether +line+ hands off to a continuation line: true when it ends in a
+      # comma after a trailing comment and whitespace are stripped. A `#` inside
+      # a delegate statement can only start a comment, since method symbols
+      # cannot contain one, so dropping from the first `#` is safe here.
+      #
+      def continuation?(line)
+        return false unless line
+
+        strip_comment(line).rstrip.end_with?(",")
+      end
+
+      # Drop a trailing line comment, preserving the newline. A `#` inside a
+      # delegate statement can only start a comment, since method symbols cannot
+      # contain one, so dropping from the first `#` is safe here.
+      #
+      def strip_comment(line)
+        line.sub(/#[^\n]*/, "")
+      end
+
       def folded_usage_regex(name)
         /(?<!:)(?<!delegate\s)(?<![a-z_])#{Regexp.quote(name.downcase(:fold))}(?!\w)/
       end

data/lib/keela/strategies/i18n_keys.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "yaml"
+require "set"
 
 module Keela
   module Strategies
@@ -21,9 +22,17 @@ module Keela
     # Lazy lookup is supported: t('.title') in app/views/users/show.html.erb
     # resolves to 'users.show.title'.
     #
+    # Lazy lookup in mailer/controller Ruby methods is also supported, e.g.
+    # t('.greeting') in UserMailer#welcome resolves to 'user_mailer.welcome.greeting',
+    # and t('.notice') in UsersController#create resolves to 'users.create.notice'.
+    #
     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
+      VIEW_PATH_REGEX = %r{(?:ee/)?app/views/(.+)\.(?:html|text)\.(?:erb|haml|slim)$}.freeze
+      RUBY_SCOPE_PATH_REGEX = %r{(?:ee/)?app/(?:mailers|controllers)/.+\.rb$}.freeze
+      CLASS_DEF_REGEX = /^\s*class\s+([A-Z][\w:]*)/.freeze
+      MODULE_DEF_REGEX = /^\s*module\s+([A-Z][\w:]*)/.freeze
+      METHOD_DEF_REGEX = /^\s*def\s+(?:self\.)?([a-z_][\w]*[?!=]?)/.freeze
       LAZY_LOOKUP_REGEX = /(?:I18n\.)?t\s*\(\s*['"](\.[^'"]+)['"]/
       def name
         "i18n_keys"
@@ -95,6 +104,7 @@ module Keela
       # "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"
+      # "app/views/user_mailer/welcome.text.erb" -> "user_mailer.welcome"
       def view_path_to_prefix(path)
         return nil unless path =~ VIEW_PATH_REGEX
 
@@ -115,22 +125,21 @@ module Keela
         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
+      # Build a set of expanded lazy lookup keys from view files,
+      # mailers, and controllers. 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
+          if (prefix = view_path_to_prefix(filepath))
+            content = lines.join("\n")
+            extract_lazy_keys(content).each do |lazy_key|
+              # .title -> users.show.title
+              expanded << "#{prefix}#{lazy_key}"
+            end
+          elsif filepath =~ RUBY_SCOPE_PATH_REGEX
+            expand_ruby_lazy_keys(lines).each { |key| expanded << key }
           end
         end
 
@@ -139,6 +148,70 @@ module Keela
 
       private
 
+      # Scan a mailer/controller Ruby file line by line, tracking the current
+      # class scope and method, and expand each lazy t('.x') to its full key.
+      #
+      # This is a pragmatic line scan (no AST) matching keela's regex style.
+      # It tracks the last-seen `def` as the enclosing method and does NOT
+      # attempt precise `end` matching. A lazy call that appears after a method
+      # body but before the next `def` is still attributed to the last method.
+      # This over-association can only mark an EXTRA key as used, never cause a
+      # false "unused" flag, so it is a safe conservative tradeoff. A lazy call
+      # seen before any `def` has no enclosing method and is skipped.
+      #
+      def expand_ruby_lazy_keys(lines)
+        keys = []
+        namespace = []
+        class_scope = nil
+        current_method = nil
+
+        lines.each do |line|
+          if (m = line.match(MODULE_DEF_REGEX))
+            namespace << m[1]
+          elsif (m = line.match(CLASS_DEF_REGEX))
+            class_scope = ruby_class_scope(namespace, m[1])
+            current_method = nil
+          elsif (m = line.match(METHOD_DEF_REGEX))
+            current_method = m[1]
+          end
+
+          next unless class_scope && current_method
+
+          line.scan(LAZY_LOOKUP_REGEX).flatten.each do |lazy_key|
+            # .greeting -> user_mailer.welcome.greeting
+            keys << "#{class_scope}.#{current_method}#{lazy_key}"
+          end
+        end
+
+        keys
+      end
+
+      # Derive the i18n scope for a class in a mailer/controller file.
+      # Combines any enclosing `module` nesting with the class name (which may
+      # itself be compact, e.g. `Admin::UserMailer`), underscores the full path,
+      # converts "/" to ".", and drops a trailing "_controller" for controllers
+      # while keeping "_mailer" for mailers.
+      #
+      #   [], "PaymentOrderMailer"        -> "payment_order_mailer"
+      #   ["Admin"], "UserMailer"         -> "admin.user_mailer"
+      #   [], "Admin::UserMailer"         -> "admin.user_mailer"
+      #   [], "UsersController"           -> "users"
+      #   ["Admin"], "UsersController"    -> "admin.users"
+      #
+      def ruby_class_scope(namespace, class_name)
+        full_path = (namespace + class_name.split("::")).map { |part| underscore(part) }.join("/")
+        full_path = full_path.delete_suffix("_controller") if full_path.end_with?("_controller")
+        full_path.tr("/", ".")
+      end
+
+      # Convert a CamelCase constant segment to snake_case.
+      # "PaymentOrderMailer" -> "payment_order_mailer"
+      def underscore(word)
+        word.gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+      end
+
       # Returns the parent key if this is a pluralization key, nil otherwise
       # "items.count.one" -> "items.count"
       # "users.show.title" -> nil

data/lib/keela/strategies/scopes.rb

@@ -18,7 +18,11 @@ module Keela
       end
 
       def usage_regex(name)
-        /(?<!scope :)(?<!def )#{Regexp.quote(name)}\W/
+        # Whitespace-anchoring the lookbehind distinguishes a `scope :name`
+        # definition (preceded by indentation whitespace) from `has_scope :name`
+        # usage (preceded by `_`), which must count as a real usage.
+        #
+        /(?<!\sscope :)(?<!def )#{Regexp.quote(name)}\W/
       end
 
       def skip_comments?

data/lib/keela/version.rb

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

data/lib/keela.rb

@@ -16,6 +16,7 @@ require_relative "keela/reporter"
 require_relative "keela/baseline"
 require_relative "keela/scanner"
 require_relative "keela/exclusion_validator"
+require_relative "keela/exclusion_normalizer"
 require_relative "keela/formatters"
 
 module Keela

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keela
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Kerri Miller
@@ -13,16 +13,22 @@ dependencies:
   name: parallel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.20'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: rainbow
   requirement: !ruby/object:Gem::Requirement
@@ -81,6 +87,7 @@ files:
 - lib/keela/baseline.rb
 - lib/keela/config_file.rb
 - lib/keela/configuration.rb
+- lib/keela/exclusion_normalizer.rb
 - lib/keela/exclusion_validator.rb
 - lib/keela/formatters.rb
 - lib/keela/formatters/base.rb