keela 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fcf07cf3f0adee173c2dfaef9e79f256f6a6318c5dd843935b6113fede4dea4
-  data.tar.gz: 454fa3bc9a9839dcf7d5f40a6d2fa2160daeb3a2d113d2f372da6ce15f9a49b0
+  metadata.gz: 3448ca0297d2fb01cbe430bf8d1686ae28871bfa36666815120241664ed95821
+  data.tar.gz: 05a96216af6eea62b31ee0e6d6ceb8e82326946ff8eecd35f3eeb07637d220d8
 SHA512:
-  metadata.gz: f9105a9cc47b95443d527772bd1dc44b5578d3b88829ec0144109e1ce82cc03d3414be62de9c8e4f8a7ab308b742e3beea343e6aefd2b4e3184f694847bba711
-  data.tar.gz: b583a1e03b6b460d4393ed687ef8796315c6fc4e8f9e4afde3a4edce26581536ef0b72dbef7215237b97835263b12a52b55879f391d901efe5409007ae407982
+  metadata.gz: fc7d5f1e2f1844dc9f67d51e96de17b23e3d040ce767b51529d23c1619f96ae86ea1bf82a028e2e09cea4d074fcba001dab20b1a29725f54f71c366b68a2de17
+  data.tar.gz: 177309a39a1fa56d97d6a3693ff674cd94b92cb81e00ea50a6b889823e4d68fd2fdf0601c7d7157e10f48d50f66f940bb92a695808b424d30f4b5ee14bd22623

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
 ```
@@ -170,10 +226,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 +323,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 +355,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
@@ -211,6 +219,9 @@ module Keela
 
       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

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

@@ -22,7 +22,7 @@ module Keela
         "i18n_keys"
       end
 
-      def definition_file_pattern
+      def default_definition_file_pattern
         # Match locale YAML files
         %r{config/locales/.*\.ya?ml$}
       end

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,15 @@ 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/
+          # Exclude both "def foo" and "def self.foo" definitions
+          /(?<!def |def self\.)#{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,15 @@ module Keela
     def extract_definitions_from_file(_filepath, _lines)
       nil
     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.0"
 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.0
 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