astel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 19a38e5beaa849b77b5d60ea2d46b1913e589a1892dd36fc6797e34e5dbd2738
+  data.tar.gz: 7de828db0d6c9e6ea66179f2f931308b9609ccade0047dc99e0b5f77e61ead5f
+SHA512:
+  metadata.gz: 8364cddfb8fe41deb8770e0f3ca105467820030d77c3563184aa9d087cbd8de2649d05db67058b18f04476ef410f945ef948dc12f2226bd55d607fa4ba683dfb
+  data.tar.gz: 4feb4b4cd00035245cf4b992612f0d51c67e2d7fa74decaea77b59912a481e9cc6129938ded3882b3aecd33a186535783ecf00f755e7347b08ca820d14bbd550

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes are documented here following Keep a Changelog, and the
+project follows Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-15
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,168 @@
+# Astel
+
+[![Ruby](https://github.com/ydah/astel/actions/workflows/main.yml/badge.svg)](https://github.com/ydah/astel/actions/workflows/main.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+Astel provides fast, reusable building blocks for Ruby source analysis and
+transformation on top of [Prism](https://github.com/ruby/prism). It parses each
+source once and provides APIs for AST traversal, declarative node matching, and
+non-destructive source rewriting.
+
+## Installation
+
+Install Astel with Bundler:
+
+```sh
+bundle add astel
+```
+
+Or install it directly with RubyGems:
+
+```sh
+gem install astel
+```
+
+Astel requires Ruby 3.3 or newer and Prism 0.30 or newer, but earlier than 2.0.
+
+## Usage
+
+Require Astel before using its APIs:
+
+```ruby
+require "astel"
+```
+
+### Parse source
+
+Parse a file from disk:
+
+```ruby
+source = Astel::SourceFile.parse(path: "example.rb")
+
+source.ast       # => Prism::ProgramNode
+source.comments  # => Prism comments
+source.errors    # => Prism parse errors
+source.valid?    # => true when there are no parse errors
+```
+
+Use `Astel::SourceFile.from_string` when the source is already in memory:
+
+```ruby
+source = Astel::SourceFile.from_string("value = 1\n", path: "example.rb")
+```
+
+### Traverse the AST
+
+`Astel::Dispatcher` walks the tree once and invokes callbacks registered for
+specific Prism node types:
+
+```ruby
+source = Astel::SourceFile.from_string(<<~RUBY)
+  puts "hello"
+  "value".freeze
+RUBY
+
+dispatcher = Astel::Dispatcher.new
+dispatcher.on(:call_node) { |node| puts node.name }
+dispatcher.run(source.ast)
+```
+
+Multiple callbacks can be registered for the same node type.
+
+### Match nodes
+
+`Astel::NodePattern` compiles a declarative pattern that can be reused across
+nodes:
+
+```ruby
+source = Astel::SourceFile.from_string('"value".freeze')
+node = source.ast.statements.body.first
+
+pattern = Astel::NodePattern.compile(<<~PATTERN)
+  (call_node receiver: (string_node) name: :freeze)
+PATTERN
+
+pattern.match?(node) # => true
+```
+
+Prefix a subpattern with `$` to capture its matched value:
+
+```ruby
+pattern = Astel::NodePattern.compile(
+  "(call_node receiver: $(string_node) name: $:freeze)"
+)
+
+captures = pattern.match(node)
+captures.first # => Prism::StringNode
+captures.last  # => :freeze
+```
+
+Patterns support node types, named fields, `_` for any non-`nil` value, `nil`,
+symbol, string, integer, and boolean literals, `{ ... }` alternatives, and `$`
+captures.
+
+### Rewrite source
+
+`Astel::Rewriter` records edits without modifying the original `SourceFile`:
+
+```ruby
+source = Astel::SourceFile.from_string("old_name\n")
+node = source.ast.statements.body.first
+
+rewriter = Astel::Rewriter.new(source)
+rewriter.replace(node.location, "new_name")
+
+rewriter.rewrite # => "new_name\n"
+source.source    # => "old_name\n"
+```
+
+The rewriter supports `replace`, `remove`, `insert_before`, and `insert_after`.
+Overlapping edits raise `Astel::Rewriter::ConflictError`, and
+`Astel::Rewriter#edits` returns an immutable snapshot of registered edits.
+
+## Performance and concurrency
+
+Compile node patterns once and reuse them for every candidate node. Astel also
+keeps a bounded cache of compiler output for repeated pattern strings.
+
+For repository-wide tools, process independent files in worker processes at
+the application layer. Keep each `SourceFile` and its Prism AST inside the
+worker that parsed it; Astel intentionally does not own a process pool or move
+ASTs between workers.
+
+Benchmarks for dispatching, node patterns, and rewriting are available under
+`benchmark/`:
+
+```sh
+bundle exec ruby benchmark/dispatch_bench.rb
+bundle exec ruby benchmark/node_pattern_bench.rb
+bundle exec ruby benchmark/rewriter_bench.rb
+```
+
+## Development
+
+After checking out the repository, install dependencies and run the test suite:
+
+```sh
+bundle install
+bundle exec rake
+```
+
+Verify the packaged gem with:
+
+```sh
+bundle exec ruby script/package_smoke.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/ydah/astel). Please include tests for behavior
+changes and keep the existing test and performance gates passing.
+
+See [CHANGELOG.md](CHANGELOG.md) for notable changes.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/benchmark/dispatch_bench.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+require 'astel'
+
+path = ARGV.fetch(0, __FILE__)
+iterations = Integer(ENV.fetch('ITERATIONS', '1000'), 10)
+ast = Astel::SourceFile.parse(path: path).ast
+dispatcher = Astel::Dispatcher.new
+50.times do
+  dispatcher.on(:call_node) { |_node| }
+  dispatcher.on(:def_node) { |_node| }
+  dispatcher.on(:string_node) { |_node| }
+end
+
+visitor_class = Class.new(Prism::Visitor) do
+end
+visitors = Array.new(50) { visitor_class.new }
+
+astel_elapsed = Benchmark.realtime { iterations.times { dispatcher.run(ast) } }
+prism_elapsed = Benchmark.realtime do
+  iterations.times { visitors.each { |visitor| visitor.visit(ast) } }
+end
+ratio = prism_elapsed / astel_elapsed
+
+dispatcher.run(ast)
+GC.start
+allocated_before = GC.stat(:total_allocated_objects)
+iterations.times { dispatcher.run(ast) }
+allocations_per_run = (GC.stat(:total_allocated_objects) - allocated_before).fdiv(iterations)
+
+callback = ->(_node) {}
+single_ast = Astel::SourceFile.from_string(Array.new(100, 'value.freeze').join("\n")).ast
+single_dispatcher = Astel::Dispatcher.new.on(:call_node, callback)
+list_dispatcher = Astel::Dispatcher.new.on(:call_node, callback)
+list_dispatcher.instance_variable_get(:@callbacks)[:call_node] = Astel::Dispatcher::CallbackList.new([callback])
+single_elapsed = Benchmark.realtime { iterations.times { single_dispatcher.run(single_ast) } }
+list_elapsed = Benchmark.realtime { iterations.times { list_dispatcher.run(single_ast) } }
+single_speedup = list_elapsed / single_elapsed
+
+puts format('Astel dispatcher: %.4fs', astel_elapsed)
+puts format('50 Prism visitors: %.4fs', prism_elapsed)
+puts format('speedup: %.2fx', ratio)
+puts format('allocations: %.2f/run', allocations_per_run)
+puts format('single callback speedup: %.2fx', single_speedup)
+
+if ENV['VERIFY'] == '1'
+  abort(format('Dispatcher regression: only %.2fx faster', ratio)) if ratio < 2.0
+  abort(format('Dispatcher regression: %.2f allocations/run', allocations_per_run)) if allocations_per_run > 10.0
+  abort(format('Dispatcher single callback regression: only %.2fx faster', single_speedup)) if single_speedup < 1.05
+end

data/benchmark/node_pattern_bench.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+require 'astel'
+require 'prism'
+
+iterations = Integer(ENV.fetch('ITERATIONS', '1000000'), 10)
+compile_iterations = Integer(ENV.fetch('COMPILE_ITERATIONS', '10000'), 10)
+verify = ENV['VERIFY'] == '1'
+node = Prism.parse('"value".freeze').value.statements.body.first
+miss = Prism.parse('"value".upcase').value.statements.body.first
+pattern = Astel::NodePattern.compile('(call_node receiver: (string_node) name: :freeze)')
+capture_source = '(call_node receiver: $(string_node) name: :freeze)'
+capture_pattern = Astel::NodePattern.compile(capture_source)
+
+pattern_elapsed = Benchmark.realtime { iterations.times { pattern.match?(node) } }
+manual_elapsed = Benchmark.realtime do
+  iterations.times do
+    node.is_a?(Prism::CallNode) && node.receiver.is_a?(Prism::StringNode) && node.name == :freeze
+  end
+end
+
+ratio = pattern_elapsed / manual_elapsed
+
+capture_elapsed = Benchmark.realtime { iterations.times { capture_pattern.match(node) } }
+manual_capture_elapsed = Benchmark.realtime do
+  iterations.times do
+    [node.receiver] if node.is_a?(Prism::CallNode) &&
+                       node.receiver.is_a?(Prism::StringNode) &&
+                       node.name == :freeze
+  end
+end
+capture_ratio = capture_elapsed / manual_capture_elapsed
+
+capture_miss_elapsed = Benchmark.realtime { iterations.times { capture_pattern.match(miss) } }
+manual_capture_miss_elapsed = Benchmark.realtime do
+  iterations.times do
+    [miss.receiver] if miss.is_a?(Prism::CallNode) &&
+                       miss.receiver.is_a?(Prism::StringNode) &&
+                       miss.name == :freeze
+  end
+end
+capture_miss_ratio = capture_miss_elapsed / manual_capture_miss_elapsed
+
+allocation_iterations = [iterations, 100_000].min
+capture_pattern.match(miss)
+GC.start
+allocated_before = GC.stat(:total_allocated_objects)
+allocation_iterations.times { capture_pattern.match(miss) }
+allocations_per_miss = (GC.stat(:total_allocated_objects) - allocated_before).fdiv(allocation_iterations)
+
+compile_elapsed = Benchmark.realtime do
+  compile_iterations.times { Astel::NodePattern.compile(capture_source) }
+end
+compile_microseconds = compile_elapsed * 1_000_000 / compile_iterations
+
+puts format('NodePattern: %.4fs', pattern_elapsed)
+puts format('Hand-written: %.4fs', manual_elapsed)
+puts format('ratio: %.2fx', ratio)
+puts format('NodePattern with capture: %.4fs', capture_elapsed)
+puts format('Hand-written with capture: %.4fs', manual_capture_elapsed)
+puts format('capture ratio: %.2fx', capture_ratio)
+puts format('NodePattern capture miss: %.4fs', capture_miss_elapsed)
+puts format('Hand-written capture miss: %.4fs', manual_capture_miss_elapsed)
+puts format('capture miss ratio: %.2fx', capture_miss_ratio)
+puts format('capture miss allocations: %.2f/call', allocations_per_miss)
+puts format('cached compile: %.2fus/call', compile_microseconds)
+
+if verify
+  abort(format('NodePattern regression: %.2fx slower than hand-written matching', ratio)) if ratio > 2.5
+  if capture_ratio > 2.5
+    abort(format('NodePattern capture regression: %.2fx slower than hand-written matching', capture_ratio))
+  end
+  if capture_miss_ratio > 2.5
+    abort(format('NodePattern capture miss regression: %.2fx slower than hand-written matching', capture_miss_ratio))
+  end
+  if allocations_per_miss > 0.1
+    abort(format('NodePattern capture miss regression: %.2f allocations/call', allocations_per_miss))
+  end
+  if compile_microseconds > 30.0
+    abort(format('NodePattern compiler cache regression: %.2fus/call', compile_microseconds))
+  end
+end

data/benchmark/rewriter_bench.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+require 'astel'
+
+def median_elapsed(samples, &operation)
+  Array.new(samples) do
+    GC.start
+    Benchmark.realtime(&operation)
+  end.sort.fetch(samples / 2)
+end
+
+iterations = Integer(ENV.fetch('ITERATIONS', '20'), 10)
+source = Astel::SourceFile.from_string('a' * 1_000_000)
+rewriter = Astel::Rewriter.new(source)
+
+100.times do |index|
+  start_offset = index * 10_000
+  rewriter.replace(start_offset...(start_offset + 5), 'replacement')
+end
+
+ordered_edits = rewriter.edits.sort_by do |edit|
+  [edit.start_offset, edit.end_offset, edit.sequence]
+end
+reference_rewrite = lambda do
+  ordered_edits.reverse_each.with_object(source.source.dup) do |edit, result|
+    prefix = result.byteslice(0, edit.start_offset)
+    suffix = result.byteslice(edit.end_offset, result.bytesize - edit.end_offset)
+    result.replace(prefix + edit.replacement + suffix)
+  end
+end
+
+expected = reference_rewrite.call
+raise 'rewriter output mismatch' unless rewriter.rewrite == expected
+
+astel_elapsed = Benchmark.realtime { iterations.times { rewriter.rewrite } }
+reference_elapsed = Benchmark.realtime { iterations.times { reference_rewrite.call } }
+ratio = reference_elapsed / astel_elapsed
+
+puts format('Astel rewriter: %.4fs', astel_elapsed)
+puts format('Repeated rebuilding: %.4fs', reference_elapsed)
+puts format('speedup: %.2fx', ratio)
+
+abort(format('Rewriter regression: only %.2fx faster', ratio)) if ENV['VERIFY'] == '1' && ratio < 5.0
+
+edit_count = Integer(ENV.fetch('EDIT_COUNT', '5000'), 10)
+registration_source = Astel::SourceFile.from_string('a' * (edit_count * 3))
+ranges = edit_count.times.map { |index| (index * 3)...(index * 3 + 1) }.reverse
+
+optimized_registration = Benchmark.realtime do
+  registration_rewriter = Astel::Rewriter.new(registration_source)
+  ranges.each { |range| registration_rewriter.replace(range, 'b') }
+end
+
+linear_registration = Benchmark.realtime do
+  registered_ranges = []
+  ranges.each do |range|
+    raise 'unexpected overlapping benchmark ranges' if registered_ranges.find { |existing| range.overlap?(existing) }
+
+    registered_ranges << range
+  end
+end
+registration_speedup = linear_registration / optimized_registration
+
+puts format('Indexed registration: %.4fs', optimized_registration)
+puts format('Linear conflict scan: %.4fs', linear_registration)
+puts format('registration speedup: %.2fx', registration_speedup)
+
+if ENV['VERIFY'] == '1' && registration_speedup < 5.0
+  abort(format('Rewriter registration regression: only %.2fx faster', registration_speedup))
+end
+
+large_edit_count = Integer(ENV.fetch('LARGE_EDIT_COUNT', '100000'), 10)
+large_registration_samples = Integer(ENV.fetch('LARGE_REGISTRATION_SAMPLES', '3'), 10)
+large_source = Astel::SourceFile.from_string('a' * (large_edit_count * 2))
+large_ranges = large_edit_count.times.map { |index| (index * 2)...(index * 2 + 1) }.reverse
+
+chunked_operation = lambda do |selected_ranges|
+  large_rewriter = Astel::Rewriter.new(large_source)
+  selected_ranges.each { |range| large_rewriter.replace(range, 'b') }
+end
+
+flat_operation = lambda do |selected_ranges|
+  registered_ranges = []
+  selected_ranges.each do |range|
+    index = registered_ranges.bsearch_index { |existing| existing.begin > range.begin } || registered_ranges.length
+    registered_ranges.insert(index, range)
+  end
+end
+
+warmup_ranges = large_ranges.first([large_edit_count, 1000].min)
+chunked_operation.call(warmup_ranges)
+flat_operation.call(warmup_ranges)
+
+chunked_registration = median_elapsed(large_registration_samples) { chunked_operation.call(large_ranges) }
+flat_registration = median_elapsed(large_registration_samples) { flat_operation.call(large_ranges) }
+large_registration_speedup = flat_registration / chunked_registration
+
+puts format('Chunked registration (%d edits): %.4fs', large_edit_count, chunked_registration)
+puts format('Flat sorted registration: %.4fs', flat_registration)
+puts format('large registration speedup: %.2fx', large_registration_speedup)
+
+if ENV['VERIFY'] == '1' && large_registration_speedup < 1.25
+  abort(format('Large rewriter registration regression: only %.2fx faster', large_registration_speedup))
+end

data/lib/astel/dispatcher.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'prism'
+require 'set'
+
+module Astel
+  class Dispatcher
+    class CallbackList < Array; end
+
+    NODE_CLASSES = Prism.constants.filter_map do |constant|
+      value = Prism.const_get(constant)
+      next unless value.is_a?(Class) && value < Prism::Node
+
+      [NodeType.from_class_name(constant.to_s), value]
+    rescue NameError
+      nil
+    end.to_h.freeze
+    NODE_TYPES = NODE_CLASSES.keys.to_set.freeze
+
+    # Each generated visit method pushes children in reverse order so the
+    # iterative traversal preserves Prism's pre-order without recursive calls.
+    class Traversal
+      def initialize(callbacks)
+        @callbacks = callbacks
+        @stack = []
+      end
+
+      def run(ast)
+        @stack << ast
+        @stack.pop.accept(self) until @stack.empty?
+      end
+    end
+
+    def self.install_traversal_method(type, node_class)
+      lines = [
+        "def visit_#{type}(node)",
+        "  callbacks = @callbacks[:#{type}]",
+        '  if Astel::Dispatcher::CallbackList === callbacks',
+        '    callbacks.each { |callback| callback.call(node) }',
+        '  elsif callbacks',
+        '    callbacks.call(node)',
+        '  end'
+      ]
+
+      if defined?(Prism::Reflection)
+        append_reflected_children(lines, node_class)
+      else
+        lines << '  node.child_nodes.reverse_each { |child| @stack << child if child }'
+      end
+
+      lines << 'end'
+      Traversal.class_eval(lines.join("\n"), __FILE__, __LINE__)
+    end
+    private_class_method :install_traversal_method
+
+    def self.append_reflected_children(lines, node_class)
+      Prism::Reflection.fields_for(node_class).reverse_each do |field|
+        name = field.name
+        case field
+        when Prism::Reflection::NodeField
+          lines << "  @stack << node.#{name}"
+        when Prism::Reflection::OptionalNodeField
+          lines << "  if (child = node.#{name})"
+          lines << '    @stack << child'
+          lines << '  end'
+        when Prism::Reflection::NodeListField
+          lines << "  node.#{name}.reverse_each { |child| @stack << child }"
+        end
+      end
+    end
+    private_class_method :append_reflected_children
+
+    NODE_CLASSES.each { |type, node_class| install_traversal_method(type, node_class) }
+
+    def initialize
+      @callbacks = {}
+    end
+
+    def on(node_type, callable = nil, &block)
+      callback = callable || block
+      raise ArgumentError, 'callback is required' unless callback
+
+      type = node_type.to_sym
+      raise ArgumentError, "unknown Prism node type: #{node_type}" unless NODE_TYPES.include?(type)
+      raise ArgumentError, 'callback must respond to call' unless callback.respond_to?(:call)
+
+      registered = @callbacks[type]
+      if registered.is_a?(CallbackList)
+        registered << callback
+      elsif registered
+        @callbacks[type] = CallbackList.new([registered, callback])
+      else
+        @callbacks[type] = callback
+      end
+      self
+    end
+
+    def run(ast)
+      return self unless ast
+
+      Traversal.new(@callbacks).run(ast)
+      self
+    end
+  end
+end

data/lib/astel/location.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Astel
+  Location = Data.define(:start_offset, :end_offset, :start_line, :start_column, :end_line, :end_column) do
+    def self.from(location)
+      return location if location.is_a?(self)
+
+      new(
+        start_offset: location.start_offset,
+        end_offset: location.end_offset,
+        start_line: location.start_line,
+        start_column: location.start_column,
+        end_line: location.end_line,
+        end_column: location.end_column
+      )
+    end
+
+    def self.point(offset:, line:, column:)
+      new(
+        start_offset: offset,
+        end_offset: offset,
+        start_line: line,
+        start_column: column,
+        end_line: line,
+        end_column: column
+      )
+    end
+
+    def length
+      end_offset - start_offset
+    end
+
+    def range
+      start_offset...end_offset
+    end
+  end
+end

data/lib/astel/node_ext.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Astel
+  module NodeExt
+    refine Prism::Node do
+      def source_text
+        location.slice
+      end
+    end
+  end
+end