keela 0.0.2 → 0.2.0

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Keela
+  class Configuration
+    # File extensions to scan for code usage
+    attr_accessor :extensions
+
+    # Directory patterns to scan (use %<ext>s as placeholder for extension)
+    attr_accessor :directory_patterns
+
+    # Path to YAML file listing excluded items (won't be flagged as unused)
+    attr_accessor :excluded_path
+
+    # Path to YAML file tracking known unused items (baseline)
+    attr_accessor :baseline_path
+
+    # Optional directory that must exist for scanning to proceed (e.g., "ee" for GitLab)
+    attr_accessor :required_directory
+
+    # 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[
+        app/**/*.%<ext>s
+        lib/**/*.%<ext>s
+        config/**/*.%<ext>s
+      ].freeze
+      @excluded_path = nil
+      @baseline_path = nil
+      @required_directory = nil
+      @show_progress = true
+      @exclude_patterns = []
+      @include_patterns = []
+    end
+  end
+end

data/lib/keela/reporter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "rainbow"
+require "yaml"
+
+module Keela
+  class Reporter
+    attr_reader :strategy_name
+
+    def initialize(strategy_name)
+      @strategy_name = strategy_name
+    end
+
+    def print_full_report(unused_collection, elapsed_time)
+      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 "\n"
+      else
+        puts Rainbow("No unused #{strategy_name} were found.").green.bright
+      end
+
+      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?
+
+      if new_unused.size + removed.size > 0
+        puts Rainbow("~" * 80).white.bright
+        puts "\n"
+      end
+
+      print_removed(removed, baseline_path) unless removed.empty?
+    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)
+      error = <<~MESSAGE
+        We have detected #{new_unused.size} newly unused #{strategy_name}.
+
+        Please remove these #{strategy_name}, or if in use, add to #{excluded_path}.
+      MESSAGE
+
+      puts Rainbow(error).red.bright
+      puts Rainbow(format_yaml(parse_diff(new_unused))).red.bright
+    end
+
+    def print_removed(removed, baseline_path)
+      message = <<~MESSAGE
+        It appears you have removed unused #{strategy_name}. Thank you!
+
+        Please update #{File.basename(baseline_path)} and remove entries for these #{strategy_name}.
+      MESSAGE
+
+      puts Rainbow(message).yellow.bright
+      puts Rainbow(format_yaml(parse_diff(removed))).yellow.bright
+    end
+
+    def parse_diff(diff_to_parse)
+      result = Hash.new { |hash, key| hash[key] = [] }
+
+      diff_to_parse.each do |file_name, name|
+        result[file_name] << name
+      end
+
+      result
+    end
+
+    # Indents YAML list items that are not already indented.
+    # Ruby's to_yaml outputs list items without indentation (e.g., "- item"),
+    # but we want 2-space indentation (e.g., "  - item").
+    def indent_yaml_list_items(yaml_string)
+      yaml_string.gsub(/\n-(\s+\S)/, "\n  -\\1")
+    end
+  end
+end

data/lib/keela/scanner.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "parallel"
+require "yaml"
+
+module Keela
+  class Scanner
+    attr_reader :strategy, :configuration, :baseline, :source_files, :unused_collection, :new_unused, :removed
+
+    def initialize(strategy:, configuration: Keela.configuration, baseline: nil)
+      @strategy = strategy
+      @configuration = configuration
+      @baseline = baseline || Baseline.new(configuration.baseline_path)
+      @source_files = {}
+      @unused_collection = Hash.new { |hash, key| hash[key] = [] }
+      @new_unused = []
+      @removed = []
+    end
+
+    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
+      definitions = find_definitions
+      definitions = filter_excluded(definitions)
+
+      # Determine mode: report if forced, updating baseline, or no baseline exists
+      report_mode = force_report || update_baseline || !baseline.exists?
+
+      find_unused(definitions, show_progress: report_mode && !silent)
+
+      if report_mode
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+        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
+      unless silent
+        reporter.print_diff_report(
+          new_unused,
+          removed,
+          excluded_path: configuration.excluded_path || "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|
+        all_patterns.map { |pattern| format(pattern, ext: ext) }
+      end
+    end
+
+    private
+
+    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|
+        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)
+          name ? [{ name: name, file: filename }] : []
+        end
+      end
+    end
+
+    def filter_excluded(definitions)
+      return definitions unless configuration.excluded_path
+      return definitions unless File.exist?(configuration.excluded_path)
+
+      excluded = YAML.load_file(configuration.excluded_path, symbolize_names: true) || {}
+
+      definitions.reject do |h|
+        excluded_for_file = excluded[h[:file].to_sym]
+        excluded_for_file&.flat_map(&:keys)&.include?(h[:name].to_sym)
+      end
+    end
+
+    def find_unused(definitions, show_progress: false)
+      source_code = source_files.values.flatten.join
+
+      progress_label = show_progress ? "Checking #{strategy.name}" : nil
+
+      unused = Parallel.flat_map(definitions, progress: progress_label) do |definition|
+        regex = strategy.usage_regex(definition[:name])
+        regex.match?(source_code) ? [] : definition
+      end
+
+      unused.each do |unused_def|
+        @unused_collection[unused_def[:file]] << unused_def[:name]
+      end
+    end
+
+    def compare_with_baseline
+      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
+  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/strategies/methods.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Keela
+  module Strategies
+    class Methods < Strategy
+      def name
+        "methods"
+      end
+
+      def definition_file_pattern
+        %r{app/helpers|app/models}
+      end
+
+      def extract_definition(line)
+        return nil unless line =~ /def ([^(;\s]+)/
+
+        Regexp.last_match(1).chomp
+      end
+
+      def usage_regex(name)
+        if name.end_with?("=")
+          # Setter method: match assignment usage
+          /(?<!def )#{Regexp.quote(name.sub(/^self\./, "").chomp("="))}\W=*/
+        else
+          # Regular method: match calls
+          /(?<!def )#{Regexp.quote(name.sub(/^self\./, ""))}\W/
+        end
+      end
+
+      def skip_comments?
+        false
+      end
+    end
+  end
+end

data/lib/keela/strategies/scopes.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Keela
+  module Strategies
+    class Scopes < Strategy
+      def name
+        "scopes"
+      end
+
+      def definition_file_pattern
+        %r{app/models}
+      end
+
+      def extract_definition(line)
+        return nil unless line =~ /\bscope\s+:(\w+)/
+
+        Regexp.last_match(1)
+      end
+
+      def usage_regex(name)
+        /(?<!scope :)(?<!def )#{Regexp.quote(name)}\W/
+      end
+
+      def skip_comments?
+        true
+      end
+    end
+  end
+end