strict_ivars 1.0.0.rc3 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 937599360a03f578b3d440efc2d58eede817bc6ec71727f4ba74c1c0fb11dc0d
-  data.tar.gz: cb212c70dab8bcf3a9d163f80f864ddf81c8f0a0e3e2ae6781f2bcff37590b88
+  metadata.gz: 5a6e9c3b4af8b1558193b058b36ab883ecc8dbce111b13bafb0cedd54852faa9
+  data.tar.gz: 22858692a9849c8f1f3b33450fe78054a622216221d81edd7992868a530dfc3c
 SHA512:
-  metadata.gz: 53fdba71a8e909d0afc5b797b1b4b7658a5ab956fab7946e1ead3e59be9298c5928a1b788c2be3781c46df3e2bb28505b5ca911357026aa0992c9f57a45e81e5
-  data.tar.gz: 86d26b307d4697843d10216e7c783a5db2207945ed3bb7a9e70959dd120e9652249dfef523b2803905728c1e4f4ed1de180a50c472f983068fbb38147367996a
+  metadata.gz: b52c5c582936f6905a00b381846109d673b6ff8b9a6c7f568d4c8bab82b60c8158afbf3924628d93ee133e5d98583169462ac42887a8f50e0c96068c23a450ea
+  data.tar.gz: 0b0d00db3c3daf0dd7c72ad2c3702e57240dcd93a5965d7b0e18b97ba56f5ec53dffc42cf4a7d845adc03ff0cd09c8f9c777d25d2c711be1c26de357583de977

data/README.md

@@ -1,13 +1,19 @@
 # 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) and [Phlex](https://www.phlex.fun), though it also works with ERB.
+If you reference an undefined method, constant or local varaible, Ruby will helpfully raise a `NameError`. But reference an undefined _instance_ variable and Ruby just returns `nil`. This can lead to all kinds of bugs — many of which can lay dormant for years before surprising you with an unexpected outage, data breach or data loss event.
 
-> [!NOTE]  
+Strict Ivars solves this by making Ruby raise a `NameError` any time you read an undefined instance varaible. It’s enabled with two lines of code in your boot process, then it just works in the background and you’ll never have to think about it again. Strict Ivars has no known false-positives or false-negatives.
+
+It’s especially good when used with [Literal](https://literal.fun) and [Phlex](https://www.phlex.fun), though it also works with regular Ruby objects and even ERB templates, which are actually pretty common spots for undefined instance variable reads to hide since that’s the main way of passing data to ERB.
+
+When combined with Literal, you can essentially remove all unexpected `nil`s. Literal validates your inputs and Strict Ivars ensures you’re reading the right instance variables.
+
+> [!NOTE]
 > JRuby and TruffleRuby are not currently supported.
 
 ## Setup
 
-Strict Ivars should be used in apps not libraries. Though you could use it in your library’s test suite.
+Strict Ivars should really be used in apps not libraries. Though you could definitely use it in your library’s test suite to help catch issues in the library code.
 
 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.
 
@@ -29,6 +35,19 @@ 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 setting this up in Rails, your `boot.rb` file should look something like this.
+
+```ruby
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "bundler/setup" # Set up gems listed in the Gemfile.
+require "bootsnap/setup" # Speed up boot time by caching expensive operations.
+
+require "strict_ivars"
+
+StrictIvars.init(include: ["#{Dir.pwd}/**/*"], exclude: ["#{Dir.pwd}/vendor/**/*"])
+```
+
 If you’re using Bootsnap, you should clear your bootsnap cache by deleting the folder `tmp/cache/bootsnap`.
 
 ## How does it work?

data/lib/strict_ivars/name_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "did_you_mean/spell_checker"
+
+class StrictIvars::NameError < ::NameError
+	INSTANCE_VARIABLE_METHOD = Kernel.instance_method(:instance_variables)
+
+	def initialize(object, name)
+		checker = DidYouMean::SpellChecker.new(
+			dictionary: INSTANCE_VARIABLE_METHOD.bind_call(object)
+		)
+
+		suggestion = checker.correct(name).first
+
+		message = [
+			"Undefined instance variable `#{name}`.",
+			("Did you mean `#{suggestion}`?" if suggestion),
+		].join(" ")
+
+		super(message)
+	end
+end

data/lib/strict_ivars/processor.rb

@@ -65,7 +65,7 @@ class StrictIvars::Processor < StrictIvars::BaseProcessor
 
 			@annotations.push(
 				[location.start_character_offset, "(defined?(#{name}) ? "],
-				[location.end_character_offset, " : (::Kernel.raise(::StrictIvars::NameError.new('Undefined instance variable #{name}'))))"]
+				[location.end_character_offset, " : (::Kernel.raise(::StrictIvars::NameError.new(self, :#{name}))))"]
 			)
 		end
 

data/lib/strict_ivars/version.rb

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

data/lib/strict_ivars.rb

@@ -4,16 +4,15 @@ require "set"
 require "prism"
 require "securerandom"
 
-require "require-hooks/setup"
-
 require "strict_ivars/version"
+require "strict_ivars/name_error"
 require "strict_ivars/base_processor"
 require "strict_ivars/processor"
 require "strict_ivars/configuration"
 
-module StrictIvars
-	NameError = Class.new(::NameError)
+require "require-hooks/setup"
 
+module StrictIvars
 	EMPTY_ARRAY = [].freeze
 	EVERYTHING = ["**/*"].freeze
 	METHOD_METHOD = Module.instance_method(:method)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: strict_ivars
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc3
+  version: 1.0.1
 platform: ruby
 authors:
 - Joel Drapper
@@ -37,7 +37,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Raise an exception when using undefined instance variables.
+description: Strict Ivars is a tiny pre-processor that guards you against undefined
+  instance variable reads. If you do read an undefined instance variable, it will
+  raise a NameError.
 email:
 - joel@drapper.me
 executables: []
@@ -49,14 +51,15 @@ files:
 - lib/strict_ivars.rb
 - lib/strict_ivars/base_processor.rb
 - lib/strict_ivars/configuration.rb
+- lib/strict_ivars/name_error.rb
 - lib/strict_ivars/processor.rb
 - lib/strict_ivars/version.rb
-homepage: https://github.com/joeldrapper/strict_ivars
+homepage: https://github.com/yippee-fun/strict_ivars
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/joeldrapper/strict_ivars
-  source_code_uri: https://github.com/joeldrapper/strict_ivars
+  homepage_uri: https://github.com/yippee-fun/strict_ivars
+  source_code_uri: https://github.com/yippee-fun/strict_ivars
   funding_uri: https://github.com/sponsors/joeldrapper
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -75,5 +78,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: Raise an exception when using undefined instance variables.
+summary: Make Ruby raise a NameError if you read an undefined instance variable.
 test_files: []