strict_ivars 0.5.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65516e69e17c893c02c57e0cc0be683c57c9dc3fd91b80f56942453d5df43649
-  data.tar.gz: 16d3c581474be1f5a7500eb24e442ac8bcd54f55ee5d7afef6cdea3ef986381f
+  metadata.gz: b910c7decefccc4495a320886042153d9178c12f76cda7ccb549c304be2b6725
+  data.tar.gz: 8af1c060ed4ad3b1eef1b306c336a5bac415018f19bc73954e056bb47f9d86ce
 SHA512:
-  metadata.gz: b92fa82ca1acbcef116a5ab531bb1a4ec08301db0b17eb9d5f5a99af47c29face2c82a51d0f63b905eec0a7506e2453b040731848a69afff951f6f44b18e789e
-  data.tar.gz: b650231f2312548af22bd11ecc031dbdcbf178a5ce4f501b29f48687a59209a6533c12a4ef8fe78a351cc03e591bbd3e01c1edf67f03568620279b3990ab0e63
+  metadata.gz: 957162900af7f34fe4e111065f8af1886327a3a3ae5ebdc8de4529869b02d4d71b1d2b27fdbf21ac5aba316e150463d990bdb4c065658b7381d599c520026a9b
+  data.tar.gz: 7748495c8e7a2e7cdddbd39b46bcb4e4d217db9b1f4f070fb810445f17b2fcd260356376ee5a7e936790410f83017dc0fdc232a69bdd1da8515204d39e8401ff

data/README.md

@@ -1,51 +1,58 @@
 # Strict Ivars
 
-Strict Ivars is a tiny pre-processor for Ruby that guards your instance variable reads, ensuring the instance variable is actually defined. This helps catch typos nice and early. It‘s especially good when used with [Literal](https://literal.fun).
+Strict Ivars is a tiny pre-processor for Ruby that guards your instance variable reads, ensuring the instance variable is actually defined. This helps catch typos nice and early. It‘s especially good when used with [Literal](https://literal.fun) and [Phlex](https://www.phlex.fun), though it also works with ERB.
 
-## How does it work?
+> [!NOTE]  
+> JRuby and TruffleRuby are not currently supported.
 
-When Strict Ivars detects that you are loading code from paths its configured to handle, it quickly looks for instance variable reads and guards them with a `defined?` check.
+## Setup
 
-For example, it will replace this:
+Strict Ivars should be used in apps not libraries. Though you could use it in your library’s test suite.
+
+Install the gem by adding it to your `Gemfile` and running `bundle install`. You’ll probably want to set it to `require: false` here because you should require it manually at precisely the right moment.
 
 ```ruby
-def example
-  foo if @bar
-end
+gem "strict_ivars", require: false
 ```
 
-...with something like this:
+Now the gem is installed, you should require and initialize the gem as early as possible in your boot process. Ideally, this should be right after Bootsnap is set up. In Rails, this will be in your `boot.rb` file.
 
 ```ruby
-def example
-  foo if (defined?(@bar) ? @bar : raise)
-end
+require "strict_ivars"
 ```
 
-The replacement happens on load, so you never see this in your source code. It’s also always wrapped in parentheses and takes up a single line, so it won’t mess up the line numbers in exceptions.
+You can pass an array of globs to `StrictIvars.init` as `include:` and `exclude:`
+
+```ruby
+StrictIvars.init(include: ["#{Dir.pwd}/**/*"], exclude: ["#{Dir.pwd}/vendor/**/*"])
+```
+
+This example include everything in the current directory apart from the `./vendor` folder (which is where GitHub Actions installs gems).
+
+If you’re using Bootsnap, you should clear your bootsnap cache by deleting the folder `tmp/cache/bootsnap`.
 
-The real guard is a little uglier than this. It uses `::Kernel.raise` so it’s compatible with `BasicObject`. It also raises a `StrictIvars::NameError` with a helpful message mentioning the name of the instance variable, and that inherits from `NameError`, allowing you to rescue either `NameError` or `StrictIvars::NameError`.
+## How does it work?
 
-**When you check defined already**
+When Strict Ivars detects that you are loading code from paths its configured to handle, it quickly looks for instance variable reads and guards them with a `defined?` check.
 
-Within the same context (e.g. class definition, module definition, block, method), if you check `defined?`, Strict Ivars will not add a guard to reads of the checked instance variable.
+For example, it will replace this:
 
 ```ruby
-if defined?(@foo)
-  @foo
+def example
+  foo if @bar
 end
 ```
 
-This applies even if the read is not in one of the conditional’s branches since you’ve indicated local awareness of the potential for this instance variable not being defined.
+...with something like this:
 
 ```ruby
-if defined?(@foo)
-  # anything
+def example
+  foo if (defined?(@bar) ? @bar : raise)
 end
-
-@foo
 ```
 
+The replacement happens on load, so you never see this in your source code. It’s also always wrapped in parentheses and takes up a single line, so it won’t mess up the line numbers in exceptions.
+
 **Writes:**
 
 Strict Ivars doesn’t apply to writes, since these are considered the authoritative source of the instance variable definitions.
@@ -56,7 +63,7 @@ Strict Ivars doesn’t apply to writes, since these are considered the authorita
 
 **Or-writes:**
 
-This is considered a definition and not guarded.
+Or-writes are considered an authoritative definition, not a read.
 
 ```ruby
 @foo ||= 1
@@ -64,47 +71,67 @@ This is considered a definition and not guarded.
 
 **And-writes:**
 
-This is considered a definition and not guarded.
+And-writes are considered an authoritative definition, not a read.
 
 ```ruby
 @foo &&= 1
 ```
 
-## Setup
-
-Install the gem by adding it to your `Gemfile` and running `bundle install`.
+## Common issues
 
-You may want to set it to `require: false` here because you should require it manually at precisely the right moment.
+#### Implicitly depending on undefined instance variables
 
 ```ruby
-gem "strict_ivars", require: false
+def description
+  return @description if @description.present?
+  @description = get_description
+end
 ```
 
-Now the gem is installed, you should require and initialize the gem as early as possible in your boot process. Ideally, this should be right after Bootsnap is set up. In Rails, this will be in your `boot.rb` file.
+This example is relying on Ruby’s behaviour of returning `nil` for undefiend instance variables, which is completely unnecessary. Instead of using `present?`, we could use `defined?` here.
 
 ```ruby
-require "strict_ivars"
+def description
+  return @description if defined?(@description)
+  @description = get_description
+end
+```
 
-StrictIvars.init(include: ["#{Dir.pwd}/**/*"], exclude: ["#{Dir.pwd}/vendor/**/*"])
+Alternatively, as long as `get_description` doesn’t return `nil` and expect us to memoize it, we could use an “or-write” `||=`
+
+```ruby
+def description
+  @description ||= get_description
+end
 ```
 
-You can pass an array of globs to `include:` and `exclude:`.
+#### Rendering instance variables that are only set somtimes
+
+It’s common to render an instance variable in an ERB view that you only set on some controllers.
 
-## Compatibility
+```erb
+<div data-favourites="<%= @user_favourites %>"></div>
+```
 
-Because Strict Ivars only transforms the source code that matches your include paths and becuase the check happens at runtime, it’s completely compatible with the rest of the Ruby ecosystem.
+The best solution to this to always set it on all controllers, but set it to `nil` in the cases where you don’t have anything to render. This will prevent you from making a typo in your views.
 
-#### For apps
+Alternatively, you could update the view to be explicit about the fact this ivar may not be set.
 
-Strict Ivars is really designed for apps, where you control the boot process and you want some extra safety in the code you and your team writes.
+```erb
+<div data-favourites="<%= (@user_favourites ||= nil) %>"></div>
+```
 
-#### For libraries
+Better yet, add a `defined?` check:
 
-You could use Strict Ivars as a dev dependency in your gem’s test suite, but I don’t recommend initializing Strict Ivars in a library directly.
+```erb
+<% if defined?(@user_favourites) %>
+  <div data-favourites="<%= @user_favourites %>"></div>
+<% end %>
+```
 
 ## Performance
 
-#### Startup performance
+#### Boot performance
 
 Using Strict Ivars will impact startup performance since it needs to process each Ruby file you require. However, if you are using Bootsnap, the processed RubyVM::InstructionSequences will be cached and you probably won’t notice the incremental cache misses day-to-day.
 
@@ -112,12 +139,14 @@ Using Strict Ivars will impact startup performance since it needs to process eac
 
 In my benchmarks on Ruby 3.4 with YJIT, it’s difficult to tell if there is any performance difference with or without the `defined?` guards at runtime. Sometimes it’s about 1% faster with the guards than without. Sometimes the other way around.
 
-On my laptop, a method that returns an instance varible takes about 15ns and a method that checks if an instance varible is defined and then returns it takes about 15ns.
+On my laptop, a method that returns an instance varible takes about 15ns and a method that checks if an instance varible is defined and then returns it takes about 15ns. All this is to say, I don’t think there will be any measurable runtime performance impact, at least not in Ruby 3.4.
+
+#### Dynamic evals
 
-All this is to say, I don’t think there will be any measurable runtime performance impact.
+There is a small additional cost to dynamically evaluating code via `eval`, `class_eval`, `module_eval`, `instance_eval` and `binding.eval`. Dynamic evaluation usually only happens at boot time but it can happen at runtime depending on how you use it.
 
 ## Uninstall
 
 Becuase Strict Ivars only ever makes your code safer, you can always back out without anything breaking.
 
-To uninstall Strict Ivars, first remove the require and initialization code from wherever you added it and then remove the gem from your `Gemfile`. If you were using Bootsnap, there’s a good chance it cached some pre-processed code with the instance variable read guards in it. To clear this, you’ll need to delete your bootsnap cache, which should be in `tmp/cache/bootsnap`.
+To uninstall Strict Ivars, first remove the require and initialization code from wherever you added it and then remove the gem from your `Gemfile`. If you are using Bootsnap, there’s a good chance it cached some pre-processed code with the instance variable read guards in it. To clear this, you’ll need to delete your bootsnap cache, which should be in `tmp/cache/bootsnap`.

data/lib/strict_ivars/base_processor.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+class StrictIvars::BaseProcessor < Prism::Visitor
+	EVAL_METHODS = Set[:class_eval, :module_eval, :instance_eval, :eval].freeze
+
+	#: (String) -> String
+	def self.call(source)
+		visitor = new
+		visitor.visit(Prism.parse(source).value)
+		buffer = source.dup
+		annotations = visitor.annotations
+		annotations.sort_by!(&:first)
+
+		annotations.reverse_each do |offset, string|
+			buffer.insert(offset, string)
+		end
+
+		buffer
+	end
+
+	def initialize
+		@context = Set[]
+		@annotations = []
+	end
+
+	#: Array[[Integer, :start_ivar_read | :end_ivar_read, Symbol]]
+	attr_reader :annotations
+
+	def visit_call_node(node)
+		name = node.name
+
+		if EVAL_METHODS.include?(name) && (arguments = node.arguments)
+			location = arguments.location
+
+			if node.receiver
+				receiver_local = "__eval_receiver_#{SecureRandom.hex(8)}__"
+				receiver_location = node.receiver.location
+
+				@annotations.push(
+					[receiver_location.start_character_offset, "(#{receiver_local} = "],
+					[receiver_location.end_character_offset, ")"],
+					[location.start_character_offset, "*(::StrictIvars.__process_eval_args__(#{receiver_local}, :#{name}, "],
+					[location.end_character_offset, "))"]
+				)
+			else
+				@annotations.push(
+					[location.start_character_offset, "*(::StrictIvars.__process_eval_args__(self, :#{name}, "],
+					[location.end_character_offset, "))"]
+				)
+			end
+		end
+
+		super
+	end
+end

data/lib/strict_ivars/configuration.rb

@@ -22,7 +22,8 @@ class StrictIvars::Configuration
 	end
 
 	#: (String) -> bool
-	def match(path)
+	def match?(path)
+		return false unless String === path
 		path = File.absolute_path(path)
 		return false if @exclude.any? { |pattern| File.fnmatch?(pattern, path) }
 		return true if @include.any? { |pattern| File.fnmatch?(pattern, path) }

data/lib/strict_ivars/processor.rb

@@ -1,36 +1,6 @@
 # frozen_string_literal: true
 
-class StrictIvars::Processor < Prism::Visitor
-	#: (String) -> String
-	def self.call(source)
-		visitor = new
-		visitor.visit(Prism.parse(source).value)
-		buffer = source.dup
-		annotations = visitor.annotations
-		annotations.sort_by!(&:first)
-
-		annotations.reverse_each do |offset, action, name|
-			case action
-			when :start
-				buffer.insert(offset, "(defined?(#{name}) ? ")
-			when :end
-				buffer.insert(offset, " : (::Kernel.raise(::StrictIvars::NameError.new('Undefined instance variable #{name}'))))")
-			else
-				raise "Invalid annotation"
-			end
-		end
-
-		buffer
-	end
-
-	def initialize
-		@context = Set[]
-		@annotations = []
-	end
-
-	#: Array[[Integer, :start | :end, Symbol]]
-	attr_reader :annotations
-
+class StrictIvars::Processor < StrictIvars::BaseProcessor
 	#: (Prism::ClassNode) -> void
 	def visit_class_node(node)
 		new_context { super }
@@ -51,17 +21,6 @@ class StrictIvars::Processor < Prism::Visitor
 		new_context { super }
 	end
 
-	#: (Prism::DefinedNode) -> void
-	def visit_defined_node(node)
-		value = node.value
-
-		if Prism::InstanceVariableReadNode === value
-			@context << value.name
-		end
-
-		super
-	end
-
 	#: (Prism::DefNode) -> void
 	def visit_def_node(node)
 		new_context { super }
@@ -95,9 +54,10 @@ class StrictIvars::Processor < Prism::Visitor
 
 			@context << name
 
-			@annotations <<
-				[location.start_character_offset, :start, name] <<
-				[location.end_character_offset, :end, name]
+			@annotations.push(
+				[location.start_character_offset, "(defined?(#{name}) ? "],
+				[location.end_character_offset, " : (::Kernel.raise(::StrictIvars::NameError.new('Undefined instance variable #{name}'))))"]
+			)
 		end
 
 		super

data/lib/strict_ivars/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StrictIvars
-	VERSION = "0.5.0"
+	VERSION = "1.0.0.rc1"
 end

data/lib/strict_ivars.rb

@@ -3,28 +3,83 @@
 require "prism"
 require "require-hooks/setup"
 require "strict_ivars/version"
+require "strict_ivars/base_processor"
+require "strict_ivars/processor"
 require "strict_ivars/configuration"
 
 module StrictIvars
 	NameError = Class.new(::NameError)
 
+	EMPTY_ARRAY = [].freeze
+	EVERYTHING = ["**/*"].freeze
+	METHOD_METHOD = Module.instance_method(:method)
+
 	CONFIG = Configuration.new
 
+	# Initializes StrictIvars so that code loaded after this point will be
+	# guarded against undefined instance variable reads. You can pass an array
+	# of globs to `include:` and `exclude:`.
+	#
+	# ```ruby
+	# StrictIvars.init(
+	#   include: ["#{Dir.pwd}/**/*"],
+	#   exclude: ["#{Dir.pwd}/vendor/**/*"]
+	# )
+	# ```
 	#: (include: Array[String], exclude: Array[String]) -> void
-	def self.init(include: [], exclude: [])
-		require "strict_ivars/patch_eval"
-
-		CONFIG.include(*include)
-		CONFIG.exclude(*exclude)
+	def self.init(include: EMPTY_ARRAY, exclude: EMPTY_ARRAY)
+		CONFIG.include(*include) unless include.length == 0
+		CONFIG.exclude(*exclude) unless exclude.length == 0
 
 		RequireHooks.source_transform(
-			patterns: include,
-			exclude_patterns: exclude
+			patterns: EVERYTHING,
+			exclude_patterns: EMPTY_ARRAY
 		) do |path, source|
 			source ||= File.read(path)
-			Processor.call(source)
+
+			if CONFIG.match?(path)
+				Processor.call(source)
+			else
+				BaseProcessor.call(source)
+			end
 		end
 	end
-end
 
-require "strict_ivars/processor"
+	# For internal use only. This method pre-processes arguments to an eval method.
+	#: (Object, Symbol, *untyped)
+	def self.__process_eval_args__(receiver, method_name, *args)
+		method = METHOD_METHOD.bind_call(receiver, method_name)
+		owner = method.owner
+
+		source, file = nil
+
+		case method_name
+		when :class_eval, :module_eval
+			if Module == owner
+				source, file = args
+			end
+		when :instance_eval
+			if BasicObject == owner
+				source, file = args
+			end
+		when :eval
+			if Kernel == owner
+				source, binding, file = args
+			elsif Binding == owner
+				source, file = args
+			end
+		end
+
+		if String === source
+			file ||= caller_locations(1, 1).first&.path
+
+			if CONFIG.match?(file)
+				args[0] = Processor.call(source)
+			else
+				args[0] = BaseProcessor.call(source)
+			end
+		end
+
+		args
+	end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strict_ivars
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Joel Drapper
@@ -47,8 +47,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/strict_ivars.rb
+- lib/strict_ivars/base_processor.rb
 - lib/strict_ivars/configuration.rb
-- lib/strict_ivars/patch_eval.rb
 - lib/strict_ivars/processor.rb
 - lib/strict_ivars/version.rb
 homepage: https://github.com/joeldrapper/strict_ivars

data/lib/strict_ivars/patch_eval.rb

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-
-module StrictIvars
-	module ModuleEvalPatch
-		#: (String, ?String, ?Integer) -> void
-		#: () { () -> void } -> void
-		def class_eval(*args)
-			source, file, lineno = args
-
-			file ||= caller_locations(1, 1).first.path
-
-			if source && file && CONFIG.match(file)
-				args[0] = Processor.call(source)
-			end
-
-			super
-		end
-
-		#: (String, ?String, ?Integer) -> void
-		#: () { () -> void } -> void
-		def module_eval(*args)
-			source, file, lineno = args
-
-			file ||= caller_locations(1, 1).first.path
-
-			if source && file && CONFIG.match(file)
-				args[0] = Processor.call(source)
-			end
-
-			super
-		end
-	end
-
-	module InstanceEvalPatch
-		#: (String, ?String, ?Integer) -> void
-		#: () { () -> void } -> void
-		def instance_eval(*args)
-			source, file, lineno = args
-
-			file ||= caller_locations(1, 1).first.path
-
-			if source && file && CONFIG.match(file)
-				args[0] = Processor.call(source)
-			end
-
-			super
-		end
-	end
-
-	module KernelEvalPatch
-		#: (String, Binding, ?String, ?Integer) -> void
-		def eval(*args)
-			source, binding, file, lineno = args
-
-			file ||= caller_locations(1, 1).first.path
-
-			if source && file && CONFIG.match(file)
-				args[0] = Processor.call(source.to_s)
-			end
-
-			super
-		end
-	end
-
-	module BindingEvalPatch
-		#: (String, ?String, ?Integer) -> void
-		def eval(*args)
-			source, file, lineno = args
-
-			file ||= caller_locations(1, 1).first.path
-
-			if source && file && CONFIG.match(file)
-				args[0] = Processor.call(source.to_s)
-			end
-
-			super
-		end
-	end
-
-	Kernel.prepend(KernelEvalPatch)
-	Module.prepend(ModuleEvalPatch)
-	Binding.prepend(BindingEvalPatch)
-	BasicObject.prepend(InstanceEvalPatch)
-end