strict_ivars 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e9fa5d49d58c37b01f9c2e11b74ebea9809bfd880a4a3a86fc37894727bedb6
-  data.tar.gz: acd5fcdc8320f9f1c2f972915b0d72ed7f1e21516d1790f77f91bcd345f5e7d9
+  metadata.gz: 65516e69e17c893c02c57e0cc0be683c57c9dc3fd91b80f56942453d5df43649
+  data.tar.gz: 16d3c581474be1f5a7500eb24e442ac8bcd54f55ee5d7afef6cdea3ef986381f
 SHA512:
-  metadata.gz: c382d756d7d25ad5ce12706a0e80a886e4d8759616e8c2d505cdd40a7dd735d21e09a1c07c325062edd452e66a3aeae4b9a560cb08296a654e027b8d07949b84
-  data.tar.gz: 415b00bd3f828d6b8f211774476f88e0f37ee4ed4c14d1211daf2ae68d75aa027bf60bcc79fd0ee84cd7958422780a60b715a69f8a93502ff3f63acb33b01052
+  metadata.gz: b92fa82ca1acbcef116a5ab531bb1a4ec08301db0b17eb9d5f5a99af47c29face2c82a51d0f63b905eec0a7506e2453b040731848a69afff951f6f44b18e789e
+  data.tar.gz: b650231f2312548af22bd11ecc031dbdcbf178a5ce4f501b29f48687a59209a6533c12a4ef8fe78a351cc03e591bbd3e01c1edf67f03568620279b3990ab0e63

data/README.md

@@ -1,39 +1,123 @@
-# StrictIvars
+# Strict Ivars
 
-StrictIvars is a tiny pre-processor for Ruby that guards your instance variable reads, ensuring the instance variable is actually defined. This helps catch typos early.
+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).
 
 ## How does it work?
 
-When StrictIvars 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.
+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.
 
 For example, it will replace this:
 
 ```ruby
 def example
-	foo if @bar
+  foo if @bar
 end
 ```
 
-with something like this:
+...with something like this:
 
 ```ruby
-	def example
-		foo if (raise unless defined?(@bar); @bar)
-	end
+def example
+  foo if (defined?(@bar) ? @bar : raise)
+end
+```
+
+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.
+
+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`.
+
+**When you check defined already**
+
+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.
+
+```ruby
+if defined?(@foo)
+  @foo
+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.
+
+```ruby
+if defined?(@foo)
+  # anything
+end
+
+@foo
+```
+
+**Writes:**
+
+Strict Ivars doesn’t apply to writes, since these are considered the authoritative source of the instance variable definitions.
+
+```ruby
+@foo = 1
+```
+
+**Or-writes:**
+
+This is considered a definition and not guarded.
+
+```ruby
+@foo ||= 1
+```
+
+**And-writes:**
+
+This is considered a definition and not guarded.
+
+```ruby
+@foo &&= 1
 ```
 
 ## Setup
 
-Install the gem by adding it to your `Gemfile` and running `bundle install`. You may want to set it to `require: false` because you need to require it at the right moment.
+Install the gem by adding it to your `Gemfile` and running `bundle install`.
+
+You may want to set it to `require: false` here because you should require it manually at precisely the right moment.
 
 ```ruby
 gem "strict_ivars", require: false
 ```
 
-Then require and initialize the gem as early as possible in your boot process. Ideally, this should be right after bootsnap.
+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
 require "strict_ivars"
 
-StrictIvars.init(include: ["#{Dir.pwd}/**/*"])
+StrictIvars.init(include: ["#{Dir.pwd}/**/*"], exclude: ["#{Dir.pwd}/vendor/**/*"])
 ```
+
+You can pass an array of globs to `include:` and `exclude:`.
+
+## Compatibility
+
+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.
+
+#### For apps
+
+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.
+
+#### For libraries
+
+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.
+
+## Performance
+
+#### Startup 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.
+
+#### Runtime performance
+
+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.
+
+All this is to say, I don’t think there will be any measurable runtime performance impact.
+
+## 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`.

data/lib/strict_ivars/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class StrictIvars::Configuration
+	def initialize
+		@mutex = Mutex.new
+		@include = []
+		@exclude = []
+	end
+
+	#: (*String) -> void
+	def include(*patterns)
+		@mutex.synchronize do
+			@include.concat(patterns)
+		end
+	end
+
+	#: (*String) -> void
+	def exclude(*patterns)
+		@mutex.synchronize do
+			@exclude.concat(patterns)
+		end
+	end
+
+	#: (String) -> bool
+	def match(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) }
+		false
+	end
+end

data/lib/strict_ivars/patch_eval.rb

@@ -0,0 +1,84 @@
+# 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

data/lib/strict_ivars/processor.rb

@@ -1,18 +1,20 @@
 # 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)
 
-		visitor.annotations.sort_by(&:first).reverse_each do |offset, action, name|
+		annotations.reverse_each do |offset, action, name|
 			case action
 			when :start
-				buffer.insert(offset, "((::Kernel.raise ::StrictIvars::NameError.new('Undefined instance variable #{name}') unless defined?(#{name})); ")
+				buffer.insert(offset, "(defined?(#{name}) ? ")
 			when :end
-				buffer.insert(offset, ")")
+				buffer.insert(offset, " : (::Kernel.raise(::StrictIvars::NameError.new('Undefined instance variable #{name}'))))")
 			else
 				raise "Invalid annotation"
 			end
@@ -26,36 +28,46 @@ class StrictIvars::Processor < Prism::Visitor
 		@annotations = []
 	end
 
+	#: Array[[Integer, :start | :end, Symbol]]
 	attr_reader :annotations
 
+	#: (Prism::ClassNode) -> void
 	def visit_class_node(node)
 		new_context { super }
 	end
 
+	#: (Prism::ModuleNode) -> void
 	def visit_module_node(node)
 		new_context { super }
 	end
 
+	#: (Prism::BlockNode) -> void
 	def visit_block_node(node)
 		new_context { super }
 	end
 
+	#: (Prism::SingletonClassNode) -> void
 	def visit_singleton_class_node(node)
 		new_context { super }
 	end
 
+	#: (Prism::DefinedNode) -> void
 	def visit_defined_node(node)
-		if Prism::InstanceVariableReadNode === node.value
-			@context << node.value.name
+		value = node.value
+
+		if Prism::InstanceVariableReadNode === value
+			@context << value.name
 		end
 
 		super
 	end
 
+	#: (Prism::DefNode) -> void
 	def visit_def_node(node)
 		new_context { super }
 	end
 
+	#: (Prism::IfNode) -> void
 	def visit_if_node(node)
 		visit(node.predicate)
 
@@ -63,6 +75,7 @@ class StrictIvars::Processor < Prism::Visitor
 		branch { visit(node.subsequent) }
 	end
 
+	#: (Prism::CaseNode) -> void
 	def visit_case_node(node)
 		visit(node.predicate)
 
@@ -73,6 +86,7 @@ class StrictIvars::Processor < Prism::Visitor
 		branch { visit(node.else_clause) }
 	end
 
+	#: (Prism::InstanceVariableReadNode) -> void
 	def visit_instance_variable_read_node(node)
 		name = node.name
 
@@ -81,13 +95,15 @@ class StrictIvars::Processor < Prism::Visitor
 
 			@context << name
 
-			@annotations << [location.start_character_offset, :start, name]
-			@annotations << [location.end_character_offset, :end, name]
+			@annotations <<
+				[location.start_character_offset, :start, name] <<
+				[location.end_character_offset, :end, name]
 		end
 
 		super
 	end
 
+	#: () { () -> void } -> void
 	private def new_context
 		original_context = @context
 
@@ -100,6 +116,7 @@ class StrictIvars::Processor < Prism::Visitor
 		end
 	end
 
+	#: () { () -> void } -> void
 	private def branch
 		original_context = @context
 		@context = original_context.dup

data/lib/strict_ivars/version.rb

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

data/lib/strict_ivars.rb

@@ -2,11 +2,21 @@
 
 require "prism"
 require "require-hooks/setup"
+require "strict_ivars/version"
+require "strict_ivars/configuration"
 
 module StrictIvars
 	NameError = Class.new(::NameError)
 
+	CONFIG = Configuration.new
+
+	#: (include: Array[String], exclude: Array[String]) -> void
 	def self.init(include: [], exclude: [])
+		require "strict_ivars/patch_eval"
+
+		CONFIG.include(*include)
+		CONFIG.exclude(*exclude)
+
 		RequireHooks.source_transform(
 			patterns: include,
 			exclude_patterns: exclude

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strict_ivars
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Joel Drapper
@@ -13,16 +13,16 @@ dependencies:
   name: require-hooks
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: prism
   requirement: !ruby/object:Gem::Requirement
@@ -47,6 +47,8 @@ files:
 - LICENSE.txt
 - README.md
 - lib/strict_ivars.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