rubocop-fourshark 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 202b492f9486b827fd67079c3a7bb113bb194a87fd968646eebbf30b881140cc
+  data.tar.gz: 20f9b022eb67bad4c30fe2295c3d56a30c027594c15142303dcfe707c5390f85
+SHA512:
+  metadata.gz: 6cd1bc1df875dc06da1fbe6091e896afe434e99f13e64c3f564e5ac43bcf23ac5cb5a4e3e0ff6792829df9df109ec331066fac1395472b536372ced8dd025d65
+  data.tar.gz: f62cfe9f582d0ef9108800eef733aa8957852b7183cc3bee53f7182680a51ceda57293d19137f4baf9badb345cf9add64f9a15643734d0b515672188026435a9

data/.ruby-gemset

@@ -0,0 +1 @@
+rubocop-fourshark

data/.ruby-version

@@ -0,0 +1 @@
+4.0.5

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+## [0.2.1] - 2026-05-29
+
+### Fixed
+
+- `RSpec/InverseOfMatcher` no longer crashes RuboCop — it classifies root vs subclass statically (reading the model file) instead of loading the model class
+
+## [0.2.0] - 2026-05-29
+
+### Added
+
+- Disable stock `Rails/InverseOf` and `Style/SafeNavigation`, which are superseded or contradicted by 4Shark cops
+
+### Changed
+
+- Cop names aligned with RuboCop naming conventions
+- `RSpec/LetNotInContext` renamed to `RSpec/OverwrittenLet` and relaxed to flag only a `let` that overrides one from an outer scope
+
+## [0.1.0] - 2026-05-29
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"rubocop-fourshark" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["plribeiro3000@gmail.com"](mailto:"plribeiro3000@gmail.com").

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,129 @@
+# rubocop-fourshark
+
+A RuboCop extension that encodes 4Shark's Ruby, Rails, and RSpec conventions as enforceable cops.
+
+## Why this gem exists
+
+4Shark has its own definition of good Ruby/Rails/RSpec code. Two needs the stock RuboCop ecosystem does not cover on its own:
+
+1. **Conventions stock RuboCop has no cop for.** Rules like "every association declares `inverse_of`", "`belongs_to` is `optional: true` with manual presence validation", or "no associations inside factories" are 4Shark decisions with no equivalent in `rubocop-rails`/`rubocop-rspec`. This gem ships them as real cops.
+2. **Stock conventions 4Shark deliberately rejects.** RuboCop's defaults nudge toward patterns 4Shark does not want — safe navigation (`&.`) and `try` being the clearest examples. Rather than each repo re-litigating the same `.rubocop.yml` overrides, the position is made enforceable in one place: a custom cop that flags the rejected construct.
+
+The goal is a single dependency that every 4Shark Ruby repository inherits, so the conventions are identical across all of them — and a new convention is added once, here, instead of in each repository.
+
+## Installation
+
+The gem is published to RubyGems. Add it to the application's `Gemfile`:
+
+```ruby
+gem 'rubocop-fourshark', require: false
+```
+
+or:
+
+```bash
+bundle add rubocop-fourshark --require=false
+```
+
+Then activate it as a plugin in `.rubocop.yml`:
+
+```yaml
+plugins:
+  - rubocop-fourshark
+```
+
+Activating the plugin auto-loads the gem's `config/default.yml`, which enables every cop below.
+
+> **Note — plugins are not transitively activated.** `rubocop-fourshark` depends on the upstream plugins (`rubocop-rails`, `rubocop-rspec`, `rubocop-rspec_rails`, `rubocop-performance`, `rubocop-factory_bot`), but `lint_roller` does not auto-activate a plugin's dependencies. Each repo still lists the upstream plugins it uses in its own `plugins:` block.
+
+## Cops
+
+All cops are **enabled by default** the moment the plugin is activated. Cops scoped to a path (models, specs, factories) only run on files matching that path. Each cop's source file under [`lib/rubocop/cop`](lib/rubocop/cop) carries runnable `@example` blocks showing the bad/good shapes.
+
+### Naming
+
+Cop names follow RuboCop's empirical convention — a noun phrase describing the construct or smell, no `Disallow*`/`No*` prefixes — with two deliberate exceptions:
+
+- **`Style/DisallowSafeNavigation` / `Style/DisallowTry`** keep the `Disallow*` prefix. RuboCop has no idiom for "forbid a construct it otherwise permits" (it uses `EnforcedStyle` on one cop), and the natural noun name is already taken by a stock cop with the *opposite* intent — `Style/SafeNavigation` *converts to* `&.`. `Disallow*` is unambiguous and collision-free.
+- **`Rails/MandatoryInverseOf`** is named to distinguish it from stock `Rails/InverseOf`, which only flags associations where Active Record cannot auto-detect the inverse. Ours mandates `inverse_of` on *every* association — a strict superset — so the gem disables the stock cop (below).
+
+### Stock cops disabled
+
+Where a 4Shark cop supersedes or contradicts a stock cop, `config/default.yml` turns the stock one off:
+
+| Disabled stock cop | Why |
+|---|---|
+| `Rails/InverseOf` | superseded by `Rails/MandatoryInverseOf` (covers its cases and more) |
+| `Style/SafeNavigation` | contradicts `Style/DisallowSafeNavigation` — it pushes `&.`, we forbid it |
+
+### Style
+
+| Cop | Intent |
+|---|---|
+| `Style/DisallowSafeNavigation` | Flags safe navigation (`&.`). 4Shark rejects it — a `&.` chain silently swallows a `nil` that usually signals a real bug. Use an explicit conditional so the `nil` case is handled on purpose. |
+| `Style/DisallowTry` | Flags `try` / `try!`. Same rationale — it hides the `nil`/missing-method case instead of handling it explicitly. |
+
+### Layout
+
+| Cop | Intent |
+|---|---|
+| `Layout/MultilineStatementSpacing` | Requires a blank line between two consecutive statements when either spans multiple lines, so multi-line statements read as distinct units. |
+
+### Rails (models)
+
+| Cop | Intent |
+|---|---|
+| `Rails/MandatoryInverseOf` | Every association (`belongs_to`/`has_many`/`has_one`) must declare `inverse_of`, so both sides resolve to the same in-memory object. Stricter than stock `Rails/InverseOf`, which only fires when AR can't auto-detect the inverse. Scoped to `app/models`. |
+| `Rails/BidirectionalAssociation` | An association must be declared on both sides of the relationship — the opposite model must carry the matching association. Scoped to `app/models`. |
+| `Rails/OptionalBelongsTo` | `belongs_to` must be `optional: true` (see the rationale below). Scoped to `app/models`. |
+| `Rails/OrderedMacros` | Same-kind class macros (associations, validations, scopes) must be sorted alphabetically within their group. Scoped to `app/models`. |
+
+### RSpec (specs)
+
+| Cop | Intent |
+|---|---|
+| `RSpec/InverseOfMatcher` | Root models must assert `.inverse_of` in association specs; subclasses must not (it belongs to the parent). Scoped to `spec/models`. |
+| `RSpec/OverwrittenLet` | A `let`/`let!` must not override one defined in an outer example group — shadowing makes it ambiguous which value applies. Scenario-specific `let`s, and the same name across sibling contexts, are fine. |
+| `RSpec/ConditionalInLet` | A `let` must not contain conditional logic (`if`/`case`) — branch with separate `context`s instead. Ternaries are allowed. |
+| `RSpec/FactoryBotInBefore` | Object creation belongs in `let`, not `before`. `before` is for actions, not for building the subjects under test. |
+
+### FactoryBot (factories)
+
+| Cop | Intent |
+|---|---|
+| `FactoryBot/AssociationInFactory` | No associations declared inside a factory — they trigger cascading object creation and callbacks. Set the association manually in the spec. Scoped to `spec/factories`. |
+
+The full rationale behind each convention (the "why this is good 4Shark code") lives in the team's engineering docs; this README states the intent each cop enforces. One convention deviates from a safe Rails default and is worth spelling out — see below.
+
+### Why `belongs_to` is `optional: true` by default
+
+4Shark never exposes internal database IDs across its API and upload boundaries. Clients send their **own** identifiers; each external identifier is mapped to its internal record (a surrogate-key cross-reference), and that lookup is scoped to the client's account — so it confirms both that the record **exists** and that it **belongs to the caller**, in a single step.
+
+By the time an association is assigned, existence and ownership have already been verified — more strictly than Rails would. Rails' default `belongs_to` (`optional: false`) then adds an existence `SELECT` per record on top of that: redundant work, and at high API throughput a measurable per-request cost.
+
+So the convention is:
+
+- `belongs_to` is always declared `optional: true` (enforced by `Rails/OptionalBelongsTo`), turning off Rails' automatic existence validation.
+- Presence is validated manually with `validates :x_id, presence: true` **where the business rule requires it** — case by case, not globally (which is why no cop enforces the presence side).
+
+A deliberate performance trade-off backed by the external-identifier mapping — not an omission.
+
+## Development
+
+After checking out the repo, install dependencies and run the suite:
+
+```bash
+bundle install
+bundle exec rspec      # cop specs
+bundle exec rubocop    # self-lint (includes rubocop-internal_affairs)
+```
+
+Each new cop ships with a spec (`expect_offense` / `expect_no_offenses`) and a `config/default.yml` entry.
+
+## Releasing
+
+This project does **not** use HubFlow. Releases are cut from `main`: feature branches merge into `main` via PR, the version is bumped, a `vX.Y.Z` tag is created from `main`, and the gem is published to RubyGems. Consuming repos depend on the published version in their `Gemfile`.
+
+## License
+
+Released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc 'Generate a new cop with a template'
+
+task :new_cop, [:cop] do |_task, args|
+  require 'rubocop'
+
+  cop_name = args.fetch(:cop) do
+    warn 'usage: bundle exec rake new_cop[Department/Name]'
+    exit!
+  end
+
+  generator = RuboCop::Cop::Generator.new(cop_name)
+
+  generator.write_source
+  generator.write_spec
+  generator.inject_require(root_file_path: 'lib/rubocop/cop/fourshark_cops.rb')
+  generator.inject_config(config_file_path: 'config/default.yml')
+
+  puts generator.todo
+end

data/config/default.yml

@@ -0,0 +1,96 @@
+# rubocop-fourshark — custom cops (4Shark conventions).
+# Cops live in their natural stock departments (Style/Rails/RSpec/Layout/FactoryBot)
+# so the names read like any other cop. Where a 4Shark cop supersedes or
+# contradicts a stock cop, the stock cop is disabled here (see the bottom block).
+
+Layout/MultilineStatementSpacing:
+  Description: 'Add a blank line between consecutive statements when either spans multiple lines.'
+  Enabled: true
+  VersionAdded: '0.2.0'
+
+Style/DisallowSafeNavigation:
+  Description: 'Do not use safe navigation (`&.`). Use explicit conditionals instead.'
+  Enabled: true
+  VersionAdded: '0.1.0'
+
+Style/DisallowTry:
+  Description: 'Do not use `try` or `try!`. Use explicit conditionals instead.'
+  Enabled: true
+  VersionAdded: '0.1.0'
+
+Rails/MandatoryInverseOf:
+  Description: 'Every association must declare `inverse_of` (stricter than stock `Rails/InverseOf`).'
+  Enabled: true
+  Include:
+    - 'app/models/**/*.rb'
+  Exclude:
+    - 'app/serializers/**/*.rb'
+  VersionAdded: '0.2.0'
+
+Rails/BidirectionalAssociation:
+  Description: 'Associations must be declared on both sides of the relationship.'
+  Enabled: true
+  Include:
+    - 'app/models/**/*.rb'
+  Exclude:
+    - 'app/serializers/**/*.rb'
+  VersionAdded: '0.2.0'
+
+Rails/OptionalBelongsTo:
+  Description: 'Declare `belongs_to` with `optional: true` and validate presence manually.'
+  Enabled: true
+  Include:
+    - 'app/models/**/*.rb'
+  VersionAdded: '0.1.0'
+
+Rails/OrderedMacros:
+  Description: 'Sort same-kind class macro declarations (associations, validations, scopes) alphabetically.'
+  Enabled: true
+  Include:
+    - 'app/models/**/*.rb'
+  VersionAdded: '0.2.0'
+
+RSpec/InverseOfMatcher:
+  Description: 'Root models must include `.inverse_of` in association specs; subclasses must not.'
+  Enabled: true
+  Include:
+    - 'spec/models/**/*_spec.rb'
+  VersionAdded: '0.2.0'
+
+RSpec/OverwrittenLet:
+  Description: 'Do not override a `let` defined in an outer example group.'
+  Enabled: true
+  Include:
+    - 'spec/**/*_spec.rb'
+  VersionAdded: '0.2.0'
+
+RSpec/ConditionalInLet:
+  Description: 'Do not put conditional logic in a `let` — use separate contexts.'
+  Enabled: true
+  Include:
+    - 'spec/**/*_spec.rb'
+  VersionAdded: '0.2.0'
+
+RSpec/FactoryBotInBefore:
+  Description: 'Do not create objects in `before` — use `let` for object creation.'
+  Enabled: true
+  Include:
+    - 'spec/**/*_spec.rb'
+  VersionAdded: '0.2.0'
+
+FactoryBot/AssociationInFactory:
+  Description: 'Do not declare associations in factories — set them manually in the spec.'
+  Enabled: true
+  Include:
+    - 'spec/factories/**/*.rb'
+  VersionAdded: '0.2.0'
+
+# Stock cops disabled because a 4Shark cop supersedes or contradicts them.
+# `Rails/InverseOf` only flags when AR can't auto-detect the inverse;
+# `Rails/MandatoryInverseOf` covers it and more.
+# `Style/SafeNavigation` converts to `&.`, the opposite of `Style/DisallowSafeNavigation`.
+Rails/InverseOf:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: false

data/lib/rubocop/cop/factory_bot/association_in_factory.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'rubocop'
+
+module RuboCop
+  module Cop
+    module FactoryBot
+      # Forbids declaring associations inside a `factory`/`trait` block. An
+      # association is a bare attribute call with no value (e.g. `customer`),
+      # which triggers cascading object creation and callbacks. Set the
+      # association manually in the spec instead.
+      #
+      # @example
+      #   # bad
+      #   factory :payment do
+      #     amount { 100.0 }
+      #     customer
+      #   end
+      #
+      #   # good
+      #   factory :payment do
+      #     amount { 100.0 }
+      #   end
+      #
+      class AssociationInFactory < ::RuboCop::Cop::Base
+        MSG = 'Do not declare associations in factories — set them manually in the spec.'
+
+        CONTAINER_METHODS = %i[factory trait].freeze
+        # FactoryBot DSL methods that are bare calls but are NOT associations.
+        DSL_KEYWORDS = %i[skip_create initialize_with].freeze
+
+        def on_block(node)
+          return unless container_block?(node)
+
+          body = node.body
+          return unless body
+
+          statements = body.begin_type? ? body.children : [body]
+
+          statements.each do |statement|
+            add_offense(statement.loc.selector) if association_call?(statement)
+          end
+        end
+
+        alias on_numblock on_block
+        alias on_itblock on_block
+
+        private
+
+        def container_block?(node)
+          send = node.send_node
+          CONTAINER_METHODS.include?(send.method_name) && send.receiver.nil?
+        end
+
+        # A bare attribute call (no receiver, no arguments, no block) inside a
+        # factory body is an implicit association.
+        def association_call?(node)
+          return false unless node.is_a?(::RuboCop::AST::Node) && node.send_type?
+          return false unless node.receiver.nil? && node.arguments.empty?
+          return false if DSL_KEYWORDS.include?(node.method_name)
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/fourshark_cops.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'factory_bot/association_in_factory'
+require_relative 'layout/multiline_statement_spacing'
+require_relative 'rails/bidirectional_association'
+require_relative 'rails/mandatory_inverse_of'
+require_relative 'rails/optional_belongs_to'
+require_relative 'rails/ordered_macros'
+require_relative 'rspec/conditional_in_let'
+require_relative 'rspec/factory_bot_in_before'
+require_relative 'rspec/inverse_of_matcher'
+require_relative 'rspec/overwritten_let'
+require_relative 'style/disallow_safe_navigation'
+require_relative 'style/disallow_try'

data/lib/rubocop/cop/layout/multiline_statement_spacing.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'rubocop'
+
+module RuboCop
+  module Cop
+    module Layout
+      # Requires a blank line between two consecutive statements when either of
+      # them spans multiple lines. Adjacent single-line statements need no blank
+      # line. The boundary with the enclosing `def`/`do`/`end` is left to other
+      # cops.
+      #
+      # Detection-only (no autocorrect) for now — the comment-handling and
+      # autocorrect behaviour need validation against the real repos first.
+      #
+      # @example
+      #   # bad
+      #   foo(
+      #     bar
+      #   )
+      #   baz
+      #
+      #   # good
+      #   foo(
+      #     bar
+      #   )
+      #
+      #   baz
+      #
+      class MultilineStatementSpacing < ::RuboCop::Cop::Base
+        MSG = 'Add a blank line around multi-line statements.'
+
+        def on_begin(node)
+          node.children.each_cons(2) do |first, second|
+            next unless first.is_a?(::RuboCop::AST::Node) && second.is_a?(::RuboCop::AST::Node)
+            next unless first.multiline? || second.multiline?
+            next if blank_line_between?(first, second)
+
+            add_offense(second)
+          end
+        end
+
+        private
+
+        def blank_line_between?(first, second)
+          return false if second.first_line - first.last_line < 2
+
+          ((first.last_line + 1)...second.first_line).any? do |line|
+            processed_source.lines[line - 1].strip.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/rails/bidirectional_association.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'rubocop'
+
+module RuboCop
+  module Cop
+    module Rails
+      # Ensures that all ActiveRecord associations are declared on both sides.
+      #
+      # Example:
+      #   # bad
+      #   class Post < ApplicationRecord
+      #     belongs_to :user
+      #   end
+      #
+      #   class User < ApplicationRecord
+      #   end
+      #
+      #   # good
+      #   class Post < ApplicationRecord
+      #     belongs_to :user, inverse_of: :posts
+      #   end
+      #
+      #   class User < ApplicationRecord
+      #     has_many :posts, inverse_of: :user
+      #   end
+      #
+      class BidirectionalAssociation < ::RuboCop::Cop::Base
+        MSG = 'Associations must be declared on both sides of the relationship.'
+
+        def self.default_configuration
+          super.merge(
+            'Include' => ['app/models/**/*.rb'],
+            'Exclude' => ['app/serializers/**/*.rb']
+          )
+        end
+
+        def on_new_investigation
+          return unless in_model_file?(processed_source.file_path)
+          return unless processed_source.ast
+
+          associations.each do |model_name, _assoc_name, inverse_name, target_class|
+            next if model_name.nil? || target_class.nil?
+
+            opposite_model_path = File.join(Dir.pwd, "app/models/#{camel_to_snake(target_class)}.rb")
+            next unless File.exist?(opposite_model_path)
+
+            opposite_content = File.read(opposite_model_path)
+
+            expected_inverse =
+              if inverse_name
+                inverse_name.to_s
+              else
+                camel_to_snake(model_name).split('/').last.pluralize
+              end
+
+            unless /(belongs_to|has_many|has_one)\s+:#{expected_inverse}/.match?(opposite_content)
+              add_global_offense("#{target_class} is missing opposite association for #{model_name}")
+            end
+          end
+        rescue StandardError => e
+          source_name =
+            if processed_source && processed_source.buffer
+              processed_source.file_path
+            else
+              'unknown'
+            end
+
+          warn "Rails/BidirectionalAssociation failed on #{source_name}: #{e.message}"
+        end
+
+        private
+
+        def associations
+          processed_source.ast.each_descendant(:send).filter_map do |node|
+            next unless %i[belongs_to has_many has_one].include?(node.method_name)
+
+            # Skip polymorphic associations and `as:` options
+            next if polymorphic_or_as?(node)
+
+            model_name = class_name_from_ast
+
+            assoc_name =
+              begin
+                node.first_argument.value if node.first_argument
+              rescue StandardError
+                nil
+              end
+
+            inverse_name = extract_inverse_of(node)
+            target_class = extract_class_name(node, assoc_name)
+
+            [model_name, assoc_name, inverse_name, target_class]
+          end
+        end
+
+        def extract_inverse_of(node)
+          kwargs = node.last_argument
+          return nil unless kwargs && kwargs.hash_type?
+
+          pair =
+            begin
+              kwargs.pairs.find { |p| p.key.value == :inverse_of }
+            rescue StandardError
+              nil
+            end
+
+          pair.value.value if pair && pair.value
+        end
+
+        def extract_class_name(node, assoc_name)
+          kwargs = node.last_argument
+          return assoc_name.to_s.camelize unless kwargs && kwargs.hash_type?
+
+          class_name_pair =
+            begin
+              kwargs.pairs.find { |p| p.key.value == :class_name }
+            rescue StandardError
+              nil
+            end
+
+          if class_name_pair
+            class_name_pair.value.value
+          else
+            assoc_name.to_s.camelize
+          end
+        end
+
+        def polymorphic_or_as?(node)
+          kwargs = node.last_argument
+          return false unless kwargs && kwargs.hash_type?
+
+          kwargs.pairs.any? do |pair|
+            key = pair.key.value
+            %i[polymorphic as].include?(key)
+          end
+        end
+
+        def class_name_from_ast
+          class_node = processed_source.ast.each_descendant(:class).first
+          return nil unless class_node
+
+          const_node = class_node.children.first
+          const_node.const_name if const_node
+        end
+
+        def in_model_file?(path)
+          return false if path.nil?
+
+          path.start_with?(File.join(Dir.pwd, 'app/models'))
+        end
+
+        # Replace ActiveSupport's underscore with plain Ruby equivalent
+        #
+        # Example:
+        #   "UserAccount" → "user_account"
+        #   "PlanStatementAudit::Row" → "plan_statement_audit/row"
+        def camel_to_snake(name)
+          return '' if name.nil?
+
+          name.gsub('::', '/')
+              .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+        end
+      end
+    end
+  end
+end