ivar 0.2.0 → 0.4.0

data/lib/ivar/checked.rb

@@ -1,40 +1,33 @@
 # frozen_string_literal: true
 
 require_relative "validation"
+require_relative "macros"
+require_relative "check_policy"
+require_relative "checked/class_methods"
+require_relative "checked/instance_methods"
 
 module Ivar
-  # Provides automatic validation for instance variables
-  # When included, automatically checks instance variables after initialization
+  # Provides automatic validation for instance variables.
+  # When included in a class, this module:
+  # 1. Automatically calls check_ivars after initialization
+  # 2. Extends the class with CheckPolicy for policy configuration
+  # 3. Extends the class with Macros for ivar declarations
+  # 4. Sets a default check policy of :warn
+  # 5. Handles proper inheritance of these behaviors in subclasses
   module Checked
     # When this module is included in a class, it extends the class
     # with ClassMethods and includes the Validation module
+    # @param base [Class] The class that is including this module
     def self.included(base)
       base.include(Validation)
       base.extend(ClassMethods)
+      base.extend(CheckPolicy)
+      base.extend(Macros)
       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
+      # Set default policy for Checked to :warn
+      # This can be overridden by calling ivar_check_policy in the class
+      base.ivar_check_policy(Ivar.check_policy)
     end
   end
 end

data/lib/ivar/declaration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ivar
+  # Base class for all declarations
+  class Declaration
+    # @return [Symbol] The name of the instance variable
+    attr_reader :name, :manifest
+
+    # Initialize a new declaration
+    # @param name [Symbol, String] The name of the instance variable
+    def initialize(name, manifest)
+      @name = name.to_sym
+      @manifest = manifest
+    end
+
+    # Called when the declaration is added to a class
+    # @param klass [Class, Module] The class or module the declaration is added to
+    def on_declare(klass)
+      # Base implementation does nothing
+    end
+
+    # Called before object initialization
+    # @param instance [Object] The object being initialized
+    # @param args [Array] Positional arguments
+    # @param kwargs [Hash] Keyword arguments
+    def before_init(instance, args, kwargs)
+      # Base implementation does nothing
+    end
+  end
+end

data/lib/ivar/explicit_declaration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+require_relative "macros"
+
+module Ivar
+  # Represents an explicit declaration from the ivar macro
+  class ExplicitDeclaration < Declaration
+    # Initialize a new explicit declaration
+    # @param name [Symbol, String] The name of the instance variable
+    # @param options [Hash] Options for the declaration
+    def initialize(name, manifest, options = {})
+      super(name, manifest)
+      @init_method = options[:init]
+      @initial_value = options[:value]
+      @reader = options[:reader] || false
+      @writer = options[:writer] || false
+      @accessor = options[:accessor] || false
+      @init_block = options[:block]
+    end
+
+    # Called when the declaration is added to a class
+    # @param klass [Class, Module] The class or module the declaration is added to
+    def on_declare(klass)
+      add_accessor_methods(klass)
+    end
+
+    # Check if this declaration uses keyword argument initialization
+    # @return [Boolean] Whether this declaration uses keyword argument initialization
+    def kwarg_init? = false
+
+    # Called before object initialization
+    # @param instance [Object] The object being initialized
+    # @param args [Array] Positional arguments
+    # @param kwargs [Hash] Keyword arguments
+    def before_init(instance, args, kwargs)
+      if @init_block
+        instance.instance_variable_set(@name, @init_block.call(@name))
+      end
+      if @initial_value != Ivar::Macros::UNSET
+        instance.instance_variable_set(@name, @initial_value)
+      end
+    end
+
+    private
+
+    # Add accessor methods to the class
+    # @param klass [Class, Module] The class to add methods to
+    def add_accessor_methods(klass)
+      var_name = @name.to_s.delete_prefix("@")
+
+      klass.__send__(:attr_reader, var_name) if @reader || @accessor
+      klass.__send__(:attr_writer, var_name) if @writer || @accessor
+    end
+  end
+end

data/lib/ivar/explicit_keyword_declaration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "explicit_declaration"
+
+module Ivar
+  # Represents an explicit declaration that initializes from keyword arguments
+  class ExplicitKeywordDeclaration < ExplicitDeclaration
+    # Check if this declaration uses keyword argument initialization
+    # @return [Boolean] Whether this declaration uses keyword argument initialization
+    def kwarg_init? = true
+
+    # Called before object initialization
+    # @param instance [Object] The object being initialized
+    # @param args [Array] Positional arguments
+    # @param kwargs [Hash] Keyword arguments
+    def before_init(instance, args, kwargs)
+      super
+      kwarg_name = @name.to_s.delete_prefix("@").to_sym
+      if kwargs.key?(kwarg_name)
+        instance.instance_variable_set(@name, kwargs.delete(kwarg_name))
+      end
+    end
+  end
+end

data/lib/ivar/explicit_positional_declaration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "explicit_declaration"
+
+module Ivar
+  # Represents an explicit declaration that initializes from positional arguments
+  class ExplicitPositionalDeclaration < ExplicitDeclaration
+    # Called before object initialization
+    # @param instance [Object] The object being initialized
+    # @param args [Array] Positional arguments
+    # @param kwargs [Hash] Keyword arguments
+    def before_init(instance, args, kwargs)
+      super
+      if args.length > 0
+        instance.instance_variable_set(@name, args.shift)
+      end
+    end
+  end
+end

data/lib/ivar/macros.rb

@@ -3,121 +3,58 @@
 module Ivar
   # Provides macros for working with instance variables
   module Macros
+    # Special flag object to detect when a parameter is not provided
+    UNSET = Object.new.freeze
+
     # 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)
+      # Get or create a manifest for this class
+      Ivar.get_or_create_manifest(base)
+    end
+
+    # Declares instance variables that should be considered valid
+    # without being explicitly initialized
+    # @param ivars [Array<Symbol>] Instance variables to declare
+    # @param value [Object] Optional value to initialize all declared variables with
+    #   Example: ivar :@foo, :@bar, value: 123
+    # @param init [Symbol] Initialization method for the variable
+    #   :kwarg or :keyword - initializes from a keyword argument with the same name
+    #   Example: ivar :@foo, init: :kwarg
+    # @param reader [Boolean] If true, creates attr_reader for all declared variables
+    #   Example: ivar :@foo, :@bar, reader: true
+    # @param writer [Boolean] If true, creates attr_writer for all declared variables
+    #   Example: ivar :@foo, :@bar, writer: true
+    # @param accessor [Boolean] If true, creates attr_accessor for all declared variables
+    #   Example: ivar :@foo, :@bar, accessor: true
+    # @param ivars_with_values [Hash] Individual initial values for instance variables
+    #   Example: ivar "@foo": 123, "@bar": 456
+    # @yield [varname] Block to generate initial values based on variable name
+    #   Example: ivar(:@foo, :@bar) { |varname| "#{varname} default" }
+    def ivar(*ivars, value: UNSET, init: nil, reader: false, writer: false, accessor: false, **ivars_with_values, &block)
+      manifest = Ivar.get_or_create_manifest(self)
+
+      ivar_hash = ivars.map { |ivar| [ivar, value] }.to_h.merge(ivars_with_values)
+
+      ivar_hash.each do |ivar_name, ivar_value|
+        raise ArgumentError, "ivars must be symbols (#{ivar_name.inspect})" unless ivar_name.is_a?(Symbol)
+        raise ArgumentError, "ivar names must start with @ (#{ivar_name.inspect})" unless /\A@/.match?(ivar_name)
+
+        options = {init:, value: ivar_value, reader:, writer:, accessor:, block:}
+
+        declaration = case init
+        when :kwarg, :keyword
+          Ivar::ExplicitKeywordDeclaration.new(ivar_name, manifest, options)
+        when :arg, :positional
+          # TODO: probably fail if a duplicate positional comes in
+          #   There aren't any obvious semantics for it.
+          Ivar::ExplicitPositionalDeclaration.new(ivar_name, manifest, options)
+        when nil
+          Ivar::ExplicitDeclaration.new(ivar_name, manifest, options)
+        else
+          raise ArgumentError, "Invalid init method: #{init.inspect}"
         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
+        manifest.add_explicit_declaration(declaration)
       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/manifest.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "declaration"
+require_relative "explicit_declaration"
+require_relative "explicit_keyword_declaration"
+require_relative "explicit_positional_declaration"
+
+module Ivar
+  # Represents a manifest of instance variable declarations for a class/module
+  class Manifest
+    # @return [Class, Module] The class or module this manifest is associated with
+    attr_reader :owner
+
+    # Initialize a new manifest
+    # @param owner [Class, Module] The class or module this manifest is associated with
+    def initialize(owner)
+      @owner = owner
+      @declarations_by_name = {}
+    end
+
+    # @return [Hash<Symbol, Declaration>] The declarations hash keyed by variable name
+    attr_reader :declarations_by_name
+
+    # @return [Array<Declaration>] The declarations in this manifest
+    def declarations
+      @declarations_by_name.values
+    end
+
+    # Add an explicit declaration to the manifest
+    # @param declaration [ExplicitDeclaration] The declaration to add
+    # @return [ExplicitDeclaration] The added declaration
+    def add_explicit_declaration(declaration)
+      name = declaration.name
+      @declarations_by_name[name] = declaration
+      declaration.on_declare(@owner)
+      declaration
+    end
+
+    # Get all ancestor manifests in reverse order (from highest to lowest in the hierarchy)
+    # Only includes ancestors that have existing manifests
+    # @return [Array<Manifest>] Array of ancestor manifests
+    def ancestor_manifests
+      return [] unless @owner.respond_to?(:ancestors)
+
+      @owner
+        .ancestors.reject { |ancestor| ancestor == @owner }
+        .filter_map { |ancestor| Ivar.get_manifest(ancestor, create: false) }
+        .reverse
+    end
+
+    def explicitly_declared_ivars
+      all_declarations.grep(ExplicitDeclaration).map(&:name)
+    end
+
+    # Get all declarations, including those from ancestor manifests
+    # @return [Array<Declaration>] All declarations
+    def all_declarations
+      ancestor_manifests
+        .flat_map(&:declarations)
+        .+(declarations)
+        # use hash stores to preserve order and deduplicate by name
+        .each_with_object({}) { |decl, acc| acc[decl.name] = decl }
+        .values
+    end
+
+    # Check if a variable is declared in this manifest or ancestor manifests
+    # @param name [Symbol, String] The variable name
+    # @return [Boolean] Whether the variable is declared
+    def declared?(name)
+      name = name.to_sym
+
+      # Check in this manifest first
+      return true if @declarations_by_name.key?(name)
+
+      # Then check in ancestor manifests
+      ancestor_manifests.any? do |ancestor_manifest|
+        ancestor_manifest.declarations_by_name.key?(name)
+      end
+    end
+
+    # Get a declaration by name
+    # @param name [Symbol, String] The variable name
+    # @return [Declaration, nil] The declaration, or nil if not found
+    def get_declaration(name)
+      name = name.to_sym
+
+      # Check in this manifest first
+      return @declarations_by_name[name] if @declarations_by_name.key?(name)
+
+      # Then check in ancestor manifests, starting from the closest ancestor
+      ancestor_manifests.each do |ancestor_manifest|
+        if ancestor_manifest.declarations_by_name.key?(name)
+          return ancestor_manifest.declarations_by_name[name]
+        end
+      end
+
+      nil
+    end
+
+    # Get all explicit declarations
+    # @return [Array<ExplicitDeclaration>] All explicit declarations
+    def explicit_declarations
+      declarations.select { |decl| decl.is_a?(ExplicitDeclaration) }
+    end
+
+    # Process before_init callbacks for all declarations
+    # @param instance [Object] The object being initialized
+    # @param args [Array] Positional arguments
+    # @param kwargs [Hash] Keyword arguments
+    # @return [Array, Hash] The modified args and kwargs
+    def process_before_init(instance, args, kwargs)
+      # Get all declarations from parent to child, with child declarations taking precedence
+      declarations_to_process = all_declarations
+
+      # Process all initializations in a single pass
+      # The before_init method will handle keyword arguments with proper precedence
+      declarations_to_process.each do |declaration|
+        declaration.before_init(instance, args, kwargs)
+      end
+
+      [args, kwargs]
+    end
+  end
+end

data/lib/ivar/policies.rb

@@ -115,12 +115,24 @@ module Ivar
     end
   end
 
+  # Policy that does nothing (no-op) for unknown instance variables
+  class NonePolicy < Policy
+    # Handle unknown instance variables by doing nothing
+    # @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)
+      # No-op - do nothing
+    end
+  end
+
   # Map of policy symbols to policy classes
   POLICY_CLASSES = {
     warn: WarnPolicy,
     warn_once: WarnOncePolicy,
     raise: RaisePolicy,
-    log: LogPolicy
+    log: LogPolicy,
+    none: NonePolicy
   }.freeze
 
   # Get a policy instance from a symbol or policy object

data/lib/ivar/project_root.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ivar
+  # Handles project root detection and caching
+  class ProjectRoot
+    # Project root indicator files, in order of precedence
+    INDICATORS = %w[Gemfile .git .ruby-version Rakefile].freeze
+
+    def initialize
+      @cache = {}
+      @mutex = Mutex.new
+    end
+
+    # Determines the project root directory based on the caller's location
+    # @param caller_location [String, nil] Optional file path to start from (defaults to caller's location)
+    # @return [String] The absolute path to the project root directory
+    def find(caller_location = nil)
+      file_path = caller_location || caller_locations(2, 1).first&.path
+      return Dir.pwd unless file_path
+
+      @mutex.synchronize do
+        return @cache[file_path] if @cache.key?(file_path)
+      end
+
+      dir = File.dirname(File.expand_path(file_path))
+      root = find_project_root(dir)
+
+      @mutex.synchronize do
+        @cache[file_path] = root
+      end
+
+      root
+    end
+
+    # Clear the cache (mainly for testing)
+    def clear_cache
+      @mutex.synchronize { @cache.clear }
+    end
+
+    private
+
+    # Find the project root by walking up the directory tree
+    # @param start_dir [String] Directory to start the search from
+    # @return [String] The project root directory
+    def find_project_root(start_dir)
+      path = Pathname.new(start_dir)
+
+      path.ascend do |dir|
+        INDICATORS.each do |indicator|
+          return dir.to_s if dir.join(indicator).exist?
+        end
+      end
+
+      start_dir
+    end
+  end
+end