keela 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5eafef4540bb30839eb54b9de70e43000be89b8984a5494d9c5b1e37c76b968
-  data.tar.gz: de69c9165352044cdfc64e84a480e4aef098a28d3ecfd285d6d0a2227d417b56
+  metadata.gz: 920e953982643da9bb58171ea626a130d27a3cc41f6ccfb3511eabefbb0b41c8
+  data.tar.gz: 8c7e5d91900e962efca4d08f242e9582ad9192c1d07401e45ce545df5af68d2a
 SHA512:
-  metadata.gz: 71d6ecd16abc63e8b74db4a09f6d5979e168219b16fa27014c848209e230d9674f9393b4087fa97af1c9bd0af84e7f00eaebabd2375fbc788f1d090377b39685
-  data.tar.gz: 5b590194ecec3ef30621d67c85bcd07a9cd4c7a43374184bd45ac53badab44cd86d83887294624e1e82122a5f85f5d57874b8e46252a92c1d3b3401a3de23be8
+  metadata.gz: 01efcb8620dd29060d5758ef41def0dd450f62d59d46cb6de8873a18b1a69014895bd64bd68aa263731cb6edbc8640dc6b24f3a9281a865ff650b9717693dd1f
+  data.tar.gz: d9e8650985b2ca2a618201ecc2ecc8ced5e275564c37e84658207b498ba70b2279d281486d2bd1127cf9696bc278cff5121a411b42ef27287bf94f5b5d157da6

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [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 (`SCREAMING_SNAKE_CASE = value`)
+- **Delegations strategy** for detecting unused `delegate :method, to: :target` declarations
+- **Attributes strategy** for detecting unused `attr_accessor`, `attr_reader`, `attr_writer` declarations
+- **Config file support** (`keela.yml` or `.keela.yml`) for project-specific settings
+- **Exclude patterns** via `--exclude` CLI flag or `exclude_patterns` in config file
+- **Include patterns** via `--include` CLI flag or `include_patterns` in config file (adds to default directory patterns)
+- **Configuration validation** - raises `ConfigurationError` if `directory_patterns` is customized while also using `include_patterns` or `exclude_patterns`
+- **I18n keys strategy (beta)** for detecting unused translation keys in locale files (`--type i18n_keys`)
+- **Multiple types** can now be specified with `--type methods,scopes,constants`
+- **JSON output** via `--format json` for machine-readable results (useful for CI integrations)
+
+### 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
+
+- Initial release
+- `Scanner` class for detecting unused code
+- Built-in strategies for methods and scopes detection
+- CLI tool with `--report` and `--update-baseline` modes
+- Configurable file extensions and directory patterns
+- Baseline comparison for CI integration
+- Exclusion file support for false positives

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kerri Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,346 @@
+# Keela 🐕
+
+Like the famous CSI dog who found what others missed, Keela sniffs out unused code in your Ruby codebase.
+
+## Why Remove Unused Code?
+
+Dead code isn't harmless — it's actively costly:
+
+- **Cognitive overhead**: Developers read and try to understand code that doesn't matter, slowing down onboarding and feature work
+- **CI minutes**: Tests for unused methods still run, burning compute time on every pipeline
+- **False confidence**: Test coverage metrics include dead code, masking gaps in the code that actually runs
+- **Refactoring friction**: Unused code creates dependencies that make refactoring harder ("wait, is this called somewhere?")
+- **Security surface**: More code means more potential vulnerabilities, even in paths users never hit
+
+Most codebases accumulate dead code gradually — a feature flag that's always on, a method replaced but never deleted, a scope that lost its last caller. Keela helps you find it and clean it up.
+
+## Installation
+
+```bash
+gem install keela
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'keela', group: :development
+```
+
+## Quick Start
+
+```bash
+# First time: generate a baseline of current unused code
+keela --update-baseline
+
+# This creates .keela_baseline.yml in your project root
+
+# From now on, just run:
+keela
+
+# Keela will fail if:
+#   - NEW unused code is detected (someone added dead code)
+#   - Previously unused code was REMOVED (time to update the baseline!)
+```
+
+## How It Works
+
+Keela operates in two modes:
+
+### Baseline Mode (Default)
+
+If a `.keela_baseline.yml` file exists, Keela compares the current scan against it:
+
+| Scenario | Result |
+|----------|--------|
+| No changes from baseline | ✅ Pass (silent, exit 0) |
+| NEW unused code detected | ❌ Fail (shows new items) |
+| Code REMOVED from baseline | ❌ Fail (prompts to update baseline) |
+
+This lets you gradually pay down tech debt while preventing new dead code from sneaking in.
+
+### Report Mode
+
+If no baseline exists (or you use `--report`), Keela shows all unused code:
+
+```bash
+keela --report
+```
+
+## Command Line Options
+
+```bash
+# 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
+
+# Update the baseline file
+keela --update-baseline
+
+# Use a custom baseline path
+keela --baseline config/unused_baseline.yml
+
+# Specify excluded items file
+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
+
+# 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:
+
+```yaml
+# .gitlab-ci.yml
+unused_code:
+  script:
+    - bundle exec keela
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+```
+
+```yaml
+# .github/workflows/ci.yml
+- name: Check for unused code
+  run: bundle exec keela
+```
+
+The workflow:
+
+1. **Initial setup**: Run `keela --update-baseline` and commit `.keela_baseline.yml`
+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:
+
+```yaml
+# .keela_excluded.yml
+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:
+
+```bash
+keela --excluded .keela_excluded.yml
+```
+
+## Ruby API
+
+```ruby
+require 'keela'
+
+# Configure Keela
+Keela.configure do |config|
+  config.extensions = %w[rb haml erb]
+  config.directory_patterns = %w[
+    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
+
+# Run a scan
+strategy = Keela::Strategies::Methods.new
+scanner = Keela::Scanner.new(strategy: strategy)
+success = scanner.run
+
+# Access results
+scanner.unused_collection  # Hash of file => [unused_names]
+scanner.new_unused         # Items not in baseline
+scanner.removed            # Items in baseline but no longer unused
+```
+
+## Custom Strategies
+
+Detect other patterns by creating your own strategy:
+
+```ruby
+class CallbackStrategy < Keela::Strategy
+  def name
+    "callbacks"
+  end
+
+  def definition_file_pattern
+    %r{app/models}
+  end
+
+  def extract_definition(line)
+    # Match: before_save :do_something
+    line =~ /(?:before|after|around)_\w+\s+:(\w+)/ ? Regexp.last_match(1) : nil
+  end
+
+  def usage_regex(name)
+    /def #{Regexp.quote(name)}\b/
+  end
+
+  def skip_comments?
+    true
+  end
+end
+
+scanner = Keela::Scanner.new(strategy: CallbackStrategy.new)
+scanner.run(force_report: true)
+```
+
+## About the Name
+
+Keela was a famous English Springer Spaniel known as the "CSI dog." She could detect microscopic traces of blood that other forensic methods missed, and worked on many high-profile cases. Like her namesake, this gem finds the unused code that other tools miss.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/exe/keela

@@ -0,0 +1,174 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "keela"
+
+options = {
+  type: :all,
+  force_report: false,
+  update_baseline: false,
+  config_path: nil,
+  format: :text
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: keela [options]"
+
+  opts.separator ""
+  opts.separator "Keela sniffs out unused code in your Ruby codebase."
+  opts.separator ""
+  opts.separator "By default, if a baseline file exists, Keela runs in diff mode:"
+  opts.separator "  - Fails if NEW unused code is detected"
+  opts.separator "  - Fails if previously unused code was REMOVED (update baseline)"
+  opts.separator "  - Passes if unchanged from baseline"
+  opts.separator ""
+  opts.separator "If no baseline exists, shows a full report of all unused code."
+  opts.separator ""
+  opts.separator "Options:"
+
+  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
+    options[:force_report] = true
+  end
+
+  opts.on("--update-baseline", "-u", "Update the baseline file with current unused code") do
+    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
+
+  opts.on("--baseline PATH", "Path to YAML baseline file (default: .keela_baseline.yml)") do |path|
+    Keela.configuration.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)
+  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("-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])
+
+# Set default baseline path if not specified
+Keela.configuration.baseline_path ||= ".keela_baseline.yml"
+
+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|
+  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 }
+
+  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)
+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