rubocop-instance_variable_access 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 944fafee55d6eae0c082e77a20ee605aee7ba1e35aa67e0b54c948d14c874bb9
+  data.tar.gz: dff9f511c5db8e20be45eb2dc6a14db0dd533590cd30f7fd62477e157643c5e9
+SHA512:
+  metadata.gz: 85fd2668242673960b7ce52680d0f9ed788e8866dbe528c56b2ba6f89a83f0e6c234ebd7a15a6b45020355a573f7b1d802888677dd504175783867340dd7017e
+  data.tar.gz: cc2b85b5b008dfe3cbf8422f91c3725a0eee420790c091f1538943e8ac0ff17ee389f3ad61ff3193e1892cdab4167f059e052b40fc0102e3a0733d66258ff528

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [Unreleased]
+
+## [1.0.0] - 2026-09-21
+
+- Add `Style/InstanceVariableAccess` cop that enforces accessing instance
+  variables (including class instance variables) through reader methods,
+  even from inside the defining class.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"rubocop-instance_variable_access" 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 ["i.tkomiya@gmail.com"](mailto:"i.tkomiya@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Takeshi KOMIYA
+
+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,136 @@
+# RuboCop::InstanceVariableAccess
+
+A RuboCop extension that provides `Style/InstanceVariableAccess`, a cop that
+enforces accessing instance variables (and class instance variables) through
+reader methods, even from inside the class that defines them.
+
+## Why?
+
+Wrapping instance variables in reader methods, even inside the class that
+defines them, follows the
+[Barewords Pattern](https://www.alchemists.io/articles/barewords_pattern):
+
+- A typo in a method name raises `NameError` immediately, while a typo in
+  an instance variable name (`@nmae`) silently returns `nil`.
+- A reader is easier to extend later (add memoization, a default value, or
+  validation) without touching every call site.
+- Ruby's own hash value omission syntax (`{x:}`) ended up supporting
+  either a local variable or a method like `attr_reader`.
+
+This does mean a reader becomes part of the class's public API unless it is
+`private`; this cop doesn't care about visibility, so keep a reader private
+when the attribute isn't meant to be exposed outside the class.
+
+Further reading:
+
+- [Barewords Pattern](https://www.alchemists.io/articles/barewords_pattern)
+- [Feature #14579 - Hash value omission](https://bugs.ruby-lang.org/issues/14579)
+
+## Installation
+
+Install the gem:
+
+```bash
+bundle add rubocop-instance_variable_access --group development,test --require false
+```
+
+## Usage
+
+Add the following to your `.rubocop.yml`:
+
+```yaml
+plugins:
+  - rubocop-instance_variable_access
+```
+
+## The cop
+
+`Style/InstanceVariableAccess` flags:
+
+```ruby
+# bad
+class Person
+  def full_name
+    "#{@first_name} #{@last_name}"
+  end
+end
+```
+
+and suggests:
+
+```ruby
+# good
+class Person
+  attr_reader :first_name, :last_name
+
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+end
+```
+
+Writing to an instance variable is always allowed, so a memoization idiom
+such as `@memo ||= expensive_call` is unaffected. Reading that same
+instance variable anywhere else while computing the value being assigned
+to it is allowed too, whether the assignment is a plain `=`
+(`@count = @count + 1`, `@count = compute(@count)`) or a compound
+assignment that reads it again explicitly (`@count += compute(@count)`).
+
+A method whose name matches the instance variable (`def first_name; ...;
+@first_name; end`) is treated as that variable's own reader, so referencing
+it there is not flagged either, no matter what else the method does first.
+Class instance variables (e.g. `@total` inside `def self.total` or
+`class << self`) are checked the same way as regular instance variables.
+
+An instance variable read inside a block passed to `instance_eval`,
+`instance_exec`, `class_eval`, or `module_eval` on anything other than
+`self` isn't flagged, since `self` (and therefore whose instance variable
+is actually being read) changes inside that block:
+
+```ruby
+# good: `@first_name` belongs to `other`, not to `Person`
+class Person
+  def borrow_name_from(other)
+    other.instance_eval { @first_name }
+  end
+end
+```
+
+Autocorrection only rewrites `@foo` to `foo` when an `attr_reader`/
+`attr_accessor` for `foo` already exists in the same class body; a
+hand-written reader doesn't count, since there's no way to tell whether
+it's safe to call in place of `@foo` (it could have side effects, or
+require arguments). Otherwise, only the offense is reported, since
+generating an `attr_reader` automatically could unintentionally widen the
+method's visibility.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `rake spec` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+To release a new version, update the version number in `version.rb` and
+push it to `main`; the [release workflow](.github/workflows/release.yml)
+then publishes the gem to [rubygems.org](https://rubygems.org) automatically.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/tk0miya/rubocop-instance_variable_access. This project is
+intended to be a safe, welcoming space for collaboration, and contributors
+are expected to adhere to the
+[code of conduct](https://github.com/tk0miya/rubocop-instance_variable_access/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the RuboCop::InstanceVariableAccess project's
+codebases, issue trackers, chat rooms and mailing lists is expected to
+follow the
+[code of conduct](https://github.com/tk0miya/rubocop-instance_variable_access/blob/main/CODE_OF_CONDUCT.md).

data/config/default.yml

@@ -0,0 +1,4 @@
+Style/InstanceVariableAccess:
+  Description: 'Checks that instance variables are accessed through reader methods.'
+  Enabled: true
+  VersionAdded: '1.0.0'

data/lib/rubocop/cop/instance_variable_access_cops.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "style/instance_variable_access"

data/lib/rubocop/cop/style/instance_variable_access.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Style
+      # Checks that instance variables (including class instance variables) are
+      # accessed through reader methods rather than referenced directly, even
+      # from within the class that defines them.
+      #
+      # Writing to an instance variable (via `=`, `+=`, `||=`, `&&=`, or
+      # multiple assignment) is always allowed, so a memoization idiom such
+      # as `@memo ||= expensive_call` is unaffected, since it writes to the
+      # variable rather than reading it. Reading that same instance variable
+      # anywhere else while computing the value being assigned to it is
+      # allowed too, whether the assignment is a plain `=`
+      # (`@count = @count + 1`, `@count = compute(@count)`) or a compound
+      # assignment that reads it again explicitly
+      # (`@count += compute(@count)`).
+      #
+      # A method whose name matches the instance variable (`def name; ...;
+      # @name; end`, or its class-method equivalent `def self.name; ...;
+      # @name; end`) is treated as that variable's own reader, so referencing
+      # it there is not itself an offense, no matter what else the method's
+      # body does.
+      #
+      # An instance variable read inside a block passed to `instance_eval`,
+      # `instance_exec`, `class_eval`, or `module_eval` on anything other
+      # than `self` is not flagged, since `self` (and therefore whose
+      # instance variable is actually being read) changes inside that
+      # block.
+      #
+      # @safety
+      #   Autocorrection only rewrites `@foo` to `foo` when an `attr_reader`/
+      #   `attr_accessor` for the same instance/singleton context already
+      #   exists in the same class body. A hand-written reader like the one
+      #   above doesn't count, because there is no way to tell whether it is
+      #   safe to call in place of `@foo` (it could have side effects, or
+      #   require arguments). Otherwise, only the offense is reported; this
+      #   cop never generates an `attr_reader`.
+      #
+      # @example
+      #   # bad
+      #   class Person
+      #     def full_name
+      #       "#{@first_name} #{@last_name}"
+      #     end
+      #   end
+      #
+      #   # good
+      #   class Person
+      #     attr_reader :first_name, :last_name
+      #
+      #     def full_name
+      #       "#{first_name} #{last_name}"
+      #     end
+      #   end
+      #
+      #   # good (the reader definition itself is not an offense)
+      #   class Person
+      #     private
+      #
+      #     def first_name
+      #       @first_name
+      #     end
+      #   end
+      #
+      #   # good (still just the reader, whatever else it does first)
+      #   class Person
+      #     def first_name
+      #       logger.debug("first_name accessed")
+      #       @first_name
+      #     end
+      #   end
+      #
+      #   # good (memoization writes to the instance variable rather than reading it)
+      #   class Person
+      #     def first_name
+      #       @first_name ||= compute_first_name
+      #     end
+      #   end
+      #
+      #   # good (reading `@count` anywhere while rewriting it is fine, `=` or `+=`)
+      #   class Counter
+      #     def increment
+      #       @count = compute(@count)
+      #       @count += compute(@count)
+      #     end
+      #   end
+      #
+      #   # good (`self` changes inside the block, so this isn't Person's own ivar)
+      #   class Person
+      #     def borrow_name_from(other)
+      #       other.instance_eval { @first_name }
+      #     end
+      #   end
+      class InstanceVariableAccess < Base
+        extend AutoCorrector
+
+        MSG = "Use a reader method instead of directly accessing `%<ivar>s`."
+
+        RESTRICT_ON_SEND = %i[attr_reader attr_accessor].freeze
+
+        # Methods that run their block with `self` rebound to something other
+        # than the block's lexical `self`, so an instance variable read inside
+        # such a block cannot be attributed to the enclosing class/module.
+        SELF_CHANGING_BLOCK_METHODS = %i[instance_eval instance_exec class_eval module_eval].freeze
+
+        # @rbs!
+        #   def attr_reader_or_accessor?: (RuboCop::AST::Node node) -> bool
+
+        def_node_matcher :attr_reader_or_accessor?, <<~PATTERN
+          (send nil? {:attr_reader :attr_accessor} ...)
+        PATTERN
+
+        # A candidate offense: an instance variable read that isn't inside the
+        # body of a method of the same name. Resolved against the enclosing
+        # scope's readers once the whole class/module body has been seen.
+        Violation = Data.define(
+          :node,      #: RuboCop::AST::Node -- the instance variable node that may be an offense
+          :singleton  #: bool -- whether it's in a singleton (class-level) context
+        )
+
+        # The readers and pending violations for a single class/module body
+        # (or the top level, for the root scope).
+        Scope = Struct.new(
+          :instance_readers,  #: Hash[Symbol, Symbol] -- known instance-level readers, by variable name
+          :class_readers,     #: Hash[Symbol, Symbol] -- known class-level (singleton) readers, by variable name
+          :violations,        #: Array[Violation] -- offense candidates collected so far in this scope
+          :singleton_depth,   #: Integer -- nesting depth inside `class << self` blocks
+          keyword_init: true
+        )
+
+        def on_new_investigation #: void
+          @scope_stack = []
+          push_scope
+        end
+
+        def on_investigation_end #: void
+          report_violations
+          pop_scope
+        end
+
+        def on_class(_node) #: void
+          push_scope
+        end
+        alias on_module on_class
+
+        # @rbs _node: RuboCop::AST::Node
+        def after_class(_node) #: void
+          report_violations
+          pop_scope
+        end
+        alias after_module after_class
+
+        # @rbs _node: RuboCop::AST::Node
+        def on_sclass(_node) #: void
+          current_scope.singleton_depth += 1
+        end
+
+        # @rbs _node: RuboCop::AST::Node
+        def after_sclass(_node) #: void
+          current_scope.singleton_depth -= 1
+        end
+
+        # @rbs node: RuboCop::AST::SendNode
+        def on_send(node) #: void
+          return if top_level?
+          return unless attr_reader_or_accessor?(node)
+
+          registry = singleton_context? ? current_scope.class_readers : current_scope.instance_readers
+          node.arguments.each do |arg|
+            case arg
+            when RuboCop::AST::SymbolNode, RuboCop::AST::StrNode
+              name = arg.value.to_sym # steep:ignore
+              registry[name] = name
+            end
+          end
+        end
+
+        # @rbs node: RuboCop::AST::Node
+        def on_ivar(node) #: void
+          return if same_named_method_body?(node)
+          return if in_self_changing_block?(node)
+          return if self_referential_write?(node)
+
+          current_scope.violations << Violation.new(node:, singleton: civar?(node))
+        end
+
+        private
+
+        attr_reader :scope_stack #: Array[Scope] -- the scopes of the classes/modules currently being visited
+
+        def push_scope #: void
+          scope_stack.push(
+            Scope.new(instance_readers: {}, class_readers: {}, violations: [], singleton_depth: 0)
+          )
+        end
+
+        def pop_scope #: void
+          scope_stack.pop
+        end
+
+        def current_scope #: Scope
+          scope_stack.last or raise
+        end
+
+        def singleton_context? #: bool
+          current_scope.singleton_depth.positive?
+        end
+
+        # Whether we are outside of any class/module, at the top level of the
+        # file. Readers are never registered there, so that a reader defined
+        # at the top level cannot unexpectedly match an unrelated top-level
+        # instance variable.
+        def top_level? #: bool
+          scope_stack.size == 1
+        end
+
+        def report_violations #: void
+          current_scope.violations.each { report_violation(_1) }
+        end
+
+        # @rbs violation: Violation
+        def report_violation(violation) #: void
+          node = violation.node
+          registry = violation.singleton ? current_scope.class_readers : current_scope.instance_readers
+          reader = registry[bare_ivar_name(node)]
+
+          add_offense(node, message: format(MSG, ivar: node.source)) do |corrector|
+            corrector.replace(node, reader.to_s) if reader
+          end
+        end
+
+        # Whether the instance variable sits in a singleton (class-level)
+        # context: inside `def self.x`, or inside `def x` that is itself
+        # nested in `class << self`.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def civar?(node) #: bool
+          method_node = enclosing_def(node)
+          return true unless method_node
+          return true if method_node.defs_type?
+
+          boundary = method_node.each_ancestor(:sclass, :class, :module).first
+          boundary&.sclass_type? || false
+        end
+
+        # Whether `node` is an instance variable read inside the body of a
+        # method of the same name, regardless of what else that method's
+        # body does.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def same_named_method_body?(node) #: bool
+          method_node = enclosing_def(node)
+          return false unless method_node
+
+          bare_ivar_name(node) == bare_method_name(method_node)
+        end
+
+        # Whether `node` sits inside a block that rebinds `self` away from the
+        # enclosing class/module (`klass.instance_eval { @foo }`), making it
+        # impossible to tell whose ivar is actually being read. The search
+        # stops at the nearest enclosing `def`/`defs`, since a method
+        # definition always establishes its own `self` regardless of any
+        # block it happens to be lexically nested in.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def in_self_changing_block?(node) #: bool
+          node.each_ancestor(:def, :defs, :block, :numblock).each do |ancestor|
+            case ancestor.type
+            when :def, :defs
+              return false
+            else
+              return true if self_changing_block?(ancestor)
+            end
+          end
+
+          false
+        end
+
+        # @rbs node: RuboCop::AST::Node
+        def self_changing_block?(node) #: bool
+          block = node #: RuboCop::AST::BlockNode
+          send_node = block.send_node
+          receiver = send_node.receiver
+
+          return false unless receiver
+          return false if receiver.self_type?
+
+          SELF_CHANGING_BLOCK_METHODS.include?(send_node.method_name)
+        end
+
+        # Whether `node` is an instance variable read that appears anywhere
+        # in the value being assigned to that very same instance variable —
+        # whether by a plain `=` (`@x = @x + 1`, `@x = process(@x)`) or a
+        # compound assignment (`@x += @x + 1`, `@x += process(@x)`,
+        # `@x ||= ...`, `@x &&= ...`). Rewriting an instance variable is
+        # always allowed to read that same instance variable freely while
+        # computing its new value, wherever in the expression it's used. The
+        # search stops at the nearest enclosing `def`/`defs`, so a variable
+        # of the same name assigned in an unrelated enclosing method doesn't
+        # accidentally match.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def self_referential_write?(node) #: bool
+          ancestor = node.each_ancestor(:ivasgn, :op_asgn, :or_asgn, :and_asgn, :def, :defs).first
+          return false unless ancestor
+
+          target = assignment_target(ancestor)
+          return false unless target
+
+          target.children.first == node.children.first
+        end
+
+        # The instance variable being assigned by `node`, if `node` is a
+        # plain assignment to one (`ivasgn`) or a compound assignment whose
+        # target is one; `nil` otherwise, including when `node` is a
+        # `def`/`defs` boundary the search above stops at.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def assignment_target(node) #: RuboCop::AST::Node?
+          return node if node.ivasgn_type?
+          return nil unless node.op_asgn_type? || node.or_asgn_type? || node.and_asgn_type?
+
+          lhs = node.children.first
+          lhs if lhs.ivasgn_type?
+        end
+
+        # @rbs node: RuboCop::AST::Node
+        def enclosing_def(node) #: RuboCop::AST::DefNode?
+          node.each_ancestor(:any_def).first #: RuboCop::AST::DefNode?
+        end
+
+        # @rbs node: RuboCop::AST::DefNode
+        def bare_method_name(node) #: Symbol
+          node.method_name.to_s.sub(/[=?]$/, "").to_sym
+        end
+
+        # @rbs node: RuboCop::AST::Node
+        def bare_ivar_name(node) #: Symbol
+          node.children.first.to_s.delete_prefix("@").to_sym
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/instance_variable_access/plugin.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "lint_roller"
+require "pathname"
+
+module RuboCop
+  module InstanceVariableAccess
+    # A plugin that integrates rubocop-instance_variable_access with RuboCop's plugin system.
+    class Plugin < LintRoller::Plugin
+      def about #: LintRoller::About
+        LintRoller::About.new(
+          name: "rubocop-instance_variable_access",
+          version: VERSION,
+          homepage: "https://github.com/tk0miya/rubocop-instance_variable_access",
+          description: "A RuboCop extension that enforces accessing instance variables through reader methods."
+        )
+      end
+
+      # @rbs context: untyped
+      def supported?(context) #: bool
+        context.engine == :rubocop
+      end
+
+      # @rbs _context: untyped
+      def rules(_context) #: LintRoller::Rules
+        project_root = Pathname.new(__dir__.to_s).join("../../..")
+
+        LintRoller::Rules.new(
+          type: :path,
+          config_format: :rubocop,
+          value: project_root.join("config", "default.yml")
+        )
+      end
+    end
+  end
+end

data/lib/rubocop/instance_variable_access/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module InstanceVariableAccess
+    VERSION = "1.0.0"
+  end
+end

data/lib/rubocop/instance_variable_access.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "instance_variable_access/version"
+
+module RuboCop
+  module InstanceVariableAccess
+    class Error < StandardError; end
+  end
+end

data/lib/rubocop-instance_variable_access.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "rubocop"
+
+require_relative "rubocop/instance_variable_access"
+require_relative "rubocop/instance_variable_access/plugin"
+
+require_relative "rubocop/cop/instance_variable_access_cops"

data/sig/rubocop/cop/instance_variable_access_cops.rbs

@@ -0,0 +1,2 @@
+# Generated from lib/rubocop/cop/instance_variable_access_cops.rb with RBS::Inline
+

data/sig/rubocop/cop/style/instance_variable_access.rbs

@@ -0,0 +1,249 @@
+# Generated from lib/rubocop/cop/style/instance_variable_access.rb with RBS::Inline
+
+module RuboCop
+  module Cop
+    module Style
+      # Checks that instance variables (including class instance variables) are
+      # accessed through reader methods rather than referenced directly, even
+      # from within the class that defines them.
+      #
+      # Writing to an instance variable (via `=`, `+=`, `||=`, `&&=`, or
+      # multiple assignment) is always allowed, so a memoization idiom such
+      # as `@memo ||= expensive_call` is unaffected, since it writes to the
+      # variable rather than reading it. Reading that same instance variable
+      # anywhere else while computing the value being assigned to it is
+      # allowed too, whether the assignment is a plain `=`
+      # (`@count = @count + 1`, `@count = compute(@count)`) or a compound
+      # assignment that reads it again explicitly
+      # (`@count += compute(@count)`).
+      #
+      # A method whose name matches the instance variable (`def name; ...;
+      # @name; end`, or its class-method equivalent `def self.name; ...;
+      # @name; end`) is treated as that variable's own reader, so referencing
+      # it there is not itself an offense, no matter what else the method's
+      # body does.
+      #
+      # An instance variable read inside a block passed to `instance_eval`,
+      # `instance_exec`, `class_eval`, or `module_eval` on anything other
+      # than `self` is not flagged, since `self` (and therefore whose
+      # instance variable is actually being read) changes inside that
+      # block.
+      #
+      # @safety
+      #   Autocorrection only rewrites `@foo` to `foo` when an `attr_reader`/
+      #   `attr_accessor` for the same instance/singleton context already
+      #   exists in the same class body. A hand-written reader like the one
+      #   above doesn't count, because there is no way to tell whether it is
+      #   safe to call in place of `@foo` (it could have side effects, or
+      #   require arguments). Otherwise, only the offense is reported; this
+      #   cop never generates an `attr_reader`.
+      #
+      # @example
+      #   # bad
+      #   class Person
+      #     def full_name
+      #       "#{@first_name} #{@last_name}"
+      #     end
+      #   end
+      #
+      #   # good
+      #   class Person
+      #     attr_reader :first_name, :last_name
+      #
+      #     def full_name
+      #       "#{first_name} #{last_name}"
+      #     end
+      #   end
+      #
+      #   # good (the reader definition itself is not an offense)
+      #   class Person
+      #     private
+      #
+      #     def first_name
+      #       @first_name
+      #     end
+      #   end
+      #
+      #   # good (still just the reader, whatever else it does first)
+      #   class Person
+      #     def first_name
+      #       logger.debug("first_name accessed")
+      #       @first_name
+      #     end
+      #   end
+      #
+      #   # good (memoization writes to the instance variable rather than reading it)
+      #   class Person
+      #     def first_name
+      #       @first_name ||= compute_first_name
+      #     end
+      #   end
+      #
+      #   # good (reading `@count` anywhere while rewriting it is fine, `=` or `+=`)
+      #   class Counter
+      #     def increment
+      #       @count = compute(@count)
+      #       @count += compute(@count)
+      #     end
+      #   end
+      #
+      #   # good (`self` changes inside the block, so this isn't Person's own ivar)
+      #   class Person
+      #     def borrow_name_from(other)
+      #       other.instance_eval { @first_name }
+      #     end
+      #   end
+      class InstanceVariableAccess < Base
+        extend AutoCorrector
+
+        MSG: ::String
+
+        RESTRICT_ON_SEND: untyped
+
+        # Methods that run their block with `self` rebound to something other
+        # than the block's lexical `self`, so an instance variable read inside
+        # such a block cannot be attributed to the enclosing class/module.
+        SELF_CHANGING_BLOCK_METHODS: untyped
+
+        def attr_reader_or_accessor?: (RuboCop::AST::Node node) -> bool
+
+        # A candidate offense: an instance variable read that isn't inside the
+        # body of a method of the same name. Resolved against the enclosing
+        # scope's readers once the whole class/module body has been seen.
+        class Violation < Data
+          attr_reader node(): RuboCop::AST::Node
+
+          attr_reader singleton(): bool
+
+          def self.new: (RuboCop::AST::Node node, bool singleton) -> instance
+                      | (node: RuboCop::AST::Node, singleton: bool) -> instance
+
+          def self.members: () -> [ :node, :singleton ]
+
+          def members: () -> [ :node, :singleton ]
+        end
+
+        # The readers and pending violations for a single class/module body
+        # (or the top level, for the root scope).
+        class Scope < Struct[Hash[Symbol, Symbol] | Array[Violation] | Integer]
+          attr_accessor instance_readers(): Hash[Symbol, Symbol]
+
+          attr_accessor class_readers(): Hash[Symbol, Symbol]
+
+          attr_accessor violations(): Array[Violation]
+
+          attr_accessor singleton_depth(): Integer
+
+          def self.new: (?instance_readers: Hash[Symbol, Symbol], ?class_readers: Hash[Symbol, Symbol], ?violations: Array[Violation], ?singleton_depth: Integer) -> instance
+                      | ({ ?instance_readers: Hash[Symbol, Symbol], ?class_readers: Hash[Symbol, Symbol], ?violations: Array[Violation], ?singleton_depth: Integer }) -> instance
+        end
+
+        def on_new_investigation: () -> void
+
+        def on_investigation_end: () -> void
+
+        def on_class: (untyped _node) -> void
+
+        alias on_module on_class
+
+        # @rbs _node: RuboCop::AST::Node
+        def after_class: (untyped _node) -> void
+
+        alias after_module after_class
+
+        # @rbs _node: RuboCop::AST::Node
+        def on_sclass: (untyped _node) -> void
+
+        # @rbs _node: RuboCop::AST::Node
+        def after_sclass: (untyped _node) -> void
+
+        # @rbs node: RuboCop::AST::SendNode
+        def on_send: (RuboCop::AST::SendNode node) -> void
+
+        # @rbs node: RuboCop::AST::Node
+        def on_ivar: (RuboCop::AST::Node node) -> void
+
+        private
+
+        attr_reader scope_stack: Array[Scope]
+
+        def push_scope: () -> void
+
+        def pop_scope: () -> void
+
+        def current_scope: () -> Scope
+
+        def singleton_context?: () -> bool
+
+        # Whether we are outside of any class/module, at the top level of the
+        # file. Readers are never registered there, so that a reader defined
+        # at the top level cannot unexpectedly match an unrelated top-level
+        # instance variable.
+        def top_level?: () -> bool
+
+        def report_violations: () -> void
+
+        # @rbs violation: Violation
+        def report_violation: (Violation violation) -> void
+
+        # Whether the instance variable sits in a singleton (class-level)
+        # context: inside `def self.x`, or inside `def x` that is itself
+        # nested in `class << self`.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def civar?: (RuboCop::AST::Node node) -> bool
+
+        # Whether `node` is an instance variable read inside the body of a
+        # method of the same name, regardless of what else that method's
+        # body does.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def same_named_method_body?: (RuboCop::AST::Node node) -> bool
+
+        # Whether `node` sits inside a block that rebinds `self` away from the
+        # enclosing class/module (`klass.instance_eval { @foo }`), making it
+        # impossible to tell whose ivar is actually being read. The search
+        # stops at the nearest enclosing `def`/`defs`, since a method
+        # definition always establishes its own `self` regardless of any
+        # block it happens to be lexically nested in.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def in_self_changing_block?: (RuboCop::AST::Node node) -> bool
+
+        # @rbs node: RuboCop::AST::Node
+        def self_changing_block?: (RuboCop::AST::Node node) -> bool
+
+        # Whether `node` is an instance variable read that appears anywhere
+        # in the value being assigned to that very same instance variable —
+        # whether by a plain `=` (`@x = @x + 1`, `@x = process(@x)`) or a
+        # compound assignment (`@x += @x + 1`, `@x += process(@x)`,
+        # `@x ||= ...`, `@x &&= ...`). Rewriting an instance variable is
+        # always allowed to read that same instance variable freely while
+        # computing its new value, wherever in the expression it's used. The
+        # search stops at the nearest enclosing `def`/`defs`, so a variable
+        # of the same name assigned in an unrelated enclosing method doesn't
+        # accidentally match.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def self_referential_write?: (RuboCop::AST::Node node) -> bool
+
+        # The instance variable being assigned by `node`, if `node` is a
+        # plain assignment to one (`ivasgn`) or a compound assignment whose
+        # target is one; `nil` otherwise, including when `node` is a
+        # `def`/`defs` boundary the search above stops at.
+        #
+        # @rbs node: RuboCop::AST::Node
+        def assignment_target: (RuboCop::AST::Node node) -> RuboCop::AST::Node?
+
+        # @rbs node: RuboCop::AST::Node
+        def enclosing_def: (RuboCop::AST::Node node) -> RuboCop::AST::DefNode?
+
+        # @rbs node: RuboCop::AST::DefNode
+        def bare_method_name: (RuboCop::AST::DefNode node) -> Symbol
+
+        # @rbs node: RuboCop::AST::Node
+        def bare_ivar_name: (RuboCop::AST::Node node) -> Symbol
+      end
+    end
+  end
+end

data/sig/rubocop/instance_variable_access/plugin.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/rubocop/instance_variable_access/plugin.rb with RBS::Inline
+
+module RuboCop
+  module InstanceVariableAccess
+    # A plugin that integrates rubocop-instance_variable_access with RuboCop's plugin system.
+    class Plugin < LintRoller::Plugin
+      def about: () -> LintRoller::About
+
+      # @rbs context: untyped
+      def supported?: (untyped context) -> bool
+
+      # @rbs _context: untyped
+      def rules: (untyped _context) -> LintRoller::Rules
+    end
+  end
+end

data/sig/rubocop/instance_variable_access/version.rbs

@@ -0,0 +1,7 @@
+# Generated from lib/rubocop/instance_variable_access/version.rb with RBS::Inline
+
+module RuboCop
+  module InstanceVariableAccess
+    VERSION: ::String
+  end
+end

data/sig/rubocop/instance_variable_access.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/rubocop/instance_variable_access.rb with RBS::Inline
+
+module RuboCop
+  module InstanceVariableAccess
+    class Error < StandardError
+    end
+  end
+end

data/sig/rubocop-instance_variable_access.rbs

@@ -0,0 +1,2 @@
+# Generated from lib/rubocop-instance_variable_access.rb with RBS::Inline
+

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-instance_variable_access
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Takeshi KOMIYA
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: rubocop-instance_variable_access provides the Style/InstanceVariableAccess
+  cop, which flags direct reads of instance variables (including class instance variables)
+  outside of their reader method, encouraging access via attr_reader/attr_accessor
+  or a hand-written reader even from within the defining class.
+email:
+- i.tkomiya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- config/default.yml
+- lib/rubocop-instance_variable_access.rb
+- lib/rubocop/cop/instance_variable_access_cops.rb
+- lib/rubocop/cop/style/instance_variable_access.rb
+- lib/rubocop/instance_variable_access.rb
+- lib/rubocop/instance_variable_access/plugin.rb
+- lib/rubocop/instance_variable_access/version.rb
+- sig/rubocop-instance_variable_access.rbs
+- sig/rubocop/cop/instance_variable_access_cops.rbs
+- sig/rubocop/cop/style/instance_variable_access.rbs
+- sig/rubocop/instance_variable_access.rbs
+- sig/rubocop/instance_variable_access/plugin.rbs
+- sig/rubocop/instance_variable_access/version.rbs
+homepage: https://github.com/tk0miya/rubocop-instance_variable_access
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tk0miya/rubocop-instance_variable_access
+  source_code_uri: https://github.com/tk0miya/rubocop-instance_variable_access.git
+  changelog_uri: https://github.com/tk0miya/rubocop-instance_variable_access/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  default_lint_roller_plugin: RuboCop::InstanceVariableAccess::Plugin
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A RuboCop extension that enforces accessing instance variables through reader
+  methods.
+test_files: []