keela 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47038e1bf08a377dba99ae8fe91134d51726c3ee20f12a24083ee4f6ecd421db
-  data.tar.gz: 429275504d8993d585671dde3cb8b09f374aa315080667d3272958656a38fff3
+  metadata.gz: 3448ca0297d2fb01cbe430bf8d1686ae28871bfa36666815120241664ed95821
+  data.tar.gz: 05a96216af6eea62b31ee0e6d6ceb8e82326946ff8eecd35f3eeb07637d220d8
 SHA512:
-  metadata.gz: 146b50c0ec50be23c122a63481ba8a6185234dc9234577530178753346f1da8f30bccbecfc4d414a014bb056bf1d2adbcbb80531391ebb7f1185a266497b9ffc
-  data.tar.gz: d3250b7c810ae53389e0a18551d1c408f7218b1437f5047b76bc36e36e4fdf069d1166cd6e0ac64356366278ed73b986d0e511ad1cbf531814bdab3093fbf233
+  metadata.gz: fc7d5f1e2f1844dc9f67d51e96de17b23e3d040ce767b51529d23c1619f96ae86ea1bf82a028e2e09cea4d074fcba001dab20b1a29725f54f71c366b68a2de17
+  data.tar.gz: 177309a39a1fa56d97d6a3693ff674cd94b92cb81e00ea50a6b889823e4d68fd2fdf0601c7d7157e10f48d50f66f940bb92a695808b424d30f4b5ee14bd22623

data/CHANGELOG.md

@@ -7,6 +7,39 @@ 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
+
+- **Strategy-aware exclusion file format** - Exclusion files can now be organized by strategy (methods, scopes, etc.) to match the baseline file format. This allows excluding the same name in one strategy while flagging it in another. The legacy flat format is still supported for backward compatibility. ([#35](https://github.com/kerrizor/keela/pull/35))
+
+### Changed
+
+- **Performance: Share source files across strategies** - When scanning multiple strategies, source files are now loaded once and shared, reducing scan time by ~33% on large codebases. ([#37](https://github.com/kerrizor/keela/pull/37))
+
+### Fixed
+
+- CLI options now correctly override config file settings ([#36](https://github.com/kerrizor/keela/pull/36))
+
 ## [0.2.3] - 2026-07-31
 
 ### Fixed

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,25 +355,68 @@ 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
 
-Some code appears unused but is actually called dynamically. Exclude it:
+Some code appears unused but is actually called dynamically. Exclude it using the **strategy-aware format** (recommended):
 
 ```yaml
-# .keela_excluded.yml
+# .keela/excluded.yml (strategy-aware format)
+methods:
+  app/models/user.rb:
+    - legacy_method: "Called via metaprogramming"
+    - callback_method: "Used as ActiveRecord callback"
+  app/helpers/application_helper.rb:
+    - helper_method: "Called from views dynamically"
+scopes:
+  app/models/user.rb:
+    - active: "Called dynamically via send()"
+```
+
+This format mirrors the baseline file structure and allows you to exclude the same name in one strategy while flagging it in another. For example, if you have both `scope :active` and `def active` in the same file, you can exclude them independently.
+
+### Legacy Flat Format
+
+The flat format is still supported for backward compatibility:
+
+```yaml
+# .keela_excluded.yml (legacy flat format)
 app/models/user.rb:
   - legacy_method: "Called via metaprogramming"
   - callback_method: "Used as ActiveRecord callback"
-app/helpers/application_helper.rb:
-  - helper_method: "Called from views dynamically"
 ```
 
-Then run with:
+**Note:** With the flat format, an exclusion applies to ALL strategies. If you exclude `active`, both the method and scope named `active` will be excluded.
+
+### Usage
 
 ```bash
-keela --excluded .keela_excluded.yml
+keela --excluded .keela/excluded.yml
+```
+
+Or configure in `keela.yml`:
+
+```yaml
+excluded_path: ".keela/excluded.yml"
 ```
 
 ## Ruby API

data/exe/keela

@@ -13,6 +13,9 @@ options = {
   quiet: false
 }
 
+# Store CLI overrides separately so they can be applied after config file loads
+cli_overrides = {}
+
 OptionParser.new do |opts|
   opts.banner = "Usage: keela [options]"
 
@@ -40,28 +43,30 @@ 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
 
   opts.on("--excluded PATH", "Path to YAML file of excluded items") do |path|
-    Keela.configuration.excluded_path = path
+    cli_overrides[:excluded_path] = path
   end
 
   opts.on("--baseline PATH", "Path to YAML baseline file (default: .keela_baseline.yml)") do |path|
-    Keela.configuration.baseline_path = path
+    cli_overrides[:baseline_path] = path
   end
 
   opts.on("--extensions EXTS", "Comma-separated file extensions to scan (default: rb,haml,erb)") do |exts|
-    Keela.configuration.extensions = exts.split(",").map(&:strip)
+    cli_overrides[:extensions] = exts.split(",").map(&:strip)
   end
 
   opts.on("--exclude PATTERN", "Glob pattern for files to exclude (can be used multiple times)") do |pattern|
-    Keela.configuration.exclude_patterns << pattern
+    cli_overrides[:exclude_patterns] ||= []
+    cli_overrides[:exclude_patterns] << pattern
   end
 
   opts.on("--include PATTERN", "Additional glob pattern to scan (can be used multiple times)") do |pattern|
-    Keela.configuration.include_patterns << pattern
+    cli_overrides[:include_patterns] ||= []
+    cli_overrides[:include_patterns] << pattern
   end
 
   opts.on("--config PATH", "-c", "Path to config file (default: keela.yml or .keela.yml)") do |path|
@@ -77,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
@@ -84,15 +101,40 @@ OptionParser.new do |opts|
 end.parse!
 
 # Load config file (keela.yml or .keela.yml) if present
-# CLI options override config file settings
 Keela::ConfigFile.load(path: options[:config_path])
 
+# Apply CLI overrides (these take precedence over config file)
+cli_overrides.each do |key, value|
+  Keela.configuration.public_send("#{key}=", value)
+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,
@@ -129,27 +171,63 @@ strategies = build_strategies(options[:types])
 # Share a single baseline across all strategies
 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
 
-  scanner = Keela::Scanner.new(strategy: strategy, baseline: baseline)
+  scanner = Keela::Scanner.new(strategy: strategy, baseline: baseline, source_files: source_files)
   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
@@ -157,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,17 +5,50 @@ 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
 
-    def initialize(strategy:, configuration: Keela.configuration, baseline: nil)
+    # Load source files once for sharing across multiple Scanner instances.
+    # Returns a hash of { filename => [lines] }.
+    def self.load_source_files(configuration: Keela.configuration)
+      source_files = {}
+      file_globs = build_file_globs(configuration)
+
+      Dir.glob(file_globs).each do |filename|
+        next if excluded_file?(filename, configuration)
+
+        source_files[filename] = File.readlines(filename)
+      end
+
+      source_files
+    end
+
+    def self.build_file_globs(configuration)
+      all_patterns = configuration.directory_patterns + configuration.include_patterns
+
+      configuration.extensions.flat_map do |ext|
+        all_patterns.map { |pattern| format(pattern, ext: ext) }
+      end
+    end
+
+    def self.excluded_file?(filename, configuration)
+      return false if configuration.exclude_patterns.empty?
+
+      configuration.exclude_patterns.any? do |pattern|
+        File.fnmatch?(pattern, filename, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      end
+    end
+
+    def initialize(strategy:, configuration: Keela.configuration, baseline: nil, source_files: nil)
       @strategy = strategy
       @configuration = configuration
       @baseline = baseline || Baseline.new(resolve_baseline_path)
-      @source_files = {}
+      @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
@@ -38,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
@@ -53,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
 
@@ -97,6 +131,8 @@ module Keela
     end
 
     def load_source_files
+      return if @source_files_preloaded
+
       Dir.glob(file_globs).each do |filename|
         next if excluded_file?(filename)
 
@@ -121,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
@@ -134,7 +176,16 @@ module Keela
       path = resolve_excluded_path
       return definitions unless path
 
-      excluded = YAML.load_file(path, symbolize_names: true) || {}
+      all_excluded = YAML.load_file(path, symbolize_names: true) || {}
+
+      # 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)
+                   all_excluded[strategy.name.to_sym] || {}
+                 else
+                   all_excluded # Legacy flat format
+                 end
 
       definitions.reject do |h|
         excluded_for_file = excluded[h[:file].to_sym]
@@ -168,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.2.3"
+  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.2.3
+  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