strict_ivars 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e9fa5d49d58c37b01f9c2e11b74ebea9809bfd880a4a3a86fc37894727bedb6
+  data.tar.gz: acd5fcdc8320f9f1c2f972915b0d72ed7f1e21516d1790f77f91bcd345f5e7d9
+SHA512:
+  metadata.gz: c382d756d7d25ad5ce12706a0e80a886e4d8759616e8c2d505cdd40a7dd735d21e09a1c07c325062edd452e66a3aeae4b9a560cb08296a654e027b8d07949b84
+  data.tar.gz: 415b00bd3f828d6b8f211774476f88e0f37ee4ed4c14d1211daf2ae68d75aa027bf60bcc79fd0ee84cd7958422780a60b715a69f8a93502ff3f63acb33b01052

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Joel Drapper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+# StrictIvars
+
+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.
+
+## 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.
+
+For example, it will replace this:
+
+```ruby
+def example
+	foo if @bar
+end
+```
+
+with something like this:
+
+```ruby
+	def example
+		foo if (raise unless defined?(@bar); @bar)
+	end
+```
+
+## 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.
+
+```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.
+
+```ruby
+require "strict_ivars"
+
+StrictIvars.init(include: ["#{Dir.pwd}/**/*"])
+```

data/lib/strict_ivars/processor.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+class StrictIvars::Processor < Prism::Visitor
+	def self.call(source)
+		visitor = new
+		visitor.visit(Prism.parse(source).value)
+
+		buffer = source.dup
+
+		visitor.annotations.sort_by(&:first).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})); ")
+			when :end
+				buffer.insert(offset, ")")
+			else
+				raise "Invalid annotation"
+			end
+		end
+
+		buffer
+	end
+
+	def initialize
+		@context = Set[]
+		@annotations = []
+	end
+
+	attr_reader :annotations
+
+	def visit_class_node(node)
+		new_context { super }
+	end
+
+	def visit_module_node(node)
+		new_context { super }
+	end
+
+	def visit_block_node(node)
+		new_context { super }
+	end
+
+	def visit_singleton_class_node(node)
+		new_context { super }
+	end
+
+	def visit_defined_node(node)
+		if Prism::InstanceVariableReadNode === node.value
+			@context << node.value.name
+		end
+
+		super
+	end
+
+	def visit_def_node(node)
+		new_context { super }
+	end
+
+	def visit_if_node(node)
+		visit(node.predicate)
+
+		branch { visit(node.statements) }
+		branch { visit(node.subsequent) }
+	end
+
+	def visit_case_node(node)
+		visit(node.predicate)
+
+		node.conditions.each do |condition|
+			branch { visit(condition) }
+		end
+
+		branch { visit(node.else_clause) }
+	end
+
+	def visit_instance_variable_read_node(node)
+		name = node.name
+
+		unless @context.include?(name)
+			location = node.location
+
+			@context << name
+
+			@annotations << [location.start_character_offset, :start, name]
+			@annotations << [location.end_character_offset, :end, name]
+		end
+
+		super
+	end
+
+	private def new_context
+		original_context = @context
+
+		@context = Set[]
+
+		begin
+			yield
+		ensure
+			@context = original_context
+		end
+	end
+
+	private def branch
+		original_context = @context
+		@context = original_context.dup
+
+		begin
+			yield
+		ensure
+			@context = original_context
+		end
+	end
+end

data/lib/strict_ivars/version.rb

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

data/lib/strict_ivars.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "prism"
+require "require-hooks/setup"
+
+module StrictIvars
+	NameError = Class.new(::NameError)
+
+	def self.init(include: [], exclude: [])
+		RequireHooks.source_transform(
+			patterns: include,
+			exclude_patterns: exclude
+		) do |path, source|
+			source ||= File.read(path)
+			Processor.call(source)
+		end
+	end
+end
+
+require "strict_ivars/processor"

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: strict_ivars
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Joel Drapper
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: require-hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Raise an exception when using undefined instance variables.
+email:
+- joel@drapper.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/strict_ivars.rb
+- lib/strict_ivars/processor.rb
+- lib/strict_ivars/version.rb
+homepage: https://github.com/joeldrapper/strict_ivars
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/joeldrapper/strict_ivars
+  source_code_uri: https://github.com/joeldrapper/strict_ivars
+  funding_uri: https://github.com/sponsors/joeldrapper
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Raise an exception when using undefined instance variables.
+test_files: []