ast_transform 1.0.0.pre.alpha.pre.15

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 48a95ba22654bc424c664e918b4d05d96938aa9647adfa742de94f9fb21ea6ce
+  data.tar.gz: 42611d110dbf44a11603d05b83b1eadfafb49fb0733dbb1063ec0f204af0fa3a
+SHA512:
+  metadata.gz: 84cd1fb8c9a63f0f565cc1cf6bf2cf75e10d0d6e8920372049f147aa6ddb7cc48e1324178a3358993bb826521d29bdb80ff7d7095a4150f6cf2d6ec71fda024b
+  data.tar.gz: a6a1411fbcd95e50ae9834d82a29093707feaac26e604364bd04e4e8c7f0510db44a8b205ac67422bb33e90ad9d11c7bb78dbcb1cb941715e27fb7255e6e87a6

data/.gitignore

@@ -0,0 +1,53 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# RubyMine
+/.idea

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+rvm:
+- '2.2'
+- '2.3'
+- '2.4'
+- '2.5'
+- '2.6'
+- '2.7'
+install: ./bin/setup
+deploy:
+  provider: rubygems
+  gemspec: ast_transform.gemspec
+  gem: ast_transform
+  on:
+    branch: master
+    tag: true
+  api_key:
+    secure: a+D7+wUWmgdk39C+oDFAqjLDAE9s8uaN08xPgf0/IaxFy3PGeuxKSi+3ZFaB0f6zI203mMe7m0sNVD77PxyPqKToKal5K9240+m9yZGoS4seMOJExcBmhiMXk8KOj9upw5Fk0PY91LY5lU13m6u40MtHT9r8da8AysO21PGhkrDkYZNGZ/0nCpV3hnux6DOlNguUhHuuKIKCY6xN9tldwUhVZJvDjSKLe0aRMbP0PZhM3JzMz9BfosirkdE9u666ryI5kIFfHgzDCekiU1sbEugOKyHyu90kaVhgRAXA81LHirj6U9pA0cfJOq84EAE2di6A0xswlbM8GBXdJpRIh706A6sZ7ByYG2SlxyF9vHogqhpg8aU5IMk+sNbrg6++qyTW8zSTksoJN/kMAHcEvMloK4Ja2rRPqhIJkawcQRd5unxHnt4jc6ED2ryDbXhAaBWX4G80jpg5lSeHIQH/S9v+PWcG9UB8Rv08oiJadEid+26r4rWsRA0f/hBP6K+KMq3rACa2Xapgo9ZbSE4xBBu+Yc+4ooiKQ42y+10A5TlTI6iSxKUDcmbH/qVZIchzlDv4MFYoE50BHVn9p0J6dbf8q+WQXsRi1ojEcVy95hd00wdmeMGItE7VuW8zDObJ5W8LNaKuKD358o+4v5CrammfNNz/MynRXhfmPCwyy8s=

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.4] 2019-06-20
+### Fixed
+- Source mapping for transformations wrapping source nodes into virtual nodes now work.
+
+## [0.1.3] 2019-05-28
+### Added
+- Changing the output path for transformed files is now supported through `ASTTransform.output_path=`.
+
+## [0.1.2] 2018-12-21
+### Fixed
+- Bumped and relaxed Unparser dependency to ~> 0.4
+
+## [0.1.1] 2018-12-06
+### Added
+- ASTTransform::Transformer now supports passing a custom AST::Node Builder.
+
+## [0.1.0] 2018-11-08
+### Initial Release!

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 ast_transform.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,69 @@
+PATH
+  remote: .
+  specs:
+    ast_transform (1.0.0)
+      parser (~> 2.7)
+      unparser (~> 0.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    abstract_type (0.0.7)
+    adamantium (0.2.0)
+      ice_nine (~> 0.11.0)
+      memoizable (~> 0.4.0)
+    ansi (1.5.0)
+    ast (2.4.1)
+    builder (3.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concord (0.1.5)
+      adamantium (~> 0.2.0)
+      equalizer (~> 0.0.9)
+    diff-lcs (1.4.4)
+    equalizer (0.0.11)
+    ice_nine (0.11.2)
+    memoizable (0.4.2)
+      thread_safe (~> 0.3, >= 0.3.1)
+    method_source (1.0.0)
+    minitest (5.14.1)
+    minitest-reporters (1.4.2)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    parser (2.7.1.4)
+      ast (~> 2.4.1)
+    procto (0.0.3)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.9.0)
+      byebug (~> 11.0)
+      pry (~> 0.13.0)
+    rake (13.0.1)
+    ruby-progressbar (1.10.1)
+    thread_safe (0.3.6)
+    unparser (0.4.7)
+      abstract_type (~> 0.0.7)
+      adamantium (~> 0.2.0)
+      concord (~> 0.1.5)
+      diff-lcs (~> 1.3)
+      equalizer (~> 0.0.9)
+      parser (>= 2.6.5)
+      procto (~> 0.0.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  ast_transform!
+  bundler (~> 2.1)
+  minitest (~> 5.14)
+  minitest-reporters (~> 1.4.2)
+  pry
+  pry-byebug
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Jean-Philippe Duchesne
+
+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,185 @@
+[![Build Status](https://travis-ci.org/rspockframework/ast-transform.svg?branch=master)](https://travis-ci.org/rspockframework/ast-transform)
+
+# ASTTransform
+
+ASTTransform is an Abstract Syntax Tree (AST) transformation framework. It hooks into the compilation process and allows to perform AST transformations using an annotation: `transform!`.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ast_transform'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ast_transform
+
+Add this to the very beginning of your script or application to install the ASTTransform hook:
+
+```ruby
+require 'ast_transform'
+ASTTransform.install
+```
+
+### Compatibility with Bootsnap
+
+ASTTransform is compatible with [Bootsnap](https://github.com/Shopify/bootsnap/). The only requirement is to install the above hook after Bootsnap, and ASTTransform does the rest for you.
+
+## Usage
+
+Getting started using ASTTransform is extremely easy! All you need is to use the `transform!` annotation:
+
+```ruby
+transform!(MyTransformation)
+class MyClass
+  # ...
+end
+```
+
+When your class is required and loaded into the runtime, ASTTransform will run the `MyTransformation` transformation on the annotated code.
+
+### Supported annotated code
+
+The following expressions can be annotated, which will pass only the annotated AST node to the transformation:
+
+#### Class definitions
+
+```ruby
+transform!(MyTransformation)
+class Foo
+  # ...
+end
+```
+
+#### Constant assignments
+
+```ruby
+transform!(MyTransformation)
+Foo = Class.new do
+  # ...
+end
+```
+
+### Running multiple transformations
+
+#### On the same AST node
+
+You can run multiple transformations on the same code, by passing multiple transformations to the annotation:
+
+```ruby
+transform!(MyTransformation1, MyTransformation2)
+class Foo
+  # ...
+end
+```
+
+**Note**: The transformations will be executed in order, the output of the previous transformation being fed into the next, etc...
+
+#### On different AST nodes
+
+Because each `transform!` annotation runs transformations in isolated scope, it is possible to have multiple annotated nodes in the same file:
+
+```ruby
+transform!(MyTransformation)
+class Foo
+  # ...
+end
+
+transform!(MyTransformation)
+class Bar
+  # ...
+end
+```
+
+You can even have nested `transform!` annotations:
+
+```ruby
+transform!(FooTransformation)
+class Foo
+  transform!(BarTransformation)
+  class Bar
+    # ...
+  end
+
+  # ...
+end
+```
+
+The above code would first process class `Foo` using `FooTransformation` (which could even make modifications to `Bar` on its own), and then `BarTransformation` would be run against `Bar`.
+
+### Writing Transformations
+
+For more in-depth information regarding processing AST nodes, we recommend looking at https://github.com/whitequark/ast, as transformations are built on top of `Parser::AST::Processor`, which in turn is built on top of the `ast` gem.
+
+Transformations should derive from `ASTTransform::AbstractTransformation`:
+
+```ruby
+require 'ast_transform/abstract_transformation'
+
+class MyTransformation < ASTTransformation::AbstractTransformation
+  # ...
+end
+```
+
+#### Transformation discoverability
+
+ASTTransform automatically loads your transformations at compile time. As such, we expect your files to be located at a known path.
+
+Transformations are required using the following scheme, i.e. for `MyNamespace::MyTransformation`, it will make the following call, so your file must be placed accordingly for ASTTransform to find it:
+```ruby
+require 'my_namespace/my_transformation'
+```
+
+#### Processing each node
+
+To do some processing on each node, override the `process_node` private method. If you do this, make sure to also process the children nodes if required.
+
+```ruby
+require 'ast_transform/abstract_transformation'
+
+class MyTransformation < ASTTransformation::AbstractTransformation
+  private
+
+  def process_node(node)
+    # ... processing
+    node.updated(nil, process_all(node.children))
+  end
+end
+```
+
+In the above, `node#updated` allows updating the node, either its type or its children. Each node is immutable, so updating nodes requires recursively re-creating the tree from the deepest modified nodes. Passing `nil` as the first argument keeps the same node type.
+
+#### Processing on certain types of nodes only
+
+The [ast gem](https://github.com/whitequark/ast) uses a pattern in which a Transformation may implement a method matching a node type, i.e. `on_class`, `on_send`, `on_lvar`, etc... This is very useful when transformations should process all nodes of this type.
+
+### Parameterizable transformations
+
+If you want your transformation to be customizable, accept the parameters in the constructor. The annotation can the be changed accordingly:
+
+```ruby
+class FooTransformation < ASTTransform::AbstractTransformation
+  def initialize(param1, params2: false)
+    # ...
+  end
+
+  # ...
+end
+
+transform!(FooTransformation.new(param1, param2: true))
+class Foo
+  # ...
+end
+```
+
+## 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).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  # Ensure we load test_loader first for ASTTransform.install
+  filepath = File.expand_path('test/test_loader.rb', __dir__)
+  t.ruby_opts << "-r #{filepath}"
+  t.warning = false
+
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/ast_transform.gemspec

@@ -0,0 +1,43 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "ast_transform/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "ast_transform"
+  spec.version       = ASTTransform::VERSION
+  spec.authors       = ["Jean-Philippe Duchesne"]
+  spec.email         = ["jpduchesne89@gmail.com"]
+
+  spec.summary       = 'An AST transformation framework.'
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/rspockframework/ast-transform"
+  spec.license       = "MIT"
+  spec.files         = `git ls-files -z`.split("\x0").reject do |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.required_ruby_version = '~> 2.2'
+
+  if ENV['TRAVIS']
+    if ENV['TRAVIS_TAG'].nil? || ENV['TRAVIS_TAG'].empty?
+      spec.version = "#{spec.version}-alpha-#{ENV['TRAVIS_BUILD_NUMBER']}"
+    elsif ENV['TRAVIS_TAG'] != spec.version.to_s
+      raise "Tag name (#{ENV['TRAVIS_TAG']}) and Gem version (#{spec.version}) are different"
+    end
+  end
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.1"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.14"
+  spec.add_development_dependency "minitest-reporters", "~> 1.4.2"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-byebug"
+
+  # Runtime dependencies
+  spec.add_runtime_dependency "parser", "~> 2.7"
+  spec.add_runtime_dependency "unparser", "~> 0.4"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "ast_transform"
+
+# 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/lib/ast_transform/abstract_transformation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+require 'ast_transform/transformation_helper'
+
+module ASTTransform
+  class AbstractTransformation < Parser::AST::Processor
+    include TransformationHelper
+
+    # Runs this transformation on +node+.
+    # Note: If you want to add one-time checks to the transformation, override this, then call super.
+    #
+    # @param node [Parser::AST::Node] The node to be transformed.
+    #
+    # @return [Parser::AST::Node] The transformed node.
+    def run(node)
+      process(node)
+    end
+
+    # Used internally by Parser::AST::Processor to process each node. DO NOT OVERRIDE.
+    def process(node)
+      return node unless node.is_a?(Parser::AST::Node)
+
+      process_node(node)
+    end
+
+    private
+
+    # Processes the given +node+.
+    # Note: If you want to do processing on each node, override this.
+    #
+    # @param node [Parser::AST::Node] The node to be transformed.
+    #
+    # @return [Parser::AST::Node] The transformed node.
+    def process_node(node)
+      method(:process).super_method.call(node)
+    end
+  end
+end

data/lib/ast_transform/instruction_sequence/bootsnap_mixin.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'ast_transform/transformer'
+require 'ast_transform/instruction_sequence/mixin_utils'
+require 'pathname'
+
+module ASTTransform
+  module InstructionSequence
+    module BootsnapMixin
+      def input_to_storage(source, source_path)
+        return ASTTransform::MixinUtils.try_super(self, :input_to_storage, source, source_path) if source_path == __FILE__
+        return ASTTransform::MixinUtils.try_super(self, :input_to_storage, source, source_path) unless source =~ /transform!/
+
+        iseq = ASTTransform::InstructionSequence.source_to_transformed_iseq(source, source_path)
+        iseq.to_binary
+      rescue SyntaxError
+        raise ::Bootsnap::CompileCache::Uncompilable, 'syntax error'
+      end
+    end
+  end
+end

data/lib/ast_transform/instruction_sequence/mixin.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+require 'pathname'
+require 'ast_transform/transformer'
+require 'ast_transform/transformation'
+require 'ast_transform/instruction_sequence/mixin_utils'
+
+module ASTTransform
+  module InstructionSequence
+    module Mixin
+      def load_iseq(source_path)
+        return ASTTransform::MixinUtils.try_super(self, :load_iseq, source_path) if source_path == __FILE__
+
+        source = File.read(source_path)
+
+        return ASTTransform::MixinUtils.try_super(self, :load_iseq, source_path) unless source =~ /transform!/
+
+        ASTTransform::InstructionSequence.source_to_transformed_iseq(source, source_path)
+      end
+    end
+  end
+end

data/lib/ast_transform/instruction_sequence/mixin_utils.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ASTTransform
+  module MixinUtils
+    class << self
+      def try_super(target, method_sym, *args, &block)
+        super_method = target.method(method_sym).super_method
+        super_method ? super_method.call(*args, &block) : nil
+      end
+    end
+  end
+end

data/lib/ast_transform/instruction_sequence.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+module ASTTransform
+  module InstructionSequence
+    class << self
+      def using_bootsnap_compilation?
+        filepath, = RubyVM::InstructionSequence.method(:load_iseq).source_location
+        filepath =~ %r{/bootsnap/}
+      rescue NameError
+        false
+      end
+
+      def source_to_transformed_iseq(source, source_path)
+        transformer = ASTTransform::Transformer.new(ASTTransform::Transformation.new)
+        rewritten_file_pathname = write_pathname(source_path)
+
+        rewritten_source = transformer.transform_file_source(source, source_path, rewritten_file_pathname.to_s)
+        write(rewritten_source, rewritten_file_pathname)
+
+        RubyVM::InstructionSequence.compile(rewritten_source, rewritten_file_pathname.to_s, rewritten_file_pathname.to_s)
+      end
+
+      def write_pathname(file_path)
+        project_path = File.expand_path("")
+        relative_source_file_pathname = Pathname.new(file_path).relative_path_from(Pathname.new(project_path))
+        Pathname.new("").join(project_path, 'tmp', 'ast_transform', relative_source_file_pathname)
+      end
+
+      def write(string, pathname)
+        FileUtils.mkdir_p(pathname.dirname)
+        File.open(pathname, 'w') do |file|
+          file.write(string)
+        end
+      end
+    end
+  end
+end

data/lib/ast_transform/source_map.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+require 'parser/current'
+
+module ASTTransform
+  class SourceMap
+    class << self
+      # Registers the given SourceMap.
+      #
+      # @param source_map [SourceMap] The source map to be registered.
+      #
+      # @return [void]
+      def register_source_map(source_map)
+        source_maps[source_map.transformed_file_path] = source_map
+
+        nil
+      end
+
+      # Retrieves the SourceMap for the given +file_path+.
+      #
+      # @param file_path [String] The transformed file path.
+      #
+      # @return [SourceMap|nil] The associated source map.
+      def for_file_path(file_path)
+        source_maps[file_path]
+      end
+
+      private
+
+      def source_maps
+        @@source_maps ||= {}
+      end
+    end
+
+    # Constructs a new SourceMap instance.
+    #
+    # Note: +source_ranges_ast+ and +transformed_ranges_ast+ must be equivalent ASTs.
+    #
+    # @param source_file_path [String] The path to the source file.
+    # @param transformed_file_path [String] The path to the transformed file.
+    # @param source_ranges_ast [Parser::AST::Node] A transformed AST that contains the source code ranges.
+    # @param transformed_ranges_ast [Parser::AST::Node] A transformed AST that contains the ranges for the executed
+    # code.
+    def initialize(source_file_path, transformed_file_path, source_ranges_ast, transformed_ranges_ast)
+      @source_file_path = source_file_path
+      @transformed_file_path = transformed_file_path
+      @source_ranges_ast = source_ranges_ast
+      @transformed_ranges_ast = transformed_ranges_ast
+
+      @lines = Hash.new { |hash, key| hash[key] = [] }
+      extract_source_map_data(@transformed_ranges_ast, [])
+      @source_map = build_source_map.freeze
+    end
+
+    attr_reader :source_file_path, :transformed_file_path, :source_map
+
+    # Retrieves the mapped line number for the given +line_number+.
+    #
+    # @param line_number [Integer] The line number in the executed code to be mapped to the source.
+    #
+    # @return [Integer|nil] The mapped line number, otherwise nil if not found.
+    def line(line_number)
+      @source_map[line_number]
+    end
+
+    # Retrieves the line count for the executed code.
+    #
+    # @return [Integer] The line count.
+    def line_count
+      @transformed_ranges_ast&.loc&.expression.last_line || 0
+    end
+
+    private
+
+    # Extracts SourceMap data from the given node.
+    #
+    # @param node [Parser::AST::Node] The node containing ranges for the executed code.
+    #
+    # @return [void]
+    def extract_source_map_data(node, indexes)
+      return false unless node&.is_a?(Parser::AST::Node)
+
+      range = node.loc&.expression
+
+      if range && range.line == range.last_line
+        @lines[range.line] << indexes.dup
+      end
+
+      node.children.each.with_index do |child, index|
+        extract_source_map_data(child, indexes.dup << index)
+      end
+
+      nil
+    end
+
+    # Builds the source map.
+    #
+    # @return [Hash] A Hash containing line numbers from executed code to source code.
+    def build_source_map
+      (1..line_count).each.with_object({}) {|it, hash| hash[it] = source_line(it) }
+    end
+
+    # Retrieves the source line for the given +line_number+ in the executed code.
+    #
+    # @param line_number [Integer] The line number in the executed code.
+    #
+    # @return [Integer|nil] The line number in the source code, or nil if cannot be mapped.
+    def source_line(line_number)
+      if @lines.key?(line_number)
+        @lines[line_number].each do |dig_array|
+          source_node = approximate_dig_last_valid_node(@source_ranges_ast, dig_array)
+          next unless source_node
+
+          range = search_range(source_node, 1)
+          return range.line if range
+        end
+      end
+
+      nil
+    end
+
+    # Recursively look for node represented by +indexes+ in +node+. If not found, goes back +depth+ nodes and search for
+    # the node pointed to by +indexes+.
+    #
+    # @param node [Parser::AST::Node] The node to search into. This must be a node in the +@source_ranges_ast+.
+    # @param indexes [Array<Integer>] Child indexes pointing to the node we're looking for in +node+.
+    # @param depth [Integer] Number of nodes to go up to search for the node pointed to by +indexes+.
+    #
+    # @return [Parser::AST::Node|nil] The node found, nil otherwise.
+    def approximate_dig_last_valid_node(node, indexes, depth = 1)
+      return node if indexes.empty?
+
+      result = dig_node(node, indexes)
+      return result if result.is_a?(Parser::AST::Node) || depth <= 0
+
+      queried_node = dig_last_valid_node(@transformed_ranges_ast, indexes)
+
+      last_known_index = dig_last_valid_node_index(node, indexes[0...-depth])
+      query_indexes = indexes[0...last_known_index]
+
+      last_known_node = dig_node(node, query_indexes)
+
+      search_node(last_known_node, queried_node)
+    end
+
+    # Recursively search the children of +node+ for an equivalent +queried_node+.
+    #
+    # @param node [Parser::AST::Node] The current node to search in.
+    # @param queried_node [Parser::AST::Node] The equivalent node to search for.
+    #
+    # @return [Parser::AST::Node|nil] The found node from the +node+ graph, nil otherwise.
+    def search_node(node, queried_node)
+      return unless node&.is_a?(Parser::AST::Node)
+      return node if node == queried_node
+
+      node.children.each do |child_node|
+        result = search_node(child_node, queried_node)
+        return result if result
+      end
+
+      nil
+    end
+
+    # Recursively search the given +node+ for a range.
+    #
+    # @param node [Parser::AST::Node] The current node to search in.
+    # @param max_range [Integer|nil] The max range to consider valid. Nil means any range is valid. If 1, only ranges
+    # which span one line will be considered, etc...
+    #
+    # @return [Parser::Source::Range|nil] The range, or nil if no range was found. This occurs when the tree contains
+    # no ranges, i.e. they're all virtually built nodes.
+    def search_range(node, max_range = nil)
+      return unless node&.is_a?(Parser::AST::Node)
+
+      range = node.loc&.expression
+      if range && max_range && range.last_line - range.line < max_range || range && max_range.nil?
+        return range
+      else
+        node.children.each do |child_node|
+          result = search_range(child_node, max_range)
+          return result if result
+        end
+      end
+
+      nil
+    end
+
+    # Finds the index for the last valid node represented by +indexes+ in the children of +node+.
+    #
+    # @param node [Parser::AST::Node] The current node to search in.
+    # @param indexes [Array<Integer>] The array of indexes pointing to the child node to be retrieved from +node+.
+    #
+    # @return [Integer|nil] The index of the node if found, nil otherwise.
+    def dig_last_valid_node_index(node, indexes)
+      return if indexes.empty?
+
+      result = dig_node(node, indexes)
+      current_index = indexes&.size
+      return current_index if result.is_a?(Parser::AST::Node)
+
+      dig_last_valid_node_index(node, indexes[0...-1])
+    end
+
+    # Recursively look for the node represented by +indexes+ in the children of +node+. If not found, returns the last
+    # valid node.
+    #
+    # @param node [Parser::AST::Node] The node to look into.
+    # @param indexes [Array<Integer>] The array of indexes pointing to the child node to be retrieved from +node+.
+    #
+    # @return [Parser::AST::Node|nil] The node if found, nil otherwise.
+    def dig_last_valid_node(node, indexes)
+      return node if indexes.empty?
+
+      result = dig_node(node, indexes)
+      return result if result.is_a?(Parser::AST::Node)
+
+      dig_last_valid_node(node, indexes[0...-1])
+    end
+
+    # Recursively look for the node represented by +indexes+ in the children of +node+.
+    #
+    # @param node [Parser::AST::Node] The node to look into.
+    # @param indexes [Array<Integer>] The array of indexes pointing to the child node to be retrieved from +node+.
+    #
+    # @return [Parser::AST::Node|nil] The node if found, nil otherwise.
+    def dig_node(node, indexes)
+      indexes.inject(node) do |node, index|
+        return nil unless node.is_a?(Parser::AST::Node)
+        node.children[index]
+      end
+    end
+  end
+end

data/lib/ast_transform/transformation.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+require 'ast_transform'
+require 'ast_transform/abstract_transformation'
+require 'ast_transform/transformer'
+require 'unparser'
+
+module ASTTransform
+  class Transformation < ASTTransform::AbstractTransformation
+    TRANSFORM_AST = s(:send, nil, :transform!)
+
+    private
+
+    def process_node(node)
+      children = node.children.map.with_index do |child_node, index|
+        previous_sibling = previous_child(node, index)
+        process_node_helper(child_node, previous_sibling)
+      end
+
+      children.reject!.with_index { |child_node, index|
+        transform_node?(child_node) && transformable_node?(next_child(node, index))
+      }
+
+      node.updated(nil, process_all(children))
+    end
+
+    def previous_child(node, index)
+      index > 0 ? node.children[index - 1] : nil
+    end
+
+    def next_child(node, index)
+      index >= 0 ? node.children[index + 1] : nil
+    end
+
+    def process_node_helper(node, previous_node)
+      if transform_node?(previous_node) && transformable_node?(node)
+        transformations = extract_transformations(previous_node)
+        ASTTransform::Transformer.new(*transformations).transform_ast(node)
+      else
+        node
+      end
+    end
+
+    def transform_node?(node)
+      return false unless node.is_a?(Parser::AST::Node)
+
+      node.type == :send && node.children.count >= 3 && node.children[0].nil? && node.children[1] == :transform!
+    end
+
+    def transformable_node?(node)
+      return false unless node.is_a?(Parser::AST::Node)
+
+      [:class, :casgn].include?(node.type)
+    end
+
+    def extract_transformations(node)
+      node.children.map do |child_node|
+        extract_transformation(child_node)
+      end.compact!
+    end
+
+    def extract_transformation(node)
+      return unless node.is_a?(Parser::AST::Node)
+      return unless node.children.count >= 2
+
+      if node.children[1] == :new
+        require_transformation(node)
+        code = Unparser.unparse(node)
+
+        TOPLEVEL_BINDING.eval(code)
+      else
+        require_transformation(node)
+        code = "#{Unparser.unparse(node)}.new"
+
+        TOPLEVEL_BINDING.eval(code)
+      end
+    end
+
+    def require_transformation(node)
+      const_node = node.children.first
+      const_name = Unparser.unparse(const_node)
+
+      constant = try_const_get(const_name)
+      unless constant
+        require_path = require_path(const_name)
+        require(require_path)
+      end
+
+      nil
+    end
+
+    def require_path(const_name)
+      acronyms = ASTTransform.acronyms
+      acronym_regex = acronyms.empty? ? /(?=a)b/ : /#{acronyms.join("|")}/
+      return const_name unless /[A-Z-]|::/.match?(const_name)
+      word = const_name.to_s.gsub("::".freeze, "/".freeze)
+      word.gsub!(/(?:(?<=([A-Za-z\d]))|\b)(#{acronym_regex})(?=\b|[^a-z])/) { "#{$1 && '_'.freeze }#{$2.downcase}" }
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2'.freeze)
+      word.gsub!(/([a-z\d])([A-Z])/, '\1_\2'.freeze)
+      word.tr!("-".freeze, "_".freeze)
+      word.downcase!
+      word
+    end
+
+    def try_const_get(const_name)
+      Object.const_get(const_name)
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/ast_transform/transformation_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+require 'parser'
+
+module ASTTransform
+  module TransformationHelper
+    def self.included(base)
+      base.extend(Methods)
+      base.include(Methods)
+    end
+
+    module Methods
+      def s(type, *children, **properties)
+        Parser::AST::Node.new(type, children, properties)
+      end
+    end
+  end
+end

data/lib/ast_transform/transformer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+require 'parser/current'
+require 'unparser'
+require 'ast_transform/source_map'
+
+module ASTTransform
+  class Transformer
+    # Constructs a new Transformer instance.
+    #
+    # @param transformations [Array<ASTTransform::AbstractTransformation>] The transformations to be run.
+    # @param builder [Parser::Builders::Default] The AST Node builder.
+    def initialize(*transformations, builder: Parser::Builders::Default.new)
+      @transformations = transformations
+      @builder = builder
+    end
+
+    # Builds the AST for the given +source+.
+    #
+    # @param source [String] The input source code.
+    # @param file_path [String] The file_path. This is important for source mapping in backtraces.
+    #
+    # @return [Parser::AST::Node] The AST.
+    def build_ast(source, file_path: 'tmp')
+      buffer = create_buffer(source, file_path)
+      parser.parse(buffer)
+    end
+
+    # Builds the AST for the given +file_path+.
+    #
+    # @param file_path [String] The input file path.
+    #
+    # @return [Parser::AST::Node] The AST.
+    def build_ast_from_file(file_path)
+      source = File.read(file_path)
+      build_ast(source, file_path: file_path)
+    end
+
+    # Transforms the given +source+.
+    #
+    # @param source [String] The input source code to be transformed.
+    #
+    # @return [String] The transformed code.
+    def transform(source)
+      ast = build_ast(source)
+      transformed_ast = transform_ast(ast)
+      Unparser.unparse(transformed_ast)
+    end
+
+    # Transforms the give +file_path+.
+    #
+    # @param file_path [String] The input file to be transformed. This is required for source mapping in backtraces.
+    # @param transformed_file_path [String] The file path to the transformed file.
+    #
+    # @return [String] The transformed code.
+    def transform_file(file_path, transformed_file_path)
+      source = File.read(file_path)
+      transform_file_source(source, file_path, transformed_file_path)
+    end
+
+    # Transforms the given +source+ in +file_path+.
+    #
+    # @param source [String] The input source code to be transformed.
+    # @param file_path [String] The file path for the input +source+. This is required for source mapping in backtraces.
+    # @param transformed_file_path [String] The file path to the transformed filed. This is required to register the
+    # SourceMap.
+    #
+    # @return [String] The transformed code.
+    def transform_file_source(source, file_path, transformed_file_path)
+      source_ast = build_ast(source, file_path: file_path)
+      # At this point, the transformed_ast contains line number mappings for the original +source+.
+      transformed_ast = transform_ast(source_ast)
+
+      transformed_source = Unparser.unparse(transformed_ast)
+
+      register_source_map(file_path, transformed_file_path, transformed_ast, transformed_source)
+
+      transformed_source
+    end
+
+    # Transforms the given +ast+.
+    #
+    # @param ast [Parser::AST::Node] The input AST to be transformed.
+    #
+    # @return [Parser::AST::Node] The transformed AST.
+    def transform_ast(ast)
+      @transformations.inject(ast) do |ast, transformation|
+        transformation.run(ast)
+      end
+    end
+
+    private
+
+    def create_buffer(source, file_path)
+      buffer = Parser::Source::Buffer.new(file_path)
+      buffer.source = source.dup.force_encoding(parser.default_encoding)
+
+      buffer
+    end
+
+    def parser
+      @parser&.reset
+      @parser ||= Parser::CurrentRuby.new(@builder)
+    end
+
+    def register_source_map(source_file_path, transformed_file_path, transformed_ast, transformed_source)
+      # The transformed_source is re-parsed to get the correct line numbers for the transformed_ast, which is the code
+      # that will run.
+      rewritten_ast = build_ast(transformed_source)
+      source_map = ASTTransform::SourceMap.new(source_file_path, transformed_file_path, transformed_ast, rewritten_ast)
+      ASTTransform::SourceMap.register_source_map(source_map)
+    end
+  end
+end

data/lib/ast_transform/version.rb

@@ -0,0 +1,3 @@
+module ASTTransform
+  VERSION = "1.0.0"
+end

data/lib/ast_transform.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ast_transform/version"
+require 'ast_transform/instruction_sequence'
+require 'ast_transform/instruction_sequence/mixin'
+require 'ast_transform/instruction_sequence/bootsnap_mixin'
+
+module ASTTransform
+  DEFAULT_OUTPUT_PATH = Pathname.new("").join("tmp", "ast_transform").to_s
+
+  class << self
+    def acronyms
+      @acronyms ||= []
+    end
+
+    def acronym(acronym)
+      acronyms << acronym
+      acronyms.uniq!
+    end
+
+    def install
+      @installed ||= begin
+        if defined?(Bootsnap) && ASTTransform::InstructionSequence.using_bootsnap_compilation?
+          class << Bootsnap::CompileCache::ISeq
+            prepend ::ASTTransform::InstructionSequence::BootsnapMixin
+          end
+        else
+          class << RubyVM::InstructionSequence
+            prepend ::ASTTransform::InstructionSequence::Mixin
+          end
+        end
+      end
+    end
+
+    def output_path=(path)
+      @output_path = path
+    end
+
+    def output_path
+      @output_path || DEFAULT_OUTPUT_PATH
+    end
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: ast_transform
+version: !ruby/object:Gem::Version
+  version: 1.0.0.pre.alpha.pre.15
+platform: ruby
+authors:
+- Jean-Philippe Duchesne
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-07-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !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.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.14'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.2
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: unparser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: An AST transformation framework.
+email:
+- jpduchesne89@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- ast_transform.gemspec
+- bin/console
+- bin/setup
+- lib/ast_transform.rb
+- lib/ast_transform/abstract_transformation.rb
+- lib/ast_transform/instruction_sequence.rb
+- lib/ast_transform/instruction_sequence/bootsnap_mixin.rb
+- lib/ast_transform/instruction_sequence/mixin.rb
+- lib/ast_transform/instruction_sequence/mixin_utils.rb
+- lib/ast_transform/source_map.rb
+- lib/ast_transform/transformation.rb
+- lib/ast_transform/transformation_helper.rb
+- lib/ast_transform/transformer.rb
+- lib/ast_transform/version.rb
+homepage: https://github.com/rspockframework/ast-transform
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.7
+signing_key: 
+specification_version: 4
+summary: An AST transformation framework.
+test_files: []