keela 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b1c9fad8b959b91c3af1518da72d36f9f82bd649b4c21a6a0cf261246cbbcdb
-  data.tar.gz: 24c7b946587cb844ae9c08c921ffecacfb8b262404b2c177f0368d803cc52861
+  metadata.gz: 40ac5a23ccbc726eeea66f99e4a6d9cb109360b987daa26e54c43c6d566c448b
+  data.tar.gz: 5c6b44f161613c7dea1aae79490918ce8233572345863febcf34a9417710bf60
 SHA512:
-  metadata.gz: e0fcd131e331240b852f7d657113aa0e9610aa4a7dd465b78576478c11abdeca5cd4140c9037cbbd378f53e23e4137d6a255eeb8d28950f0f82f6ad0eeabc7fd
-  data.tar.gz: 7d71ea4b1a2c601f0aba8901fbe31f95ba055eb784614213afa386321e096bb2364ecd832b60356f08c8cc42ed2e07e9bdcfc4c3a794fe218931834ac7df7c39
+  metadata.gz: 69de532e979e8bb052281e2fc58f2c4c6b9039f6a157b88139badff12c4f48abc0df134c817a44f6a6b1dcad131c2fe86c7a667fd51e36d1314184d5444b620d
+  data.tar.gz: fc86b2efb01f42db61d20f2a65d029082802a09c480bc6aeda5a6739f4b13c4ebfbb5d061f98520bb0248d10d15b9f4237bd18b8a5a0925b384553915d5f6ed4

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-10-06
+
+### Changed
+
+- **The `partials` strategy is dramatically faster on large codebases, up to ~27× less CPU.** It now collects every rendered partial in a single pass over the source instead of re-scanning the whole codebase once per partial. Measured against a large reference Rails monolith, partials went from the slowest strategy to effectively free, and no longer meaningfully slows a combined `--type all,partials` run. The report is unchanged ([#96](https://github.com/kerrizor/keela/pull/96))
+
+## [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

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,10 +194,11 @@ 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)
 
@@ -208,9 +213,22 @@ The following patterns ARE now supported:
 
 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**.
+Keela uses static analysis: it reads your code without executing it. This means some patterns are **fundamentally undetectable**.
 
 ### What Keela CAN Detect
 
@@ -233,17 +251,17 @@ respond_to?(:optional_method)
 **Dynamic dispatch** with interpolation or variables cannot be analyzed statically:
 
 ```ruby
-# ❌ Interpolated symbols — what method does this call?
+# ❌ Interpolated symbols: what method does this call?
 public_send(:"add_#{role}", user)
 
-# ❌ Variable method names — could be anything
+# ❌ 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.
+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
 
@@ -313,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:
@@ -542,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,24 +208,52 @@ 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)
 
+      # A strategy whose #additional_used_names enumerates every used name in one
+      # pass (e.g. partials) decides purely by Set membership. Skip building the
+      # derived source views and the per-definition #used? scan entirely: that
+      # per-definition scan is O(N x whole-codebase) and is the hot path we are
+      # avoiding here.
+      #
+      if strategy.detects_all_usage?
+        unused = definitions.reject { |definition| additional_used.include?(definition[:name]) }
+        return record_unused(unused)
+      end
+
+      # 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|
         # Check if marked as used by additional detection
         next [] if additional_used.include?(definition[:name])
 
-        regex = strategy.usage_regex(definition[:name])
-        regex.match?(source_code) ? [] : definition
+        strategy.used?(definition[:name], source) ? [] : definition
       end
 
+      record_unused(unused)
+    end
+
+    # Collect the unused definitions into @unused_collection / @source_locations.
+    #
+    # 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.
+    #
+    def record_unused(unused)
       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/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/partials.rb

@@ -0,0 +1,318 @@
+# 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
+
+      # A view directly under app/views/ with no intermediate directory, e.g.
+      # app/views/index.html.erb. Its caller directory is the root (""), so a
+      # bareword render "foo" from here resolves to the root-level partial "foo".
+      # VIEW_DIR_REGEX requires an intermediate dir and so never matches these.
+      #
+      ROOT_VIEW_REGEX = %r{(?:ee/)?app/views/[^/]+\.html\.(?:erb|haml|slim)$}.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
+
+      # #additional_used_names collects every rendered partial name in a single
+      # pass, so the scanner decides by Set membership and skips the per-definition
+      # #used? scan. See the note on #additional_used_names.
+      #
+      def detects_all_usage?
+        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).
+      #
+      # Retained as the Strategy contract and for direct callers (tests), but the
+      # scanner no longer drives detection through it: #additional_used_names now
+      # collects every used name in a single pass over the corpus, so the scanner
+      # decides via that Set instead of calling #used? per definition. See the
+      # note on #additional_used_names.
+      #
+      def used?(name, source)
+        usage_regex(name).match?(stripped_text_for(source))
+      end
+
+      # The set of partial names used anywhere in +source_files+, collected in a
+      # SINGLE pass over the corpus.
+      #
+      # This is the whole-run detection path for partials. The scanner checks a
+      # definition against this Set and never calls #used? for a name that is in
+      # it, so extracting every used name here (not just the bareword/positional
+      # ones) turns detection from O(N_partials x codebase) per-definition regex
+      # scans into O(codebase + N_partials): we scan each file once, collect the
+      # rendered names, then membership-test each definition. This is the fix for
+      # the partials strategy being CPU-bound on large codebases.
+      #
+      # Three render forms are collected, each the single-pass twin of a branch
+      # that used to be matched per-definition:
+      #
+      #   1. Explicit slashed paths (the #usage_regex cases): render "users/form",
+      #      render partial:/layout: "users/form", render_to_string/_to_body, and
+      #      configured render_helpers. Captured verbatim as the logical name.
+      #   2. Positional-underscore paths: render "shared/notes/_note" names the
+      #      file directly -> "shared/notes/note" (strip the basename's leading _).
+      #   3. Barewords resolved against the caller's directory: render "form" in
+      #      app/views/users/* or users_controller.rb -> "users/form".
+      #
+      # All three share the comment-stripped content and the same left word-anchor
+      # and render-method rules as #usage_regex, so the collected strings are
+      # exactly what the per-name regex would have matched.
+      #
+      def additional_used_names(source_files)
+        used = Set.new
+
+        source_files.each do |filepath, lines|
+          content = strip_erb_comments(lines.join("\n"))
+
+          # Explicit slashed paths: the single-pass twin of #usage_regex. A
+          # basename leading _ is stripped so "users/_form" and "users/form"
+          # agree with the positional-underscore form and with definition names.
+          #
+          content.scan(explicit_path_regex).each do |(path)|
+            used << path.sub(%r{(^|/)_([^/]+)$}, '\1\2')
+          end
+
+          # 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)|
+            # dir is "" for a root-level view, so join without a separator to
+            # resolve render "foo" -> "foo" rather than "/foo".
+            #
+            used << (dir.empty? ? bareword : "#{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, the
+      # controller-derived dir, or "" for a root-level view (render "foo" from
+      # app/views/index.html.erb resolves to the root partial "foo"). 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
+        return "" if filepath =~ ROOT_VIEW_REGEX
+
+        nil
+      end
+
+      # The single-pass twin of #usage_regex: instead of matching one known name,
+      # CAPTURE the rendered path so one scan collects every explicitly-rendered
+      # partial. Same left word-anchor, same optional partial:/layout: keyword,
+      # same #render_method_pattern (so configured render_helpers are honored),
+      # as #usage_regex.
+      #
+      # The captured path must contain at least one slash: barewords (no slash)
+      # are resolved relative to the caller by #additional_used_names via
+      # BAREWORD_RENDER_REGEX, exactly as #usage_regex only ever matched slashed
+      # logical names. Requiring a slash here keeps the two paths disjoint.
+      #
+      def explicit_path_regex
+        %r{(?<!\w)#{render_method_pattern}(?:(?:partial|layout):\s*)?["']([^"'/]+(?:/[^"'/]+)+)["']}
+      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
@@ -63,6 +83,20 @@ module Keela
       Set.new
     end
 
+    # Whether #additional_used_names already collects EVERY used name in a single
+    # pass, making the per-definition #used? scan redundant.
+    #
+    # Defaults to false: the scanner checks #additional_used_names first and then
+    # falls back to #used? per definition. A strategy that returns true here is
+    # declaring its #additional_used_names is complete, so the scanner skips the
+    # per-definition scan entirely. This turns O(N_definitions x codebase) regex
+    # scanning into a single O(codebase) pass plus Set membership tests, for
+    # strategies whose usage can be enumerated in one sweep (e.g. partials).
+    #
+    def detects_all_usage?
+      false
+    end
+
     private
 
     def configured_pattern

data/lib/keela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Keela
-  VERSION = "0.4.1"
+  VERSION = "0.5.1"
 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.1
+  version: 0.5.1
 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:
   - - ">="