dynamic_locals 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82329848153ed44bdf77018d27125b15b1b3b8bb039867ba5aeac718c13f9bcc
+  data.tar.gz: 422065d9beca6fad9aa6447c361352d25b860efeb0c5f7477b4c02b7df809084
+SHA512:
+  metadata.gz: 28b72b64c991993cac07d046e9090f7b9c0b6c969e4c0e62a8e72f5bc4948795da721ac5588cfc6f7deec21e72725515a35215ccb154ea3286a34e27a65054a2
+  data.tar.gz: 0a44008c2ea2c798c38b46352e92e596c1c943e704fde57cd7764cc4ba010878762c9b25957e0631b9c81baca36e1329b39edf41d8029cb3dd11ca2b643a4986

data/.github/workflows/test.yml

@@ -0,0 +1,19 @@
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rake

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at john@hawthorn.email. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in dynamic_locals.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    dynamic_locals (0.1.0)
+      prism (>= 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.27.0)
+    prism (1.9.0)
+    rake (13.4.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 2.0)
+  dynamic_locals!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+
+BUNDLED WITH
+  4.0.10

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 John Hawthorn
+
+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,67 @@
+# DynamicLocals
+
+This is an experimental Ruby to Ruby transpiler which swaps out the functionality of local variables, allowing them to be dynamically defined.
+
+This is a proof of concept and shouldn't be used yet.
+
+## Usage
+
+``` ruby
+c = Class.new do
+  def foo
+    "from method"
+  end
+end
+
+src = DynamicLocals.translate("foo")
+# => "locals.fetch(:foo) { foo() }"
+
+c.class_eval("def run(locals); #{src}; end")
+
+c.new.run({})
+#=> "from method"
+c.new.run({ foo: "from local" })
+#=> "from local"
+```
+
+## Why?
+
+ActionView has the interesting quality that the local variables defined within a template are defined by the caller.
+
+``` ruby
+<%= render partial: "some_template", locals: { foo: "bar" } %>
+```
+
+This is tricky, because local variables are determined by Ruby at compile time.
+Because method calls with no arguments look the same as local variable accesses, it's ambiguous which they are. Ruby determines between calls and locals by checking if the local is being assigned to at
+
+ActionView currently solves this by compiling a separate template for each set of local variable names passed in. This wastes memory by duplicating the template for every set of locals being passed in and also prevents templates from being compiled at boot, since we don't know what locals they will be given.
+
+## How?
+
+The basic mechanism is to replace all ambiguous access a hash fetch falling back to an unambiguous method call:
+
+``` ruby
+locals.fetch(:foobar) { foobar() }
+```
+
+This introduces a number of corner cases (see tests for many examples), which this also tries to work around.
+The goal of this is for Ruby's behaviour to be unchanged and not to leak this "optimization".
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jhawthorn/dynamic_locals. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the DynamicLocals project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jhawthorn/dynamic_locals/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dynamic_locals"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/dynamic_locals.gemspec

@@ -0,0 +1,32 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "dynamic_locals/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "dynamic_locals"
+  spec.version       = DynamicLocals::VERSION
+  spec.authors       = ["John Hawthorn"]
+  spec.email         = ["john@hawthorn.email"]
+
+  spec.summary       = %q{Makes it possible to define locals dynamically}
+  spec.description   = %q{Parses ruby to rewrite how locals work}
+  spec.homepage      = "https://github.com/jhawthorn/dynamic_locals"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "prism", ">= 1.0"
+
+  spec.add_development_dependency "bundler", ">= 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+end

data/lib/dynamic_locals/ast_rewriter.rb

@@ -0,0 +1,116 @@
+require "prism"
+
+module DynamicLocals
+  class ASTRewriter
+    # The source we translate is a *method body*: it may legally use constructs
+    # that are only valid inside a method -- `yield`, a top-level `return`, and
+    # an implicit begin/rescue (`raise; rescue; ...`). Parsing it as a standalone
+    # program rejects those, so we parse it wrapped in a method definition and
+    # then map node offsets back onto the original (unwrapped) source.
+    WRAPPER_NAME = "__dynamic_locals_parse_wrapper__"
+    WRAPPER_PREFIX = "def #{WRAPPER_NAME}\n"
+    WRAPPER_SUFFIX = "\nend"
+
+    def initialize(source)
+      @original_src = source.dup.freeze
+
+      result, prefix = parse_with_locals([])
+      errors = result.errors.reject { |error| error.type == :no_local_variable }
+      raise SyntaxError, errors.map(&:message).join("\n") if errors.any?
+
+      # A pin such as `^foo` reports :no_local_variable when `foo` will only be
+      # supplied dynamically. Reparse with those names declared on the wrapper
+      # method; pins in blocks then resolve naturally, while a pin beyond a real
+      # scope boundary (a nested def/class/module body) remains a syntax error.
+      implicit_locals = result.errors.filter_map do |error|
+        error.location.slice.to_sym if error.type == :no_local_variable
+      end.uniq
+      result, prefix = parse_with_locals(implicit_locals) if implicit_locals.any?
+      raise SyntaxError, result.errors.map(&:message).join("\n") unless result.success?
+
+      @offset = prefix.bytesize
+      @def_node = result.value.statements.body.first
+      @replacements = []
+    end
+
+    Replacement = Struct.new(:range, :src)
+
+    attr_reader :original_src
+
+    # The method body scope: a StatementsNode, a BeginNode (when the body has a
+    # rescue/else/ensure), or nil when the body is empty.
+    def ast
+      @def_node.body
+    end
+
+    # The method-level local table Ruby derives from the body.
+    def locals
+      @def_node.locals
+    end
+
+    def modified_src
+      # Apply right-to-left so earlier ranges stay valid. Ties are broken so
+      # that a zero-width insertion at an offset is applied before a
+      # replacement ending there (keeping the insertion outside the replaced
+      # text), and same-position insertions land in registration order.
+      rewrites =
+        @replacements.each_with_index.sort_by do |replacement, index|
+          [replacement.range.end, replacement.range.begin, index]
+        end.reverse
+
+      src = original_src.b
+      rewrites.each do |replacement, _|
+        src[replacement.range] = replacement.src.b
+      end
+      src.force_encoding(original_src.encoding)
+    end
+
+    def insert_before(node, src)
+      raise TypeError unless Prism::Node === node
+
+      insert_at(node.location.start_offset, src)
+    end
+
+    def insert_after(node, src)
+      raise TypeError unless Prism::Node === node
+
+      insert_at(node.location.end_offset, src)
+    end
+
+    # Offsets are relative to the wrapped source, as in Prism locations.
+    def insert_at(wrapped_offset, src)
+      pos = wrapped_offset - @offset
+      @replacements << Replacement.new(pos...pos, src)
+    end
+
+    def replace_offsets(wrapped_start, wrapped_end, src)
+      @replacements << Replacement.new((wrapped_start - @offset)...(wrapped_end - @offset), src)
+    end
+
+    def replace(node, src)
+      raise TypeError unless Prism::Node === node
+
+      range = range_from(node)
+      @replacements << Replacement.new(range, src)
+    end
+
+    private
+
+    def parse_with_locals(locals)
+      prefix =
+        if locals.empty?
+          WRAPPER_PREFIX
+        else
+          parameters = locals.map { |local| "#{local}: nil" }.join(", ")
+          "def #{WRAPPER_NAME}(#{parameters})\n"
+        end
+      [Prism.parse("#{prefix}#{@original_src}#{WRAPPER_SUFFIX}"), prefix]
+    end
+
+    # Node offsets are relative to the wrapped source; shift them back onto the
+    # original source by subtracting the wrapper prefix length.
+    def range_from(node)
+      (node.location.start_offset - @offset)...(node.location.end_offset - @offset)
+    end
+  end
+end

data/lib/dynamic_locals/base_translator.rb

@@ -0,0 +1,28 @@
+module DynamicLocals
+  class BaseTranslator
+    attr_reader :original_src, :locals_hash, :lookup_strategy, :known_locals
+
+    def initialize(src, locals_hash: :locals, lookup_strategy: :hash, known_locals: [])
+      @original_src = src
+      @locals_hash = locals_hash
+      @lookup_strategy = lookup_strategy
+      @known_locals = Array(known_locals).map(&:to_sym)
+    end
+
+    def translate
+      raise NotImplementedError
+    end
+
+    # The parameter list that pairs with the translated body. The default shape
+    # takes the locals as a single hash argument; strategies that use real
+    # parameters (see RewriteTranslator's keyword strategy) override this.
+    def parameters
+      "#{locals_hash} = {}"
+    end
+
+    # Wrap the translated body in a method definition.
+    def to_s(name = "__dynamic_locals__")
+      "def #{name}(#{parameters})\n#{translate}\nend"
+    end
+  end
+end

data/lib/dynamic_locals/eval_translator.rb

@@ -0,0 +1,22 @@
+require "dynamic_locals/base_translator"
+
+module DynamicLocals
+  # This is (probably) the simplest possible implementation of the behaviour we
+  # want. It builds a new string of Ruby code with assignments to the locals
+  # each time it is called and evals that string.
+  #
+  # This is not intended to be used in production code, but for debugging and
+  # as a reference implementation.
+  class EvalTranslator < BaseTranslator
+    def translate
+      # `eval` compiles its argument as a standalone program, which -- unlike a
+      # method body -- has no implicit `begin`. Wrap the source in begin/end so a
+      # method-body-style implicit rescue parses.
+      body = "begin\n#{original_src}\nend"
+      # The file/line arguments make errors report the line the source would
+      # occupy had it been spliced in directly: the `begin` line lands one
+      # line above the eval call, so source line N reports as call line + N.
+      %{eval(#{locals_hash}.keys.map { |k| "\#{k} = #{locals_hash}[\#{k.inspect}];" }.join + #{body.inspect}, binding, __FILE__, __LINE__ - 1)}
+    end
+  end
+end

data/lib/dynamic_locals/rewrite_translator.rb

@@ -0,0 +1,512 @@
+require "dynamic_locals/base_translator"
+require "dynamic_locals/ast_rewriter"
+
+module DynamicLocals
+  class RewriteTranslator < BaseTranslator
+    def initialize(...)
+      super
+
+      unless [:hash, :keywords].include?(lookup_strategy)
+        raise ArgumentError, "unknown lookup strategy: #{lookup_strategy.inspect}"
+      end
+
+      @rewriter = ASTRewriter.new(original_src)
+
+      root = @rewriter.ast
+      # Names assigned anywhere in this method body. Earlier occurrences of
+      # these names can still be CallNodes, e.g. `foo; foo = 123`.
+      @local_table = @rewriter.locals
+      @dynamic_locals = @local_table.dup
+      @keyword_unset_flags = {}
+      @shadowed_locals = []
+      @shadow_names = {}
+      @generated_names = []
+      @scope_parameter_names = {}
+      collect_dynamic_locals(root)
+      # Known locals are real variables that already exist (e.g. method
+      # parameters); they are never looked up dynamically, made into kwargs,
+      # or initialized from the locals hash.
+      @dynamic_locals = @dynamic_locals.sort.uniq - known_locals
+      dynamic_locals.each { |local| keyword_unset_flag(local) } if keywords?
+      find_replacements(root, [:root])
+    end
+
+    attr_reader :dynamic_locals
+
+    def keyword_parameters(rest: nil)
+      return "#{locals_hash} = {}" unless keywords?
+      params = dynamic_locals.map do |local|
+        "#{local}: (#{keyword_unset_flag(local)} = true; nil)"
+      end
+      params << "**#{rest}" if rest
+      params.join(", ")
+    end
+
+    def translate
+      src = @rewriter.modified_src
+
+      initialize = initialize_local_table
+
+      "#{initialize}#{src}"
+    end
+
+    # In the keyword strategy the locals are real parameters; absorb any
+    # unsupplied-but-passed keys so callers can splat an arbitrary hash.
+    def parameters
+      keyword_parameters(rest: :__dynamic_locals_unused_keywords)
+    end
+
+    private
+
+    def collect_dynamic_locals(node)
+      return unless Prism::Node === node
+
+      if nested_scope?(node)
+        nested_local_table(node).each do |local|
+          @local_table << local
+          @dynamic_locals << local
+          # Pre-declaring a dynamic local as a method-level variable changes
+          # the scoping of assignments inside blocks: plain Ruby would have
+          # created a fresh block-local per invocation. These names get a
+          # "shadow" variable whose assignments are co-located with the
+          # original ones, so its scope structure matches plain Ruby's.
+          @shadowed_locals << local unless known_locals.include?(local)
+        end
+
+        child_nodes_for_method_body(node).each { |child| collect_dynamic_locals(child) }
+      elsif defined_variable_call?(node)
+        @dynamic_locals << node.value.name
+      elsif variable_call?(node)
+        @dynamic_locals << node.name
+      else
+        child_nodes_for_method_body(node).each { |child| collect_dynamic_locals(child) }
+      end
+    end
+
+    # Leaf branches replace a node (or deliberately leave it alone) and return;
+    # write branches recurse only into their value; everything else falls
+    # through to the generic recursion at the bottom.
+    def find_replacements(node, scopes)
+      return unless Prism::Node === node
+
+      if nested_scope?(node)
+        scopes += [node]
+      elsif defined_variable_call?(node)
+        # A `defined?` spanning newlines must not pull later lines up;
+        # re-emit its newlines inside the parenthesized replacement.
+        newlines = "\n" * node.slice.count("\n")
+        @rewriter.replace node, "(#{defined_lookup_src(node.value.name)}#{newlines})"
+        return
+      elsif Prism::DefinedNode === node && Prism::LocalVariableReadNode === node.value
+        # `defined?` of a real local is 'local-variable' whether the name was
+        # supplied or shadow-assigned, so leave it alone. Rewriting the read
+        # into a guarded expression would change the answer to 'expression'.
+        return
+      elsif variable_call?(node)
+        name = node.name
+        fallback = @local_table.include?(name) ? "#{name}()" : name.to_s
+        @rewriter.replace node, local_lookup_src(name, fallback)
+        return
+      elsif Prism::LocalVariableReadNode === node
+        if shadow_binding?(node.name, node.depth, scopes)
+          @rewriter.replace node, shadow_read_src(node.name)
+        end
+        return
+      elsif Prism::LocalVariableWriteNode === node
+        if shadow_binding?(node.name, node.depth, scopes)
+          @rewriter.insert_before(node, "#{shadow_name(node.name)} = ")
+        end
+        return find_replacements(node.value, scopes)
+      elsif local_operator_write?(node)
+        expand_operator_write(node, scopes) if shadow_binding?(node.name, node.depth, scopes)
+        return find_replacements(node.value, scopes)
+      elsif Prism::MatchWriteNode === node
+        shadow_match_write(node, scopes)
+        return find_replacements(node.call, scopes)
+      elsif Prism::MultiWriteNode === node
+        shadow_multi_write(node, scopes)
+      elsif Prism::RescueNode === node
+        shadow_rescue_reference(node, scopes)
+      elsif Prism::ForNode === node
+        shadow_for_index(node, scopes)
+      elsif Prism::MatchRequiredNode === node
+        shadow_required_pattern(node, scopes)
+      elsif Prism::MatchPredicateNode === node
+        shadow_predicate_pattern(node, scopes)
+      elsif Prism::InNode === node
+        # This branch owns its recursion: guard syncs must be registered
+        # around the predicate's own rewrites (see shadow_in_clause).
+        return shadow_in_clause(node, scopes) do
+          child_nodes_for_method_body(node).each { |child| find_replacements(child, scopes) }
+        end
+      end
+
+      child_nodes_for_method_body(node).each { |child| find_replacements(child, scopes) }
+    end
+
+    # True when a read/write of +name+ resolves to a binding that was declared
+    # by assignment rather than by a parameter or explicit block-local -- those
+    # are the bindings whose scoping our pre-declaration changed, so they must
+    # go through the shadow variable. Parameter bindings shadow the dynamic
+    # local in plain Ruby too and stay untouched.
+    def shadow_binding?(name, depth, scopes)
+      return false unless @shadowed_locals.include?(name)
+      scope = scopes[scopes.length - 1 - depth]
+      return true if scope == :root
+      !scope_parameter_names(scope).include?(name)
+    end
+
+    def scope_parameter_names(scope)
+      @scope_parameter_names[scope] ||= parameter_names(scope.parameters)
+    end
+
+    # `x = v` => `__dynamic_locals_shadow_x = x = v`
+    # The kwarg keeps its real name (callers supply it), and the shadow gets a
+    # fresh block-local binding exactly where plain `x` would have. The leading
+    # underscore exempts write-only shadows from unused-variable warnings.
+    def shadow_name(name)
+      @shadow_names[name] ||= generate_hygienic_name("__dynamic_locals_shadow_#{name}")
+    end
+
+    def discard_name
+      @discard_name ||= generate_hygienic_name("__dynamic_locals_discard")
+    end
+
+    def generate_hygienic_name(base)
+      candidate = base.to_sym
+      index = 0
+      while reserved_name?(candidate)
+        index += 1
+        candidate = :"#{base}#{index}"
+      end
+      @generated_names << candidate
+      candidate
+    end
+
+    def reserved_name?(name)
+      # The regex alone can't cover dynamic locals: \b fails around non-word
+      # names like emoji identifiers.
+      known_locals.include?(name) ||
+        @generated_names.include?(name) ||
+        @dynamic_locals.include?(name) ||
+        original_src.match?(/\b#{Regexp.escape(name.to_s)}\b/)
+    end
+
+    # Selects the plain variable when the local was supplied, the shadow
+    # otherwise. Needed even for method-level bindings: when the local is
+    # unset, the double-write leaves garbage in the kwarg.
+    def shadow_read_src(name)
+      if keywords?
+        "(#{keyword_unset_flag(name)} ? #{shadow_name(name)} : #{name})"
+      else
+        "(#{locals_hash}.key?(#{name.inspect}) ? #{name} : #{shadow_name(name)})"
+      end
+    end
+
+    # `x op= v` => `__dynamic_locals_shadow_x = x = <guarded read> op (v)`
+    # The parens around the value preserve associativity (`x -= a - b`); any
+    # newlines between the operator and its value re-emit after the opening
+    # paren so the value keeps its line.
+    def expand_operator_write(node, scopes)
+      name = node.name
+      op =
+        case node
+        when Prism::LocalVariableOrWriteNode then "||"
+        when Prism::LocalVariableAndWriteNode then "&&"
+        else node.binary_operator.to_s
+        end
+      value_offset = node.value.location.start_offset
+      newlines = "\n" * node.slice.byteslice(0, value_offset - node.location.start_offset).count("\n")
+      prefix = "#{shadow_name(name)} = #{name} = #{shadow_read_src(name)} #{op} (#{newlines}"
+      @rewriter.replace_offsets(node.location.start_offset, value_offset, prefix)
+      @rewriter.insert_after(node.value, ")")
+    end
+
+    # `a, b = v` =>
+    # `__dynamic_locals_shadow_a, __dynamic_locals_shadow_b = (a, b = v)`
+    # A masgn evaluates to its right-hand side, so a structurally identical
+    # outer masgn assigns the same values to the shadows. Targets that don't
+    # need a shadow become a discard variable (duplicates are legal).
+    def shadow_multi_write(node, scopes)
+      copied, any = copy_masgn_targets(node, scopes)
+      return unless any
+      @rewriter.insert_before(node, "#{copied} = (")
+      @rewriter.insert_after(node, ")")
+    end
+
+    def copy_masgn_targets(node, scopes)
+      any = false
+      items = []
+      node.lefts.each do |target|
+        src, hit = copy_masgn_target(target, scopes)
+        any ||= hit
+        items << src
+      end
+      case node.rest
+      when Prism::SplatNode
+        if (expression = node.rest.expression)
+          src, hit = copy_masgn_target(expression, scopes)
+          any ||= hit
+          items << "*#{src}"
+        else
+          items << "*"
+        end
+      when Prism::ImplicitRestNode
+        items << ""
+      end
+      node.rights.each do |target|
+        src, hit = copy_masgn_target(target, scopes)
+        any ||= hit
+        items << src
+      end
+      [items.join(", "), any]
+    end
+
+    def copy_masgn_target(node, scopes)
+      case node
+      when Prism::LocalVariableTargetNode
+        if shadow_binding?(node.name, node.depth, scopes)
+          [shadow_name(node.name).to_s, true]
+        else
+          [discard_name.to_s, false]
+        end
+      when Prism::MultiTargetNode
+        src, any = copy_masgn_targets(node, scopes)
+        ["(#{src})", any]
+      else
+        # Attribute/index/constant/etc. targets: assign to a discard variable
+        # instead so the side effect isn't repeated.
+        [discard_name.to_s, false]
+      end
+    end
+
+    # `/(?<word>...)/ =~ str` assigns its named captures as locals. It's an
+    # expression (often a condition), so sync the shadows inside a wrapper that
+    # preserves the match result:
+    # `(tmp = (re =~ str); __dynamic_locals_shadow_word = word; tmp)`
+    def shadow_match_write(node, scopes)
+      names = node.targets.filter_map do |target|
+        next unless Prism::LocalVariableTargetNode === target
+        target.name if shadow_binding?(target.name, target.depth, scopes)
+      end
+      return if names.empty?
+
+      temp = match_temp_name
+      syncs = names.map { |name| "#{shadow_name(name)} = #{name}" }.join("; ")
+      @rewriter.insert_before(node, "(#{temp} = (")
+      @rewriter.insert_after(node, "); #{syncs}; #{temp})")
+    end
+
+    def match_temp_name
+      @match_temp_name ||= generate_hygienic_name("__dynamic_locals_match")
+    end
+
+    # `rescue => e` has no expression form to wrap, so sync the shadow as the
+    # first statement of the rescue body.
+    def shadow_rescue_reference(node, scopes)
+      reference = node.reference
+      return unless Prism::LocalVariableTargetNode === reference
+      return unless shadow_binding?(reference.name, reference.depth, scopes)
+
+      sync = "#{shadow_name(reference.name)} = #{reference.name}"
+      insert_at_body_start(node, node.then_keyword_loc, sync) do
+        @rewriter.insert_after(reference, "; #{sync}")
+      end
+    end
+
+    # `for x in list` assigns its index in the enclosing scope; sync the shadow
+    # at the top of the loop body.
+    def shadow_for_index(node, scopes)
+      names = []
+      each_local_target(node.index) do |target|
+        names << target.name if shadow_binding?(target.name, target.depth, scopes)
+      end
+      return if names.empty?
+
+      sync = names.map { |name| "#{shadow_name(name)} = #{name}" }.join("; ")
+      insert_at_body_start(node, node.do_keyword_loc, sync) do
+        @rewriter.insert_at(node.collection.location.end_offset, " do #{sync}")
+      end
+    end
+
+    # `expr => pattern` raises on mismatch, so on any fall-through the targets
+    # were assigned; sync unconditionally, preserving the expression's value:
+    # `begin tmp = (expr); tmp => pattern; __dynamic_locals_shadow_x = x; tmp end`
+    def shadow_required_pattern(node, scopes)
+      names = shadow_pattern_names(node.pattern, scopes)
+      return if names.empty?
+
+      result = generate_hygienic_name("__dynamic_locals_pattern_result")
+      @rewriter.insert_before(node, "begin #{result} = (")
+      @rewriter.insert_after(node.value, "); #{result}")
+      @rewriter.insert_after(node, "; #{shadow_sync_src(names)}; #{result} end")
+    end
+
+    # `expr in pattern` is a boolean; sync only when it matched:
+    # `(begin tmp = (expr in pattern); __dynamic_locals_shadow_x = x if tmp; tmp end)`
+    def shadow_predicate_pattern(node, scopes)
+      names = shadow_pattern_names(node.pattern, scopes)
+      return if names.empty?
+
+      result = generate_hygienic_name("__dynamic_locals_pattern_result")
+      @rewriter.insert_before(node, "(begin #{result} = (")
+      @rewriter.insert_after(
+        node,
+        "); #{shadow_sync_src(names)} if #{result}; #{result} end)",
+      )
+    end
+
+    # A `case/in` clause's targets are assigned once its pattern matches, even
+    # if a guard then rejects it, so sync at the start of the clause body -- or
+    # inside the guard itself, which can already read the captures.
+    def shadow_in_clause(node, scopes)
+      guard = node.pattern if Prism::IfNode === node.pattern || Prism::UnlessNode === node.pattern
+      pattern = guard ? guard.statements : node.pattern
+      names = shadow_pattern_names(pattern, scopes)
+      return yield if names.empty?
+
+      sync = shadow_sync_src(names)
+      if guard
+        predicate = guard.predicate
+        # Register the closing insertion after rewriting the predicate so a
+        # nested pattern wrapper closes before this guard wrapper.
+        @rewriter.insert_before(predicate, "(begin #{sync}; ")
+        yield
+        @rewriter.insert_after(predicate, " end)")
+      else
+        insert_at_body_start(node, node.then_loc, sync) do
+          @rewriter.insert_after(node.pattern, "; #{sync};")
+        end
+        yield
+      end
+    end
+
+    def shadow_pattern_names(pattern, scopes)
+      names = []
+      each_local_target(pattern) do |target|
+        names << target.name if shadow_binding?(target.name, target.depth, scopes)
+      end
+      names.uniq
+    end
+
+    def shadow_sync_src(names)
+      names.map { |name| "#{shadow_name(name)} = #{name}" }.join("; ")
+    end
+
+    # Insert +src+ as the first statement of +node+'s body. An empty body has
+    # no statement to insert before, so it goes after +keyword_loc+ (the
+    # node's `then`/`do`) instead; when that is also absent, yields to let the
+    # caller pick a spot.
+    def insert_at_body_start(node, keyword_loc, src)
+      if (first = node.statements&.body&.first)
+        @rewriter.insert_before(first, "#{src}; ")
+      elsif keyword_loc
+        @rewriter.insert_at(keyword_loc.end_offset, " #{src};")
+      else
+        yield
+      end
+    end
+
+    def each_local_target(node, &block)
+      return unless Prism::Node === node
+
+      if Prism::LocalVariableTargetNode === node
+        yield node
+      else
+        node.child_nodes.each { |child| each_local_target(child, &block) }
+      end
+    end
+
+    def local_operator_write?(node)
+      Prism::LocalVariableOperatorWriteNode === node ||
+        Prism::LocalVariableOrWriteNode === node ||
+        Prism::LocalVariableAndWriteNode === node
+    end
+
+    def initialize_local_table
+      return "" if keywords?
+      (@local_table.sort.uniq - known_locals).map do |local|
+        "#{local} = #{locals_hash}[#{local.inspect}];"
+      end.join
+    end
+
+    def local_lookup_src(name, fallback)
+      if keywords?
+        "(#{keyword_unset_flag(name)} ? #{name}() : #{name})"
+      elsif @local_table.include?(name)
+        "(#{locals_hash}.key?(#{name.inspect}) ? #{name} : #{fallback})"
+      else
+        "#{locals_hash}.fetch(#{name.inspect}){ #{fallback} }"
+      end
+    end
+
+    def defined_lookup_src(name)
+      if keywords?
+        "(#{keyword_unset_flag(name)} ? defined?(#{name}()) : 'local-variable'.freeze)"
+      else
+        "(#{locals_hash}.key?(#{name.inspect}) ? 'local-variable'.freeze : defined?(#{name}()))"
+      end
+    end
+
+    def keyword_unset_flag(name)
+      @keyword_unset_flags[name] ||=
+        generate_hygienic_name("__dynamic_locals_unset_#{@keyword_unset_flags.length}")
+    end
+
+    def keywords?
+      lookup_strategy == :keywords
+    end
+
+    def nested_local_table(node)
+      node.locals - parameter_names(node.parameters)
+    end
+
+    def parameter_names(node, names = [])
+      return names unless Prism::Node === node
+
+      if Prism::NumberedParametersNode === node
+        node.maximum.times { |i| names << :"_#{i + 1}" }
+      elsif parameter_node?(node) && node.respond_to?(:name) && node.name
+        names << node.name
+      elsif Prism::BlockLocalVariableNode === node
+        names << node.name
+      end
+
+      node.child_nodes.each { |child| parameter_names(child, names) }
+      names
+    end
+
+    def parameter_node?(node)
+      node.class.name.start_with?("Prism::") && node.class.name.end_with?("ParameterNode")
+    end
+
+    def nested_scope?(node)
+      Prism::BlockNode === node || Prism::LambdaNode === node
+    end
+
+    # Scopes that don't share our local table: recurse only into the parts
+    # still evaluated in the enclosing scope.
+    def child_nodes_for_method_body(node)
+      case node
+      when Prism::DefNode
+        [node.receiver]
+      when Prism::ClassNode
+        [node.superclass]
+      when Prism::ModuleNode
+        []
+      when Prism::SingletonClassNode
+        [node.expression]
+      else
+        node.child_nodes
+      end
+    end
+
+    def variable_call?(node)
+      Prism::CallNode === node && node.variable_call? && !known_locals.include?(node.name)
+    end
+
+    def defined_variable_call?(node)
+      Prism::DefinedNode === node && variable_call?(node.value)
+    end
+  end
+end

data/lib/dynamic_locals/version.rb

@@ -0,0 +1,3 @@
+module DynamicLocals
+  VERSION = "0.1.0"
+end

data/lib/dynamic_locals.rb

@@ -0,0 +1,20 @@
+require "dynamic_locals/version"
+require "dynamic_locals/base_translator"
+require "dynamic_locals/eval_translator"
+require "dynamic_locals/rewrite_translator"
+
+module DynamicLocals
+  class Error < StandardError; end
+
+  DefaultImplementation = RewriteTranslator
+
+  def self.translate(...)
+    DefaultImplementation.new(...).translate
+  end
+
+  # This is intended for convenience debugging purposes
+  def self.compile(...)
+    translator = DefaultImplementation.new(...)
+    eval("-> (#{translator.parameters}) { #{translator.translate} }")
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: dynamic_locals
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- John Hawthorn
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Parses ruby to rewrite how locals work
+email:
+- john@hawthorn.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/test.yml"
+- ".gitignore"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- dynamic_locals.gemspec
+- lib/dynamic_locals.rb
+- lib/dynamic_locals/ast_rewriter.rb
+- lib/dynamic_locals/base_translator.rb
+- lib/dynamic_locals/eval_translator.rb
+- lib/dynamic_locals/rewrite_translator.rb
+- lib/dynamic_locals/version.rb
+homepage: https://github.com/jhawthorn/dynamic_locals
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Makes it possible to define locals dynamically
+test_files: []