keela 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fcf07cf3f0adee173c2dfaef9e79f256f6a6318c5dd843935b6113fede4dea4
-  data.tar.gz: 454fa3bc9a9839dcf7d5f40a6d2fa2160daeb3a2d113d2f372da6ce15f9a49b0
+  metadata.gz: 1b1c9fad8b959b91c3af1518da72d36f9f82bd649b4c21a6a0cf261246cbbcdb
+  data.tar.gz: 24c7b946587cb844ae9c08c921ffecacfb8b262404b2c177f0368d803cc52861
 SHA512:
-  metadata.gz: f9105a9cc47b95443d527772bd1dc44b5578d3b88829ec0144109e1ce82cc03d3414be62de9c8e4f8a7ab308b742e3beea343e6aefd2b4e3184f694847bba711
-  data.tar.gz: b583a1e03b6b460d4393ed687ef8796315c6fc4e8f9e4afde3a4edce26581536ef0b72dbef7215237b97835263b12a52b55879f391d901efe5409007ae407982
+  metadata.gz: e0fcd131e331240b852f7d657113aa0e9610aa4a7dd465b78576478c11abdeca5cd4140c9037cbbd378f53e23e4137d6a255eeb8d28950f0f82f6ad0eeabc7fd
+  data.tar.gz: 7d71ea4b1a2c601f0aba8901fbe31f95ba055eb784614213afa386321e096bb2364ecd832b60356f08c8cc42ed2e07e9bdcfc4c3a794fe218931834ac7df7c39

data/CHANGELOG.md

@@ -7,6 +7,34 @@ 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
+
+- **Verbose mode** via `--verbose` flag to show files being scanned, glob patterns, and configuration for debugging ([#53](https://github.com/kerrizor/keela/pull/53))
+- **Source location** via `--source-location` flag to show line numbers in reports for easier navigation ([#55](https://github.com/kerrizor/keela/pull/55))
+- **Exclusion validation** via `--test-exclusions` flag to find stale entries in exclusion files ([#56](https://github.com/kerrizor/keela/pull/56))
+- **TOON output format** via `--format toon` for token-efficient LLM-friendly output ([#58](https://github.com/kerrizor/keela/pull/58))
+- **Configurable definition paths** per strategy via `strategies.<name>.definition_paths` in config file ([#59](https://github.com/kerrizor/keela/pull/59))
+
+### Changed
+
+- **`--quiet` now suppresses all output**, not just the progress bar. Use exit code for success/failure in scripts. ([#54](https://github.com/kerrizor/keela/pull/54))
+
+### Fixed
+
+- Multi-method delegate declarations now detect all methods, not just the first ([#51](https://github.com/kerrizor/keela/pull/51))
+- Class methods (`def self.foo`) are now correctly detected as unused ([#60](https://github.com/kerrizor/keela/pull/60))
+
 ## [0.3.0] - 2026-08-05
 
 ### Added

data/README.md

@@ -66,6 +66,27 @@ If a `.keela_baseline.yml` file exists, Keela compares the current scan against
 
 This lets you gradually pay down tech debt while preventing new dead code from sneaking in.
 
+The baseline file is organized by strategy:
+
+```yaml
+# .keela_baseline.yml
+methods:
+  app/models/user.rb:
+    - legacy_method
+    - old_callback
+  app/helpers/application_helper.rb:
+    - unused_helper
+scopes:
+  app/models/user.rb:
+    - inactive
+    - archived
+constants:
+  app/models/user.rb:
+    - OLD_STATUS
+```
+
+**Note:** The baseline file only stores names, not line numbers. This prevents false positives when code moves within a file.
+
 ### Report Mode
 
 If no baseline exists (or you use `--report`), Keela shows all unused code:
@@ -74,6 +95,32 @@ If no baseline exists (or you use `--report`), Keela shows all unused code:
 keela --report
 ```
 
+## What "Unused" Means
+
+Keela defines "unused" as **unused in production code** — not just unused anywhere.
+
+By default, Keela scans `app/`, `lib/`, and `config/` directories. It intentionally
+excludes `spec/` and `test/` directories because:
+
+1. **Tests aren't usage** — Code that only exists to be tested isn't providing
+   application value. If you delete the unused code, you delete its tests too.
+
+2. **Tests can cover dead code** — A method with 100% test coverage can still be
+   dead if nothing in the application calls it.
+
+3. **Cleaner signal** — Including test files would hide genuinely unused code
+   behind "but it has tests!" false negatives.
+
+If Keela flags something that's only used in tests, consider whether the code
+(and its tests) can be removed entirely. If the code is intentionally test-only
+(e.g., test helpers defined in `app/`), add it to your exclusion file.
+
+To include test directories in usage scanning (not recommended), use `--include`:
+
+```bash
+keela --include 'test/**/*.rb' --include 'spec/**/*.rb'
+```
+
 ## Command Line Options
 
 ```bash
@@ -114,10 +161,19 @@ keela --config path/to/keela.yml
 # Output as JSON (for CI integrations)
 keela --format json
 
-# Suppress progress bar (useful for CI and scripting)
+# Suppress all output (useful for CI and scripting, rely on exit code)
 keela --quiet
 keela -q
 
+# Show verbose debugging output (files scanned, patterns used)
+keela --verbose
+
+# Show source location (file:line) for each unused item
+keela --source-location
+
+# Validate exclusion file entries (find stale exclusions)
+keela --test-exclusions
+
 # Show version
 keela --version
 ```
@@ -143,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:
@@ -170,10 +280,39 @@ include_patterns:
 
 excluded_path: ".keela_excluded.yml"
 baseline_path: ".keela_baseline.yml"
+
+# Per-strategy configuration
+strategies:
+  methods:
+    definition_paths:
+      - app/helpers
+      - app/models
+      - lib/
 ```
 
 Keela automatically loads `keela.yml` or `.keela.yml` from the current directory. Use `--config` to specify a different path.
 
+### Customizing Definition Paths Per Strategy
+
+By default, each strategy looks for definitions in specific directories (e.g., `methods` looks in `app/helpers` and `app/models`). You can customize this per-strategy:
+
+```yaml
+# keela.yml
+strategies:
+  methods:
+    definition_paths:
+      - app/helpers
+      - app/models
+      - lib/
+      - ee/app/models
+  scopes:
+    definition_paths:
+      - app/models
+      - ee/app/models
+```
+
+This is useful when your project has code in non-standard locations (like `lib/` or enterprise edition directories) that you want Keela to check for unused definitions.
+
 ### Customizing Which Files to Scan
 
 There are two approaches:
@@ -238,14 +377,17 @@ The workflow:
 2. **CI runs**: `keela` compares against baseline, fails on new dead code
 3. **After cleanup**: Run `keela --update-baseline` to update the baseline
 
-### JSON Output
+### Structured Output Formats
 
-Use `--format json` for machine-readable output:
+Use `--format` for machine-readable output:
 
 ```bash
-keela --format json --report
+keela --format json --report   # JSON output
+keela --format toon --report   # TOON output (token-efficient for LLMs)
 ```
 
+#### JSON
+
 ```json
 {
   "strategies": ["methods", "scopes"],
@@ -267,7 +409,25 @@ keela --format json --report
 }
 ```
 
-This is useful for integrating with other tools, generating reports, or processing results programmatically.
+#### TOON
+
+[TOON (Token-Oriented Object Notation)](https://toonformat.dev/) is a compact format optimized for LLM prompts, using ~40-50% fewer tokens than JSON:
+
+```
+strategies[2]: methods,scopes
+unused:
+  methods:
+    "app/models/user.rb"[2]: unused_method,old_helper
+  scopes:
+    "app/models/post.rb"[1]: inactive
+summary:
+  total: 3
+  by_strategy:
+    methods: 2
+    scopes: 1
+```
+
+These formats are useful for integrating with other tools, generating reports, processing results programmatically, or including in LLM context windows.
 
 ## Exclusion File
 

data/exe/keela

@@ -43,7 +43,7 @@ OptionParser.new do |opts|
     options[:update_baseline] = true
   end
 
-  opts.on("--format FORMAT", %i[text json], "Output format: text (default) or json") do |format|
+  opts.on("--format FORMAT", %i[text json toon], "Output format: text (default), json, or toon") do |format|
     options[:format] = format
   end
 
@@ -82,6 +82,18 @@ OptionParser.new do |opts|
     options[:quiet] = true
   end
 
+  opts.on("--verbose", "Show detailed debugging output (files scanned, patterns used)") do
+    options[:verbose] = true
+  end
+
+  opts.on("--source-location", "Show file:line for each unused item in reports") do
+    options[:source_location] = true
+  end
+
+  opts.on("--test-exclusions", "Validate that exclusion file entries match actual definitions") do
+    options[:test_exclusions] = true
+  end
+
   opts.on("-h", "--help", "Show this help") do
     puts opts
     exit
@@ -99,9 +111,30 @@ end
 # Apply quiet mode if requested
 Keela.configuration.show_progress = false if options[:quiet]
 
+# Apply verbose mode if requested
+Keela.configuration.verbose = true if options[:verbose]
+
+# Apply source location mode if requested
+Keela.configuration.source_location = true if options[:source_location]
+
 # Set default baseline path if not specified
 Keela.configuration.baseline_path ||= ".keela_baseline.yml"
 
+# Handle --test-exclusions mode
+if options[:test_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
+
+  validator = Keela::ExclusionValidator.new(excluded_path)
+  success = validator.validate
+  exit(success ? 0 : 1)
+end
+
 STRATEGY_MAP = {
   methods: Keela::Strategies::Methods,
   scopes: Keela::Strategies::Scopes,
@@ -141,13 +174,46 @@ baseline = Keela::Baseline.new(Keela.configuration.baseline_path)
 # Load source files once and share across all strategies
 source_files = Keela::Scanner.load_source_files
 
+# Show verbose output if requested
+if options[:verbose]
+  config = Keela.configuration
+  globs = Keela::Scanner.build_file_globs(config)
+
+  puts Rainbow("=== Verbose Mode ===").magenta.bright
+  puts
+  puts Rainbow("Configuration:").yellow
+  puts "  Extensions: #{config.extensions.join(', ')}"
+  puts "  Directory patterns: #{config.directory_patterns.join(', ')}"
+  puts "  Include patterns: #{config.include_patterns.empty? ? '(none)' : config.include_patterns.join(', ')}"
+  puts "  Exclude patterns: #{config.exclude_patterns.empty? ? '(none)' : config.exclude_patterns.join(', ')}"
+  puts
+  puts Rainbow("Resolved globs:").yellow
+  globs.each { |g| puts "  #{g}" }
+  puts
+  sorted_files = source_files.keys.sort
+  file_count = sorted_files.size
+  max_display = 50
+
+  puts Rainbow("Files to scan (#{file_count}):").yellow
+  # Show all files when piping (not a TTY), truncate for interactive use
+  if file_count <= max_display || !$stdout.tty?
+    sorted_files.each { |f| puts "  #{f}" }
+  else
+    sorted_files.first(max_display).each { |f| puts "  #{f}" }
+    puts "  ... and #{file_count - max_display} more files"
+    puts "  (pipe output to see full list: keela --verbose > files.txt)"
+  end
+  puts
+end
+
 success = true
 results = {}
 
-json_mode = options[:format] == :json
+structured_output = Keela::Formatters.structured_format?(options[:format])
+silent_output = structured_output || options[:quiet]
 
 strategies.each_with_index do |strategy, index|
-  unless json_mode
+  unless silent_output
     puts Rainbow("=== Sniffing for unused #{strategy.name} ===").cyan.bright if strategies.size > 1
   end
 
@@ -155,13 +221,13 @@ strategies.each_with_index do |strategy, index|
   success &&= scanner.run(
     force_report: options[:force_report],
     update_baseline: options[:update_baseline],
-    silent: json_mode
+    silent: silent_output
   )
 
-  # Collect results for JSON output
+  # Collect results for structured output formats
   results[strategy.name] = scanner.unused_collection.transform_values(&:to_a)
 
-  unless json_mode
+  unless silent_output
     puts if strategies.size > 1 && index < strategies.size - 1
   end
 end
@@ -169,26 +235,14 @@ end
 # Save baseline after all strategies have run
 if options[:update_baseline]
   baseline.save
-  puts Rainbow("Updated #{baseline.path}").green.bright unless json_mode
+  puts Rainbow("Updated #{baseline.path}").green.bright unless silent_output
 end
 
-# Output JSON if requested
-if json_mode
-  require "json"
-
-  total = results.values.flat_map(&:values).flatten.size
-  by_strategy = results.transform_values { |files| files.values.flatten.size }
-
-  output = {
-    strategies: strategies.map(&:name),
-    unused: results.reject { |_, v| v.empty? },
-    summary: {
-      total: total,
-      by_strategy: by_strategy.reject { |_, v| v.zero? }
-    }
-  }
-
-  puts JSON.pretty_generate(output)
+# Output structured format if requested
+if structured_output
+  formatter_class = Keela::Formatters.for(options[:format])
+  formatter = formatter_class.new(results: results, strategies: strategies)
+  puts formatter.format
 end
 
 exit(success ? 0 : 1)

data/lib/keela/config_file.rb

@@ -17,6 +17,7 @@ module Keela
   #   - excluded_path: Path to YAML file of excluded items
   #   - baseline_path: Path to baseline YAML file
   #   - required_directory: Directory that must exist for scanning to proceed
+  #   - strategies: Per-strategy configuration (see below)
   #
   # Example:
   #   # keela.yml
@@ -29,6 +30,15 @@ module Keela
   #     - rb
   #     - haml
   #     - erb
+  #   strategies:
+  #     methods:
+  #       definition_paths:
+  #         - app/helpers
+  #         - app/models
+  #         - lib/
+  #     scopes:
+  #       definition_paths:
+  #         - app/models
   #
   module ConfigFile
     CONFIG_FILENAMES = %w[.keela/config.yml keela.yml .keela.yml].freeze
@@ -74,6 +84,15 @@ module Keela
           value = config[key]
           configuration.public_send("#{key}=", value)
         end
+
+        apply_strategy_options(config["strategies"]) if config.key?("strategies")
+      end
+
+      def apply_strategy_options(strategies)
+        return unless strategies.is_a?(Hash)
+
+        configuration = Keela.configuration
+        configuration.strategy_options = strategies
       end
     end
   end

data/lib/keela/configuration.rb

@@ -26,6 +26,18 @@ module Keela
     # Additional directory patterns to include (added to directory_patterns)
     attr_accessor :include_patterns
 
+    # Whether to show verbose debugging output
+    attr_accessor :verbose
+
+    # Whether to show source location (file:line) in reports
+    attr_accessor :source_location
+
+    # Per-strategy configuration options
+    # Hash of strategy_name => { option => value }
+    # Supported options:
+    #   - definition_file_pattern: Regex pattern string for files containing definitions
+    attr_accessor :strategy_options
+
     def initialize
       @extensions = %w[rb haml erb].freeze
       @directory_patterns = %w[
@@ -39,6 +51,14 @@ module Keela
       @show_progress = true
       @exclude_patterns = []
       @include_patterns = []
+      @verbose = false
+      @source_location = false
+      @strategy_options = {}
+    end
+
+    # Get options for a specific strategy
+    def options_for(strategy_name)
+      strategy_options[strategy_name.to_s] || {}
     end
   end
 end

data/lib/keela/exclusion_validator.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "rainbow"
+
+module Keela
+  class ExclusionValidator
+    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, :results
+
+    def initialize(excluded_path)
+      @excluded_path = excluded_path
+      @results = { valid: [], stale: [] }
+    end
+
+    def validate
+      unless File.exist?(excluded_path)
+        puts Rainbow("Exclusion file not found: #{excluded_path}").red
+        return false
+      end
+
+      all_excluded = YAML.load_file(excluded_path, symbolize_names: true) || {}
+
+      if all_excluded.empty?
+        puts Rainbow("Exclusion file is empty: #{excluded_path}").yellow
+        return true
+      end
+
+      puts "Validating exclusions in #{excluded_path}...\n\n"
+
+      # Detect format: strategy-aware or legacy flat
+      if strategy_aware_format?(all_excluded)
+        validate_strategy_aware(all_excluded)
+      else
+        validate_legacy_flat(all_excluded)
+      end
+
+      print_results
+      results[:stale].empty?
+    end
+
+    private
+
+    def strategy_aware_format?(data)
+      data.keys.any? { |k| STRATEGY_MAP.key?(k) }
+    end
+
+    def validate_strategy_aware(all_excluded)
+      all_excluded.each do |strategy_name, files|
+        next unless STRATEGY_MAP.key?(strategy_name)
+
+        strategy = STRATEGY_MAP[strategy_name].new
+        validate_files(strategy, strategy_name, files || {})
+      end
+    end
+
+    def validate_legacy_flat(all_excluded)
+      # Legacy format applies to all strategies, but we'll check against methods
+      strategy = Strategies::Methods.new
+      validate_files(strategy, :methods, all_excluded)
+    end
+
+    def validate_files(strategy, strategy_name, files)
+      files.each do |file_path, entries|
+        file_str = file_path.to_s
+        entries ||= []
+
+        entries.each do |entry|
+          name = entry.keys.first.to_s
+          reason = entry.values.first
+
+          if !File.exist?(file_str)
+            results[:stale] << {
+              strategy: strategy_name,
+              file: file_str,
+              name: name,
+              reason: reason,
+              error: "file not found"
+            }
+          elsif !definition_exists?(strategy, file_str, name)
+            results[:stale] << {
+              strategy: strategy_name,
+              file: file_str,
+              name: name,
+              reason: reason,
+              error: "no definition found"
+            }
+          else
+            results[:valid] << {
+              strategy: strategy_name,
+              file: file_str,
+              name: name,
+              reason: reason
+            }
+          end
+        end
+      end
+    end
+
+    def definition_exists?(strategy, file_path, name)
+      return false unless File.exist?(file_path)
+
+      lines = File.readlines(file_path)
+
+      # Check custom extraction first (for I18n YAML files)
+      custom_defs = strategy.extract_definitions_from_file(file_path, lines)
+      if custom_defs
+        return custom_defs.any? { |d| d[:name] == name }
+      end
+
+      # Default line-by-line extraction
+      lines.any? do |line|
+        next if strategy.skip_comments? && line.strip.start_with?("#")
+
+        result = strategy.extract_definition(line)
+        Array(result).compact.include?(name)
+      end
+    end
+
+    def print_results
+      if results[:valid].any?
+        puts Rainbow("✅ Valid exclusions (#{results[:valid].size}):").green.bright
+        group_by_strategy(results[:valid]).each do |strategy, entries|
+          puts "   #{strategy}:"
+          entries.each do |e|
+            puts "     #{e[:file]}:#{e[:name]}"
+          end
+        end
+        puts
+      end
+
+      if results[:stale].any?
+        puts Rainbow("⚠️  Stale exclusions found (#{results[:stale].size}):").yellow.bright
+        puts
+        group_by_strategy(results[:stale]).each do |strategy, entries|
+          puts "   #{strategy}:"
+          entries.each do |e|
+            puts "     #{e[:file]}:#{e[:name]} — #{e[:error]}"
+          end
+        end
+        puts
+        puts "Consider removing stale exclusions from #{excluded_path}"
+      else
+        puts Rainbow("All exclusions are valid!").green.bright
+      end
+    end
+
+    def group_by_strategy(entries)
+      entries.group_by { |e| e[:strategy] }
+    end
+  end
+end

data/lib/keela/formatters/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Keela
+  module Formatters
+    class Base
+      attr_reader :results, :strategies
+
+      def initialize(results:, strategies:)
+        @results = results
+        @strategies = strategies
+      end
+
+      def format
+        raise NotImplementedError, "Subclasses must implement #format"
+      end
+
+      private
+
+      def total_count
+        results.values.flat_map(&:values).flatten.size
+      end
+
+      def by_strategy_counts
+        results.transform_values { |files| files.values.flatten.size }
+                .reject { |_, v| v.zero? }
+      end
+
+      def non_empty_results
+        results.reject { |_, v| v.empty? }
+      end
+    end
+  end
+end

data/lib/keela/formatters/json.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Keela
+  module Formatters
+    class Json < Base
+      def format
+        output = {
+          strategies: strategies.map(&:name),
+          unused: non_empty_results,
+          summary: {
+            total: total_count,
+            by_strategy: by_strategy_counts
+          }
+        }
+
+        JSON.pretty_generate(output)
+      end
+    end
+  end
+end

data/lib/keela/formatters/toon.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "toon"
+
+module Keela
+  module Formatters
+    class Toon < Base
+      def format
+        output = {
+          "strategies" => strategies.map(&:name),
+          "unused" => non_empty_results.transform_keys(&:to_s),
+          "summary" => {
+            "total" => total_count,
+            "by_strategy" => by_strategy_counts.transform_keys(&:to_s)
+          }
+        }
+
+        ::Toon.encode(output)
+      end
+    end
+  end
+end

data/lib/keela/formatters.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "formatters/base"
+require_relative "formatters/json"
+require_relative "formatters/toon"
+
+module Keela
+  module Formatters
+    REGISTRY = {
+      json: Json,
+      toon: Toon
+    }.freeze
+
+    def self.for(format)
+      REGISTRY[format]
+    end
+
+    def self.structured_format?(format)
+      REGISTRY.key?(format)
+    end
+  end
+end

data/lib/keela/reporter.rb

@@ -11,12 +11,12 @@ module Keela
       @strategy_name = strategy_name
     end
 
-    def print_full_report(unused_collection, elapsed_time)
+    def print_full_report(unused_collection, elapsed_time, source_locations: {})
       unused_count = unused_collection.values.flatten.size
 
       if unused_count > 0
         puts "\nFound #{unused_count} unused #{strategy_name}:\n\n"
-        puts format_yaml(unused_collection)
+        puts format_report(unused_collection, source_locations)
         puts "\n"
       else
         puts Rainbow("No unused #{strategy_name} were found.").green.bright
@@ -25,8 +25,8 @@ module Keela
       puts "Finished in #{elapsed_time.round(2)} seconds."
     end
 
-    def print_diff_report(new_unused, removed, excluded_path:, baseline_path:)
-      print_new_unused(new_unused, excluded_path) unless new_unused.empty?
+    def print_diff_report(new_unused, removed, excluded_path:, baseline_path:, source_locations: {})
+      print_new_unused(new_unused, excluded_path, source_locations) unless new_unused.empty?
 
       if new_unused.size + removed.size > 0
         puts Rainbow("~" * 80).white.bright
@@ -36,13 +36,42 @@ module Keela
       print_removed(removed, baseline_path) unless removed.empty?
     end
 
+    def format_report(collection, source_locations = {})
+      if source_locations.empty?
+        format_yaml(collection)
+      else
+        format_with_locations(collection, source_locations)
+      end
+    end
+
     def format_yaml(collection)
       indent_yaml_list_items(collection.sort.to_h.to_yaml)
     end
 
     private
 
-    def print_new_unused(new_unused, excluded_path)
+    def format_with_locations(collection, source_locations)
+      # Calculate max name length for alignment
+      all_names = collection.values.flatten
+      max_name_len = all_names.map(&:length).max || 0
+      padding = max_name_len + 6  # "  - " prefix + 2 spaces
+
+      lines = ["---"]
+      collection.sort.each do |file, names|
+        lines << "#{file}:"
+        names.each do |name|
+          line_num = source_locations["#{file}:#{name}"]
+          if line_num
+            lines << "  - #{name}".ljust(padding) + "#{file}:#{line_num}"
+          else
+            lines << "  - #{name}"
+          end
+        end
+      end
+      lines.join("\n")
+    end
+
+    def print_new_unused(new_unused, excluded_path, source_locations = {})
       error = <<~MESSAGE
         We have detected #{new_unused.size} newly unused #{strategy_name}.
 
@@ -50,7 +79,7 @@ module Keela
       MESSAGE
 
       puts Rainbow(error).red.bright
-      puts Rainbow(format_yaml(parse_diff(new_unused))).red.bright
+      puts Rainbow(format_report(parse_diff(new_unused), source_locations)).red.bright
     end
 
     def print_removed(removed, baseline_path)

data/lib/keela/scanner.rb

@@ -5,7 +5,7 @@ require "yaml"
 
 module Keela
   class Scanner
-    attr_reader :strategy, :configuration, :baseline, :source_files, :unused_collection, :new_unused, :removed
+    attr_reader :strategy, :configuration, :baseline, :source_files, :unused_collection, :source_locations, :new_unused, :removed
 
     DEFAULT_EXCLUDED_PATHS = [".keela/excluded.yml", "keela_excluded.yml"].freeze
     DEFAULT_BASELINE_PATHS = [".keela/baseline.yml", "keela_baseline.yml"].freeze
@@ -48,6 +48,7 @@ module Keela
       @source_files = source_files || {}
       @source_files_preloaded = !source_files.nil?
       @unused_collection = Hash.new { |hash, key| hash[key] = [] }
+      @source_locations = {}  # { "file:name" => line_number }
       @new_unused = []
       @removed = []
     end
@@ -70,7 +71,7 @@ module Keela
 
       if report_mode
         elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
-        reporter.print_full_report(unused_collection, elapsed) unless silent
+        reporter.print_full_report(unused_collection, elapsed, source_locations: source_locations) unless silent
         if update_baseline
           baseline.set(strategy.name, unused_collection)
           # Note: caller is responsible for calling baseline.save after all strategies run
@@ -85,7 +86,8 @@ module Keela
           new_unused,
           removed,
           excluded_path: resolve_excluded_path || ".keela/excluded.yml",
-          baseline_path: baseline.path
+          baseline_path: baseline.path,
+          source_locations: source_locations
         )
       end
 
@@ -155,11 +157,17 @@ module Keela
         next custom_definitions if custom_definitions
 
         # Default: line-by-line parsing
-        lines.flat_map do |line|
+        track_lines = configuration.source_location
+        lines.each_with_index.flat_map do |line, index|
           next [] if strategy.skip_comments? && line.strip.start_with?("#")
 
-          name = strategy.extract_definition(line)
-          name ? [{ name: name, file: filename }] : []
+          result = strategy.extract_definition(line)
+          # Support both single name (String) and multiple names (Array)
+          Array(result).compact.map do |name|
+            definition = { name: name, file: filename }
+            definition[:line] = index + 1 if track_lines
+            definition
+          end
         end
       end
     end
@@ -202,15 +210,25 @@ 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
 
       unused.each do |unused_def|
         @unused_collection[unused_def[:file]] << unused_def[:name]
+        if unused_def[:line]
+          @source_locations["#{unused_def[:file]}:#{unused_def[:name]}"] = unused_def[:line]
+        end
       end
     end
 

data/lib/keela/strategies/attributes.rb

@@ -7,7 +7,7 @@ module Keela
         "attributes"
       end
 
-      def definition_file_pattern
+      def default_definition_file_pattern
         # Match app/ and lib/ directories, but exclude spec/ and test/
         %r{(?:^|/)(?:ee/)?(?:app|lib)/}
       end

data/lib/keela/strategies/constants.rb

@@ -7,7 +7,7 @@ module Keela
         "constants"
       end
 
-      def definition_file_pattern
+      def default_definition_file_pattern
         # Match app/ and lib/ directories, but exclude spec/ and test/
         %r{(?:^|/)(?:ee/)?(?:app|lib)/}
       end
@@ -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/delegations.rb

@@ -7,7 +7,7 @@ module Keela
         "delegations"
       end
 
-      def definition_file_pattern
+      def default_definition_file_pattern
         # Match app/models/ directories (including concerns), but exclude spec/test
         %r{(?:^|/)(?:ee/)?app/models/}
       end
@@ -44,12 +44,8 @@ module Keela
           methods = methods.map { |m| "#{prefix}_#{m}" }
         end
 
-        # Return single string for single method (scanner expects this)
-        # For multiple methods, return first one only
-        # The scanner will create one definition entry per extract_definition call
-        # To handle multiple delegations per line, we'd need to change the scanner
-        # For now, return just the first method
-        methods.first
+        # Return all methods (scanner handles both single string and array)
+        methods.length == 1 ? methods.first : methods
       end
 
       def usage_regex(name)

data/lib/keela/strategies/i18n_keys.rb

@@ -15,14 +15,21 @@ 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
 
-      def definition_file_pattern
+      def default_definition_file_pattern
         # Match locale YAML files
         %r{config/locales/.*\.ya?ml$}
       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

@@ -7,7 +7,7 @@ module Keela
         "methods"
       end
 
-      def definition_file_pattern
+      def default_definition_file_pattern
         %r{app/helpers|app/models}
       end
 
@@ -18,12 +18,20 @@ module Keela
       end
 
       def usage_regex(name)
+        method_name = Regexp.quote(name.sub(/^self\./, ""))
+
         if name.end_with?("=")
           # Setter method: match assignment usage
-          /(?<!def )#{Regexp.quote(name.sub(/^self\./, "").chomp("="))}\W=*/
+          /(?<!def |def self\.)#{method_name.chomp("=")}\W=*/
         else
-          # Regular method: match calls
-          /(?<!def )#{Regexp.quote(name.sub(/^self\./, ""))}\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/strategies/scopes.rb

@@ -7,7 +7,7 @@ module Keela
         "scopes"
       end
 
-      def definition_file_pattern
+      def default_definition_file_pattern
         %r{app/models}
       end
 

data/lib/keela/strategy.rb

@@ -14,8 +14,23 @@ module Keela
 
     # Regex pattern to match files that may contain definitions
     # (e.g., /app\/models/ for scopes)
+    #
+    # Can be overridden via configuration:
+    #   strategies:
+    #     methods:
+    #       definition_paths:
+    #         - app/helpers
+    #         - app/models
+    #         - lib/
+    #
     def definition_file_pattern
-      raise NotImplementedError, "#{self.class} must implement #definition_file_pattern"
+      configured_pattern || default_definition_file_pattern
+    end
+
+    # Default pattern when no configuration override is provided.
+    # Subclasses should implement this instead of definition_file_pattern.
+    def default_definition_file_pattern
+      raise NotImplementedError, "#{self.class} must implement #default_definition_file_pattern"
     end
 
     # Extract a definition name from a line of code, or nil if no definition found
@@ -39,5 +54,23 @@ module Keela
     def extract_definitions_from_file(_filepath, _lines)
       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
+      paths = Keela.configuration.options_for(name)["definition_paths"]
+      return nil unless paths.is_a?(Array) && paths.any?
+
+      escaped = paths.map { |p| Regexp.escape(p.to_s) }
+      Regexp.new(escaped.join("|"))
+    end
   end
 end

data/lib/keela/version.rb

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

data/lib/keela.rb

@@ -13,6 +13,8 @@ require_relative "keela/strategies/i18n_keys"
 require_relative "keela/reporter"
 require_relative "keela/baseline"
 require_relative "keela/scanner"
+require_relative "keela/exclusion_validator"
+require_relative "keela/formatters"
 
 module Keela
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keela
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Kerri Miller
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: toon-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: Like the famous CSI dog who found what others missed, Keela detects unused
   methods and scopes in your Ruby codebase.
 email: kerrizor@kerrizor.com
@@ -67,6 +81,11 @@ files:
 - lib/keela/baseline.rb
 - lib/keela/config_file.rb
 - lib/keela/configuration.rb
+- lib/keela/exclusion_validator.rb
+- lib/keela/formatters.rb
+- lib/keela/formatters/base.rb
+- lib/keela/formatters/json.rb
+- lib/keela/formatters/toon.rb
 - lib/keela/reporter.rb
 - lib/keela/scanner.rb
 - lib/keela/strategies/attributes.rb