keela 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2532684d9e7c3cca0411cbe55c3d944265236d159c287f8b719a778695872ed
-  data.tar.gz: '08a678fa6105ae093817dba3ce3632f25d173cae617db34aa267bd524b77e2ee'
+  metadata.gz: a2bb8c13b7ef3c4a38029a71e02f46a3d572cc9f27e2d625f779b39bef07197a
+  data.tar.gz: b6bfcdd221a08c429eac645c01598817c5c1bd01304b937da143d6a5c0c9eb26
 SHA512:
-  metadata.gz: 8b0574c28fcec2f29a78463c08d20ccf58401d81b67c60878571fef4c381dc88bd4beca3b802c72edb5b456ec9c8bbf7b1f46b3bd2c6ed68380994ac04267330
-  data.tar.gz: 90e50d394dff39875fad354923381b9490994a9d2a4d3673f4c1a0d6df15be85c21bb54a24fee6a4860553bcea580ac589d4ed57f0e5fa44c8c2e80ba6742765
+  metadata.gz: db79ae6b9b332d6bef3b2472f347f7b015805b70aef92ad58e5b788b8c33dac3424b9242aee60747b5eb6048a645140665e96f6dc27d6424a5160c4afe54e22f
+  data.tar.gz: fc15ddd72010545b39df3e03a7f7c28dea0fa6b14c3d5f2a8d9a9223e01e67336254864514ff9941195457e7d5cba90535da217b6a86b7d067f03f874464c3c6

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-07-27
+
+### Added
+
+- **Quiet mode** via `--quiet` / `-q` CLI flag to suppress progress bar output ([#26](https://github.com/kerrizor/keela/issues/26))
+
+### Changed
+
+- Default suggested excluded filename changed from `excluded.yml` to `keela_excluded.yml` for consistency with `keela_baseline.yml` ([#28](https://github.com/kerrizor/keela/pull/28))
+- Default file locations now support `.keela/` directory with fallback to root ([#29](https://github.com/kerrizor/keela/pull/29))
+  - Excluded: `.keela/excluded.yml` → `keela_excluded.yml`
+  - Baseline: `.keela/baseline.yml` → `keela_baseline.yml`
+
+## [0.2.0] - 2026-07-17
+
+### Added
+
+- `Baseline` class for managing multi-strategy baseline files ([#1](https://github.com/kerrizor/keela/pull/1))
+- Single baseline file now supports multiple strategy sections (methods, scopes)
+- **Constants strategy** for detecting unused constant definitions ([#2](https://github.com/kerrizor/keela/pull/2))
+- **Delegations strategy** for detecting unused `delegate :method, to: :target` declarations ([#4](https://github.com/kerrizor/keela/pull/4))
+- **Attributes strategy** for detecting unused `attr_accessor`, `attr_reader`, `attr_writer` declarations ([#5](https://github.com/kerrizor/keela/pull/5))
+- **Config file support** (`keela.yml` or `.keela.yml`) for project-specific settings ([#11](https://github.com/kerrizor/keela/pull/11))
+- **Exclude patterns** via `--exclude` CLI flag or `exclude_patterns` in config file ([#12](https://github.com/kerrizor/keela/pull/12))
+- **Include patterns** via `--include` CLI flag or `include_patterns` in config file ([#14](https://github.com/kerrizor/keela/pull/14))
+- **Configuration validation** - raises `ConfigurationError` if `directory_patterns` is customized while also using `include_patterns` or `exclude_patterns` ([#15](https://github.com/kerrizor/keela/pull/15))
+- **I18n keys strategy (beta)** for detecting unused translation keys in locale files ([#16](https://github.com/kerrizor/keela/pull/16))
+- **Multiple types** can now be specified with `--type methods,scopes,constants` ([#18](https://github.com/kerrizor/keela/pull/18))
+- **JSON output** via `--format json` for machine-readable results ([#19](https://github.com/kerrizor/keela/pull/19))
+
+### Fixed
+
+- Running strategies separately no longer overwrites previous strategy data ([#1](https://github.com/kerrizor/keela/pull/1))
+
 ## [0.1.0] - 2026-07-16
 
 ### Added

data/README.md

@@ -1,6 +1,14 @@
 # Keela 🐕
 
-Like the famous CSI dog who found what others missed, Keela sniffs out unused code in your Ruby codebase.
+**Your Ruby codebase's forensic investigator.**
+
+Like her namesake — the famous springer spaniel who helped solve cases by finding microscopic traces that eluded forensic teams — Keela sniffs out the dead code that `grep` missed.
+
+```
+🔍 6 strategies: methods, scopes, constants, delegates, attrs, i18n
+🎯 Baseline mode — only bark at NEW dead code  
+📊 JSON output for CI pipelines
+```
 
 ## Why Remove Unused Code?
 
@@ -69,13 +77,16 @@ keela --report
 ## Command Line Options
 
 ```bash
-# Scan for all unused code (methods and scopes)
+# Scan for all unused code (methods, scopes, constants, delegations, attributes)
 keela
 
 # Scan for specific types
 keela --type methods
 keela --type scopes
 
+# Combine multiple types
+keela --type methods,scopes,constants
+
 # Force report mode (ignore baseline)
 keela --report
 
@@ -91,10 +102,117 @@ keela --excluded config/keela_excluded.yml
 # Custom file extensions
 keela --extensions rb,rake,haml
 
+# Exclude files matching patterns
+keela --exclude 'vendor/**/*' --exclude 'tmp/**/*'
+
+# Include additional directories (adds to defaults)
+keela --include 'engines/**/*.rb' --include 'custom/**/*.rb'
+
+# Use a custom config file
+keela --config path/to/keela.yml
+
+# Output as JSON (for CI integrations)
+keela --format json
+
+# Suppress progress bar (useful for CI and scripting)
+keela --quiet
+keela -q
+
 # Show version
 keela --version
 ```
 
+## Detection Strategies
+
+Keela detects several types of unused code:
+
+| Strategy | Detects | Example |
+|----------|---------|---------|
+| **methods** | Unused method definitions | `def unused_method` |
+| **scopes** | Unused ActiveRecord scopes | `scope :unused_scope, -> { }` |
+| **constants** | Unused constants | `UNUSED_CONSTANT = 'value'` |
+| **delegations** | Unused delegate declarations | `delegate :unused, to: :target` |
+| **attributes** | Unused attr_* declarations | `attr_accessor :unused_attr` |
+| **i18n_keys** | Unused translation keys | `en.users.unused_key` in locale YAML |
+
+Run all strategies (default) or target specific ones with `--type`.
+
+**Note:** The `i18n_keys` strategy is not included in `--type all` because it requires scanning YAML locale files. Run it explicitly with `--type i18n_keys`.
+
+### I18n Keys (Beta)
+
+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
+
+Review results carefully and use the exclusion file for known false positives.
+
+## Configuration File
+
+Create a `keela.yml` or `.keela.yml` in your project root:
+
+```yaml
+# keela.yml
+extensions:
+  - rb
+  - haml
+  - erb
+
+exclude_patterns:
+  - "vendor/**/*"
+  - "tmp/**/*"
+
+include_patterns:
+  - "engines/**/*.%<ext>s"
+
+excluded_path: ".keela_excluded.yml"
+baseline_path: ".keela_baseline.yml"
+```
+
+Keela automatically loads `keela.yml` or `.keela.yml` from the current directory. Use `--config` to specify a different path.
+
+### Customizing Which Files to Scan
+
+There are two approaches:
+
+**1. Tweak the defaults** with `--include` and `--exclude` (or `include_patterns`/`exclude_patterns` in config):
+
+```bash
+# Add engines/ to the default app/, lib/, config/ directories
+keela --include 'engines/**/*.rb'
+
+# Exclude vendor files from scanning
+keela --exclude 'vendor/**/*'
+```
+
+**2. Full control** with `directory_patterns` - replaces the defaults entirely:
+
+```yaml
+# keela.yml - scan ONLY these directories
+directory_patterns:
+  - "src/**/*.%<ext>s"
+  - "custom/**/*.%<ext>s"
+```
+
+Use `directory_patterns` when you need complete control. Use `--include`/`--exclude` when you just want to tweak the defaults.
+
+**Note:** Mixing both approaches raises a `ConfigurationError`. Choose one or the other.
+
+**Available options:**
+
+| Key | Description | Default |
+|-----|-------------|---------|
+| `directory_patterns` | Glob patterns for files to scan (replaces defaults) | `app/`, `lib/`, `config/` |
+| `extensions` | File extensions to scan | `rb`, `haml`, `erb` |
+| `include_patterns` | Additional patterns to scan (added to defaults) | `[]` |
+| `exclude_patterns` | Patterns for files to exclude | `[]` |
+| `excluded_path` | Path to YAML file of excluded items | `nil` |
+| `baseline_path` | Path to baseline YAML file | `.keela_baseline.yml` |
+| `required_directory` | Directory that must exist for scanning to proceed | `nil` |
+
 ## CI Integration
 
 Keela is designed for CI pipelines. Add it to catch dead code before it merges:
@@ -120,6 +238,37 @@ 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
+
+Use `--format json` for machine-readable output:
+
+```bash
+keela --format json --report
+```
+
+```json
+{
+  "strategies": ["methods", "scopes"],
+  "unused": {
+    "methods": {
+      "app/models/user.rb": ["unused_method", "old_helper"]
+    },
+    "scopes": {
+      "app/models/post.rb": ["inactive"]
+    }
+  },
+  "summary": {
+    "total": 3,
+    "by_strategy": {
+      "methods": 2,
+      "scopes": 1
+    }
+  }
+}
+```
+
+This is useful for integrating with other tools, generating reports, or processing results programmatically.
+
 ## Exclusion File
 
 Some code appears unused but is actually called dynamically. Exclude it:
@@ -151,6 +300,8 @@ Keela.configure do |config|
     app/**/*.%<ext>s
     lib/**/*.%<ext>s
   ]
+  config.include_patterns = %w[engines/**/*.%<ext>s]
+  config.exclude_patterns = %w[vendor/**/* tmp/**/*]
   config.excluded_path = '.keela_excluded.yml'
   config.baseline_path = '.keela_baseline.yml'
 end
@@ -200,7 +351,11 @@ scanner.run(force_report: true)
 
 ## About the Name
 
-[Keela](https://en.wikipedia.org/wiki/Keela_(dog)) was a famous English Springer Spaniel known as the "CSI dog." She could detect microscopic traces of blood that other methods missed, and worked on many high-profile forensic cases including the Madeleine McCann investigation. Like her namesake, this gem finds the unused code that other tools miss.
+Keela was a famous English Springer Spaniel known as the "CSI dog." She could detect microscopic traces of blood that other forensic methods missed, helping solve cases that had gone cold for decades. Her nose was so sensitive she found evidence that luminol and DNA testing couldn't.
+
+Like her namesake, this gem finds the dead code that `grep` and your IDE missed.
+
+*Good girl, Keela.* 🦴
 
 ## License
 

data/exe/keela

@@ -7,7 +7,10 @@ require "keela"
 options = {
   type: :all,
   force_report: false,
-  update_baseline: false
+  update_baseline: false,
+  config_path: nil,
+  format: :text,
+  quiet: false
 }
 
 OptionParser.new do |opts|
@@ -25,8 +28,8 @@ OptionParser.new do |opts|
   opts.separator ""
   opts.separator "Options:"
 
-  opts.on("--type TYPE", %i[methods scopes all], "Type to detect: methods, scopes, all (default: all)") do |type|
-    options[:type] = type
+  opts.on("--type TYPES", "Comma-separated types to detect: methods, scopes, constants, delegations, attributes, i18n_keys, all (default: all)") do |types|
+    options[:types] = types.split(",").map { |t| t.strip.to_sym }
   end
 
   opts.on("--report", "-r", "Force report mode: show all unused code (ignore baseline)") do
@@ -37,6 +40,10 @@ OptionParser.new do |opts|
     options[:update_baseline] = true
   end
 
+  opts.on("--format FORMAT", %i[text json], "Output format: text (default) or json") do |format|
+    options[:format] = format
+  end
+
   opts.on("--excluded PATH", "Path to YAML file of excluded items") do |path|
     Keela.configuration.excluded_path = path
   end
@@ -49,38 +56,127 @@ OptionParser.new do |opts|
     Keela.configuration.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
+  end
+
+  opts.on("--include PATTERN", "Additional glob pattern to scan (can be used multiple times)") do |pattern|
+    Keela.configuration.include_patterns << pattern
+  end
+
+  opts.on("--config PATH", "-c", "Path to config file (default: keela.yml or .keela.yml)") do |path|
+    options[:config_path] = path
+  end
+
   opts.on("--version", "-v", "Show version") do
     puts "keela #{Keela::VERSION}"
     exit
   end
 
+  opts.on("--quiet", "-q", "Suppress progress bar output (useful for CI and scripting)") do
+    options[:quiet] = true
+  end
+
   opts.on("-h", "--help", "Show this help") do
     puts opts
     exit
   end
 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 quiet mode if requested
+Keela.configuration.show_progress = false if options[:quiet]
+
 # Set default baseline path if not specified
 Keela.configuration.baseline_path ||= ".keela_baseline.yml"
 
-strategies = case options[:type]
-             when :all
-               [Keela::Strategies::Methods.new, Keela::Strategies::Scopes.new]
-             when :methods
-               [Keela::Strategies::Methods.new]
-             when :scopes
-               [Keela::Strategies::Scopes.new]
-             end
+STRATEGY_MAP = {
+  methods: Keela::Strategies::Methods,
+  scopes: Keela::Strategies::Scopes,
+  constants: Keela::Strategies::Constants,
+  delegations: Keela::Strategies::Delegations,
+  attributes: Keela::Strategies::Attributes,
+  i18n_keys: Keela::Strategies::I18nKeys
+}.freeze
+
+# Default strategies for "all" (excludes i18n_keys which requires different config)
+DEFAULT_STRATEGIES = %i[methods scopes constants delegations attributes].freeze
+
+VALID_TYPES = (STRATEGY_MAP.keys + [:all]).freeze
+
+def build_strategies(types)
+  types = types || [:all]
+
+  # Validate types
+  invalid = types - VALID_TYPES
+  unless invalid.empty?
+    warn "Error: Invalid type(s): #{invalid.join(', ')}"
+    warn "Valid types: #{VALID_TYPES.join(', ')}"
+    exit 1
+  end
+
+  # Expand :all to default strategies
+  expanded = types.flat_map { |t| t == :all ? DEFAULT_STRATEGIES : t }.uniq
+
+  expanded.map { |t| STRATEGY_MAP[t].new }
+end
+
+strategies = build_strategies(options[:types])
+
+# Share a single baseline across all strategies
+baseline = Keela::Baseline.new(Keela.configuration.baseline_path)
 
 success = true
+results = {}
+
+json_mode = options[:format] == :json
 
 strategies.each_with_index do |strategy, index|
-  puts Rainbow("=== Sniffing for unused #{strategy.name} ===").cyan.bright if strategies.size > 1
+  unless json_mode
+    puts Rainbow("=== Sniffing for unused #{strategy.name} ===").cyan.bright if strategies.size > 1
+  end
+
+  scanner = Keela::Scanner.new(strategy: strategy, baseline: baseline)
+  success &&= scanner.run(
+    force_report: options[:force_report],
+    update_baseline: options[:update_baseline],
+    silent: json_mode
+  )
+
+  # Collect results for JSON output
+  results[strategy.name] = scanner.unused_collection.transform_values(&:to_a)
+
+  unless json_mode
+    puts if strategies.size > 1 && index < strategies.size - 1
+  end
+end
+
+# Save baseline after all strategies have run
+if options[:update_baseline]
+  baseline.save
+  puts Rainbow("Updated #{baseline.path}").green.bright unless json_mode
+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 }
 
-  scanner = Keela::Scanner.new(strategy: strategy)
-  success &&= scanner.run(force_report: options[:force_report], update_baseline: options[:update_baseline])
+  output = {
+    strategies: strategies.map(&:name),
+    unused: results.reject { |_, v| v.empty? },
+    summary: {
+      total: total,
+      by_strategy: by_strategy.reject { |_, v| v.zero? }
+    }
+  }
 
-  puts if strategies.size > 1 && index < strategies.size - 1
+  puts JSON.pretty_generate(output)
 end
 
 exit(success ? 0 : 1)

data/lib/keela/baseline.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Keela
+  # Handles reading and writing baseline files with multiple strategy sections.
+  #
+  # File format:
+  #   methods:
+  #     app/models/user.rb:
+  #       - unused_method
+  #   scopes:
+  #     app/models/user.rb:
+  #       - unused_scope
+  #
+  class Baseline
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+      @data = nil
+    end
+
+    def exists?
+      path && File.exist?(path)
+    end
+
+    def load
+      return {} unless exists?
+
+      @data = YAML.load_file(path) || {}
+    end
+
+    def data
+      @data ||= load
+    end
+
+    def get(strategy_name)
+      data[strategy_name] || {}
+    end
+
+    def set(strategy_name, unused_collection)
+      # Ensure we've loaded existing data before setting
+      load if @data.nil? && exists?
+      @data ||= {}
+      @data[strategy_name] = unused_collection.sort.to_h
+    end
+
+    def save
+      return unless path
+
+      header = <<~HEADER
+        # Unused code identified by Keela.
+        # These are potential targets for removal.
+        #
+        # If an item listed here is actually in use,
+        # remove it from this file and add it to your excluded file.
+        #
+      HEADER
+
+      sorted_data = data.sort.to_h
+      yaml_content = if sorted_data.empty? || sorted_data.values.all?(&:empty?)
+                       "#{header}---\n{}\n"
+                     else
+                       "#{header}#{format_yaml(sorted_data)}"
+                     end
+
+      File.write(path, yaml_content)
+    end
+
+    private
+
+    def format_yaml(hash)
+      indent_yaml_list_items(hash.to_yaml)
+    end
+
+    # Indents YAML list items that are not already indented.
+    def indent_yaml_list_items(yaml_string)
+      yaml_string.gsub(/\n-(\s+\S)/, "\n  -\\1")
+    end
+  end
+end

data/lib/keela/config_file.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Keela
+  # Loads configuration from a YAML file.
+  #
+  # Looks for config files in this order:
+  #   1. keela.yml
+  #   2. .keela.yml
+  #
+  # Supported keys:
+  #   - extensions: Array of file extensions to scan
+  #   - directory_patterns: Array of glob patterns for directories to scan
+  #   - exclude_patterns: Array of glob patterns for files to exclude
+  #   - 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
+  #
+  # Example:
+  #   # keela.yml
+  #   directory_patterns:
+  #     - "app/**/*.%<ext>s"
+  #     - "lib/**/*.%<ext>s"
+  #     - "ee/app/**/*.%<ext>s"
+  #     - "ee/lib/**/*.%<ext>s"
+  #   extensions:
+  #     - rb
+  #     - haml
+  #     - erb
+  #
+  module ConfigFile
+    CONFIG_FILENAMES = %w[keela.yml .keela.yml].freeze
+
+    ALLOWED_KEYS = %w[
+      extensions
+      directory_patterns
+      include_patterns
+      exclude_patterns
+      excluded_path
+      baseline_path
+      required_directory
+    ].freeze
+
+    class << self
+      # Load configuration from a YAML file.
+      #
+      # @param path [String, nil] Optional path to config file. If nil, searches
+      #   for keela.yml or .keela.yml in the current directory.
+      # @return [Boolean] true if a config file was loaded, false otherwise
+      #
+      def load(path: nil)
+        config_path = path || find_config_file
+        return false unless config_path && File.exist?(config_path)
+
+        config = YAML.load_file(config_path) || {}
+        apply_config(config)
+        true
+      end
+
+      private
+
+      def find_config_file
+        CONFIG_FILENAMES.find { |filename| File.exist?(filename) }
+      end
+
+      def apply_config(config)
+        configuration = Keela.configuration
+
+        ALLOWED_KEYS.each do |key|
+          next unless config.key?(key)
+
+          value = config[key]
+          configuration.public_send("#{key}=", value)
+        end
+      end
+    end
+  end
+end

data/lib/keela/configuration.rb

@@ -20,6 +20,12 @@ module Keela
     # Whether to show progress during scanning
     attr_accessor :show_progress
 
+    # Glob patterns for files to exclude from scanning
+    attr_accessor :exclude_patterns
+
+    # Additional directory patterns to include (added to directory_patterns)
+    attr_accessor :include_patterns
+
     def initialize
       @extensions = %w[rb haml erb].freeze
       @directory_patterns = %w[
@@ -31,6 +37,8 @@ module Keela
       @baseline_path = nil
       @required_directory = nil
       @show_progress = true
+      @exclude_patterns = []
+      @include_patterns = []
     end
   end
 end

data/lib/keela/scanner.rb

@@ -5,20 +5,26 @@ require "yaml"
 
 module Keela
   class Scanner
-    attr_reader :strategy, :configuration, :source_files, :unused_collection, :new_unused, :removed
+    attr_reader :strategy, :configuration, :baseline, :source_files, :unused_collection, :new_unused, :removed
 
-    def initialize(strategy:, configuration: Keela.configuration)
+    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)
       @strategy = strategy
       @configuration = configuration
+      @baseline = baseline || Baseline.new(resolve_baseline_path)
       @source_files = {}
       @unused_collection = Hash.new { |hash, key| hash[key] = [] }
       @new_unused = []
       @removed = []
     end
 
-    def run(force_report: false, update_baseline: false)
+    def run(force_report: false, update_baseline: false, silent: false)
       return true unless should_run?
 
+      validate_configuration!
+
       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       load_source_files
@@ -26,60 +32,96 @@ module Keela
       definitions = filter_excluded(definitions)
 
       # Determine mode: report if forced, updating baseline, or no baseline exists
-      report_mode = force_report || update_baseline || !baseline_exists?
+      report_mode = force_report || update_baseline || !baseline.exists?
 
-      find_unused(definitions, show_progress: report_mode)
+      find_unused(definitions, show_progress: report_mode && !silent && configuration.show_progress)
 
       if report_mode
         elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
-        reporter.print_full_report(unused_collection, elapsed)
-        write_baseline_file if update_baseline
+        reporter.print_full_report(unused_collection, elapsed) unless silent
+        if update_baseline
+          baseline.set(strategy.name, unused_collection)
+          # Note: caller is responsible for calling baseline.save after all strategies run
+        end
         return true
       end
 
       # Baseline mode: compare against known unused code
       compare_with_baseline
-      reporter.print_diff_report(
-        new_unused,
-        removed,
-        excluded_path: configuration.excluded_path || "excluded.yml",
-        baseline_path: configuration.baseline_path
-      )
+      unless silent
+        reporter.print_diff_report(
+          new_unused,
+          removed,
+          excluded_path: resolve_excluded_path || ".keela/excluded.yml",
+          baseline_path: baseline.path
+        )
+      end
 
       new_unused.empty? && removed.empty?
     end
 
     def file_globs
+      all_patterns = configuration.directory_patterns + configuration.include_patterns
+
       configuration.extensions.flat_map do |ext|
-        configuration.directory_patterns.map { |pattern| format(pattern, ext: ext) }
+        all_patterns.map { |pattern| format(pattern, ext: ext) }
       end
     end
 
     private
 
-    def baseline_exists?
-      configuration.baseline_path && File.exist?(configuration.baseline_path)
-    end
-
     def should_run?
       return true unless configuration.required_directory
 
       Dir.exist?(configuration.required_directory)
     end
 
+    def validate_configuration!
+      custom_directory_patterns = configuration.directory_patterns != default_directory_patterns
+      has_include_patterns = !configuration.include_patterns.empty?
+      has_exclude_patterns = !configuration.exclude_patterns.empty?
+
+      return unless custom_directory_patterns && (has_include_patterns || has_exclude_patterns)
+
+      raise ConfigurationError,
+        "Cannot use include_patterns or exclude_patterns with custom directory_patterns. " \
+        "Use directory_patterns for full control, OR use include/exclude to tweak the defaults."
+    end
+
+    def default_directory_patterns
+      Keela::Configuration.new.directory_patterns
+    end
+
     def reporter
       @reporter ||= Reporter.new(strategy.name)
     end
 
     def load_source_files
       Dir.glob(file_globs).each do |filename|
+        next if excluded_file?(filename)
+
         @source_files[filename] = File.readlines(filename)
       end
     end
 
+    def excluded_file?(filename)
+      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 find_definitions
       source_files.keys.grep(strategy.definition_file_pattern).flat_map do |filename|
-        source_files[filename].flat_map do |line|
+        lines = source_files[filename]
+
+        # Allow strategies to override file parsing (e.g., for YAML files)
+        custom_definitions = strategy.extract_definitions_from_file(filename, lines)
+        next custom_definitions if custom_definitions
+
+        # Default: line-by-line parsing
+        lines.flat_map do |line|
           next [] if strategy.skip_comments? && line.strip.start_with?("#")
 
           name = strategy.extract_definition(line)
@@ -89,10 +131,10 @@ module Keela
     end
 
     def filter_excluded(definitions)
-      return definitions unless configuration.excluded_path
-      return definitions unless File.exist?(configuration.excluded_path)
+      path = resolve_excluded_path
+      return definitions unless path
 
-      excluded = YAML.load_file(configuration.excluded_path, symbolize_names: true) || {}
+      excluded = YAML.load_file(path, symbolize_names: true) || {}
 
       definitions.reject do |h|
         excluded_for_file = excluded[h[:file].to_sym]
@@ -100,6 +142,20 @@ module Keela
       end
     end
 
+    def resolve_excluded_path
+      return configuration.excluded_path if configuration.excluded_path && File.exist?(configuration.excluded_path)
+
+      # Check default locations in order of preference
+      DEFAULT_EXCLUDED_PATHS.find { |path| File.exist?(path) }
+    end
+
+    def resolve_baseline_path
+      return configuration.baseline_path if configuration.baseline_path && File.exist?(configuration.baseline_path)
+
+      # Check default locations in order of preference
+      DEFAULT_BASELINE_PATHS.find { |path| File.exist?(path) }
+    end
+
     def find_unused(definitions, show_progress: false)
       source_code = source_files.values.flatten.join
 
@@ -116,36 +172,13 @@ module Keela
     end
 
     def compare_with_baseline
-      baseline = YAML.load_file(configuration.baseline_path) || {}
-      baseline_items = baseline.flat_map { |f, names| [f].product(names) }
+      baseline_for_strategy = baseline.get(strategy.name)
+      baseline_items = baseline_for_strategy.flat_map { |f, names| [f].product(names) }
 
       current_items = unused_collection.flat_map { |f, names| [f].product(names) }
 
       @new_unused = current_items - baseline_items
       @removed = baseline_items - current_items
     end
-
-    def write_baseline_file
-      return unless configuration.baseline_path
-
-      header = <<~HEADER
-        # The #{strategy.name} listed here have been identified as "unused" by Keela,
-        # and are potential targets for future removal.
-        #
-        # If a #{strategy.name.chomp('s')} listed here is actually in use,
-        # remove it from this file and add it to your excluded file.
-        #
-      HEADER
-
-      yaml_content = if unused_collection.empty?
-                       "#{header}---\n{}\n"
-                     else
-                       sorted_collection = unused_collection.sort.to_h
-                       "#{header}#{reporter.format_yaml(sorted_collection)}"
-                     end
-
-      File.write(configuration.baseline_path, yaml_content)
-      puts Rainbow("Updated #{configuration.baseline_path}").green.bright
-    end
   end
 end

data/lib/keela/strategies/attributes.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Keela
+  module Strategies
+    class Attributes < Strategy
+      def name
+        "attributes"
+      end
+
+      def definition_file_pattern
+        # Match app/ and lib/ directories, but exclude spec/ and test/
+        %r{(?:^|/)(?:ee/)?(?:app|lib)/}
+      end
+
+      def extract_definition(line)
+        # Match attr_accessor, attr_reader, attr_writer declarations
+        # But NOT other attr_* DSLs like attr_encrypted, attr_spammable, etc.
+        return nil unless line =~ /^\s*attr_(accessor|reader|writer)\s+/
+
+        # Extract the first symbol after the attr_* declaration
+        return nil unless line =~ /attr_(?:accessor|reader|writer)\s+:(\w+)/
+
+        Regexp.last_match(1)
+      end
+
+      def usage_regex(name)
+        # Match usage of the attribute:
+        # - Getter: obj.name, name (without receiver)
+        # - Setter: obj.name = value, self.name = value
+        # - Instance variable: @name (direct access)
+        #
+        # Exclude:
+        # - Symbol notation (:name)
+        # - The attr_* definition itself
+        # - Partial word matches (username shouldn't match name)
+        /(?:(?<!:)(?<!attr_accessor\s)(?<!attr_reader\s)(?<!attr_writer\s)(?<![a-z_])#{Regexp.quote(name)}(?!\w)|@#{Regexp.quote(name)}(?!\w))/
+      end
+
+      def skip_comments?
+        true
+      end
+    end
+  end
+end

data/lib/keela/strategies/constants.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Keela
+  module Strategies
+    class Constants < Strategy
+      def name
+        "constants"
+      end
+
+      def definition_file_pattern
+        # Match app/ and lib/ directories, but exclude spec/ and test/
+        %r{(?:^|/)(?:ee/)?(?:app|lib)/}
+      end
+
+      def extract_definition(line)
+        # Match constant definitions like:
+        #   MAX_SIZE = 100
+        #   ALLOWED_TYPES = %w[foo bar].freeze
+        #   OPTIONS = { foo: 1 }.freeze
+        #
+        # Must start with uppercase letter followed by uppercase letters,
+        # digits, or underscores, then = (with optional whitespace)
+        #
+        # Avoid matching:
+        #   - Comparisons: MAX_SIZE == 100
+        #   - Namespaced access: Foo::BAR
+        #   - Class/module definitions
+
+        # First check it's not a comparison
+        return nil if line =~ /[!=]=/
+
+        # Match the constant definition pattern
+        return nil unless line =~ /^\s*([A-Z][A-Z0-9_]*)\s*=/
+
+        Regexp.last_match(1)
+      end
+
+      def usage_regex(name)
+        # Match usage of the constant, but not its definition
+        # Uses negative lookbehind to avoid matching when preceded by
+        # 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*=(?!=))/
+      end
+
+      def skip_comments?
+        true
+      end
+    end
+  end
+end

data/lib/keela/strategies/delegations.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Keela
+  module Strategies
+    class Delegations < Strategy
+      def name
+        "delegations"
+      end
+
+      def definition_file_pattern
+        # Match app/models/ directories (including concerns), but exclude spec/test
+        %r{(?:^|/)(?:ee/)?app/models/}
+      end
+
+      def extract_definition(line)
+        # Match delegate declarations like:
+        #   delegate :name, to: :user
+        #   delegate :name, :email, to: :user
+        #   delegate :name, to: :user, prefix: true
+        #   delegate :name, to: :user, prefix: :owner
+        #   delegate :name, to: :user, allow_nil: true
+        return nil unless line =~ /^\s*delegate\s+/
+
+        # Extract the target for prefix detection
+        target = line[/to:\s*:[@]?(\w+)/, 1]
+
+        # Check for prefix option
+        prefix = if line =~ /prefix:\s*:(\w+)/
+                   Regexp.last_match(1)
+                 elsif line =~ /prefix:\s*true/
+                   target
+                 end
+
+        # Extract all method symbols from the delegate call
+        # Match :symbol patterns before 'to:'
+        # Include ? and ! for predicate and bang methods
+        delegate_part = line.split(/,\s*to:/)[0]
+        methods = delegate_part.scan(/:(\w+[?!]?)/).flatten
+
+        return nil if methods.empty?
+
+        # Apply prefix if present
+        if prefix
+          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
+      end
+
+      def usage_regex(name)
+        # Match usage of the delegated method, but not the delegate declaration
+        # Uses negative lookbehind to avoid matching:
+        #   - Symbol notation (:name)
+        #   - Part of delegate declaration
+        # Uses word boundary to avoid partial matches
+        # Note: Regexp.quote handles ? and ! in method names
+        /(?<!:)(?<!delegate\s)(?<![a-z_])#{Regexp.quote(name)}(?!\w)/i
+      end
+
+      def skip_comments?
+        true
+      end
+    end
+  end
+end

data/lib/keela/strategies/i18n_keys.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Keela
+  module Strategies
+    # Detects unused I18n translation keys in locale files.
+    #
+    # Definitions are extracted from YAML locale files (config/locales/*.yml)
+    # and flattened to dot notation (e.g., "users.show.title").
+    #
+    # Usage is detected by searching for:
+    #   - I18n.t("key") or I18n.t('key')
+    #   - t("key") or t('key')
+    #   - t(:key)
+    #   - .human_attribute_name(:attr)
+    #
+    # Note: Lazy lookup (t('.title') in views) is not yet supported.
+    #
+    class I18nKeys < Strategy
+      def name
+        "i18n_keys"
+      end
+
+      def definition_file_pattern
+        # Match locale YAML files
+        %r{config/locales/.*\.ya?ml$}
+      end
+
+      # Override: I18n keys need special YAML parsing, not line-by-line
+      def extract_definitions_from_file(filepath, _lines)
+        return [] unless File.exist?(filepath)
+
+        content = YAML.load_file(filepath, permitted_classes: [Symbol]) || {}
+        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 }
+        end
+      rescue Psych::SyntaxError => e
+        warn "Warning: Could not parse #{filepath}: #{e.message}"
+        []
+      end
+
+      def extract_definition(_line)
+        # Not used - we override extract_definitions_from_file instead
+        nil
+      end
+
+      def usage_regex(name)
+        # Match various I18n lookup patterns:
+        #   I18n.t("users.show.title")
+        #   I18n.t('users.show.title')
+        #   t("users.show.title")
+        #   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"
+        quoted_name = Regexp.quote(name)
+
+        # Build pattern that matches the key in quotes or as a symbol
+        /(?:I18n\.)?t\s*\(\s*["':]+#{quoted_name}["']?\s*[,)]/
+      end
+
+      def skip_comments?
+        true
+      end
+
+      private
+
+      # Flatten nested hash to dot-notation keys
+      # { "en" => { "users" => { "title" => "..." } } }
+      # becomes ["en.users.title"]
+      def flatten_keys(hash, prefix = nil)
+        hash.flat_map do |key, value|
+          full_key = [prefix, key].compact.join(".")
+          case value
+          when Hash
+            flatten_keys(value, full_key)
+          else
+            [full_key]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/keela/strategy.rb

@@ -32,5 +32,12 @@ module Keela
     def skip_comments?
       false
     end
+
+    # Override this method for strategies that need custom file parsing
+    # (e.g., YAML files for I18n keys).
+    # Returns an array of { name:, file: } hashes, or nil to use default line-by-line parsing.
+    def extract_definitions_from_file(_filepath, _lines)
+      nil
+    end
   end
 end

data/lib/keela/version.rb

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

data/lib/keela.rb

@@ -2,13 +2,22 @@
 
 require_relative "keela/version"
 require_relative "keela/configuration"
+require_relative "keela/config_file"
 require_relative "keela/strategy"
 require_relative "keela/strategies/methods"
 require_relative "keela/strategies/scopes"
+require_relative "keela/strategies/constants"
+require_relative "keela/strategies/delegations"
+require_relative "keela/strategies/attributes"
+require_relative "keela/strategies/i18n_keys"
 require_relative "keela/reporter"
+require_relative "keela/baseline"
 require_relative "keela/scanner"
 
 module Keela
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
   class << self
     attr_writer :configuration
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keela
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kerri Miller
@@ -64,9 +64,15 @@ files:
 - README.md
 - exe/keela
 - lib/keela.rb
+- lib/keela/baseline.rb
+- lib/keela/config_file.rb
 - lib/keela/configuration.rb
 - lib/keela/reporter.rb
 - lib/keela/scanner.rb
+- lib/keela/strategies/attributes.rb
+- lib/keela/strategies/constants.rb
+- lib/keela/strategies/delegations.rb
+- lib/keela/strategies/i18n_keys.rb
 - lib/keela/strategies/methods.rb
 - lib/keela/strategies/scopes.rb
 - lib/keela/strategy.rb
@@ -93,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Sniff out unused code in your Ruby codebase
 test_files: []