empirical 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c9b64cdbca71cda53eac79ca46ed80f2e2d0e19901dfa5b7b675c0465c3f4eb
-  data.tar.gz: c8abbdbbdb0cc7dd461e810ee398a8046f259fdc78a1c7b6aa117749c6263f38
+  metadata.gz: 7fede1fc1d6079a9a1b13ae0875ac41bf61a6b7fe812688ca06e8ccd4e1cb9f5
+  data.tar.gz: cadaa32b10e496014d25418b594dd0195958e8aa15eee50f45549a1390cf9012
 SHA512:
-  metadata.gz: 114a23808cdb5746bfcc791207a80693900c960ef37870f0370c35b3c0bc6d215fff22f59ba9b57516002a31f56d20a76b8982473606da9421dffe9cff585876
-  data.tar.gz: da7ef76d2913b4be14a5dc08ce01a8a4f01fba6d103500eb197c7604cb38dcb12d9f0e23dd24a6d8e9381bd547db6e24bf9876418b42b9e75431d55e1723fbbd
+  metadata.gz: 8a5371864bd72f10a9a65648ea13227af2e621978018f151d6d4dae360d08dd909d105663d0954a98f378c2d464b1d46fc5cca098ae547c5148319f7f6acac95
+  data.tar.gz: 6fa32faa04f2e919616ee06a0e4fe60e3c0b316eb5e07936eb16dac1a5fd6200aace0e8b821b43c62bf5902a3eb7a65b6f0d3af5646d478ea182dca34beba808

data/README.md

@@ -1,21 +1,27 @@
-# Strict Ivars
+# Empirical
 
-If you reference an undefined method, constant or local varaible, Ruby will helpfully raise an error. 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.
+> (_adjective_) based on what is experienced or seen rather than on theory \
+> (_noun_) enhancements for Ruby with a runtime type system
 
-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.
+Empirical catches bugs early and makes your code self-documenting by enhancing Ruby with beautiful syntax to define runtime type assertions.
 
-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.
+```ruby
+fun word_frequency(text: String) => _Hash(String, Integer) do
+  text
+    .downcase
+    .scan(/\w+/)
+    .tally
+    .sort_by { |word, count| -count }
+    .first(10)
+    .to_h
+end
+```
 
-> [!NOTE]
-> JRuby and TruffleRuby are not currently supported.
+(see [below](#runtime-typing)).
 
 ## Setup
 
-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.
+Install the gem by adding it to your <kbd>Gemfile</kbd> and running <kbd>bundle install</kbd>. You’ll probably want to set it to `require: false` here because you should require it manually at precisely the right moment.
 
 ```ruby
 gem "empirical", require: false
@@ -32,144 +38,3 @@ You can pass an array of globs to `Empirical.init` as `include:` and `exclude:`
 ```ruby
 Empirical.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 "empirical"
-
-Empirical.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?
-
-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
-end
-```
-
-...with something like this:
-
-```ruby
-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.
-
-**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:**
-
-Or-writes are considered an authoritative definition, not a read.
-
-```ruby
-@foo ||= 1
-```
-
-**And-writes:**
-
-And-writes are considered an authoritative definition, not a read.
-
-```ruby
-@foo &&= 1
-```
-
-## Common mistakes
-
-#### Implicitly depending on undefined instance variables
-
-```ruby
-def description
-  return @description if @description.present?
-  @description = get_description
-end
-```
-
-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
-def description
-  return @description if defined?(@description)
-  @description = get_description
-end
-```
-
-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
-```
-
-#### 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.
-
-```erb
-<div data-favourites="<%= @user_favourites %>"></div>
-```
-
-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.
-
-Alternatively, you could update the view to be explicit about the fact this ivar may not be set.
-
-```erb
-<div data-favourites="<%= (@user_favourites ||= nil) %>"></div>
-```
-
-Better yet, add a `defined?` check:
-
-```erb
-<% if defined?(@user_favourites) %>
-  <div data-favourites="<%= @user_favourites %>"></div>
-<% end %>
-```
-
-## 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.
-
-#### 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, at least not in Ruby 3.4.
-
-#### Dynamic evals
-
-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.
-
-## Stability
-
-Strict Ivars has 100% line and branch coverage and there are no known false-positives, false-negatives or bugs.
-
-## 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 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/empirical/base_processor.rb

@@ -3,59 +3,8 @@
 class Empirical::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, length, string|
-			buffer[offset, length] = string
-		end
-
-		buffer
-	end
-
-	def initialize
+	def initialize(annotations:)
 		@context = Set[]
-		@annotations = []
-	end
-
-	#: Array[[Integer, String]]
-	attr_reader :annotations
-
-	def visit_call_node(node)
-		name = node.name
-
-		if EVAL_METHODS.include?(name) && (arguments = node.arguments)
-			location = arguments.location
-
-			closing = if arguments.contains_forwarding?
-				")), &(::Empirical.__eval_block_from_forwarding__(...))"
-			else
-				"))"
-			end
-
-			if node.receiver
-				receiver_local = "__eval_receiver_#{SecureRandom.hex(8)}__"
-				receiver_location = node.receiver.location
-
-				@annotations.push(
-					[receiver_location.start_character_offset, 0, "(#{receiver_local} = "],
-					[receiver_location.end_character_offset, 0, ")"],
-					[location.start_character_offset, 0, "*(::Empirical.__process_eval_args__(#{receiver_local}, :#{name}, "],
-					[location.end_character_offset, 0, closing]
-				)
-			else
-				@annotations.push(
-					[location.start_character_offset, 0, "*(::Empirical.__process_eval_args__(self, :#{name}, "],
-					[location.end_character_offset, 0, closing]
-				)
-			end
-		end
-
-		super
+		@annotations = annotations
 	end
 end

data/lib/empirical/class_callbacks_processor.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Ensure the new callback methods exist on the base classes.
+# Developers can define their own callback methods in their classes/modules.
+class Module
+	def module_defined
+	end
+end
+
+class Class
+	def class_defined
+	end
+end
+
+class Empirical::ClassCallbacksProcessor < Empirical::BaseProcessor
+	# def visit_class_node(node)
+	# 	@annotations << [node.end_keyword_loc.start_offset, 0, ";class_defined();"]
+	# end
+
+	# def visit_module_node(node)
+	# 	@annotations << [node.end_keyword_loc.start_offset, 0, ";module_defined();"]
+	# end
+end

data/lib/empirical/eval_processor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Empirical
+	# 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] = process(source, with: PROCESSORS)
+			else
+				args[0] = process(source)
+			end
+		end
+
+		args
+	rescue ::NameError
+		args
+	end
+
+	#: () { () -> void } -> Proc
+	def self.__eval_block_from_forwarding__(*, &block)
+		block
+	end
+
+	class EvalProcessor < Empirical::BaseProcessor
+		EVAL_METHODS = Set[:class_eval, :module_eval, :instance_eval, :eval].freeze
+
+		def visit_call_node(node)
+			name = node.name
+
+			if EVAL_METHODS.include?(name) && (arguments = node.arguments)
+				location = arguments.location
+
+				closing = if arguments.contains_forwarding?
+					")), &(::Empirical.__eval_block_from_forwarding__(...))"
+				else
+					"))"
+				end
+
+				if node.receiver
+					receiver_local = "__eval_receiver_#{SecureRandom.hex(8)}__"
+					receiver_location = node.receiver.location
+
+					@annotations.push(
+						[receiver_location.start_character_offset, 0, "(#{receiver_local} = "],
+						[receiver_location.end_character_offset, 0, ")"],
+						[location.start_character_offset, 0, "*(::Empirical.__process_eval_args__(#{receiver_local}, :#{name}, "],
+						[location.end_character_offset, 0, closing]
+					)
+				else
+					@annotations.push(
+						[location.start_character_offset, 0, "*(::Empirical.__process_eval_args__(self, :#{name}, "],
+						[location.end_character_offset, 0, closing]
+					)
+				end
+			end
+
+			super
+		end
+	end
+end

data/lib/empirical/ivar_processor.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+class Empirical::IvarProcessor < Empirical::BaseProcessor
+	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_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_defined_node(node)
+		value = node.value
+
+		return if Prism::InstanceVariableReadNode === value
+
+		super
+	end
+
+	def visit_instance_variable_read_node(node)
+		name = node.name
+
+		unless @context.include?(name)
+			location = node.location
+
+			@context << name
+
+			@annotations.push(
+				[location.start_character_offset, 0, "(defined?(#{name}) ? "],
+				[location.end_character_offset, 0, " : (::Kernel.raise(::Empirical::NameError.new(self, :#{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/empirical/signature_processor.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+class Empirical::SignatureProcessor < Empirical::BaseProcessor
+	def initialize(...)
+		@return_type = nil
+		@block_stack = []
+		super
+	end
+
+	def visit_call_node(node)
+		case node
+		in { name: :fun }
+			original_return_type = @return_type
+			@return_type = visit_fun_call_node(node)
+			super # ensures any early returns are processed (also, technically, any internal method defs)
+			@return_type = original_return_type
+
+		# handle "method macros" (like `private`, `protected`, etc.)
+		# because the body block is attached to that call node,
+		# not the `fun` call node
+		in { block: Prism::BlockNode }
+			@block_stack << node.block
+			super
+			@block_stack.pop
+		else
+			original_return_type = @return_type
+			super # ensures any early returns are processed (also, technically, any internal method defs)
+			@return_type = original_return_type
+		end
+	end
+
+	def visit_fun_call_node(node)
+		# TODO: better error messages
+		raise SyntaxError unless node.arguments
+		raise SyntaxError unless nil == node.receiver
+
+		case node
+		in {
+			arguments: Prism::ArgumentsNode[
+				arguments: [
+					Prism::KeywordHashNode[
+						elements: [
+							Prism::AssocNode[
+								key: signature,
+								value: return_type
+							]
+						]
+					]
+				]
+			]
+		}
+			body_block = node.block || @block_stack.first
+			preamble = []
+			postamble = []
+
+			case signature
+			# parameterless method defs (e.g. `fun foo` or `fun foo()`)
+			in Prism::LocalVariableReadNode | Prism::ConstantReadNode
+			# no-op
+			# parameterful method defs (e.g. `fun foo(a: Type)` or `fun foo(a = Type)`)
+			in Prism::CallNode
+				raise SyntaxError if signature.block
+
+				signature.arguments&.arguments&.each do |argument|
+					case argument
+					# Positional splat (e.g. `a = [Type]` becomes `*a`)
+					in Prism::LocalVariableWriteNode[name: name, value: Prism::ArrayNode[elements: [type]]]
+						# make argument a splat
+						@annotations << [
+							argument.name_loc.start_offset,
+							0,
+							"*",
+						]
+
+						# remove the type and equals operator from the argument
+						@annotations << [
+							argument.name_loc.end_offset,
+							type.location.end_offset - argument.name_loc.end_offset + 1,
+							"",
+						]
+
+						preamble << "raise(::Empirical::TypeError.argument_type_error(name: '#{name}', value: #{name}, expected: ::Literal::_Array(#{type.slice}), method_name: __method__, context: self)) unless ::Literal::_Array(#{type.slice}) === #{name}"
+
+					# Positional (e.g. `a = Type` becomes `a = nil` or `a = default`)
+					in Prism::LocalVariableWriteNode[name: name, value: typed_param]
+						case typed_param
+						# Positional with default (e.g. `a = Type | 1` becomes `a = 1`)
+						in Prism::CallNode[name: :|, receiver: type, arguments: Prism::ArgumentsNode[arguments: [default]]]
+							type_slice = type.slice
+							default_string = default.slice
+						# Positional without default (e.g. `a = Type` becomes `a = nil`)
+						else
+							type_slice = typed_param.slice
+							default_string = "nil"
+						end
+
+						# replace the typed_param from the argument with the appropriate default value
+						@annotations << [
+							(start = typed_param.location.start_offset),
+							typed_param.location.end_offset - start,
+							default_string,
+						]
+
+						preamble << "raise(::Empirical::TypeError.argument_type_error(name: '#{name}', value: #{name}, expected: #{type_slice}, method_name: __method__, context: self)) unless #{type_slice} === #{name}"
+
+					# Keyword (e.g. `a: Type` becomes `a: nil` or `a: default`)
+					in Prism::KeywordHashNode
+						argument.elements.each do |argument|
+							name = argument.key.unescaped
+
+							nilable = false
+
+							if name.end_with?("?")
+								name = name[0..-2]
+								nilable = true
+
+								@annotations << [
+									argument.key.location.end_offset - 2,
+									1,
+									"",
+								]
+							end
+
+							typed_param = argument.value
+
+							case typed_param
+							# Keyword splat (e.g. `a: {Type => Type}` becomes `**a`)
+							in Prism::HashNode[elements: [Prism::AssocNode[key: key_type, value: value_type]]]
+								# make argument a splat
+								@annotations << [
+									argument.key.location.start_offset,
+									0,
+									"**",
+								]
+
+								# remove the typed_param and equals operator from the argument
+								@annotations << [
+									argument.key.location.end_offset - 1,
+									typed_param.location.end_offset - argument.key.location.end_offset + 1,
+									"",
+								]
+
+								preamble << "raise(::Empirical::TypeError.argument_type_error(name: '#{name}', value: #{name}, expected: ::Literal::_Hash(#{key_type.slice}, #{value_type.slice}), method_name: __method__, context: self)) unless ::Literal::_Hash(#{key_type.slice}, #{value_type.slice}) === #{name}"
+							else
+								case typed_param
+								# Keyword with default
+								in Prism::CallNode[name: :|, receiver: type, arguments: Prism::ArgumentsNode[arguments: [default]]]
+									type_slice = if nilable
+										"::Literal::_Nilable(#{type.slice})"
+									else
+										type.slice
+									end
+
+									default_string = default.slice
+								else
+									type_slice = if nilable
+										"::Literal::_Nilable(#{typed_param.slice})"
+									else
+										typed_param.slice
+									end
+
+									default_string = "nil"
+								end
+
+								# replace the typed_param from the argument with the appropriate default value
+								@annotations << [
+									(start = typed_param.location.start_offset),
+									typed_param.location.end_offset - start,
+									default_string,
+								]
+
+								preamble << "raise(::Empirical::TypeError.argument_type_error(name: '#{name}', value: #{name}, expected: #{type_slice}, method_name: __method__, context: self)) unless #{type_slice} === #{name}"
+							end
+						end
+					else
+						# TODO: better error message
+						raise SyntaxError
+					end
+				end
+			else
+				# TODO: better error message
+				raise SyntaxError
+			end
+
+			preamble << "__literally_returns__ = ("
+			postamble << ")"
+
+			case return_type
+			in Prism::LocalVariableReadNode[name: :void] | Prism::CallNode[name: :void, receiver: nil, block: nil, arguments: nil]
+				postamble << "::Empirical::Void"
+			in Prism::LocalVariableReadNode[name: :never] | Prism::CallNode[name: :never, receiver: nil, block: nil, arguments: nil]
+				postamble << "raise(::Empirical::NeverError.new)"
+			else
+				postamble << "raise(::Empirical::TypeError.return_type_error(value: __literally_returns__, expected: #{return_type.slice}, method_name: __method__, context: self)) unless #{return_type.slice} === __literally_returns__"
+				postamble << "__literally_returns__"
+			end
+
+			# Replace `fun` with `def`
+			@annotations << [
+				(start = node.message_loc.start_offset),
+				node.message_loc.end_offset - start,
+				"def",
+			]
+
+			# Remove the return type and `do` and replace with preamble
+			@annotations << [
+				(start = signature.location.end_offset),
+				body_block.opening_loc.end_offset - start,
+				";#{preamble.join(';')};",
+			]
+
+			# Insert postamble
+			@annotations << [
+				body_block.closing_loc.start_offset,
+				0,
+				";#{postamble.join(';')};",
+			]
+		else
+			# TODO: better error message
+			raise SyntaxError
+		end
+
+		return_type
+	end
+
+	def visit_return_node(node)
+		case @return_type
+		in nil
+			# no-op
+		in Prism::LocalVariableReadNode[name: :void] | Prism::CallNode[name: :void, receiver: nil, block: nil, arguments: nil]
+			if node.arguments
+				raise "You’re returning something"
+			else
+				@annotations << [
+					node.keyword_loc.end_offset,
+					0,
+					"(::Empirical::Void)",
+				]
+			end
+		in Prism::LocalVariableReadNode[name: :never] | Prism::CallNode[name: :never, receiver: nil, block: nil, arguments: nil]
+			@annotations << [
+				node.keyword_loc.start_offset,
+				node.keyword_loc.end_offset - node.keyword_loc.start_offset,
+				"(raise(::Empirical::NeverError.new))",
+			]
+		else
+			@annotations.push(
+				[
+					node.keyword_loc.start_offset,
+					node.keyword_loc.end_offset - node.keyword_loc.start_offset,
+					"(__literally_returning__ = (",
+				],
+				[
+					node.location.end_offset,
+					0,
+					");(raise ::Empirical::TypeError.return_type_error(value: __literally_returning__, expected: #{@return_type.slice}, method_name: __method__, context: self) unless #{@return_type.slice} === __literally_returning__);return(__literally_returning__))",
+				]
+			)
+		end
+
+		super
+	end
+end

data/lib/empirical/type_error.rb

@@ -0,0 +1,28 @@
+class Empirical::TypeError < ::TypeError
+	def self.argument_type_error(name:, value:, expected:, method_name:, context:)
+		owner = context.method(method_name).owner
+		sign = owner.singleton_class? ? "." : "#"
+
+		new(<<~MESSAGE)
+			Method #{method_name} called with the wrong type for the argument #{name}.
+
+			  #{owner.name}#{sign}#{method_name}
+			    #{name}:
+			      Expected: #{expected.inspect}
+			      Actual (#{value.class}): #{value.inspect}
+		MESSAGE
+	end
+
+	def self.return_type_error(value:, expected:, method_name:, context:)
+		owner = context.method(method_name).owner
+		sign = owner.singleton_class? ? "." : "#"
+
+		new(<<~MESSAGE)
+			Method #{method_name} returned the wrong type.
+
+			  #{owner.name}#{sign}#{method_name}
+			    Expected: #{expected.inspect}
+			    Actual (#{value.class}): #{value.inspect}
+		MESSAGE
+	end
+end

data/lib/empirical/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Empirical
-	VERSION = "0.0.1"
+	VERSION = "0.0.3"
 end

data/lib/empirical.rb

@@ -1,28 +1,49 @@
 # frozen_string_literal: true
 
-require "set"
 require "prism"
 require "securerandom"
-
+require "literal"
 require "empirical/version"
 require "empirical/name_error"
+require "empirical/type_error"
 require "empirical/base_processor"
-require "empirical/processor"
+require "empirical/ivar_processor"
+require "empirical/eval_processor"
+require "empirical/class_callbacks_processor"
+require "empirical/signature_processor"
 require "empirical/configuration"
 
 require "require-hooks/setup"
 
 module Empirical
+	class VoidClass < BasicObject
+		def method_missing(method_name, ...)
+			::Kernel.raise "The method `#{method_name}` was called on void. Methods that explicitly declare a void return type should not have their return values used for anything."
+		end
+	end
+
+	Void = VoidClass.new
+
 	EMPTY_ARRAY = [].freeze
 	EVERYTHING = ["**/*"].freeze
 	METHOD_METHOD = Module.instance_method(:method)
 
 	CONFIG = Configuration.new
-	TypedSignatureError = Class.new(StandardError)
+	PROCESSORS = [
+		IvarProcessor,
+		SignatureProcessor,
+		ClassCallbacksProcessor,
+	]
+
+	TypedSignatureError = Class.new(SyntaxError)
+	NeverError = Class.new(RuntimeError)
 
-	# Initializes Empirical 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:`.
+	# Initializes Empirical so that code loaded after this point will:
+	#   1. be guarded against undefined instance variable reads,
+	#   2. permit users to define type checked method definitions, and
+	#   3. permit users to define class/module defined callbacks
+	#
+	# You can pass an array of globs to `include:` and `exclude:`.
 	#
 	# ```ruby
 	# Empirical.init(
@@ -42,55 +63,34 @@ module Empirical
 			source ||= File.read(path)
 
 			if CONFIG.match?(path)
-				Processor.call(source)
+				process(source, with: PROCESSORS)
 			else
-				BaseProcessor.call(source)
+				process(source)
 			end
 		end
 	end
 
-	# 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
+	def self.process(source, with: [])
+		annotations = []
+		tree = Prism.parse(source).value
 
-		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
+		Array(with).each do |processor|
+			processor.new(annotations:).visit(tree)
 		end
 
-		if String === source
-			file ||= caller_locations(1, 1).first.path
+		Empirical::EvalProcessor.new(annotations:).visit(tree)
 
-			if CONFIG.match?(file)
-				args[0] = Processor.call(source)
-			else
-				args[0] = BaseProcessor.call(source)
-			end
+		buffer = source.dup
+		annotations.sort_by!(&:first)
+
+		annotations.reverse_each do |offset, length, string|
+			buffer[offset, length] = string
 		end
 
-		args
-	rescue ::NameError
-		args
+		buffer
 	end
+end
 
-	#: () { () -> void } -> Proc
-	def self.__eval_block_from_forwarding__(*, &block)
-		block
-	end
+class Object
+	include Literal::Types
 end

data/lib/rubocop/cop/empirical/no_defs.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class RuboCop::Cop::Empirical::NoDefs < RuboCop::Cop::Base
+	MSG = "Use `fun` method definitions instead of `def` method definitions."
+
+	def on_def(node)
+		add_offense(node) unless node.arguments.any?(&:forward_args_type?)
+	end
+
+	def on_defs(node)
+		add_offense(node) unless node.arguments.any?(&:forward_args_type?)
+	end
+end

data/lib/rubocop/cop/empirical.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RuboCop
+	module Cop
+		module Empirical; end
+	end
+end
+
+require_relative "empirical/no_defs"

data/lib/rubocop-empirical.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "rubocop"
+require_relative "rubocop/cop/empirical"

data/lib/ruby_lsp/empirical/addon.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "ruby_lsp/addon"
+
+module RubyLsp
+	module Empirical
+		class Addon < ::RubyLsp::Addon
+			def activate(global_state, message_queue)
+			end
+
+			def deactivate
+			end
+
+			def name
+				"Empirical"
+			end
+
+			def version
+				"0.1.0"
+			end
+		end
+
+		class IndexingEnhancement < RubyIndexer::Enhancement
+			def on_call_node_enter(node)
+				call_name = node.name
+				owner = @listener.current_owner
+				location = node.location
+
+				return unless owner
+				return unless :fun == call_name
+				return unless node.arguments
+
+				# Match the pattern: fun foo(...) => ReturnType do ... end
+				case node
+				in {
+					arguments: Prism::ArgumentsNode[
+						arguments: [
+							Prism::KeywordHashNode[
+								elements: [
+									Prism::AssocNode[
+										key: signature,
+										value: _return_type
+									]
+								]
+							]
+						]
+					],
+					block: Prism::BlockNode
+				}
+					# Extract method name from signature
+					method_name = case signature
+					in Prism::LocalVariableReadNode
+						signature.name.to_s
+					in Prism::ConstantReadNode
+						signature.name.to_s
+					in Prism::CallNode
+						signature.name.to_s
+					else
+						return
+					end
+
+					# Extract parameters from signature if it's a call node
+					parameters = []
+					if signature.is_a?(Prism::CallNode) && signature.arguments
+						signature.arguments.arguments.each do |arg|
+							case arg
+							in Prism::LocalVariableWriteNode[name: param_name]
+								parameters << RubyIndexer::Entry::OptionalParameter.new(name: param_name.to_s)
+							in Prism::KeywordHashNode
+								arg.elements.each do |element|
+									param_name = element.key.unescaped
+									parameters << RubyIndexer::Entry::OptionalKeywordParameter.new(name: param_name)
+								end
+							end
+						end
+					end
+
+					@listener.add_method(
+						method_name,
+						location,
+						[RubyIndexer::Entry::Signature.new(parameters)]
+					)
+				end
+			end
+		end
+	end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: empirical
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Joel Drapper
@@ -38,10 +38,25 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: literal
+  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: Based on, concerned with, or verifiable by observation or experience
   rather than theory or pure logic.
 email:
 - joel@drapper.me
+- stephen.margheim@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -50,10 +65,18 @@ files:
 - README.md
 - lib/empirical.rb
 - lib/empirical/base_processor.rb
+- lib/empirical/class_callbacks_processor.rb
 - lib/empirical/configuration.rb
+- lib/empirical/eval_processor.rb
+- lib/empirical/ivar_processor.rb
 - lib/empirical/name_error.rb
-- lib/empirical/processor.rb
+- lib/empirical/signature_processor.rb
+- lib/empirical/type_error.rb
 - lib/empirical/version.rb
+- lib/rubocop-empirical.rb
+- lib/rubocop/cop/empirical.rb
+- lib/rubocop/cop/empirical/no_defs.rb
+- lib/ruby_lsp/empirical/addon.rb
 homepage: https://github.com/yippee-fun/empirical
 licenses:
 - MIT

data/lib/empirical/processor.rb

@@ -1,257 +0,0 @@
-# frozen_string_literal: true
-
-class Empirical::Processor < Empirical::BaseProcessor
-	#: (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::IfNode) -> void
-	def visit_if_node(node)
-		visit(node.predicate)
-
-		branch { visit(node.statements) }
-		branch { visit(node.subsequent) }
-	end
-
-	#: (Prism::CaseNode) -> void
-	def visit_case_node(node)
-		visit(node.predicate)
-
-		node.conditions.each do |condition|
-			branch { visit(condition) }
-		end
-
-		branch { visit(node.else_clause) }
-	end
-
-	#: (Prism::DefinedNode) -> void
-	def visit_defined_node(node)
-		value = node.value
-
-		return if Prism::InstanceVariableReadNode === value
-
-		super
-	end
-
-	#: (Prism::InstanceVariableReadNode) -> void
-	def visit_instance_variable_read_node(node)
-		name = node.name
-
-		unless @context.include?(name)
-			location = node.location
-
-			@context << name
-
-			@annotations.push(
-				[location.start_character_offset, 0, "(defined?(#{name}) ? "],
-				[location.end_character_offset, 0, " : (::Kernel.raise(::Empirical::NameError.new(self, :#{name}))))"]
-			)
-		end
-
-		super
-	end
-
-	#: () { () -> void } -> void
-	private def new_context
-		original_context = @context
-
-		@context = Set[]
-
-		begin
-			yield
-		ensure
-			@context = original_context
-		end
-	end
-
-	#: () { () -> void } -> void
-	private def branch
-		original_context = @context
-		@context = original_context.dup
-
-		begin
-			yield
-		ensure
-			@context = original_context
-		end
-	end
-
-	def visit_def_node(node)
-		new_context do
-			return super unless node.equal_loc
-			return super unless node in {
-				body: {
-					body: [
-						Prism::CallNode[
-							block: Prism::BlockNode[
-								body: Prism::StatementsNode
-							] => block
-						] => call
-					]
-				}
-			}
-
-			signature = build_typed_parameters_assertion(node)
-
-			if node.rparen_loc
-				@annotations << [
-					start = node.rparen_loc.start_offset + 1,
-					block.opening_loc.end_offset - start,
-					";binding.assert(#{signature});__literally_returns__ = (;",
-				]
-			else
-				@annotations << [
-					start = node.equal_loc.start_offset - 1,
-					block.opening_loc.end_offset - start,
-					";__literally_returns__ = (;",
-				]
-			end
-
-			return_type = if call.closing_loc
-				node.slice[(call.start_offset)...(call.closing_loc.end_offset)]
-			else
-				call.name
-			end
-			@annotations << [
-				block.closing_loc.start_offset,
-				0,
-				";);binding.assert(__literally_returns__: #{return_type});__literally_returns__;",
-			]
-
-			@annotations << [
-				start = block.closing_loc.start_offset,
-				block.closing_loc.end_offset - start,
-				"end",
-			]
-		end
-	end
-
-	private def build_typed_parameters_assertion(node)
-		return unless node.parameters
-
-		if (requireds = node.parameters.requireds)&.any?
-			raise Empirical::TypedSignatureError.new("Typed method signatures don't allow required keyword parameters: #{requireds.inspect}")
-		elsif (rest = node.parameters.rest)&.any?
-			raise Empirical::TypedSignatureError.new("Typed method signatures don't allow a splat array parameter: #{rest.inspect}")
-		elsif (posts = node.parameters.posts)&.any?
-			raise Empirical::TypedSignatureError.new("Typed method signatures don't allow a splat hash parameter: #{posts.inspect}")
-		elsif (keyword_rest = node.parameters.keyword_rest)&.any?
-			raise Empirical::TypedSignatureError.new("Typed method signatures don't allow a splat hash parameter: #{keyword_rest.inspect}")
-		end
-
-		parameters_assertions = []
-
-		if (optionals = node.parameters.optionals)&.any?
-			parameters_assertions << optionals.map do |optional|
-				case optional
-				# typed splats, e.g.
-				# `(names = [String])` => `(*names); assert(names: _Array(String))` and
-				# `(position = [*Position])` => `(*position); assert(position: Position)`
-				in { value: Prism::ArrayNode[elements: [type_node]] => value }
-					if type_node in Prism::SplatNode
-						type = type_node.expression.slice
-					else
-						type = "::Literal::_Array(#{type_node.slice})"
-					end
-
-					# Make the parameter a splat
-					@annotations << [optional.name_loc.start_offset, 0, "*"]
-
-					# Remove the type signature (the default value)
-					@annotations << [optional.operator_loc.start_offset, value.closing_loc.end_offset - optional.operator_loc.start_offset, ""]
-					next "#{optional.name}: #{type}"
-				# With default
-				in {
-					value: Prism::CallNode[
-						block: Prism::BlockNode[
-							body: Prism::StatementsNode => default_node
-						]
-					] => call
-				}
-					default = "(#{default_node.slice})"
-
-					type = if call.closing_loc
-						node.slice[(call.start_offset)...(call.closing_loc.end_offset)]
-					else
-						call.name
-					end
-				# No default
-				else
-					default = "nil"
-					type = optional.value.slice
-				end
-
-				value_location = optional.value.location
-				@annotations << [value_location.start_offset, value_location.end_offset - value_location.start_offset, default]
-				"#{optional.name}: #{type}"
-			end.join(", ")
-		end
-
-		if (keywords = node.parameters.keywords)&.any?
-			parameters_assertions << keywords.map do |keyword|
-				case keyword
-				# Splat
-				in { value: Prism::HashNode[elements: [Prism::AssocNode[key: key_type_node, value: val_type_node]]] => value }
-					type = "::Literal::_Hash(#{key_type_node.slice}, #{val_type_node.slice})"
-
-					# Make the parameter a splat
-					@annotations << [keyword.name_loc.start_offset, 0, "**"]
-
-					# Remove the type signature (the default value) and the colon at the end of the keyword
-					@annotations << [keyword.name_loc.end_offset - 1, value.closing_loc.end_offset - keyword.name_loc.end_offset + 1, ""]
-					next "#{keyword.name}: #{type}"
-				in { value: Prism::HashNode[elements: [Prism::AssocSplatNode[value: val_type_node]]] => value }
-					type = val_type_node.slice
-
-					# Make the parameter a splat
-					@annotations << [keyword.name_loc.start_offset, 0, "**"]
-
-					# Remove the type signature (the default value) and the colon at the end of the keyword
-					@annotations << [keyword.name_loc.end_offset - 1, value.closing_loc.end_offset - keyword.name_loc.end_offset + 1, ""]
-					next "#{keyword.name}: #{type}"
-				# With default
-				in {
-					value: Prism::CallNode[
-						block: Prism::BlockNode[
-							body: Prism::StatementsNode => default_node
-						]
-					] => call
-				}
-					default = "(#{default_node.slice})"
-
-					type = if call.closing_loc
-						node.slice[(call.start_offset)...(call.closing_loc.end_offset)]
-					else
-						call.name
-					end
-				# No default
-				else
-					default = "nil"
-					type = keyword.value.slice
-				end
-
-				value_location = keyword.value.location
-				@annotations << [value_location.start_offset, value_location.end_offset - value_location.start_offset, default]
-				"#{keyword.name}: #{type}"
-			end.join(", ")
-		end
-
-		parameters_assertions.join(", ")
-	end
-end