ivar 0.2.0

data/examples/sandwich_with_ivar_block.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithIvarBlock
+  include Ivar::Checked
+
+  # Pre-declare instance variables with a block that runs before initialization
+  ivar :@side do
+    @pickles = true
+    @condiments = []
+  end
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+    # Note: @pickles is already set to true by the ivar block
+    # Note: @condiments is already initialized to an empty array by the ivar block
+    @condiments << "mayo" if !@pickles
+    @condiments << "mustard"
+    # Note: @side is not set here, but it's pre-initialized to nil
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese}"
+    result += " and #{@condiments.join(", ")}" unless @condiments.empty?
+    result += " with pickles" if @pickles
+    result += " and a side of #{@side}" if @side
+    result
+  end
+
+  def add_side(side)
+    @side = side
+  end
+end
+
+# Create a sandwich - this will automatically check instance variables
+sandwich = SandwichWithIvarBlock.new
+puts sandwich
+
+# Add a side
+sandwich.add_side("chips")
+puts sandwich

data/examples/sandwich_with_ivar_macro.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithIvarMacro
+  include Ivar::Checked
+
+  # Pre-declare only instance variables that might be referenced before being set
+  # You don't need to include variables that are always set in initialize
+  ivar :@side
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+    @condiments = %w[mayo mustard]
+    # NOTE: @side is not set here, but it's pre-initialized to nil
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese} and #{@condiments.join(", ")}"
+    # This won't trigger a warning because @side is pre-initialized
+    result += " and a side of #{@side}" if @side
+    result
+  end
+
+  def add_side(side)
+    @side = side
+  end
+end
+
+# Create a sandwich - this will automatically check instance variables
+sandwich = SandwichWithIvarMacro.new
+puts sandwich
+
+# Add a side and print again
+sandwich.add_side("chips")
+puts sandwich

data/examples/sandwich_with_kwarg.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithKwarg
+  include Ivar::Checked
+
+  # Pre-declare instance variables to be initialized from keyword arguments
+  ivar kwarg: [:@bread, :@cheese, :@condiments]
+
+  def initialize(pickles: false, side: nil)
+    # Note: @bread, @cheese, and @condiments are already set from keyword arguments
+    # We only need to handle the remaining keyword arguments
+    @pickles = pickles
+    @side = side
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese}"
+    result += " and #{@condiments.join(", ")}" unless @condiments.empty?
+    result += " with pickles" if @pickles
+    result += " and a side of #{@side}" if @side
+    result
+  end
+end
+
+# Create a sandwich with keyword arguments
+sandwich = SandwichWithKwarg.new(
+  bread: "wheat",
+  cheese: "muenster",
+  condiments: ["mayo", "mustard"],
+  side: "chips"
+)
+
+puts sandwich  # Outputs: A wheat sandwich with muenster and mayo, mustard and a side of chips
+
+# Create another sandwich with different keyword arguments
+sandwich2 = SandwichWithKwarg.new(
+  bread: "rye",
+  cheese: "swiss",
+  condiments: ["mustard"],
+  pickles: true
+)
+
+puts sandwich2  # Outputs: A rye sandwich with swiss and mustard with pickles

data/ivar.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "lib/ivar/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ivar"
+  spec.version = Ivar::VERSION
+  spec.authors = ["Avdi Grimm"]
+  spec.email = ["avdi@avdi.codes"]
+
+  spec.summary = "Automatically check instance variables for typos."
+  spec.description = <<~EOF
+    Ruby instance variables are so convenient - you don't even need to declare them!
+    But... they are also dangerous, because a mispelled variable name results in `nil`
+    instead of an error.
+
+    Why not have the best of both worlds? Ivar lets you use plain-old instance variables,
+    and automatically checks for typos.
+
+    Ivar waits until an instance is created to do the checking, then uses Prism to look
+    for variables that don't match what was set in initialization. So it's a little bit
+    dynamic, a little bit static. It doesn't encumber your instance variable reads and
+    writes with any extra checking. And with the `:warn_once` policy, it won't overwhelm
+    you with output.
+  EOF
+
+  spec.homepage = "https://github.com/avdi/ivar"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.4.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/avdi/ivar"
+  spec.metadata["changelog_uri"] = "https://github.com/avdi/ivar/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  spec.add_dependency "prism", "~> 1.2"
+end

data/lib/ivar/auto_check.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "validation"
+require_relative "macros"
+
+module Ivar
+  # Module for adding ivar_check_policy to classes
+  module CheckPolicy
+    # Set the check policy for this class
+    # @param policy [Symbol, Policy] The check policy
+    # @return [Symbol, Policy] The check policy
+    def ivar_check_policy(policy = nil, **options)
+      if policy.nil?
+        # Getter - return the current policy
+        @__ivar_check_policy || Ivar.check_policy
+      else
+        # Setter - set the policy
+        @__ivar_check_policy = options.empty? ? policy : [policy, options]
+      end
+    end
+
+    # Hook method called when the module is included
+    def inherited(subclass)
+      super
+      # Copy the check policy to the subclass
+      subclass.instance_variable_set(:@__ivar_check_policy, @__ivar_check_policy)
+    end
+  end
+
+  # Provides automatic validation for instance variables
+  # When included, automatically calls check_ivars after initialization
+  module Checked
+    # When this module is included in a class, it extends the class
+    # with ClassMethods and includes the Validation module
+    def self.included(base)
+      base.include(Validation)
+      base.include(PreInitializeIvars)
+      base.extend(ClassMethods)
+      base.extend(CheckPolicy)
+      base.extend(Macros)
+      base.prepend(InstanceMethods)
+
+      # Set default policy for Checked to :warn
+      base.ivar_check_policy(:warn)
+    end
+
+    # Class methods added to the including class
+    module ClassMethods
+      # Hook method called when the module is included
+      def inherited(subclass)
+        super
+        # Ensure subclasses also get the initialize wrapper
+        subclass.prepend(Ivar::Checked::InstanceMethods)
+      end
+    end
+
+    # Instance methods that will be prepended to the including class
+    module InstanceMethods
+      # Wrap the initialize method to automatically call check_ivars
+      def initialize(*args, **kwargs, &block)
+        # Initialize pre-declared instance variables
+        initialize_pre_declared_ivars
+        # Execute the initialization block if provided
+        execute_ivar_init_block
+
+        # Process keyword arguments
+        remaining_kwargs = initialize_from_kwargs(kwargs)
+
+        # Call the original initialize method with remaining arguments
+        super(*args, **remaining_kwargs, &block)
+
+        # Automatically check instance variables
+        check_ivars
+      end
+    end
+  end
+end

data/lib/ivar/checked.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "validation"
+
+module Ivar
+  # Provides automatic validation for instance variables
+  # When included, automatically checks instance variables after initialization
+  module Checked
+    # When this module is included in a class, it extends the class
+    # with ClassMethods and includes the Validation module
+    def self.included(base)
+      base.include(Validation)
+      base.extend(ClassMethods)
+      base.prepend(InstanceMethods)
+    end
+
+    # Class methods added to the including class
+    module ClassMethods
+      # Hook method called when the module is included
+      def inherited(subclass)
+        super
+        # Ensure subclasses also get the initialize wrapper
+        subclass.prepend(InstanceMethods)
+      end
+    end
+
+    # Instance methods that will be prepended to the including class
+    module InstanceMethods
+      # Wrap the initialize method to automatically call check_ivars
+      def initialize(*args, **kwargs, &block)
+        # Call the original initialize method
+        super
+        # Automatically check instance variables
+        # We need to collect all instance variables from the current object
+        # and pass them to check_ivars_once to ensure they're all recognized
+        check_ivars_once
+      end
+    end
+  end
+end

data/lib/ivar/macros.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Ivar
+  # Provides macros for working with instance variables
+  module Macros
+    # When this module is extended, it adds class methods to the extending class
+    def self.extended(base)
+      # Store pre-declared instance variables for this class
+      base.instance_variable_set(:@__ivar_pre_declared_ivars, [])
+      # Store initialization block
+      base.instance_variable_set(:@__ivar_init_block, nil)
+      # Store keyword argument mappings
+      base.instance_variable_set(:@__ivar_kwarg_mappings, [])
+    end
+
+    # Declares instance variables that should be pre-initialized to nil
+    # before the initializer is called
+    # @param ivars [Array<Symbol>] Instance variables to pre-initialize
+    # @param kwarg [Array<Symbol>] Instance variables to initialize from keyword arguments
+    # @yield Optional block to execute in the context of the instance before initialization
+    def ivar(*ivars, kwarg: [], &block)
+      # Store the pre-declared instance variables
+      pre_declared = instance_variable_get(:@__ivar_pre_declared_ivars) || []
+      instance_variable_set(:@__ivar_pre_declared_ivars, pre_declared + ivars)
+
+      # Store the keyword argument mappings
+      kwarg_mappings = instance_variable_get(:@__ivar_kwarg_mappings) || []
+      instance_variable_set(:@__ivar_kwarg_mappings, kwarg_mappings + Array(kwarg))
+
+      # Store the initialization block if provided
+      instance_variable_set(:@__ivar_init_block, block) if block
+    end
+
+    # Hook method called when the module is included
+    def inherited(subclass)
+      super
+      # Copy pre-declared instance variables to subclass
+      parent_ivars = instance_variable_get(:@__ivar_pre_declared_ivars) || []
+      subclass.instance_variable_set(:@__ivar_pre_declared_ivars, parent_ivars.dup)
+
+      # Copy keyword argument mappings to subclass
+      parent_kwarg_mappings = instance_variable_get(:@__ivar_kwarg_mappings) || []
+      subclass.instance_variable_set(:@__ivar_kwarg_mappings, parent_kwarg_mappings.dup)
+
+      # Copy initialization block to subclass
+      parent_block = instance_variable_get(:@__ivar_init_block)
+      subclass.instance_variable_set(:@__ivar_init_block, parent_block) if parent_block
+    end
+
+    # Get the pre-declared instance variables for this class
+    # @return [Array<Symbol>] Pre-declared instance variables
+    def ivar_pre_declared
+      instance_variable_get(:@__ivar_pre_declared_ivars) || []
+    end
+
+    # Get the keyword argument mappings for this class
+    # @return [Array<Symbol>] Keyword argument mappings
+    def ivar_kwarg_mappings
+      instance_variable_get(:@__ivar_kwarg_mappings) || []
+    end
+
+    # Get the initialization block for this class
+    # @return [Proc, nil] The initialization block or nil if none was provided
+    def ivar_init_block
+      instance_variable_get(:@__ivar_init_block)
+    end
+  end
+
+  # Module to pre-initialize instance variables
+  module PreInitializeIvars
+    # Initialize pre-declared instance variables to nil
+    def initialize_pre_declared_ivars
+      klass = self.class
+      while klass.respond_to?(:ivar_pre_declared)
+        klass.ivar_pre_declared.each do |ivar|
+          instance_variable_set(ivar, nil) unless instance_variable_defined?(ivar)
+        end
+        klass = klass.superclass
+      end
+    end
+
+    # Execute the initialization block in the context of the instance
+    def execute_ivar_init_block
+      klass = self.class
+      while klass.respond_to?(:ivar_init_block)
+        block = klass.ivar_init_block
+        instance_eval(&block) if block
+        klass = klass.superclass
+      end
+    end
+
+    # Get all keyword argument mappings from the class hierarchy
+    # @return [Array<Symbol>] All keyword argument mappings
+    def all_kwarg_mappings
+      mappings = []
+      klass = self.class
+      while klass.respond_to?(:ivar_kwarg_mappings)
+        mappings.concat(klass.ivar_kwarg_mappings)
+        klass = klass.superclass
+      end
+      mappings
+    end
+
+    # Initialize instance variables from keyword arguments
+    # @param kwargs [Hash] Keyword arguments
+    # @return [Hash] Remaining keyword arguments
+    def initialize_from_kwargs(kwargs)
+      remaining_kwargs = kwargs.dup
+
+      all_kwarg_mappings.each do |ivar|
+        # Convert @ivar_name to ivar_name for keyword lookup
+        key = ivar.to_s.delete_prefix("@").to_sym
+
+        if remaining_kwargs.key?(key)
+          instance_variable_set(ivar, remaining_kwargs[key])
+          remaining_kwargs.delete(key)
+        end
+      end
+
+      remaining_kwargs
+    end
+  end
+end

data/lib/ivar/policies.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Ivar
+  # Base class for all ivar checking policies
+  class Policy
+    # Handle unknown instance variables
+    # @param unknown_refs [Array<Hash>] References to unknown instance variables
+    # @param klass [Class] The class being checked
+    # @param allowed_ivars [Array<Symbol>] List of allowed instance variables
+    def handle_unknown_ivars(unknown_refs, klass, allowed_ivars)
+      raise NotImplementedError, "Subclasses must implement handle_unknown_ivars"
+    end
+
+    # Find the closest match for a variable name
+    # @param ivar [Symbol] The variable to find a match for
+    # @param known_ivars [Array<Symbol>] List of known variables
+    # @return [Symbol, nil] The closest match or nil if none found
+    def find_closest_match(ivar, known_ivars)
+      finder = DidYouMean::SpellChecker.new(dictionary: known_ivars)
+      suggestions = finder.correct(ivar.to_s)
+      suggestions.first&.to_sym if suggestions.any?
+    end
+
+    # Format a warning message for an unknown instance variable
+    # @param ref [Hash] Reference to an unknown instance variable
+    # @param suggestion [Symbol, nil] Suggested correction or nil
+    # @return [String] Formatted warning message
+    def format_warning(ref, suggestion)
+      ivar = ref[:name]
+      suggestion_text = suggestion ? "Did you mean: #{suggestion}?" : ""
+      "#{ref[:path]}:#{ref[:line]}: warning: unknown instance variable #{ivar}. #{suggestion_text}\n"
+    end
+  end
+
+  # Policy that warns about unknown instance variables
+  class WarnPolicy < Policy
+    # Handle unknown instance variables by emitting warnings
+    # @param unknown_refs [Array<Hash>] References to unknown instance variables
+    # @param klass [Class] The class being checked
+    # @param allowed_ivars [Array<Symbol>] List of allowed instance variables
+    def handle_unknown_ivars(unknown_refs, _klass, allowed_ivars)
+      unknown_refs.each do |ref|
+        ivar = ref[:name]
+        suggestion = find_closest_match(ivar, allowed_ivars)
+        $stderr.write(format_warning(ref, suggestion))
+      end
+    end
+  end
+
+  # Policy that warns about unknown instance variables only once per class
+  class WarnOncePolicy < Policy
+    # Handle unknown instance variables by emitting warnings once per class
+    # @param unknown_refs [Array<Hash>] References to unknown instance variables
+    # @param klass [Class] The class being checked
+    # @param allowed_ivars [Array<Symbol>] List of allowed instance variables
+    def handle_unknown_ivars(unknown_refs, klass, allowed_ivars)
+      # Skip if this class has already been checked
+      return if Ivar.class_checked?(klass)
+
+      # Emit warnings
+      unknown_refs.each do |ref|
+        ivar = ref[:name]
+        suggestion = find_closest_match(ivar, allowed_ivars)
+        $stderr.write(format_warning(ref, suggestion))
+      end
+
+      # Mark this class as having been checked
+      Ivar.mark_class_checked(klass)
+    end
+  end
+
+  # Policy that raises an exception for unknown instance variables
+  class RaisePolicy < Policy
+    # Handle unknown instance variables by raising an exception
+    # @param unknown_refs [Array<Hash>] References to unknown instance variables
+    # @param klass [Class] The class being checked
+    # @param allowed_ivars [Array<Symbol>] List of allowed instance variables
+    def handle_unknown_ivars(unknown_refs, _klass, allowed_ivars)
+      return if unknown_refs.empty?
+
+      # Get the first unknown reference
+      ref = unknown_refs.first
+      ivar = ref[:name]
+      suggestion = find_closest_match(ivar, allowed_ivars)
+      suggestion_text = suggestion ? " Did you mean: #{suggestion}?" : ""
+
+      # Raise an exception with location information
+      message = "#{ref[:path]}:#{ref[:line]}: unknown instance variable #{ivar}.#{suggestion_text}"
+      raise NameError, message
+    end
+  end
+
+  # Policy that logs unknown instance variables to a logger
+  class LogPolicy < Policy
+    # Initialize with a logger
+    # @param logger [Logger] The logger to use
+    def initialize(logger: Logger.new($stderr))
+      @logger = logger
+    end
+
+    # Handle unknown instance variables by logging them
+    # @param unknown_refs [Array<Hash>] References to unknown instance variables
+    # @param klass [Class] The class being checked
+    # @param allowed_ivars [Array<Symbol>] List of allowed instance variables
+    def handle_unknown_ivars(unknown_refs, _klass, allowed_ivars)
+      unknown_refs.each do |ref|
+        ivar = ref[:name]
+        suggestion = find_closest_match(ivar, allowed_ivars)
+        suggestion_text = suggestion ? " Did you mean: #{suggestion}?" : ""
+        message = "#{ref[:path]}:#{ref[:line]}: unknown instance variable #{ivar}.#{suggestion_text}"
+        @logger.warn(message)
+      end
+    end
+  end
+
+  # Map of policy symbols to policy classes
+  POLICY_CLASSES = {
+    warn: WarnPolicy,
+    warn_once: WarnOncePolicy,
+    raise: RaisePolicy,
+    log: LogPolicy
+  }.freeze
+
+  # Get a policy instance from a symbol or policy object
+  # @param policy [Symbol, Policy, Array] The policy to get
+  # @param options [Hash] Options to pass to the policy constructor
+  # @return [Policy] The policy instance
+  def self.get_policy(policy, **options)
+    return policy if policy.is_a?(Policy)
+
+    # Handle the case where policy is an array with [policy_name, options]
+    if policy.is_a?(Array) && policy.size == 2 && policy[1].is_a?(Hash)
+      policy_name, policy_options = policy
+      policy_class = POLICY_CLASSES[policy_name]
+      raise ArgumentError, "Unknown policy: #{policy_name}" unless policy_class
+
+      return policy_class.new(**policy_options)
+    end
+
+    policy_class = POLICY_CLASSES[policy]
+    raise ArgumentError, "Unknown policy: #{policy}" unless policy_class
+
+    policy_class.new(**options)
+  end
+end

data/lib/ivar/prism_analysis.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Ivar
+  # Analyzes a class to find all instance variables using Prism
+  class PrismAnalysis
+    attr_reader :ivars
+
+    def initialize(klass)
+      @klass = klass
+      @references = nil
+      collect_references
+      @ivars = unique_ivar_names
+    end
+
+    # Returns a list of hashes each representing a code reference to an ivar
+    # Each hash includes var name, path, line number, and column number
+    def ivar_references
+      @references
+    end
+
+    private
+
+    def collect_references
+      source_files = collect_source_files
+      @references = []
+
+      source_files.each do |file_path|
+        code = File.read(file_path)
+        result = Prism.parse(code)
+        visitor = IvarReferenceVisitor.new(file_path)
+        result.value.accept(visitor)
+        @references.concat(visitor.references)
+      end
+    end
+
+    def unique_ivar_names
+      @references.map { |ref| ref[:name] }.uniq.sort
+    end
+
+    def collect_source_files
+      # Get all instance methods
+      instance_methods = @klass.instance_methods(false) | @klass.private_instance_methods(false)
+
+      # Collect source files for all methods
+      source_files = Set.new
+      instance_methods.each do |method_name|
+        next unless @klass.instance_method(method_name).source_location
+
+        source_files << @klass.instance_method(method_name).source_location.first
+      end
+
+      source_files
+    end
+
+    # Visitor that collects instance variable references with location information
+    class IvarReferenceVisitor < Prism::Visitor
+      attr_reader :references
+
+      def initialize(file_path)
+        super()
+        @file_path = file_path
+        @references = []
+      end
+
+      def visit_instance_variable_read_node(node)
+        add_reference(node)
+        true
+      end
+
+      def visit_instance_variable_write_node(node)
+        add_reference(node)
+        true
+      end
+
+      def visit_instance_variable_operator_write_node(node)
+        add_reference(node)
+        true
+      end
+
+      def visit_instance_variable_target_node(node)
+        add_reference(node)
+        true
+      end
+
+      private
+
+      def add_reference(node)
+        location = node.location
+        reference = {
+          name: node.name.to_sym,
+          path: @file_path,
+          line: location.start_line,
+          column: location.start_column
+        }
+
+        @references << reference
+      end
+    end
+  end
+end