ivar 0.2.0 → 0.4.0

data/lib/ivar/targeted_prism_analysis.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Ivar
+  # Analyzes a class to find instance variable references in specific instance methods
+  # Unlike PrismAnalysis, this targets only the class's own methods (not inherited)
+  # and precisely locates instance variable references within each method definition
+  class TargetedPrismAnalysis
+    attr_reader :ivars, :references
+
+    def initialize(klass)
+      @klass = klass
+      @references = []
+      @method_locations = {}
+      collect_method_locations
+      analyze_methods
+      @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 unique_ivar_names
+      @references.map { |ref| ref[:name] }.uniq.sort
+    end
+
+    def collect_method_locations
+      # Get all instance methods defined directly on this class (not inherited)
+      instance_methods = @klass.instance_methods(false) | @klass.private_instance_methods(false)
+      instance_methods.each do |method_name|
+        # Try to get the method from the stash first, then fall back to the current method
+        method_obj = Ivar.get_stashed_method(@klass, method_name) || @klass.instance_method(method_name)
+        next unless method_obj.source_location
+
+        file_path, line_number = method_obj.source_location
+        @method_locations[method_name] = {path: file_path, line: line_number}
+      end
+    end
+
+    def analyze_methods
+      # Group methods by file to avoid parsing the same file multiple times
+      methods_by_file = @method_locations.group_by { |_, location| location[:path] }
+
+      methods_by_file.each do |file_path, methods_in_file|
+        code = File.read(file_path)
+        result = Prism.parse(code)
+
+        methods_in_file.each do |method_name, location|
+          visitor = MethodTargetedInstanceVariableReferenceVisitor.new(
+            file_path,
+            method_name,
+            location[:line]
+          )
+
+          result.value.accept(visitor)
+          @references.concat(visitor.references)
+        end
+      end
+    end
+  end
+
+  # Visitor that collects instance variable references within a specific method definition
+  class MethodTargetedInstanceVariableReferenceVisitor < Prism::Visitor
+    attr_reader :references
+
+    def initialize(file_path, target_method_name, target_line)
+      super()
+      @file_path = file_path
+      @target_method_name = target_method_name
+      @target_line = target_line
+      @references = []
+      @in_target_method = false
+    end
+
+    # Only visit the method definition we're targeting
+    def visit_def_node(node)
+      # Check if this is our target method
+      if node.name.to_sym == @target_method_name && node.location.start_line == @target_line
+        # Found our target method, now collect all instance variable references within it
+        collector = IvarCollector.new(@file_path, @target_method_name)
+        node.body&.accept(collector)
+        @references = collector.references
+        false
+      else
+        # Sometimes methods are found inside other methods...
+        node.body&.accept(self)
+        true
+      end
+    end
+  end
+
+  # Helper visitor that collects all instance variable references
+  class IvarCollector < Prism::Visitor
+    attr_reader :references
+
+    def initialize(file_path, method_name)
+      super()
+      @file_path = file_path
+      @method_name = method_name
+      @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,
+        method: @method_name
+      }
+
+      @references << reference
+    end
+  end
+end

data/lib/ivar/validation.rb

@@ -9,46 +9,23 @@ module Ivar
     # @param add [Array<Symbol>] Additional instance variables to allow
     # @param policy [Symbol, Policy] The policy to use for handling unknown variables
     def check_ivars(add: [], policy: nil)
-      # Get the policy to use
       policy ||= get_check_policy
-
-      # Get the class analysis from the cache
-      analysis = Ivar.get_analysis(self.class)
-
-      # Get all instance variables defined in the current object
-      # These are the ones the user has explicitly defined before calling check_ivars
-      defined_ivars = instance_variables.map(&:to_sym)
-
-      # Add any additional allowed variables
-      allowed_ivars = defined_ivars + add
-
-      # Get all instance variable references from the analysis
-      # This includes location information for each reference
-      references = analysis.ivar_references
-
-      # Find references to unknown variables (those not in allowed_ivars)
-      unknown_refs = references.reject { |ref| allowed_ivars.include?(ref[:name]) }
-
-      # Handle unknown variables according to the policy
+      analyses = Ivar.get_ancestral_analyses(self.class)
+      manifest = Ivar.get_or_create_manifest(self.class)
+      declared_ivars = manifest.all_declarations.map(&:name)
+      allowed_ivars = (Ivar.known_internal_ivars | instance_variables | declared_ivars | add).uniq
+      instance_refs = analyses.flat_map(&:references)
+      unknown_refs = instance_refs.reject { |ref| allowed_ivars.include?(ref[:name]) }
       policy_instance = Ivar.get_policy(policy)
       policy_instance.handle_unknown_ivars(unknown_refs, self.class, allowed_ivars)
     end
 
-    # For backward compatibility - delegates to check_ivars with warn_once policy
-    # @param add [Array<Symbol>] Additional instance variables to allow
-    def check_ivars_once(add: [])
-      check_ivars(add: add, policy: :warn_once)
-    end
-
     private
 
     # Get the check policy for this instance
     # @return [Symbol, Policy] The check policy
     def get_check_policy
-      # If the class has an ivar_check_policy method, use that
       return self.class.ivar_check_policy if self.class.respond_to?(:ivar_check_policy)
-
-      # Otherwise, use the global default
       Ivar.check_policy
     end
   end

data/lib/ivar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ivar
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/ivar.rb

@@ -1,42 +1,124 @@
 # frozen_string_literal: true
 
 require_relative "ivar/version"
-require_relative "ivar/prism_analysis"
 require_relative "ivar/policies"
 require_relative "ivar/validation"
 require_relative "ivar/macros"
-require_relative "ivar/auto_check"
+require_relative "ivar/project_root"
+require_relative "ivar/check_all_manager"
+require_relative "ivar/check_policy"
+require_relative "ivar/checked"
+require_relative "ivar/manifest"
+require_relative "ivar/targeted_prism_analysis"
 require "prism"
 require "did_you_mean"
+require "pathname"
 
 module Ivar
   @analysis_cache = {}
   @checked_classes = {}
-  @default_check_policy = :warn
+  @default_check_policy = :warn_once
+  @manifest_registry = {}
+  @project_root = nil
+  MUTEX = Mutex.new
+  PROJECT_ROOT_FINDER = ProjectRoot.new
+  CHECK_ALL_MANAGER = CheckAllManager.new
+
+  # Pattern for internal instance variables
+  INTERNAL_IVAR_PREFIX = "@__ivar_"
+
+  # Checks if an instance variable name is an internal variable
+  # @param ivar_name [Symbol, String] The instance variable name to check
+  # @return [Boolean] Whether the variable is an internal variable
+  def self.internal_ivar?(ivar_name)
+    ivar_name.to_s.start_with?(INTERNAL_IVAR_PREFIX)
+  end
+
+  # Returns a list of known internal instance variables
+  # @return [Array<Symbol>] List of known internal instance variables
+  def self.known_internal_ivars
+    [
+      :@__ivar_check_policy,
+      :@__ivar_initialized_vars,
+      :@__ivar_method_impl_stash,
+      :@__ivar_skip_init
+    ]
+  end
+
+  def self.get_ancestral_analyses(klass)
+    klass
+      .ancestors.filter_map { |ancestor| maybe_get_analysis(ancestor) }
+      .reverse
+  end
+
+  def self.maybe_get_analysis(klass)
+    if klass.include?(Validation)
+      get_analysis(klass)
+    end
+  end
 
   # Returns a cached analysis for the given class or module
   # Creates a new analysis if one doesn't exist in the cache
+  # Thread-safe: Multiple readers are allowed, but writers block all other access
   def self.get_analysis(klass)
-    @analysis_cache[klass] ||= PrismAnalysis.new(klass)
+    return @analysis_cache[klass] if @analysis_cache.key?(klass)
+
+    MUTEX.synchronize do
+      @analysis_cache[klass] ||= TargetedPrismAnalysis.new(klass)
+    end
   end
 
   # Checks if a class has been validated already
   # @param klass [Class] The class to check
   # @return [Boolean] Whether the class has been validated
+  # Thread-safe: Read-only operation
   def self.class_checked?(klass)
-    @checked_classes.key?(klass)
+    MUTEX.synchronize { @checked_classes.key?(klass) }
   end
 
   # Marks a class as having been checked
   # @param klass [Class] The class to mark as checked
+  # Thread-safe: Write operation protected by mutex
   def self.mark_class_checked(klass)
-    @checked_classes[klass] = true
+    MUTEX.synchronize { @checked_classes[klass] = true }
   end
 
   # For testing purposes - allows clearing the cache
+  # Thread-safe: Write operation protected by mutex
   def self.clear_analysis_cache
-    @analysis_cache.clear
-    @checked_classes.clear
+    MUTEX.synchronize do
+      @analysis_cache.clear
+      @checked_classes.clear
+      @manifest_registry.clear
+    end
+    PROJECT_ROOT_FINDER.clear_cache
+  end
+
+  # Get or create a manifest for a class or module
+  # @param klass [Class, Module] The class or module to get a manifest for
+  # @param create [Boolean] Whether to create a new manifest if one doesn't exist
+  # @return [Manifest, nil] The manifest for the class or module, or nil if not found and create_if_missing is false
+  def self.get_manifest(klass, create: true)
+    return @manifest_registry[klass] if @manifest_registry.key?(klass)
+    return nil unless create
+
+    MUTEX.synchronize do
+      @manifest_registry[klass] ||= Manifest.new(klass)
+    end
+  end
+
+  # Alias for get_manifest that makes it clearer that it may create a manifest
+  # @param klass [Class, Module] The class or module to get a manifest for
+  # @return [Manifest] The manifest for the class or module
+  def self.get_or_create_manifest(klass)
+    get_manifest(klass, create: true)
+  end
+
+  # Check if a manifest exists for a class or module
+  # @param klass [Class, Module] The class or module to check
+  # @return [Boolean] Whether a manifest exists for the class or module
+  def self.manifest_exists?(klass)
+    @manifest_registry.key?(klass)
   end
 
   # Get the default check policy
@@ -48,6 +130,56 @@ module Ivar
   # Set the default check policy
   # @param policy [Symbol, Policy] The default check policy
   def self.check_policy=(policy)
-    @default_check_policy = policy
+    MUTEX.synchronize { @default_check_policy = policy }
+  end
+
+  def self.project_root=(explicit_root)
+    @project_root = explicit_root
+  end
+
+  # Determines the project root directory based on the caller's location
+  # Delegates to ProjectRoot class
+  # @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 self.project_root(caller_location = nil)
+    @project_root ||= PROJECT_ROOT_FINDER.find(caller_location)
+  end
+
+  # Enables automatic inclusion of Ivar::Checked in all classes and modules
+  # defined within the project root.
+  #
+  # @param block [Proc] Optional block. If provided, auto-checking is only active
+  #   for the duration of the block. Otherwise, it remains active indefinitely.
+  # @return [void]
+  def self.check_all(&block)
+    root = project_root
+    CHECK_ALL_MANAGER.enable(root, &block)
+  end
+
+  # Disables automatic inclusion of Ivar::Checked in classes and modules.
+  # @return [void]
+  def self.disable_check_all
+    CHECK_ALL_MANAGER.disable
+  end
+
+  # Gets a method from the stash or returns nil if not found
+  # @param klass [Class] The class that owns the method
+  # @param method_name [Symbol] The name of the method to retrieve
+  # @return [UnboundMethod, nil] The stashed method or nil if not found
+  def self.get_stashed_method(klass, method_name)
+    (klass.instance_variable_get(:@__ivar_method_impl_stash) || {})[method_name]
+  end
+
+  # Stashes a method implementation for a class
+  # @param klass [Class] The class that owns the method
+  # @param method_name [Symbol] The name of the method to stash
+  # @return [UnboundMethod, nil] The stashed method or nil if the method doesn't exist
+  def self.stash_method(klass, method_name)
+    return nil unless klass.method_defined?(method_name) || klass.private_method_defined?(method_name)
+
+    method_impl = klass.instance_method(method_name)
+    stash = klass.instance_variable_get(:@__ivar_method_impl_stash) ||
+      klass.instance_variable_set(:@__ivar_method_impl_stash, {})
+    stash[method_name] = method_impl
   end
 end

data/script/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ivar"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/script/de-lint

@@ -0,0 +1,2 @@
+#!/bin/sh
+STANDARDOPTS="--fix $*" bundle exec rake standard

data/script/de-lint-unsafe

@@ -0,0 +1,2 @@
+#!/bin/sh
+STANDARDOPTS="--fix-unsafely $*" bundle exec rake standard

data/script/lint

@@ -0,0 +1,2 @@
+#!/bin/sh
+STANDARDOPTS="$*" bundle exec rake standard

data/script/release

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# This script helps with releasing a new version of the gem
+# Usage: script/release [major|minor|patch] [options]
+#
+# Options:
+#   --yes, -y    Skip confirmation prompt
+
+require "bundler/gem_tasks"
+require_relative "../lib/ivar/version"
+
+def error(message)
+  puts "\e[31mError: #{message}\e[0m"
+  exit 1
+end
+
+def success(message)
+  puts "\e[32m#{message}\e[0m"
+end
+
+def info(message)
+  puts "\e[34m#{message}\e[0m"
+end
+
+def get_new_version(current_version, bump_type)
+  major, minor, patch = current_version.split(".").map(&:to_i)
+
+  case bump_type
+  when "major"
+    "#{major + 1}.0.0"
+  when "minor"
+    "#{major}.#{minor + 1}.0"
+  when "patch"
+    "#{major}.#{minor}.#{patch + 1}"
+  else
+    error "Invalid bump type. Use 'major', 'minor', or 'patch'."
+  end
+end
+
+def update_version_file(new_version)
+  version_file_path = "lib/ivar/version.rb"
+  version_content = File.read(version_file_path)
+  updated_content = version_content.gsub(/VERSION = "[0-9]+\.[0-9]+\.[0-9]+"/, "VERSION = \"#{new_version}\"")
+  File.write(version_file_path, updated_content)
+end
+
+def update_changelog(new_version)
+  changelog_path = "CHANGELOG.md"
+  changelog_content = File.read(changelog_path)
+
+  # Check if there are unreleased changes
+  unless changelog_content.include?("## [Unreleased]")
+    error "No unreleased changes found in CHANGELOG.md. Add changes before releasing."
+  end
+
+  # Update the changelog with the new version
+  today = Time.now.strftime("%Y-%m-%d")
+  updated_content = changelog_content.gsub(
+    "## [Unreleased]",
+    "## [Unreleased]\n\n## [#{new_version}] - #{today}"
+  )
+
+  File.write(changelog_path, updated_content)
+end
+
+def run_tests
+  info "Running tests..."
+  system("bundle exec rake test") || error("Tests failed. Fix the tests before releasing.")
+end
+
+def run_linter
+  info "Running linter..."
+  system("bundle exec rake standard") || error("Linter found issues. Fix them before releasing.")
+end
+
+def clean_build_artifacts
+  info "Cleaning build artifacts..."
+  system("bundle exec rake clean clobber")
+  # Also remove any stray .gem files in the project root
+  Dir.glob("*.gem").each do |gem_file|
+    info "Removing stray gem file: #{gem_file}"
+    File.delete(gem_file)
+  end
+end
+
+def commit_and_tag(new_version)
+  info "Committing version bump..."
+  system("git add lib/ivar/version.rb CHANGELOG.md")
+  system("git commit -m \"Bump version to #{new_version}\"")
+
+  info "Creating tag v#{new_version}..."
+  system("git tag -a v#{new_version} -m \"Version #{new_version}\"")
+
+  info "To push the new version, run:"
+  puts "  git push origin main && git push origin v#{new_version}"
+end
+
+# Main script
+error "Please specify a version bump type: major, minor, or patch" if ARGV.empty?
+
+# Parse arguments
+args = ARGV.dup
+skip_confirmation = args.delete("--yes") || args.delete("-y")
+bump_type = args[0].downcase if args[0]
+
+error "Please specify a version bump type: major, minor, or patch" unless bump_type
+
+current_version = Ivar::VERSION
+new_version = get_new_version(current_version, bump_type)
+
+info "Current version: #{current_version}"
+info "New version: #{new_version}"
+
+# Skip confirmation if --yes/-y option is provided
+confirmation = "y" if skip_confirmation
+
+unless confirmation
+  puts "Continue? (y/n)"
+  confirmation = $stdin.gets.chomp.downcase
+end
+
+if confirmation == "y"
+  clean_build_artifacts
+  run_tests
+  run_linter
+  update_version_file(new_version)
+  update_changelog(new_version)
+  commit_and_tag(new_version)
+  success "Version bumped to #{new_version}!"
+  success "Run 'git push origin main && git push origin v#{new_version}' to trigger the release workflow."
+else
+  info "Release cancelled."
+end

data/script/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/script/test

@@ -0,0 +1,2 @@
+#!/bin/sh
+TESTOPTS="$*" bundle exec rake test

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ivar
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Avdi Grimm
@@ -45,29 +45,65 @@ files:
 - ".augment-guidelines"
 - ".devcontainer/Dockerfile"
 - ".devcontainer/devcontainer.json"
+- ".devcontainer/post-create.sh"
+- ".editorconfig"
+- ".rubocop.yml"
 - ".standard.yml"
 - ".vscode/extensions.json"
+- ".vscode/launch.json"
 - ".vscode/settings.json"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- VERSION.md
+- examples/check_all_block_example.rb
+- examples/check_all_example.rb
+- examples/inheritance_with_kwarg_init.rb
+- examples/inheritance_with_positional_init.rb
+- examples/mixed_positional_and_kwarg_init.rb
+- examples/require_check_all_example.rb
 - examples/sandwich_inheritance.rb
+- examples/sandwich_with_accessors.rb
+- examples/sandwich_with_block_values.rb
 - examples/sandwich_with_checked.rb
 - examples/sandwich_with_checked_once.rb
+- examples/sandwich_with_initial_values.rb
 - examples/sandwich_with_ivar_block.rb
 - examples/sandwich_with_ivar_macro.rb
-- examples/sandwich_with_kwarg.rb
+- examples/sandwich_with_kwarg_init.rb
+- examples/sandwich_with_positional_init.rb
+- examples/sandwich_with_shared_values.rb
+- hooks/README.md
+- hooks/install.sh
+- hooks/pre-commit
 - ivar.gemspec
 - lib/ivar.rb
-- lib/ivar/auto_check.rb
+- lib/ivar/check_all.rb
+- lib/ivar/check_all_manager.rb
+- lib/ivar/check_policy.rb
 - lib/ivar/checked.rb
+- lib/ivar/checked/class_methods.rb
+- lib/ivar/checked/instance_methods.rb
+- lib/ivar/declaration.rb
+- lib/ivar/explicit_declaration.rb
+- lib/ivar/explicit_keyword_declaration.rb
+- lib/ivar/explicit_positional_declaration.rb
 - lib/ivar/macros.rb
+- lib/ivar/manifest.rb
 - lib/ivar/policies.rb
-- lib/ivar/prism_analysis.rb
+- lib/ivar/project_root.rb
+- lib/ivar/targeted_prism_analysis.rb
 - lib/ivar/validation.rb
 - lib/ivar/version.rb
+- script/console
+- script/de-lint
+- script/de-lint-unsafe
+- script/lint
+- script/release
+- script/setup
+- script/test
 - sig/ivar.rbs
 - test_file.rb
 homepage: https://github.com/avdi/ivar
@@ -85,7 +121,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="