keela 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3448ca0297d2fb01cbe430bf8d1686ae28871bfa36666815120241664ed95821
-  data.tar.gz: 05a96216af6eea62b31ee0e6d6ceb8e82326946ff8eecd35f3eeb07637d220d8
+  metadata.gz: 0755e73eaeeb61f9f97ffa109fd8c421316e7725b83ef2502a37c5ba0111858f
+  data.tar.gz: d66e1092dd578f28ae3d727b179b601fcd7068671550f9186e53c76a543d1763
 SHA512:
-  metadata.gz: fc7d5f1e2f1844dc9f67d51e96de17b23e3d040ce767b51529d23c1619f96ae86ea1bf82a028e2e09cea4d074fcba001dab20b1a29725f54f71c366b68a2de17
-  data.tar.gz: 177309a39a1fa56d97d6a3693ff674cd94b92cb81e00ea50a6b889823e4d68fd2fdf0601c7d7157e10f48d50f66f940bb92a695808b424d30f4b5ee14bd22623
+  metadata.gz: bf117842ed4d8891671dac92ee34c48b5433f50795f9a90963211c1e650df11b31e72c2d142a6fc489f3dfb040989341764ab6eba4d2ea70432828bd6ed1c1dc
+  data.tar.gz: ac2d7352393d70240f7ad1541f2ff476e5ed7c8def8b13212721a527df4e7c285b2c31519333ebe712aab31e9a186a997420598e7e7662af181353cf9f8b96ca

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-21
+
+### Added
+
+- **`partials` strategy**, which detects unused Rails view partials (`_*.html.{erb,haml,slim}`) in `app/views` and `ee/app/views`. It resolves explicit renders (`render "users/form"`, `render partial:`/`layout:`), relative bareword renders against the calling view or controller directory, `render_to_string`/`render_to_body`, and positional underscore paths (`render_to_string("shared/notes/_note")`). Opt-in via `--type partials` (not in the default set) while its false-positive rate is validated. Collection renders (`render @users`) and dynamic renders are documented limitations ([#82](https://github.com/kerrizor/keela/pull/82))
+- **`partials` strategy: configurable custom render-helper allowlist.** App-specific helpers that render a partial from an explicit string path (e.g. GitLab's `view_to_html_string`, `tabs_json`) can be registered under `strategies.partials.render_helpers`, so they are recognized as usages instead of false-flagging the partial as unused. Configured helpers are matched only for explicit paths (positional path strings, positional underscore paths, and `partial:`/`layout:` keys), never for bareword-relative resolution, which stays limited to `render`/`render_to_string`/`render_to_body`. Default behavior is unchanged when unset ([#87](https://github.com/kerrizor/keela/pull/87))
+- `Keela::Source`, which holds the concatenated source and its case-folded view
+- `Strategy#used?` and `Strategy#prepare`, so a strategy can give a cheaper equivalent of its `usage_regex`. `Strategy#usage_regex` is unchanged, so existing custom strategies keep working
+
+### Changed
+
+- CI now tests against Ruby 3.3, 3.4, and 4.0; dropped end-of-life Ruby 3.1 and 3.2. Minimum required Ruby is now 3.3.0
+- **Usage detection is faster.** On a 47.5 MB codebase of 24,783 files and 42,053 definitions, a full run went from 41s to 18.5s of wall time, and from 438s to 130s of CPU time. The report is unchanged
+- **The `attributes` strategy checks its two patterns separately.** It matched one pattern built as an alternation of a bare reference and an `@ivar` reference. An alternation has no single mandatory literal, so the regexp engine cannot fast-forward to a candidate position and scans the whole source instead. Each pattern now keeps its literal
+- **The `delegations` strategy folds the source instead of matching case-insensitively.** Only three ASCII fold targets have a non-ASCII source: U+017F folds to `s`, U+212A folds to `k`, and the eszett folds to `ss`. So once the scanned source is not entirely 7-bit ASCII, a `//i` pattern whose literal begins with `s` or `k` can no longer be found with a plain byte search, and takes 100x longer or worse. A single non-ASCII character in any scanned file is enough to put a whole run on that path, and method names beginning with `s` are common, so delegations such as `squash_never?` and `sentry_issue` each cost about a second. The source is now case-folded once per run and matched with a case-sensitive pattern. It falls back to the case-insensitive pattern when folding would not give the same answer, which only happens with non-ASCII source, for example a character that folds to two characters, or a non-ASCII character that folds into ASCII
+
+### Fixed
+
+- **`partials` strategy: a render inside a single-line ERB comment no longer counts as a usage.** A commented-out `<%# render "users/old_form" %>` (including the trim variants `<%-# ... %>` and `<%# ... -%>`) previously marked the partial used, hiding effectively dead partials. Single-line ERB comment tags are now stripped before render-matching in both the explicit-path and bareword/positional-underscore paths. Multi-line ERB comments and HAML comments remain out of scope and are still counted ([#88](https://github.com/kerrizor/keela/pull/88))
+- Usage matches can no longer span a file boundary. The concatenated source joined files with no separator, so a file whose last line lacked a trailing newline glued onto the next file's first line, letting a match exist across a gap that is in no single file. This silently marked some unused code as used. Each file is now newline-terminated before concatenation, affecting every strategy ([#86](https://github.com/kerrizor/keela/pull/86))
+- Unused entries are no longer listed more than once per file in reports and baselines when a single definition is extracted from multiple lines (e.g. the same method delegated twice, or a constant declared and referenced) ([#72](https://github.com/kerrizor/keela/pull/72))
+
+## [0.4.1] - 2026-08-21
+
+### Fixed
+
+- Constants used as hash keys (`CONST => value`) or in rescue splats (`rescue *ERRORS => e`) are now correctly detected as used ([#63](https://github.com/kerrizor/keela/pull/63))
+- Methods referenced as literal symbols (`:method_name`) are now detected as used, including Rails callbacks, `send(:method)`, `validate :method`, etc. ([#64](https://github.com/kerrizor/keela/issues/64))
+- I18n pluralization keys (`one`, `other`, `zero`, etc.) are now detected as used when the parent key is called with `t('key', count: n)` ([#69](https://github.com/kerrizor/keela/pull/69))
+- I18n lazy lookup (`t('.title')` in views) now correctly resolves to the full key based on the view path ([#17](https://github.com/kerrizor/keela/issues/17))
+
 ## [0.4.0] - 2026-08-14
 
 ### Added

data/README.md

@@ -2,17 +2,17 @@
 
 **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.
+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  
+🔍 7 strategies: methods, scopes, constants, delegates, attrs, i18n, partials
+🎯 Baseline mode: only bark at NEW dead code
 📊 JSON output for CI pipelines
 ```
 
 ## Why Remove Unused Code?
 
-Dead code isn't harmless — it's actively costly:
+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
@@ -20,7 +20,7 @@ Dead code isn't harmless — it's actively costly:
 - **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.
+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
 
@@ -97,18 +97,18 @@ keela --report
 
 ## What "Unused" Means
 
-Keela defines "unused" as **unused in production code** — not just unused anywhere.
+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
+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
+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
+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
@@ -131,6 +131,10 @@ keela
 keela --type methods
 keela --type scopes
 
+# Opt-in strategies (not in the default run)
+keela --type i18n_keys
+keela --type partials
+
 # Combine multiple types
 keela --type methods,scopes,constants
 
@@ -190,22 +194,90 @@ Keela detects several types of unused code:
 | **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 |
+| **partials** | Unused Rails view partials | `app/views/users/_unused.html.erb` |
 
 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`.
+**Note:** The `i18n_keys` and `partials` strategies are not included in `--type all`. Run them explicitly with `--type i18n_keys` or `--type partials`.
 
 ### 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
+
+The following patterns ARE now supported:
+- **Lazy lookup** - `t('.title')` in views resolves based on the view path
+- **Pluralization siblings** - `t('key', count: n)` marks all plural forms as used
 
 Review results carefully and use the exclusion file for known false positives.
 
+### Partials (Beta)
+
+The `partials` strategy is **beta** and may produce false positives. It detects unused Rails view partials (`_*.html.{erb,haml,slim}`) in `app/views` and `ee/app/views`, and resolves usage through `render` (and `render_to_string`/`render_to_body`) calls in views and controllers: explicit paths (`render "users/form"`, `render partial:`/`layout:`), relative bareword renders against the calling file's directory, and positional underscore paths (`render_to_string("shared/notes/_note")`).
+
+It cannot detect:
+
+- **Collection/object rendering** - `render @users` infers the partial from the object's class at runtime, which static analysis cannot resolve
+- **Dynamic rendering** - `render partial_name` where the partial name is a variable
+
+**Custom render helpers** (project-specific methods that render a partial from a string path, e.g. `view_to_html_string`) are not recognized by default, but you can register them with the `render_helpers` option so their partials are not false-flagged. See [Customizing Render Helpers Per Strategy](#customizing-render-helpers-per-strategy).
+
+Partials only reached via the undetectable patterns above may be reported as unused. Review results carefully and use the exclusion file (or baseline) for known false positives.
+
+## Limitations
+
+Keela uses static analysis: it reads your code without executing it. This means some patterns are **fundamentally undetectable**.
+
+### What Keela CAN Detect
+
+Keela detects **literal references** to methods, constants, etc.:
+
+```ruby
+# ✅ Direct calls
+user.save
+User.find(1)
+
+# ✅ Literal symbol references
+before_save :ensure_token
+validate :check_valid
+send(:process_data)
+respond_to?(:optional_method)
+```
+
+### What Keela CANNOT Detect
+
+**Dynamic dispatch** with interpolation or variables cannot be analyzed statically:
+
+```ruby
+# ❌ Interpolated symbols: what method does this call?
+public_send(:"add_#{role}", user)
+
+# ❌ Variable method names: could be anything
+send(method_name)
+
+# ❌ Computed method names
+define_method(compute_name) { }
+```
+
+To detect these, Keela would need to trace all possible runtime values, essentially becoming a Ruby interpreter. This is not a bug; it's a fundamental limitation of static analysis.
+
+### Handling False Positives
+
+When Keela reports a method as unused but it's actually called dynamically, add it to your exclusion file:
+
+```yaml
+# .keela/excluded.yml
+methods:
+  app/models/project_team.rb:
+    - add_owner: "Called via public_send(:\"add_\#{role}\")"
+    - add_maintainer: "Called via public_send(:\"add_\#{role}\")"
+    - add_developer: "Called via public_send(:\"add_\#{role}\")"
+```
+
+**Tip:** If you see `send`, `public_send`, or `define_method` with interpolation in a file, expect some false positives for methods in that file.
+
 ## Configuration File
 
 Create a `keela.yml` or `.keela.yml` in your project root:
@@ -259,6 +331,23 @@ strategies:
 
 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 Render Helpers Per Strategy
+
+The `partials` strategy recognizes `render`, `render_to_string`, and `render_to_body` when detecting partial usage. If your project renders partials through custom helper methods that take a string path, register them under `render_helpers` so their partials are not reported as unused:
+
+```yaml
+# keela.yml
+strategies:
+  partials:
+    render_helpers:
+      - view_to_html_string
+      - tabs_json
+```
+
+With the above, a call like `view_to_html_string("shared/notes/_note")` marks `shared/notes/note` as used.
+
+Configured helpers are matched for **explicit paths only** (positional path strings, positional underscore paths, and `partial:`/`layout:` keys). They are deliberately not used for relative bareword resolution (`view_to_html_string("form")` is not resolved against the calling file's directory), since an arbitrary helper name is too ambiguous to safely resolve a bare name. Relative bareword resolution stays limited to `render`/`render_to_string`/`render_to_body`.
+
 ### Customizing Which Files to Scan
 
 There are two approaches:
@@ -488,6 +577,10 @@ Like her namesake, this gem finds the dead code that `grep` and your IDE missed.
 
 *Good girl, Keela.* 🦴
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of notable changes to each release.
+
 ## License
 
 MIT License. See [LICENSE.txt](LICENSE.txt).

data/exe/keela

@@ -31,7 +31,7 @@ OptionParser.new do |opts|
   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|
+  opts.on("--type TYPES", "Comma-separated types to detect: methods, scopes, constants, delegations, attributes, i18n_keys, partials, all (default: all)") do |types|
     options[:types] = types.split(",").map { |t| t.strip.to_sym }
   end
 
@@ -141,10 +141,12 @@ STRATEGY_MAP = {
   constants: Keela::Strategies::Constants,
   delegations: Keela::Strategies::Delegations,
   attributes: Keela::Strategies::Attributes,
-  i18n_keys: Keela::Strategies::I18nKeys
+  i18n_keys: Keela::Strategies::I18nKeys,
+  partials: Keela::Strategies::Partials
 }.freeze
 
-# Default strategies for "all" (excludes i18n_keys which requires different config)
+# Default strategies for "all". Excludes i18n_keys and partials, which are
+# opt-in via --type until we're confident in their false-positive rate.
 DEFAULT_STRATEGIES = %i[methods scopes constants delegations attributes].freeze
 
 VALID_TYPES = (STRATEGY_MAP.keys + [:all]).freeze

data/lib/keela/scanner.rb

@@ -208,17 +208,35 @@ module Keela
     end
 
     def find_unused(definitions, show_progress: false)
-      source_code = source_files.values.flatten.join
+      source = Source.from_source_files(source_files)
+
+      # Get additional used names from strategy-specific detection
+      # (e.g., I18n lazy lookup)
+      additional_used = strategy.additional_used_names(source_files)
+
+      # Build the source views the strategy needs here, in the parent, so that
+      # the workers Parallel forks below inherit them instead of each building
+      # its own copy of a string the size of the whole codebase.
+      strategy.prepare(source)
 
       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
+        # Check if marked as used by additional detection
+        next [] if additional_used.include?(definition[:name])
+
+        strategy.used?(definition[:name], source) ? [] : definition
       end
 
+      # A single logical definition can be extracted from multiple lines
+      # (e.g. the same method delegated twice, or a constant declared and
+      # referenced), so guard against listing the same name twice per file.
+      #
       unused.each do |unused_def|
-        @unused_collection[unused_def[:file]] << unused_def[:name]
+        names = @unused_collection[unused_def[:file]]
+        next if names.include?(unused_def[:name])
+
+        names << unused_def[:name]
         if unused_def[:line]
           @source_locations["#{unused_def[:file]}:#{unused_def[:name]}"] = unused_def[:line]
         end

data/lib/keela/source.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Keela
+  # The concatenated source that usage detection is matched against, plus
+  # lazily-derived views of it.
+  #
+  # Built once and shared by every strategy in a run. Derived views are memoized
+  # because they cost about as much as a single usage check but are identical for
+  # every definition in the run.
+  #
+  class Source
+    # The ASCII block as a String#delete range. Built from its code points
+    # rather than written as a literal so that this file stays free of the
+    # control characters the range ends in.
+    ASCII_RANGE = [0x00, 0x7F].map { |code_point| code_point.chr(Encoding::UTF_8) }.join("-").freeze
+
+    attr_reader :text
+
+    def initialize(text)
+      @text = text
+    end
+
+    # Build from the scanner's { filename => [lines] } hash.
+    #
+    # Each file's lines are joined as-is, then a newline is guaranteed at the
+    # end of every non-empty file before files are concatenated. Without that
+    # boundary a file whose last line lacks a trailing newline glues onto the
+    # next file's first line, letting a usage match span a gap that exists in
+    # no single file (issue #83). Empty files contribute nothing.
+    #
+    def self.from_source_files(source_files)
+      new(source_files.values.map { |lines| terminate(lines.join) }.join)
+    end
+
+    def self.terminate(text)
+      return text if text.empty? || text.end_with?("\n")
+
+      "#{text}\n"
+    end
+    private_class_method :terminate
+
+    # Unicode full case folding of #text.
+    #
+    # Lets a strategy drop //i from its pattern and match case-sensitively
+    # against this instead, which avoids a sharp performance cliff.
+    #
+    # Only three ASCII fold targets have a non-ASCII source: U+017F folds to
+    # "s", U+212A folds to "k", and the eszett folds to "ss". So once the string
+    # being searched is not entirely 7-bit ASCII, a //i pattern whose literal
+    # BEGINS with "s" or "k" can no longer be found with a plain byte search,
+    # and takes 100x longer or worse. A literal with "s" in the middle is partly
+    # affected; one ending in "s" is not.
+    #
+    # A single non-ASCII character in any scanned file is enough to put a whole
+    # run on that path, and method names beginning with "s" are common, so this
+    # is easy to hit by accident.
+    #
+    # Full folding, not #downcase, because //i folds too: /strasse/i matches the
+    # eszett spelling of "STRASSE".
+    #
+    def folded
+      @folded ||= text.downcase(:fold)
+    end
+
+    # Whether matching a folded ASCII literal against #folded decides exactly
+    # what matching that literal against #text under //i would decide.
+    #
+    # Two things can break the equivalence, both only reachable with non-ASCII
+    # text:
+    #
+    # - A character that folds to more than one character (an eszett folds to
+    #   "ss") shifts everything after it, so a pattern's lookarounds see
+    #   different neighbours than they would in #text. Folding never maps a
+    #   character to nothing, so an unchanged total length proves every
+    #   character mapped to exactly one and positions are preserved.
+    #
+    # - A character that folds into ASCII (U+212A KELVIN SIGN folds to "k",
+    #   U+017F LATIN SMALL LETTER LONG S folds to "s") puts ASCII letters in the
+    #   folded view where #text had none. A guard such as (?<![a-z_]) would then
+    #   see a letter that //i never matches in #text.
+    #
+    # Neither occurs in ASCII-only text, so this holds for essentially all code.
+    # Strategies fall back to their //i pattern when it does not.
+    #
+    def fold_preserves_matching?
+      return @fold_preserves_matching if defined?(@fold_preserves_matching)
+
+      @fold_preserves_matching = folded.length == text.length && !non_ascii_folds_into_ascii?
+    end
+
+    private
+
+    def non_ascii_folds_into_ascii?
+      non_ascii_characters.downcase(:fold).match?(/[[:ascii:]]/)
+    end
+
+    # Only the non-ASCII characters of #text, which is a tiny string even for a
+    # large codebase.
+    #
+    # #delete with a character range rather than a regexp: a regexp scan of a
+    # string this size costs seconds, this costs milliseconds.
+    #
+    def non_ascii_characters
+      text.delete(ASCII_RANGE)
+    end
+  end
+end

data/lib/keela/strategies/attributes.rb

@@ -24,16 +24,36 @@ module Keela
       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))/
+        Regexp.union(*usage_regexes(name))
+      end
+
+      # The two ways an attribute can be used, as separate patterns:
+      # - bare reference: obj.name, name, self.name = value
+      # - instance variable: @name
+      #
+      # Excluded by the lookarounds:
+      # - symbol notation (:name)
+      # - the attr_* declaration itself
+      # - partial word matches (username must not match name)
+      #
+      # These are kept apart rather than combined into one alternation because
+      # an alternation has no single mandatory literal, so the regexp engine
+      # cannot fast-forward to a candidate position and scans the whole source
+      # instead. Checked separately, each pattern keeps its literal.
+      #
+      def usage_regexes(name)
+        quoted = Regexp.quote(name)
+
+        [
+          /(?<!:)(?<!attr_accessor\s)(?<!attr_reader\s)(?<!attr_writer\s)(?<![a-z_])#{quoted}(?!\w)/,
+          /@#{quoted}(?!\w)/
+        ]
+      end
+
+      # Equivalent to matching #usage_regex, because the caller asks only
+      # whether a match exists and not where it is.
+      def used?(name, source)
+        usage_regexes(name).any? { |regex| regex.match?(source.text) }
       end
 
       def skip_comments?

data/lib/keela/strategies/constants.rb

@@ -41,8 +41,12 @@ module Keela
         # 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*=(?!=))/
+        #   - definitions (followed by optional whitespace then =, but not == or =>)
+        #
+        # The pattern (?!\s*=(?![=>])) means:
+        #   - Don't match if followed by optional whitespace, then =
+        #   - UNLESS that = is followed by = (comparison) or > (hash rocket)
+        /(?<![A-Z0-9_])#{Regexp.quote(name)}(?![A-Z0-9_])(?!\s*=(?![=>]))/
       end
 
       def skip_comments?

data/lib/keela/strategies/delegations.rb

@@ -58,9 +58,36 @@ module Keela
         /(?<!:)(?<!delegate\s)(?<![a-z_])#{Regexp.quote(name)}(?!\w)/i
       end
 
+      def prepare(source)
+        source.fold_preserves_matching?
+      end
+
+      # Equivalent to matching #usage_regex, with the case folding moved from
+      # the pattern onto the source so that the pattern can drop //i. See
+      # Source#folded for why //i is the expensive part.
+      #
+      # The two decide alike because every guard in the pattern is
+      # case-symmetric: (?<!:) and (?!\w) do not involve case, and under //i
+      # both (?<![a-z_]) and (?<!delegate\s) already match their uppercase
+      # forms, which a folded source no longer contains. That argument needs an
+      # ASCII literal and a source whose folding preserves positions, so fall
+      # back to the //i pattern when either does not hold.
+      #
+      def used?(name, source)
+        return usage_regex(name).match?(source.text) unless name.ascii_only? && source.fold_preserves_matching?
+
+        folded_usage_regex(name).match?(source.folded)
+      end
+
       def skip_comments?
         true
       end
+
+      private
+
+      def folded_usage_regex(name)
+        /(?<!:)(?<!delegate\s)(?<![a-z_])#{Regexp.quote(name.downcase(:fold))}(?!\w)/
+      end
     end
   end
 end

data/lib/keela/strategies/i18n_keys.rb

@@ -15,9 +15,16 @@ module Keela
     #   - t(:key)
     #   - .human_attribute_name(:attr)
     #
-    # Note: Lazy lookup (t('.title') in views) is not yet supported.
+    # Pluralization keys (zero, one, two, few, many, other) are grouped:
+    # if t("items.count", count: n) is called, all siblings are considered used.
+    #
+    # Lazy lookup is supported: t('.title') in app/views/users/show.html.erb
+    # resolves to 'users.show.title'.
     #
     class I18nKeys < Strategy
+      PLURAL_SUFFIXES = %w[zero one two few many other].freeze
+      VIEW_PATH_REGEX = %r{(?:ee/)?app/views/(.+)\.html\.(?:erb|haml|slim)$}.freeze
+      LAZY_LOOKUP_REGEX = /(?:I18n\.)?t\s*\(\s*['"](\.[^'"]+)['"]/
       def name
         "i18n_keys"
       end
@@ -32,10 +39,19 @@ module Keela
         return [] unless File.exist?(filepath)
 
         content = YAML.load_file(filepath, permitted_classes: [Symbol]) || {}
-        flatten_keys(content).map do |key|
+        keys = 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 }
+          key.sub(/^[a-z]{2}(-[A-Z]{2})?\./, "")
+        end
+
+        # For pluralization keys, also add the parent key so that
+        # t("items.count", count: n) marks all siblings as used
+        parent_keys = keys.filter_map do |key|
+          parent_key_for_pluralization(key)
+        end.uniq
+
+        (keys + parent_keys).uniq.map do |key|
+          { name: key, file: filepath }
         end
       rescue Psych::SyntaxError => e
         warn "Warning: Could not parse #{filepath}: #{e.message}"
@@ -55,20 +71,86 @@ module Keela
         #   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"
+        # For pluralization keys, also match the parent key:
+        #   t("items.count", count: n) should match items.count.one, items.count.other, etc.
         quoted_name = Regexp.quote(name)
 
-        # Build pattern that matches the key in quotes or as a symbol
-        /(?:I18n\.)?t\s*\(\s*["':]+#{quoted_name}["']?\s*[,)]/
+        # Check if this is a pluralization key and build alternate pattern
+        parent_key = parent_key_for_pluralization(name)
+        if parent_key
+          quoted_parent = Regexp.quote(parent_key)
+          # Match either the exact key OR the parent key
+          /(?:I18n\.)?t\s*\(\s*["':]+(?:#{quoted_name}|#{quoted_parent})["']?\s*[,)]/
+        else
+          # Build pattern that matches the key in quotes or as a symbol
+          /(?:I18n\.)?t\s*\(\s*["':]+#{quoted_name}["']?\s*[,)]/
+        end
       end
 
       def skip_comments?
         true
       end
 
+      # Convert a view file path to its I18n prefix
+      # "app/views/users/show.html.erb" -> "users.show"
+      # "app/views/users/_form.html.erb" -> "users.form"
+      # "ee/app/views/users/show.html.erb" -> "users.show"
+      def view_path_to_prefix(path)
+        return nil unless path =~ VIEW_PATH_REGEX
+
+        view_path = Regexp.last_match(1)
+
+        # Split into parts and process
+        parts = view_path.split("/")
+
+        # Handle partials: _form -> form
+        parts[-1] = parts[-1].sub(/^_/, "")
+
+        parts.join(".")
+      end
+
+      # Extract lazy lookup keys from view content
+      # Returns array of keys like [".title", ".description"]
+      def extract_lazy_keys(content)
+        content.scan(LAZY_LOOKUP_REGEX).flatten
+      end
+
+      # Build a set of expanded lazy lookup keys from view files
+      # Called by the scanner to detect usage via lazy lookup
+      def additional_used_names(source_files)
+        expanded = Set.new
+
+        source_files.each do |filepath, lines|
+          prefix = view_path_to_prefix(filepath)
+          next unless prefix
+
+          content = lines.join("\n")
+          lazy_keys = extract_lazy_keys(content)
+
+          lazy_keys.each do |lazy_key|
+            # .title -> users.show.title
+            full_key = "#{prefix}#{lazy_key}"
+            expanded << full_key
+          end
+        end
+
+        expanded
+      end
+
       private
 
+      # Returns the parent key if this is a pluralization key, nil otherwise
+      # "items.count.one" -> "items.count"
+      # "users.show.title" -> nil
+      def parent_key_for_pluralization(key)
+        PLURAL_SUFFIXES.each do |suffix|
+          if key.end_with?(".#{suffix}")
+            return key.sub(/\.#{suffix}$/, "")
+          end
+        end
+        nil
+      end
+
       # Flatten nested hash to dot-notation keys
       # { "en" => { "users" => { "title" => "..." } } }
       # becomes ["en.users.title"]

data/lib/keela/strategies/methods.rb

@@ -24,9 +24,14 @@ module Keela
           # Setter method: match assignment usage
           /(?<!def |def self\.)#{method_name.chomp("=")}\W=*/
         else
-          # Regular method: match calls
-          # Exclude both "def foo" and "def self.foo" definitions
-          /(?<!def |def self\.)#{method_name}\W/
+          # Regular method: match calls and symbol references
+          # Matches:
+          #   - Direct calls: foo(arg), obj.foo
+          #   - Symbol references: :foo, :foo! (callbacks, send, etc.)
+          # Excludes:
+          #   - Definitions: def foo, def self.foo
+          #   - Partial matches: :foobar, before_foo (via word boundary lookbehind)
+          /(?<!def |def self\.)(?<![A-Za-z0-9_]):?#{method_name}(?:\W|$)/
         end
       end
 

data/lib/keela/strategies/partials.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Keela
+  module Strategies
+    # Detects unused Rails view partials (_*.html.{erb,haml,slim}) under
+    # app/views/** and ee/app/views/**.
+    #
+    # Definitions come from filenames, not file contents (like i18n_keys), so
+    # this strategy overrides #extract_definitions_from_file. The logical name
+    # is the path with the app/views/ (or ee/app/views/) prefix, leading _, and
+    # extension stripped: app/views/users/_form.html.erb -> "users/form".
+    #
+    # Usage is detected two ways:
+    #   1. Explicit paths via #usage_regex: render "users/form",
+    #      render partial: "users/form", render layout: "users/form". layout:
+    #      renders a partial as a layout, so it counts as a use.
+    #   2. Relative (bareword) renders via #additional_used_names: render "form"
+    #      (and render partial:/layout: "form") is resolved against the CALLING
+    #      file's directory. In a view, the directory is the view's own dir; in a
+    #      controller, it is derived from the controller name
+    #      (users_controller.rb -> users).
+    #
+    # Known limitations (not implemented, by design):
+    #   - Collection/object render (render @users -> users/_user) is NOT
+    #     resolved. A singularize heuristic could silently hide dead code on a
+    #     wrong guess, so these partials may be reported as unused; suppress via
+    #     the baseline.
+    #   - Dynamic render with a variable (render partial_name) is statically
+    #     unsolvable, so it is not resolved (same posture as send for methods).
+    #   - shared/* partials are treated like any other partial; false positives
+    #     belong in the baseline rather than a hard-coded skip.
+    #
+    class Partials < Strategy
+      # The intermediate directory is optional so a partial directly under
+      # app/views/ (app/views/_foo.html.erb) matches too; without this the file
+      # filter and #extract_definitions_from_file disagree and root partials are
+      # silently skipped.
+      #
+      DEFINITION_FILE_REGEX = %r{(?:ee/)?app/views/(?:.*/)?_[^/]+\.html\.(?:erb|haml|slim)$}.freeze
+
+      # Captures the path under app/views/ so we can derive a partial name:
+      # app/views/users/_form.html.erb -> "users/_form"
+      #
+      NAME_PATH_REGEX = %r{(?:ee/)?app/views/(.+)\.html\.(?:erb|haml|slim)$}.freeze
+
+      # The directory of a calling VIEW, used to resolve bareword renders.
+      # app/views/users/show.html.erb -> "users"
+      #
+      VIEW_DIR_REGEX = %r{(?:ee/)?app/views/(.+)/[^/]+\.html\.(?:erb|haml|slim)$}.freeze
+
+      # A controller path, used to derive the implicit view directory for
+      # bareword renders made from controllers.
+      # app/controllers/users_controller.rb -> "users"
+      # app/controllers/admin/users_controller.rb -> "admin/users"
+      #
+      CONTROLLER_REGEX = %r{(?:ee/)?app/controllers/(.+)_controller\.rb$}.freeze
+
+      # The render family we recognize: render, plus render_to_string and
+      # render_to_body, which render partials the same way (Rails/GitLab use both
+      # off-request, e.g. in mailers and background jobs). An optional opening
+      # paren after the method lets us match both the no-parens same-line form
+      # (render_to_string partial: "x/y") and the contiguous parens form
+      # (render_to_string(partial: "x/y")). Multi-line detached partial: args are
+      # out of scope; see issue #84.
+      #
+      RENDER_METHOD = /render(?:_to_string|_to_body)?\s*\(?\s*/
+
+      # A bareword render: render "form" / render 'form' / render partial: "form"
+      # / render layout: "form". layout: renders a partial as a layout, so it
+      # counts as a use just like partial:. Only barewords (no slash) are
+      # captured here; paths with a slash are handled by #usage_regex.
+      #
+      # The leading negative lookbehind anchors the method on its left so that
+      # prerender/foo_render(_to_string) do not count as a render.
+      #
+      # This uses RENDER_METHOD, not #render_method_pattern, on purpose:
+      # configured render_helpers must never enable bareword-relative resolution.
+      # A bare 'form' passed to an arbitrary app helper is too ambiguous to
+      # safely resolve against the caller's directory.
+      #
+      BAREWORD_RENDER_REGEX = /(?<!\w)#{RENDER_METHOD}(?:(?:partial|layout):\s*)?["']([^"'\/]+)["']/
+
+      def name
+        "partials"
+      end
+
+      def default_definition_file_pattern
+        DEFINITION_FILE_REGEX
+      end
+
+      # Definitions come from filenames, not contents.
+      def extract_definitions_from_file(filepath, _lines)
+        return [] unless filepath =~ NAME_PATH_REGEX
+
+        # "users/_form" -> "users/form"; "_form" -> "form"
+        name = Regexp.last_match(1).sub(%r{(^|/)_}, '\1')
+
+        [{ name: name, file: filepath }]
+      end
+
+      def extract_definition(_line)
+        # Not used; definitions come from #extract_definitions_from_file.
+        nil
+      end
+
+      def usage_regex(name)
+        # render "users/form", render 'users/form',
+        # render partial: "users/form", render layout: "users/form"
+        # (single/double quotes, tolerant space). layout: renders the partial as
+        # a layout, so it counts as a use. render_to_string / render_to_body are
+        # recognized too via RENDER_METHOD.
+        #
+        # The leading negative lookbehind anchors the method on its left so that
+        # prerender/foo_render do not count as a render.
+        #
+        # Configured render_helpers extend the method token here (explicit-path
+        # matching only) via #render_method_pattern.
+        #
+        /(?<!\w)#{render_method_pattern}(?:(?:partial|layout):\s*)?["']#{Regexp.quote(name)}["']/
+      end
+
+      def skip_comments?
+        true
+      end
+
+      # Build the comment-stripped view once in the parent so workers inherit it
+      # copy-on-write instead of each rebuilding a codebase-sized string.
+      #
+      def prepare(source)
+        @stripped_source = source
+        @stripped_text = strip_erb_comments(source.text)
+      end
+
+      # Match against a view with single-line ERB comments removed, so a render
+      # inside <%# ... %> does not count as a usage. Falls back to stripping on
+      # demand if #prepare was not run for this source (defensive: #used? can be
+      # called directly in tests, or on a different source than #prepare saw).
+      #
+      def used?(name, source)
+        usage_regex(name).match?(stripped_text_for(source))
+      end
+
+      # Resolve bareword renders against the calling file's directory so that a
+      # short render marks the fully-qualified partial used.
+      #
+      def additional_used_names(source_files)
+        used = Set.new
+
+        source_files.each do |filepath, lines|
+          content = strip_erb_comments(lines.join("\n"))
+
+          # Positional-underscore paths are absolute logical names, so they are
+          # resolved regardless of the caller's directory. "shared/notes/_note"
+          # -> "shared/notes/note" (strip the leading _ of the basename only).
+          #
+          content.scan(positional_underscore_regex).each do |(path)|
+            used << path.sub(%r{/_([^/]+)$}, '/\1')
+          end
+
+          dir = caller_directory(filepath)
+          next unless dir
+
+          content.scan(BAREWORD_RENDER_REGEX).each do |(bareword)|
+            used << "#{dir}/#{bareword}"
+          end
+        end
+
+        used
+      end
+
+      private
+
+      # The comment-stripped text for +source+, using the view #prepare built
+      # when it saw this same source, otherwise stripping on demand.
+      #
+      def stripped_text_for(source)
+        return @stripped_text if defined?(@stripped_source) && @stripped_source.equal?(source)
+
+        strip_erb_comments(source.text)
+      end
+
+      # Blank out single-line ERB comment tags so renders inside them are not
+      # matched. Matches <% (optional -) then #, up to %> (optional -), on one
+      # line; a <%= output %> or <% code %> tag has no # after <% and is left
+      # intact. Multi-line ERB comments and HAML comments are out of scope: the
+      # dot does not cross newlines, so they are not matched.
+      #
+      # Replaced with same-length spaces (via the block form, so the length is
+      # the matched span's, not a global) to preserve positions and line
+      # structure.
+      #
+      def strip_erb_comments(text)
+        text.gsub(/<%\s*-?\s*#.*?-?\s*%>/) { |match| " " * match.length }
+      end
+
+      # The directory a bareword render resolves against: the view's own dir, or
+      # the controller-derived dir. Returns nil for files that render nothing
+      # resolvable this way.
+      #
+      def caller_directory(filepath)
+        return Regexp.last_match(1) if filepath =~ VIEW_DIR_REGEX
+        return Regexp.last_match(1) if filepath =~ CONTROLLER_REGEX
+
+        nil
+      end
+
+      # A positional string whose basename starts with _ names a partial file
+      # directly: render_to_string("shared/notes/_note") uses shared/notes/note.
+      # There is no partial:/layout: keyword here, so it is handled separately
+      # from #usage_regex and the bareword path. Only the leading _ of the
+      # BASENAME is stripped; intermediate path segments are kept verbatim.
+      #
+      # A method (not a constant) so configured render_helpers extend the
+      # recognized method token via #render_method_pattern.
+      #
+      def positional_underscore_regex
+        /(?<!\w)#{render_method_pattern}["']([^"']*\/_[^"'\/]+)["']/
+      end
+
+      # The recognized render-method token for EXPLICIT-PATH matching. Defaults
+      # to RENDER_METHOD; when the partials strategy is configured with
+      # render_helpers, each helper name is added to the alternation so an
+      # app-specific helper that renders a partial from a string path is treated
+      # like render for explicit-path detection.
+      #
+      #   strategies:
+      #     partials:
+      #       render_helpers:
+      #         - view_to_html_string
+      #         - tabs_json
+      #
+      # Helper names are Regexp.quote'd so metacharacters match literally, and
+      # the caller keeps the (?<!\w) left-anchor so tabs_json does not match
+      # my_tabs_json. Returns RENDER_METHOD unchanged when none are configured,
+      # so default behavior is byte-identical to today.
+      #
+      def render_method_pattern
+        helpers = Keela.configuration.options_for(name)["render_helpers"]
+        return RENDER_METHOD unless helpers.is_a?(Array) && helpers.any?
+
+        quoted = helpers.map { |h| Regexp.quote(h.to_s) }
+        /(?:render(?:_to_string|_to_body)?|#{quoted.join('|')})\s*\(?\s*/
+      end
+    end
+  end
+end

data/lib/keela/strategy.rb

@@ -43,6 +43,26 @@ module Keela
       raise NotImplementedError, "#{self.class} must implement #usage_regex"
     end
 
+    # Whether +name+ is used anywhere in +source+ (a Keela::Source).
+    #
+    # Defaults to matching #usage_regex against the raw source. Override when an
+    # equivalent formulation is cheaper to match. An override must decide
+    # exactly what #usage_regex would decide.
+    #
+    def used?(name, source)
+      usage_regex(name).match?(source.text)
+    end
+
+    # Force any derived Keela::Source view this strategy needs in #used?.
+    #
+    # The scanner calls this once before it forks its workers, so the views are
+    # built in the parent and inherited copy-on-write rather than being rebuilt
+    # by every worker.
+    #
+    def prepare(_source)
+      nil
+    end
+
     # Whether to skip lines that start with # (comments)
     def skip_comments?
       false
@@ -55,6 +75,14 @@ module Keela
       nil
     end
 
+    # Override this method for strategies that need to detect usage through
+    # patterns that can't be expressed as a simple regex (e.g., I18n lazy lookup).
+    # Returns a Set of definition names that are considered "used".
+    # Called with the source_files hash { filepath => [lines] }.
+    def additional_used_names(_source_files)
+      Set.new
+    end
+
     private
 
     def configured_pattern

data/lib/keela/version.rb

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

data/lib/keela.rb

@@ -3,6 +3,7 @@
 require_relative "keela/version"
 require_relative "keela/configuration"
 require_relative "keela/config_file"
+require_relative "keela/source"
 require_relative "keela/strategy"
 require_relative "keela/strategies/methods"
 require_relative "keela/strategies/scopes"
@@ -10,6 +11,7 @@ require_relative "keela/strategies/constants"
 require_relative "keela/strategies/delegations"
 require_relative "keela/strategies/attributes"
 require_relative "keela/strategies/i18n_keys"
+require_relative "keela/strategies/partials"
 require_relative "keela/reporter"
 require_relative "keela/baseline"
 require_relative "keela/scanner"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keela
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kerri Miller
@@ -88,11 +88,13 @@ files:
 - lib/keela/formatters/toon.rb
 - lib/keela/reporter.rb
 - lib/keela/scanner.rb
+- lib/keela/source.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/partials.rb
 - lib/keela/strategies/scopes.rb
 - lib/keela/strategy.rb
 - lib/keela/version.rb
@@ -111,7 +113,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="