v0.3.0 — fold in import/import_relative from rubyworks/finder

Add Kernel#import and Kernel#import_relative as scope-aware alternatives
to require / require_relative. They evaluate the loaded script into the
current scope rather than the toplevel, providing a partial workaround
for Ruby's toplevel pollution of Object (Problem 1 in the README).

The two libraries are conceptually about the same thing — making Ruby's
toplevel/module loading semantics behave more sensibly — so consolidating
them makes sense.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: trans

HISTORY.md

@@ -1,5 +1,20 @@
 # RELEASE HISTORY
 
+## 0.3.0 / 2026-04-08
+
+Fold in the `import`/`import_relative` feature from rubyworks/finder.
+
+Changes:
+
+* Add `Kernel#import` and `Kernel#import_relative` (require
+  `'main_like_module/import'`) as scope-aware alternatives to `require`
+  and `require_relative`. They evaluate the loaded script into the
+  current scope rather than into the toplevel, providing a partial
+  workaround for Problem 1 (toplevel pollution of Object).
+* Update README to document the new feature and explain how the two
+  pieces of the library address Ruby's two toplevel design quirks.
+
+
 ## 0.2.0 / 2026-04-07
 
 Maintenance release modernizing the project.

README.md

@@ -87,11 +87,14 @@ not a hand-picked subset.
 
 ## What This Library Does
 
-The first problem — toplevel polluting `Object` — cannot be fixed from
-userland. It is baked into the parser and the interpreter. Only a change
-to Ruby itself could address it.
+This library addresses both problems, though only one of them fully.
+
+### Completing the Toplevel Proxy (Problem 2)
+
+```ruby
+    require 'main_like_module'
+```
 
-The second problem *can* be addressed, and that is what this library does.
 On `require`, it walks `Module`'s instance methods and, for each one not
 already available at the toplevel, defines a singleton method on `main`
 that forwards the call to `Object.class_eval`. The result is that anything
@@ -108,9 +111,45 @@ you can do inside a `module` body, you can now do at the toplevel as well.
 Public, private, and protected `Module` methods are all proxied with their
 correct visibility.
 
-Note carefully: this does *nothing* about Problem 1. The methods you define
-at the toplevel still end up on `Object`. This library only completes the
-proxy; it does not redesign the toplevel.
+### A Partial Workaround for Toplevel Pollution (Problem 1)
+
+```ruby
+    require 'main_like_module/import'
+```
+
+The parser-level pollution of `Object` cannot be fixed from userland —
+that ship sailed when the Ruby grammar was written. But for code you
+*write yourself*, this library provides `Kernel#import` and
+`Kernel#import_relative` as scope-aware alternatives to `require` and
+`require_relative`. They evaluate the loaded script directly into the
+*current scope* rather than into the toplevel:
+
+```ruby
+    require 'main_like_module/import'
+
+    module MyApp
+      import 'helpers'   # helpers.rb is evaluated into MyApp,
+                         # not into Object
+    end
+
+    MyApp.some_helper_method   #=> works
+    Object.private_instance_methods.include?(:some_helper_method)
+    #=> false  -- Object stays clean
+```
+
+`import` searches `$LOAD_PATH` the way `require` does. `import_relative`
+resolves its argument relative to the calling file the way
+`require_relative` does. Both raise `LoadError` on miss.
+
+This is a *partial* workaround. It only helps for code that uses `import`
+explicitly — toplevel code in scripts you don't control still pollutes
+`Object`. But for organizing your own libraries into clean module
+namespaces without ceremony, it is genuinely useful.
+
+`import` was originally part of the `rubyworks/finder` gem, which has
+been folded into `main_like_module` because the two libraries are really
+about the same thing: making Ruby's toplevel/module loading semantics
+behave more sensibly.
 
 
 ## Should You Use This?

Rakefile

@@ -10,6 +10,7 @@ end
 desc "Run tests"
 task :test do
   sh 'ruby -Ilib -Itest test/test_main_like_module.rb'
+  sh 'ruby -Ilib -Itest test/test_import.rb'
 end
 
 task :default => :test

lib/main_like_module/import.rb

@@ -0,0 +1,61 @@
+# Kernel#import and Kernel#import_relative are variants of #require and
+# #require_relative that evaluate the loaded script *into the current scope*
+# instead of into the toplevel. This provides a partial workaround for the
+# fact that toplevel definitions in Ruby pollute Object globally.
+#
+#   module MyApp
+#     import 'somefile'   # somefile's contents are loaded into MyApp,
+#                         # not into Object
+#   end
+#
+# Originally extracted from rubyworks/finder.
+
+module Kernel
+
+  private
+
+  # Find +feature+ in $LOAD_PATH and evaluate it into the current scope.
+  #
+  # Unlike #require, definitions in the loaded file are added to whatever
+  # scope #import was called from rather than to Object.
+  def import(feature)
+    file = nil
+    if File.file?(feature) && File.absolute_path(feature) == feature
+      file = feature
+    else
+      candidates = feature.end_with?('.rb') ? [feature] : ["#{feature}.rb", feature]
+      $LOAD_PATH.each do |dir|
+        candidates.each do |c|
+          path = File.expand_path(c, dir)
+          if File.file?(path)
+            file = path
+            break
+          end
+        end
+        break if file
+      end
+    end
+    raise LoadError, "no such file to import -- #{feature}" unless file
+    instance_eval(::File.read(file), file)
+  end
+
+  # Like #import, but resolves +fname+ relative to the file that called
+  # #import_relative (mirroring how #require_relative works).
+  def import_relative(fname)
+    call = caller.first
+    fail "Can't parse #{call}" unless call.rindex(/:\d+(:in [`'].*[`'])?$/)
+    path = $`
+    if /\A\((.*)\)/ =~ path # eval, etc.
+      raise LoadError, "import_relative is called in #{$1}"
+    end
+    base = File.expand_path(fname, File.dirname(path))
+    file = if File.file?(base)
+             base
+           elsif File.file?("#{base}.rb")
+             "#{base}.rb"
+           end
+    raise LoadError, "no such file to import -- #{base}" unless file
+    instance_eval(::File.read(file), file)
+  end
+
+end

main_like_module.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'main_like_module'
-  s.version     = '0.2.0'
+  s.version     = '0.3.0'
   s.summary     = 'Completes the toplevel proxy of the Object class.'
   s.description = 'A small demonstration library that fills in the missing ' \
                   'parts of Ruby\'s toplevel object so that it behaves like a ' \

test/fixtures/greeter.rb

@@ -0,0 +1,3 @@
+def hello
+  'hello from greeter'
+end

test/test_import.rb

@@ -0,0 +1,44 @@
+require 'minitest/autorun'
+require 'main_like_module/import'
+
+class ImportTest < Minitest::Test
+
+  def setup
+    @fixtures = File.expand_path('fixtures', __dir__)
+    $LOAD_PATH.unshift(@fixtures) unless $LOAD_PATH.include?(@fixtures)
+  end
+
+  def teardown
+    $LOAD_PATH.delete(@fixtures)
+  end
+
+  def test_import_into_module_scope
+    target = Module.new
+    target.module_eval { import 'greeter' }
+    assert_equal 'hello from greeter', target.send(:hello)
+  end
+
+  def test_import_does_not_pollute_object
+    target = Module.new
+    target.module_eval { import 'greeter' }
+    refute Object.private_instance_methods.include?(:hello),
+      'import should not add methods to Object'
+  end
+
+  def test_import_relative
+    target = Module.new
+    fixture = File.expand_path('fixtures/greeter.rb', __dir__)
+    target.module_eval(<<~RUBY, fixture, 1)
+      import_relative 'greeter'
+    RUBY
+    assert_equal 'hello from greeter', target.send(:hello)
+  end
+
+  def test_import_raises_for_missing_file
+    target = Module.new
+    assert_raises(LoadError) do
+      target.module_eval { import 'nonexistent_xyz' }
+    end
+  end
+
+end